8. UA rendering based on color schemes

A user agent may provide a user preferred color scheme which is the result of the user selecting that scheme within the user agent itself, or based on the color scheme selected in the UAs environment like an operating system. This preferred scheme is used to evaluate the prefers-color-scheme media feature. This specification introduces a supported-color-schemes property to affect UA specific rendering on a per element basis.

The prefers-color-scheme media query is not affected by the used color scheme as that would have introduced a circular dependency. Similarly, the used scheme does not result in a different UA stylesheet, but the other computed or used values may.

How the UA decides upon the preferred color scheme is out of scope for this specification.

8.1. Switching color schemes: the supported-color-schemes property

If the specified value only contains unsupported color schemes, the computed value is light. Otherwise, the computed value is the specified value with unsupported and duplicate color schemes removed.

Note: The rationale behind specifying computed and used style (below) like this is to have to store as little as possible (bitset of supported schemes) while not having to recreate computed styles on preferred color scheme changes.

<color-scheme>

<color-scheme> = light | dark | <custom-ident>

light

The element supports rendering with a light theme.

dark

The element supports rendering with a dark theme.

<custom-ident>

Other color scheme names are allowed to be forward compatible with color schemes added later without dropping the declaration in UAs not supporting those themes.

only

Ask the UA to use one of the listed color schemes when the UA preferred color scheme is not listed in the supported color schemes. This can typically be used force a dark theme rendering when the preferred color scheme is light.

Force dark theming:

:root {
       supported-color-schemes: dark only;
     }
     

8.2. Resolving the used color scheme

The UA provides a preferred color scheme which is used to evaluate the prefers-color-scheme media feature. For the following, a preferred color scheme of no-preference maps to light. The supported-color-schemes and the preferred color scheme resolves to a used color scheme per element as follows:

1. If the computed value of supported-color-schemes contains the preferred color scheme, make that the used color scheme.
2. If the computed value of supported-color-schemes contains the only keyword, make the first UA supported of the supported-color-schemes, per grammar order, the used color scheme.

   Does it make sense to allow multiple color schemes before only?

3. Otherwise the used color scheme is light.

8.3. Rendering effects

The UA should take the used color scheme into account when rendering the default page background, form controls, the default selection color, and other UA-controlled UI like misspelling underlines.

When the canvas background is not opaque, a UA dependent background is seen behind the canvas. This background should be dark instead of light when the used color scheme for the root element of the top level document is dark.

Should the spec say white/black instead of light/dark? Probably not since this is defined as UA dependent?

Note: The background color of the canvas is typically transparent. Changing the UA background behind the canvas allows for iframes to still be transparent by default when both the parent document and the iframe uses a dark theme.

The UA stylesheet should include a named color, not exposed to authors, specified on :root. This named color computes to the same computed value as the initial value of color when the resolved theme for the element is light, and rgb(255, 255, 255) for dark.

Making the computed value of a color relying on the used color theme could be an issue.