CSS Color Adjustment Module Level 1

W3C Working Draft,

This version:
Latest published version:
Editor's Draft:
Previous Versions:
Issue Tracking:
Inline In Spec
GitHub Issues
Elika J. Etemad / fantasai (Invited Expert)
Tab Atkins Jr. (Google)
Suggest an Edit for this Spec:
GitHub Editor


This module introduces a model and controls over automatic color adjustment by the user agent to handle user preferences, such as "Dark Mode", contrast adjustment, or specific desired color schemes.

CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, etc.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

GitHub Issues are preferred for discussion of this specification. When filing an issue, please put the text “css-color-adjust” in the title, preferably like this: “[css-color-adjust] …summary of comment…”. All issues and comments are archived, and there is also a historical archive.

This document was produced by the CSS Working Group.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2019 W3C Process Document.

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:

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

Name: color-scheme
Value: normal | [ light | dark | <custom-ident> ]+ | only && light
Initial: normal
Applies to: all elements
Inherited: yes
Percentages: n/a
Computed value: the keyword normal, or optional only keyword and ordered list of specified color scheme keywords
Canonical order: per grammar
Animation type: discrete

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:


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.


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

To find the used color scheme for an element el:
  1. Let scheme be the keyword matching prefers-color-scheme.

  2. If the computed value of color-scheme on el contains scheme, return scheme.

  3. If the computed value of color-scheme on el contains the only keyword or scheme is no-preference, and at least one color scheme indicated in color-scheme is supported by the user agent, return the first keyword, in specified order, that is supported by the user agent.

  4. Otherwise, return no-preference.

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:

  1. Let candidate elements be the list of all meta elements that meet the following criteria, in tree order:

  2. For each element in candidate elements:

    1. If element’s content attribute’s value parses as a <color-scheme> value, treat that value as a declaration of the color-scheme property on element’s root, cascaded as a non-CSS presentational hint. Then return.

Note: Because these rules check successive elements until they find a match, an author can provide multiple such values to handle fallback for legacy user agents. Opposite how CSS fallback works for properties, the multiple meta elements must be arranged with the legacy values after the newer values.

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:


Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Conformance classes

Conformance to this specification is defined for three conformance classes:

style sheet
A CSS style sheet.
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Requirements for Responsible Implementation of CSS

The following sections define several conformance requirements for implementing CSS responsibly, in a way that promotes interoperability in the present and future.

Partial Implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported property values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

Implementations of CR-level Features

Once a specification reaches the Candidate Recommendation stage, implementers should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec, and should avoid exposing a prefixed variant of that feature.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at https://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.


Terms defined by this specification

Terms defined by reference


Normative References

Bert Bos; Elika Etemad; Brad Kemper. CSS Backgrounds and Borders Module Level 3. 17 October 2017. CR. URL: https://www.w3.org/TR/css-backgrounds-3/
Elika Etemad; Tab Atkins Jr.. CSS Cascading and Inheritance Level 4. 28 August 2018. CR. URL: https://www.w3.org/TR/css-cascade-4/
Tab Atkins Jr.; Chris Lilley. CSS Color Module Level 4. 5 November 2019. WD. URL: https://www.w3.org/TR/css-color-4/
Håkon Wium Lie; Florian Rivoal; Rachel Andrew. CSS Multi-column Layout Module Level 1. 15 October 2019. WD. URL: https://www.w3.org/TR/css-multicol-1/
Daniel Glazman; Elika Etemad; Alan Stearns. CSS Pseudo-Elements Module Level 4. 25 February 2019. WD. URL: https://www.w3.org/TR/css-pseudo-4/
Tantek Çelik; Rossen Atanassov. CSS Scrollbars Module Level 1. 25 September 2018. WD. URL: https://www.w3.org/TR/css-scrollbars-1/
Tab Atkins Jr.; Simon Sapin. CSS Syntax Module Level 3. 16 July 2019. CR. URL: https://www.w3.org/TR/css-syntax-3/
Elika Etemad; Koji Ishii. CSS Text Decoration Module Level 3. 13 August 2019. CR. URL: https://www.w3.org/TR/css-text-decor-3/
Tantek Çelik; Florian Rivoal. CSS Basic User Interface Module Level 3 (CSS3 UI). 21 June 2018. REC. URL: https://www.w3.org/TR/css-ui-3/
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 3. 6 June 2019. CR. URL: https://www.w3.org/TR/css-values-3/
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 4. 31 January 2019. WD. URL: https://www.w3.org/TR/css-values-4/
Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. REC. URL: https://www.w3.org/TR/CSS2/
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
Dean Jackson; Florian Rivoal; Tab Atkins Jr.. Media Queries Level 5. 18 March 2020. WD. URL: https://www.w3.org/TR/mediaqueries-5/
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
Amelia Bellamy-Royds; et al. Scalable Vector Graphics (SVG) 2. 4 October 2018. CR. URL: https://www.w3.org/TR/SVG2/

Informative References

Andrew Kirkpatrick; et al. Web Content Accessibility Guidelines (WCAG) 2.1. 5 June 2018. REC. URL: https://www.w3.org/TR/WCAG21/

Property Index

Name Value Initial Applies to Inh. %ages Anim­ation type Canonical order Com­puted value
color-adjust economy | exact economy all elements yes N/A discrete per grammar specified keyword
color-scheme normal | [ light | dark | <custom-ident> ]+ | only && light normal all elements yes n/a discrete per grammar the keyword normal, or optional only keyword and ordered list of specified color scheme keywords
forced-color-adjust auto | none auto all elements yes n/a discrete per grammar as specified

Issues Index

find what we name this in other specs
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.
This algorithm favors the first meta, to allow for ASAP rendering with a chosen color scheme. Is that the desired behavior?
Should this property be merged with color-adjust somehow?
List additional MSFT / Apple / Google people here.