Design System Migration Plan

When to Use

• Upgrading to a new major version of your design system
• Moving from one component library to another (e.g., Material to custom)
• Migrating token formats (e.g., Tokens Studio to Style Dictionary)
• Consolidating multiple design systems into one

The Prompt

Create a detailed migration plan for the following design system change:

**From:** [current system/version/tool]
**To:** [target system/version/tool]
**Scope:** [tokens only / components / full system]
**Team size:** [number of designers + engineers]
**Products affected:** [list products/apps]
**Timeline constraint:** [desired completion date or "flexible"]

Include:

1. **Impact assessment** — What breaks? What's deprecated? What's new? Rough % of codebase affected.
2. **Migration phases** — Break into phases with clear milestones. Each phase should be deployable independently.
3. **Token mapping table** — Old token name to new token name, with any value changes noted.
4. **Codemods / automation** — What can be automated? Provide regex or codemod pseudocode.
5. **Risk register** — Top 5 risks with likelihood, impact, and mitigation.
6. **Testing strategy** — Visual regression, accessibility, functional testing approach.
7. **Rollback plan** — How to revert each phase if something goes wrong.
8. **Communication plan** — Who to notify, when, and what they need to do.
9. **Definition of done** — How you know each phase is complete.

Format as a Markdown document I can share with stakeholders.

Example Output

# Migration Plan: Design Tokens v1 to v2

## Impact Assessment
- 47 tokens renamed, 12 tokens removed, 8 new tokens added
- Estimated 60% of component styles affected
- 3 products, ~200 component files

## Phase 1: Alias Layer (Week 1-2)
- Add v2 tokens as aliases pointing to v1 values
- No visual changes, no breaking changes
- Teams can start adopting new names immediately
- Done when: All v2 names resolve correctly

## Phase 2: Gradual Adoption (Week 3-6)
- Replace v1 token references with v2, product by product
- Codemod: find `--color-primary` replace `--color-brand-primary`
- Run visual regression after each product
- Done when: No v1 references remain in Product A

## Phase 3: Deprecation (Week 7-8)
- Mark all v1 aliases as deprecated (console warnings)
- Done when: All products migrated, zero v1 usage

## Phase 4: Removal (Week 9-10)
- Remove v1 tokens entirely
- Run full test suite
- Done when: Clean build with no deprecated token warnings

## Risk Register
| Risk                       | Likelihood | Impact | Mitigation                    |
|---------------------------|------------|--------|-------------------------------|
| Missed token in codemod   | High       | Medium | Visual regression catches it  |
| Third-party theme breaks  | Medium     | High   | Keep aliases for one release  |
| Team doesn't adopt in time| Medium     | Low    | Extend alias period           |