Dark mode support for WordPress embeds

[meszarosrob]

WordPress embeds in version 6.8 and earlier do not support dark mode. They are always displayed with a white background with dark text, regardless of the user's system-wide light or dark mode settings.

This is because WordPress embeds do not include CSS rules for dark mode support. They were added before browsers widely supported the prefers-color-scheme media query.

On websites optimized for dark mode, the embedded WordPress posts stand out harshly and can create an unpleasant visual experience. Since embeds are rendered within iframes, embedding sites have little control over their styling.

Other platforms that support oEmbed, such as Bluesky, adjust their embed appearance based on the user's system preferences. Ideally, WordPress should adopt the same approach.

If this is an issue, it affects all websites that embed WordPress posts. Therefore, it might make sense for dark mode support to be implemented in WordPress core rather than relying on plugins. Otherwise, every WordPress instance would need to install a plugin to "play nice" with the rest of the websites.

Although dark mode is often seen as an aesthetic feature, it can also offer accessibility benefits and contribute to power savings:

• ​https://web.dev/articles/prefers-color-scheme
• ​https://www.nngroup.com/articles/dark-mode-users-issues/
• ​https://web.dev/case-studies/terra-dark-mode

[swissspidy]

Thanks for opening this ticket.

There's a related discussion about color contrast which was just started, which should probably be resolved first: #63460

Second, I'd like us to gather more information about this part:

Other platforms that support oEmbed, such as Bluesky, adjust their embed appearance based on the user's system preferences.

The screenshots only show an example of Bluesky, but it would be great to collect more examples from all the supported oEmbed providers so that we have more context to work on this.

[meszarosrob]

Taking the most straightforward approach and adding the CSS rules for dark mode to the existing wp-embed-template.css file would still keep it roughly around 12 KB unminified, adding about 36% to the original size.

Here are some simulation for different cases:

User is using light mode.	User is using dark mode, but the WordPress embeds don't support it.
User is using dark mode; the main website doesn't support it, but the embeds do.	User is using dark mode, and both the website and the embeds support it.

There are opportunities to improve wp-embed-template.css by using CSS custom properties for easier theming. More ambitious changes could include replacing inline SVGs in the CSS with actual SVG files, removing the legacy wp-embed-template-ie.css file, and ensuring the embed meets accessibility color contrast standards. However, these improvements may be better addressed in separate tickets, as they are not directly related to dark mode support.

The visual examples and the patch provided use colors from the WordPress Design System Figma library. This is a rough proposal, and final color choices should be made by the design team.

[meszarosrob]

Replying to swissspidy:

Thanks for opening this ticket.

There's a related discussion about color contrast which was just started, which should probably be resolved first: #63460

Thanks for the information.

Second, I'd like us to gather more information about this part:

Other platforms that support oEmbed, such as Bluesky, adjust their embed appearance based on the user's system preferences.

The screenshots only show an example of Bluesky, but it would be great to collect more examples from all the supported oEmbed providers so that we have more context to work on this.

I can try to collect some other examples.

[meszarosrob]

I'm not aware of any other providers listed at ​https://developer.wordpress.org/reference/hooks/oembed_providers/ that support dark mode. However, many of them, if not most, display embedded media that fills the entire area and includes little additional UI to theme.

Here are some additional examples I know that support dark mode without requiring an extra parameter:

Service	Example
Codepoints.net	​https://codepoints.net/api/v1/oembed?url=https://codepoints.net/U+00E4
Raindrop.io	​https://pub.raindrop.io/api/oembed?url=https://raindrop.io/exentrich/design-66
Smash Notes	​https://smashnotes.com/services/oembed?url=https://smashnotes.com/p/below-the-line-with-james-beshara/e/1-justin-kan/
Tonic Audio	​https://tonicaudio.com/oembed/?url=YsiaUAFouw
Web3 is Going Just Great	​https://www.web3isgoinggreat.com/api/oembed?url=https://www.web3isgoinggreat.com/?collection=binance&id=binance-legal-action
Datawrapper	​https://www.datawrapper.de/_/TX95t/

The previous attachment shows how these embeds appear in light mode and when switching to dark mode.

[sabernhardt]

custom dark mode styles added to embedded post with prefers-color-scheme, when Twenty Twenty-One's dark mode is activated and system preference is dark

[sabernhardt]

the same custom dark mode styles for embedded post when Twenty Twenty-One's dark mode is turned off but the system preference is dark

[sabernhardt]

Themes and sites might benefit from a standard dark mode if it is added with a new filter, add_theme_support(), or a separately enqueued (but inline) stylesheet. I do not think dark-mode colors belong in the same stylesheet as the rest of the embed styles because they would not fit well with all sites.

Using the prefers-color-scheme: dark media query could work if the theme sets a dark mode exactly the same way. However, themes can

• show dark text against a light background for everyone (no dark mode support)
• assign light text against a dark background for everyone, automatically
• add a theme.json style variation that includes light text and a dark background, such as Twenty Twenty-Five's Evening and Twilight styles
• add a Customizer option to choose a dark version of a classic theme (Twenty Eleven and Twenty Seventeen)
• allow site administrators to define their own light text and dark background colors in Customizer (including Twenty Twenty)
• add a button for visitors to activate and deactivate the theme's dark mode (Twenty Twenty-One)

Regarding the patch:

• Elements in the share dialog—including dashicons-no—are already light against a dark background, so this would not need to define new colors there.
• [50025] assigned colors from the ​admin color palette, and a dark mode could use the same palette.
• The box-shadow is unchanged (and would not need to be added again in the dark mode styles).

For the Twenty Twenty-One screenshots, I used:

• #a7aaad for Comments and Share SVG icons in the footer
• #dcdcde when hovering over the icons
• a few additional rulesets:

  	.wp-embed {
  		background: #101517;
  		border-color: #000;
  		color: #c3c4c7;
  	}
  	.wp-embed-heading a,
  	.wp-embed .wp-embed-more,
  	.wp-embed a {
  		color: #a7aaad;
  	}
  	.wp-embed-meta a:hover {
  		color: #dcdcde;
  	}
  	.wp-embed-site-icon[src*="/wp-includes/images/w-logo-blue.png"] {
  		background: #fff;
  		border-radius: 50%;
  	}
  

[meszarosrob]

Simulation of a dark mode embed using the WordPress admin color scheme

[meszarosrob]

Patch using the colors of the WordPress admin for the embeds dark mdoe

[meszarosrob]

Replying to sabernhardt:

Themes and sites might benefit from a standard dark mode if it is added with a new filter, add_theme_support(), or a separately enqueued (but inline) stylesheet. I do not think dark-mode colors belong in the same stylesheet as the rest of the embed styles because they would not fit well with all sites.

Using the prefers-color-scheme: dark media query could work if the theme sets a dark mode exactly the same way. However, themes can [...]

I agree that WordPress themes and sites would benefit from a standardized dark mode. However, I wouldn't strongly link that to the topic of dark mode for embeds.

The way I see it, while a WordPress site can embed its own posts, it's just one of many sites on the internet that might do so.

To me, the primary use case for embeds isn't for a site to embed its own content, but rather to make it easy for others to include it.

Based on my experience, very few WordPress sites actually customize the default appearance of their embeds. As a result, in most cases, there's already disconnect between a site's design and how the embeds look. And everybody seem to be okay with that.

In my opinion, whether this makes sense at all comes down to accepting the fact that today it's expected for UIs to be presented in either dark or light mode based on the user's (system) preference.

If we subscribe to this idea, then since we don't know in what contexts WordPress embeds will be displayed, we should assume they appear in contexts that honor the user's (system) preference, regardless of whether WordPress offers a standard dark mode for themes or sites.

However, I'm not sure if it's really the expectation of the world just yet. What I do know is that, a few years ago, there were considerably fewer sites and applications offering any choice compared to today. When it comes to my experience with mobile applications, I rarely see any that don't honor my preference.

In addition to offering dark mode based on prefers-color-scheme, or as an alternative, having a parameter like ?theme=dark|light could also solve some problems and address certain use cases.

Let me know what you think :-)

Regarding the patch:

• Elements in the share dialog—including dashicons-no—are already light against a dark background, so this would not need to define new colors there.
• [50025] assigned colors from the ​admin color palette, and a dark mode could use the same palette.
• [...]

I added another patch that chooses the colors from the palettes you mentioned.

My rationale for choosing the colors from ​https://www.figma.com/community/file/1436359662053949167 was that they might (I'm assuming) eventually become the standard colors used throughout the platform, not just in the Editor.

I personally really like this variation too. It was definitely worth trying to see how it looks. So, thanks for suggesting it.

I kept the dashicons-no icon and added a hover state to match the behavior of the comments and share icons.