Design System Governance
A design system without governance becomes one of two things within eighteen months: a bottleneck that product teams route around, or a free-for-all that contains four slightly different modals. Governance is the set of decisions about who can change the system, how changes are proposed and reviewed, how they are released, and how consumers move from one version to the next. It is the difference between a component library and a design system.
The technical pages in this section — Component Patterns, Color Tokens, Dark Mode — describe what to build. This page describes how to keep it alive.
Why Governance Fails (and Why It Matters)
flowchart LR
subgraph TOO_TIGHT["Too tight"]
T1["Every change needs<br/>core team approval"] --> T2["6-week backlog"]
T2 --> T3["Teams fork components<br/>locally"]
T3 --> T4["System is bypassed"]
end
subgraph TOO_LOOSE["Too loose"]
L1["Anyone merges<br/>anything"] --> L2["Inconsistent APIs,<br/>duplicate components"]
L2 --> L3["Breaking changes<br/>in minor releases"]
L3 --> L4["Teams pin old versions<br/>forever"]
end
Both failure modes end in the same place: product teams stop upgrading, the system's surface area fragments, and the promised consistency never materializes. Good governance is calibrated: strict on the things that are expensive to change later (public APIs, token names, accessibility behavior), permissive on the things that are cheap (internal implementation, documentation, examples).
| Decision type | Cost of getting it wrong | Governance weight |
|---|---|---|
| New public component | High — every consumer couples to its API | RFC + design and engineering review |
| New prop on an existing component | Medium — hard to remove later | Lightweight proposal + API review |
| New semantic token | High — names propagate into every theme | Token council review |
| Primitive token value change | Medium — visual regressions everywhere | Visual diff review |
| Bug fix | Low | Normal code review |
| Docs, examples, stories | Low | Normal code review, any contributor |
Governance Models
There are three common models. Most mature systems end up hybrid.
flowchart TB
subgraph C["Centralized"]
CT["Core team"] --> CP1["Product team A"]
CT --> CP2["Product team B"]
CT --> CP3["Product team C"]
end
subgraph F["Federated"]
FA["Team A designers/devs"] <--> FB["Team B designers/devs"]
FB <--> FC["Team C designers/devs"]
FA <--> FC
FA --> FS["Shared system"]
FB --> FS
FC --> FS
end
subgraph H["Hybrid"]
HC["Small core team<br/>(owns foundations,<br/>releases, quality bar)"]
HA["Contributors from<br/>product teams"] -->|"RFCs, PRs"| HC
HC -->|"releases"| HP["Product teams"]
end
| Model | Who builds | Who decides | Strengths | Weaknesses | Fits when |
|---|---|---|---|---|---|
| Centralized | Dedicated core team | Core team | High consistency, coherent API, clear ownership | Bottleneck; core team drifts from product reality | Early system, < ~10 product teams, strong brand requirements |
| Federated | Product teams | Cross-team council | Reflects real needs; scales contribution | Slow decisions, inconsistent quality, nobody owns releases | Many senior teams, no budget for a core team |
| Hybrid | Core team builds foundations; product teams contribute components | Core team sets the bar and owns releases; council for big decisions | Scales while keeping quality | Requires mature contribution process | Most organizations past ~50 engineers on the frontend |
Start centralized, design for hybrid
A brand-new system needs a coherent voice; committees do not produce coherent APIs. But build the contribution process (templates, review checklists, CI) from day one, so you can open the doors when demand outgrows the core team — which, if the system is succeeding, it will.
Ownership Tiers
A practical hybrid pattern is to give components an explicit ownership tier, visible in the docs:
| Tier | Ownership | Quality bar | Versioning | Example |
|---|---|---|---|---|
| Core | Core team | Full a11y audit, visual tests, docs, design spec, RTL, dark mode | Strict semver, deprecation policy | Button, TextField, Dialog, tokens |
| Shared / community | Contributing team, core reviews | Core checklist minus some polish; owner listed | Semver, shorter deprecation window | DataGrid extensions, DateRangePicker |
| Labs / experimental | Anyone | Works, has a story | No stability guarantee; import from /labs | New patterns being validated |
| Product-local | Product team | Product team's choice | Not in the system | One-off marketing layouts |
Labs is the pressure valve: teams can share something useful immediately without waiting for full review, and the core team gets evidence about what deserves promotion.
Contribution Process
The Lifecycle of a Contribution
flowchart LR
IDEA["Need identified<br/>in a product team"] --> CHECK{"Exists already<br/>or composable?"}
CHECK -->|"yes"| USE["Use / compose<br/>existing components"]
CHECK -->|"no"| SIZE{"Size of change"}
SIZE -->|"small: bug, prop,<br/>variant"| ISSUE["Issue + PR"]
SIZE -->|"large: new component,<br/>new token category,<br/>breaking change"| RFC["RFC"]
RFC --> REVIEW["Design + eng review<br/>(1-2 weeks)"]
REVIEW -->|"accepted"| LABS["Build in labs"]
REVIEW -->|"rejected"| LOCAL["Build product-local;<br/>revisit with evidence"]
LABS --> VALIDATE["Used by >= 2 teams"]
VALIDATE --> PROMOTE["Promote to core<br/>(audit, docs, tests)"]
ISSUE --> PR["PR review"]
PR --> RELEASE["Released"]
PROMOTE --> RELEASE
The two-team rule. A component earns a place in the system when at least two product teams need it. One team's need is a product-local component; a system component built for one consumer bakes that consumer's assumptions into everyone's API.
RFC Template
Large changes start as an RFC — a markdown file in the system repo (rfcs/0042-combobox.md), discussed in a PR so the history is preserved.
# RFC 0042: Combobox
- **Status:** Draft | In review | Accepted | Rejected | Superseded by RFC NNNN
- **Author(s):** @name (Team Checkout)
- **Reviewers:** design-system-core, accessibility-guild
- **Created:** 2026-10-02
## Summary
One paragraph. What is being proposed?
## Motivation
- Which teams need this? Link to at least two concrete product use cases.
- What are they doing today? (Screenshots of the current local implementations.)
- What breaks or is inconsistent without it?
## Prior art
- Existing components in our system that come close and why they are insufficient.
- How Radix, React Aria, MUI, Carbon, and the WAI-ARIA Authoring Practices handle it.
## Design
- Figma link to the spec: anatomy, states (default, hover, focus, disabled, error,
loading), density variants, responsive behavior, dark mode.
## API proposal
- Component signature and props table.
- Composition model (compound components? slots?).
- Controlled and uncontrolled usage examples.
## Accessibility
- ARIA pattern and roles; keyboard interactions table; screen reader announcements.
- Known assistive technology quirks.
## Tokens
- New tokens required (should be rare). Existing tokens reused.
## Migration / impact
- Is anything deprecated? Codemod needed? Which packages bump which version?
## Alternatives considered
- Including "do nothing" and "teams keep local implementations."
## Unresolved questions
Review Checklist
Every component PR (and every RFC before acceptance) is checked against the same list. Publish it; contributors should be able to self-review.
| Area | Check |
|---|---|
| API | Follows naming conventions (variant, size, onValueChange); supports controlled and uncontrolled where stateful; forwards refs; spreads remaining props to the root element; no boolean props that should be an enum |
| Composition | Uses existing primitives (Box, Stack, Text) and patterns from Component Patterns |
| Tokens | No hardcoded colors, spacing, radii, or durations; only semantic tokens (see Semantic Tokens) |
| Theming | Works in light, dark, and high-contrast themes; see Dark Mode token mapping |
| Accessibility | Keyboard operable; visible focus; correct roles; axe passes; manual screen reader check; see Testing Accessibility |
| Internationalization | No hardcoded strings; RTL layout; long-text overflow handled |
| Testing | Unit tests for behavior; stories for every state; visual snapshots |
| Docs | Usage guidelines (when to use, when not to), props table, do/don't examples |
| Bundle | Tree-shakeable; size delta reported in CI |
Semantic Versioning for Components and Tokens
Semver is a contract: MAJOR.MINOR.PATCH, where a major bump means "you may need to change your code." The hard part is deciding what counts as breaking for UI, which is much fuzzier than for a function signature.
What Counts as Breaking
| Change | Bump | Reasoning |
|---|---|---|
| Remove a component, prop, or token | Major | Code stops compiling or working |
| Rename a prop or token | Major (or minor with alias + deprecation) | Same as remove, unless an alias keeps the old name working |
| Change a prop's type to be narrower | Major | Previously valid values now rejected |
| Change default value of a prop | Major if behavior or layout visibly changes | Consumers relied on the default implicitly |
| Change DOM structure that consumers may target | Major if documented as stable; otherwise minor | Publish which DOM/class names are public API (ideally none) |
| Add a new optional prop, component, or token | Minor | Additive |
| Widen a prop's accepted type | Minor | Additive |
| Visual change within the design spec (spacing tweak, shadow) | Minor with visual changelog entry | Not breaking for code, but can break layouts and screenshot tests |
| Bug fix that changes behavior people relied on | Patch, but call it out | Judgement call; when many consumers depend on the bug, consider minor |
Accessibility fix (adding aria-*, focus management) | Patch or minor | Never hold accessibility fixes back for a major |
| Internal refactor, no API or visual change | Patch |
Visual changes are API changes for some consumers
A product team with screenshot tests sees a 1px padding change as a failed build. Treat visual changes as at least minor, document them with before/after images in the changelog, and give consumers a way to preview them (a canary release or a Chromatic build link) before they ship.
Package Topology
| Strategy | Example | Pros | Cons |
|---|---|---|---|
| Single package | @acme/ui@4.2.0 | One version to reason about; no compatibility matrix | Any breaking change bumps everything; big upgrades |
| Per-component packages | @acme/button@2.1.0, @acme/dialog@5.0.0 | Upgrade one component at a time | Dependency hell; mismatched internal versions; duplicated deps in bundles |
| Few layered packages | @acme/tokens, @acme/primitives, @acme/components, @acme/icons | Separate cadence for tokens vs components; manageable matrix | Must coordinate cross-package releases |
The layered approach is the common middle ground. Tokens change rarely and are consumed by non-React platforms (iOS, Android, email templates), so they deserve their own versioned package.
flowchart BT
TOK["@acme/tokens<br/>JSON, CSS vars, Swift, Kotlin"] --> PRIM["@acme/primitives<br/>Box, Stack, Text, VisuallyHidden"]
TOK --> ICONS["@acme/icons"]
PRIM --> COMP["@acme/components<br/>Button, Dialog, Combobox..."]
ICONS --> COMP
COMP --> LABS["@acme/labs<br/>0.x, no guarantees"]
COMP --> APPS["Product apps"]
TOK --> NATIVE["iOS / Android apps"]
Versioning Tokens
Tokens have their own breaking-change semantics, because consumers reference them by name:
| Token change | Bump | Notes |
|---|---|---|
| Add a token | Minor | |
Change a primitive's value (blue-600 hex) | Minor (visual) | Every semantic token aliasing it changes |
| Change which primitive a semantic token aliases | Minor (visual) | This is the intended way to restyle |
| Rename or remove a token | Major | Keep the old name as a deprecated alias for one major cycle |
| Change a token's type (color to gradient) | Major | Breaks platform transforms |
{
"color": {
"text": {
"subtle": {
"$type": "color",
"$value": "{color.gray.600}",
"$description": "Secondary text: captions, helper text"
},
"secondary": {
"$type": "color",
"$value": "{color.text.subtle}",
"$deprecated": "Use color.text.subtle. Removed in tokens v5.0.0."
}
}
}
}
The $deprecated field (from the W3C Design Tokens Community Group format) lets the build pipeline emit warnings, add /* @deprecated */ comments to generated CSS, and drive lint rules.
Deprecation and Migration
Breaking changes are inevitable. What makes them survivable is a predictable deprecation policy and tooling that does most of the migration for consumers.
Deprecation Policy
timeline
title Lifecycle of a deprecated prop
v4.3 : New API added (variant="ghost")
: Old API still works (subtle={true})
v4.4 : Old API marked deprecated
: Dev-mode console warning
: Lint rule + codemod published
v4.x : Adoption dashboard tracks remaining usages
: Core team opens PRs on top consumers
v5.0 : Old API removed
: Migration guide links codemod
A concrete written policy prevents arguments later:
- Nothing is removed without at least one minor release in which it is deprecated with a warning, and at least N months (commonly 3-6) of notice.
- Every deprecation ships with: a console warning in development builds, a lint rule, a migration note, and — when the change is mechanical — a codemod.
- Majors are batched and scheduled (for example, at most two per year), announced in advance, with a migration guide published before the release.
- The previous major receives security and critical accessibility fixes for a defined window after a new major.
Dev-only warnings that do not spam:
// packages/components/src/internal/deprecate.ts
const warned = new Set<string>();
export function deprecate(id: string, message: string): void {
if (process.env.NODE_ENV === 'production') return;
if (warned.has(id)) return;
warned.add(id);
console.warn(`[@acme/components] ${message} See https://design.acme.dev/migrations#${id}`);
}
// packages/components/src/button/Button.tsx
export function Button({ subtle, variant, ...rest }: ButtonProps) {
if (subtle !== undefined) {
deprecate('button-subtle', 'Button `subtle` is deprecated; use variant="ghost". Removed in v5.');
}
const resolved = variant ?? (subtle ? 'ghost' : 'solid');
return <ButtonImpl variant={resolved} {...rest} />;
}
Codemods
A codemod is a program that rewrites consumer code. For mechanical changes — renamed props, moved imports, renamed tokens — it turns a week of migration into a single command. jscodeshift is the long-standing standard for JavaScript and TypeScript:
// codemods/v5/button-subtle-to-variant.ts
// Usage: npx jscodeshift -t button-subtle-to-variant.ts --parser=tsx src/
import type { API, FileInfo, JSXAttribute } from 'jscodeshift';
export default function transform(file: FileInfo, api: API) {
const j = api.jscodeshift;
const root = j(file.source);
// Only touch files that import Button from our package
const localNames = new Set<string>();
root
.find(j.ImportDeclaration, { source: { value: '@acme/components' } })
.find(j.ImportSpecifier, { imported: { name: 'Button' } })
.forEach((p) => localNames.add(p.node.local?.name ?? 'Button'));
if (localNames.size === 0) return file.source;
let changed = false;
root.find(j.JSXOpeningElement).forEach((path) => {
const name = path.node.name;
if (name.type !== 'JSXIdentifier' || !localNames.has(name.name)) return;
const attrs = path.node.attributes ?? [];
const idx = attrs.findIndex(
(a): a is JSXAttribute => a.type === 'JSXAttribute' && a.name.name === 'subtle',
);
if (idx === -1) return;
const attr = attrs[idx] as JSXAttribute;
const hasVariant = attrs.some((a) => a.type === 'JSXAttribute' && a.name.name === 'variant');
// <Button subtle> or <Button subtle={true}> -> variant="ghost"
const isTrue =
attr.value === null ||
(attr.value?.type === 'JSXExpressionContainer' &&
attr.value.expression.type === 'BooleanLiteral' &&
attr.value.expression.value === true);
if (isTrue && !hasVariant) {
attrs[idx] = j.jsxAttribute(j.jsxIdentifier('variant'), j.stringLiteral('ghost'));
changed = true;
} else if (!isTrue) {
// Dynamic value (subtle={isQuiet}): cannot be rewritten safely; leave for a human
const line = path.node.loc?.start.line ?? '?';
console.warn(`${file.path}:${line}: dynamic \`subtle\` prop needs manual migration`);
}
});
return changed ? root.toSource({ quote: 'single' }) : file.source;
}
Test codemods with fixtures — an input file and the expected output — exactly as you test components:
// codemods/v5/__tests__/button-subtle-to-variant.test.ts
import { defineInlineTest } from 'jscodeshift/src/testUtils';
import transform from '../button-subtle-to-variant';
defineInlineTest(
transform, {},
`import { Button } from '@acme/components';\nconst a = <Button subtle>Hi</Button>;`,
`import { Button } from '@acme/components';\nconst a = <Button variant='ghost'>Hi</Button>;`,
'converts boolean subtle to variant ghost',
);
defineInlineTest(
transform, {},
`import { Button } from 'other-lib';\nconst a = <Button subtle />;`,
`import { Button } from 'other-lib';\nconst a = <Button subtle />;`,
'ignores Buttons from other packages',
);
| Migration type | Tooling |
|---|---|
| JSX prop / import renames | jscodeshift, ts-morph, ast-grep |
CSS custom property renames (--acme-color-text-secondary) | stylelint rule with autofix, or a regex codemod over .css/.scss |
| Token renames in design files | Figma variables library update + "swap library" |
| Behavioral changes | Not automatable; migration guide + lint rule that flags call sites |
War Story (illustrative)
The major version nobody adopted
A design system shipped v3 with 40 breaking changes, a 30-page migration guide, and no codemods. Eight months later, 85% of product repos were still on v2, the core team was backporting fixes to both, and new components existed only in v3. Teams were not lazy; the migration was simply estimated at two sprints per app and never won a prioritization meeting.
For v4 the team changed approach: breaking changes were capped at a dozen, every mechanical one shipped with a codemod, and the core team ran the codemods themselves and opened PRs on the twenty largest repos. Median migration time dropped to under a day, and adoption passed 80% within six weeks. The cost of a breaking change is paid by consumers; if the system team does not pay part of it, adoption stalls.
Release Process and Changelogs
Release Pipeline
flowchart LR
PR["PR with<br/>changeset file"] --> CI["CI: lint, types,<br/>unit, a11y, visual diff"]
CI --> MERGE["Merge to main"]
MERGE --> VPR["Bot opens<br/>'Version Packages' PR"]
VPR --> CANARY["Snapshot release<br/>0.0.0-canary-sha"]
CANARY --> TRY["Consumers test<br/>in their apps"]
VPR -->|"merged"| PUB["Publish to npm,<br/>tag, GitHub release"]
PUB --> DOCS["Docs site deploy<br/>+ changelog"]
PUB --> ANN["Announce:<br/>Slack, newsletter"]
Changesets is the de facto tool for monorepo-based design systems: each PR includes a small markdown file declaring which packages change and at what semver level, plus a human-written summary. At release time the tool aggregates them into version bumps and changelogs.
---
"@acme/components": minor
"@acme/tokens": minor
---
**Button:** add `variant="ghost"`. The `subtle` prop is deprecated and will be
removed in v5.0.0. Run `npx @acme/codemods v5/button-subtle-to-variant src/`.
# .github/workflows/release.yml
name: Release
on:
push:
branches: [main]
concurrency: release-${{ github.ref }}
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
id-token: write # npm provenance
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: pnpm
registry-url: https://registry.npmjs.org
- run: pnpm install --frozen-lockfile
- run: pnpm build
- name: Create release PR or publish
uses: changesets/action@v1
with:
version: pnpm changeset version
publish: pnpm changeset publish
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
NPM_CONFIG_PROVENANCE: "true"
Release Cadence
| Release type | Cadence | Contents |
|---|---|---|
| Canary | Every merge to main | Anything; for early testing only |
| Patch | As needed (often daily/weekly) | Bug and a11y fixes |
| Minor | Every 1-2 weeks, or continuous | New components, props, tokens, deprecations |
| Major | Scheduled, at most 1-2 per year | Removals of deprecated APIs; announced at least a quarter ahead |
Writing Changelogs People Read
A changelog is documentation for upgraders, not a commit log. Group by impact, lead with what consumers must do, and include visuals for visual changes.
| Section | Contents |
|---|---|
| Breaking (majors only) | What changed, why, the codemod command, link to migration guide |
| Deprecated | What, replacement, removal version |
| Added | New components/props/tokens with a link to docs |
| Changed (visual) | Before/after screenshots or Chromatic link |
| Fixed | Bugs and accessibility fixes, with component names |
Adoption: Metrics and Strategies
A design system is a product whose customers are other teams. If you cannot measure adoption, you cannot tell whether it is succeeding, and you cannot defend its budget.
What to Measure
| Metric | How | Target signal |
|---|---|---|
| Coverage | % of rendered UI (or JSX elements) in product code that come from the system vs local components | Rising over time; > 70% in mature products |
| Version currency | % of repos on the latest major / within one minor of latest | > 80% on current major within one quarter of release |
| Deprecated API usage | Count of deprecated props/tokens/components in consumer code | Trending to zero before the next major |
| Detached instances (design side) | Figma library analytics: detached vs linked component instances | Low and falling; spikes indicate a missing variant |
| Hardcoded values | Lint counts of raw hex, px spacing, non-token durations | Falling |
| Contribution | PRs and RFCs from outside the core team per quarter | Rising in a hybrid model |
| Time to adopt a release | Days from publish to N% of repos upgraded | Shrinking |
| Satisfaction | Quarterly survey (developer and designer NPS or CSAT), office-hours attendance | Qualitative input for the roadmap |
Measuring code coverage is easiest with a scanner that parses every product repo and counts JSX element usage by import source. Tools such as react-scanner do this; a minimal version with the TypeScript compiler is small enough to own:
// scripts/adoption-scan.ts
// Counts JSX elements by import source across a repo. Run in CI for each product repo
// and push results to a metrics store.
import { Project, SyntaxKind } from 'ts-morph';
const SYSTEM_PACKAGES = ['@acme/components', '@acme/primitives', '@acme/labs'];
const DEPRECATED_PROPS: Record<string, string[]> = { Button: ['subtle'], Dialog: ['isOpen'] };
const project = new Project({ tsConfigFilePath: process.argv[2] ?? 'tsconfig.json' });
const counts = { system: 0, other: 0, deprecatedProps: 0 };
const byComponent = new Map<string, number>();
for (const file of project.getSourceFiles(['src/**/*.tsx'])) {
// Map local identifier -> import source
const sources = new Map<string, string>();
for (const imp of file.getImportDeclarations()) {
const mod = imp.getModuleSpecifierValue();
for (const named of imp.getNamedImports()) {
sources.set(named.getAliasNode()?.getText() ?? named.getName(), mod);
}
}
const elements = [
...file.getDescendantsOfKind(SyntaxKind.JsxOpeningElement),
...file.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement),
];
for (const el of elements) {
const tag = el.getTagNameNode().getText();
if (/^[a-z]/.test(tag)) continue; // intrinsic DOM element
const src = sources.get(tag.split('.')[0]);
if (src && SYSTEM_PACKAGES.includes(src)) {
counts.system++;
byComponent.set(tag, (byComponent.get(tag) ?? 0) + 1);
for (const attr of el.getAttributes()) {
const name = attr.getFirstChildByKind(SyntaxKind.Identifier)?.getText();
if (name && DEPRECATED_PROPS[tag]?.includes(name)) counts.deprecatedProps++;
}
} else {
counts.other++;
}
}
}
const coverage = counts.system / Math.max(1, counts.system + counts.other);
console.log(JSON.stringify({
coverage: Number(coverage.toFixed(3)),
...counts,
topComponents: [...byComponent].sort((a, b) => b[1] - a[1]).slice(0, 20),
}, null, 2));
Coverage is a guide, not a target
A product with 95% coverage might be forcing system components into shapes they were not designed for. A product at 50% might have a legitimately custom marketing surface. Use coverage to find conversations to have, not to rank teams.
Adoption Strategies
| Strategy | Why it works |
|---|---|
| Make the system the easiest path | Project templates and scaffolding generate code using the system; a new page built without it should feel like extra work |
| Embedded "system ambassadors" | A designer or engineer in each product team with a direct line to the core team; they surface needs early and spread patterns |
| Office hours and a support channel | Fast answers prevent forks; track recurring questions as doc or API gaps |
| Migrate for them | Core team opens upgrade PRs on the largest consumers, running the codemods themselves |
| Lint rules with autofix | no-restricted-imports for legacy libraries, stylelint rules against raw hex; enforcement without meetings |
| Showcase wins | Before/after of a team that shipped faster or fixed a11y bugs for free by adopting a component |
| Prioritize by blocker | Ask "what is stopping you from adopting?" and put the answers on the roadmap |
| Do not mandate prematurely | A mandate on an immature system produces resentment and forks; earn adoption first, then make it policy |
Documentation
Documentation is the system's user interface. A component nobody can find or understand does not exist.
| Doc type | Audience | Contents |
|---|---|---|
| Getting started | New consumers | Install, theme provider setup, first component, bundler notes |
| Foundations | Designers and developers | Color, typography, spacing, motion, elevation — linking token references |
| Component pages | Developers and designers | Usage guidance, live examples, props table generated from types, accessibility notes, do/don't, related components |
| Patterns | Product teams | Forms, empty states, error handling, data tables — combinations of components |
| Migration guides | Upgraders | One per major, with codemods |
| Contribution guide | Contributors | Process, RFC template, review checklist, local dev setup |
| Decision log | Everyone | Accepted and rejected RFCs and the reasons — prevents relitigating |
Generate what can be generated — props tables from TypeScript types, token tables from the token source, changelogs from changesets — so docs cannot drift from code. Hand-write what cannot: when to use a component, when not to, and why.
Tooling
flowchart LR
subgraph DESIGN["Design source"]
FIG["Figma library<br/>+ variables"]
end
subgraph TOKENS["Token pipeline"]
JSON["tokens/*.json<br/>(W3C DTCG format)"]
SD["Style Dictionary"]
OUT["CSS vars, TS, Swift,<br/>Kotlin, Tailwind preset"]
end
subgraph CODE["Components"]
SRC["React source"]
SB["Storybook stories"]
end
subgraph QA["Quality gates (CI)"]
UNIT["Unit tests<br/>(Vitest + Testing Library)"]
AXE["a11y tests<br/>(axe via Storybook test runner)"]
VIS["Visual regression<br/>(Chromatic / Playwright)"]
SIZE["Bundle size check"]
end
FIG -->|"export / sync plugin"| JSON
JSON --> SD --> OUT
OUT --> SRC
SRC --> SB
SB --> AXE
SB --> VIS
SRC --> UNIT
SRC --> SIZE
| Tool category | Common choices | Role in governance |
|---|---|---|
| Workshop / docs | Storybook, Ladle, Histoire | Every state of every component has a story; stories are the test fixtures |
| Visual regression | Chromatic, Playwright screenshots, Percy | Every PR shows exactly which components changed visually; reviewers approve diffs |
| Token pipeline | Style Dictionary, Tokens Studio, Figma variables + REST API | Single source of truth for tokens across platforms; see Semantic Tokens |
| Accessibility | axe-core, Storybook a11y addon, manual audits | Automated floor, manual ceiling; see WCAG Compliance |
| Release | Changesets, semantic-release | Enforces that every change declares its semver impact |
| Codemods | jscodeshift, ts-morph, ast-grep | Makes breaking changes affordable |
| Adoption analytics | react-scanner, custom AST scanners, Figma library analytics | Measures whether the system is used |
| Design-code link | Figma Code Connect, Storybook design addon | Designers see the real component API; developers see the spec |
A minimal Style Dictionary configuration that emits CSS variables and TypeScript from the same source, with deprecation comments:
// tokens/style-dictionary.config.mjs
export default {
source: ['tokens/**/*.json'],
platforms: {
css: {
transformGroup: 'css',
prefix: 'acme',
buildPath: 'dist/css/',
files: [{
destination: 'tokens.css',
format: 'css/variables',
options: { outputReferences: true, showFileHeader: true },
}],
},
ts: {
transformGroup: 'js',
buildPath: 'dist/ts/',
files: [
{ destination: 'tokens.js', format: 'javascript/es6' },
{ destination: 'tokens.d.ts', format: 'typescript/es6-declarations' },
],
},
},
};
Gate visual changes in CI so that no visual diff merges without an explicit approval:
# .github/workflows/visual.yml
name: Visual review
on: pull_request
jobs:
chromatic:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Chromatic needs history for baselines
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: pnpm
- run: pnpm install --frozen-lockfile
- uses: chromaui/action@v11
with:
projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
onlyChanged: true # TurboSnap: only stories affected by the diff
exitZeroOnChanges: false # unapproved visual changes fail the check
Team Structure
Roles
| Role | Responsibility |
|---|---|
| Product manager / lead | Roadmap, prioritization against consumer needs, adoption metrics, stakeholder communication |
| Design system designers | Foundations, component specs, Figma library, usage guidelines |
| Design system engineers | Component implementation, API design, tooling, releases, codemods |
| Accessibility specialist (often shared) | Audits, patterns, AT testing |
| Content designer (part-time) | Voice and tone, microcopy guidelines, docs quality |
| Developer advocate / enablement (at scale) | Onboarding, office hours, migrations, ambassadors program |
Sizing
There is no universal ratio, but commonly cited industry rules of thumb put a dedicated core team at roughly 1 system engineer per 15-30 product frontend engineers, with at least one designer for every two to three system engineers. Below about three dedicated people, a system tends to stall as soon as one person goes on leave; a hybrid model with strong contribution lets a small core team support a large organization.
flowchart TB
LEAD["DS lead / PM"] --> DES["DS designers (2)"]
LEAD --> ENG["DS engineers (4)"]
LEAD --> A11Y["Accessibility (shared, 0.5)"]
ENG --> AMB["Ambassadors in product teams<br/>(1 per team, ~10% time)"]
DES --> AMB
AMB --> PT["Product teams (12)"]
COUNCIL["Design system council<br/>(lead + 3-5 senior product reps)<br/>monthly: RFCs, roadmap"] --- LEAD
Rituals
| Ritual | Cadence | Purpose |
|---|---|---|
| Office hours | Weekly | Unblock consumers; collect needs |
| RFC review | Weekly or biweekly | Decide on proposals within a bounded time |
| Council | Monthly | Roadmap, cross-team priorities, escalations |
| Release notes / demo | Per minor release | Make the system visible; celebrate contributors |
| Adoption review | Quarterly | Metrics, survey results, next quarter's priorities |
| Accessibility audit | Per new core component + annually | Keep the quality bar real |
Governance Anti-Patterns
| Anti-pattern | Symptom | Fix |
|---|---|---|
| The ivory tower | Core team builds what it finds interesting; product teams build local copies | Roadmap driven by consumer requests and adoption blockers |
| The dumping ground | Every team's one-off component lands in core | Two-team rule; labs tier |
| Silent breaking changes | Visual or behavior changes in patches | Changesets required; visual regression gates |
| Major version cliffs | Dozens of breaking changes at once; nobody upgrades | Small, scheduled majors with codemods |
| Design-code drift | Figma and code disagree on variants and names | Same names in both, Code Connect, shared review of specs and API |
| Mandate before maturity | "Everyone must use the system" with half the components missing | Earn adoption; mandate only once coverage is broad |
| No owner for "shared" tier | Contributed components rot when the author changes teams | Owner field required; orphaned components move to labs or deprecation |
Further Reading
- Component Patterns — API patterns that make components composable and stable
- Atomic Design — a vocabulary for organizing the component hierarchy
- Color Tokens and Semantic Tokens — the token architecture that versioning protects
- Dark Mode — theming as a consumer of the token pipeline
- Testing Accessibility — the automated and manual checks in the review gate
- Micro-Frontends — sharing a design system across independently deployed apps
"A design system's API is a promise to every team that uses it. Governance is how you keep promises at scale."