Anchoring Accessibility Systematically Through Design Tokens

1. The design system as a structural lever for accessibility

Accessibility enforced solely through code reviews or after-the-fact audits stays a reactive affair. A bug gets introduced, eventually gets discovered, then gets fixed individually, while the same class of bug already exists again somewhere else in the codebase. A design token system changes that dynamic at its root, because it defines correct values, for example a color with sufficient contrast, in exactly one central place and reuses them consistently across every component.

That centralization means a single, carefully vetted decision, such as which shade of gray is allowed as secondary text on which background, propagates automatically across the entire store, instead of being made and checked individually all over again in every new component. Accessibility becomes a property of the design foundation itself, not a checklist that gets worked through from scratch with every new component.

2. Contrast-checked color tokens instead of ad hoc color choices

Instead of leaving a designer or developer free to pick any hex value for text on a colored background, a token system defines a limited, deliberately curated palette of color combinations, each already checked against the WCAG contrast requirement of at least 4.5 to 1 for normal text and 3 to 1 for large text. Every token carries a descriptive name like text-secondary-on-surface that clearly states its intended use, instead of a plain color label like gray-500 that says nothing about the allowed context.

Checking combinations, not just individual colors, matters in particular, because the same gray can offer sufficient contrast on a white background yet already fall short on a light gray background. A good token system therefore defines allowed foreground-background pairs as a single unit, which structurally makes it hard to accidentally slot an unchecked, low-contrast combination into a new component.

/* Tailwind v4 CSS-first theme: contrast-checked color tokens */
@theme {
  --color-text-primary: oklch(0.21 0.02 265);      /* 15.2:1 on --color-surface */
  --color-text-secondary: oklch(0.42 0.02 265);    /* 5.1:1 on --color-surface, WCAG AA */
  --color-text-on-accent: oklch(0.98 0 0);         /* 6.8:1 on --color-accent */
  --color-surface: oklch(0.99 0 0);
  --color-accent: oklch(0.45 0.18 255);
}

3. Spacing tokens for minimum touch target sizes

WCAG 2.5.8 requires a minimum size of 24 by 24 CSS pixels for interactive elements, while the stricter AAA requirement 2.5.5 pushes that up to 44 by 44 pixels, a measurement that decides, particularly for people with motor impairments, whether a button can be reliably hit at all. Left as a free decision for each individual component instead of a token, that minimum size inevitably drifts, for example a compact icon button in a toolbar ending up well below the required minimum.

A spacing token system therefore defines fixed minimum values for interactive elements, such as --size-touch-target-min at forty-four pixels, that every button and icon component in the design system is required to reference, regardless of how small the visual icon itself is designed. The clickable area can be larger than the visible icon, for instance through extra padding controlled by the same token, instead of tying the click area rigidly to the visual size.

@theme {
  --size-touch-target-min: 44px;
  --spacing-icon-button-padding: 10px; /* 24px icon + padding = 44px click area */
}

.icon-button {
  min-width: var(--size-touch-target-min);
  min-height: var(--size-touch-target-min);
  padding: var(--spacing-icon-button-padding);
}

4. Typography tokens with guaranteed scalability

WCAG 1.4.4 requires that text can be resized up to two hundred percent without losing content or functionality, a requirement that can only be reliably met when font sizes are consistently defined in relative units like rem instead of fixed pixel values. A typography token system defines every font size once, in rem, structurally preventing an individual component from accidentally using a fixed pixel size that ignores the user's zoom setting.

It is also worth using clamp() inside the token definition to achieve responsive scaling between mobile and desktop views that stays within defined bounds, without losing baseline scalability through the browser's zoom feature. A line height token that scales proportionally with font size, instead of being fixed, also stops text from crowding together and becoming hard to read at high magnification.

@theme {
  --text-base: clamp(1rem, 0.95rem + 0.25vw, 1.125rem);
  --text-lg: clamp(1.125rem, 1.05rem + 0.375vw, 1.375rem);
  --leading-base: 1.6; /* scales proportionally with --text-base */
}

5. Technical token structure: CSS custom properties in Tailwind v4

In Tailwind CSS v4, design tokens can be defined directly through the CSS-first approach inside the @theme block as CSS custom properties, which makes them automatically available as utility classes without extra build tooling while staying inspectable at runtime in the browser, for example for an automated contrast check against the actually rendered value. This direct availability as a CSS variable also allows tokens to adapt dynamically, for instance for a dark mode, without having to change the underlying utility class in every component.

It matters that tokens never get misused as a pure convenience shortcut for a value used only once, and instead stay consistently tied to their semantic meaning, so a later adjustment, such as a contrast fix after an audit, can happen in exactly one place and reliably propagates across the entire store.

6. Governance: who can change tokens and how they get approved

A token system only pays off if changes to central tokens cannot be made casually by any developer, but instead go through a defined approval process, similar to a code review, where every new or changed color combination is explicitly checked against the contrast requirement before it gets added to the central token set. This governance stops a single compromise made under time pressure from quietly becoming the permanent foundation for a large number of components.

In practice it works well to treat token changes as their own pull request type, mandatorily reviewed by someone with accessibility expertise on the team, regardless of how urgent the underlying business requirement seems, because a non-compliant token, once introduced, spreads across a great many components and becomes correspondingly expensive to fix later.

7. Applying tokens at the component level in Hyvä and Tailwind

In a Hyvä theme, design tokens translate directly into Tailwind utility classes used in .phtml templates, for example text-text-secondary for a token-defined color scheme instead of a direct text-gray-500. This convention makes the semantic role of a color visible right when reading the template, and makes it far easier to reliably find every affected spot with a simple search for the token name when a token later gets adjusted.

For reusable Hyvä components like buttons or form fields, it is also worth building a central, shared .phtml template or view model that encapsulates the token-based classes once, instead of every single place in the theme reassembling the utility classes individually and risking forgetting a token or replacing it with a diverging hardcoded value.

8. Automated checks against the tokens themselves

The token set itself can be checked automatically against contrast requirements by having a small script walk every defined foreground-background combination and calculate the contrast ratio, instead of relying solely on manual review during a design pass. Such a script can run automatically as its own CI job on every change to the token file and fail as soon as a newly introduced combination drops below the required contrast threshold.

Spacing tokens can be checked in a similar way, verifying that every component marked as interactive actually references the minimum size token, for example through a lint rule set that flags direct pixel values not tied to a token as an error in interactive components. This automated safeguard at the token level stops an individual component from quietly drifting away from the centrally checked foundation.

9. Rolling out to the team: migrating from hardcoded values to tokens

Migrating a grown store to a consistent token system rarely succeeds in one single big step, it works better incrementally, starting with the most frequently reused elements such as buttons, form fields, and text colors, where a single token definition unlocks the biggest leverage across the most pages at once. An automated search for frequently occurring hex values in the existing codebase helps prioritize the most pressing candidates for migration.

For the rollout to actually stick across the team, a short but mandatory onboarding session for every developer is worth the time, explaining why a token should be used instead of a direct hex or pixel value, paired with a simple lookup reference of all available tokens, so making the right choice in daily work is no more effort than the previous, unstructured approach.

10. Summary

11. FAQ: Design Tokens and Accessibility: Key Takeaways