Low contrast text is the most frequently detected accessibility failure on the web, year after year. Teams treat it as a series of page bugs, file a ticket per instance, fix eleven of them, and find fourteen more next quarter.<\/p>\n\n\n\n
It is not a page problem. A palette has maybe twenty colours in it. Every contrast failure on your site is one of those twenty appearing on a surface it should not appear on. Fix the layer where colours are defined and the whole class of bug stops being possible.<\/p>\n\n\n\n
Most design systems name colours by what they look like or where they sit on a scale.<\/p>\n\n\n\n
--grey-100: #f5f5f7;\n--grey-400: #a3a3ab;\n--grey-600: #6d6d76;\n--blue-500: #2f7cff;<\/code><\/pre>\n\n\n\nNothing in that structure says which of them may carry body text, or on what. A developer needing muted text picks grey-400 or grey-600 by eye. Both look fine on white in a bright room. One of them fails on your dark surface and neither of them was ever checked against the tinted panel that shipped last month.<\/p>\n\n\n\n
The token is not wrong. The missing thing is the pairing.<\/p>\n\n\n\n
Name tokens by role and surface<\/h2>\n\n\n\n
Keep the raw scale as a private layer, then expose semantic tokens that encode where they are allowed to be used.<\/p>\n\n\n\n
\/* private: never used directly in components *\/\n--_grey-400: #a3a3ab;\n--_grey-500: #7d7d86;\n--_ink-900: #0f0f0f;\n\n\/* public: role plus the surface it is verified against *\/\n--text-primary-on-base: #e7e7ea; \/* 15.8:1 on --surface-base *\/\n--text-muted-on-base: #7d7d86; \/* 4.7:1 on --surface-base *\/\n--text-muted-on-raised: #8a8a93; \/* 4.6:1 on --surface-raised *\/\n--border-control-on-base: #63636b; \/* 3.2:1, meets non-text 3:1 *\/\n--focus-ring: #8ec0fa; \/* 10.1:1, and never removed *\/<\/code><\/pre>\n\n\n\nThe name now carries the constraint. A developer writing muted text on a raised card reaches for the token that says raised, and there is no version of the decision where they have to guess a ratio.<\/p>\n\n\n\n
Record the measured ratio in a comment. It is documentation for the next person and it is the thing you check when a designer proposes changing a value.<\/p>\n\n\n\n
The thresholds, so nobody has to look them up<\/h2>\n\n\n\n\n\n- 4.5:1<\/strong> for normal body text against its background.<\/li>\n\n\n
- 3:1<\/strong> for large text, meaning roughly 24px regular or 18.66px bold and above.<\/li>\n\n\n
- 3:1<\/strong> for the visual boundary of interactive components and for meaningful graphics. Input borders, icon buttons, chart lines, toggle states.<\/li>\n\n\n
- 3:1<\/strong> for the focus indicator against the adjacent background, with a minimum size, under WCAG 2.2.<\/li>\n\n<\/ul>\n\n\n\n
The third one catches almost everybody. Placeholder borders on inputs are routinely a faint hairline that fails 3:1, which means a user with low vision cannot see where the field is, only where the label is.<\/p>\n\n\n\n
Test the pairs in CI, not the pages<\/h2>\n\n\n\n
A page scan tells you a component failed. A token test tells you the palette is wrong, which is the actionable version.<\/p>\n\n\n\n
Declare the pairs that are supposed to be valid and assert them. This is a unit test, it runs in milliseconds, and it fails the moment a designer nudges a hex value.<\/p>\n\n\n\n
const PAIRS = [\n [\"--text-primary-on-base\", \"--surface-base\", 4.5],\n [\"--text-muted-on-base\", \"--surface-base\", 4.5],\n [\"--text-muted-on-raised\", \"--surface-raised\", 4.5],\n [\"--border-control-on-base\", \"--surface-base\", 3.0],\n [\"--focus-ring\", \"--surface-base\", 3.0],\n];\n\ntest.each(PAIRS)(\"%s on %s meets %s:1\", (fg, bg, min) => {\n expect(contrastRatio(tokens[fg], tokens[bg])).toBeGreaterThanOrEqual(min);\n});<\/code><\/pre>\n\n\n\nThe valuable side effect is social rather than technical. When a palette change fails a build, the conversation happens in the pull request with a number attached, instead of six months later in an audit where it reads as an accusation.<\/p>\n\n\n\n
Dark mode doubles the surface, not the work<\/h2>\n\n\n\n
If the semantic layer is a real indirection, a theme is a remap of the same names and the same test list runs against it unchanged.<\/p>\n\n\n\n
Two things that are specific to dark themes and get missed. Pure white text on pure black is uncomfortable at high ratios, so soften both ends slightly. And a colour that passed on light almost never passes on dark, so your accent needs a separate value per theme rather than one value used in both.<\/p>\n\n\n\n
The cases tokens cannot cover<\/h2>\n\n\n\n
Be honest about the limit. Text over photographs, video, or gradients has no fixed background, so no token pair describes it.<\/p>\n\n\n\n
Handle those structurally instead: a scrim of known opacity between the image and the text, sized so the worst case underlying pixel still clears the threshold. Then the pair you are testing is text against scrim, which is fixed, and the photograph stops being a variable.<\/p>\n\n\n\n
Colour is never the only signal<\/h2>\n\n\n\n
Contrast is necessary and not sufficient. A separate criterion says colour cannot be the sole means of conveying information, and no token structure enforces that.<\/p>\n\n\n\n
Practically that means links in body copy stay underlined, error states carry an icon and a message rather than a red border, required fields say required, and a chart legend does not depend on distinguishing two shades of blue. These are component decisions, and the token system is what frees you to spend review time on them instead of on hex values.<\/p>\n\n\n\n
\n\n\n\n