Design System Migration at Scale
Design System Migration at Scale
Moving 4 product teams from Bootstrap to a custom design system — without breaking anything.
Component inventory spreadsheet — 847 unique elements
Context
The company was a Series B startup with four product teams building different parts of a connected platform — a dashboard app, a mobile companion, an admin panel, and a public-facing marketing site. All four teams had started with Bootstrap and then layered on custom overrides as their products diverged. The result was chaos: 14 different button styles, 3 competing color palettes, and a typography system that varied not just between products but between pages within the same product.
Every new feature took longer than it should because designers couldn't reuse components across teams. Engineers spent hours debugging CSS specificity conflicts between Bootstrap's defaults and the custom overrides. The design team had grown from 2 to 11 people in eighteen months, and without a shared system, every new hire brought their own interpretation of the brand. I was brought in specifically to build a unified design system and lead the migration.
The tricky part: all four products were actively shipping features on two-week cycles. We couldn't freeze development for a migration. Whatever approach we chose had to work incrementally, team by team, component by component, without breaking anything in production.
Approach
I broke the migration into four phases, each building on the last:
- Audit — I spent three weeks cataloguing every UI component across all four products. The final inventory: 847 unique elements. Most were minor variations — a button with 2px more padding here, a card with a slightly different shadow there. I built a shared spreadsheet and tagged each element by frequency of use, visual similarity, and which teams used it.
- Converge — Using the audit data, I identified 43 canonical components that covered 95% of all use cases. Getting agreement required a week of design critiques, two workshops with engineering leads, and one very long meeting with the CPO.
- Build — I started with the foundations: typography, color tokens, spacing scale, and elevation. Then the most-used components — Button, Input, Card, and Modal covered about 60% of all UI surfaces.
- Migrate — Team by team. The admin panel team volunteered first. We wrote codemods to handle common migration patterns. The codemods handled about 70% of the migration automatically.
The convergence map — 847 elements → 43 canonical components
Lessons
Start with what people use most, not what's easiest to build. My instinct was to begin with simple, self-contained components like Badge and Tooltip. But the engineering teams didn't care about those — they wanted Button, Input, and Card because those appeared on every screen. Starting with high-frequency components meant the system felt useful from day one, which built the trust we needed for the harder migrations later.
Documentation is a product, not an afterthought. We built the component docs alongside the components themselves. Each component page included live examples, do/don't guidelines, and a migration guide from the old Bootstrap patterns. When teams could look up exactly how to migrate a specific pattern, adoption accelerated dramatically.
Naming is the hardest design problem. We spent more time debating component names and prop names than any other single decision. Should it be variant="danger" or variant="destructive"? Is it size="sm" or size="small"? These seem trivial, but inconsistent naming is how design systems become confusing. We eventually adopted a naming convention document that every new component had to follow.
Celebrate adoption, not just releases. We tracked "system coverage" — the percentage of UI surfaces using design system components versus legacy Bootstrap. We shared this number weekly in Slack, and teams started competing to increase their coverage. The dashboard team hit 90% coverage two weeks ahead of schedule.
"A design system is only as good as its adoption. Adoption is only as good as its developer experience."
The biggest lesson: Don't try to migrate everything at once. Start with the component teams use most. For us, that was Button.
