Design Tokens at Scale: Lessons from Migrating 200 Components
We migrated a five-year-old design system to tokens. Here's what we'd do differently — and what was worth the pain.
Sofia Reyes
Tokens look simple in a slide deck. In a real codebase with 200 components, five product teams, and three years of "temporary" hex codes, they're a project.
What we got right
- Started with a token taxonomy doc, not a script. Naming is 60% of the work.
- Migrated one component family at a time — buttons first, because they exposed the most colour assumptions.
- Built an auto-codemod for the obvious replacements (hex → token reference). Saved weeks.
What we'd do differently
We waited too long to involve product teams. By the time we shipped, several teams had built around the old system. Half of our energy went into "tokens for them" rather than "tokens with them".
If you're starting now: announce early, ship a small slice, and let people opt in.
Related articles.
DesignTypography Pairing in Five Minutes (Without Losing Your Mind)
A repeatable framework for choosing two fonts that work together — without the analysis-paralysis tour of Google Fonts.
DesignThe Underrated Craft of Interface Copy
The best UX writing isn't clever — it's invisible. Three rules we use to write button labels, error messages, and empty states.
DesignColor Systems That Survive Dark Mode
Your light palette is half a system. Here's how to design tokens that work in both modes — without doubling your work.