Book a call

WritingGovernancePart 3 of 3 in Growing adoption

Migrating legacy products onto a design system

Big-bang rewrites stall halfway and leave products with two systems. Migrate in layers instead: tokens first, then the most visible parts, then screen by screen, with codemods, warnings and an agreed end state for every product.

On this pageWhy big-bang migrations fail
  1. Why big-bang migrations fail
  2. Migrate in layers
  3. A migration plan across products
  4. Decide an end state for every product
  5. Make the new way the easy way
  6. Measure the whole portfolio
  7. The short version
  8. Frequently asked questions
  9. Further reading

The short answer

Don't migrate a legacy product onto a design system with a big-bang rewrite. Migrate in layers: tokens first (ship colours, type and spacing into the old product as CSS variables or a theme file, so it looks part of the family within weeks), then replace the most visible components as screens are touched (navigation, buttons, forms), with codemods for mechanical changes and warnings on old components. Track every product on one adoption dashboard, and agree an end state for each legacy product openly: full adoption, tokens only, or retirement.

  • Migrate as screens are touched for feature work, not in a separate project nobody funds.
  • Make the new way the easy way: a migration guide, an automated codemod and someone to ask.
  • Every deprecated component gets a replacement, a guide and a removal date.

Why big-bang migrations fail

Every company with a design system has an older product that can't adopt it quickly: different technology, no team assigned, or a rewrite planned "next year". The tempting answer is a migration project: freeze features, rebuild every screen on the new system, launch. It almost never works. The project competes with feature work, takes longer than planned, and gets cancelled halfway, leaving a product with two systems instead of one.

An illustration: the rewrite that stalled

The situation

A team plans a six-month project to rebuild its admin product on the new design system, starting with a full screen inventory.

What goes wrong

In month three, a customer deadline pulls half the team back to features. The project pauses with 40% of screens migrated. Users now see two buttons, two tables and two date pickers.

What works instead

Tokens shipped in two weeks so the whole product looks consistent; then each screen migrated when a feature touches it, with codemods doing the mechanical work. Slower on paper, finished in practice.

New word

A codemod is a script that rewrites code automatically: renaming a prop across a whole codebase, or swapping an old component import for a new one. Tools such as jscodeshift make them practical for JavaScript and TypeScript codebases.

Migrate in layers

1TokensShip token values into the old product as CSS variables or a theme file. Colours, type and spacing align quickly.
2Most visible partsNavigation, buttons, forms and alerts: where users notice inconsistency most.
3Screen by screenMigrate each screen when a feature touches it, with codemods doing the mechanical work.
4Remove the oldDeprecation warnings, then removal on a published date, once usage reaches zero.
Four layers of migration. Layer 1 gives most of the visible consistency for the least effort, which is why tokens come first.

Layer 1 works even when the legacy product uses a completely different framework. Tokens are just values; the token pipeline can generate them as CSS variables, a Sass file or a JavaScript theme for whatever the old product uses. See design tokens.

A migration plan across products

M1M2M3M4M5M6M7M8M9M10M11M12
Main web app · tokens
Main web app · screens
Admin tool · tokens
Admin tool · key parts
Old portal · tokens only
Old dropdowns · removal
Focused workAs screens are touched
A first-year migration across three products. Illustration Tokens go everywhere early; the main app migrates screen by screen with feature work; the old portal is agreed as "tokens only" because it's being retired; old dropdowns are removed on a published date.

Decide an end state for every product

For each legacy product, decide openly what "done" means. A clear plan is better than an endless "someday".

FULL ADOPTION

Products with a future

Actively developed, used by many customers. Migrate screen by screen until no old components remain.

TOKENS ONLY

Stable products

Rarely changed, but customers still see them. Tokens make them look part of the family; no component migration.

RETIREMENT

Products on the way out

Leave alone, or tokens only if retirement is far away. Don't spend migration effort on something being switched off.

Make the new way the easy way

Teams migrate when it's easier to migrate than not to. Each deprecated component should come with four things:

  1. A replacement that's actually better

    If the new component is missing something the old one did, teams won't move. Find out what before you deprecate.

  2. A migration guide

    Old props mapped to new ones, before-and-after code, and the visual differences to expect. Short, with examples.

  3. A codemod for the mechanical part

    Renames, import changes and prop mappings done automatically; people review the result and handle the judgement calls.

  4. A warning and a date

    A console or lint warning when the old component is used, and a removal date announced well ahead in the release notes.

// The old component still works, but says what to do
export function Dropdown(props) {
  warnOnce("Dropdown is deprecated and will be removed in 6.0. Use Select. Guide: /docs/migrate/select");
  return <Select {...mapDropdownProps(props)} />;
}

Notice the trick in that example: the old component is re-implemented on top of the new one. Teams that haven't migrated still get the new behaviour and accessibility fixes, and the eventual switch is just a rename, which a codemod handles. More on deprecation and version numbers in design system versioning.

Measure the whole portfolio

Leadership needs to see migration progress across the company, not just in the newest product. One simple dashboard is enough:

Main web app78%
Mobile app64%
Admin tool41%
Partner portal22%
Old portal (tokens only)done
Share of UI built from system components, per product. Illustration Measure against each product's agreed end state: the old portal is "done" because tokens only was the goal. Counting component imports with a script is usually enough.

Track two numbers per product: the share of screens (or component usages) on the system, and the number of deprecated components still in use. The second one tells you whether you can keep your removal dates.

In practice

At CARS24, changes were documented in Figma and Storybook and announced with a changelog and migration steps, as part of a governance model with one front door for requests. Read the case study.

The short version

  • Avoid big-bang rewrites; migrate in layers.
  • Tokens first: the fastest way to make a legacy product look part of the family.
  • Migrate screens as feature work touches them, with codemods for the mechanical part.
  • Every deprecated component gets a replacement, a guide, a warning and a date.
  • Agree an end state per product and track the whole portfolio on one dashboard.

Frequently asked questions

How do you migrate a legacy product to a design system?

Start with tokens, shipped into the old product as CSS variables or a theme file. Then replace the most visible components, migrate screens as feature work touches them, and remove old components on published dates.

Can a legacy product use the design system if it's built in a different framework?

Yes, at the token level. The token pipeline can generate values for any technology. Components may need wrappers or a later rebuild, but colours, type and spacing can align immediately.

How long should a deprecated component stay available?

Long enough for teams to plan the change: typically at least one or two release cycles, announced in advance, with usage tracked so you know when it's safe to remove.

Who pays for migration work?

Usually product teams do the migration as part of feature work, while the system team provides guides, codemods and support. Large migrations can justify dedicated help from the system team.

Further reading