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.
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:
| Content | WCAG level | Minimum ratio | Success criterion |
|---|---|---|---|
| Body text under 18pt (or 14pt bold) | AA | 4.5:1 | 1.4.3 Contrast (Minimum) |
| Large text, 18pt+ or 14pt+ bold | AA | 3:1 | 1.4.3 Contrast (Minimum) |
| Body text under 18pt | AAA | 7:1 | 1.4.6 Contrast (Enhanced) |
| Large text, 18pt+ or 14pt+ bold | AAA | 4.5:1 | 1.4.6 Contrast (Enhanced) |
| UI components, focus rings, icons carrying meaning | AA | 3:1 | 1.4.11 Non-text Contrast |
| Inactive controls and pure decoration | n/a | No requirement | 1.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:
- 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.4above 0.04045, andc / 12.92below it). All three channels match, and the weights 0.2126, 0.7152 and 0.0722 sum to 1, so the luminance is 0.3515. - 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.
- 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 onink-900stops the run withalpha < 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
kindis a promise. Marking a tokenlargemeans 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
TypeErrorinstead 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.
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.