the color-scheme
The CSS property and the corresponding meta tag allow developers to include their pages in the theme-specific defaults of the user agent stylesheet.
Updated
Background
the prefers-color-scheme
user preference media function
The user preference media feature gives developers full control over the appearance of their pages. If you are not familiar with it, please read my article
prefers-color-scheme
Hello Darkness, my old friend, where I documented everything I know about creating amazing dark mode experiences.
One piece of the puzzle that was only briefly mentioned in the article is the color-scheme
CSS property and the corresponding meta tag of the same name. Both make your life as a developer easier by allowing you to embed your page in the theme-specific defaults of the user agent stylesheet, such as form controls, scroll bars, and CSS system colors. At the same time, this feature prevents browsers from applying transformations themselves.
The user agent style sheet
Before continuing, let me briefly describe what a user agent stylesheet is. Most of the time, you can think of the word user agent (UA) as a fancy way of saying browser. The UA style sheet determines the default appearance of a page. As the name suggests, a UA stylesheet is something that depends on the UA in question. You can take a look at
Chrome
(and Chromium's UA stylesheet) and compare it to
From Firefox or
Safari (and WebKit's). Typically, UA stylesheets match on most things. For example, they all make the links blue, the general text black, and the background color white, but there are also important (and sometimes annoying) differences, for example, how they design the form controls.
Take a closer look
WebKit UA Style Sheet
and what it does regarding dark mode. (Do a full-text search for "dark" in the stylesheet.) The default value provided by the stylesheet changes depending on whether dark mode is on or off. To illustrate this, here is a CSS rule that uses the
: matches
pseudoclass and internal variables of WebKit like -apple-system-control-background
as well as the WebKit internal preprocessor directive #if defined
:
input,
input: matches ([type = "password"], [type = "search"]) {
-webkit-appearance : textfield ;
#if defined ( HAVE_OS_DARK_MODE_SUPPORT ) &&
HAVE_OS_DARK_MODE_SUPPORT
color : text ;
background-color : -apple-system-control-background ;
#else
background-color : white ;
#endif
}
You will notice some non-standard values for the color
and background-color
properties above. None text
neither -apple-system-control-background
they are valid CSS colors. They are internal to WebKit semantic colors.
It turns out that CSS has standardized the colors of the semantic system. They are specified in
CSS color module level 4. For example,
Canvas
(not to be confused with label) is for the background of app content or documents, while
CanvasText
It is for text in documents or application content. The two go together and should not be used in isolation.
UA style sheets can use their own proprietary colors, or those of the standardized semantic system, to determine how HTML elements should be rendered by default. If the operating system is set to dark mode or uses a dark theme,
CanvasText
(or text
) would be conditionally set to blank, and Canvas
(or -apple-system-control-background
) would be set to black. The UA stylesheet assigns the following CSS only once and covers both light and dark mode.
body {
color : CanvasText ;
background-color : Canvas
}
the color-scheme
CSS property
the CSS level 1 color adjustment module
The specification introduces a model and controls automatic color adjustment by the user agent in order to manage user preferences such as dark mode, contrast adjustment, or specific desired color schemes.
the color-scheme
The property defined in it allows an element to indicate which color schemes it is comfortable rendering with. These values are negotiated with the user's preferences, resulting in a chosen color scheme that affects aspects of the user interface (UI), such as the default colors of form controls and scroll bars, as well as the used values of the CSS system colors. The following values are currently supported:
-
normal
Indicates that the element does not know the color schemes at all, so the element should be rendered using the browser's default color scheme. -
[light | dark] +
Indicates that the element knows and can handle the listed color schemes, and expresses an ordered preference between them.
Providing both keywords indicates that the first scheme is preferred (by the author), but the second is also acceptable if the user prefers it.
In this list, Light
represents a light color scheme, with light background colors and dark foreground colors, while dark
represents the opposite, with dark background colors and light foreground colors.
Warning:
Previously, the specification allowed an additional value light only
which indicated that the element had to be rendered with a light color scheme if possible, even if the user's preference is for a different color scheme. Authors should not use this value and instead you should ensure that your page renders well with the color scheme that the user prefers.
For all elements, rendering with a color scheme must make the colors used throughout the user interface provided by the browser for the element to match the intent of the color scheme. Some examples are scroll bars, spell check underlines, form controls, and so on.
the color-scheme
The CSS property can be used both in : root
level as well as individual level per item.
About him : root
element, the representation with a color scheme should additionally affect the color of the canvas surface (that is, the global background color), the initial value of the color
property, and the used values of the system colors, and should also affect the scroll bars of the viewport.
: root {
color-scheme : dark light ;
}
Honoring the color-scheme
The CSS property requires the CSS to be downloaded first (if referenced by ) and to be analyzed. To help user agents render the background of the page with the desired color scheme. immediately, a
color-scheme
The value can also be provided in a
element.
< meta name = " color-scheme " content = " dark light " >
Combinatorial color-scheme
and prefers-color-scheme
Since both the meta tag and the CSS property (if applied to the : root
element) eventually result in the same behavior, I always recommend specifying the color scheme via the meta tag, so the browser can adopt the preferred scheme faster.
While for absolute baseline pages no additional CSS rules are needed, in the general case you should always combine color-scheme
with prefers-color-scheme
. For example, WebKit's proprietary CSS color -webkit-link
, used by WebKit and Chrome for the classic blue link rgb (0,0,238)
, has an insufficient contrast ratio of 2.23: 1 on a black background and
failure
both WCAG AA and WCAG AAA
requirements.
I have opened errors for Chrome,
WebKitand
Firefox
as well as a meta problem in HTML standard
to fix this.
Interaction with prefers-color-scheme
The interaction of color-scheme
CSS property and the corresponding meta tag with the prefers-color-scheme
The user preference media feature may seem confusing at first. In fact, they play very well together. The most important thing to understand is that color-scheme
exclusively determines the default appearance, while prefers-color-scheme
determines the stylizable appearance. To clarify this, assume the following page:
< head >
< meta name = " color-scheme " content = " dark light " >
< style >
fieldset {
background-color : gainsboro ;
}
@media ( prefers-color-scheme : dark ) {
fieldset {
background-color : darkslategray ;
}
}
style >
head >
< body >
< p >
Lorem ipsum pain sit amet, legere ancillae ne vis.
p >
< form >
< fieldset >
< legend > Lorem ipsum legend >
< button type = " button " > Lorem ipsum button >
fieldset >
form >
body >
The inline CSS code on the page sets the elements
background-color
to gainsboro
in the general case, and for darkslategray
if the user prefers a dark
color scheme according to prefers-color-scheme
user preference media function.
Through the element, the page tells the browser that it supports a dark and a light theme, with a preference for a dark theme.
Depending on whether the operating system is set to dark or light mode, the entire page appears light on dark, or vice versa, depending on the user agent style sheet. There is No Additional developer provided CSS to change paragraph text or page background color.
Notice how the elements
background-color
Changes are based on whether dark mode is enabled, following the rules of the online stylesheet provided by the developer on the page. Is good gainsboro
or darkslategray
.
the The appearance of the element is controlled by the user agent style sheet. Their
color
is configured in the
ButtonText
system color, and its background-color
and the four border-color
s are set to the system color
ButtonFace
.
Now notice how the elements
border-color
changes. the calculated value for him border-top-color
and the border-bottom-color
change of rgba (0, 0, 0, 0.847)
(blackish) to rgba (255, 255, 255, 0.847)
(off-white), as the user agent updates ButtonFace
dynamically based on color scheme. The same applies to the elements
color
which is set to the corresponding system color ButtonText
.
Manifestation
You can see the effects of color-scheme
applied to a large number of HTML elements in a Glitch demo. The demo deliberately shows WCAG AA and WCAG AAA
violation
with the colors of the links mentioned in the warning above.
Thanks
the color-scheme
The CSS property and corresponding meta tag were implemented by
Lillesveen rune. Rune is also a co-editor of the level 1 specification of the CSS color adjustment module. Hero image of
Philippe Leone
in Unsplash.