Skip to content

Commit

Permalink
[css-color-6] Make contrast-color() candidates optional
Browse files Browse the repository at this point in the history
Also move grammar above description of syntax, and some minor prose cleanup
  • Loading branch information
LeaVerou committed Oct 19, 2022
1 parent 36594e9 commit f5a104b
Showing 1 changed file with 28 additions and 15 deletions.
43 changes: 28 additions & 15 deletions css-color-6/Overview.bs
Original file line number Diff line number Diff line change
Expand Up @@ -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'',
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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">
Expand Down

0 comments on commit f5a104b

Please sign in to comment.