On this page

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 typeCost of getting it wrongGovernance weight
New public componentHigh — every consumer couples to its APIRFC + design and engineering review
New prop on an existing componentMedium — hard to remove laterLightweight proposal + API review
New semantic tokenHigh — names propagate into every themeToken council review
Primitive token value changeMedium — visual regressions everywhereVisual diff review
Bug fixLowNormal code review
Docs, examples, storiesLowNormal 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
ModelWho buildsWho decidesStrengthsWeaknessesFits when
CentralizedDedicated core teamCore teamHigh consistency, coherent API, clear ownershipBottleneck; core team drifts from product realityEarly system, < ~10 product teams, strong brand requirements
FederatedProduct teamsCross-team councilReflects real needs; scales contributionSlow decisions, inconsistent quality, nobody owns releasesMany senior teams, no budget for a core team
HybridCore team builds foundations; product teams contribute componentsCore team sets the bar and owns releases; council for big decisionsScales while keeping qualityRequires mature contribution processMost 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:

TierOwnershipQuality barVersioningExample
CoreCore teamFull a11y audit, visual tests, docs, design spec, RTL, dark modeStrict semver, deprecation policyButton, TextField, Dialog, tokens
Shared / communityContributing team, core reviewsCore checklist minus some polish; owner listedSemver, shorter deprecation windowDataGrid extensions, DateRangePicker
Labs / experimentalAnyoneWorks, has a storyNo stability guarantee; import from /labsNew patterns being validated
Product-localProduct teamProduct team's choiceNot in the systemOne-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.

AreaCheck
APIFollows 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
CompositionUses existing primitives (Box, Stack, Text) and patterns from Component Patterns
TokensNo hardcoded colors, spacing, radii, or durations; only semantic tokens (see Semantic Tokens)
ThemingWorks in light, dark, and high-contrast themes; see Dark Mode token mapping
AccessibilityKeyboard operable; visible focus; correct roles; axe passes; manual screen reader check; see Testing Accessibility
InternationalizationNo hardcoded strings; RTL layout; long-text overflow handled
TestingUnit tests for behavior; stories for every state; visual snapshots
DocsUsage guidelines (when to use, when not to), props table, do/don't examples
BundleTree-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

ChangeBumpReasoning
Remove a component, prop, or tokenMajorCode stops compiling or working
Rename a prop or tokenMajor (or minor with alias + deprecation)Same as remove, unless an alias keeps the old name working
Change a prop's type to be narrowerMajorPreviously valid values now rejected
Change default value of a propMajor if behavior or layout visibly changesConsumers relied on the default implicitly
Change DOM structure that consumers may targetMajor if documented as stable; otherwise minorPublish which DOM/class names are public API (ideally none)
Add a new optional prop, component, or tokenMinorAdditive
Widen a prop's accepted typeMinorAdditive
Visual change within the design spec (spacing tweak, shadow)Minor with visual changelog entryNot breaking for code, but can break layouts and screenshot tests
Bug fix that changes behavior people relied onPatch, but call it outJudgement call; when many consumers depend on the bug, consider minor
Accessibility fix (adding aria-*, focus management)Patch or minorNever hold accessibility fixes back for a major
Internal refactor, no API or visual changePatch

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

StrategyExampleProsCons
Single package@acme/ui@4.2.0One version to reason about; no compatibility matrixAny breaking change bumps everything; big upgrades
Per-component packages@acme/button@2.1.0, @acme/dialog@5.0.0Upgrade one component at a timeDependency hell; mismatched internal versions; duplicated deps in bundles
Few layered packages@acme/tokens, @acme/primitives, @acme/components, @acme/iconsSeparate cadence for tokens vs components; manageable matrixMust 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 changeBumpNotes
Add a tokenMinor
Change a primitive's value (blue-600 hex)Minor (visual)Every semantic token aliasing it changes
Change which primitive a semantic token aliasesMinor (visual)This is the intended way to restyle
Rename or remove a tokenMajorKeep the old name as a deprecated alias for one major cycle
Change a token's type (color to gradient)MajorBreaks 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:

  1. 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.
  2. Every deprecation ships with: a console warning in development builds, a lint rule, a migration note, and — when the change is mechanical — a codemod.
  3. Majors are batched and scheduled (for example, at most two per year), announced in advance, with a migration guide published before the release.
  4. 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 typeTooling
JSX prop / import renamesjscodeshift, 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 filesFigma variables library update + "swap library"
Behavioral changesNot 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 typeCadenceContents
CanaryEvery merge to mainAnything; for early testing only
PatchAs needed (often daily/weekly)Bug and a11y fixes
MinorEvery 1-2 weeks, or continuousNew components, props, tokens, deprecations
MajorScheduled, at most 1-2 per yearRemovals 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.

SectionContents
Breaking (majors only)What changed, why, the codemod command, link to migration guide
DeprecatedWhat, replacement, removal version
AddedNew components/props/tokens with a link to docs
Changed (visual)Before/after screenshots or Chromatic link
FixedBugs 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

MetricHowTarget signal
Coverage% of rendered UI (or JSX elements) in product code that come from the system vs local componentsRising 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 usageCount of deprecated props/tokens/components in consumer codeTrending to zero before the next major
Detached instances (design side)Figma library analytics: detached vs linked component instancesLow and falling; spikes indicate a missing variant
Hardcoded valuesLint counts of raw hex, px spacing, non-token durationsFalling
ContributionPRs and RFCs from outside the core team per quarterRising in a hybrid model
Time to adopt a releaseDays from publish to N% of repos upgradedShrinking
SatisfactionQuarterly survey (developer and designer NPS or CSAT), office-hours attendanceQualitative 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

StrategyWhy it works
Make the system the easiest pathProject 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 channelFast answers prevent forks; track recurring questions as doc or API gaps
Migrate for themCore team opens upgrade PRs on the largest consumers, running the codemods themselves
Lint rules with autofixno-restricted-imports for legacy libraries, stylelint rules against raw hex; enforcement without meetings
Showcase winsBefore/after of a team that shipped faster or fixed a11y bugs for free by adopting a component
Prioritize by blockerAsk "what is stopping you from adopting?" and put the answers on the roadmap
Do not mandate prematurelyA 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 typeAudienceContents
Getting startedNew consumersInstall, theme provider setup, first component, bundler notes
FoundationsDesigners and developersColor, typography, spacing, motion, elevation — linking token references
Component pagesDevelopers and designersUsage guidance, live examples, props table generated from types, accessibility notes, do/don't, related components
PatternsProduct teamsForms, empty states, error handling, data tables — combinations of components
Migration guidesUpgradersOne per major, with codemods
Contribution guideContributorsProcess, RFC template, review checklist, local dev setup
Decision logEveryoneAccepted 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 categoryCommon choicesRole in governance
Workshop / docsStorybook, Ladle, HistoireEvery state of every component has a story; stories are the test fixtures
Visual regressionChromatic, Playwright screenshots, PercyEvery PR shows exactly which components changed visually; reviewers approve diffs
Token pipelineStyle Dictionary, Tokens Studio, Figma variables + REST APISingle source of truth for tokens across platforms; see Semantic Tokens
Accessibilityaxe-core, Storybook a11y addon, manual auditsAutomated floor, manual ceiling; see WCAG Compliance
ReleaseChangesets, semantic-releaseEnforces that every change declares its semver impact
Codemodsjscodeshift, ts-morph, ast-grepMakes breaking changes affordable
Adoption analyticsreact-scanner, custom AST scanners, Figma library analyticsMeasures whether the system is used
Design-code linkFigma Code Connect, Storybook design addonDesigners 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

RoleResponsibility
Product manager / leadRoadmap, prioritization against consumer needs, adoption metrics, stakeholder communication
Design system designersFoundations, component specs, Figma library, usage guidelines
Design system engineersComponent 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

RitualCadencePurpose
Office hoursWeeklyUnblock consumers; collect needs
RFC reviewWeekly or biweeklyDecide on proposals within a bounded time
CouncilMonthlyRoadmap, cross-team priorities, escalations
Release notes / demoPer minor releaseMake the system visible; celebrate contributors
Adoption reviewQuarterlyMetrics, survey results, next quarter's priorities
Accessibility auditPer new core component + annuallyKeep the quality bar real

Governance Anti-Patterns

Anti-patternSymptomFix
The ivory towerCore team builds what it finds interesting; product teams build local copiesRoadmap driven by consumer requests and adoption blockers
The dumping groundEvery team's one-off component lands in coreTwo-team rule; labs tier
Silent breaking changesVisual or behavior changes in patchesChangesets required; visual regression gates
Major version cliffsDozens of breaking changes at once; nobody upgradesSmall, scheduled majors with codemods
Design-code driftFigma and code disagree on variants and namesSame names in both, Code Connect, shared review of specs and API
Mandate before maturity"Everyone must use the system" with half the components missingEarn adoption; mandate only once coverage is broad
No owner for "shared" tierContributed components rot when the author changes teamsOwner field required; orphaned components move to labs or deprecation

Further Reading


"A design system's API is a promise to every team that uses it. Governance is how you keep promises at scale."