Migration Guides make change less painful by showing teams exactly how to move from old tokens or patterns to the new system. They provide a side-by-side "before and after," call out deprecations, and reduce uncertainty. Use them when releasing updates, versioning the system, or phasing out legacy design and code so adoption happens with clarity and confidence.
Migration Guides
How to
-
Define the scope
Decide what's changing—tokens, patterns or processes. Use inputs from Release, Versioning, or Retire and Replace.
-
Map old → new
Create a clear side-by-side comparison with names, screenshots, or code snippets.
- AI can generate codemod scripts that automate find-and-replace migrations, saving significant manual effort.
-
Highlight deprecations
Mark what's being removed and when, so teams can plan.
-
Flag effort levels
Label changes as low, medium, or high effort to set realistic expectations.
-
Provide recipes and support
Show "replace this with that" examples, where relevant include linking to guidance and specs for detail and how-to guides to ensure smooth migration.
- Scan codebases to generate team-specific migration reports with effort estimates
-
Publish and support
Add the guide to your Guidance Setup, announce through System Updates and/or Release, and equip System Champions and Advocates to coach others.
Automate migrations: AI's excellent at generating migration code and finding all usage instances. You still need to handle edge cases, custom implementations, and support teams through changes.