[css-color-4] Rewrite intro to non-deprecated system colors to center their use around forced-colors mode rather than generic use.

Author: tabatkins

css-color-4/Overview.bs

@@ -715,57 +715,85 @@ For historical reasons, this is also referred to as the X11 color set.
 <h3 id="css-system-colors">
 CSS System Colors</h3>
 
-	In addition to being able to assign color keyword values to text, backgrounds, etc.,
-	CSS defines a set of <dfn>&lt;system-color></dfn> values,
-	to allow authors to specify colors in a manner that integrate them into the user's graphic environment.
-
-	<<system-color>>s incur some privacy and security risk, as detailed in [[#priv-sec]].
-
-	For systems that do not have a corresponding value,
-	the specified value should be mapped to the nearest system color value,
-	or to a default color.
-	Note that some profiles of CSS may not support System Colors at all.
-
-	The following lists the additional values for color-related CSS values and their general meaning.
-	Any color property can take one of the following names.
-	These names are case-insensitive and shown here with mixed capitalization for legibility.
+	In [=forced colors mode=],
+	most colors on the page are forced into a restricted, user-chosen palette.
+	The <dfn>&lt;system-color></dfn> keywords
+	expose these user-chosen colors
+	so that the rest of the page can integrate with this restricted palette.
+
+	When the 'forced-colors' [=media feature=] is ''forced-colors/active'',
+	authors <em>should</em> use the <<system-color>> keywords as color values
+	in properties other than those listed in [[css-color-adjust-1#forced-colors-properties]],
+	to ensure legibility and consistency across the page
+	and avoid an uncoordinated mishmash of user-forced and page-chosen colors.
+
+	Authors <em>may</em> also use these keywords at any time,
+	but <em>should</em> be careful to use the colors
+	in <a href="#system-color-pairs">matching background-foreground pairs</a>
+	to ensure appropriate contrast,
+	as any particular contrast relationship across non-matching pairs
+	(e.g. ''Canvas'' and ''ButtonText'')
+	is not guaranteed.
+
+	The <<system-color>> keywords are defined as follows:
 
 	<dl id="system-color-values" data-dfn-type="value" dfn-for="<system-color>">
 		<dt><dfn>Canvas</dfn>
 		<dd>Background of application content or documents.
 		<dt><dfn>Text</dfn>
 		<dd>Text in application content or documents.
-
-		<dt><dfn>HighlightText</dfn>
-		<dd>Text of item(s) selected in a control.
-		<dt><dfn>Highlight</dfn>
-		<dd>Background of item(s) selected in a control.
-
 		<dt><dfn>LinkText</dfn>
 		<dd>Text in non-active, non-visited links.
 		<dt><dfn>VisitedText</dfn>
 		<dd>Text in visited links.
 		<dt><dfn>ActiveText</dfn>
 		<dd>Text in active links.
 
+		<dt><dfn>ButtonFace</dfn>
+		<dd>The face background color for push buttons.
+		<dt><dfn>ButtonText</dfn>
+		<dd>Text on push buttons.
+
 		<dt><dfn>Field</dfn>
 		<dd>Background of input fields.
 		<dt><dfn>FieldText</dfn>
 		<dd>Text in input fields.
 
-		<dt><dfn>ButtonFace</dfn>
-		<dd>The face background color for push buttons.
-		<dt><dfn>ButtonText</dfn>
-		<dd>Text on push buttons.
+		<dt><dfn>Highlight</dfn>
+		<dd>Background of item(s) selected in a control.
+		<dt><dfn>HighlightText</dfn>
+		<dd>Text of item(s) selected in a control.
 
 		<dt><dfn>GrayText</dfn>
-		<dd>Disabled text. (Often, but not necessarily, gray.)
+		<dd>Disabled text.
+			(Often, but not necessarily, gray.)
 	</dl>
 
+	Note: As with all other [=CSS/keywords=],
+	these names are case-insensitive.
+	They are shown here with mixed capitalization for legibility.
+
+	For systems that do not have a particular system UI concept,
+	the specified value should be mapped to
+	the most closely related system color value that exists.
+	The following pairings are expected to form legible background-foreground colors:
+
+	<ul id=system-color-pairs>
+		* ''Canvas'' background with ''Text'', ''LinkText'', ''VisitedText'', ''ActiveText'' foreground.
+		* ''ButtonFace'' background with ''ButtonText'' foreground.
+		* ''Field'' background with ''FieldText'' foreground.
+		* ''Highlight'' background with ''HighlightText'' foreground.
+	</ul>
+
+	Additionally, ''GrayText'' is expected to be readable,
+	though possibly at a lower contrast rating,
+	over any of the backgrounds.
+
 	Earlier versions of CSS defined additional <<system-color>>s,
 	which have since been deprecated.
 	These are documented in [[#deprecated-system-colors]].
 
+	Note: The <<system-color>>s incur some privacy and security risk, as detailed in [[#priv-sec]].
 
 <h3 id='transparent-color'>
 The ''transparent'' keyword</h3>

css-values-4/Overview.bs

@@ -489,7 +489,7 @@ Textual Data Types</h2>
 Pre-defined Keywords</h3>
 
 	In the value definition fields,
-	<dfn lt="keyword" export>keywords</dfn> with a pre-defined meaning appear literally.
+	<dfn lt="keyword" export for=CSS>keywords</dfn> with a pre-defined meaning appear literally.
 	Keywords are <a>CSS identifiers</a>
 	and are interpreted <a lt="ASCII case-insensitive">ASCII case-insensitively</a>
 	(i.e., [a-z] and \[A-Z] are equivalent).