Color scheme

The contrast-color() Function

Imagine you are building a set of buttons whose background colors come from a design token, a CMS field, or a user preference. For each background, you need to decide whether the text should be black or white. Until recently, that decision required a second custom property, a preprocessor function, or JavaScript. The contrast-color() function hands that job to the browser. You give it a background color, and it returns whichever of black or white provides the higher contrast. One line of CSS replaces an entire set of paired text and background variables.

As of April 2026, contrast-color() is supported in Chrome, Firefox, Safari, and Edge. It is a real, production-ready feature, but it comes with meaningful limitations that you need to understand before you rely on it. This page covers how the function works, where it shines, where it falls short, and how to combine it with other modern color tools to get better results.

How It Works

The syntax is intentionally simple. You pass a single color value and the function returns either black or white:


        .card {
            --bg: var(--brand-color);
            background-color: var(--bg);
            color: contrast-color(var(--bg));
        }
    

Under the hood, the browser calculates the WCAG 2 contrast ratio of both white and black against your input color. Whichever one produces the higher ratio wins. If the two ratios tie (a perfectly mid-gray, for example), white is returned as the default. The function accepts any valid <color> value: named colors, hex, rgb(), hsl(), oklch(), custom properties, or even the output of color-mix().


        /* All of these work */
        color: contrast-color(darkblue);
        color: contrast-color(#ff6b35);
        color: contrast-color(oklch(0.6 0.15 250));
        color: contrast-color(var(--surface));
        color: contrast-color(color-mix(in oklch, var(--seed) 50%, white));
    
Name Change

Earlier drafts of the specification used the name color-contrast() with a different, more complex syntax that accepted a list of candidate colors and a vs keyword. That version was never shipped to stable browsers. The current function is called contrast-color(), takes a single argument, and returns only black or white. The fuller version with candidate lists remains in CSS Color Level 6, where it is still being designed.

Why It Matters for Accessibility

The Web Content Accessibility Guidelines (WCAG) require a minimum contrast ratio of 4.5:1 between normal-sized text and its background, and 3:1 for large text (18px bold or 24px regular). Maintaining these ratios across every component, state, and theme in a design system is tedious and error-prone. Developers frequently get it wrong, especially on hover states, disabled states, and dark mode variants where background colors shift dynamically.

contrast-color() does not guarantee that the result will meet the 4.5:1 threshold in every case. What it guarantees is that the browser will pick whichever of black or white has more contrast with your background. For backgrounds that are clearly light or clearly dark, this produces excellent results. The trouble appears in the middle of the lightness range, where neither black nor white provides strong contrast. That is the honest limitation you need to understand.

The Mid-Tone Problem

Consider a medium blue like #317CFF. When you run it through the WCAG 2 algorithm, black scores a contrast ratio of about 5.45:1 and white scores about 3.84:1. Mathematically, black wins. But when you actually look at black text on that blue background, it is harder to read than white text. The WCAG 2 formula calculates luminance contrast using a simple mathematical ratio that does not account for how human vision perceives lightness differently across hues. This discrepancy has been widely criticized, and a newer algorithm called APCA (Accessible Perceptual Contrast Algorithm) is being developed for WCAG 3 to address exactly this problem.

The CSS specification acknowledges this weakness. It states that browsers "may use different and better algorithms" in the future, and the APCA is a leading candidate. For now, the practical advice is straightforward: contrast-color() works reliably on backgrounds that are clearly light or clearly dark. For mid-tone backgrounds (roughly 40% to 60% lightness in oklch), you should still test the result manually and consider overriding it with a known accessible pairing when the output looks wrong.

Do Not Assume Compliance

contrast-color() is a convenience tool, not a compliance guarantee. It picks the better of two options, but "better" does not always mean "good enough." Always verify contrast ratios with a dedicated checker like WebAIM's Contrast Checker for any color pairing that lives near the mid-tone range.

Practical Patterns

Themed Buttons

The most common use case is a set of buttons or badges whose backgrounds are driven by custom properties. Instead of maintaining a paired text color for each variant, let the browser decide:


        .button {
            background-color: var(--btn-bg);
            color: contrast-color(var(--btn-bg));
        }

        .button--primary   { --btn-bg: var(--color-primary); }
        .button--secondary { --btn-bg: var(--color-secondary); }
        .button--danger    { --btn-bg: var(--color-danger); }
    

Add a new color variant and the text color handles itself. No second variable needed.

Dynamic Hover States

When you lighten or darken a background on hover, the text color may need to flip. contrast-color() handles this automatically:


        .card {
            --bg: oklch(0.6 0.15 250);
            background: var(--bg);
            color: contrast-color(var(--bg));
        }

        .card:hover {
            --bg: color-mix(in oklch, oklch(0.6 0.15 250) 40%, white);
        }
    

The hover lightens the background significantly. If it crosses the threshold where white text would become harder to read than black, the function flips automatically.

Dark Mode Without Paired Variables

Combined with light-dark() and color-scheme, you can define a single background token and let contrast-color() handle text in both modes:


        :root {
            color-scheme: light dark;
            --surface: light-dark(#f4f6f8, #1e1e2e);
        }

        body {
            background-color: var(--surface);
            color: contrast-color(var(--surface));
        }
    

This eliminates the need for a separate --text token entirely, at least for the primary surface. For more nuanced text colors (muted labels, secondary headings), you will still want dedicated tokens.

Feature Detection

Even though browser support is strong, wrapping contrast-color() in an @supports block is good practice when you need a safe fallback for older browsers or embedded webviews:


        .badge {
            background-color: var(--badge-bg);
            color: #ffffff; /* fallback */
        }

        @supports (color: contrast-color(red)) {
            .badge {
                color: contrast-color(var(--badge-bg));
            }
        }
    

Live Demo

Pick a background color with the color input below and watch contrast-color() decide whether the text should be black or white. Pay attention to mid-tone colors where the result may look questionable. Use the theme toggle to see how the demo container responds in both light and dark mode:

#6633cc
Color scheme
Your browser does not support contrast-color(). Try Chrome 133+, Firefox 146+, or Safari 18.4+.
Text Tint (lighter)
Text Base color
Text Shade (darker)

Limitations to Be Honest About

contrast-color() is a powerful convenience, but honesty about its boundaries is important, especially when teaching others about it. Here is what it cannot do today:

  • It only returns black or white. You cannot get a dark navy or a soft cream. If your design system needs branded text colors, you will still need to define them yourself.
  • It does not account for font size or weight. WCAG allows a lower contrast ratio (3:1) for large text, but the function always targets the 4.5:1 normal-text threshold.
  • It uses the WCAG 2 luminance algorithm, which is known to produce poor results on mid-tone backgrounds and saturated blues. The APCA algorithm addresses these issues but is not yet part of the specification.
  • It operates on computed color values, not rendered ones. If an element has background: transparent, the function calculates against invisible black (rgba 0,0,0,0), not the actual color showing through from a parent element.
  • It does not work with gradients or background images. If your background is a gradient that shifts from light to dark, the function cannot evaluate the portion behind each piece of text.

None of these limitations make the function useless. They mean you should treat it as one tool in your accessibility toolkit rather than a complete solution. Pair it with manual contrast checks on mid-tones, use relative color syntax or color-mix() when you need text colors beyond black and white, and always test your final output with real users and real assistive technology.

Resources

Teaching Video Checklist

When you record your teaching video, make sure your teammates come away understanding these concepts:

  • What contrast-color() does and what it returns (only black or white, whichever has higher WCAG 2 contrast)
  • How to use it with custom properties so that text color updates automatically when the background changes
  • The mid-tone problem: why the function can produce visually poor results on backgrounds in the 40% to 60% lightness range, and why the WCAG 2 algorithm is responsible
  • How to use @supports to provide a fallback for browsers that do not support the function
  • The honest limitations: no custom output colors, no font-size awareness, no gradient support, and the transparent background gotcha

Show a live demo in your video. Build a set of colored cards or buttons that use contrast-color() for their text. Include at least one mid-tone background that demonstrates where the function struggles, and explain why. Your teammates should leave your video knowing both when to use this tool and when not to trust it blindly.