[css-color-5] add target contrast ratio, fix w3c#4749

Author: svgeesus

css-color-5/Overview.bs

@@ -132,7 +132,8 @@ Mixing colors: the ''color-mix()'' function {#color-mix}
 	4. Otherwise, if <var>p1</var> is omitted, it becomes 100% - <var>p2</var>
 	5. If the percentages sum to zero <em>do something, tbd</em>
 	6. Otherwise, if both are provided but do not add up to 100%,
-	they are scaled accordingly so that they add up to 100%.
+			they are scaled accordingly so that they add up to 100%.
+
 	This means that
 	<var>p1</var> becomes <var>p1</var> / (<var>p1</var> + <var>p2</var>)
 	and
@@ -143,10 +144,11 @@ Issue: Should we handle p1 + p2 &lt; 100% differently? E.g. a mix with `transpar
 After normalizing both percentages, the result is produced via the following algorithm:
 
 1. Both colors are converted to the specified [=colorspace=].
-If the specified colorspace has a smaller gamut
-than the one in which the color to be adjusted is specified,
-gamut mapping will occur.
-2. Colors are then <a href="../css-color-4/#interpolation">interpolated in the specified colorspace</a>.
+	If the specified colorspace has a smaller gamut
+	than the one in which the color to be adjusted is specified,
+	gamut mapping will occur.
+2. Colors are then <a href="../css-color-4/#interpolation">interpolated in the 		specified colorspace</a>.
+
 The result of mixing is the color at the specified percentage along the progression
 of the second color to the first color.
 
@@ -462,17 +464,23 @@ Selecting the most contrasting color: the ''color-contrast()'' function {#colorc
 
 	This function takes, firstly, a single color
 	(typically a background, but not necessarily),
-	and then second, a list of two or more colors;
-	it selects from that list
-	the color with highest <a href="https://www.w3.org/TR/WCAG21/#contrast-minimum">luminance contrast</a> [[!WCAG21]]
+	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]].
+	It selects from that list
+	the first color color to meet or exceed the target contrast.
+	If no target is specified,
+	it selects the first color with the highest contrast
 	to the single color.
 
+	The single color is separated from the list
+	with the keyword 'vs'
+	and the target contrast, if present, is separated from the list
+	with the keyword 'to'.
+
 	<pre class='prod'>
-		<dfn>color-contrast()</dfn> = color-contrast( <<color>> vs <<color>>#{2,}  )
+		<dfn>color-contrast()</dfn> = color-contrast( <<color>> vs <<color>>#{2,}  ( to [<<number>> | AA | AA-large])? )
 	</pre>
 
-	Issue(#4749): <a href="https://github.com/w3c/csswg-drafts/issues/4749">add target contrast ratio to color-contrast?</a>
-
 	<div class="example">
 		<pre class="lang-css">color-contrast(wheat vs tan, sienna, var(--myAccent), #d2691e)</pre>
 
@@ -488,15 +496,69 @@ Selecting the most contrasting color: the ''color-contrast()'' function {#colorc
 
 	</div>
 
+	The keyword 'AA' is equivalent to 4.5, and the keyword 'AA-large' is equivalent to 3.
+
+	<!-- live example
+		https://colorjs.io/notebook/?storage=https%3A%2F%2Fgist.github.com%2Fsvgeesus%2Fec249f376fcecbaa8794f75dbfc1dacf
+	-->
+	<div class="example">
+		<pre class="lang-css">color-contrast(wheat vs bisque, darkgoldenrod, olive, sienna, darkgreen, maroon to AA)</pre>
+
+		The calculation is as follows:
+			* <span class="swatch" style="--color: wheat"></span> wheat (#f5deb3), the background, has relative luminance 0.749
+			* <span class="swatch" style="--color: bisque"></span> bisque (#ffe4c4) has relative luminance 0.807 and contrast ratio <strong>1.073</strong>
+			* <span class="swatch" style="--color: darkgoldenrod"></span> darkgoldenrod (#b8860b) has relative luminance 0.273 and contrast ratio <strong>2.477</strong>
+			* <span class="swatch" style="--color: olive"></span> olive (#808000 ) has relative luminance 0.200 and contrast ratio <strong>3.193</strong>
+			* <span class="swatch" style="--color: sienna"></span> sienna (#a0522d) has relative luminance 0.137 and contrast ratio <strong>4.274</strong>
+			* <span class="swatch" style="--color: darkgreen"></span> darkgreen (#006400 ) has relative luminance 0.091 and contrast ratio <strong>5.662</strong>
+			* <span class="swatch" style="--color: maroon"></span> maroon (#800000 ) has relative luminance 0.046 and contrast ratio <strong>8.333</strong>
+
+
+		The first color in the list which meets the desired contrast ratio of 4.5 is <span class="swatch" style="--color: darkgreen"></span> darkgreen.
+
+	</div>
+
+	<div class="example">
+		<pre class="lang-css">color-contrast(wheat vs bisque, darkgoldenrod, olive, sienna, darkgreen, maroon to 5.8)</pre>
+
+		The calculation is as follows:
+			* the relative luminances and contrast ratios are the same as the previous example.
+
+		The first color in the list which meets the desired contrast ratio of 5.8 is <span class="swatch" style="--color: maroon"></span> maroon.
+
+	</div>
+
 	The colors in the list (after the keyword vs) 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,
-	and once the end of the list is reached, the current temporary winner is the overall winner.
+	if it has  the highest contrast of all those tested so far.
+
+	List traversal is terminated once the target contrast has been meet or exceeded.
+
+	Once the end of the list is reached, if there is no target contrast,
+	the current temporary winner is the overall winner.
 	Thus, if two colors in the list happen to have the same contrast,
 	the earlier in the list wins
 	because the later one has the same contrast, not higher.
 
+	If there is a target contrast,
+	and the end of the list is reached without meeting that target,
+	either 'white' or 'black' is returned,
+	whichever has the higher contrast.
+
+	<div class="example">
+		<pre class="lang-css">color-contrast(wheat vs bisque, darkgoldenrod, olive to AA)</pre>
+
+		The calculation is as follows:
+			* the relative luminances and contrast ratios are the same as the previous example.
+
+		No color in the list meets the desired contrast ratio of 4.5,
+		so <span class="swatch" style="--color: black"></span> black
+		is returned as the contrast (15.982)
+		is higher than that of white (1.314).
+
+	</div>
+
 	<div class="example">
 		<pre class="lang-css">
 			foo {