add guide body for contrast-color by patrickkettner · Pull Request #966 · GoogleChrome/modern-web-guidance-src

patrickkettner · 2026-06-24T19:09:36Z

Follow-up to #753, which merged contrast-color as a stub (step 1: frontmatter + demo.html). This adds the full guide.md body.

Restores the guidance written earlier and incorporates the use cases @jamesnw suggested in the #753 review:

Derive readable hover/interaction states — change only the background custom property via relative color syntax and let contrast-color() re-derive the foreground (algorithmic hover states).
Build colors beyond black and white — feed the contrast-color() result into relative color syntax, with an explicit accessibility caveat that the contrast guarantee no longer holds once the value is transformed.

Use cases: optimal text color, custom-property theming, hover/interaction states, derived colors, plus fallback strategy.

Refs #687

jamesnw

This is looking good! I have a few suggestions, and I think the demo will need to be updated to more closely match the guide.

I think we should also add notes that caution against using contrast-color() over gradients, images, or backgrounds with transparency.

jamesnw · 2026-06-25T15:21:15Z

+
+# Ensure text readability with dynamic background colors
+
+When building reusable UI components (like badges or buttons) or supporting dynamic themes, ensuring text is readable against an unpredictable background color can be challenging. The `contrast-color()` CSS function automatically selects either black or white to maximize the contrast ratio against a specified background color.


Suggested change

When building reusable UI components (like badges or buttons) or supporting dynamic themes, ensuring text is readable against an unpredictable background color can be challenging. The `contrast-color()` CSS function automatically selects either black or white to maximize the contrast ratio against a specified background color.

When building reusable UI components (like badges or buttons) or supporting dynamic themes, ensuring text is readable against an unpredictable background color can be challenging. The `contrast-color()` CSS function resolves to `black` or `white`, maximizing the contrast ratio against the specified background color.

jamesnw · 2026-06-25T15:21:32Z

+
+This guide explains how to use `contrast-color()` to guarantee text legibility.


Suggested change

This guide explains how to use `contrast-color()` to guarantee text legibility.

I don't think this is needed.

jamesnw · 2026-06-25T15:22:29Z

+
+When an element has a variable or dynamically injected background color, you can rely on the browser to compute the safest text color.
+
+MANDATORY: You must define a fallback strategy for older browsers, such as using an `@supports` query with a `text-shadow` or variant-specific colors, because a single static fallback color will inevitably fail against some dynamic backgrounds.


I don't think we need to talk about fallbacks in the main section of the guide

jamesnw · 2026-06-25T15:23:21Z

+
+MANDATORY: You must define a fallback strategy for older browsers, such as using an `@supports` query with a `text-shadow` or variant-specific colors, because a single static fallback color will inevitably fail against some dynamic backgrounds.
+
+MANDATORY: Set the `color` property using the `contrast-color()` function, passing the effective background color (or its custom property) as the argument.


I'm not sure what's meant by "effective" here- I think it can be removed?

jamesnw · 2026-06-25T15:30:57Z

+}
+```
+
+DO: Use `contrast-color()` primarily when backgrounds are distinctly light or dark. Because the function currently only selects between black or white, mid-tone backgrounds (such as royal blue) may result in suboptimal contrast even when the mathematical maximum is chosen.


Rather than mid-tone, would it make sense to say lightness specifically?

jamesnw · 2026-06-25T15:35:05Z

+@supports (color: contrast-color(red)) {
+  .button:hover {
+    /* Darken the background; the text color re-derives on its own */
+    --button-bg: oklch(from #4f46e5 calc(l - 0.1) c h);


It might make sense to make this example actually flip the text from white to black- this should do it.

Suggested change

--button-bg: oklch(from #4f46e5 calc(l - 0.1) c h);

--button-bg: oklch(from #4f46e5 calc(1 - l) c h);

jamesnw · 2026-06-25T15:39:28Z

+
+## Fallback strategies
+
+{{ FEATURE_FALLBACKS("contrast-color") }}


Suggested change

{{ FEATURE_FALLBACKS("contrast-color") }}

{{ BASELINE_STATUS("contrast-color") }}

jamesnw · 2026-06-25T15:44:43Z

+
+{{ FEATURE_FALLBACKS("contrast-color") }}
+
+Due to its limited availability, `contrast-color()` must be applied using progressive enhancement. If the background color is known and fixed for a specific CSS class (like a `.badge-dark` variant), declaring a variant-specific safe default `color` immediately before the `contrast-color()` rule is sufficient, because browsers ignore CSS values they do not understand.


I don't think the prose needs to talk about availability.

Suggested change

Due to its limited availability, `contrast-color()` must be applied using progressive enhancement. If the background color is known and fixed for a specific CSS class (like a `.badge-dark` variant), declaring a variant-specific safe default `color` immediately before the `contrast-color()` rule is sufficient, because browsers ignore CSS values they do not understand.

For browsers that do not yet support `contrast-color()`, use it as a progressive enhancement. If the background color is known and fixed for a specific CSS class (like a `.badge-dark` variant), declare a variant-specific safe default `color` immediately before the `contrast-color()` rule.

jamesnw · 2026-06-25T15:47:02Z

+
+Due to its limited availability, `contrast-color()` must be applied using progressive enhancement. If the background color is known and fixed for a specific CSS class (like a `.badge-dark` variant), declaring a variant-specific safe default `color` immediately before the `contrast-color()` rule is sufficient, because browsers ignore CSS values they do not understand.
+
+However, if the background color is highly dynamic and unpredictable (such as user-injected themes), a single static fallback will inevitably fail. In these cases, you MUST use an `@supports` feature query to apply a robust fallback strategy, such as a text shadow or translucent background, to guarantee readability.


We could also mention using a library like ColorJS to compute a contrast color in JavaScript.

Another option would be using RCS, but that isn't widely available yet. Perhaps we don't need to mention that. https://lea.verou.me/blog/2024/contrast-color/#using-rcs-to-automatically-compute-a-contrasting-text-color

add guide body for contrast-color

e60a9bc

patrickkettner requested review from malchata, philipwalton and rviscomi as code owners June 24, 2026 19:09

patrickkettner mentioned this pull request Jun 24, 2026

add guidance for contrast-color #753

Merged

jamesnw requested changes Jun 25, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

add guide body for contrast-color#966

add guide body for contrast-color#966
patrickkettner wants to merge 1 commit into
mainfrom
contrast-color-guide

patrickkettner commented Jun 24, 2026

Uh oh!

jamesnw left a comment

Uh oh!

jamesnw Jun 25, 2026

Uh oh!

jamesnw Jun 25, 2026

Uh oh!

jamesnw Jun 25, 2026

Uh oh!

jamesnw Jun 25, 2026

Uh oh!

jamesnw Jun 25, 2026

Uh oh!

jamesnw Jun 25, 2026

Uh oh!

jamesnw Jun 25, 2026

Uh oh!

jamesnw Jun 25, 2026

Uh oh!

jamesnw Jun 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		# Ensure text readability with dynamic background colors

		When building reusable UI components (like badges or buttons) or supporting dynamic themes, ensuring text is readable against an unpredictable background color can be challenging. The `contrast-color()` CSS function automatically selects either black or white to maximize the contrast ratio against a specified background color.


		This guide explains how to use `contrast-color()` to guarantee text legibility.


		When an element has a variable or dynamically injected background color, you can rely on the browser to compute the safest text color.

		MANDATORY: You must define a fallback strategy for older browsers, such as using an `@supports` query with a `text-shadow` or variant-specific colors, because a single static fallback color will inevitably fail against some dynamic backgrounds.


		MANDATORY: You must define a fallback strategy for older browsers, such as using an `@supports` query with a `text-shadow` or variant-specific colors, because a single static fallback color will inevitably fail against some dynamic backgrounds.

		MANDATORY: Set the `color` property using the `contrast-color()` function, passing the effective background color (or its custom property) as the argument.

	--button-bg: oklch(from #4f46e5 calc(l - 0.1) c h);
	--button-bg: oklch(from #4f46e5 calc(1 - l) c h);


		## Fallback strategies

		{{ FEATURE_FALLBACKS("contrast-color") }}

	{{ FEATURE_FALLBACKS("contrast-color") }}
	{{ BASELINE_STATUS("contrast-color") }}


		{{ FEATURE_FALLBACKS("contrast-color") }}

		Due to its limited availability, `contrast-color()` must be applied using progressive enhancement. If the background color is known and fixed for a specific CSS class (like a `.badge-dark` variant), declaring a variant-specific safe default `color` immediately before the `contrast-color()` rule is sufficient, because browsers ignore CSS values they do not understand.

	Due to its limited availability, `contrast-color()` must be applied using progressive enhancement. If the background color is known and fixed for a specific CSS class (like a `.badge-dark` variant), declaring a variant-specific safe default `color` immediately before the `contrast-color()` rule is sufficient, because browsers ignore CSS values they do not understand.
	For browsers that do not yet support `contrast-color()`, use it as a progressive enhancement. If the background color is known and fixed for a specific CSS class (like a `.badge-dark` variant), declare a variant-specific safe default `color` immediately before the `contrast-color()` rule.


		Due to its limited availability, `contrast-color()` must be applied using progressive enhancement. If the background color is known and fixed for a specific CSS class (like a `.badge-dark` variant), declaring a variant-specific safe default `color` immediately before the `contrast-color()` rule is sufficient, because browsers ignore CSS values they do not understand.

		However, if the background color is highly dynamic and unpredictable (such as user-injected themes), a single static fallback will inevitably fail. In these cases, you MUST use an `@supports` feature query to apply a robust fallback strategy, such as a text shadow or translucent background, to guarantee readability.

Uh oh!

Conversation

patrickkettner commented Jun 24, 2026

Uh oh!

jamesnw left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants