1. Purpose
To create a systematic mapping between design tokens and components so that every component:
- Inherits tokens (not manual styles).
- Syncs automatically with updates.
- Can be implemented in dev with 1:1 parity.
2. Why This Matters
- Without token → component linkage, libraries drift: buttons with custom hex, inputs with inconsistent spacing, etc.
- Devs then code “random values” → inconsistency across products.
- Sync Map ensures design = dev = QA parity.
3. Mapping Model
| Token Category | Token Name | Applied To | Component Examples | Notes |
| Color | Color-Primary | Fill, border | Button/Primary, Link/Active | Must meet contrast AA |
Color-Error | Fill, text, border | Input/Error, Alert/Error | Red used only for errors | |
| Typography | Font-Heading | H1–H3 | Card Titles, Modal Headers | Use consistent line height |
Font-Body | Body text | Inputs, Forms, Paragraphs | Base size = 16px | |
| Spacing | Space-2 (8px) | Gaps inside forms | Input fields, Cards | Base multiple = 8px grid |
Space-4 (24px) | Section padding | Modals, Cards | Used for container padding | |
| Radius | Radius-Small (4px) | Small interactive components | Buttons, Inputs | Subtle rounding |
Radius-Large (12px) | Larger modules | Cards, Modals | Friendly feel | |
| Shadows | Shadow-1 | Low elevation | Cards, Dropdowns | Soft subtle shadow |
Shadow-2 | High elevation | Modals, Tooltips | Prominent, layered |
4. Sync Workflow
- Design Stage
- Every component must inherit tokens directly (never raw values).
- Component builder checks: “Are all fills, borders, spacing = tokens?”
- Library Maintenance Stage
- Monthly audit (see Doc 10.4 Cleanup Checklist).
- Scan for overrides (random hex, manual font sizes).
- Dev Handoff Stage
- Export tokens in JSON/Style Dictionary format.
- Dev team implements same tokens in CSS/React Native/Flutter.
- Components mapped directly to code components.
5. Example – Button/Primary
| Element | Token Applied | Value (example) |
| Background | Color-Primary | #3B82F6 |
| Border Radius | Radius-Small | 4px |
| Font | Font-Button-Text | Inter 16px SemiBold |
| Padding | Space-2 vertical, Space-4 horizontal | 8px × 24px |
| Shadow | Shadow-1 | 0 1px 2px rgba(0,0,0,0.05) |
6. Governance
- No component can be approved if tokens ≠ are applied.
- Violations flagged in Component Review Log (Doc 10.8).
- Quarterly sync meeting with the dev team to check design–code parity.
7. Usage Notes
- Keep this map as a living doc, updated with new tokens/components.
- Share with both design & dev teams → it’s the bridge document.
- Store under:
Design System → Token–Component Maps.