CSS Color Adjustment Module Level 1

1. Introduction

1.1. Value Definitions

This specification follows the CSS property definition conventions from [CSS2] using the value definition syntax from [CSS-VALUES-3]. Value types not defined in this specification are defined in CSS Values & Units [CSS-VALUES-3]. Combination with other CSS modules may expand the definitions of these value types.

In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the CSS-wide keywords keywords as their property value. For readability they have not been repeated explicitly.

2. Preferred Color Schemes

Operating systems and user agents often give users the ability to choose their preferred color schemes for user interface elements. These are typically reflected in the user agent’s rendering of its navigation interface as well as in-page interface elements such as form controls and scrollbars, and are expected to also be reflected in the values of the CSS system colors.

A UA can also allow the user to indicate a preference for the color scheme of the pages they view, requesting that the author adapt the page to those color preferences. (It is not required to express a preference; users can have preferences for operating system interface colors that they do not want imposed on pages.)

The most common preferences are a choice of “Light” vs “Dark” (or “Day Mode” vs “Night Mode”) color schemes, rendering things as mostly light- or dark-colored backgrounds, and with dark- or light-colored foregrounds (text, icons). This module, together with Media Queries Level 5, defines controls to enable color scheme negotiation for “Light” and “Dark” color schemes (and no preference).

Note: The “Light” and “Dark” color schemes don’t represent an exact color palette (such as black-and-white), but a range of possible palettes. To guarantee specific colors, authors must specify those colors themselves. Note also that, consequently, pairing default or <system-color> colors with author-specified colors cannot guarantee any particular contrast level; it might be necessary to set both foreground and background colors together to ensure legibility [WCAG21].

To enable pages to adapt to the user’s preferred color scheme, user agents will match the prefers-color-scheme media query to the user’s preferred color schemes. See [MEDIAQUERIES-5].

Additionally, if the author has indicated that the page can support this color scheme (see color-scheme), the user agent must match the following to the user’s preferred color scheme:

• the color of the canvas surface find what we name this in other specs, the initial value of the color property, and the system colors

• the default colors of scrollbars and other interaction UI

• the default colors of form controls and other "specially-rendered" elements

• the default colors of other browser-provided UI, such as "spellcheck" underlines

User agents may support additional color schemes, however CSS does not support negotiation of additional color schemes: user agents should pursue standardization of these schemes, so that prefers-color-scheme and color-scheme can reflect the additional values.

Note: Aside from the small list of adjustments given above, user agents generally do not further adjust a page to match the user’s preferred color scheme, because the chance of accidentally ruining a page is too high. However, when particular color choices are required by the user (for accessibility reasons, for example), more invasive changes might be applied; see § 3 Forced Color Schemes: the forced-color-adjust property.

2.1. Opting Into a Preferred Color Scheme: the color-scheme property

The color-scheme property allows an element to indicate which color schemes it is comfortable being rendered with. These values are negotiated with the users preferences, resulting in a chosen color scheme that affects UI things such as the default colors of form controls and scrollbars as well as the used values of the CSS system colors. Values are defined as follows:

normal

Indicates that the element isn’t aware of color schemes at all, and so the element should be rendered with the browser’s default color scheme.

[ light | dark | <custom-ident> ]+

Indicates that the element is aware of and can handle the listed color schemes, and expresses an ordered preference between them. (See § 2.2 Finding the Used Color Scheme for details on how this choice is resolved.)

Note: Providing both keywords indicates that the first scheme is preferred, but the second is also acceptable if the user prefers it instead.

light represents a “Light” color scheme, with light background colors and dark foreground colors. dark represents the opposite, with dark background colors and light foreground colors.

<custom-ident> values are meaningless, and exist only for future compatibility, so that future added color schemes do not invalidate the color-scheme declaration in legacy user agents. User agents must not interpret any <custom-ident> values as having a meaning; any additional recognized color schemes must be explicitly added to this property’s grammar. To avoid confusion, authoring tutorials and references should omit <custom-ident> from their materials.

only, normal, light, and dark are not valid <custom-ident>s in this property.

Repeating a keyword, such as color-scheme: light light, is valid but has no additional effect beyond what the first instance of the keyword provides.

only

If provided, only indicates that the element must be rendered with one of the specified color schemes, if possible, even if the user’s preference is for a different color scheme.

Per spec, only can only be used with light. Apple’s implementation allows it with dark as well. The concern with only dark is that pages won’t consider UAs that can’t support dark schemes, and will thus render brokenly. This value might be expanded to all schemes or removed entirely depending on further consideration.

Authors should not use this value, and should instead ensure that their page renders well with whatever color scheme the user prefers (using the prefers-color-scheme media query to adjust styles accordingly). This keyword is provided only for the rare cases where that might not be reasonably possible, and using a different color scheme would render the element difficult or impossible to use.

Note: User agents are not required to support any particular color scheme, so using only to indicate a required color scheme is still not guaranteed to have any effect on the rendering of the element.

Note: “Light” and “Dark” modes are not specific color palettes. For example, both a stark black-on-white scheme and a sepia dark-on-tan scheme would both be considered “Light” color schemes. To ensure particular foreground or background colors, they need to be specified explicitly.

2.2. Finding the Used Color Scheme

For each element, find the used color scheme for that element. If the used color scheme is no-preference, the element must be rendered with the user agent’s default color scheme. (For Web compatibility, this should be a “Light” color scheme.) Otherwise, the element must be rendered with the used color scheme.

Note: This algorithm ensures that if the user prefers a non-default color scheme, it will only be used if the page claims to support it. This ensures that legacy pages, written before color scheme preferences were exposed, do not change behavior.

2.3. Effects of the Used Color Scheme

For all elements, rendering with a color scheme should cause the colors used in all browser-provided UI for the element—e.g. scrollbars, spellcheck underlines, form controls, etc.—to match with the intent of the color scheme.

On the root element, rendering with a color scheme additionally must affect the surface color of the canvas, the initial value of the color property, and the used values of the system colors, and should also affect the viewport’s scrollbars.

In order to preserve expected color contrasts, in the case of embedded documents typically rendered over a transparent canvas (such as provided via an HTML iframe element), if the used color-scheme of the element and the used color-scheme of the embedded document’s root element do not match, then the UA must use an opaque canvas of the Canvas color appropriate to the embedded document’s color-scheme instead of a transparent canvas. This rule does not apply to documents embedded via elements intended for graphics (such as img elements embedding an SVG document).

2.4. The "color-scheme" meta value

To aid user agents in rendering the page background with the desired color scheme immediately (rather than waiting for all CSS in the page to load), a color-scheme value can also be provided in a meta element.

If any meta elements are inserted into a document or removed from a document, or existing meta elements have their name or content attributes changed, user agents must run the following algorithm:

This algorithm favors the first meta, to allow for ASAP rendering with a chosen color scheme. Is that the desired behavior?

3. Forced Color Schemes: the forced-color-adjust property

Forced colors mode is an accessibility feature intended to increase the readability of text through color contrast. Individuals with limited vision often find it more comfortable to read content when there is a a particular type of contrast between foreground and background colors.

Operating systems can provide built-in color themes, such as Windows’ high contrast black-on-white and high-contrast white-on-black themes. Users can also customize their own themes, for example to provide low contrast or hue contrast.

In forced colors mode, the user agent enforces the user’s preferred color palette on the page, overriding the author’s chosen colors for specific properties, see § 3.1 Properties Affected by Forced Colors Mode. It may also enforce a “backplate” underneath text (similar to the way backgrounds are painted on the ::selection pseudo-element) to ensure adequate contrast for readability.

To enable pages to adapt to forced colors mode user agents will match the forced-colors media query and must provide the required color palette through the CSS system colors (see [CSS-COLOR-4]). Additionally, if the UA determines, based on Lab lightness, that the Canvas color is clearly either dark (L < 33%) or light (L > 67%), then it must match the appropriate value of the prefers-color-scheme media query and express a corresponding user preference for color-scheme. This will allow pages that support light/dark color schemes to automatically adjust to more closely match the forced color scheme. Behavior between the above dark vs. light thresholds is UA-defined, and may result in assuming either light, dark, or no-preference as the user’s preferred color scheme.

3.1. Properties Affected by Forced Colors Mode

When forced colors mode is active and forced-color-adjust is auto (see below), colors must be force-adjusted to the user’s preferred color palette.

Any author origin or animation origin declaration of the following properties on any element (including any declarations representing a non-CSS presentational hint) is rewritten to specify revert:

• color
• fill
• stroke
• text-decoration-color
• text-emphasis-color
• border-color
• outline-color
• column-rule-color
• scrollbar-color
• -webkit-tap-highlight-color
• box-shadow
• text-shadow

  Additionally, on on user input controls (except button-like controls) only, background-image.

  Based on the resulting computed color value, the [computed|used] background-color of an element is forced by matching all channels other than alpha to the appropriate forced background color; which should be the corresponding system background color if color is a system color (see [CSS-COLOR-4]), and Canvas otherwise.

  UA may further tweak these forced colors mode heuristics to provide better user experience.

  Note: See [CSS-CASCADE-4] for information about cascade origins, non-CSS presentational hints, and the revert keyword.

  3.2. Opting Out of a Forced Color Scheme: the forced-color-adjust property

  Name:	forced-color-adjust
  Value:	auto | none
  Initial:	auto
  Applies to:	all elements
  Inherited:	yes
  Percentages:	n/a
  Computed value:	as specified
  Canonical order:	per grammar
  Animation type:	discrete

  The forced-color-adjust property allows authors to opt particular elements out of forced colors mode, restoring full control over the colors to CSS. Values have the following meanings:

  auto

  The element’s colors are automatically adjusted by the UA in forced colors mode.

  none

  The element’s colors are not automatically adjusted by the UA in forced colors mode.

  Authors should only use this value when they are themselves adjusting the colors to support the user’s color and contrast needs and need to make changes to the UA’s default adjustments to provide a more appropriate user experience for those elements.

  Should this property be merged with color-adjust somehow?

  In order to not break SVG content, UAs are expected to add the following rules to their UA style sheet:

  @namespace "http://www.w3.org/2000/svg";
  svg|svg { forced-color-adjust: none; }
  svg|foreignObject { forced-color-adjust: auto; }
  

  4. Performance-based Color Schemes: the color-adjust property

  On most monitors, the color choices that authors make have no significant difference in terms of how the device performs; displaying a document with a white background or a black background is approximately equally easy.

  However, some devices have limitations and other qualities that make this assumption untrue. For example, printers tend to print on white paper; a document with a white background thus has to spend no ink on drawing that background, while a document with a black background will have to expend a large amount of ink filling in the background color. This tends to look fairly bad, and sometimes has deleterious physical effects on the paper, not to mention the vastly increased printing cost from expending the extra ink. Even fairly small differences, such as coloring text black versus dark gray, can be quite different when printing, as it switches from using a single black ink to a mixture of cyan, magenta, and yellow ink, resulting in higher ink usage and lower resolution.

  As a result, in some circumstances user agents will alter the styles an author specifies in some particular context, adjusting them to be more appropriate for the output device and to accommodate what they assume the user would prefer. However, in some cases the document may be using colors in important, well-thought-out ways that the user would appreciate, and so the document would like some way to hint to the user agent that it might want to respect the page’s color choices. The color-adjust property controls this.

  Name:	color-adjust
  Value:	economy | exact
  Initial:	economy
  Applies to:	all elements
  Inherited:	yes
  Percentages:	N/A
  Computed value:	specified keyword
  Canonical order:	per grammar
  Animation type:	discrete

  The color-adjust property provides a hint to the user-agent about how it should treat color and style choices that might be expensive or generally unwise on a given device, such as using light text on a dark background in a printed document. If user agents allow users to control this aspect of the document’s display, the user preference must be respected more strongly than the hint provided by color-adjust. It has the following values:

  economy

  The user agent should make adjustments to the page’s styling as it deems necessary and prudent for the output device.

  For example, if the document is being printed, a user agent might ignore any backgrounds and adjust text color to be sufficiently dark, to minimize ink usage.

  exact

  This value indicates that the page is using color and styling on the specified element in a way which is important and significant, and which should not be tweaked or changed except at the user’s request.

  For example, a mapping website offering printed directions might "zebra-stripe" the steps in the directions, alternating between white and light gray backgrounds. Losing this zebra-striping and having a pure-white background would make the directions harder to read with a quick glance when distracted in a car.

  5. Privacy and Security Considerations

  Applying user color preferences via color schemes or forced colors mode expose the user’s color preferences to the page, which can increase fingerprinting surface.

  Additionally, it may be possible for an embedded document to use timing attacks to determine whether its own color-scheme matches that of its embedding iframe or not.

  6. Acknowledgements

  This specification would not be possible without the development efforts of various color adjustment features at Apple, Google, and Microsoft as well as discussions about print adjustments on www-style. In particular, the CSS Working Group would like to thank: Alison Maher, François Remy, イアンフェッティ

  List additional MSFT / Apple / Google people here.

  7. Changes

  Changes since the 23 May 2019 Working Draft:

  • Forced background colors don’t revert, they force all color channels other than alpha (to preserve author’s transparency). Issue 4175.
  • Other properties revert by rewriting author-level rules to specify revert, not by injecting revert !important rules into the cascade. Issue 4020.
  • Force opaque background if color-adjust mismatches between iframe and embedded document. Issue 4472.
  • Don’t force colors on SVG text.
  • Rename color-scheme: auto to color-scheme: normal. Issue 3849.
  • Miscellaneous clarifications.