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.
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.
-
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.
-
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.