The design system adoption problem: why Storybook isn't enough

Every design system story follows the same arc: a small, motivated team spends months building a beautiful component library. They write comprehensive Storybook stories. They publish an npm package. They send a Slack message announcing the launch.

And then, slowly, nothing happens.

Six months later, engineers are still copy-pasting the button component between projects. The design system has drifted from the product. Half the team doesn't know the table component exists. The Storybook site gets 12 visits a month, mostly from the people who built it.

I've seen this pattern repeat across multiple organisations. I've contributed to it myself. Here's what I've learned about what actually drives adoption.

The problem isn't the components

When adoption fails, the instinct is to blame the components. "We need better documentation." "The API is too complex." "We need more components."

These are real problems, but they're rarely the problem.

The real problem is almost always one of three things:

1. The system doesn't solve engineers' actual day-to-day problems
2. The migration path is too painful to be worth it
3. There's no social infrastructure around the system

Let me take each of these seriously.

1. Does it solve real problems?

Ask yourself: what does an engineer gain by reaching for your Button component instead of writing their own?

If the answer is "consistency" — that's not enough. Consistency is an abstract organisational benefit. Engineers optimise for their own productivity, not abstract organisational benefits. That's not selfishness; it's rational behaviour.

The components that get adopted are the ones that are harder to write correctly yourself than they are to use from the system. Accessibility-compliant modals. Data tables with sorting, filtering, and virtualisation. Date pickers that work across locales. Form validation patterns.

If your design system is mostly stateless display components (Badge, Card, Avatar), engineers will reach for it occasionally. If it contains the hard, stateful, accessibility-sensitive components that take two days to build correctly — they'll depend on it.

// A Badge component: easy to write, low adoption value
@Component({
  selector: 'ds-badge',
  template: `<span class="badge" [class]="variant">{{ label }}</span>`
})
export class BadgeComponent {}

// A ComboBox component: genuinely hard to build correctly (keyboard nav,
// ARIA attributes, virtualisation, locale-aware search) — high adoption value
@Component({
  selector: 'ds-combobox',
  // ... significant implementation
})
export class ComboboxComponent implements OnInit, AfterViewInit {
  // Keyboard navigation, ARIA management, virtual scroll...
}

Audit your component library against this question: for each component, would an engineer rather use yours or write their own? If the answer is "write their own" for more than a third of your components, you have a problem.

2. The migration path

Adoption requires engineers to do work now to gain benefits later. That's a hard sell in a roadmap full of product features.

The teams that succeed at adoption do one of two things: they make the migration trivially easy, or they make staying on the old approach progressively more painful.

Make migration trivially easy

The best design system adoption I've seen happened because the team built codemods. Not documentation — codemods.

npx @ourcompany/ds-migrate --from="legacy-button" --to="ds-button" ./src

A codemod that automatically rewrites imports, updates attribute names, and handles the most common variants removes the primary friction of migration. Engineers run it, review the diff, and move on.

ESLint rules as guardrails

We shipped an ESLint plugin alongside the design system that flagged direct DOM element usage where a design system equivalent existed:

// .eslintrc
{
  "plugins": ["@ourcompany/design-system"],
  "rules": {
    "@ourcompany/design-system/no-raw-button": "warn",
    "@ourcompany/design-system/no-raw-input": "warn"
  }
}

This doesn't break builds, but it creates a gentle, persistent nudge. New code uses the system; old code gets migrated during natural refactoring.

3. Social infrastructure

The most underrated driver of design system adoption is social, not technical.

The champion network

At every organisation where design system adoption succeeded, there was a named person on each product team whose job partly included being the design system advocate. Not a full-time role — 20% time at most. Their job was to:

• Know the system well enough to answer questions quickly
• Provide PR feedback when they spotted non-system patterns
• Escalate genuinely missing components back to the core team

This distributes the knowledge and creates accountability without creating a top-down mandate.

The RFC process

A design system dies when engineers stop trusting that their needs will be heard. The antidote is a lightweight RFC (Request for Comments) process for new components:

1. Engineer proposes a new component in a shared doc with: use case, proposed API, existing solutions reviewed
2. Core team + champions review within 5 business days
3. If accepted: core team builds it (or pairs with the engineer)
4. If declined: core team explains why and suggests an alternative

The key is speed. A two-week silence on an RFC is worse than a rejection. Engineers learn to route around slow systems.

Metrics that actually matter

Adoption metrics most teams track: npm install count, Storybook views, component usage count.

Metrics that actually matter:

• Time-to-first-correct-component for new engineers onboarding
• Bug rate in form flows using DS components vs. custom implementations
• Accessibility audit pass rate for DS-built pages vs. non-DS pages

The last one is particularly powerful. When you can show that pages built with the design system have a 94% accessibility audit pass rate vs. 61% for custom implementations, the adoption conversation changes entirely.

What the Storybook does and doesn't do

Storybook is genuinely excellent at one thing: interactive component documentation. Engineers can see components in all their states, copy usage examples, and understand the API surface.

It's not good at:

• Showing engineers when to use a component vs. a different one
• Explaining the reasoning behind API decisions
• Providing upgrade guides between major versions
• Answering "what's the right component for this design?" questions

These gaps need prose documentation, decision trees, and human answers — not more Storybook stories.

The systems I've seen drive sustained adoption all had a companion site (often a simple Next.js or Astro site) alongside Storybook, with:

• When to use / when not to use guidance per component
• Pattern pages showing how multiple components work together for real use cases (login forms, data tables, empty states)
• Migration guides with real diff examples
• Changelog written for engineers, not maintainers

The uncomfortable truth

Design systems are organisational change, not engineering projects. The technical work — building great components, writing solid documentation, publishing an accessible API — is necessary but not sufficient.

Sustainable adoption requires investment in the human systems around the technical ones: champions, RFCs, feedback loops, and the patience to let the system earn trust rather than mandate it.

The teams that treat design system adoption like a product launch — big announcement, then move on — consistently struggle. The teams that treat it like a long-term relationship — continuously earning usage through quality, listening to engineers, and making migration easier every sprint — consistently succeed.

---

Dealing with design system adoption challenges in your organisation? I write about this regularly and take occasional calls with teams working through this.