Skip to content
UX Atlas
Case studyCraft conventionAdvanced

Migrating Product Teams onto a Design System

A system team built a complete component library that nobody adopted, then changed the strategy from mandate to migration path.

Definition

A decision case about design system adoption: why a technically good library failed to be used, and what changed when the team treated adoption as a product problem.

Craft convention. True because the industry converged on it. Breaking it costs familiarity, not correctness.

A composite scenario assembled from situations that recur across teams. It is written to teach reasoning rather than to report on a named company, and outcomes are stated directionally rather than as invented measurements.

Problem

Eighteen months after launch, the design system was used in a small minority of the product surface. Teams knew it existed and continued building their own components.

Context

A large enterprise product with several product teams, a dedicated design system team of four, and a mandate from leadership that teams should use the system.

Constraints

  • No team could pause feature work for a migration project.
  • Several products used a different frontend framework from the one the system targeted.
  • The system covered around forty components; product teams collectively used far more.
  • The mandate existed but had no enforcement mechanism, and leadership was unwilling to create one.

Decision

Stop adding components. Spend a quarter on three things: a framework-agnostic token layer, a codemod for the five most-used components, and a two-hour response commitment on support requests.

Rationale

Adoption was failing for practical reasons, not for lack of components. Teams on a different framework could not use the library at all, migration required manual effort nobody had time for, and questions took days to answer so teams solved problems themselves. None of those were fixed by adding a forty-first component.

Evidence used

  • A codebase scan measuring what proportion of rendered elements came from the system, which was much lower than the team's estimate.
  • A count of forked components, which identified exactly which APIs were too rigid.
  • Interviews with engineers on non-adopting teams, who consistently named support latency and framework mismatch.
  • Time-tracking showing migration effort per screen, which was higher than anyone had assumed.

Trade-offs accepted

  • A quarter with no new components, which was uncomfortable to explain to stakeholders expecting output.
  • The token layer added indirection and a build step for teams already using the library.
  • The support commitment consumed roughly a third of one person's time permanently.

Outcome

Adoption rose steadily over the following two quarters, driven mostly by the codemod and by teams on the other framework becoming able to use tokens at all. Forks declined as the team used them as a backlog for API changes. The support commitment turned out to be the single most cited reason teams gave for adopting.

Alternatives considered

Enforce the mandate through code review

Why not: It produces minimum compliance and resentment, and it does not address the reasons adoption was failing. Teams route around enforcement they consider unreasonable.

Rebuild the system in every framework

Why not: Four people cannot maintain three implementations. Tokens gave the other framework most of the value at a fraction of the cost.

Fund a dedicated migration team

Why not: It was considered and would have worked, but it treats migration as a one-off project. The underlying friction would have returned with the next version.

Continue from here

Each link says what the connection is, so you can tell a principle from an alternative from a thing people mix this up with.

Applies when you are designing

An Enterprise Workflow

Concepts behind this decision

What the reasoning in this case rests on.