The engineering team has product features to ship. The design system team has a migration to run. These two priorities will conflict every week of the migration unless the path is engineered specifically to keep them from conflicting.
The migration that ships is the one that lets product teams keep working at full speed while the system catches up underneath them.
Codemods do the boring 80%
Per-component codemods that handle the mechanical replacements: prop renames, import path changes, deprecated wrapper removals. Run them per-team, per-PR, on a cadence the team controls.
Document the codemod with a one-line invocation and a link to the changes it makes. The team should be able to run it without asking the platform team for help.
Escape hatches for the unhappy 20%
Some components have product-specific behavior that doesn't fit the new component. Provide an explicit escape hatch — a 'legacy' import path or a 'use-legacy' prop — that opts out of the new component cleanly.
Document the escape hatch as a temporary state with a planned removal. Teams that need it can use it; the migration tracker shows it as still-pending.
Branch protection and per-component dashboards
Add a CI check that lists files still importing legacy components. Surface the count in a dashboard the leadership team sees weekly.
Without visibility, the migration disappears under product work. With weekly numbers, the conversation happens at the right level.
Office hours and pair-migrations
Reserve a recurring slot — twice a week, an hour each — where the design-system team helps adopters migrate. Real screens, real PRs, real questions.
The platform team will spend more time supporting adopters than building components in the first six months. That's the migration; the components were the easy part.
- 01Codemods handle the mechanical 80% — document the invocation, run them per-team.
- 02Escape hatches let the unhappy 20% opt out cleanly without blocking the migration.
- 03Per-component dashboards keep the migration visible in leadership conversations.
- 04Office hours and pair-migrations are how the system actually moves — not docs.