How do you scale a design system across multiple teams
Design tokens + accessible primitives + clear ownership. Single source of truth for tokens (JSON → CSS vars + platform exports), unopinionated headless primitives, contribution model with RFCs + versioning, governance (a small core team), Storybook + visual regression, and automated migration codemods. Treat the DS as a product with its own roadmap, not a side project.
A design system serves N consuming teams — its success is measured by adoption and velocity unlocked, not output. Scaling it is a product + governance problem more than a code problem.
Layers
- Tokens — colors, spacing, radii, typography, motion as JSON. Exported to CSS vars, Tailwind config, iOS/Android equivalents via Style Dictionary or similar.
- Primitives — Button, Input, Modal, Tooltip, Dialog, Popover. Accessible (built on Radix / Ariakit / Headless UI). Unopinionated styling so brands can theme.
- Patterns — composed templates (FormRow, EmptyState, DataTable cells).
- Recipes — page-level examples in docs, not in the library.
Keep the boundary clear: library ships primitives, not pages.
Ownership model
- Small core team (2–4 engineers + designer) owns the system.
- Contributing teams add components via an RFC + PR process.
- Office hours weekly for design + engineering questions.
- CODEOWNERS so DS team reviews changes.
Distribution
- Monorepo with versioned packages (Changesets) or single package with semver.
- Consumers pin a version; major bumps come with codemods.
- Snapshot a "stable" docs site per major.
Governance
- RFCs for new primitives or breaking changes. Markdown in a
design-system/rfcrepo. - ADRs for internal decisions.
- Deprecation policy — warn for a release, remove the next major.
- Public roadmap consumers can see.
Quality gates
- Storybook for every component.
- Visual regression (Chromatic / Playwright snapshots) — catches accidental UI drift.
- A11y CI (axe / Storybook a11y addon).
- Bundle size budget per component.
Adoption levers
- Codemods that migrate consumers to new APIs (jscodeshift).
- Linter rules that warn on raw colors / spacing (
no-restricted-syntaxagainstcolor: #...). - "Use the DS" CI check that fails PRs adding new shadow/border-radius values not in tokens.
Migration patterns
- Adapter layer for legacy teams during transition.
- Coexistence — both old and new live during the migration window.
- Internal newsletter / changelog so teams see what's new.
Cross-platform
- If iOS/Android share the system: keep tokens as the single source; ship platform-specific component packages downstream.
- Don't try to share component code across web + mobile — abstraction cost > value.
Anti-patterns
- DS team building bespoke screens for consumers — kills focus.
- Components with 30 props because every team added theirs — extract via composition or recipes.
- "Just one more" snowflake variant — every yes costs maintenance.
Interview framing
"Tokens are the contract — JSON source of truth, generated for every platform. Primitives are accessible, headless, themed via tokens. A small core team owns the system as a product; new components come through RFCs with deprecation policy. Quality is enforced via Storybook + visual regression + a11y CI + bundle budgets. Adoption is enforced via codemods, lint rules, and deprecation warnings. Track adoption + velocity unlocked, not component count."
Follow-up questions
- •How would you handle a team that needs a one-off variant?
- •What does a deprecation policy look like?
- •How do you measure DS adoption and ROI?
Common mistakes
- •Treating the DS as a side project.
- •Letting every team contribute primitives without governance — API drifts.
- •No visual regression — accidental redesigns ship.
- •Building pages, not primitives.
Performance considerations
- •Tree-shakable exports so consumers only ship what they import. Per-component bundle budget. Avoid 'one big bundle' libraries.
Edge cases
- •Brand/theme variants for the same product line.
- •Acquired apps with their own DS that must coexist.
- •i18n with right-to-left layouts.
Real-world examples
- •GitHub Primer, Shopify Polaris, Atlassian Atlaskit, Material UI, Adobe Spectrum.