Skip to content

Stop Auditing Contrast After the Fact, Bake It Into Tokens

Design system color contrast at the token level: a DTCG token file plus a 37-line Node script that fails CI on any pair under WCAG 4.5:1 or 3:1.

· · 16 min read

Updated: October 15, 2026

Wall covered in assorted colorful paint samples and swatches used to test color combinations

Picture a design system where every color has a documented hex value and a named swatch in Figma. Now picture a designer pairing a light gray label with an off-white card. Nothing objects, because the tokens describe colors, not relationships. That's a hypothetical, but the mechanism behind it is real: a file that stores values can't tell you which pairs of values are safe to put together.

Most teams treat contrast as a check you run at the end, a browser audit before launch. Auditing after the fact means touching every screen that used the failing pair. The alternative is to bake the rule into the token file, so the pair gets tested every time the file changes.

This article builds the second version, and you can reproduce it. I wrote a short Node script, pointed it at a nine-pair token file in the W3C DTCG format, and ran it. It failed two pairs. Every number below is pasted from that run or worked out by hand from the WCAG formula. An earlier draft of this post printed ratios I couldn't reproduce (it claimed 4.87:1 for white on #2B6CB0, and the real figure is 5.42:1), so I recomputed all of them.

TL;DR: Low contrast text, below the WCAG 2 AA thresholds, was found on 83.9% of home pages in 2026, up from 79.1% in 2025, and it's the most commonly detected accessibility issue (WebAIM Million 2026). Put each text and background pair in the token file, check the whole file with a 37-line script, and let a ratio under 4.5:1 (text) or 3:1 (large text, UI) fail the build.

Photo by Taylor Heery on Unsplash

Why Do Contrast Failures Keep Slipping Through, Even With a Design System?

Because most token systems store colors, not color relationships. A token named color.gray.400 gives you a hex value. It doesn't say where that gray is safe as text, or on which background it quietly drops under 4.5:1. Every designer and developer has to remember that constraint, or run a checker by hand, every single time. Over a fifty-screen product and a two-year timeline, someone forgets. That isn't a discipline problem. The system never encoded the rule.

The scale of the problem is not small. WebAIM's 2026 analysis of one million home pages counted an average of 34 distinct low-contrast text instances per page, and 95.9% of the pages had at least one detected WCAG 2 failure. Automated tools only catch part of what's wrong, so the real figures are worse.

Here's the unpopular part. An accessibility statement in a README is not a control. If nothing fails when a pair gets worse, nothing is enforcing it, and calling the system "accessible" is a description of intent.

The thresholds themselves are the easy part. They're what your tokens need to encode:

ContentWCAG levelMinimum ratioSuccess criterion
Body text under 18pt (or 14pt bold)AA4.5:11.4.3 Contrast (Minimum)
Large text, 18pt+ or 14pt+ boldAA3:11.4.3 Contrast (Minimum)
Body text under 18ptAAA7:11.4.6 Contrast (Enhanced)
Large text, 18pt+ or 14pt+ boldAAA4.5:11.4.6 Contrast (Enhanced)
UI components, focus rings, icons carrying meaningAA3:11.4.11 Non-text Contrast
Inactive controls and pure decorationn/aNo requirement1.4.3, 1.4.11 exceptions

That last row is the one teams get wrong in both directions. Inactive controls are genuinely exempt, so chasing 4.5:1 on a greyed-out button is wasted effort, and so is text inside a logo. But a focus ring is not decoration, and it needs 3:1 against whatever sits behind it.

One more detail from the W3C's own guidance: the computed ratio should not be rounded. A 4.499:1 pair does not meet 4.5:1. Keep that in mind when you read a report that prints two decimals, because the display rounds and the comparison shouldn't.

What Does the Contrast Math Actually Compute?

A ratio of two luminances, nothing more. The WCAG formula takes each color's relative luminance, a weighted sum of its linearized red, green and blue channels, and divides the lighter one plus 0.05 by the darker one plus 0.05.

Spelled out for the failing pair in the example file, gray-400 (#a0a0a0) as text on paper-50 (#f8f8f6) as the page:

  1. Gray-400 is 160 on each channel. 160 / 255 = 0.6275. The sRGB curve turns that into 0.3515 (the formula is ((c + 0.055) / 1.055) ^ 2.4 above 0.04045, and c / 12.92 below it). All three channels match, and the weights 0.2126, 0.7152 and 0.0722 sum to 1, so the luminance is 0.3515.
  2. Paper-50 is 248, 248, 246. The channels linearize to 0.9387, 0.9387 and 0.9216. Weighted: 0.2126 x 0.9387 + 0.7152 x 0.9387 + 0.0722 x 0.9216 = 0.9375.
  3. Ratio: (0.9375 + 0.05) / (0.3515 + 0.05) = 0.9875 / 0.4015 = 2.46.

That's 2.46:1 against a floor of 4.5:1. Not close. A gray this light looks refined on a good monitor, and that is the trap.

How far can you push a gray before it breaks? I ran the formula on the famous one: #767676 on pure white comes out at 4.54:1, and #777777 on white drops to 4.48:1. So #767676 is the lightest neutral gray that clears 4.5:1 on white. On the off-white page in the example file the same #767676 would score 4.27:1, which is the whole argument for testing pairs instead of colors. The background moved a few points of lightness and the answer flipped.

The checker below runs that same arithmetic in the browser. It uses the WCAG relative-luminance formula, and it opens on the fixed caption color, so type the failing #a0a0a0 from our token file to watch it break.

What Does an Accessibility Token Look Like in the DTCG Format?

DTCG is the W3C Design Tokens Community Group's file format. A token is an object with a $value, a $type can be set on the token or inherited from a parent group, and an alias is a curly-brace path to another token. The version I checked is 2025.10, which the group published on 28 October 2025 and describes as stable. It's a Community Group Report, not a W3C Standard, and it isn't on the W3C Standards Track. Our explainer on Style Dictionary and Figma covers how tools read that format and where they differ.

One trap worth knowing before you copy anything. In 2025.10 the value of a color token is an object with a required colorSpace and components, plus optional alpha and a hex fallback. A bare hex string as a color $value is not a documented form in that version, so an exporter that writes one is following something older or looser. The example file uses the object form.

DTCG has no concept of a pair, so the pair goes in $extensions. The spec says keys should avoid clashing and recommends reverse domain notation, and that tools must preserve extension data they don't understand. That makes it a safe place for a contrast rule. Each foreground token names its background and its kind: text, large or ui.

Here's the whole file I tested, color.tokens.json (the spec recommends the .tokens.json suffix):

{
  "$type": "color",
  "palette": {
    "ink-900": { "$value": { "colorSpace": "srgb", "components": [0.102, 0.102, 0.102], "hex": "#1a1a1a" } },
    "gray-600": { "$value": { "colorSpace": "srgb", "components": [0.349, 0.349, 0.349], "hex": "#595959" } },
    "gray-500": { "$value": { "colorSpace": "srgb", "components": [0.5412, 0.5412, 0.5412], "hex": "#8a8a8a" } },
    "gray-400": { "$value": { "colorSpace": "srgb", "components": [0.6275, 0.6275, 0.6275], "hex": "#a0a0a0" } },
    "paper-50": { "$value": { "colorSpace": "srgb", "components": [0.9725, 0.9725, 0.9647], "hex": "#f8f8f6" } },
    "white": { "$value": { "colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff" } },
    "blue-600": { "$value": { "colorSpace": "srgb", "components": [0.1686, 0.4235, 0.6902], "hex": "#2b6cb0" } },
    "blue-500": { "$value": { "colorSpace": "srgb", "components": [0.2314, 0.5098, 0.9647], "hex": "#3b82f6" } },
    "blue-300": { "$value": { "colorSpace": "srgb", "components": [0.3882, 0.702, 0.9294], "hex": "#63b3ed" } },
    "amber-300": { "$value": { "colorSpace": "srgb", "components": [0.9647, 0.7882, 0.2706], "hex": "#f6c945" } }
  },
  "surface": {
    "page": { "$value": "{palette.paper-50}" },
    "brand": { "$value": "{palette.blue-600}" },
    "warning": { "$value": "{palette.amber-300}" }
  },
  "text": {
    "body": { "$value": "{palette.ink-900}", "$extensions": { "com.artofstyleframe.contrast": { "on": "{surface.page}", "kind": "text" } } },
    "caption": { "$value": "{palette.gray-600}", "$extensions": { "com.artofstyleframe.contrast": { "on": "{surface.page}", "kind": "text" } } },
    "muted": { "$value": "{palette.gray-400}", "$extensions": { "com.artofstyleframe.contrast": { "on": "{surface.page}", "kind": "text" } } },
    "link": { "$value": "{palette.blue-600}", "$extensions": { "com.artofstyleframe.contrast": { "on": "{surface.page}", "kind": "text" } } },
    "display": { "$value": "{palette.blue-300}", "$extensions": { "com.artofstyleframe.contrast": { "on": "{surface.page}", "kind": "large" } } },
    "on-brand": { "$value": "{palette.white}", "$extensions": { "com.artofstyleframe.contrast": { "on": "{surface.brand}", "kind": "text" } } },
    "on-warning": { "$value": "{palette.ink-900}", "$extensions": { "com.artofstyleframe.contrast": { "on": "{surface.warning}", "kind": "text" } } }
  },
  "ui": {
    "focus-ring": { "$value": "{palette.blue-500}", "$extensions": { "com.artofstyleframe.contrast": { "on": "{surface.page}", "kind": "ui" } } },
    "border": { "$value": "{palette.gray-500}", "$extensions": { "com.artofstyleframe.contrast": { "on": "{surface.page}", "kind": "ui" } } }
  }
}

Nine pairs, and I planted two bad ones on purpose: text.muted and text.display. A real file would never be that honest about its own flaws, which is why the script has to be.

Aliases do the work of keeping the file small. The script follows {surface.page} back to palette.paper-50, so if someone edits that one palette entry, every pair that lands on the page color gets rechecked on the next run. Nobody has to remember which tokens depend on it.

How Do You Make the Build Fail on a Bad Pair?

With a script that reads the file, resolves the aliases, computes a ratio per pair and exits with code 1 if any pair misses its floor. No dependencies, plain Node 22 (it uses ES modules, so save it as check-contrast.mjs).

The script

import { readFileSync } from "node:fs";

const EXT = "com.artofstyleframe.contrast";
const MIN = { text: 4.5, large: 3, ui: 3 };
const tokens = JSON.parse(readFileSync(process.argv[2] ?? "color.tokens.json", "utf8"));

const get = (path) => path.split(".").reduce((node, key) => node?.[key], tokens);
const resolve = (value) => (typeof value === "string" ? resolve(get(value.slice(1, -1)).$value) : value);
const rgb = ({ components, alpha = 1 }) => {
  if (alpha < 1) {
    throw new Error("alpha < 1 needs compositing first");
  }
  return components.map((c) => Math.round(c * 255) / 255);
};
const lin = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
const lum = ([r, g, b]) => 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
const ratio = (a, b) => {
  const [hi, lo] = [lum(a), lum(b)].sort((x, y) => y - x);
  return (hi + 0.05) / (lo + 0.05);
};
const pairs = (node, path = []) => Object.entries(node).flatMap(([key, child]) => {
  if (typeof child !== "object" || key.startsWith("$")) {
    return [];
  }
  const rule = child.$extensions?.[EXT];
  return rule ? [{ name: [...path, key].join("."), fg: child.$value, ...rule }] : pairs(child, [...path, key]);
});

let failed = 0;
for (const p of pairs(tokens)) {
  const r = ratio(rgb(resolve(p.fg)), rgb(resolve(p.on)));
  const ok = r >= MIN[p.kind];
  failed += ok ? 0 : 1;
  console.log(`${ok ? "PASS" : "FAIL"}  ${p.name.padEnd(16)} ${r.toFixed(2).padStart(5)}:1  needs ${MIN[p.kind]}:1  (${p.kind})`);
}
console.log(`${failed} of ${pairs(tokens).length} pairs failed`);
process.exit(failed ? 1 : 0);

Three details are easy to miss. resolve calls itself, so an alias that points at another alias still ends at a real color. The comparison uses the unrounded ratio and only the printed number is rounded to two decimals, matching the W3C note about 4.499:1. And rgb rounds each channel to a whole 8-bit value first, because that's what a screen renders; it also means the file's four-decimal components give the same answer as the hex fallback.

What it printed

I ran it on Node 22.23.3 against the file above. This is the real output, copied from the terminal:

PASS  text.body        16.37:1  needs 4.5:1  (text)
PASS  text.caption      6.59:1  needs 4.5:1  (text)
FAIL  text.muted        2.46:1  needs 4.5:1  (text)
PASS  text.link         5.10:1  needs 4.5:1  (text)
FAIL  text.display      2.15:1  needs 3:1  (large)
PASS  text.on-brand     5.42:1  needs 4.5:1  (text)
PASS  text.on-warning  11.07:1  needs 4.5:1  (text)
PASS  ui.focus-ring     3.46:1  needs 3:1  (ui)
PASS  ui.border         3.25:1  needs 3:1  (ui)
2 of 9 pairs failed

The shell reported exit code 1. The 2.46 on text.muted matches the hand arithmetic from the previous section, which is the reassuring part: two independent routes, one answer. The second failure, text.display, is the one people defend. Light blue at display size looks fine to the person who picked it. At 2.15:1 it misses even the 3:1 large-text floor.

Wiring it into CI

Any CI system treats a non-zero exit code as a failed step, so the script needs no plugin. Here's how it would look in GitHub Actions, one step per theme so a light failure doesn't hide a dark one:

- name: Contrast, light tokens
  run: node scripts/check-contrast.mjs tokens/color.tokens.json

- name: Contrast, dark tokens
  if: always()
  run: node scripts/check-contrast.mjs tokens/color.dark.tokens.json

I haven't run that YAML on a hosted runner. What I did run is the script itself and its exit codes, locally, and the YAML only wires those exit codes to a step. Test it on a throwaway branch before you trust it, and make the check a required one, or a red step will be ignored by the third week.

The dark file is where the check earns its keep. I wrote color.dark.tokens.json with three pairs: an #ededed body, the blue-300 link, and the same gray-600 caption on a #121212 page. The output:

PASS  text.body        16.00:1  needs 4.5:1  (text)
PASS  text.link         8.21:1  needs 4.5:1  (text)
FAIL  text.caption      2.67:1  needs 4.5:1  (text)
1 of 3 pairs failed

Same token value, 6.59:1 on the light page and 2.67:1 on the dark one. I built that case on purpose, and it's still the best argument for one file per theme. Our dark mode design patterns covers why dark mode is more than a color swap.

Where Does a Ratio Check Stop Being Enough?

Earlier than most write-ups admit. The script is a floor, and it has holes you should know about before you tell anyone the system is accessible.

  • Opacity. DTCG colors can carry an alpha. The ratio formula needs two opaque colors, so I made the script throw on anything below 1 instead of guessing. I tested that: setting alpha to 0.6 on ink-900 stops the run with alpha < 1 needs compositing first. Blend the translucent color over its real backdrop and check the result. The W3C's guidance on measuring says nothing about transparency, so don't assume the checker you use handles it.
  • The kind is a promise. Marking a token large means 18pt or 14pt bold, which is 24px or about 18.67px in CSS at 96 dpi. Nothing in the file stops a component from using that token at 16px. Pair the check with a rule on where the token can be used.
  • Background images and gradients. A pair assumes one flat surface. Text over a photo has no single background color to name.
  • States. Hover, focus, pressed and visited states are separate pairs, and each needs its own entry. Inactive states are exempt, but only the ones that are truly inactive.
  • Missing aliases. If a token points at a path that doesn't exist, the script dies with a TypeError instead of a friendly message. I tried it. A loud crash beats a silent pass, so I left it.
  • What the ratio can't see. WCAG 2 treats a ratio the same for thin and heavy type and for light-on-dark and dark-on-light. That's the weakness APCA tries to fix.

On APCA, then. The WCAG 3.0 Working Draft dated 10 September 2026 says "The contrast algorithm used in WCAG 3 is yet to be determined." Adrian Roselli's April 2026 write-up notes that APCA was removed from the July 2023 draft. And the draft states that WCAG 3 does not replace WCAG 2. So for now the legal and audit reference is still the WCAG 2.2 ratio, and I wouldn't gate a build on anything else. Is APCA useless in the meantime? No. Run it as a second opinion on borderline pairs. Just don't let it overrule the number your auditors will use.

How Do You Retrofit This Into a System That Already Exists?

Start with an audit, not a rewrite. List every text and background pairing in production, put them in the format above, and run the script. You'll get a list of failures; rank them by how often each pairing appears across your product and fix the highest-frequency ones first, because that's where the retrofit buys the most coverage per hour. For a one-off pair that isn't in a file yet, the WCAG contrast checker gives the same ratio, one pair at a time.

Then comes the step teams skip. Don't just fix the failing pair. Add the passing replacement as a named token with its surface declared in $extensions, so the next designer who needs "text on a warning banner" picks from a list that's already tested instead of eyeballing a new hex value that fails again in six months. In the example file, text.on-warning (11.07:1) exists for exactly that reason.

Photo by Mika Baumeister on Unsplash

If your system has several brands, run the script once per brand file. A palette swap that reads fine for brand one can drop a secondary label under 4.5:1 for brand two, and the multi-brand theming guide shows how the semantic layer keeps that swap contained.

Is This Worth the Engineering Time It Takes?

Honestly? Yes, because the ongoing cost is close to zero. The upfront work is restructuring the tokens and adding a rule per pair. After that the system prevents the mistake instead of asking a human to catch it every time. The alternative is a score that drifts down every quarter as new screens ship, followed by a remediation sprint before somebody's deadline. The token-first approach is boring in exactly the way good infrastructure should be boring.

There's a people cost worth naming too. Every time a designer stops to check a ratio by hand, that's a small tax on attention, paid across hundreds of screens. With the rule in the token file, design reviews can stop debating contrast and spend the time on decisions that need judgment.

An accessibility statement in a README is not a control: if nothing fails when a pair gets worse, nothing is enforcing it.

Contrast is one half of accessible type. The other half is choosing typefaces and spacing that don't fight your readers before contrast even enters the picture, which is exactly what our accessible typography guide covers next.

Check a pair before you argue about it

This opens on the fixed caption, #6b6b6b on the paper-50 page color, which scores 5.01:1. Now type #a0a0a0 into the text field, the gray-400 the token file below actually holds, and watch it fall to 2.46:1. Change either color and watch the ratio move. The checker takes one pair at a time, which is exactly why the script in the next sections reads the whole token file and checks every pair in one run.

Open the full checker

Large heading text

The quick brown fox jumps over the lazy dog. This is body copy at a normal reading size.

Button label
--contrast ratio
  • AA Normal text 4.5:1
  • AA Large text 3:1
  • AA UI & graphics 3:1

Frequently Asked Questions

What is an accessibility token, exactly?
It's a color token that carries a checked relationship instead of a bare value. A normal token says text.muted is #a0a0a0. An accessibility token also says which surface that text sits on and what kind of content it is (body text, large text, a UI edge), so a script can compute the ratio and compare it with the 4.5:1 or 3:1 floor. The DTCG format has a place for that extra data: $extensions, which tools are required to preserve even when they don't understand it. Nobody picking from the token list can end up with a failing pair, because the pair is tested every time the file changes.
Do I need to support APCA as well as WCAG contrast ratios?
Not as a gate. WCAG 2.2 (a W3C Recommendation since 12 December 2024) defines the 4.5:1 and 3:1 ratios that audits measure against. The WCAG 3.0 Working Draft dated 10 September 2026 says its contrast algorithm is yet to be determined, and Adrian Roselli notes that APCA was pulled from the July 2023 draft. Keep your pair list as data, though. If a second algorithm ever lands, it becomes one more column in the report instead of a re-audit.
Do dark mode tokens need their own contrast check?
Yes, and the same palette value can flip from pass to fail. In the example file in this article, gray-600 as caption text scores 6.59:1 on the light page color and 2.67:1 on the dark one. Put each theme in its own token file, run the script on each, and fail the build if either exits non-zero.
How do I find hardcoded hex values that bypass the tokens?
Search for them: grep -rnE '#[0-9a-fA-F]{6}' src --include=*.css --include=*.tsx, then drop the lines that come from your token files. What's left is the real scope of the retrofit. Many will turn out to be hand-typed copies of colors the token set already has, and each one a script can't see is a pair that nothing is checking.