<pre class='metadata'>
Title: CSS Color Adjustment Module Level 1
Shortname: css-color-adjust
Level: 1
Status: CR
Prepare for TR: yes
Date: 2025-12-16
Deadline: 2026-02-16
Work Status: testing
Group: CSSWG
TR: https://www.w3.org/TR/css-color-adjust-1/
ED: https://drafts.csswg.org/css-color-adjust-1/
Previous Version: https://www.w3.org/TR/2022/CRD-css-color-adjust-1-20220614/
Implementation Report: https://wpt.fyi/results/css/css-color-adjust?label=experimental&label=master&aligned
Editor: Alison Maher, Microsoft, almaher@microsoft.com, w3cid 123530
Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Rossen Atanassov, Microsoft, ratan@microsoft.com, w3cid 49885
Editor: Rune Lillesveen, Google, futhark@google.com, w3cid 45291
Editor: Tab Atkins Jr., Google, http://www.xanthir.com/contact/, w3cid 42199
Abstract: 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.
Ignored Terms: -webkit-tap-highlight-color, name, the head element
WPT Path Prefix: css/css-color-adjust/
</pre>
<pre class='link-defaults'>
spec:css2; type:dfn; text:canvas
spec:css-backgrounds-3; type:property;
	text:border-color
	text:box-shadow
spec:css-color-4; type:property; text:color
spec:css-color-5; type:function; text:color()
spec:fill-stroke-3; type:property;
	text:fill
	text:stroke
spec:css-gaps-1; type:property; text:column-rule-color
spec: html;
	text:body; type:element
	text:meta; type:element
	text:navigable; type:dfn; for:Window;
	text:top-level traversable; type:dfn; for:/;
</pre>

<pre class=anchors>
url: https://html.spec.whatwg.org/multipage/semantics.html#meta-color-scheme;
	type: attr-value; for: meta/name; spec: html; text: color-scheme;
</pre>

<link rel="stylesheet" href="style.css" />

Introduction {#intro}
=====================

	This specification introduces three new features
	related to controlling how/when colors are auto-adjusted
	by the user agent:

	* [=Color schemes=]
		and the 'color-scheme' property,
		which controls whether or not browser-provided parts of the page's UI
		respect the user's chosen [=color scheme=].

	* [=Forced colors mode=]
		and the 'forced-color-adjust' property,
		which controls whether or not [=forced colors mode=] is allowed to apply to a given element.

	* The 'print-color-adjust' property,
		which controls whether the browser is allowed
		to automatically adjust colors to the user's assumed performance preferences,
		such as suppressing background colors when printing to save ink.

	Together with the <a descriptor for=@media>prefers-color-scheme</a>,
	<a descriptor for=@media>prefers-contrast</a>, and
	<a descriptor for=@media>forced-colors</a> [=media queries=] [[!MEDIAQUERIES-5]],
	this module allows color scheme negotiation
	between the author and the user.


Value Definitions {#values}
---------------------------

	This specification follows the <a href="https://www.w3.org/TR/CSS2/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]]
	using the <a href="https://www.w3.org/TR/css-values-3/#value-defs">value definition syntax</a> from [[!CSS-VALUES-3]].
	Value types not defined in this specification are defined in CSS Values &amp; 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 <a>CSS-wide keywords</a> as their property value.
	For readability they have not been repeated explicitly.


<!--
 ██████   ███████  ██        ███████  ████████           ██████   ██████  ██     ██ ████████ ██     ██ ████████
██    ██ ██     ██ ██       ██     ██ ██     ██         ██    ██ ██    ██ ██     ██ ██       ███   ███ ██
██       ██     ██ ██       ██     ██ ██     ██         ██       ██       ██     ██ ██       ████ ████ ██
██       ██     ██ ██       ██     ██ ████████  ███████  ██████  ██       █████████ ██████   ██ ███ ██ ██████
██       ██     ██ ██       ██     ██ ██   ██                 ██ ██       ██     ██ ██       ██     ██ ██
██    ██ ██     ██ ██       ██     ██ ██    ██          ██    ██ ██    ██ ██     ██ ██       ██     ██ ██
 ██████   ███████  ████████  ███████  ██     ██          ██████   ██████  ██     ██ ████████ ██     ██ ████████
-->

Preferred Color Schemes {#preferred}
=======================

	Operating systems and user agents often give users
	the ability to choose their <dfn export>preferred color scheme</dfn>
	for user interface elements.
	This <dfn export>color scheme</dfn> is 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.

	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 such a preference;
	users can have preferences for operating system interface colors
	that they do not want imposed on pages.)

	The most common [=color scheme=] preferences are:

	* A <dfn export local-lt=light>light color scheme</dfn> ("day mode")
		consists of light background colors and dark foreground/text colors.
	* A <dfn export local-lt=dark>dark color scheme</dfn> ("night mode")
		consists of the opposite,
		with dark background colors and light foreground/text colors.

	Note: [=Light=] and [=dark=] [=color schemes=]
	are not specific color palettes,
	but a range of possible palettes.
	For example,
	a stark black-on-white scheme and a sepia dark-on-tan scheme
	would both be considered [=light color schemes=].
	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;
	to ensure legibility,
	generally either both foreground and background should be paired [=system colors=]
	or both be manually specified colors.
	[[WCAG22]]

	The user's [=preferred color scheme=]
	is then combined with the [=page's supported color schemes=]
	to produce a <dfn export>page color scheme</dfn>.
	The [=page color scheme=] also records whether it's <dfn export for="color scheme">default</dfn> or not.
	The [=page color scheme=] is queryable with the '@media/prefers-color-scheme' [=media query=]. [[!MEDIAQUERIES-5]]

	Individual elements have an <dfn export>element color scheme</dfn>,
	which by default matches the [=page color scheme=],
	but can be overriden using the 'color-scheme' property.
	The [=element color scheme=] affects things such as the value of [=system colors=] on the element,
	the value of the ''light-dark()'' function,
	and how user interface elements (like scrollbars) render.
	(See [[#color-scheme-effect]].)

	User agents <em>may</em> support additional [=color schemes=],
	however CSS does not support negotiation of additional [=color schemes=]:
	user agents should pursue standardization of these schemes,
	so that '@media/prefers-color-scheme' and 'color-scheme' can reflect the additional values.

	Note: Because many pages were authored before [=color scheme=] support existed,
	and thus pages were authored with the assumption of the default ([=light=]) color scheme,
	user agents cannot automatically adapt the colors used in elements under their control,
	as it might cause unreadable color contrast with the surrounding page.
	Pages <em>have to</em> opt into [=color scheme=] support
	by setting the [=page color scheme=],
	or manually setting the 'color-scheme' property on individual elements.

Opting Into a Preferred Color Scheme {#color-scheme-page}
------------------------------------

	The [=page color scheme=]
	represents the [=color scheme=] that will be used for the page overall
	(queryable with the ''prefers-color-scheme'' [=media feature=])
	and for all elements that don't specifically override the [=page color scheme=] with the 'color-scheme' property.
	See [[#color-scheme-effect]] for a full description of what the [=color scheme=] effects.

	Note: In HTML, the <{meta/name/color-scheme|color-scheme &lt;meta>}>
	sets the [=page color scheme=].

	Authors <em>should</em> generally set the [=page color scheme=],
	rather than using the 'color-scheme' property,
	so that the '@media/prefers-color-scheme' [=media feature=]
	is consistent with the elements on the page.

	The [=page color scheme=] is determined by finding the [=used color scheme=],
	given the [=preferred color scheme=]
	and the <dfn export lt="page's supported color scheme">page's supported color schemes</dfn>
	(a [=color scheme support=]).

	In embedded documents
	(such as an <{iframe}> or an SVG <{img}>),
	the embedding element's [=element color scheme=]
	is used as the embedded document's [=preferred color scheme=]
	(treated as a normal [=color scheme preference=]),
	rather than the user's preference.
	<span class=note>This allows embedded documents to match the negotiated color scheme
	for the page or an element,
	similar to other elements in the parent document.</span>


	<div class=example>
		A page that responds to user preferences for light or dark display
		by using the ''@media/prefers-color-scheme'' media feature
		to alter the colors it uses
		can easily opt the browser-controlled UI
		(scrollbars, inputs, etc)
		to match
		with a simple global declaration:

		<xmp highlight=html>
			<meta name=color-scheme contents="light dark">
		</xmp>

		(Or, in languages that don't have a way to set the [=page color scheme=] directly,
		a '':root { color-scheme: light dark;}'' rule.)

		If a page limits itself to using <em>only</em> the <<system-color>>s,
		the 'color-scheme' declaration
		will support the user's preferred color scheme
		even without the author needing to use ''@media'' at all.
	</div>

	<div class=example>
		If a page cannot reasonably accommodate all color schemes,
		such as for branding or theatrical reasons,
		<{meta/name/color-scheme}> or 'color-scheme'
		can still indicate which color schemes the page <em>can</em> support,
		causing the UI to match.

		If the page's color scheme is primarily light,
		the following will indicate that explicitly:

		<xmp highlight=html>
			<meta name=color-scheme contents="light">
		</xmp>

		While if the page is primarily dark,
		indicating that explicitly will make the page look more coherent as well:

		<xmp highlight=html>
			<meta name=color-scheme contents="dark">
		</xmp>

		However, it is better to support both color schemes,
		of course.
	</div>



Overriding the Page Color Scheme: the 'color-scheme' property {#color-scheme-prop}
-----------------------------------------------------------------

	<pre class=propdef>
	Name: color-scheme
	Value: normal | [ light | dark | <<custom-ident>> ]+ && only?
	Initial: normal
	Applies to: all elements and text
	Inherited: yes
	Computed Value: the keyword ''normal'', or a [=color scheme support=]
	Animation type: discrete
	</pre>

	<wpt>
		parsing/color-scheme-computed.html
		parsing/color-scheme-invalid.html
		parsing/color-scheme-valid.html
		rendering/dark-color-scheme/color-scheme-change-checkbox.html
		rendering/dark-color-scheme/color-scheme-color-property.html
		rendering/dark-color-scheme/color-scheme-iframe-background-mismatch-alpha.html
		rendering/dark-color-scheme/color-scheme-iframe-background-mismatch-opaque-cross-origin.sub.html
		rendering/dark-color-scheme/color-scheme-iframe-background-mismatch-opaque.html
		rendering/dark-color-scheme/color-scheme-iframe-background-mismatch-used-preferred.html
		rendering/dark-color-scheme/color-scheme-iframe-background.html
		rendering/dark-color-scheme/color-scheme-iframe-dynamic.html
		rendering/dark-color-scheme/color-scheme-iframe-preferred-change.html
		rendering/dark-color-scheme/color-scheme-iframe-preferred-page-dark.html
		rendering/dark-color-scheme/color-scheme-iframe-preferred-page-light.html
		rendering/dark-color-scheme/color-scheme-iframe-preferred.html
		rendering/dark-color-scheme/color-scheme-link-crash.html
		rendering/dark-color-scheme/color-scheme-root-background.html
		rendering/dark-color-scheme/color-scheme-rule-cache.html
		rendering/dark-color-scheme/color-scheme-system-colors.html
		rendering/dark-color-scheme/color-scheme-table-border-currentcolor-responsive.html
		rendering/dark-color-scheme/color-scheme-visited-link-initial.html
	</wpt>

	While the [=page color scheme=] should generally be used
	to control what [=color scheme=] a page uses,
	occasionally there is need to override that [=color scheme=]
	on a particular subtree.
	The 'color-scheme' property allows this,
	manually setting the [=element color scheme=]
	for an element and its descendants.
	Values are defined as follows:

	<dl dfn-type=value dfn-for=color-scheme>
		: <dfn>normal</dfn>
		::
			The [=element color scheme=] is the same as the [=page color scheme=].
			(This includes noting whether the [=color scheme=] was [=color scheme/defaulted=].)

		: <dfn>light</dfn>
		: <dfn>dark</dfn>
		::
			Indicates that the element supports a [=light=] and/or [=dark=] color scheme,
			as appropriate.
			The element's [=color scheme support=] will include the keywords,
			in the order they're specified.

		: <dfn>only</dfn>
		::
			Forbids the user agent from [=overriding the color scheme=] for the element.
			The element's [=color scheme support=] will have a flag
			indicating sole support.

		: <dfn><<custom-ident>></dfn>
		::
			<<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 <em>must not</em> interpret any <<custom-ident>> values as having a meaning;
			any additional recognized color schemes
			must be explicitly added to this property’s grammar.

			Note: To avoid confusion,
			authoring tutorials and references
			should omit <<custom-ident>> from their materials.

			The ''color-scheme/normal'', ''light'', ''dark'', and ''only'' keywords
			are not valid <<custom-ident>>s in this property.
	</dl>

	If an element has any value other than ''color-scheme: normal'',
	its [=element color scheme=] is determined by finding the [=used color scheme=],
	given the user's [=preferred color scheme=]
	and the element's [=color scheme support=]
	specified by this property.

	<div class=example>
		A page might be generally capable of handling multiple color schemes,
		while still having a sub-section that needs to be rendered in a particular color scheme.

		For example,
		a style guide might give several UI examples that are using light or dark colors,
		showing off the light or dark theme specifically.
		This can be indicated as:

		<xmp highlight=markup>
			<meta name=color-scheme content="light dark">
			<style>
			.light-theme-example {
				color-scheme: light;
			}

			.dark-theme-example {
				color-scheme: dark;
			}
			</style>
		</xmp>

		Only the subsections rooted at ''.light-theme-example'' or ''.dark-theme-example''
		will be opted into the [=light=] or [=dark=] themes specifically;
		the rest of the page will respect the user's preference.
	</div>

	Note: 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.


Resolving Color Schemes {#color-scheme-resolution}
-----------------------

	While it's important for a page to respect the user's preferred [=color scheme=],
	it's also important to only use a [=color scheme=] the page author <em>expects</em>,
	or else it is very easy to render a page unreadable
	by causing the foreground and background elements to accidentally have minimal (or zero!) contrast.

	For example, an author expecting the default light color scheme
	might set the page background to a light cream
	while leaving the text color unset,
	expecting it to use the default black text color.
	If the page unexpectedly opted into a user's preferred [=dark color scheme=],
	however,
	and adjusted the default text color to white,
	that would make the text virtually unreadable.

	To balance these competing concerns,
	a user's [=color scheme preference=]
	is compared against a page's [=color scheme support=]
	to produce a used [=color scheme=].

	A <dfn export>color scheme preference</dfn>
	is either no preference,
	a [=color scheme=] preference ([=light=] or [=dark=]),
	or an <dfn for="color scheme" lt="overriding preference">overriding</dfn> [=color scheme=] preference.

	A <dfn export>color scheme support</dfn>
	is null,
	or an ordered list of one or more supported [=color schemes=],
	along with a flag indicating whether or not it <em>solely</em> supports the indicated [=color schemes=].

	<div algorithm>
		To determine the <dfn noexport>used color scheme</dfn>,
		given a [=color scheme support=] |support|
		and a [=color scheme preference=] |preference|:

		1. If |support| is null,
			or none of the [=color schemes=] in |support|
			are supported by the UA,
			return the UA default [=color scheme=],
			and annotate that this [=color scheme=] was [=color scheme/defaulted=].

		1. If |preference| is no preference,
			return the first supported [=color scheme=] in |support|.

		1. If |preference|'s [=color scheme=] is in |support|
			and supported by the UA,
			return that [=color scheme=].

		1. If |support| is flagged as sole support,
			return the first supported [=color scheme=] in |support|.

		1. If |preference| is an [=overriding preference=],
			return |preference|'s [=color scheme=].
			If this [=color scheme=] is used as an [=element color scheme=],
			also [=override the color scheme=] on the element
			to this [=color scheme=].

		1. Otherwise,
			return the first supported [=color scheme=] in |support|.

		Note: The basic logic here is that,
		if the page hasn't opted into color schemes at all (null |supports|),
		we go with the safe UA default that it was probably implicitly designed for.
		If there <em>is</em> a usable |supports|,
		and it matches |preference|,
		we use the preference.
		Otherwise |preference| and |supports| disagree,
		and we go back and forth down the preference hierarchy to see who wins:
		sole support in |support| wins,
		then overriding preference in |preference| wins
		(and we adjust the element's colors to make sure this actually <em>works</em>),
		then |support| finally wins.
	</div>

	Note: User agents are <strong>not required</strong>
	to support any particular [=color scheme=],
	so only using a single keyword,
	such as ''color-scheme: dark'',
	to indicate a required [=color scheme=]
	is still not guaranteed to have any effect on the rendering of the element.

	Note: User agents might not actually support preference levels in a [=color scheme preferences=].
	At the time of writing,
	UAs generally only support an ordinary [=light=] or [=dark=] preference,
	which considerably simplifies the above logic.


Effects of the Used Color Scheme {#color-scheme-effect}
--------------------------------

	For all elements,
	the user agent must match the following to the [=element color scheme=]:

	* 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
	* the value of [=system colors=]
	* the value of the ''light-dark()'' function

	On the root element,
	the [=element color scheme=] additionally must affect
	the surface color of the [=canvas=],
	and 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 [=element color scheme=] of the element
	and the [=element 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 root element's [=element 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);
	their canvases remain the default transparent regardless.

	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 [[#forced]].

Overriding the Color Scheme {#color-scheme-override}
---------------------------

If the user has indicated an [=color scheme/overriding preference=] for a particular color scheme that the author does not explicitly support,
and the author has not disallowed this (by using the ''only'' keyword),
the user agent must <dfn>override the color scheme</dfn>:
in addition to the effects described in [[#color-scheme-effect]],
it must also auto-adjust <em>other</em> colors into this chosen [=color scheme=],
such as by inverting their brightness,
while preserving any color contrast necessary for readability of the page.
In this case, UA may also auto-adjust colors within replaced elements, background images, and other external resources as appropriate.

Note: The specifics of such auto-adjustments are UA-defined,
and can differ from UA to UA.
But it is not intended to force all colors into a fixed palette,
as [=forced colors mode=] does,
only to force all colors on the page
to conform to either a [=dark=] or [=light=] color scheme.

<div class="example">
	For example, a UA might have a “dark room” mode,
	which forces all pages into a [=dark=] color scheme.

	For pages that already support [=dark=] color schemes,
	and have indicated so using the 'color-scheme' property
	or <{meta/name/color-scheme}> <{meta}> name,
	this has no effect other than reporting a ''@media/prefers-color-scheme/dark'' value
	for the <a descriptor for=@media>prefers-color-scheme</a> [=media query=]
	and selecting a [=dark=] [=used color scheme=].

	But for pages that do not explicitly support a [=dark=] color scheme,
	and have not explicitly forbidden this auto-adjustment
	by specifying ''color-scheme: only light'',
	this mode triggers auto-adjustment of the page’s colors
	to <em>force</em> the page to conform to the desired [=dark=] color scheme.
</div>


<!--
████████  ███████  ████████   ██████  ████████ ████████
██       ██     ██ ██     ██ ██    ██ ██       ██     ██
██       ██     ██ ██     ██ ██       ██       ██     ██
██████   ██     ██ ████████  ██       ██████   ██     ██
██       ██     ██ ██   ██   ██       ██       ██     ██
██       ██     ██ ██    ██  ██    ██ ██       ██     ██
██        ███████  ██     ██  ██████  ████████ ████████
-->

Forced Color Palettes {#forced}
=====================

	<dfn export>Forced colors mode</dfn> 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 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 <a>forced colors mode</a>,
	the user agent enforces the user’s preferred color palette on the page,
	overriding the author’s chosen colors for specific properties,
	see [[#forced-colors-properties]].
	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 <a>forced colors mode</a>
	user agents will match the '@media/forced-colors' media query
	<!-- (see [[MEDIAQUERIES-5]]) -->
	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 '@media/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
	''prefers-color-scheme/light'' or ''prefers-color-scheme/dark''
	as the user’s preferred color scheme.

	If [=get emulated forced colors theme data=]
	is not "{{ForcedColorsModeAutomationTheme/none}}",
	the user agent should bypass the above operating system color themes,
	and instead act as if the user has enabled <a>forced colors mode</a>
	with the [=forced colors mode emulation color palette=] defined for
	the resulting value of [=emulated forced colors theme data=].
		

<!--THOUGHTS
	This advice (below) maybe makes sense for (prefers-contrast),
	but is it really applicable to forced-colors as well?
	If so, should forced-colors be instead a 'forced' value on <a descriptor for=@media>prefers-contrast</a>,
	so that a (prefers-contrast) query will catch all of these cases at once?

	Authors are encouraged to simplify the contrast in their pages
	when '@media/forced-colors' is ''active'',
	reducing effects such as shadows, fades, blurs, filters, gradients,
	and image or pattern fills
	that add complexity to discerning shape outline
-->

Properties Affected by Forced Colors Mode {#forced-colors-properties}
-----------------------------------------

	When <a>forced colors mode</a> is active
	and 'forced-color-adjust' is ''forced-color-adjust/auto'' (see below) on an element,
	the <<color>> components of all properties on the element
	are force-adjusted to the user’s preferred color palette.

	<div class="note">
		Specifically, <a>forced colors mode</a> applies to the following color properties,
		along with their shorthands.
		This is the list of color properties existing at the time of writing,
		but it may not be an exhaustive list as more properties get added over time:

		<ul>
			<li>'accent-color'
			<li>'background-color'
			<li>'border-color'
			<li>'caret-color'
			<li>'color'
			<li>'flood-color'
			<li>'fill'
			<li>'lighting-color'
			<li>'outline-color'
			<li>'rule-color'
			<li>'scrollbar-color'
			<li>'stop-color'
			<li>'stroke'
			<li>'text-decoration-color'
			<li>'text-emphasis-color'
			<li>'-webkit-tap-highlight-color'
		</ul>
	</div>

	For each <<color>> component of a property,
	if its [=computed value=] is a color other than a [=system color=],
	its [=used value=] is instead forced to a [=system color=] as follows:

	* For 'background-color' in particular,
		it is forced to
		the color opposite the 'color' property’s [=system color=] value
		in the [=system color pairings=],
		using ''CanvasText'' as the opposite of ''Canvas''.
		However, its alpha channel is taken from
		the original 'background-color' value
		so that transparent backgrounds remain transparent.
	* In all other cases, the UA determines
		the appropriate forced [=system color=]--
		which should match the color that would result
		from an empty [=author style sheet=]
		whenever all of the element’s affected properties
		are likewise UA-determined.

		<div class="note">
			UAs need to be careful about inheritance when forcing colors.
			For example,
			suppose the UA’s button 'color' and 'background-color'
			are the opposite of its canvas 'color' and 'background-color'.
			Given markup such as

			<xmp highlight=html>
				<button>Push <em>this</em> button</button>
			</xmp>

			Normally, <{em}> will inherit from <{button}>,
			ensuring its readability.
			However in [=forced colors mode=],
			the 'color' of both <{button}> and <{em}> will need to be forced.
			It's easy to see that <{button}>’s color should be forced to the button color,
			but <{em}> also needs to be forced to the button color;
			if it were forced to the canvas 'color' like it is everywhere else in the document,
			its text will be unreadable.
		</div>

	Additionally:
	* 'box-shadow' and 'text-shadow' compute to ''box-shadow/none''
	* 'background-image' computes to ''background-image/none''
		unless the original value contains a ''url()'' function
	* 'color-scheme' computes to ''light dark''
	* 'scrollbar-color' computes to ''scrollbar-color/auto''
	* 'accent-color' computes to ''accent-color/auto''
	* If 'font-variant-emoji' computes to ''font-variant-emoji/normal'' or ''font-variant-emoji/unicode'',
		UAs should force any emoji on the page to its monochrome variant, if available,
		by forcing the [=computed value=] of 'font-variant-emoji' to ''font-variant-emoji/text''.

	UAs may further tweak these <a>forced colors mode</a> heuristics
	to provide better user experience.

	<div class="example">
		Authors may still use features such as ''color-mix()'' in [=forced colors mode=].
		In such cases, the [=computed value=] will behave as it would normally,
		but the [=used value=] will be overridden with an appropriate [=system color=].

		<pre highlight=css>
		.example {
			color: color-mix(in srgb, CanvasText, Canvas);
		}
		</pre>

		The [=computed value=] for 'color' will be a 50-50 blend of the ''CanvasText'' and ''Canvas'' [=system colors=].
		That value will inherit to descendants and be observable via APIs such as {{Element/computedStyleMap()}}.

		The [=used value=] for 'color' will be a system color chosen by the UA, for example ''CanvasText''.
	</div>

Opting Out of a Forced Color Palette: the 'forced-color-adjust' property {#forced-color-adjust-prop}
-----------------------------------------------------------------

	<pre class=propdef>
	Name: forced-color-adjust
	Value: auto | none | preserve-parent-color
	Initial: auto
	Applies to: all elements and text
	Inherited: yes
	Animation type: not animatable
	</pre>

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

	<dl dfn-type=value dfn-for=forced-color-adjust>
		: <dfn>auto</dfn>
		:: The element’s colors are automatically adjusted by the UA
			in <a>forced colors mode</a>.

		: <dfn>none</dfn>
		:: The element’s colors are not automatically adjusted by the UA
			in <a>forced colors mode</a>.

			Advisement: 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.

		: <dfn>preserve-parent-color</dfn>
		:: In [=forced colors mode=],
			if the 'color' property inherits from its parent
			(i.e. there is no [=cascaded value=]
			or the [=cascaded value=] is ''currentColor'', ''inherit'',
			or another keyword that inherits from the parent),
			then it computes to the [=used value|used=] color of its parent’s 'color' value.

			In all other respects, behaves the same as ''none''.

			Note: This value is intended solely to get a reasonable behavior
			from embedded SVG elements that expect to receive the outer document's text color
			(and stay consistent with adjustments from [=forced colors mode=]),
			while otherwise defaulting SVGs
			to preserving their exact colors,
			as [=forced colors mode=] can't generally be usefully applied to illustrations.
	</dl>

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

	<pre highlight=css>
		@namespace "http://www.w3.org/2000/svg";
		svg|svg { forced-color-adjust: preserve-parent-color; }
		svg|foreignObject { forced-color-adjust: auto; }
	</pre>

	UAs must propagate the 'forced-color-adjust' value set on the root element
	to the document viewport
	(where it can affect e.g. the canvas background).
	Note that 'forced-color-adjust' is <em>not</em> propagated from HTML <{body}>.

<wpt>
	/css/css-forced-color-adjust/inheritance.html
	/css/css-forced-color-adjust/parsing/forced-color-adjust-computed.html  
	/css/css-forced-color-adjust/parsing/forced-color-adjust-invalid.html  
	/css/css-forced-color-adjust/parsing/forced-color-adjust-valid.html
</wpt>


<!--
 ██████   ███████  ██        ███████  ████████             ███    ████████        ██ ██     ██  ██████  ████████
██    ██ ██     ██ ██       ██     ██ ██     ██           ██ ██   ██     ██       ██ ██     ██ ██    ██    ██
██       ██     ██ ██       ██     ██ ██     ██          ██   ██  ██     ██       ██ ██     ██ ██          ██
██       ██     ██ ██       ██     ██ ████████  ███████ ██     ██ ██     ██       ██ ██     ██  ██████     ██
██       ██     ██ ██       ██     ██ ██   ██           █████████ ██     ██ ██    ██ ██     ██       ██    ██
██    ██ ██     ██ ██       ██     ██ ██    ██          ██     ██ ██     ██ ██    ██ ██     ██ ██    ██    ██
 ██████   ███████  ████████  ███████  ██     ██         ██     ██ ████████   ██████   ███████   ██████     ██
-->

Performance-based Color Adjustments {#perf}
===================================

	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.
	This section defines properties for controlling these automatic adjustments.

Ink Economy: the 'print-color-adjust' property {#print-color-adjust}
----------------------------------------------

	<pre class='propdef'>
	Name: print-color-adjust
	Value: economy | exact
	Initial: economy
	Applies to: all elements
	Percentages: N/A
	Inherited: yes
	Computed value: specified keyword
	Animation type: discrete
	</pre>

	<wpt>
		parsing/print-color-adjust.html
	</wpt>

	The 'print-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 printer or similar device,
	such as using light text on a dark background.
	If user agents allow users to control this aspect of the document's display,
	the user preference <strong>must</strong> be respected more strongly
	than the hint provided by 'print-color-adjust'.
	It has the following values:

	<dl dfn-type=value dfn-for=print-color-adjust>
		<dt><dfn>economy</dfn>
		<dd>
			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.

		<dt><dfn>exact</dfn>
		<dd>
			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.
	</dl>

	UAs must propagate the 'print-color-adjust' value set on the root element
	to the document viewport
	(where it can affect e.g. the canvas background).
	Note that 'print-color-adjust' is <em>not</em> propagated from HTML <{body}>.

The 'color-adjust' Shorthand {#color-adjust}
--------------------------------------------

	<pre class="propdef shorthand">
	Name: color-adjust
	Value: <<'print-color-adjust'>>
	</pre>

	The 'color-adjust' shorthand allows an author
	to set all of the performance-motivated color adjustment properties
	in one declaration.
	(Currently, there is only one such property--
	'print-color-adjust'--
	but more might be added in the future.)

	Advisement: The 'color-adjust' shorthand is currently <em>deprecated</em>.
	Authors should use the more specific 'print-color-adjust' property,
	to avoid accidentally resetting performance-based color adjustments
	in other contexts than the one intended.

<wpt>
	animation/color-scheme-no-interpolation.html
	animation/forced-color-adjust-no-interpolation.html
	inheritance.html
</wpt>

Emulation {#color-adjust-emulation}
===================================
	For the purposes of user agent automation and application testing, this document
	defines the below emulations.

	Emulate Forced Colors Mode {#emulate-forced-colors-mode}
	--------------------------------------------

	Each [=top-level traversable=] has an associated
	<dfn>emulated forced colors theme data</dfn>, which is data representing
	{{ForcedColorsModeAutomationTheme}}, initially "{{ForcedColorsModeAutomationTheme/none}}".

	<xmp class="idl">
		enum ForcedColorsModeAutomationTheme {
			"none",
			"light",
			"dark"
		};
	</xmp>

	To <dfn export>set emulated forced colors theme data</dfn>, given
	[=navigable=] |navigable| and an |emulatedThemeData|:

	1. Assert |emulatedThemeData| is {{ForcedColorsModeAutomationTheme}}.

	2. Let |traversable| be |navigable|’s [=navigable/top-level traversable=].

	3. If |traversable| is not null:
		1. Set |traversable|'s associated [=emulated forced colors theme data=] to
			|emulatedThemeData|.
		
		2. UAs must consider this a change that requires style recalculation.
	
	To <dfn>get emulated forced colors theme data</dfn>, given {{ForcedColorsModeAutomationTheme}}
		|theme|:

	1. Let |navigable| be |theme|'s [=relevant global object=]'s
		[=associated Document=]'s [=node navigable=].

	2. If |navigable| is null, return null.

	3. Let |traversable| be |navigable|’s [=navigable/top-level traversable=].

	4. If |traversable| is null, return null.

	5. Return |traversable|'s associated [=emulated forced colors theme data=].

Forced Colors Mode Color Palettes {#forced-color-palettes}
----------------------------------------------
	For the purposes of user agent automation and application testing, this document
	defines the below <dfn>forced colors mode emulation color palettes</dfn>.

		<table class="data">
			<caption>
				[=System color=] mappings for "{{ForcedColorsModeAutomationTheme/light}}"
			</caption>
			<thead>
			<tr>
				<th><<system-color>> keyword</th>
				<th>Value</th>
			</tr>
			</thead>
			<tbody>
				<tr>
					<td>''AccentColor''</td>
					<td>
						<span class="swatch" style="--color: #FFFFFF"></span>
						&nbsp;#FFFFFF
					</td>
				</tr>
				<tr>
					<td>''AccentColorText''</td>
					<td>
						<span class="swatch" style="--color: #000000"></span>
						&nbsp;#000000
					</td>
				</tr>
				<tr>
					<td>''ActiveText''</td>
					<td>
						<span class="swatch" style="--color: #00009F"></span>
						&nbsp;#00009F
					</td>
				</tr>
				<tr>
					<td>''ButtonBorder''</td>
					<td>
						<span class="swatch" style="--color: #000000"></span>
						&nbsp;#000000
					</td>
				</tr>
				<tr>
					<td>''ButtonFace''</td>
					<td>
						<span class="swatch" style="--color: #FFFFFF"></span>
						&nbsp;#FFFFFF
					</td>
				</tr>
				<tr>
					<td>''ButtonText''</td>
					<td>
						<span class="swatch" style="--color: #000000"></span>
						&nbsp;#000000
					</td>
				</tr>
				<tr>
					<td>''Canvas''</td>
					<td>
						<span class="swatch" style="--color: #FFFFFF"></span>
						&nbsp;#FFFFFF
					</td>
				</tr>
				<tr>
					<td>''CanvasText''</td>
					<td>
						<span class="swatch" style="--color: #000000"></span>
						&nbsp;#000000
					</td>
				</tr>
				<tr>
					<td>''Field''</td>
					<td>
						<span class="swatch" style="--color: #FFFFFF"></span>
						&nbsp;#FFFFFF
					</td>
				</tr>
				<tr>
					<td>''FieldText''</td>
					<td>
						<span class="swatch" style="--color: #000000"></span>
						&nbsp;#000000
					</td>
				</tr>
				<tr>
					<td>''GrayText''</td>
					<td>
						<span class="swatch" style="--color: #600000"></span>
						&nbsp;#600000
					</td>
				</tr>
				<tr>
					<td>''Highlight''</td>
					<td>
						<span class="swatch" style="--color: #37006E"></span>
						&nbsp;#37006E
					</td>
				</tr>
				<tr>
					<td>''HighlightText''</td>
					<td>
						<span class="swatch" style="--color: #FFFFFF"></span>
						&nbsp;#FFFFFF
					</td>
				</tr>
				<tr>
					<td>''LinkText''</td>
					<td>
						<span class="swatch" style="--color: #00009F"></span>
						&nbsp;#00009F
					</td>
				</tr>
				<tr>
					<td>''Mark''</td>
					<td>
						N/A - this [=system color=] keyword should not be adjusted.
					</td>
				</tr>
				<tr>
					<td>''MarkText''</td>
					<td>
						N/A - this [=system color=] keyword should not be adjusted.
					</td>
				</tr>
				<tr>
					<td>''SelectedItem''</td>
					<td>
						<span class="swatch" style="--color: #37006E"></span>
						&nbsp;#37006E
					</td>
				</tr>
				<tr>
					<td>''SelectedItemText''</td>
					<td>
						<span class="swatch" style="--color: #FFFFFF"></span>
						&nbsp;#FFFFFF
					</td>
				</tr>
				<tr>
					<td>''VisitedText''</td>
					<td>
						<span class="swatch" style="--color: #00009F"></span>
						&nbsp;#00009F
					</td>
				</tr>
			</tbody>
		</table>

		<table class="data">
			<caption>
				[=System color=] mappings for "{{ForcedColorsModeAutomationTheme/dark}}"
			</caption>
			<thead>
				<tr>
					<th><<system-color>> keyword</th>
					<th>Value</th>
				</tr>
			</thead>
			<tbody>
				<tr>
					<td>''AccentColor''</td>
					<td>
						<span class="swatch" style="--color: #000000"></span>
						&nbsp;#000000
					</td>
				</tr>
				<tr>
					<td>''AccentColorText''</td>
					<td>
						<span class="swatch" style="--color: #FFFFFF"></span>
						&nbsp;#FFFFFF
					</td>
				</tr>
				<tr>
					<td>''ActiveText''</td>
					<td>
						<span class="swatch" style="--color: #FFFF00"></span>
						&nbsp;#FFFF00
					</td>
				</tr>
				<tr>
					<td>''ButtonBorder''</td>
					<td>
						<span class="swatch" style="--color: #000000"></span>
						&nbsp;#000000
					</td>
				</tr>
				<tr>
					<td>''ButtonFace''</td>
					<td>
						<span class="swatch" style="--color: #000000"></span>
						&nbsp;#000000
					</td>
				</tr>
				<tr>
					<td>''ButtonText''</td>
					<td>
						<span class="swatch" style="--color: #FFFFFF"></span>
						&nbsp;#FFFFFF
					</td>
				</tr>
				<tr>
					<td>''Canvas''</td>
					<td>
						<span class="swatch" style="--color: #000000"></span>
						&nbsp;#000000
					</td>
				</tr>
				<tr>
					<td>''CanvasText''</td>
					<td>
						<span class="swatch" style="--color: #FFFFFF"></span>
						&nbsp;#FFFFFF
					</td>
				</tr>
				<tr>
					<td>''Field''</td>
					<td>
						<span class="swatch" style="--color: #000000"></span>
						&nbsp;#000000
					</td>
				</tr>
				<tr>
					<td>''FieldText''</td>
					<td>
						<span class="swatch" style="--color: #FFFFFF"></span>
						&nbsp;#FFFFFF
					</td>
					<td></td>
				</tr>
				<tr>
					<td>''GrayText''</td>
					<td>
						<span class="swatch" style="--color: #3FF23F"></span>
						&nbsp;#3FF23F
					</td>
				</tr>
				<tr>
					<td>''Highlight''</td>
					<td>
						<span class="swatch" style="--color: #1AEBFF"></span>
						&nbsp;#1AEBFF
					</td>
				</tr>
				<tr>
					<td>''HighlightText''</td>
					<td>
						<span class="swatch" style="--color: #000000"></span>
						&nbsp;#000000
					</td>
				</tr>
				<tr>
					<td>''LinkText''</td>
					<td>
						<span class="swatch" style="--color: #FFFF00"></span>
						&nbsp;#FFFF00
					</td>
				</tr>
				<tr>
					<td>''Mark''</td>
					<td>
						N/A - this [=system color=] keyword should not be adjusted.
					</td>
				</tr>
				<tr>
					<td>''MarkText''</td>
					<td>
						N/A - this [=system color=] keyword should not be adjusted.
					</td>
				</tr>
				<tr>
					<td>''SelectedItem''</td>
					<td>
						<span class="swatch" style="--color: #1AEBFF"></span>
						&nbsp;#1AEBFF
					</td>
				</tr>
				<tr>
					<td>''SelectedItemText''</td>
					<td>
						<span class="swatch" style="--color: #000000"></span>
						&nbsp;#000000
					</td>
				</tr>
				<tr>
					<td>''VisitedText''</td>
					<td>
						<span class="swatch" style="--color: #FFFF00"></span>
						&nbsp;#FFFF00
					</td>
				</tr>
			</tbody>
		</table>


Privacy Considerations {#privacy}
===================================

	Applying user color preferences via [=color schemes=] or [=forced colors mode=]
	exposes the user's color preferences to the page
	via {{getComputedStyle()}},
	which can increase fingerprinting surface.

	<div class=note>
		Avoiding this comes with unfortunate drawbacks that were deemed too significant to be ignored.
		Namely:

		* preserving system colors as keywords until actual-value time
			would break a significant amount of deployed script,
			as the initial value of 'color' is a system color already
			(but a huge amount of script implicitly expects to see an RGB color from 'color')
		* lying about system colors from the scripting APIs
			(pretending they're always some static values)
			can result in any colors calculated <em>from</em> page colors in script
			being unreadable when used with the <em>actual</em> system colors.

		See <a href="https://github.com/w3c/csswg-drafts/issues/5710#issuecomment-840772752">Issue 5710</a>
		for discussion on this topic.
	</div>

	Embedded documents (even cross-origin ones)
	recieve their embedding element's [=element color scheme=]
	as their [=preferred color scheme=],
	which is technically a bit of cross-site communication.
	This was not considered a significant problem by browser security reviewers,
	and the user benefit of having pages and, particularly, SVG images
	automatically adapt to the parent page's color scheme
	was considered valuable enought to warrant it.

Security Considerations {#security}
===================================

	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.

Acknowledgements {#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:
	François Remy,
	イアンフェッティ

	ISSUE: List additional MSFT / Apple / Google people here.

Changes {#changes}
=======

	Changes since the <a href="https://www.w3.org/TR/2022/CR-css-color-adjust-1-20220210/">10 February 2022 Candidate Recommendation Snapshot</a>:

	<ul>
		<li>Removed special handling of ''color()'' fallback system colors, since the feature was removed from [[CSS-COLOR-4]].
			(<a href="https://github.com/w3c/csswg-drafts/issues/7007">Issue 7007</a>)
		<li> Added emulation support for improved testing of [=forced colors mode=].
			(<a href="https://github.com/w3c/csswg-drafts/issues/11824#issuecomment-2769343959">Issue 11824</a>)
		<li> Updated the properties that apply in [=forced colors mode=]
			to more generically apply to the <<color>> components of all properties,
			with specific known properties moved to a note.
			(<a href="https://github.com/w3c/csswg-drafts/issues/11857">Issue 11857</a>)
		<li> Added font emoji fallback logic for [=forced colors mode=].
			(<a href="https://github.com/w3c/csswg-drafts/issues/8064">Issue 8064</a>)
	</ul>

	<strong>See also <a href="https://www.w3.org/TR/2022/CR-css-color-adjust-1-20220210/#changes">Changes prior to Candidate Recommendation</a>.</strong>
