Migration Strategy
Convert an existing design system into an AI-ready system incrementally.
Key takeaways
- Migrate to an AI-first design system incrementally; big-bang migrations create too much risk.
- Start where AI generation already fails or where teams repeat the same UI patterns most often.
- Move through six phases: audit, normalize, specify, inject, verify, and govern, each with a concrete output.
- Migrate high-volume components, forms, navigation, data-display, and empty/loading/error states first.
- Avoid anti-patterns like translating every legacy doc up front or letting agents generate UI before token rules exist.
Moving to an AI-first design system is an incremental improvement process. Big-bang migrations create too much risk. Start with the surfaces where AI generation already fails or where teams repeat the same UI patterns.
Migration Phases
| Phase | Goal | Output |
|---|---|---|
| Audit | Understand current drift | Inventory and failure map. |
| Normalize | Align tokens and names | Semantic token proposal. |
| Specify | Make components machine-readable | Component specs and examples. |
| Inject | Make context available to agents | DESIGN.md, AGENTS.md, docs. |
| Verify | Catch generated UI regressions | Automated checks and screenshot review. |
| Govern | Sustain the system | Ownership and change policy. |
What to Migrate First
- High-volume components.
- Forms and validation patterns.
- Navigation and app-shell patterns.
- Data-display components.
- Empty, loading, and error states.
Anti-Patterns
- Translating every legacy doc before agents can use any of it.
- Allowing agents to generate UI before token rules exist.
- Creating new variants without deprecating old ones.
- Treating screenshots as optional for UI migration.
Success Metrics
- Fewer invented tokens and components.
- More generated UI passes on the first review.
- Lower design QA rework.
- Faster onboarding for new engineers and agents.