[css-color-adjust-1][editorial] Reorganize color-scheme section. #5897

Author: tabatkins

css-color-adjust-1/Overview.bs

@@ -30,12 +30,12 @@ Introduction {#intro}
 	related to controlling how/when colors are auto-adjusted
 	by the user agent:
 
-	* The concept of [=color schemes=]
+	* [=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=].
 
-	* The concept of [=forced colors mode=]
+	* [=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.
 
@@ -66,31 +66,30 @@ Preferred Color Schemes {#preferred}
 =======================
 
 	Operating systems and user agents often give users
-	the ability to choose their preferred <dfn>color schemes</dfn>
+	the ability to choose their <dfn export>preferred color scheme</dfn>
 	for user interface elements.
-	These are typically reflected in the user agent's rendering
+	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,
-	and are expected to also be reflected
-	in the values of the CSS system colors.
+	and is 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;
+	(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 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 <a href="https://www.w3.org/TR/mediaqueries-5/">Media Queries Level 5</a>,
-	defines controls to enable [=color scheme=] negotiation
-	for “Light” and “Dark” [=color schemes=] (and no preference).
+	The most common [=color scheme=] preferences are:
 
-	Note: <strong>The “Light” and “Dark” color schemes
+	* 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.
+
+	Advisement: <strong>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.</strong>
@@ -100,37 +99,19 @@ Preferred Color Schemes {#preferred}
 	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=],
+	To enable pages to adapt to the user's [=preferred color scheme=],
 	user agents will match the '@media/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
-	    <span class=issue>find what we name this in other specs</span>,
-		the initial value of the '/color' property,
-		and the [[css-color-4#css-system-colors|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
+	to the user's [=preferred color scheme=].
+	[[!MEDIAQUERIES-5]]
+	Complementing this, the 'color-scheme' property defined here
+	lets the author indicate appropriate [=color schemes=]
+	for UA-provided UI and colors in the page.
 
 	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: 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]].
-
 Opting Into a Preferred Color Scheme: the 'color-scheme' property {#color-scheme-prop}
 -----------------------------------------------------------------
 
@@ -152,9 +133,10 @@ Opting Into a Preferred Color Scheme: the 'color-scheme' property {#color-scheme
 	which [=color schemes=] it is designed to be rendered with.
 	These values are negotiated with the user's preferences,
 	resulting in a <dfn export>used color scheme</dfn>
-	that affects UI things such as
+	that affects things such as
 	the default colors of form controls and scrollbars
-	as well as the used values of the CSS system colors.
+	as well as the used values of the [[css-color-4#css-system-colors|CSS system colors]].
+	(See [[#color-scheme-effect]].)
 
 	Note: Because many pages were authored before color scheme support existed,
 	user agents cannot automatically adapt the colors used in elements under their control,
@@ -168,55 +150,64 @@ Opting Into a Preferred Color Scheme: the 'color-scheme' property {#color-scheme
 			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>
+		: <dfn>light</dfn>
 		::
-			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=].
-
-			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''.)
-
-			''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.
+			Indicates that the page can handle the element being rendered
+			in a [=light color scheme=].
 
+		: <dfn>dark</dfn>
+		::
+			Indicates that the page can handle the element being rendered
+			in a [=dark color scheme=].
+
+		: <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.
-			To avoid confusion,
+
+			Note: To avoid confusion,
 			authoring tutorials and references
 			should omit <<custom-ident>> from their materials.
 
-			''color-scheme/normal'', ''light'', and ''dark'' are not valid <<custom-ident>>s in this property.
-
-			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.
+			The ''color-scheme/normal'', ''light'', and ''dark'' keywords
+			are not valid <<custom-ident>>s in this property.
 	</dl>
 
+	Note: [=Light=] and [=dark=] [=color schemes=]
+	are not specific color palettes.
+	For example,
+	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.
+
+	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''.)
+
+	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.
+
 	<div class=example>
 		A well-written page--
 		one that responds to user preferences for light or dark display
@@ -250,53 +241,55 @@ Opting Into a Preferred Color Scheme: the 'color-scheme' property {#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.
-
 	Note: [[HTML]] specifies a
 	<a href="https://html.spec.whatwg.org/multipage/semantics.html#meta-color-scheme">color-scheme</a>
 	<{meta}> tag which can be used to set the color-scheme on the root element as
 	a [[css-cascade-4#preshint|non-CSS presentational hint]].
 
-	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.
+	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.
 
 
 Effects of the Used Color Scheme {#color-scheme-effect}
 --------------------------------
 
 	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=].
+	the user agent must match the following to the [=used color scheme=]:
+
+	* the used value of the [[css-color-4#css-system-colors|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
 
 	On the root element,
-	rendering with a [=color scheme=] additionally must affect
+	the [=used color scheme=] additionally must affect
 	the surface color of the [=canvas=],
 	the initial value of the '/color' property,
-	and the used values of the [[css-color-4#css-system-colors|system colors]],
-	and should also affect the viewport's scrollbars.
+	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 used 'color-scheme' of the element
-	and the used 'color-scheme' of the embedded document’s root 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'
+	appropriate to the embedded document’s [=used 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).
 
+	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]].
+
 
 Forced Color Schemes {#forced}
 ====================