v147 · CSS

contrast-color()

A CSS color function that automatically returns black or white — whichever has higher contrast against a given background — so dynamic color themes never produce unreadable text.

concepts

  1. Hue Explorer

    Drag HSL sliders to sculpt any color. Watch text flip between black and white in real time, driven entirely by contrast-color() — no JavaScript logic, just CSS.

  2. Theme Generator

    Pick one brand color and see a full UI kit — header, card, button, badge — render with automatically contrasting text across every component, all from a single CSS custom property.

  3. Palette Grid

    A 10 × 10 hue-lightness grid: 100 swatches, each showing contrast-color() in action. Hover any cell to see the exact contrast ratio and which color was chosen.

  4. Tag Cloud

    A tag cloud of programming languages where each tag gets a random background color — the text auto-picks black or white via contrast-color(var(--tag-bg)). Shuffle the palette, add custom tags with any color, and inspect the contrast ratios in the accessibility grid.

  5. Compatibility Lab

    Probes contrast-color() with different argument forms via CSS.supports(). Shows a 12-swatch grid using native contrast-color() when available and a JavaScript WCAG luminance calculation as the fallback. Provides the exact @supports guard and a portable contrastColor(hex) helper function.

why it shipped

Dynamic color themes — user-chosen accents, system dark mode, design tokens pulled from a CMS — mean a background color is often not known at author time. Developers have historically approximated readable text by computing luminance in JavaScript, using clunky filter: invert() tricks, or shipping only pre-vetted palette combinations. contrast-color() moves that decision into the browser's color engine where it belongs: one declaration, zero JavaScript, zero maintenance. As browsers adopt the full CSS Color Level 5 spec, the function is expected to grow to support any two colors (not just black and white), but this binary form already solves the majority of real-world contrast problems.

references

implementation reference

Need the exact API surface, compatibility boundaries, errors, lifecycle, and source links? Read the matching gendn reference ↗