Tokens Logic
The programmatic engine of wA11y.
Design tokens are the smallest units of the system. They translate high-level accessibility requirements into shared, reusable variables. By using tokens instead of raw values, we eliminate “guesswork” and ensure that accessibility standards like WCAG 2.2 AA are enforced across all platforms simultaneously.
Token Architecture
wA11y uses a three-tier inheritance model. This structure allows us to change a brand color at the root without breaking the accessibility logic of the components.
Primitives (The Values)
The raw “source of truth” for colors, spacing, and motion. Primitives are not aware of context (e.g., Deep Green #01553B).
Semantic (The Intent)
Tokens defined by their function (e.g., action-primary-background). This layer handles the “logic”—ensuring a background always has enough contrast with its foreground.
Component (The Execution)
Specific attributes for UI elements (e.g., button-radius-large). These inherit from primitives or semantics to ensure consistency across the library.
Color Logic & Contrast Safety
The wA11y color system is built on a Foreground/Background Pairing logic. Every background token has a corresponding “On-” token to ensure WCAG compliance is automated.
The “On-” Token Standard:
For every surface color (e.g., surface-success), we provide a mandatory foreground token (e.g., text-on-success).
Contrast Guardrails
All primary semantic pairs are tested to maintain a minimum 4.5:1 ratio.
Dark Mode Inversion
Our tokens are “mode-aware.” When a user switches to Dark Mode, the semantic ID remains the same, but the value is programmatically swapped to a high-contrast alternative defined in the wa11y-Colors.json.
Typography & Legibility
Typography tokens do more than set font size; they enforce the rhythm required for inclusive reading.
Legibility Scaling
Our type tokens include specific line-height (minimum 1.5x for body text) and letter-spacing values to meet WCAG 1.4.12 (Text Spacing).
Dyslexia-Friendly Defaults:
We utilize the Roca and Roboto scales with generous tracking to prevent “character crowding,” which is a common barrier for neurodivergent users.
Unit Logic
All typography is defined in rem or pixels that scale proportionally, ensuring that if a user increases their browser font size to 200%, the layout reflows without overlapping.
Interactive & Motion Tokens
We encode interaction standards directly into our primitive and semantic layers to ensure a predictable experience for keyboard and screen reader users
Focus Ring Standard
Defined by the border/focus token at 3px. This ensures that the “Visible Focus” requirement is met across all interactive components.
Touch Target Primitives
Spacing tokens are designed around a 4px grid to ensure that components like Buttons and Checkboxes always meet the 44x44px minimum target.
Motion Reduction
Our motion tokens (100ms–300ms) are mapped to media queries that respect the prefers-reduced-motion system setting.
Deep Dive: System Toolboxes
Downloadable resources to help your team implement the system at scale.
The wA11y Token Spreadsheet
A mapping of all semantic tokens to their corresponding WCAG contrast ratios.
Designer’s Handoff Checklist
A 1-page guide to annotating focus order and intent for developers.
The “Stop & Fix” Dev Card
A quick reference for common code-level accessibility red flags.
Accessible Components Vetting Guide
How to audit third-party components before adding them to your library.