Building the components is the half of the work people see. Getting them adopted across multiple product teams is the half of the work that determines whether the system is alive or just published.
Distribution is a product problem with the same shape as any other developer-facing API: discovery, trial, integration, ongoing support, version migration.
The artifact
An npm package (or several — primitives, components, icons), a Figma library, a docs site with code examples, and per-component changelogs. Without all four, adoption stalls.
shadcn-style copy-paste registries are the alternative to npm packages. Trade-off: teams own the code (good for customization, bad for centrally pushing fixes). The token generator's component registry is one example.
Versioning: strict semver
Major bumps for breaking changes (renamed props, removed components, changed render output). Minor for additive changes. Patch for bug fixes that don't change visual output.
Document upgrade paths for every major bump. "Run this codemod" is the gold standard. "Replace these props by hand" is the adoption-killer.
The adoption funnel
Discovery: docs site comes up in internal search, design system links from your engineering wiki, the team is in slack channels people actually read.
Trial: the install command works on a fresh machine in under five minutes. The button-and-input demo runs without yak-shaving.
Adoption: a real product surface ships using the system. Track this — it's the only metric that matters.
Contribution: external teams can propose changes through a documented RFC process. Don't accept PRs without an RFC.
Forcing functions
ESLint rules that flag raw color hex values. Component-usage dashboards. PR templates that ask 'is this using the design system?'. Quarterly office hours where the team helps adopters integrate.
Adoption doesn't happen because the system is good. It happens because using the system is the path of least resistance.
- 01An npm package, a Figma library, a docs site, and changelogs — all four or adoption stalls.
- 02Strict semver. Codemods for breaking changes. Document upgrade paths.
- 03The only adoption metric that matters: percentage of product UI surfaces using the system.
- 04Forcing functions (lint rules, PR templates, dashboards) move the curve more than docs do.