Design systems

The problem: six teams, fourteen blues

Picture a company with one web app and six product teams: checkout, search, account, admin, help center, and marketing. Each team ships every week. Each needs buttons, inputs, dialogs, tables, and toasts. Nobody planned to build these six times, but each team needed a button on a Tuesday and the quickest path was to write one.

Two years later, someone runs a script over the CSS and finds 14 different blues, 9 button styles, 5 date pickers, and 3 modal dialogs. Two of the dialogs do not trap focus, so keyboard users get lost behind them. One of the date pickers cannot be used with a screen reader at all. Every one of these was a reasonable choice when it was made.

Then the product lead asks for dark mode. In this codebase that means finding every hard-coded #1a73e8 and #ffffff in hundreds of files and deciding what each becomes in dark mode, six times in six styles. A week of work becomes a quarter.

What goes wrong without a shared system

• Inconsistency. The same action looks different on different pages, and the product feels stitched together.
• Repeated work. Six teams each spend days on a dropdown. Each fixes its own bugs, and nobody shares the fixes.
• Accessibility gaps. Focus traps, keyboard support, and ARIA roles are hard to get right. When every team writes its own dialog, some get it wrong, and you find out from an audit or a complaint.
• Slow global changes. A rebrand, a new font, dark mode, or a higher contrast ratio means touching every screen by hand.
• Design and code drift. The design file says one thing, the code says another, and nobody knows which one is right.

What a design system actually is

A design system is the shared set of decisions, and the tools that carry them, that lets many teams build one consistent product. It is more than a component library. A good one has five parts that work together.

1. Design tokens: named values for color, spacing, type, radius, shadow, and motion, like color.action.primary or space.4. They are the single source of truth for the look.
2. Components: coded, tested, accessible building blocks like Button, TextField, and Dialog, in the frameworks the company uses.
3. Patterns: agreed ways to solve common problems with those components, like how a form shows errors or what an empty table says.
4. Documentation: when to use what, live examples, do and don't, accessibility notes, and a changelog.
5. People and process: a team or group that owns the system, a way for others to contribute, and a release process with versions.

Leave out the tokens and theming becomes a search-and-replace job. Leave out the docs and people use components wrongly. Leave out the process and the system either freezes or falls apart. This lesson covers each part, with the most depth on tokens and theming, where the engineering is least obvious.

Two related lessons go deeper on parts we only touch here: component API design (how to shape props, and codemods) and contract and visual tests (Storybook and visual baselines).

The mental model: layers of decisions

Think of a design system as a stack of layers. Each layer is built only from the layers below it, and makes a few more decisions than they do. Change a lower layer and everything above it changes with it. That one property is the whole point.

1. Tokens at the bottom: raw values with names. blue.600 = #1f5fd1, space.4 = 16px, radius.md = 6px. No components, no layout, just the palette and the scales.
2. Primitives: the smallest components. Box, Stack, Text, Icon, Button, Input, Checkbox. They read tokens and know nothing about any product.
3. Patterns (sometimes called composites): primitives put together to solve a common problem. A form field with label, hint, and error. A dialog with a title, body, and actions. A data table with sorting and an empty state.
4. Templates: page-level layouts. A settings page with a side nav, a list-detail page, a sign-in page. They define regions, not content.
5. Product pages at the top: owned by product teams, not by the system. They fill templates with real data and product logic.

An everyday comparison is a kitchen. Tokens are the pantry ingredients, primitives are prepared basics like a sauce, patterns are dishes on the menu, and templates are the set menu of starter, main, and dessert. The product page is tonight's dinner. Swap the salt in the pantry for a low-sodium one and every dish changes, without anyone rewriting a recipe.

Two rules that keep the stack healthy

Rule one: depend only downwards. A Button may use tokens. It must not import the checkout page's code. A product page may use templates, patterns, primitives, and tokens, but should not skip them for raw hex values. Code that hard-codes a value is code a global change can no longer reach.

Rule two: the higher the layer, the less of it belongs in the shared system. Tokens and primitives are almost always shared. Patterns are shared when several products need the same one. Templates are shared only in companies with many similar apps. Product pages are never shared.

One source of truth, many outputs

The second half of the mental model is where the truth lives. A mature system keeps its decisions in one place, usually token files in a repository, and generates everything else: CSS variables for the web, Swift constants for iOS, XML or Kotlin resources for Android, and variables in the design tool. Designers and engineers then read the same names.

When the truth lives in two places, such as a Figma file and a CSS file that someone copies values between, they drift within months. The fix is not more discipline but a pipeline: edit once, build, and every platform gets the new value. The next chapter shows that pipeline.

Design tokens: primitive, semantic, component

A design token is a named design decision: a name plus a value, like space.4 = 16px. Code and design files refer to the name, never to the raw value. That indirection is what makes global change cheap: change the value once and everything that uses the name follows.

Not all tokens are the same kind of decision, though. Most mature systems split them into three tiers, and the split is the most useful idea in this lesson.

The three tiers

• Primitive tokens (also called base, global, or reference tokens) name every value you are allowed to use. color.blue.600 = #1f5fd1, color.gray.900 = #16181d, space.4 = 16px. They say what a value is, not where it goes. Product code should almost never use them directly.
• Semantic tokens (also called alias or system tokens) name a purpose and point at a primitive. color.text.default points to color.gray.900, color.action.primary points to color.blue.600, color.border.focus points to color.blue.500. This is the layer product code and components use.
• Component tokens name one property of one component and point at a semantic token. button.primary.bg points to color.action.primary. They let one component be tuned without touching others.

The tiers pay off when a theme changes. In dark mode, color.text.default points at gray.50 instead of gray.900, and no component or primitive changes: only the arrows in the middle tier move. A brand refresh is the opposite: the primitive blue.600 gets a new hex value, and everything that points at it follows.

Naming tokens

Names are the API of the system, and renaming one later is a breaking change. Most systems use a fixed order from general to specific, such as category, then purpose, then variant, then state.

color.text.default
color.text.muted
color.text.danger
color.bg.surface
color.bg.surface.raised
color.border.focus
color.action.primary
color.action.primary.hover
space.1  space.2  space.3  space.4  space.6  space.8
radius.sm  radius.md  radius.full
font.size.body  font.size.heading.lg
motion.duration.fast

• Name the purpose, not the look. color.text.danger stays right when danger becomes orange. color.red becomes a lie.
• Use a scale, not adjectives, for sizes. space.1 to space.12 on a 4px grid leaves room to insert values. small, medium, large runs out at extra-extra-large.
• Keep the set small. If two tokens always change together, they are one token.

Storing tokens: the DTCG format

Tokens live in data files, not in CSS, so that every platform can read them. The W3C Design Tokens Community Group (DTCG) defines a JSON format for this. It is a community group report, not a W3C standard, but it is the format design tools and build tools have converged on. In October 2025 the group published its first stable version, the Design Tokens Format Module 2025.10.

{
  "color": {
    "$type": "color",
    "blue": {
      "600": { "$value": "#1f5fd1" },
      "300": { "$value": "#8fb0f0" }
    },
    "action": {
      "primary": {
        "$value": "{color.blue.600}",
        "$description": "Main call to action: buttons, links"
      }
    }
  }
}

A build tool then turns the JSON into code for each platform. Style Dictionary, an open-source tool first released by Amazon, is the most common, and version 4 and later read the DTCG format. Plugins such as Tokens Studio sync tokens with Figma. The build resolves aliases, converts units (px to rem for web, points for iOS), and writes one output per platform.

:root {
  --color-white: #ffffff;
  --color-blue-300: #8fb0f0;
  --color-blue-600: #1f5fd1;
  --color-gray-50: #f6f7f9;
  --color-gray-900: #16181d;
  --color-gray-950: #0b0c0f;
  --color-text-default: var(--color-gray-900);
  --color-action-primary: var(--color-blue-600);
  --space-2: 0.5rem;
  --space-4: 1rem;
}

.button-primary {
  background: var(--color-action-primary);
  padding: var(--space-2) var(--space-4);
}

Do you need all three tiers?

Now try it. The lab below has a small app drawn twice, light and dark. Some parts use semantic tokens, and some use hard-coded values copied from the design file. Change a token and watch which parts follow.

Theming and dark mode

A theme is a mapping from semantic tokens to primitive values. Light and dark are two mappings; high contrast and a second brand are two more. Components never know which theme is active: they read --color-text-default and get whatever the current mapping says.

CSS custom properties make themes cheap

On the web, the mapping is a block of CSS custom properties (CSS variables). Custom properties inherit down the DOM tree like color does, and var() is resolved at the time styles are computed. So switching a theme is one attribute change on an ancestor element: the browser recomputes styles and every component picks up the new values. No component re-renders in React or any other framework.

:root,
[data-theme="light"] {
  color-scheme: light;
  --color-bg-surface: var(--color-white);
  --color-text-default: var(--color-gray-900);
  --color-action-primary: var(--color-blue-600);
}

[data-theme="dark"] {
  color-scheme: dark;
  --color-bg-surface: var(--color-gray-950);
  --color-text-default: var(--color-gray-50);
  --color-action-primary: var(--color-blue-300);
}

The color-scheme property tells the browser which schemes this part of the page supports, so form controls, scrollbars, and the default page background render to match. Without it you get a dark page with bright white native checkboxes and scrollbars.

Following the operating system

The prefers-color-scheme media query reports the user's operating system setting. Most products offer three choices: Light, Dark, and System. System means "follow the media query, and keep following it if it changes", for example when a phone switches to dark at sunset.

The newer light-dark() CSS function puts both values in one place: color: light-dark(#16181d, #f6f7f9) uses the first value when the element's used color scheme is light and the second when it is dark. It needs color-scheme to be set, and it only works for color values. It has been Baseline, supported in all major browsers, since May 2024. It suits a small system with exactly two schemes; a token build that writes separate mappings scales better to high contrast and extra brands.

/* Follow the OS by default */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme]) {
    color-scheme: dark;
    --color-text-default: var(--color-gray-50);
  }
}

/* Or, with light-dark(), one declaration per token */
:root {
  color-scheme: light dark;
  --color-text-default: light-dark(var(--color-gray-900), var(--color-gray-50));
}

The flash of the wrong theme

Almost every team ships this bug once. The user picks Dark, and the app saves theme=dark in localStorage. On the next visit the server renders HTML without knowing that, so the page paints light.

Then JavaScript loads, reads localStorage, and switches to dark. The user sees a white flash on every page load, which in a dark room is worse than no dark mode at all.

<head>
  <meta name="color-scheme" content="light dark">
  <script>
    try {
      const t = localStorage.getItem("theme");
      if (t === "light" || t === "dark") {
        document.documentElement.dataset.theme = t;
      }
    } catch {}
  </script>
  <link rel="stylesheet" href="/app.css">
</head>

Dark mode is a design, not an inversion

• Re-check contrast. In our palette blue.600 is 5.8:1 on white but only 3.4:1 on gray.950, below the 4.5:1 that text needs. Each theme mapping needs its own contrast check, which is why dark mode uses lighter steps like blue.300.
• Show depth with lighter surfaces. Shadows barely show on dark backgrounds, so raised surfaces (cards, menus) usually get a slightly lighter background instead. That is a semantic token like color.bg.surface.raised.
• Avoid pure black and pure white. Pure white text on pure black can cause glare for some readers, so most dark themes use a dark gray background and off-white text.
• Watch images and charts. Logos with dark text, screenshots, and chart colors may need dark variants or a token of their own.

The same machinery serves other themes. prefers-contrast: more can switch to a high-contrast mapping. forced-colors: active means the OS (for example Windows contrast themes) replaces your colors, so components must keep borders and focus outlines visible rather than relying on background color alone. Density themes (compact, comfortable) re-map spacing tokens the same way color themes re-map colors.

Primitives, patterns, and templates

Tokens decide how things look. Components decide how things behave. The hardest everyday question for a system team is not how to build a component but which layer a proposed component belongs in, or whether it belongs in the system at all.

Primitives: small, boring, everywhere

Primitives are the components every screen uses: layout helpers (Box, Stack, Grid), typography (Text, Heading), and basic controls (Button, Link, TextField, Checkbox, Select, Icon). They take a small set of props tied to tokens, such as size="sm" or gap="4", and refuse arbitrary values. That refusal is the feature: a Stack that accepts gap="13px" no longer enforces the spacing scale.

Primitives should render semantic HTML. A Button renders a button element, a Link renders an a element with an href. This sounds obvious, yet a clickable div posing as a button is a common source of keyboard and screen reader bugs.

Patterns: solving a problem once

A pattern combines primitives to solve a recurring problem, and it encodes a decision that would otherwise be made differently by every team. A form field pattern decides where the label goes, how hint text and error text are announced, and when validation runs. A dialog pattern decides how focus moves in, where it goes on close, and what Escape does.

• Form field: label, control, hint, and error, wired with for, id, and aria-describedby so a screen reader reads the error with the field.
• Dialog: focus moves inside on open, stays inside, and returns to the trigger on close; Escape closes it; the page behind is inert.
• Data table: sortable headers announce the sort direction; an empty state says what to do next; a loading state keeps the layout from jumping.
• Toast: announced through a live region without stealing focus, and stays long enough to read.

Patterns can live as code components, as documented recipes, or both. A recipe ("a destructive confirmation is a Dialog with the danger button on the right and Cancel focused first") is cheaper to maintain than a component with 20 props. Start with a recipe once three or more teams need the pattern, and promote it to a component when its API has settled.

Templates: layout, not content

A template is a page skeleton: an app shell with header and side navigation, a list and detail layout, a settings page with sections and a save bar. Templates are worth sharing in companies with many internal tools, where every admin page looks the same. In a consumer product with a handful of unique pages, they often belong to the product team.

Accessibility built in

The biggest single benefit of a design system is that accessibility gets solved once by the people best placed to solve it, then inherited by every team. A product engineer who uses the system's Combobox gets the keyboard model, the aria-expanded and aria-activedescendant wiring, and the screen reader announcements for free. The ARIA patterns lesson covers those widget patterns in detail.

• Focus styles as tokens. A color.border.focus token and a shared focus ring, shown with :focus-visible, so focus is always visible and consistent.
• Contrast in the tokens. Every text and background pair that the semantic layer allows is checked against WCAG ratios (4.5:1 for normal text, 3:1 for large text and UI parts) in every theme, in CI.
• Motion tokens that respect settings. Duration tokens drop to near zero under prefers-reduced-motion: reduce.
• Required accessible names. The IconButton type makes a label prop required, so a button with only an icon cannot ship without a name.

The design system decides which components exist and what they promise. How people call them (compound components like Tabs.List, headless hooks, controlled and uncontrolled state) is the subject of the component API design lesson.

Versioning and breaking changes

A design system is a dependency of every product team. Each release can fix bugs for 30 apps at once, or break 30 apps at once. Versioning is how the system tells its users which one to expect, and how it gives them time to move.

Semantic versioning, applied to UI

Most systems use semantic versioning (semver): a version like 4.2.1 is MAJOR.MINOR.PATCH. A patch fixes bugs, a minor adds things without breaking existing use, and a major may break it. The hard part is deciding what "break" means for UI, because a UI has more surface than its props.

An observation known as Hyrum's Law applies strongly here: with enough users, every behavior someone can observe becomes something someone depends on. If 12 apps style .ds-button__label, renaming that class is a breaking change even if the docs said class names are private. The defense is to not expose internals in the first place: no stable class names, styles applied through tokens and props.

Recording changes with changesets

In a repository with many packages (tokens, React components, icons, a web components build), tracking what changed and which version each package needs is error-prone by hand. Changesets is a popular tool for this. Each pull request adds a small markdown file that names the packages it changes, the bump type, and a sentence for the changelog. At release time the tool combines them, bumps versions, writes CHANGELOG.md files, and publishes.

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

Add `Button` `loading` prop to replace `busy`, and the
`color.action.primary.disabled` token. `busy` keeps working
for now and will be removed in 5.0.

Deprecation windows

Product teams have their own roadmaps, and nobody drops a feature to upgrade a button. So systems rarely remove anything in one step. They follow a deprecation window: ship the new way next to the old way, warn, help people move, then remove in the next major.

1. Add the replacement in a minor release. Old and new both work.
2. Mark the old one deprecated: a JSDoc @deprecated tag so editors strike it through, a development-only console warning, a lint rule, and a docs note.
3. Ship a codemod, a script that rewrites call sites automatically. The component API design lesson covers how codemods work.
4. Measure usage across repositories until it reaches zero or close to it.
5. Remove in the next major, with a migration guide. A common window is one or two quarters, long enough for teams to plan, short enough that the system does not carry two APIs forever.

Tokens follow the same path. When color.primary becomes color.action.primary, the build keeps color.primary as an alias of the new token, marked deprecated, for one major version. A lint rule flags the old name in product code.

Version skew

In a large company, different apps run different versions of the system. That is normal and fine when each app is its own page. It becomes a problem when two versions end up on the same page, for example with micro-frontends, where one team's widget brings ds-react@4 and the host runs ds-react@5.

• Two copies of the code in the bundle, often tens of KB or more.
• Clashing global CSS: both versions define --color-action-primary or the same class names with different values, and whichever loads last wins.
• Two buttons that look slightly different on the same screen, which is exactly what the system was meant to prevent.

Fixes include sharing one copy at run time (for example a shared singleton in module federation), declaring the system as a peer dependency so the host decides the version, and scoping CSS per major version with a prefix. The cheapest fix is organizational: keep everyone within one major version by making upgrades small and frequent.

Documentation and adoption

A design system that nobody uses is a cost with no benefit. Adoption is not automatic, even inside one company: product teams are busy, their own button already works, and the system's button might not do the one thing they need. Docs, tooling, and measurement are how a system earns its users.

What good docs contain

Docs answer the questions a product engineer has at the moment of building: which component do I need, how do I use it, and what should I not do with it. A props table alone answers only the second question.

• When to use it, and when not to. "Use Link to navigate, Button to perform an action" prevents more bugs than any props table.
• Live, editable examples for common cases, so people copy working code.
• Do and don't pairs with pictures: one primary button per view, not three.
• Accessibility notes: the keyboard behavior, what screen readers announce, and what the consumer must still provide (a label, a heading level).
• Props and token reference, generated from the types and token files so it stays current.
• Changelog and migration guides, linked from each component page.

Many teams build docs on Storybook, which renders each component state as a story and can generate props tables. Others build a dedicated docs site that embeds stories. Either way, stories double as the input for visual regression tests; the contract and visual tests lesson covers that side.

Measuring adoption

Adoption metrics tell the system team where to help, and tell leadership whether the investment is paying off. The useful ones are measured automatically from code, not from surveys.

Coverage is easy to game. A team can wrap every page in a system Box and score high while hand-coding everything inside. Counting interactive elements (buttons, inputs, menus, dialogs) is more honest, because that is where consistency and accessibility matter most.

Driving adoption

• Make the right thing the easy thing. A starter template that already uses the system and good TypeScript autocomplete do more than any mandate.
• Lint, then enforce. Start lint rules for raw colors and native elements as warnings, and make them errors for new code once most teams are clean.
• Help with migrations. Pair with a team to move its first screens. Each migration teaches the system team what is missing.
• Fix gaps fast. A team that waits two months for a feature builds its own and stops asking. A documented escape hatch, such as a className or slot, beats a fork.
• Find champions. One engineer per product team who answers questions and brings feedback back.
• Show the payoff. When dark mode ships in a week for adopted screens and not for the rest, adoption sells itself.

Governance: who decides what goes in

Every design system has to answer the same questions: who decides whether a new component goes in, who reviews a token change, and who fixes a bug at 6 pm before a launch? The answers are its governance model. Weak governance sinks more systems than weak technical choices do.

Three models

A contribution process that works

1. Propose: a short issue that names the problem, shows the existing local versions, and lists which teams need it.
2. Agree the design: designers from both teams agree the behavior, states, tokens, and keyboard and screen reader behavior.
3. Build: the proposing team builds it in the system repository, with stories and tests.
4. Review: the core team reviews API, accessibility, and visuals. Clear criteria keep this from becoming taste.
5. Release and own: the core team takes over ownership, or the contributing team stays listed as co-owner for bugs.

Not every request deserves a new component. Some are better answered with a recipe, a new variant of an existing component, or a documented "build this locally". A clear "no, and here is what to do instead" keeps the system small and still unblocks the team.

Funding and roles

A system serving dozens of engineers needs at least a few people on it full time, usually designers and engineers together, often with an accessibility specialist shared with other teams. Budgets are easier to defend with numbers: hours saved per component not rebuilt, accessibility issues fixed once instead of per team, and time to ship a theme or rebrand.

In production: failure modes and real systems

Most design systems do not fail on day one. They fail slowly: the tokens sprawl, teams route around the components, the bundle grows, and two years later the company starts a "new design system" project. Knowing the usual failure modes lets you design against them from the start.

What breaks, how you notice, how you fix it

Performance angles

A design system sits on every page, so its costs multiply. JavaScript size comes first: a primitive like Button should cost a few KB at most, and teams should pay only for what they import. Fonts and icons come next: a system that loads four font weights and a 300 KB icon font on every page undoes careful product work.

The third cost is styling runtime. CSS-in-JS libraries that generate styles while rendering add work to every render and complicate server rendering and React Server Components. Several large systems have moved to plain CSS, CSS Modules, or build-time extraction.

Themes themselves are cheap. Changing the theme attribute on the root element triggers one style recalculation for the page, usually a few milliseconds, not something to optimize.

Real systems worth studying

Several large companies publish their systems openly. Details change often, so treat this as a map for further reading, not as current facts to quote.

The common thread: each keeps its decisions in tokens and docs, separate from component code. That is what lets one system serve several frameworks and platforms.

Design systems in a system design interview

Design systems come up in two ways. Sometimes the whole question is about one: "design a component library for a company with 20 teams". More often it is a follow-up inside another problem: "how would you keep this consistent across teams?", "how would you add dark mode?", or "how would you roll out a breaking change to the shared table?".

What to draw

1. The layer stack: tokens, primitives, patterns, templates, products. Say which layers are shared and who owns each.
2. The token pipeline: one JSON source, a build step, outputs for web, iOS, Android, and the design tool.
3. The theme mapping: semantic tokens pointing at different primitives for light and dark, applied with CSS custom properties.
4. The release flow: changesets, semver, deprecation window, codemods, adoption dashboards.

What to say, by level

Inside a larger problem, spend a minute or two on it unless the interviewer leans in. When the whole question is a design system, the people and process half matters as much as the code half.

Common mistakes

• Talking only about the component library. Mid and senior interviewers look for tokens, docs, governance, and adoption.
• Naming tokens by color. color.blue as the button color makes the dark mode answer fall apart.
• Applying the theme in a client effect. Say how the first paint gets the right theme.
• Forgetting the consumers. Every breaking change costs other teams time; mention deprecation windows and codemods.
• Building everything up front. Start with the components most teams need (button, input, dialog, layout) and grow from real demand.