[css-color-adjust-1] Per WG resolution in w3c#3881, remove the 'only' keyword from 'color-scheme', and adjust the resolution rules to always respect author preference. Since the used color scheme resolution rules are now simple enough to inline, remove the table and the algorithm. Also add some examples highlighting good practice.

Author: tabatkins

css-color-adjust-1/Overview.bs

@@ -108,94 +108,60 @@ Opting Into a Preferred Color Scheme: the 'color-scheme' property {#color-scheme
 
 	<pre class=propdef>
 	Name: color-scheme
-	Value: normal | [ light | dark | <<custom-ident>> ]+ | only && light
+	Value: normal | [ light | dark | <<custom-ident>> ]+
 	Initial: normal
 	Applies to: all elements
 	Inherited: yes
-	Computed Value: the keyword ''normal'', or optional ''only'' keyword and ordered list of specified color scheme keywords
+	Computed Value: the keyword ''normal'', or an ordered list of specified color scheme keywords
 	</pre>
 
 	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=]
+	These values are negotiated with the user's preferences,
+	resulting in a <dfn>used color scheme</dfn>
 	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.
 
-
-	<table class="data">
-	<caption>Interaction of author and user preferences in determining [=used color scheme=] (non-normative)</caption>
-	<colgroup span=2></colgroup>
-	<colgroup span=3></colgroup>
-	<thead>
-		<tr>
-			 <td colspan=2 rowspan=2>
-			 <th colspan=3>User Preference ('prefers-color-scheme')
-		<tr>
-			<th>''@media/prefers-color-scheme/no-preference''
-			<th>''@media/prefers-color-scheme/light''
-			<th>''@media/prefers-color-scheme/dark''
-	<tbody>
-		<tr>
-			<th rowspan=7 style="width: 1.2em; writing-mode: vertical-rl; writing-mode: sideways-lr">Author Preference ('color-scheme')
-			<th>''color-scheme/normal''
-			<td>default
-			<td>default
-			<td>default
-		<tr>
-			<th>''color-scheme/light''
-			<td>light
-			<td>light
-			<td>default
-		<tr>
-			<th>''color-scheme/dark''
-			<td>dark
-			<td>default
-			<td>dark
-		<tr>
-			<th>''color-scheme/light dark''
-			<td>light
-			<td>light
-			<td>dark
-		<tr>
-			<th>''color-scheme/dark light''
-			<td>dark
-			<td>light
-			<td>dark
-		<tr>
-			<th>''color-scheme/only light''
-			<td>light
-			<td>light
-			<td>light
-		<tr>
-			<th>''color-scheme/only dark''
-			<td>dark
-			<td>dark
-			<td>dark
-	</table>
-
 	Values are defined as follows:
 
 	<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 isn't aware of [=color schemes=] at all,
 			and so the element should be rendered with the browser's default [=color scheme=].
 
 		: <dfn lt="light | dark">[ light | dark | <<custom-ident>> ]+</dfn>
-		:: Indicates that the element is aware of and can handle the listed [=color schemes=],
-			and expresses an ordered preference between them.
-			(See [[#color-scheme-processing]] for details on how this choice is resolved.)
+		::
+			Indicates that the element is okay with being rendered with any of the listed [=color schemes=].
+
+			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=].
 
-			Note: Providing both keywords indicates that the first scheme is preferred,
-			but the second is also acceptable
-			if the user prefers it instead.
+			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.
 
-			''light'' represents a “Light” [=color scheme=],
+			Otherwise,
+			the [=used color scheme=] is the browser default.
+			(Same as ''color-scheme/normal''.)
+
+			''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.
 
+			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.
+
 			<<custom-ident>> values are meaningless,
 			and exist only for future compatibility,
 			so that future added color schemes do not invalidate the 'color-scheme' declaration
@@ -207,81 +173,59 @@ Opting Into a Preferred Color Scheme: the 'color-scheme' property {#color-scheme
 			authoring tutorials and references
 			should omit <<custom-ident>> from their materials.
 
-			''only'', ''color-scheme/normal'', ''light'', and ''dark'' are not valid <<custom-ident>>s in this property.
+			''color-scheme/normal'', ''light'', and ''dark'' are not valid <<custom-ident>>s in this property.
 
-			Repeating a keyword, such as ''color-scheme: light light'',
+			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.
+	</dl>
 
-		: <dfn lt=only>only</dfn>
-		:: If provided,
-			''only'' indicates that the element <em>must</em> be rendered with one of the specified [=color schemes=],
-			if possible,
-			even if the user's preference is for a different [=color scheme=].
-
-			Issue: 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 <strong>should not</strong> use this value,
-			and should instead ensure that their page renders well with whatever [=color scheme=] the user prefers
-			(using the '@media/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.
+	<div class=example>
+		A well-written page
+		that responds to user preferences for light or dark display
+		by using the 'prefers-color-scheme' media feature
+		to alter the colors it uses
+		can easily opt the browser-controlled UI
+		(scrollbars, inputs, etc)
+		into the user's preferred color scheme as well
+		with a simple global declaration:
+
+		<pre highlight=css>
+		:root {
+			color-scheme: light dark;
+		}
+		</pre>
+	</div>
 
-			Note: User agents are <strong>not required</strong>
-			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.
-	</dl>
+	<div class=example>
+		If a page limits itself to using <em>only</em> the <<system-color>>s,
+		it can support the user's preferred color scheme
+		without needing to use ''@media'' at all,
+		simply by using the 'color-scheme' property:
+
+		<pre highlight=css>
+		:root {
+			color-scheme: light dark;
+		}
+		</pre>
 
-	Note: “Light” and “Dark” modes are not specific color palettes.
+		because the [=used color scheme=]
+		affects what <<system-color>>s resolve to.
+	</div>
+
+	Note: “Light” and “dark” color schemes 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.
 
-Finding the Used Color Scheme {#color-scheme-processing}
------------------------------
-
-	<div algorithm>
-		To find the <dfn>used color scheme</dfn> for an element |el|:
-
-		1. Let |scheme| be the keyword matching '@media/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 <css>no-preference</css>,
-			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 <css>no-preference</css>.
-	</div>
+	Note: Earlier versions of this property also defined an <css>only</css> keyword
+	to be specified alongside a preferred color scheme,
+	indicating a stronger author preference.
+	It ended up being unnecessary,
+	and was removed.
 
-	For each element,
-	find the [=used color scheme=] for that element.
-	If the [=used color scheme=] is <css>no-preference</css>,
-	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.
 
 Effects of the Used Color Scheme {#color-scheme-effect}
 --------------------------------