Build the smallest system that makes the product more coherent. Favor semantic contracts that components can use over a large inventory of decorative values.
Choose the Mode
- Extract when the product is visually coherent but undocumented.
- Reconcile when multiple patterns conflict.
- Create when a new product has no established UI language.
- Extend when a feature needs states or components the system lacks.
Workflow
- Inspect the framework, CSS strategy, theme files, primitives, component library, icon set, and representative screens.
- Inventory repeated values and patterns. Separate intentional variation from accidental drift.
- Map raw values to semantic roles before changing code. Example:
blue-600->action-primary, not "replace every blue." - Define the minimum token layers:
- foundations: color, type, spacing, radius, border, shadow, motion;
- semantic tokens: background, surface, text, border, action, focus, and status;
- component tokens only where a component genuinely needs them.
- Specify component anatomy, variants, sizes, and state behavior. Include content constraints, not only appearance.
- Define responsive behavior and density rules without inventing device-specific duplicates.
- Encode accessibility defaults: semantic elements, names, labels, focus-visible, keyboard behavior, contrast, errors, target size, and reduced motion.
- Implement inside the existing styling mechanism. Avoid parallel token systems.
- Migrate one representative component or screen and remove superseded values when safe.
- Verify light/dark themes, core states, narrow/wide layouts, and at least one realistic content stress case.
System Rules
- Name tokens by purpose, not by current appearance.
- Keep primitive escape hatches available, but make the correct path easier.
- Do not force every region into a card.
- Do not encode status through color alone.
- Keep component APIs small; prefer composition over variant explosions.
- Preserve established patterns unless they harm usability, accessibility, or maintainability.
- Document decisions where future contributors would otherwise recreate the inconsistency.
Delivery Contract
Provide:
- Mode and audit - what exists, what conflicts, and what remains.
- Token map - existing value -> semantic role -> implementation location.
- Component contract - anatomy, variants, states, content limits, responsive behavior.
- Migration slice - at least one real component when code changes are requested.
- Verification evidence - themes, states, viewports, and exceptions tested.
Reference
Read references/token-checklist.md while defining or auditing tokens and component states.