Contrast tuning is a system task
Instead of spot-fixing colors, build a repeatable workflow that guards contrast across themes and states.
Define token roles
- Text tokens by role (primary, secondary, inverse)
- Surface tokens with steps for elevation
- Interactive tokens for default/hover/active/disabled
Measure and adjust
- Run automated contrast checks in CI
- Adjust lightness in small increments (2–3%) to hit AA/AAA targets
- Document deltas so devs know what changed and why
Validate with real UI
Test key flows (forms, modals, alerts) in both light and dark themes. Ensure focus, hover, and disabled states stay legible.