Book a call

WritingFoundations & tokensPart 3 of 4 in Foundations in depth

Colour contrast in design systems: WCAG ratios and pairing rules

Contrast is decided once in a design system and inherited everywhere, which makes it the cheapest place to get accessibility right. The WCAG ratios that matter, why you check pairs and not colours, and simple pairing rules that hold across a palette.

On this pageWhy contrast belongs in the design system
  1. Why contrast belongs in the design system
  2. The WCAG ratios that matter
  3. Check pairs, not colours
  4. A contrast matrix for your palette
  5. How to build contrast into the system
  6. Beyond the ratio: colour and meaning
  7. The short version
  8. Frequently asked questions
  9. Further reading

The short answer

Build contrast into a design system once, at the token level, and every product inherits it. Use the WCAG 2.2 minimums: 4.5:1 for body text, 3:1 for large text and for meaningful non-text elements like input borders, icons and focus rings. Check pairs, not colours (a colour is only accessible against what it sits on), in every theme. With a palette built on a shared lightness curve, simple rules emerge: in ours, any two steps six apart pass for body text, with one exception at the very light end.

  • Low-contrast text is the most common accessibility failure on the web.
  • Publish the approved pairs and test them automatically on every token change.
  • Give the accessibility owner a real veto over token value changes.

Why contrast belongs in the design system

WebAIM's 2025 scan of the world's top million home pages found low-contrast text on 79.1% of them. Measured It's the most common accessibility failure on the web, and almost always the result of colours chosen one screen at a time.

A design system changes the economics. Decide the text and background pairs once, as tokens, check them once, and every component and product built on them inherits the result. Fix a failing pair in the system and the fix reaches every screen in a release. That's why contrast is the cheapest place in the whole product to get accessibility right.

The WCAG ratios that matter

WhatMinimum (AA)WCAG 2.2Examples
Body text4.5:11.4.3Paragraphs, labels, table cells, helper text, button labels
Large text3:11.4.324px and above, or about 18.66px and above in bold
Non-text elements3:11.4.11Input borders, checkbox outlines, icons that carry meaning, focus indicators, chart lines
Enhanced (AAA)7:11.4.6Optional; worth it for long-form reading and data-dense views
Disabled controls, decorationnoneexemptDisabled buttons, purely decorative dividers and illustrations
WCAG 2.2 contrast requirements. Many laws and procurement rules, including the European Accessibility Act, point to level AA.
Watch out

"Exempt" isn't the same as "fine". Disabled text that nobody can read still confuses people. Keep disabled states legible, and explain nearby why an action isn't available.

Check pairs, not colours

A colour has no contrast on its own. neutral.600 is 4.57:1 on white but only 4.25:1 on neutral.50, our light canvas: it passes on one background and fails on the other. So the unit you check, document and test is the pair: a foreground token on a background token, in a specific theme.

That's another reason for semantic tokens. When colours are named by job (text.secondary on bg.canvas), the pairs that matter are finite and nameable, and you can check every one in every theme:

UsePairNeedsLightDark
Body texttext.primary on bg.canvas4.5:114.67:1 Pass14.67:1 Pass
Secondary texttext.secondary on bg.canvas4.5:15.99:1 Pass8.89:1 Pass
Linkstext.link on bg.canvas4.5:16.05:1 Pass8.76:1 Pass
Primary button labelaction.primary.text on action.primary.bg4.5:16.44:1 Pass6.09:1 Pass
Error messagefeedback.danger.text on feedback.danger.bg4.5:15.74:1 Pass6.68:1 Pass
Success messagefeedback.success.text on feedback.success.bg4.5:15.02:1 Pass6.81:1 Pass
Input border (non-text)border.strong on bg.canvas3:13.07:1 Pass4.77:1 Pass
Focus ring (non-text)focus.ring on bg.canvas3:14.28:1 Pass6.51:1 Pass
Disabled text (exempt)text.disabled on bg.canvasexempt2.23:1 3.45:1
Every pairing that matters, checked in both modes against WCAG 2.2: 4.5:1 for text (1.4.3) and 3:1 for borders and focus rings (1.4.11). Disabled text is exempt under WCAG, but we still keep it readable.

A contrast matrix for your palette

If your palette is built on one shared lightness curve, as an OKLCH palette can be, contrast becomes predictable. Here's every pairing of the eleven neutral steps:

Text ↓ · Bg →50100200300400500600700800900950
50–1.11.31.62.23.14.26.08.411.314.7
1001.1–1.21.52.02.83.95.57.710.313.4
2001.31.2–1.31.72.33.24.66.48.611.2
3001.61.51.3–1.41.92.63.65.16.98.9
4002.22.01.71.4–1.41.92.73.85.16.6
5003.12.82.31.91.4–1.41.92.83.74.8
6004.23.93.22.61.91.4–1.42.02.73.5
7006.05.54.63.62.71.91.4–1.41.92.5
8008.47.76.45.13.82.82.01.4–1.31.7
90011.310.38.66.95.13.72.71.91.3–1.3
95014.713.411.28.96.64.83.52.51.71.3–

4.5:1 or more · any text3:1 to 4.5:1 · large text, borders, iconsbelow 3:1 · decoration only

Every pairing of the eleven neutral steps, computed. Read across from a text colour to a background. Because the lightness curve is shared, the pattern carries over to every hue: steps six or more apart pass 4.5:1 for body text (except next to step 50, which needs 700), and steps five or more apart always pass 3:1 for large text and borders.

From a matrix like this you can write pairing rules anyone can apply without a checker:

  1. Body text: six steps apart

    Steps six or more apart pass 4.5:1, except next to the lightest step: on 50, text needs 700 or darker.

  2. Large text and borders: five steps apart

    Steps five or more apart always pass 3:1, which covers large headings, input borders, icons and focus rings.

  3. Same rule, every hue

    Because every ramp shares the lightness curve, step 700 is between 5.8:1 and 7.1:1 on white in every colour family we built. Brand, blue, red and green follow the same rule.

How to build contrast into the system

  • Pick text tokens that pass on every background they're allowed on, in every theme.
  • Publish the approved pairs on the token documentation page, with their ratios.
  • Test automatically: a script that computes every documented pair and fails the build if one drops below its minimum.
  • Check states: hover, pressed, focus and selected colours are pairs too.
  • Lint for raw colours in product code, so nobody bypasses the checked tokens.
  • Give accessibility a veto over token value changes in your decision-rights matrix.

An illustration: fixing secondary text everywhere at once

The situation

An audit finds secondary text (captions, helper text, timestamps) at 4.25:1 on the default background: just below 4.5:1, in every product.

Without a system

Hundreds of hard-coded greys across several codebases, fixed screen by screen over months.

With a system

color.text.secondary moves from neutral.600 to neutral.700, raising it to 5.99:1. One token change, announced in the release notes, reaches every screen.

Beyond the ratio: colour and meaning

Contrast is necessary but not sufficient. WCAG also asks that colour isn't the only way information is shown (1.4.1). An error field needs an icon or message as well as a red border; a chart needs labels or patterns as well as colours. Build those patterns into components, so teams get them by default.

WCAG 2 vs APCA

APCA, the Accessible Perceptual Contrast Algorithm, is a newer method that accounts for font size, weight and whether text is light-on-dark or dark-on-light. It often gives better answers in dark mode and for thin fonts. It's a useful second opinion, but WCAG 2.2's ratios are what laws and audits measure today, so use WCAG as the gate.

The short version

  • 4.5:1 for body text; 3:1 for large text, borders, icons and focus rings.
  • Check pairs, not colours, in every theme and every state.
  • A shared lightness curve turns contrast into simple step rules.
  • Publish approved pairs, test them automatically, and lint for raw colours.
  • Don't rely on colour alone to carry meaning.

Frequently asked questions

What contrast ratio does WCAG require?

At level AA: 4.5:1 for normal text, 3:1 for large text, and 3:1 for meaningful non-text elements such as borders, icons and focus indicators.

Does the primary brand colour have to pass contrast?

Only where it's used for text or meaningful UI. Many brands use a lighter brand colour for decoration and a darker step of the same hue for text and buttons.

Should we use APCA instead of WCAG 2?

Use WCAG 2.2 as the requirement, and APCA as a second opinion, especially for dark mode and thin type.

How do we test contrast automatically?

List every allowed foreground–background pair in your token docs, compute their ratios in a script during the token build, and fail the build if any drop below their minimum.

Further reading