[css-color-adjust-1] Define 'color scheme' and link throughout.

Author: fantasai

css-color-adjust-1/Overview.bs

@@ -36,52 +36,55 @@ Preferred Color Schemes {#preferred}
 =======================
 
 	Operating systems and user agents often give users
-	the ability to choose their preferred color schemes
+	the ability to choose their preferred <dfn>color schemes</dfn>
 	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.
 
-	Users on some systems can also indicate a preference
-	in the color scheme of the pages they view,
+	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).
+	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).
 
-	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 scheme.
-	<!-- See [[MEDIAQUERIES-5]]. -->
+	to the user's preferred [=color schemes=].
+	See [[MEDIAQUERIES-5]].
 
-	Additionally, if the author has indicated that the page can support this color scheme
+	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 user agent must match the following to the user's preferred [=color scheme=]:
 
-	* the initial color of the background canvas <span class=issue>find what we name this in other specs</span>,
+	* the initial color of the <a href="https://www.w3.org/TR/CSS2/intro.html#canvas">canvas</a>
+	    <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
 
-	User agents <em>may</em> support additional color schemes,
-	however CSS does not support negotiation of additional color schemes:
+	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,
+	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),
@@ -101,25 +104,25 @@ Opting Into a Preferred Color Scheme: the 'color-scheme' property {#color-scheme
 	</pre>
 
 	The 'color-scheme' property allows an element to indicate
-	which color schemes it is comfortable being rendered with.
+	which [=color schemes=] it is comfortable being rendered with.
 	These values are negotiated with the users preferences,
-	resulting in a chosen color scheme
+	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.
 	Its 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,
-			and so the element should be rendered with the browser's default 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>
-		:: Indicates that the element is aware of and can handle the listed color schemes,
+		:: 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.)
 
-			''light'' represents a "light" color scheme,
+			''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.
@@ -137,7 +140,7 @@ Opting Into a Preferred Color Scheme: the 'color-scheme' property {#color-scheme
 			must be explicitly added to this property’s grammar.
 			To avoid confusion,
 			authoring tutorials and references
-			should omit it from their materials.
+			should omit <<custom-ident>> from their materials.
 
 			''only'', ''color-scheme/normal'', ''light'', and ''dark'' are not valid <<custom-ident>>s in this property.
 
@@ -147,9 +150,9 @@ Opting Into a Preferred Color Scheme: the 'color-scheme' property {#color-scheme
 
 		: <dfn lt=only>only</dfn>
 		:: If provided,
-			''only'' indicates that the element <em>must</em> be rendered with one of the specified color schemes,
+			''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.
+			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.
@@ -159,21 +162,21 @@ Opting Into a Preferred Color Scheme: the 'color-scheme' property {#color-scheme
 			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
+			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.
 
-			Note that user agents are <strong>not required</strong>
-			to support any particular color scheme,
-			so using ''only'' to indicate a required color scheme
+			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>
 
 	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 be considered “Light” color schemes.
+	would both be considered “Light” color schemes.
 	To ensure particular foreground or background colors,
 	they need to be specified explicitly.
 
@@ -191,7 +194,7 @@ Finding the Used Color Scheme {#color-scheme-processing}
 
 		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'
+			and at least one [=color scheme=] indicated in 'color-scheme'
 			is supported by the user agent,
 			return the first keyword,
 			in specified order,
@@ -203,13 +206,13 @@ Finding the Used Color Scheme {#color-scheme-processing}
 	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.)
+	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,
+	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,
@@ -219,12 +222,12 @@ 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--
+	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.
+	to match with the intent of the [=color scheme=].
 
 	On the root element,
-	rendering with a color scheme additionally must affect the background of the canvas,
+	rendering with a [=color scheme=] additionally must affect the background 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.
@@ -245,7 +248,7 @@ Effects of the Used Color Scheme {#color-scheme-effect}
 The "color-scheme" <{meta}> value {#color-scheme-meta}
 ---------------------------------
 
-	To aid user agents in rendering the page background with the desired color scheme immediately
+	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.