How to Find and Fix Design Token Violations
Token violations occur when designers use hardcoded values (#3B82F6) instead of tokens (primary-blue). These violations break the design system's ability to update globally—changing a token won't affect hardcoded values.
Why This Is Challenging
- Hardcoded values are visually identical to token values
- No visual indicator distinguishes token usage from hardcoding
- Violations accumulate in complex nested components
- Brand updates become migration projects instead of token changes
Manual Token Compliance Check
- 1Export your design token definitions (colors, typography, spacing)
- 2Select elements one by one and check their fill/stroke/text properties
- 3Compare each value against your token definitions
- 4For colors: check if the hex value exists in your color tokens
- 5For typography: verify font family, size, weight, and line height match your type scale
- 6For spacing: confirm padding and margins use your spacing scale values
- 7Document violations in a spreadsheet for tracking
- 8Manually update each violation to use the correct token
Automated Token Auditing with ComponentQA
ComponentQA compares every value in your design against your token definitions, flagging violations instantly. Each violation includes the current value, expected token, and a direct link to fix it.
- Scan every fill, stroke, and text style in seconds
- Automatic comparison against your token library
- Violation severity based on how far values deviate from tokens
- Deep links to each violation for quick fixes
- Track token compliance percentage over time