Token migration brief
Move products to a new token system safely, with clear mappings, compatibility rules, validation, and cleanup milestones.
Design systems · 45 min · Advanced · 34 questions
Current system
Which tokens exist today?
Which aliases exist today?
Where are values hard-coded?
Which generated outputs do products use?
Which products consume the current tokens?
Mapping
Which old tokens have direct replacements?
Which old tokens must split by context?
Which old tokens should merge?
Which token meanings will change?
Which tokens will have no replacement?
Themes and platforms
Which themes must the new tokens support?
How should tokens resolve in dark mode?
How should tokens resolve in high-contrast mode?
Which platforms need generated token outputs?
Compatibility
How will old consumers keep working during migration?
Which temporary aliases are needed?
Which adapters are needed?
Which package versions can work together?
When will compatibility support end?
Migration tools
Which changes can a codemod make safely?
A codemod updates repeated code patterns automatically.
Which lint rules can prevent old token use?
How will design libraries be updated?
Which cases require manual review?
Validation
Which visual comparisons must pass?
Which contrast checks must pass?
Which type checks must pass?
Which product builds must pass?
Which cross-platform examples must match?
Rollout and cleanup
Which token consumers should migrate first?
How will remaining token usage be tracked?
What would pause the migration?
Who approves removal of the old aliases?
How will remaining consumers be handled?
What rollback remains after cleanup?
How to use this brief
Use this brief as a bank of questions for the conversation. Choose what is relevant, mark covered questions as you go, and skip anything that has already been answered.
Use this brief when...
Use when you need to move products to a new token system safely, with clear mappings, compatibility rules, validation, and cleanup milestones.
Best used as: Delivery checklist
- Category
- Design systems
- Discussion time
- 45 minutes
- Depth
- Advanced
- Last updated
- Jul 21, 2026
- Scope
- Design briefs
- Best used as
- Delivery checklist
- Design roles
- Design systems designer
- Audience
- Design leadsProduct designersUX and UI designers
- Platforms
- Design toolsWebiOSAndroid
- Company type
- B2BB2CEnterprise
- Product stage
- GrowthMature product
- Tags
- design-systemstoken-migrationdelivery-and-operationstoken-refactorbreaking-system-migration