Design System Token Audit
Audit design token consistency, calculate proliferation, and identify consolidation work. Enter values for instant results with step-by-step formulas.
Formula
Tokenization % = (Tokenized Values / Unique Values) × 100
Measures what percentage of design values use tokens vs hardcoded. Health score considers both tokenization rate and total unique value count against targets.
Worked Examples
Example 1: Startup Webapp Audit
Problem:Product has 75 components. Audit finds: 89 unique colors (only 10 tokenized), 18 font sizes (6 tokenized), 28 spacing values (8 tokenized).
Solution:Current state: Colors: 89 unique, 10 tokens → 11% tokenized Fonts: 18 unique, 6 tokens → 33% tokenized Spacing: 28 unique, 8 tokens → 29% tokenized Overall: 24% tokenized (POOR) Target: Colors: 12 tokens (consolidate 77 values) Fonts: 8 tokens (consolidate 10 values) Spacing: 8 tokens (consolidate 20 values) Effort: 107 consolidations × 0.5hr = 54 hours Recommendation: Phased cleanup over 2 sprints
Result:24% tokenized | 107 values to consolidate | 54 hour effort
Example 2: Enterprise Design System
Problem:Large SaaS: 200 components, 45 colors (all tokenized), 12 fonts (all tokenized), 15 spacing (all tokenized).
Solution:Current state: Colors: 45 unique, 45 tokens → 100% tokenized ✓ Fonts: 12 unique, 12 tokens → 100% tokenized ✓ Spacing: 15 unique, 15 tokens → 100% tokenized ✓ Overall: 100% tokenized (EXCELLENT) But: Still too many values Colors: 45 vs target 12 (33 to consolidate) Spacing: 15 vs target 8 (7 to consolidate) Action: Consolidate similar tokens E.g., --spacing-18 and --spacing-20 → --spacing-lg
Result:100% tokenized (Good) | Reduce token count | Consolidate 40 tokens
Example 3: Legacy Migration
Problem:Converting legacy app to design system. 300 components, 200+ colors (0 tokens), 50 font sizes (0 tokens).
Solution:Massive technical debt: Colors: 200+ unique, 0 tokenized Fonts: 50+ unique, 0 tokenized Spacing: Unknown but likely 100+ Tokenization: 0% (CRITICAL) Phased approach: 1. Create token system (12 colors, 8 fonts, 8 spacing) 2. Automated migration (80-90% coverage) 3. Manual edge cases 4. Enforce via linting Estimated effort: 200-300 hours Recommendation: 8-12 week initiative
Result:0% tokenized | 200-300hr effort | Multi-sprint initiative
Frequently Asked Questions
What are design tokens?
Design tokens are named variables storing design decisions (colors, typography, spacing). Examples: --color-primary-500, --font-size-lg, --spacing-4. They enable consistency, theming, and centralized design updates across products.
Why audit design tokens?
Audits reveal: duplicate or near-duplicate values, orphaned unused tokens, naming inconsistencies, missing semantic tokens, and proliferation (too many variations). Regular audits maintain system health.
How many design tokens should I have?
Typical well-maintained systems: 8-15 colors (per theme), 6-10 font sizes, 8-12 spacing values, 2-4 font families. More indicates poor governance. Less may be too restrictive.
What causes token proliferation?
Common causes: designers creating one-off values, lack of design system education, missing tokens for needed cases, copy-paste coding, no token linting, and weak code review for design consistency.
How do I consolidate similar tokens?
Process: audit all unique values, cluster similar values (e.g., #3B82F6 and #3B81F5), map to semantic tokens, update all references, deprecate old values, and enforce via linting going forward.
What's the difference between design tokens and CSS variables?
Design tokens are platform-agnostic design decisions. CSS variables (--custom-property) are one implementation. Tokens can generate CSS vars, iOS/Android code, Figma styles, etc., from single source of truth.
How do I enforce token usage?
Tools: Stylelint rules banning hardcoded values, design token linters, visual regression testing, design-to-code validation, and PR checks. Make it easier to use tokens than hardcode values.
What are semantic vs base tokens?
Base tokens: primitive values (--blue-500). Semantic tokens: purpose-named (--color-primary, --color-error). Semantic tokens reference base tokens, enabling theme switching while maintaining meaning.
How often should I audit tokens?
Quarterly for active systems, after major features, before design system versions. Automated checks can run continuously. Manual review ensures semantic naming and accessibility compliance.
What's the ROI of design tokens?
Benefits: faster design updates (change once vs hundreds of files), reduced bugs from inconsistency, easier theming, improved accessibility, and faster onboarding. Typical 30-50% reduction in design implementation time after adoption.