From f5a104b8078183bcd09ba866231ea31766f1fe50 Mon Sep 17 00:00:00 2001
From: Lea Verou <lea@verou.me>
Date: Wed, 19 Oct 2022 15:47:16 -0400
Subject: [PATCH] [css-color-6] Make contrast-color() candidates optional

Also move grammar above description of syntax, and some minor prose cleanup
---
 css-color-6/Overview.bs | 43 +++++++++++++++++++++++++++--------------
 1 file changed, 28 insertions(+), 15 deletions(-)

diff --git a/css-color-6/Overview.bs b/css-color-6/Overview.bs
index b4ed93769b5..136f58d4cc7 100644
--- a/css-color-6/Overview.bs
+++ b/css-color-6/Overview.bs
@@ -52,27 +52,40 @@ Introduction {#intro}
 	https://caniuse.com/mdn-css_types_color_color-contrast
 -->
 
-Selecting the most contrasting color: the ''contrast-color()'' function {#colorcontrast}
+Computing a sufficiently contrasting color: the ''contrast-color()'' function {#colorcontrast}
 ========================================================================================
 
-	This function takes, firstly, a single color
-	(typically a background, but not necessarily),
-	secondly, a list of two or more colors,
-	and thirdly, an optional target <a href="https://www.w3.org/TR/WCAG21/#contrast-minimum">luminance contrast</a> [[!WCAG21]].
+	The purpose of this function is to generate sufficiently contrasting colors from other colors,
+	without authors having to compute them manually.
 
-	It <a href="#winner">returns</a> the first color in the list
-	to meet or exceed the specified target contrast
-	or, if no target is given,
-	the color in the list with the greatest contrast.
+	Its syntax is:
+
+	<pre class='prod'>
+		<dfn>contrast-color()</dfn> = contrast-color( <<color>> [ vs <<color>>#{2,} ]? [ to [<<number>> | AA | AA-large | AAA | AAA-large]]? )
+	</pre>
+
+	The only mandatory argument is the first color, which is the color to be contrasted,
+	typically (but not necessarily) a background color.
+
+	An optional list of color candidates is provided after a ''vs'' keyword.
+	If no candidates are provided, the default candidates are used: ''white, black''.
+
+	An optional target <a href="https://www.w3.org/TR/WCAG21/#contrast-minimum">luminance contrast</a> [[!WCAG21]]
+	is provided after a ''contrast-color()/to'' keyword.
+
+	If a target contrast is specified,
+	the <a href="#winner">returned color</a> is the first color candidate that meets or exceeds the target contrast.
+	If no target is given,
+	the color candidate with the greatest contrast is returned.
+	If multiple candidates have the same contrast,
+	the one that comes earliest in the list is returned.
 
 	The single color is separated from the list
 	with the keyword <css>vs</css>
 	and the target contrast, if present, is separated from the list
 	with the keyword <css>to</css>.
 
-	<pre class='prod'>
-		<dfn>contrast-color()</dfn> = contrast-color( <<color>> vs <<color>>#{2,}  [ to [<<number>> | AA | AA-large | AAA | AAA-large]]? )
-	</pre>
+
 
 	The keyword <dfn value for="contrast-color()">AA</dfn> is equivalent to ''4.5'',
 	 <dfn value for="contrast-color()">AA-large</dfn> is equivalent to ''3'',
@@ -173,10 +186,10 @@ Selecting the most contrasting color: the ''contrast-color()'' function {#colorc
 
 	</div>
 
-	The colors in the list (after the keyword vs) are tested sequentially,
+	The candidate colors are tested sequentially,
 	from left to right;
 	a color is the temporary winner
-	if it has  the highest contrast of all those tested so far.
+	if it has the highest contrast of all those tested so far.
 
 	List traversal is terminated once the target contrast has been met or exceeded.
 
@@ -260,7 +273,7 @@ Selecting the most contrasting color: the ''contrast-color()'' function {#colorc
 
 			the contrast with cadetblue is <strong>1.97</strong>
 			while the contrast with hsl(200 83% 23%) is <strong>6.09</strong>
-			which exceeds 4.5, the value for 'AA';
+			which exceeds 4.5, the value for ''AA'';
 			so it has the computed value of the resolved hsl function:
 
 			<pre class="lang-css">