Every legacy product UI is a museum of accumulated decisions. Three button styles that look identical but render with different padding. Five card components built by five teams over five years. Two form-validation patterns, one of which is a half-finished refactor someone abandoned in 2021. The migration starts with an honest inventory of what you actually have.
Audit before architecture. The migration plan you write before the audit is the migration plan you'll throw out three months in.
Inventory components, not pages
Walk every product surface and list every component — Button, Input, Card, Modal, Toast — that gets used. Note variants that should be the same component but aren't (PrimaryButton vs Button with primary prop). The output is a flat spreadsheet, not a Figma file.
Count instances. The Button used on 800 pages is not the same migration as the Banner used on 3 pages. Volume tells you sequence.
Inventory tokens — primitives and semantics
Same audit, color and spacing layer. Pull every hex value from the codebase. Pull every spacing value (px, rem, em). Group near-duplicates: #4f46e5 and #5046e5 are probably the same color, just typo'd.
Most teams discover they have ~80 colors when they expected ~20. That's the gap the system has to close.
Map ownership
Each component has a current owner — usually informally. Track them down. The migration won't happen by talking to design or platform; it happens by talking to the team that ships the surface using the component.
If three teams all own the same Card with three different implementations, the migration starts with a conversation between them, not with code.
Score the migration cost
For each component, score: complexity (1-3), instances (low/med/high), API surface (compatible / partially / breaking). The cheapest migrations are high-instance simple components with compatible APIs — Button, Input. The expensive ones are low-instance complex components with breaking APIs — Modal, DataTable.
Sequence the work: cheap-and-high-impact first, build momentum, then tackle the expensive ones with the team's buy-in already won.
- 01Inventory components and tokens flatly — every variant, every instance, every hex value.
- 02Map current ownership of each component before proposing changes.
- 03Score migrations by complexity × instance count × API compatibility.
- 04Sequence cheap-and-high-impact first to build momentum before tackling the expensive cases.