Every migration team has a favorite component they want to fix first — usually the one that's been embarrassing them in production for two years. Resist. The order in which components migrate determines whether the migration takes six months or two years.
Migrate high-volume primitives first. Once primitives are stable, composites built on top of them are mostly free.
Wave 1: typography, color, spacing tokens
Before any component migrates, the foundations have to be in place. CSS variables published, available, documented. This is the unglamorous step that the migration depends on.
Most teams ship this in week 1. The whole org should be able to reference --color-brand-primary or --space-md by the end of the first sprint.
Wave 2: high-volume primitives (Button, Input, Select)
Pick three or four components that ship on every product surface. Migrate them. Document them publicly. Run an internal launch.
These are the components that prove the system works. Adoption velocity will track whether these feel right.
Wave 3: layout primitives (Card, Stack, Grid)
Once primitives are stable, layout components built on top of them migrate next. Card composes Heading + Body + Footer slots, all referencing typography tokens. Stack uses spacing tokens.
Layout components without primitive coverage are wishful thinking. Don't ship Stack before space tokens are public.
Wave 4: complex composites (Modal, Form, DataTable)
Now the expensive ones. By the time you reach modals and tables, the team has six months of tokens, primitives, and layout components shipping in production. The composites have a stable foundation to build on.
Don't try to ship DataTable in week one. The DataTable migration is a six-month project on its own.
- 01Foundation tokens (typography, color, spacing) ship before any component.
- 02High-volume primitives (Button, Input, Select) come second — adoption velocity tracks how these feel.
- 03Layout components (Card, Stack, Grid) build on stable primitives.
- 04Complex composites (Modal, Form, DataTable) come last — give them a foundation to land on.