CSS oklch: tune a surface color without guessing contrast

When to use it

A payment exception panel needs a restrained blue surface behind dark text. Start with a tested hex fallback, then place an oklch surface behind it when the function is supported. Keep the foreground explicit in both cases. The numerical lightness is a design input, not a contrast ratio: font weight, text size, alpha, backdrop, and display processing still determine readability. Compare normal text, links, focus rings, disabled controls, and dark-mode versions after the actual colors are computed. If the panel can sit over an image or translucent surface, test that composite rather than the flat token alone. Avoid generating an entire warning system by adding the same chroma amount to arbitrary hues; some requested colors fall outside the target display gamut and can map differently. Keep status wording in HTML so palette variation never removes meaning.

.payment-exception { color: #163746; background: #eaf3f6; }
@supports (background: oklch(95% .025 220)) { .payment-exception { background: oklch(95% .025 220); } }

Cost and verification

Color calculation has little performance cost. Validation cost grows with the number of themes, overlays, and component states that share the token. Check the computed color in the target browsers and run contrast measurements on the final pair; an oklch lightness percentage is not a WCAG score. Gamut mapping can alter high-chroma colors, so prefer restrained values for broad UI surfaces and review P3 and sRGB output separately. The hex fallback must remain acceptable on its own. A color surface can aid grouping, but it must not be the only error signal, especially in forced colors or monochrome print.

Common Mistakes

• Do not read oklch lightness as a text contrast score.
• Do not assume a requested high-chroma color is rendered identically on every display.
• Do not remove the tested fallback or textual status.

Connected lessons

• CSS Property Decisions
• CSS color and contrast: pair text with its real surface
• CSS color-mix: derive a surface without assuming contrast
• CSS color-gamut: add a wide-color accent behind an sRGB base