Web Color Schemes

Browsers have implemented a number of different tools to help support Light and Dark modes, but it can be difficult to reason about how all these tools interact with one another, especially when including iframed content on a page. The purpose of this site is to demonstrate and clarify how these tools interact with one another.

Color Mode Toolkit

• prefers-color-scheme Media Query [MDN]

  This media query responds to the page's requested scheme, which can have a value of either light or dark.

• CSS color-scheme [MDN]

  This property is used to indicate to the browser what color theme is used by an element and its descendants. This selects the styles applied to browser-provided UI elements, such as form elements, scroll bars, etc. It also overrides the requested scheme for embedded pages, for example in <iframe> elements.
  

  If a user has explicitly selected a color scheme using options provided by the site, then this property should be set to the corresponding value of either light or dark. If this element is styled implicitly according to prefers-color-scheme, this property should be set to light dark to imply that the element is using the current page's requested scheme so the browser-provided UI elements can match, and it can be determined if embedded pages are "compatible".

  When this property is unset or normal, it will assume its value according to the page's <meta name="color-scheme">.

• <meta name="color-scheme"> [MDN]

  This meta property indicates to the browser whether or not the page supports the requested scheme. It's used for checking compatibility of embedded pages with the host page.

Requested Scheme

Determining the requested scheme for a page is necessary to use these tools effectively. For a top-level page, the requested scheme is determined simply by the user's color scheme preference for the browser. For embedded pages, the requested scheme depends on the CSS color-scheme of its containing element or the <meta name="color-scheme"> of its containing page, combined with the user's color scheme preference.

Compatibility

When an embedded page is compatible with its host element, the browser will allow it to have a transparent background. Otherwise, the browser automatically applies a background color to the embedded page appropriate for its expected color scheme. Only when the host element and the embedded page have the same expected color scheme, then they are considered compatible.

Host Element

The expected color scheme of the host element depends first upon its CSS color-scheme property. When set to light or dark, then a Light or Dark color scheme is expected, respectively. When set to light dark, the expected color scheme is derived from the requested scheme. When unset or normal, then the expected color scheme is derived from the host page's <meta name="color-scheme">. Failing that, a Light color scheme is assumed. The logic is very similar to that of requested scheme for an embedded page, but pay special attention to the last row in the following table:

Embedded Page

The expected color scheme for an embedded page is determined primarily by its <meta name="color-scheme">. When unset, normal, or light, the expected color scheme is Light. When set to dark, the expected color scheme is Dark. When set to light dark, the expected color scheme depends on the requested scheme.

Demo

The effects of these settings can be visualized with the tools below. The "Page Settings" block shows the value of the <meta name="color-scheme"> and CSS color-scheme properties for the component that follows it. In this component is an "unstyled" button, which will assume styles provided by the browser, and a button styled according to the prefers-color-scheme media query. This page doesn't set values for either of these properties.

Below here are two <iframe>, one nested inside the other, along with controls to configure them and see how these properties interact. Both <iframe> elements have subtle checkerboard backgrounds which are visible when the embedded page is compatible with its host.