css(add): contrast-color() function page

files/en-us/_redirects.txt

@@ -12321,8 +12321,8 @@
 /en-US/docs/Web/CSS/clamp()	/en-US/docs/Web/CSS/clamp
 /en-US/docs/Web/CSS/color-adjust	/en-US/docs/Web/CSS/print-color-adjust
 /en-US/docs/Web/CSS/color_value/color()	/en-US/docs/Web/CSS/color_value/color
-/en-US/docs/Web/CSS/color_value/color-contrast	/en-US/docs/Web/CSS/color_value
-/en-US/docs/Web/CSS/color_value/color-contrast()	/en-US/docs/Web/CSS/color_value
+/en-US/docs/Web/CSS/color_value/color-contrast	/en-US/docs/Web/CSS/color_value/contrast-color
+/en-US/docs/Web/CSS/color_value/color-contrast()	/en-US/docs/Web/CSS/color_value/contrast-color
 /en-US/docs/Web/CSS/color_value/color-mix()	/en-US/docs/Web/CSS/color_value/color-mix
 /en-US/docs/Web/CSS/color_value/color_keywords	/en-US/docs/Web/CSS/named-color
 /en-US/docs/Web/CSS/color_value/device-cmyk()	/en-US/docs/Web/CSS/color_value/device-cmyk

files/en-us/web/css/color_value/contrast-color/index.md

@@ -0,0 +1,86 @@
+---
+title: contrast-color()
+slug: Web/CSS/color_value/contrast-color
+page-type: css-function
+status:
+  - experimental
+browser-compat: css.types.color.contrast-color
+---
+
+{{CSSRef}}{{SeeCompatTable}}
+
+The **`contrast-color()`** functional notation takes a {{cssxref("color_value","color")}} value and returns a [guaranteed](https://www.w3.org/TR/WCAG21/#contrast-minimum) contrasting color. The function makes it easy to specify text color when background colors are created dynamically. It saves developers from maintaining background-text color pairs. It is not limited to deriving text colors; you can use it for deriving colors of anything, such as border, background, etc.
+
+The function produces only `white` or `black` value, depending on which value produces maximum contrast with the input color. If both white and black colors produce the same contrast, then the `white` value is returned.
+
+> [!WARNING]
+> There is no guarantee that the resulting colors obtained using the `contrast-color()` function will always be accessible. For example, generally, mid-tone background colors don't result in enough contrast. It is recommended to use clearly-light or clearly-dark colors with the `contrast-color()` function.
+
+## Syntax
+
+```css
+color-contrast(red)
+color-contrast(var(--backgroundColor))
+```
+
+### Values
+
+- `color`
+  - : Any valid {{cssxref("<color>")}}.
+
+### Examples
+
+#### Contrasting text for a button
+
+```html hidden live-sample__button_text_ex
+<button>Submit</button>
+```
+
+```css live-sample__button_text_ex
+:root {
+  --button-color: lightblue;
+}
+
+button {
+  background-color: var(--button-color);
+
+  color: contrast-color(var(--button-color));
+}
+```
+
+```css hidden live-sample__button_text_ex
+@supports not (color: color-contrast(red)) {
+  body::before {
+    content: "Your browser doesn't support the color-contrast() function.";
+    background-color: wheat;
+    display: block;
+    width: 100%;
+    text-align: center;
+  }
+
+  body > * {
+    display: none;
+  }
+}
+```
+
+{{EmbedLiveSample("button_text_ex", "", 200)}}
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [How to have the browser pick a contrasting color in CSS](https://webkit.org/blog/16929/contrast-color/)
+- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
+- {{cssxref("color_value", "&lt;color>")}} data type
+- [WCAG: color contrast](/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Perceivable/Color_contrast)
+- [CSS colors](/en-US/docs/Web/CSS/CSS_colors) module
+- [`prefers-contrast`](/en-US/docs/Web/CSS/@media/prefers-contrast) and [`prefers-color-scheme`](/en-US/docs/Web/CSS/@media/prefers-color-scheme) {{cssxref("@media")}} features
+- [`contrast()`](/en-US/docs/Web/CSS/filter-function/contrast)
+- [CSS custom properties](/en-US/docs/Web/CSS/--*) and {{cssxref("var")}}

files/en-us/web/css/color_value/index.md

@@ -76,6 +76,7 @@ A `<color>` value can be specified using one of the methods listed below:
   - Other color spaces: {{CSSXref("color_value/color", "color()")}}.
 - By using [relative color](/en-US/docs/Web/CSS/CSS_colors/Relative_colors) syntax to output a new color based on an existing color. Any of the above color functions can take an **origin color** preceded by the `from` keyword and followed by definitions of the channel values for the new **output color**.
 - By mixing two colors: {{CSSXref("color_value/color-mix", "color-mix()")}}.
+- By selecting a color with maximum contrast: {{CSSXref("color_value/contrast-color", "contrast-color()")}}.
 - By specifying two colors, using the first for light color-schemes and the second for dark color-schemes: {{CSSXref("color_value/light-dark", "light-dark()")}}.
 
 ### `currentcolor` keyword

files/en-us/web/css/css_colors/index.md

@@ -47,6 +47,7 @@ To see the code for this color syntax converter, [view the source on GitHub](htt
   - [`oklch()`](/en-US/docs/Web/CSS/color_value/oklch)
   - [`color()`](/en-US/docs/Web/CSS/color_value/color)
 - [`color-mix()`](/en-US/docs/Web/CSS/color_value/color-mix)
+- [`contrast-color()`](/en-US/docs/Web/CSS/color_value/contrast-color)
 - {{CSSXref("color_value/light-dark", "light-dark()")}}
 
 > [!NOTE]

files/en-us/web/css/css_values_and_units/css_value_functions/index.md

@@ -202,6 +202,8 @@ The {{CSSxRef("color_value","<color>")}} CSS [data type](/en-US/docs/Web/C
   - : Specifies a particular, specified colorspace rather than the implicit sRGB colorspace.
 - {{CSSxRef("color_value/color-mix", "color-mix()")}}
   - : Mixes two color values in a given colorspace by a given amount.
+- {{CSSxRef("color_value/contrast-color", "contrast-color()")}}
+  - : Returns color with maximum color contrast for a given color.
 - {{CSSxRef("color_value/device-cmyk", "device-cmyk()")}}
   - : Defines CMYK colors in a device-dependent way.
 - {{CSSXref("color_value/light-dark", "light-dark()")}}