Skip to content
Design Systems

Architecture & Scale

Listen 0%
Speed

11 · Design Systems

Atomic design, design tokens, headless primitives, theming, governance, and distribution — the system that lets dozens of teams ship a consistent, accessible product without re-deciding what a button is. Current as of the token-pipeline + headless-primitive era (Radix, React Aria, Base UI, design tokens via Style Dictionary / W3C DTCG format).

Positioning

A design system is not a component library. A component library is code; a design system is code + design + documentation + process + governance — the shared source of truth that keeps a product coherent as it scales across teams and surfaces. The component library is the most visible artifact, but the tokens, the contribution model, and the governance are what make it survive contact with twelve product teams. (This is Rian’s specialty area; the notes below assume that level.)

Foundations

Atomic Design (Brad Frost)

A mental model for composition, not a folder structure mandate:

  • Atoms — irreducible UI primitives (a label, an input, a button, a color token).
  • Molecules — small groups of atoms that do one thing (a search field = label + input + button).
  • Organisms — complex, distinct sections (a header, a product card grid).
  • Templates — page-level layout skeletons with placeholder content.
  • Pages — templates with real content; where you validate the system against reality.

The value is the thinking (compose from primitives; promote repeated molecules into the system), not literal atoms/ folders. Most mature systems organize by component, not by atomic tier.

Design tokens — the foundation layer

Tokens are named design decisions stored as data, decoupled from any platform. color.background.danger, space.4, font.size.body, radius.md. They are the contract between design and engineering.

  • Tiers: primitive/global tokens (blue.500 = #2563eb) → semantic/alias tokens (color.action.primary = {blue.500}) → component tokens (button.primary.bg = {color.action.primary}). Semantic tokens are the indirection that makes theming and rebrands tractable — components reference intent, not raw values.
  • Format: the W3C Design Tokens Community Group (DTCG) JSON format is the emerging standard for interchange; Style Dictionary (Amazon) is the dominant build tool that transforms one token source into CSS custom properties, JS/TS, iOS, Android, Tailwind config, etc. Tokens Studio bridges Figma ↔ token files.
  • Runtime expression: on the web, semantic tokens compile to CSS custom properties (--color-action-primary), which gives you runtime theming (light/dark, brand switching, density) without rebuilds.

Headless / unstyled primitives — the behavior layer

The big shift of the last few years: separate behavior + accessibility (hard, universal, easy to get wrong) from styling (opinionated, per-brand). Headless primitives ship the former and leave the latter to you.

  • Radix UI Primitives — unstyled, accessible React primitives (dialog, popover, dropdown, tooltip) with correct focus management, keyboard interaction, and ARIA. The most common foundation in 2026.
  • React Aria / React Aria Components (Adobe) — the most rigorous a11y/interaction layer, cross-adapted for many components, internationalized.
  • Base UI — from the Radix/MUI lineage, the headless successor direction for MUI.
  • TanStack headless utilities (Table, Virtual, Form) for data-heavy primitives.
  • shadcn/ui — not a dependency but a copy-in pattern: Radix + Tailwind components you own and edit. Hugely popular as a starting point, but it’s a scaffold, not a governed system — for an enterprise design system you typically build a governed package on top of primitives rather than copy-pasting.

The senior takeaway: don’t hand-roll accessible dialogs/menus/comboboxes in 2026. Build your design system’s styled components on top of Radix/React Aria; you inherit years of a11y edge-case work (19).

Deep dive

1. The layered architecture of a modern design system

Design tokens (JSON / DTCG)  ──Style Dictionary──▶  CSS vars + TS types + Tailwind preset
        │
Headless primitives (Radix / React Aria)  ── behavior + a11y
        │
Styled components (your DS package)  ── tokens applied to primitives
        │
Patterns / recipes  ── composed, opinionated assemblies (a Form, a DataTable)
        │
Product apps / MFEs  ── consume the package (or the DS-as-remote, 09)

2. Theming strategies

  • CSS custom properties + semantic tokens = the dominant approach. Switch data-theme="dark" or data-brand="x" on a root element; everything downstream re-resolves. Zero JS, instant, SSR-safe.
  • Multi-brand: brand-specific semantic token sets layered over shared primitives; components never change, only the token resolution does.
  • Density / spacing modes: a token scale swap.
  • Avoid theming via JS context for visual values when CSS vars can do it — CSS vars are faster, work without hydration, and don’t cause re-renders.

3. Distribution & versioning

  • Package the system as a versioned npm package (often a monorepo with tokens, icons, react, css packages). Use semantic versioning seriously: a token rename or a prop change is a breaking change.
  • Changesets for coordinated multi-package releases and changelogs.
  • Treeshakeability: ship ESM, side-effect-free, per-component entry points so apps only bundle what they use (14).
  • In MFE contexts (09): the design system should be consumed per-MFE or exposed as a remote, not force-shared by the host — otherwise every team is pinned to one version forever.

4. Documentation & tooling

  • Storybook — the de facto component workshop: isolated states, controls, interaction tests, a11y addon, visual-regression hooks (16). The living catalog.
  • Figma as the design source of truth; Tokens Studio to keep Figma variables and code tokens in sync (ideally one direction, tokens-as-data being the contract).
  • A docs site (often Storybook Docs or a custom site) with usage guidelines, do/don’t, a11y notes, and props tables generated from TS types.

5. Governance — the part that actually determines success

  • Operating model: centralized (one team owns it), federated/distributed (a core team + contributors from product teams), or hybrid. Federated scales best once adoption grows; pure centralized becomes a bottleneck.
  • Contribution model: a clear RFC/proposal process, “definition of done” (a11y, tokens, docs, tests, responsive, RTL), and a review gate. Without this, the system fragments.
  • Adoption tracking & deprecation: measure usage, version drift, and provide codemods for breaking changes. A design system nobody upgrades is a fork farm.
  • Accessibility as a gate, not an afterthought (19) — every component meets WCAG before it ships.

Worked example: a token-driven, primitive-based Button

// tokens (compiled by Style Dictionary to CSS vars)
:root {
  --color-action-primary-bg: #2563eb;     /* semantic ← primitive */
  --color-action-primary-fg: #ffffff;
  --radius-md: 8px;
  --space-3: 12px;
}
[data-theme='dark'] { --color-action-primary-bg: #3b82f6; }

// Button.tsx — styled component over a primitive-quality base
import { forwardRef } from 'react';
const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant = 'primary', ...props }, ref) => (
    <button ref={ref} data-variant={variant} className="ds-button" {...props} />
  )
);
// ds-button reads ONLY semantic tokens — never raw hex:
//   background: var(--color-action-primary-bg);
//   color: var(--color-action-primary-fg);
//   border-radius: var(--radius-md);
//   padding-block: var(--space-3);

Dark mode, rebrand, and density all work by swapping token values — the component code never changes. For a menu/dialog/combobox, wrap a Radix or React Aria primitive instead of hand-rolling focus and ARIA.

Pitfalls & gotchas

  • Building a component library and calling it a design system — skipping tokens, docs, and governance. It will fragment.
  • Raw values in components (hardcoded #2563eb, 16px) — defeats theming and tokenization. Lint against it.
  • No semantic token tier — primitive tokens referenced directly means a rebrand touches every component.
  • Hand-rolling accessible widgets — dialogs/menus/comboboxes have brutal a11y edge cases; use primitives.
  • Forcing the DS as a host-shared singleton in MFEs — pins every team to one version (09).
  • Figma and code drifting — no token pipeline means design and engineering slowly disagree.
  • No deprecation/codemod story — breaking changes strand teams on old versions.
  • Over-abstracting too early — promoting one-off components into the system before a pattern is proven.

Interview questions

  1. Design system vs component library — what’s the difference?
  2. What are design tokens, and why have a semantic/alias tier?
  3. How do CSS custom properties enable runtime theming and multi-brand?
  4. Why use headless primitives (Radix/React Aria) instead of building your own dialog?
  5. How do you keep Figma and code tokens in sync?
  6. How would you version and distribute a design system across many teams?
  7. How does design-system distribution work in a micro-frontend architecture?
  8. What does governance look like, and why does it determine success?
  9. Atomic design — what is it actually useful for?
  10. How do you make a design system accessible by default?

Recommendations

  • Build on a token pipeline (DTCG JSON → Style Dictionary → CSS vars + TS) with primitive → semantic → component tiers.
  • Base interactive components on Radix / React Aria primitives; never hand-roll a11y.
  • Express themes via CSS custom properties, not JS context, for visual values.
  • Ship a versioned, treeshakeable, ESM package; use Changesets; provide codemods for breaking changes.
  • Run a federated governance model with an explicit contribution definition-of-done that includes a11y.
  • Use Storybook as the workshop + visual-regression surface (16); generate prop docs from TS.
  • In MFEs, consume the DS per-MFE or as a remote, not host-shared.

Books & references

  • “Atomic Design” — Brad Frost (free at atomicdesign.bradfrost.com). The compositional mental model.
  • “Design Systems” — Alla Kholmatova (Smashing Magazine). The best book on the system/process/governance side.
  • “Expressive Design Systems” — Yesenia Perez-Cruz (A Book Apart). Governance and flexibility.
  • W3C Design Tokens Community Group spec (tr.designtokens.org) — the token interchange format.
  • Style Dictionary docs (styledictionary.com) — the token build pipeline.
  • Radix Primitives (radix-ui.com) and React Aria (react-spectrum.adobe.com/react-aria) — the headless layers; read their a11y docs.
  • Storybook docs (storybook.js.org) — the workshop and testing surface.
  • Design system case studies: Adobe Spectrum, Atlassian, GOV.UK, Shopify Polaris, IBM Carbon, Material — read how mature systems document tokens and governance.

Connections

Frontend Deep-Dive Library · content is the single source of truth.