Design a design system for many teams

Requirements: what a design system for many teams has to do

A design system is the shared set of design decisions (colors, spacing, type), the components built from them (button, dialog, table), and the rules for using both. The design-systems lesson covers what each piece is. This guide is about the harder question: how you design one that 24 teams, 70 repos, several frameworks and two brands can actually use, and how you move all of them forward when it changes.

Interviewers like this question because it has almost no algorithm in it. It tests whether you think about the system as a product whose users are other engineers and designers.

A library that is technically great but that nobody upgrades is a failure. So is one that ships a breaking change on a Friday and breaks 40 checkout pages. Most of a strong answer is about those people problems, solved with engineering.

Questions to ask

The middle column is what this guide assumes. The right column is why the answer changes the design.

Functional requirements

• Tokens: one source of truth for color, spacing, type, radius, shadow and motion, published as CSS variables, JavaScript constants, iOS Swift and Android XML from the same files.
• Themes and brands: any app can switch brand or mode (light, dark, high contrast) without changing component code.
• Components: about 60 core components at launch (button, text field, select, checkbox, dialog, tabs, toast, table, date picker) with keyboard and screen reader support built in.
• Frameworks: first-class React; usable from Angular and server-rendered HTML.
• Releases: versioned packages with changelogs, a clear deprecation policy and codemods for breaking changes.
• Docs: a site with live examples, usage rules, do and don't pairs, generated props tables and links to Figma.
• Contribution and measurement: teams can propose and contribute components; the core team can measure adoption per repo.

Non-functional requirements

Out of scope

• Page templates and full product flows: the system ships building blocks and patterns, product teams build pages.
• The internals of single components like a dialog, tabs or a select: the modal-dialog, tabs and dropdown-select guides cover those.
• Dark mode switching on one site (the no-flash script, the three-state choice): the dark-mode-theming guide covers that. Here we care about how themes are packaged for many apps.
• Sharing one runtime copy across micro-frontends: the micro-frontend-shell guide covers that. We only make sure the packages allow it.

What makes this hard: one system, many consumers, no stop button

A component library for one app is a folder. A design system for 24 teams is a platform with its own users, releases and support load. Five traits drive every decision in the rest of this guide.

• Many consumers, one source. A change to a token or a component lands in 70 repos. The upside: fix a focus bug once, and 70 apps get the fix. The downside: break a button once, and 70 apps break. Every change has a blast radius, and we have to know how big it is before we ship.
• Many platforms. React, Angular, plain HTML from Rails, Swift and Kotlin can't share component code. They can share decisions: the brand blue, the 8 px spacing step, the 200 ms motion. So the lowest layer must be data, not code.
• Independent upgrade schedules. We can't upgrade other teams' apps for them. A team in the middle of a launch will stay on version 4 for months. So at any time several versions are live, and our versioning, deprecation and codemod story decides how painful that is.
• Optional adoption. Teams can (and do) keep writing their own CSS. The system competes with copy and paste. If it's slower to use, heavier, or blocks a team for two weeks waiting for a variant, it loses. Developer experience is a feature.
• Quality multiplies. A contrast bug in a one-off page affects one page. In a shared Text component it affects every screen in the company. Quality gates must be stricter than in any single app, and they must be automated, because nobody can click through 70 apps.

Those traits point to the layer stack from the design-systems lesson, with one change: components split into a behavior layer and a looks layer. The bottom layer is the most shared and the most stable: tokens, as plain data. Above it sit behavior primitives (keyboard, focus, ARIA) with no looks, then the styled components teams import.

On top sit patterns and product code. Each layer changes faster than the one below it, and each upper layer can be swapped without touching the lower ones.

Keep this picture in mind. Most mistakes in real design systems come from mixing layers: brand colors hard-coded inside a component (so a second brand needs a fork), keyboard logic tangled with styling (so the Angular team can't reuse it), or product-specific variants added to core components (so the button ends up with 23 props). The rest of the guide walks the layers bottom up, then covers how the whole thing ships, gets tested, documented, adopted and measured.

Tokens and the token pipeline: one source for every platform and brand

A design token is one named design decision stored as data: color.action.primary is #0b5cd6, space.3 is 12px. The design-systems lesson covers why tokens exist, the three tiers and how to name them. The question here is where tokens live, what format they're in, and how one change reaches CSS, JavaScript, Swift and Kotlin in nine themes without anyone copying a hex code by hand.

The naive approach is a colors.ts file in the React package. It works for one React app. Then the Angular team copies it into a SCSS file, and the iOS team types the values into an asset catalog.

Six months later the brand blue changes from #0b5cd6 to #0a56c8. Someone updates the TypeScript file, and the other three copies drift. That is how a codebase ends up with 900 distinct hex values.

The format: W3C Design Tokens (DTCG)

The design-systems lesson introduces the JSON format from the W3C Design Tokens Community Group (DTCG). Its first stable version, 2025.10, came out in October 2025 as three modules: the Format (tokens, groups, aliases), Color (colors as objects with an explicit color space), and the Resolver (how to combine token sets for themes and brands). At our scale, the color format and the Resolver are the parts that matter.

{
  "color": {
    "blue": {
      "600": {
        "$type": "color",
        "$value": { "colorSpace": "srgb", "components": [0.043, 0.361, 0.839], "hex": "#0b5cd6" }
      }
    }
  }
}

{
  "color": {
    "action": {
      "primary": {
        "$type": "color",
        "$value": "{color.blue.600}",
        "$description": "Fill of the main call to action. One per view."
      }
    }
  }
}

Note the color value. In the stable spec a color is an object with a colorSpace, a components array (0 to 1 for sRGB), an optional alpha and an optional hex fallback, not a bare hex string. That lets the same file carry wide-gamut display-p3 or oklch colors. Many tools written against older drafts still expect hex strings, so check what each tool in the pipeline reads.

Three tiers, enforced by tools

The three tiers (primitive, semantic, component) come from the design-systems lesson. With 24 teams they stop being a naming habit and become access rules: each tier may only point at the one below it, and each has a fixed audience.

The semantic tier is the contract that product code and components depend on, and the only tier that themes and brands remap. Component tokens are kept few on purpose. Every one of them is a public knob that makes the system harder to change, so we add one only when a brand truly needs a single component to break from the semantic rule.

The rules only hold if tools check them. The token build fails when a component token points at a primitive. A Stylelint rule shipped to product teams rejects primitive variables such as --ds-color-blue-600 outside the token package, and the adoption scanner counts any that slip through.

The token build: one source, four platforms

A token build reads the JSON, resolves aliases, converts values to each platform's units and syntax, and writes files: CSS custom properties for the web, an ES module for JavaScript (charts and canvas need raw values), Swift for iOS, XML resources for Android. We use Style Dictionary, the open-source build tool the lesson introduces, with one config for every platform.

One caveat as of 2026: Style Dictionary 4 and later read the DTCG $value and $type keys, but its own docs say full support for the 2025.10 format is still work in progress in version 5. So we register a small custom transform that turns the color objects into CSS, Swift and Android values, and test it like any other code.

export default {
  source: ["tokens/primitive/**/*.json", "tokens/semantic/**/*.json", "tokens/brands/acme/light.json"],
  platforms: {
    css: {
      transformGroup: "css",
      prefix: "ds",
      buildPath: "dist/css/",
      files: [{ destination: "acme-light.css", format: "css/variables",
        options: { selector: '[data-brand="acme"][data-mode="light"]', outputReferences: true } }],
    },
    js: { transformGroup: "js", buildPath: "dist/js/",
      files: [{ destination: "acme-light.js", format: "javascript/es6" }] },
    ios: { transformGroup: "ios-swift", buildPath: "dist/ios/",
      files: [{ destination: "AcmeLight.swift", format: "ios-swift/class.swift", options: { className: "AcmeLight" } }] },
    android: { transformGroup: "android", buildPath: "dist/android/",
      files: [{ destination: "acme_light_colors.xml", format: "android/colors" }] },
  },
};

The CSS output for one theme is a block of variables under a selector. outputReferences keeps the alias, so you can see in devtools that --ds-color-action-primary comes from --ds-color-blue-600. Components only ever read semantic variables, so switching brand or mode is one attribute change on the html element, with no JavaScript re-render and no new component code.

[data-brand="acme"][data-mode="light"] {
  --ds-color-blue-600: #0b5cd6;
  --ds-color-gray-900: #1a1d23;
  --ds-color-action-primary: var(--ds-color-blue-600);
  --ds-color-text-default: var(--ds-color-gray-900);
  --ds-color-text-on-action: #ffffff;
  --ds-space-inset-sm: 0.5rem;
  --ds-space-inset-md: 1rem;
  --ds-radius-control: 0.25rem;
}

Brands and modes are token sets, not code

Three brands times three modes is nine combinations. Writing nine full token files by hand would be a maintenance trap: most values are the same everywhere.

Instead each combination is a stack of small token sets applied in order: the shared primitives, the shared semantic defaults, a brand set that overrides a few dozen tokens (brand colors, font family, corner radius), and a mode set that overrides colors for dark or high contrast. The DTCG Resolver module standardizes this: named sets, modifiers such as brand and mode with one context per value, and a resolutionOrder that decides which value wins.

In our numbers: about 180 primitives, 260 semantic tokens and 40 component tokens. A brand set overrides about 45 tokens; a mode set overrides about 70. The build writes nine CSS files of roughly 20 KB each before compression and 3 to 4 KB after gzip. An app loads only its own brand, so the token cost on the wire is a few kilobytes per mode it supports.

Native apps get the same decisions in their own idiom. On Android the mode sets go into values and values-night resource folders; on iOS a small custom format writes asset catalog colors with light and dark appearances, since the built-in Swift formats write plain constants. The point is not identical code on every platform but identical decisions: the brand green is the same number everywhere because it was typed once.

Keeping Figma variables in sync

Figma variables are Figma's own token feature: values grouped into collections, each with modes (for example Light, Dark and High contrast). If the Figma library and the code disagree, designers hand off mockups in colors that don't exist, and engineers either guess or add a one-off hex. So the sync must be automatic in both directions, with git as the referee.

1. Code to Figma. When token files merge, a job writes the values into the Figma library (through the Variables REST API, which needs an Enterprise plan, or a plugin such as Tokens Studio). Designers get a library update to accept.
2. Figma to code. When a designer changes a variable, the plugin or a bot exports the change as DTCG JSON and opens a pull request. CI runs contrast checks and shows a visual diff; a design system engineer reviews and merges.
3. Conflicts. If both sides changed the same token, the pull request shows it and a human decides. Figma never writes to the main branch directly.

Components: behavior, styling and many frameworks

Components decide how things behave: a select must open with Enter, Space and the arrow keys, move focus through options, announce the selected value to a screen reader, close on Escape and return focus to its trigger. That behavior is the hardest part to get right and the part teams most often get wrong, so it's where a shared system saves the most work.

This chapter makes three decisions: how components are structured, how their styles are written and shipped, and how they reach apps that aren't React. The component-api-design lesson covers props, slots and naming in general; here we decide how to structure 60 components for 24 teams.

The naive approach is one styled component per widget, with behavior and looks mixed, and a prop for every request. After two years the Button has variant, size, color, fullWidth, iconLeft, iconRight, loading, loadingText, href, target, tooltip, badge and 11 more. Each prop interacts with the others, the test matrix explodes, and the Angular team still can't reuse any of the keyboard logic.

Composition over configuration

Instead of a prop for every part, complex components are built from named parts that share state through context. A team that needs a badge in the dialog header puts a badge in the header; nobody adds headerBadge to the API. This is how Radix, React Aria Components and most large systems shape their dialogs, menus and tabs.

<Dialog>
  <Dialog.Trigger asChild>
    <Button variant="secondary">Archive project</Button>
  </Dialog.Trigger>
  <Dialog.Content>
    <Dialog.Title>Archive this project?</Dialog.Title>
    <Dialog.Description>Members lose access. You can restore it for 30 days.</Dialog.Description>
    <Dialog.Actions>
      <Dialog.Close asChild><Button variant="secondary">Cancel</Button></Dialog.Close>
      <Button variant="danger" onPress={archive}>Archive</Button>
    </Dialog.Actions>
  </Dialog.Content>
</Dialog>

Two patterns let one component render as a different element. A polymorphic as prop (Button as="a" href="/billing") swaps the tag; it's convenient but hard to type well in TypeScript, because the allowed props depend on the tag. asChild (Radix's name, also used by Ark UI) renders no element of its own and merges its props, handlers and ref into its single child. Base UI offers the same idea as a render prop.

We support asChild on trigger and item parts (Dialog.Trigger, Menu.Item), so a team's own button or router link can open a dialog, and we keep as off the public API. For links that look like buttons, the system's Link takes the button variants, and React Aria's RouterProvider lets it navigate with the app's own router, so the system never imports a router.

Controlled and uncontrolled, always both

Every stateful component (tabs, dialog, select, accordion) works uncontrolled by default (it keeps its own state, seeded by defaultValue) and controlled when the app passes value and onChange (the app owns the state, for example to sync with the URL). One small hook gives every component the same rule, so teams learn it once.

export function useControllableState<T>(opts: {
  value?: T;
  defaultValue: T;
  onChange?: (next: T) => void;
}): [T, (next: T) => void] {
  const [inner, setInner] = useState(opts.defaultValue);
  const controlled = opts.value !== undefined;
  const current = controlled ? (opts.value as T) : inner;
  const set = useCallback((next: T) => {
    if (!controlled) setInner(next);
    opts.onChange?.(next);
  }, [controlled, opts.onChange]);
  return [current, set];
}

Styling: static CSS, variables and layers

How the styles are written and delivered decides three things that teams feel every day: how much the system costs at runtime, whether it works with server rendering and React Server Components, and whether a product team can override a style without a fight over CSS specificity. It also decides whether the Angular and Rails apps can use the same styles at all.

Cascade layers: product CSS wins on purpose

The classic override problem: a product team writes .checkout .ds-button { padding: 0 } and it works, until the system ships a more specific selector and their fix silently stops working. Teams then reach for !important, and specificity wars begin.

Cascade layers (@layer, supported in every major browser since 2022) fix this structurally. For normal declarations, styles in a later layer beat styles in an earlier layer no matter how specific the selectors are, and styles in no layer at all beat every layer. (!important declarations reverse that order, which is one more reason to keep them out.)

/* @acme/ds-css/base.css */
@layer ds.reset, ds.tokens, ds.components, ds.utilities;

@layer ds.components {
  .ds-button {
    padding-block: var(--ds-space-inset-sm);
    padding-inline: var(--ds-space-inset-md);
    border-radius: var(--ds-radius-control);
    background: var(--ds-color-action-primary);
    color: var(--ds-color-text-on-action);
  }
  .ds-button[data-variant="secondary"] {
    background: transparent;
    color: var(--ds-color-action-primary);
  }
}

/* product app, unlayered: beats the system even with a weaker selector */
.ds-button { min-inline-size: 8rem; }

Overrides are allowed but they are not free: they depend on our class names and DOM, which can change in a major version. So we offer escape hatches in order of safety.

First, props and variants. Second, component tokens set on a wrapper (--ds-button-radius: 0), which are a public, versioned API. Third, unlayered CSS on documented class names. The adoption scanner counts the third kind, because many overrides on one component signal that the component is missing something.

Many frameworks: what to share and what to write twice

About 55 repos are React, 9 are Angular and 6 render HTML on the server with Rails or Django templates. Tokens and plain CSS already reach all of them. The question is behavior: should the Angular team get a working, accessible select, and if so, from what code?

Web components are the browser's own component model: custom elements (ds-select) with optional shadow DOM for encapsulated markup and styles. They run in any framework or none, which makes them look like the obvious answer. The web-components lesson covers how they work; here the question is whether they should be our main implementation.

For the server-rendered apps, the CSS package documents the HTML each component needs (button class="ds-button" data-variant="secondary"). Those class names and attributes become public API under semver, the same as React props. A Rails partial or Django template tag wraps the markup so templates don't repeat it.

GitHub's Primer ran this split for years: Primer React, Primer ViewComponents for Rails, and shared CSS and tokens. In 2026 GitHub put the Rails library into maintenance mode to focus on React. That is the cost of a second implementation made visible, and it's why ours stays limited to markup and a few leaf elements.

Shipping change: packages, versions and codemods

The system is published to the company's private npm registry, and every repo upgrades on its own schedule. This chapter covers the three things that decide how painful that is: how the system is split into packages, what counts as a breaking change, and how breaking changes reach 70 repos. The monorepos lesson covers the repo side.

Start with the packages. How the system is split decides how teams install it, how versions can drift apart, and how much code ends up in each app.

{
  "name": "@acme/ds-react",
  "version": "5.3.0",
  "type": "module",
  "exports": {
    ".": "./dist/index.js",
    "./button": "./dist/button/index.js",
    "./dialog": "./dist/dialog/index.js",
    "./styles.css": "./dist/styles.css"
  },
  "sideEffects": ["**/*.css"],
  "peerDependencies": {
    "react": "^18.3.0 || ^19.0.0",
    "react-dom": "^18.3.0 || ^19.0.0",
    "@acme/ds-css": "^5.0.0"
  }
}

Avoiding two copies in one app

Duplicate copies are the most common packaging bug in large companies. The app installs @acme/ds-react@5, but an internal package (say, the shared checkout widget) depends on @acme/ds-react@4, so npm installs both. The app now ships two Buttons (tens of kilobytes more JavaScript) and two React contexts, so the checkout widget doesn't see the app's theme or locale provider. It also gets two focus managers: a dialog from one copy doesn't know about a dialog from the other, so Escape can close the wrong one.

• Libraries use peer dependencies. Any internal package built on the system lists it in peerDependencies with a range (^4.0.0 || ^5.0.0), never in dependencies. The app decides the one copy.
• React is always a peer, for the same reason: two React copies break hooks entirely.
• CI checks for duplicates. A step runs npm ls @acme/ds-react (or pnpm why) and fails the build if more than one version resolves.
• Micro-frontends share one copy at runtime through the shell's module sharing; the micro-frontend-shell guide covers that setup.

Versioning: what counts as breaking for a component

The design-systems lesson explains semantic versioning (semver) for UI: major for breaking changes, minor for additions, patch for fixes, and a public surface much wider than props. With 70 repos, a rough rule is not enough. A change that looks small to us can fail another team's tests, layout or screen reader flow, so the line has to be written down and applied the same way by every contributor.

So the system writes down, in its docs, what the public API of a component is. Ours is: the props and their types and defaults, the documented class names and data attributes of the CSS package, the semantic and component tokens, the accessible role and name of each part, and the keyboard behavior. The exact DOM inside a component is not public unless documented, and we say so in the docs, so teams know that .ds-dialog > div > div selectors are on their own.

Changesets: every pull request says what it changes

Changesets, introduced in the design-systems lesson, records the bump inside each pull request: a small markdown file naming the packages touched, the bump type and a changelog line. Two rules make it reliable with many contributors. CI fails a pull request that changes package code without a changeset, and a reviewer checks the bump against the table above. At release time the tool takes the biggest bump per package, writes each CHANGELOG.md and publishes.

---
"@acme/ds-react": minor
"@acme/ds-css": minor
---

Button: add the `tone="critical"` variant. Deprecate `variant="danger"`;
it keeps working until 6.0. Run `npx @acme/ds-codemods button-tone` to migrate.

Deprecation policy and N-1 support

Breaking changes never arrive by surprise. Every component and every prop moves through the same lifecycle, and each step is visible to teams in their editor, in the console and in the docs.

• Deprecate in a minor. The old prop or component keeps working. Its type gets a @deprecated JSDoc tag, so editors strike it through. In development builds it logs one console warning naming the replacement and the codemod. A lint rule flags it.
• Remove in the next major, at least 3 months later. Majors ship at most twice a year, on a published calendar, so teams can plan.
• Support N-1 for 12 months. The previous major gets security fixes, accessibility fixes and critical bugs, back-ported from main. Nothing older gets fixes. Two live majors is what 7 people can maintain.

Migrations: codemods and upgrade pull requests

A deprecation policy tells teams what will break. It doesn't do the work. If renaming variant="danger" to tone="critical" means 70 repos each spend an afternoon finding and editing call sites, teams postpone the upgrade, N-1 support stretches into N-3, and the system's team spends its time back-porting. The fix is to make upgrades almost free: the system team ships the code change along with the breaking change.

A codemod is a program that rewrites source code. Instead of search and replace on text, it parses the code into a syntax tree, finds the exact pattern (a Button imported from our package, with a variant attribute equal to "danger"), and edits the tree. So it won't touch a different Button or a string in a comment.

jscodeshift (from Meta) is the long-standing tool for JavaScript and JSX transforms. ts-morph wraps the TypeScript compiler API and is better when the change needs type information, such as finding every place a prop's type is used.

export default function transform(file, api) {
  const j = api.jscodeshift;
  const root = j(file.source);
  const names = new Set();
  root.find(j.ImportDeclaration, { source: { value: "@acme/ds-react" } })
    .find(j.ImportSpecifier, { imported: { name: "Button" } })
    .forEach((path) => names.add(path.node.local.name));
  if (names.size === 0) return undefined; // file untouched

  root.find(j.JSXOpeningElement)
    .filter((path) => names.has(path.node.name.name))
    .find(j.JSXAttribute, { name: { name: "variant" } })
    .forEach((path) => {
      const value = path.node.value;
      const isString = value && (value.type === "StringLiteral" || value.type === "Literal");
      if (isString && value.value === "danger") {
        path.node.name.name = "tone";
        path.node.value = j.stringLiteral("critical");
      } else if (value && value.type === "JSXExpressionContainer") {
        path.node.comments = [j.commentBlock(" TODO(ds-6): if this can be danger, use tone ")];
      }
    });
  return root.toSource();
}

export const parser = "tsx"; // parse TypeScript and JSX

Codemods are tested like any code: each one has fixture files (input and expected output) covering aliased imports, dynamic values and unrelated Button components from other libraries. A good codemod handles about 90% of call sites and marks the rest with a searchable comment, rather than guessing. Guessing wrong is worse than not changing the code, because the result type-checks and ships.

Running it across the fleet

Plan for a long tail. Our planning numbers for a major: about 60% of repos merge the bot's pull request within two weeks, another 25% need a small manual fix (a TODO the codemod left, or a snapshot test), and the last 15% are frozen, abandoned or mid-launch. The tail is where office hours and pairing go. The bot also refuses to open pull requests in repos with failing main branches, so it doesn't add noise to a broken build.

Quality gates: nothing reaches 70 repos unreviewed

A bug in a shared component is a bug in every app at once, and product teams will stop upgrading after the first bad release. So every pull request to the system passes automated gates that check what reviewers can't see by reading a diff: how each component looks in nine themes, whether it is still accessible, whether it still works with a keyboard, and whether it got heavier.

The testing-strategy and contract-and-visual-tests lessons cover these test types in general; here is how they fit a design system. The backbone is Storybook. Every component has stories: one per meaningful state (default, hover, focus, disabled, loading, error, long text, right to left).

Stories are the docs examples, and they are also the test cases: the same story is screenshotted, scanned by axe and driven by an interaction test. Writing a story is how a contributor adds test coverage.

Automated accessibility is a floor, not a ceiling

axe-core finds problems that can be decided from the DOM: an image without alt text, a button with no accessible name, a contrast ratio of 3.9 to 1 where 4.5 to 1 is required. It can't tell whether the name is helpful, whether focus lands in a sensible place after a dialog closes, or whether a live region announces too much.

In a 2021 study of more than 2,000 of its own audits, Deque, which makes axe, found that automated tests caught about 57% of issues by volume. The most frequent issue types happen to be ones tools can detect, so the share is far lower when counted by WCAG success criteria. Even by the kinder count, more than 40% of issues need a human to find them.

So every new component, and every change to behavior, gets a manual pass with a screen reader matrix before it moves from beta to stable: NVDA with Firefox or Chrome, JAWS with Chrome, VoiceOver with Safari on macOS and iOS, and TalkBack with Chrome on Android.

Documentation: the system's real user interface

Engineers meet the system through its docs long before they read its code. If they can't find the right component in a minute, they write their own. So the docs are part of the product, with the same review and the same release as the code. A docs page that is out of date is worse than none, because it teaches the wrong thing with authority.

Every component page has the same parts in the same order, so readers learn where to look. Props tables are generated from the TypeScript types at build time (react-docgen-typescript reads prop names, types, defaults and JSDoc comments), so a new prop appears in the docs the moment it ships. Hand-written props tables drift within weeks.

• Status badge: experimental, beta, stable or deprecated, with the replacement linked.
• Live examples from stories, with a copy button and a theme switcher for all nine brand and mode combinations.
• When to use and when not to, with do and don't pairs: "Use one primary button per view" next to a screenshot with three.
• Accessibility: the keyboard map, what the component announces, and what the product team must still do (for example, give an icon button a label).
• Props table generated from types, and the component tokens it exposes.
• Links: the Figma component, the source, the changelog filtered to this component, and the codemods that touch it.

Architecture, data model and interfaces

With the layers decided, here is the system as a set of parts with one job each. Most of it is not runtime code in the browser; it's the build, test, release and measurement machinery around the components. That is normal for a platform product: the components are only the visible part.

The boundaries follow who changes what and how often. Tokens change when design decisions change, and every platform consumes them, so they are data at the bottom with no dependencies. CSS depends only on tokens, so Rails and Angular can take it without React. The React package depends on CSS and on the headless library, never the other way.

The bots and the scanner sit outside the packages. They read and write other teams' repos, so they need their own permissions, logs and rate limits, and they must never be a dependency of an app.

Follow one change through the system: a designer darkens the muted text color for dark mode. It starts in Figma, becomes a pull request, passes the contrast check and visual review, merges, gets released as a minor, reaches apps through the migration bot or the team's own upgrade, and is finally served to users as a few changed bytes of CSS.

Data model: tokens, components and adoption records

A design system has little user data, but it has three kinds of records that tools read and write: tokens (the design decisions), a component manifest (what exists, its status, owner and links), and adoption records (what each repo uses). Each lives somewhere different, chosen by who writes it and how it's versioned.

// Lives in git as DTCG JSON; versioned with the packages.
type Token = {
  path: string[];              // ["color", "action", "primary"]
  $type: "color" | "dimension" | "fontFamily" | "duration" | "shadow";
  $value: unknown;             // a literal or an alias like "{color.blue.600}"
  tier: "primitive" | "semantic" | "component";
  $deprecated?: string;        // "Use color.text.muted"
};

// Generated at build time from source and JSDoc; published with the docs.
type ComponentManifest = {
  name: string;                // "Dialog"
  status: "experimental" | "beta" | "stable" | "deprecated";
  since: string;               // "3.2.0"
  owner: string;               // "core" or a contributing team
  figmaNodeUrl: string;
  tokens: string[];            // component tokens it reads
  sizeBudgetKb: number;        // gzipped
};

// Written weekly by the scanner; stored in a small database behind a dashboard.
type AdoptionRecord = {
  repo: string; team: string; dsVersion: string | null;
  componentUses: Record<string, number>;   // { Button: 412, Dialog: 38 }
  localLookalikes: number;                 // home-made buttons, modals...
  overrides: number;                       // unlayered CSS on ds- classes
  rawColorValues: number;                  // hex and rgb outside tokens
  scannedAt: string;
};

Tokens live in git because they need review and versions. The manifest is generated, never hand-edited, so the docs, the scanner and the lint rules all agree on which components exist and which are deprecated. Adoption records live in a database because they are measurements over time, not source; the dashboard needs trends per team, not the latest file.

Interfaces: the contracts teams code against

A design system has four public interfaces: component props, CSS classes and data attributes, token names, and the tools (codemods, lint rules, CLI). Consistency across them matters more than any single API. If every component handles refs, class names, state and events the same way, a team that learned Button already knows half of Dialog.

type ButtonProps = {
  variant?: "primary" | "secondary" | "tertiary";  // default "secondary"
  tone?: "neutral" | "critical";                   // default "neutral"
  size?: "sm" | "md" | "lg";                       // default "md"
  isDisabled?: boolean;
  isPending?: boolean;          // shows a spinner, keeps focus, announces "Loading"
  onPress?: (e: PressEvent) => void;  // mouse, touch, keyboard, and screen reader
  children: React.ReactNode;
} & Omit<React.ComponentPropsWithoutRef<"button">, "onClick" | "disabled">;

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
  { variant = "secondary", tone = "neutral", size = "md", className, ...rest }, ref) {
  // behavior from the headless layer; looks from ds-css classes and data attributes
  return <AriaButton ref={ref} className={cx("ds-button", className)}
    data-variant={variant} data-tone={tone} data-size={size} {...rest} />;
});

• Every component forwards its ref and spreads remaining props onto its root element, so id, aria-*, data-testid and event handlers just work.
• State is exposed as data attributes (data-state="open", data-disabled), the same ones the CSS uses, so product CSS and tests have a stable hook that is part of the public API.
• Booleans read as questions (isDisabled, isPending), variants are string unions with a documented default, and nothing takes a raw color.
• Codemods have one CLI: npx @acme/ds-codemods list shows the transforms for a version range, and npx @acme/ds-codemods 6.0 src/ runs them all.
• Lint rules ship as a package: @acme/eslint-plugin-ds and a Stylelint config flag deprecated props, primitive tokens and raw hex values in product code.

Note what the API leaves out: no color prop, no style passthrough for colors, no margin prop. Spacing between components belongs to layout components (Stack, Inline, Grid) that read the spacing scale. Every prop we don't add is one we never have to deprecate.

Adoption and governance: making teams want it

A design system nobody adopts is an expensive side project. Adoption is not won by a mandate from leadership; teams comply on paper and keep their own buttons. It's won by being the fastest way to ship a good screen, and by a governance model that lets teams get what they need without waiting on 7 people.

The design-systems lesson compares the three governance models in general. Here the question is concrete: 24 teams will ask for far more components and variants than 7 people can build, so who builds them?

• RFCs: a one-page proposal (the problem, three teams that need it, the proposed API, accessibility notes). Reviewed weekly in public.
• Office hours twice a week, and a support channel with a published response time. Questions that come up twice become docs.
• Early adopters: start with two or three willing teams on real features, not a big-bang mandate. Their screens become the case studies that convince the rest.
• Make the right thing the easy thing: project templates with the system preinstalled, lint rules with autofix, and Figma libraries enabled by default for every design file.

Measuring adoption

Download counts on the registry say almost nothing: one install can mean 400 uses or one. The scanner reads code instead. Each week it parses every repo (with the same syntax tree tools the codemods use) and counts imports of each system component, home-made lookalikes (a Button or Modal defined in the repo), unlayered overrides of ds- classes, and raw color values outside tokens.

You don't have to build all of it. react-scanner is an open-source command line tool that reports which components and props a codebase uses, and Omlet is a hosted product that tracks component adoption across repos over time. Our scanner adds the parts specific to us: lookalikes, ds- overrides and raw colors.

On the design side, Figma's library analytics report how often each component is inserted and detached (unlinked from the library so a designer can change it freely). Enterprise plans can pull the same numbers through Figma's Library Analytics REST API. A component that is detached a lot is telling you it's missing something.

The headline metric is the coverage ratio: system component uses divided by system plus lookalike uses, per team. Pair it with the version spread (how many repos are on N, N-1, older) and the one-off color count. Publish it, but use it to find where the system is failing teams, not to rank them. A team with low coverage usually has a need the system doesn't meet yet.

Accessibility and performance: what the system guarantees

A design system is the most effective accessibility investment a company can make: one correct combobox fixes every combobox. But teams often hear "the components are accessible" and conclude their pages are. They aren't automatically.

A perfectly accessible button with the label "Click here", a dialog opened with no heading, or a form whose errors are only red text still fail users. So the system writes down a clear line between what it guarantees and what remains the product team's job. The aria-patterns and visual-accessibility lessons cover the techniques.

Two practices make the line real. First, each component's docs page has an accessibility section that lists both columns for that component, so the responsibility is next to the example engineers copy. Second, the system ships tools for the product side too: the lint plugin warns on an icon-only Button without aria-label, and an axe test helper lets teams run the same rules on their own pages in their own CI.

Performance: never heavier than hand-written code

Teams will compare the system's cost against writing the component themselves. If importing one Button pulls 80 KB, the system loses that argument, and it deserves to. The goal is that using the system costs about the same bytes and main-thread time as a careful hand-written version, and usually less, because it's optimized once for everyone. The code-splitting lesson covers bundling in general.

• ES modules, one file per component, so bundlers can drop what isn't imported (tree shaking). No single pre-bundled file.
• sideEffects declared: the package marks only its CSS files as having side effects, so the bundler can safely remove unused JavaScript modules.
• Subpath exports (@acme/ds-react/button) and no giant barrel file for icons: 1,200 icons are 1,200 modules. Barrel files slow dev servers even when production tree shaking works; Next.js's optimizePackageImports option exists for exactly this problem.
• Size budgets per entry enforced in CI: Button 3 KB, Dialog 9 KB, DatePicker 18 KB (gzipped, counting what each adds beyond React and the shared behavior core, which has its own budget). A pull request that goes over has to justify it.
• Heavy dependencies stay out of core: date math, virtualization and charting live in separate entry points that load only where used.

Server Components and the client boundary

In React Server Components, components are server components by default. A module that starts with the "use client" directive marks a boundary: it and everything it imports run on the client too. Anything with state, effects, context or event handlers must be on the client side of that line.

A design system that marks everything as client forces all its users' pages into client code; one that marks nothing breaks on first use. So the system sorts components. Static ones (Text, Heading, Stack, Card, Badge, icons) have no hooks and no directive, so a server page renders them with zero client JavaScript. Interactive ones (Button with onPress, Dialog, Tabs, Select) start with "use client".

Two details catch library authors. Bundling all components into one file loses per-file directives, so the build must keep one output module per component with the directive at its top. And themes must not rely on React context for colors: because our themes are CSS variables chosen by a data-brand attribute on html, server components get the right colors with no provider at all.

Running it in the interview

This question is open-ended, and the trap is spending 30 minutes on Button props. Interviewers want to see that you treat the system as a product with users, that you know the layers, and that you have a plan for change: versions, migrations and measurement. A 50-minute plan:

Follow-up questions to expect

Common mistakes: designing only the React components and forgetting the 15 non-React repos; using primitive colors in components so theming breaks; one package per component with no plan for the version matrix; treating semver as "props only" and breaking Rails apps with a class rename; and saying "we'll write a migration guide" where the answer should be codemods and a bot. The strongest answers also say what they would not build in year one: a full web component library, a page builder, or 200 components.