[css-color-6] syntax to specify contrast algorithm for contrast-color(), following WG resolution

Closes #7356

Author: LeaVerou

css-color-6/Overview.bs

@@ -61,7 +61,8 @@ Computing a sufficiently contrasting color: the ''contrast-color()'' function {#
 	Its syntax is:
 
 	<pre class='prod'>
-		<dfn>contrast-color()</dfn> = contrast-color( <<color>> [ vs <<color>>#{2,} ]? [ to [<<number>> | AA | AA-large | AAA | AAA-large]]? )
+		<dfn>contrast-color()</dfn> = contrast-color( <<color>> [ vs <<color>>#{2,} ]? [ to <<target-contrast>>]? )
+		<dfn><<target-contrast>></dfn> = wcag2([<<number>> | [ aa | aaa ] && large? ])
 	</pre>
 
 	The only mandatory argument is the first color, which is the color to be contrasted,
@@ -85,12 +86,14 @@ Computing a sufficiently contrasting color: the ''contrast-color()'' function {#
 	and the target contrast, if present, is separated from the list
 	with the keyword <css>to</css>.
 
+	The target contrast is specified by providing a function for the algorithm used
+	(currently only [WCAG 2.1](#luminance-contrast) is supported )
+	with the contrast ratio as the argument.
 
-
-	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'',
-	 <dfn value for="contrast-color()">AAA</dfn> is equivalent to ''7'', and
-	 <dfn value for="contrast-color()">AAA-large</dfn> is equivalent to ''4.5'' .
+	For ''wcag2()'', ''aa'' is equivalent to ''4.5'',
+	''aa large'' (or ''large aa'') is equivalent to ''3'',
+	''aaa'' is equivalent to ''7'',
+	and ''aaa large'' (or ''large aaa'') is equivalent to ''4.5''.
 
 <h3 id="luminance-contrast">
 	Calculating luminance and WCAG 2.1 contrast
@@ -160,7 +163,7 @@ Computing a sufficiently contrasting color: the ''contrast-color()'' function {#
 		https://colorjs.io/notebook/?storage=https%3A%2F%2Fgist.github.com%2Fsvgeesus%2Fec249f376fcecbaa8794f75dbfc1dacf
 	-->
 	<div class="example">
-		<pre class="lang-css">contrast-color(wheat vs bisque, darkgoldenrod, olive, sienna, darkgreen, maroon to AA)</pre>
+		<pre class="lang-css">contrast-color(wheat vs bisque, darkgoldenrod, olive, sienna, darkgreen, maroon to wcag2(aa))</pre>
 
 		The calculation is as follows:
 			* <span class="swatch" style="--color: wheat"></span> wheat (#f5deb3), the background, has relative luminance 0.749
@@ -177,7 +180,7 @@ Computing a sufficiently contrasting color: the ''contrast-color()'' function {#
 	</div>
 
 	<div class="example">
-		<pre class="lang-css">contrast-color(wheat vs bisque, darkgoldenrod, olive, sienna, darkgreen, maroon to 5.8)</pre>
+		<pre class="lang-css">contrast-color(wheat vs bisque, darkgoldenrod, olive, sienna, darkgreen, maroon to wcag2(5.8))</pre>
 
 		The calculation is as follows:
 			* the relative luminances and contrast ratios are the same as the previous example.
@@ -205,7 +208,7 @@ Computing a sufficiently contrasting color: the ''contrast-color()'' function {#
 	whichever has the higher contrast.
 
 	<div class="example">
-		<pre class="lang-css">contrast-color(wheat vs bisque, darkgoldenrod, olive to AA)</pre>
+		<pre class="lang-css">contrast-color(wheat vs bisque, darkgoldenrod, olive to wcag2(AA))</pre>
 
 		The calculation is as follows:
 			* the relative luminances and contrast ratios are the same as the previous example.
@@ -268,7 +271,7 @@ Computing a sufficiently contrasting color: the ''contrast-color()'' function {#
 			For example, given the value
 
 			<pre class="lang-css">
-				contrast-color(rgb(179 213 230) vs cadetblue, hsl(200 83% 23%) to AA)
+				contrast-color(rgb(179 213 230) vs cadetblue, hsl(200 83% 23%) to wcag2(AA))
 			</pre>
 
 			the contrast with cadetblue is <strong>1.97</strong>
@@ -289,13 +292,13 @@ Computing a sufficiently contrasting color: the ''contrast-color()'' function {#
 			the value
 
 			<pre class="lang-css">
-				contrast-color(currentColor vs hsl(200 83% 23%), purple to AA)
+				contrast-color(currentColor vs hsl(200 83% 23%), purple to wcag2(AA))
 			</pre>
 
 			has the computed value
 
 			<pre class="lang-css">
-				contrast-color(currentColor vs rgb(10 75 107), rgb(128 0 128) to 4.5)
+				contrast-color(currentColor vs rgb(10 75 107), rgb(128 0 128) to wcag2(4.5))
 			</pre>
 
 		</div>