Your token file is the only place in your design system where accessibility guarantees can live permanently — here’s how to put them there.
The previous post covered why WCAG compliance belongs in the token layer. This one is the implementation: what you actually write, how you structure it, and how you test it before a single component ships.
Contrast tokens: the foundation. Every text token needs a documented contrast ratio against its intended background. Don't store just the value — store the guarantee. In your tokens.css (or tokens.json), pair every semantic text token with a comment that names the ratio:
--text-primary: rgba(244,240,232,1.0); /* 18:1 on --bg-base ✓ */
--text-secondary: rgba(244,240,232,0.75); /* 9:1 on --bg-base ✓ */
--text-muted: rgba(244,240,232,0.55); /* 5.6:1 on --bg-base ✓ AA body */
This isn't decoration. It's a contract. When a developer reaches for --text-muted on a dark background, the ratio is right there. The floor for body text is 4.5:1 under WCAG AA. Set your muted token above that floor and never go lower. If you're tempted to add a --text-faint at 0.40 opacity, run the math first: on #0d0d0d that's 3.7:1 — a body text failure. The token structure stops that failure before it becomes a component.
Touch target tokens. Minimum interactive touch target is 44×44px under WCAG 2.5.5 (advisory) and the de facto standard for mobile. This belongs in your spacing token set, not left to component-level decisions:
--touch-target-min: 44px;
--touch-target-comfortable: 48px;
Any component that renders a button, link, or icon-only control should reference --touch-target-min as its minimum height and width. When you define it once at the token level, resizing for accessibility is a single variable change — not a component hunt.
Focus state tokens. Focus indicators are one of the most skipped accessibility requirements in design systems. WCAG 2.4.11 (AA in WCAG 2.2) requires a focus indicator with a 3:1 contrast ratio against adjacent colors and a minimum area of the perimeter. Define it in tokens:
--focus-ring-color: #1ab5a3; /* teal — 7:1 on dark bg ✓ */
--focus-ring-width: 2px;
--focus-ring-offset: 2px;
Every interactive component inherits these. If someone redesigns a button and the focus ring disappears, it's a token regression — not a forgotten detail. The token system makes the omission visible.
Semantic HTML + tokens: the pairing that enforces meaning. Tokens define visual intent. Semantic HTML enforces structural meaning. A heading token applied to a <div> is cosmetically correct but structurally broken for screen readers. The rule: pair every display token with the element it maps to. Document it in your system:
--text-display → <h1>
--text-heading → <h2> / <h3>
--text-label → <label>, <caption>
--text-body → <p>
This isn't rigid — context matters. But when your token system names the semantic pairing, designers and developers make better decisions by default.
Testing strategy: build it into the token review. Don't wait for a full audit. Every time you add or update a color token, run three checks before it lands: (1) contrast ratio against each background it'll appear on, (2) contrast in both light and dark contexts if you have themes, (3) pass/fail at both the 4.5:1 body threshold and the 3:1 large-text threshold. Tools like Colour Contrast Analyser (free, desktop), the WebAIM Contrast Checker, and the Figma plugin "Contrast" all take seconds per token. Treat a failing token the same way you'd treat a broken variable reference: it doesn't ship.
The free token starter at the download link below has all of this pre-built. Contrast ratios are documented inline, touch target tokens are included, and the focus ring tokens are wired to the default interactive component pattern. It's the foundation — drop it into your file and build from there.
Leave a Reply
You must be logged in to post a comment.