Chapter 16: Adoption & Migration

Core Idea

Building the system is the easy half — getting existing products to actually adopt it, and migrating off deprecated patterns without breaking production, requires a deliberate rollout strategy, tooling (codemods), and a way to measure whether adoption is actually happening.

Key Concepts

• Gradual rollout over big-bang replacement: adopting a design system inside an existing, shipping product is almost always safer done incrementally (new features first, then opportunistic replacement during other work) than as a dedicated, high-risk rewrite sprint.
• Codemods: automated code-transformation scripts (e.g. via jscodeshift) that mechanically rewrite old component usage into new component usage across a codebase — turns a manual, error-prone migration (find every usage, update by hand) into a repeatable, reviewable script.
• Deprecation windows: pairing a deprecation warning (console warning, lint rule, or TypeScript @deprecated tag) with a real removal date gives consuming teams a visible, time-boxed signal instead of an open-ended "eventually update this."
• Measuring adoption: tracking real usage (e.g. static analysis of which components/versions are imported across the org's repos) rather than assuming adoption from the system's existence — this is what tells a system team whether governance/communication is actually working.
• Champions/embedded advocates: teams that succeed at adoption often have a design-system advocate embedded in each consuming team, rather than relying on the central team to police every codebase.

Mental Models

Adoption is a change-management problem, not a technical rollout. The system being technically ready doesn't mean teams will actually switch — that requires the same intentional communication and incentive alignment as any organizational change.

A deprecated pattern with no removal date never actually gets removed. Pair every deprecation with a concrete, communicated timeline, or it becomes permanent technical debt everyone quietly ignores.

Anti-patterns

• Big-bang migrations with no incremental path: a mandate to migrate everything at once, on a fixed deadline, tends to produce rushed, incomplete, or reverted migrations.
• Deprecating without a codemod for mechanical cases: forcing every team to hand-migrate a simple prop rename wastes effort a script could have done safely and consistently.

Key Takeaways

1. Roll a design system into an existing product gradually — new work first, opportunistic replacement second — rather than as a single risky rewrite.
2. Invest in codemods for any migration with mechanical, high-volume patterns — it's cheaper than the aggregate manual cost across every consuming team.
3. Always pair deprecation with a concrete removal date; an open-ended deprecation notice doesn't drive migration.
4. Actually measure adoption (real import/usage data) instead of assuming it — this is the feedback loop that tells governance whether it's working.

Connects To

• Ch 14 (Versioning & Governance): the deprecation/removal mechanics this chapter's rollout strategy depends on.
• Ch 10 (Maintaining Design Systems): "make it visible" — adoption depends on teams knowing the system exists and where it's headed.