[css-color-adjust-1] Re-add only, per WG resolution and the proposal in w3c#5089

Author: tabatkins

css-color-adjust-1/Overview.bs

@@ -23,6 +23,11 @@ spec:fill-stroke-3; type:property;
 	text:stroke
 </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>
+
 Introduction {#intro}
 =====================
 
@@ -128,7 +133,7 @@ Opting Into a Preferred Color Scheme: the 'color-scheme' property {#color-scheme
 
 	<pre class=propdef>
 	Name: color-scheme
-	Value: normal | [ light | dark | <<custom-ident>> ]+
+	Value: normal | [ light | dark | <<custom-ident>> ]+ && only?
 	Initial: normal
 	Applies to: all elements and text
 	Inherited: yes
@@ -158,20 +163,22 @@ Opting Into a Preferred Color Scheme: the 'color-scheme' property {#color-scheme
 	<dl dfn-type=value dfn-for=color-scheme>
 		: <dfn>normal</dfn>
 		::
-			Indicates that the element isn't aware of [=color schemes=] at all,
+			Indicates that the element doesn't support [=color schemes=] at all,
 			and so the element should be rendered with the browser's default [=color scheme=].
 
 			(This is typically, tho not always, similar to ''light''.)
 
 		: <dfn>light</dfn>
 		::
-			Indicates that the page can handle the element being rendered
-			in a [=light color scheme=].
+			Indicates that the element supports a [=light color scheme=].
 
 		: <dfn>dark</dfn>
 		::
-			Indicates that the page can handle the element being rendered
-			in a [=dark color scheme=].
+			Indicates that the element supports a [=dark color scheme=].
+
+		: <dfn>only</dfn>
+		::
+			Forbids the user agent from [=overriding the color scheme=] for the element.
 
 		: <dfn><<custom-ident>></dfn>
 		::
@@ -187,7 +194,7 @@ Opting Into a Preferred Color Scheme: the 'color-scheme' property {#color-scheme
 			authoring tutorials and references
 			should omit <<custom-ident>> from their materials.
 
-			The ''color-scheme/normal'', ''light'', and ''dark'' keywords
+			The ''color-scheme/normal'', ''light'', ''dark'', and ''only'' keywords
 			are not valid <<custom-ident>>s in this property.
 	</dl>
 
@@ -199,20 +206,31 @@ Opting Into a Preferred Color Scheme: the 'color-scheme' property {#color-scheme
 	To ensure particular foreground or background colors,
 	they need to be specified explicitly.
 
-	If the user's [=preferred color scheme=],
-	as indicated by the 'prefers-color-scheme' media feature,
-	is present among the listed [=color schemes=],
-	and is supported by the user agent,
-	that's the element's [=used color scheme=].
-
-	Otherwise,
-	if the user agent supports at least one of the listed [=color schemes=],
-	the [=used color scheme=] is
-	the first supported [=color scheme=] in the list.
-
-	Otherwise,
-	the [=used color scheme=] is the browser default.
-	(Same as ''color-scheme/normal''.)
+	<div algorithm>
+		To <dfn noexport>determine the used color scheme</dfn> of an element:
+
+		1. If the user's [=preferred color scheme=],
+			as indicated by the 'prefers-color-scheme' media feature,
+			is present among the listed [=color schemes=],
+			and is supported by the user agent,
+			that's the element's [=used color scheme=].
+
+		2. Otherwise,
+			if the user has indicated an overriding preference for their chosen color scheme,
+			and the ''only'' keyword is not present in 'color-scheme' for the element,
+			the user agent must [=override the color scheme=]
+			with the user's [=preferred color scheme=].
+			See [[#color-scheme-override]].
+
+		3. Otherwise,
+			if the user agent supports at least one of the listed [=color schemes=],
+			the [=used color scheme=] is
+			the first supported [=color scheme=] in the list.
+
+		4. Otherwise,
+			the [=used color scheme=] is the browser default.
+			(Same as ''color-scheme/normal''.)
+	</div>
 
 	Note: User agents are <strong>not required</strong>
 	to support any particular [=color scheme=],
@@ -347,6 +365,44 @@ Effects of the Used Color Scheme {#color-scheme-effect}
 	more invasive changes might be applied;
 	see [[#forced]].
 
+Overriding the Color Scheme {#color-scheme-override}
+---------------------------
+
+If the user has indicated an <em>overriding</em> preference for a particular color scheme,
+and the author has not disallowed this (by using the ''only'' keyword),
+the user agent may <dfn>override the color scheme</dfn>,
+forcing the [=used color scheme=] to the user's [=preferred color scheme=].
+If the element does not support that [=color scheme=],
+the user agent must also auto-adjust other 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 'prefers-color-scheme' [=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>
+
 
 <!--
 ████████  ███████  ████████   ██████  ████████ ████████
@@ -358,8 +414,8 @@ Effects of the Used Color Scheme {#color-scheme-effect}
 ██        ███████  ██     ██  ██████  ████████ ████████
 -->
 
-Forced Color Schemes {#forced}
-====================
+Forced Color Palettes {#forced}
+=====================
 
 	<dfn export>Forced colors mode</dfn> is an accessibility feature
 	intended to increase the readability of text through color contrast.
@@ -498,7 +554,7 @@ Properties Affected by Forced Colors Mode {#forced-colors-properties}
 	UAs may further tweak these <a>forced colors mode</a> heuristics
 	to provide better user experience.
 
-Opting Out of a Forced Color Scheme: the 'forced-color-adjust' property {#forced-color-adjust-prop}
+Opting Out of a Forced Color Palette: the 'forced-color-adjust' property {#forced-color-adjust-prop}
 -----------------------------------------------------------------
 
 	<pre class=propdef>