Building Accessible Color Systems from Scratch

Retrofitting accessibility into an existing color system is expensive and usually incomplete. Building with it from the start is faster and produces more coherent results. Here's the process. **Step 1: Define Your Scale Architecture First** Before choosing any colors, decide your scale structure. A 10-step scale (50–900 or 100–1000) is standard. Within this scale, you'll use steps 100-300 for light surfaces and backgrounds, 500-700 for interactive elements (must pass 3:1 contrast), and 700-900 for text (must pass 4.5:1 contrast). **Step 2: Choose Your Base Hue, Then Build Contrast** Pick your base hue, then generate your scale using lightness as the primary variable. Test each step in your scale against white and black. Document which steps pass AA for large text, AA for normal text, and AAA. This becomes your scale spec. Key insight: the specific lightness values that produce 4.5:1 contrast against white depend heavily on the hue. Yellow and green hues need to be significantly darker to hit the same contrast ratio as blue and purple hues, because of their higher perceptual luminance. **Step 3: Define Semantic Tokens Referencing Your Scale** Now map scale values to semantic tokens: - color.text.primary → your darkest step on the appropriate background - color.action.primary → the step that passes 4.5:1 on your background - color.surface.default → a light step that your text tokens pass contrast against - color.feedback.error → your red scale at the step that passes contrast requirements **Step 4: Test Pairs, Not Just Individual Colors** Contrast testing must cover every token pair that appears together in the UI. An automated tool (like our WCAG Auditor) can test your full token matrix. Any combination that fails is a design issue to resolve before implementation. **Step 5: Document Pass/Fail per Token** For each semantic token, document which background it passes against. 'color.action.primary passes AA on color.surface.default and color.surface.raised' is the level of documentation that prevents accessibility regressions as the system evolves.