UX Encyclopedia

Building Your Own Design System

A design system = design tokens + component library + usage guidance + governance. Its purpose: consistency at scale and cheaper decisions — solve each problem once.

Try it — swap the theme and see which card survives. Both cards use identical markup. The left is styled with raw hex values, the right with role tokens. Re-theming the token card means remapping six variables; the raw card can only be re-themed by rewriting it.

Styled with raw values (#FFF, #111827, #4F46E5 …)

Quarterly report

Revenue up 12% — three regions pending review.

Updated 2 hours ago

#FFFFFF#111827#6B7280#E5E7EB#4F46E5

Styled with role tokens (surface, on-surface, primary, on-primary …)

Quarterly report

Revenue up 12% — three regions pending review.

Updated 2 hours ago

surfaceon-surfacemutedoutlineprimaryon-primary

Light: both cards pass. Hardcoded values only feel safe until the first theme swap.

When (and when not)

A single small product may only need a "UI kit" (styles + a few components). Build a true system when multiple products/teams/platforms must stay coherent, or churn in UI decisions is visibly expensive. (Nathan Curtis's and Brad Frost's writings both stress: a design system is a product serving products — it needs ownership and a roadmap, or it rots.)

Layered architecture (Atomic Design, Frost 2013 — adapted)

tokens → primitives (atoms: button, input, icon) → composites (molecules: form field, card) → patterns (organisms: nav bar, checkout form) → templates/pages. Document at every layer: what it is, when to use it, when NOT to, content guidelines, accessibility notes.

Design tokens (the foundation)

  • Name by ROLE, not value: color-surface, color-primary, space-md, radius-card, font-body — never blue-500 at the usage layer. Two tiers: global/core tokens (raw values) → alias/semantic tokens (roles referencing core). This is the shared model across Material 3, Fluent 2, and the DTCG format — follow it and theming (dark mode, brands, density) becomes a token swap.
  • The W3C Design Tokens Community Group format reached its first stable version in October 2025 (Design Tokens Format Module 2025.10, designtokens.org): a vendor-neutral JSON format ($value, $type, $description, aliases, groups) with standardized theming support and modern color spaces. Tooling already speaks it — Figma, Tokens Studio, Style Dictionary, Terrazzo, Penpot, Sketch. New systems should store tokens in this format and generate platform outputs from it.
  • Minimum viable token set: color roles (incl. on-colors + semantic status), type scale (5–7 roles), spacing ramp (8-pt based), radius ramp, elevation/shadow levels, motion durations & easings, breakpoints.

Multi-brand theming

If more than one brand/white-label skin is even plausible, architect for it now — retrofitting is expensive. The mechanism: components reference ONLY semantic tokens; each brand supplies its own core palette + any overridden semantic mappings; themes (light/dark/high-contrast/density) multiply per brand, so keep the semantic layer small. Test every component against the ugliest brand, not the flagship. Brand-specific components should be rare, quarantined, and named as such.

Component quality bar (each component ships with)

All states: default/hover/focus-visible/active/disabled/loading/error • keyboard behavior per WAI-ARIA Authoring Practices Guide (APG) patterns • RTL support • dark theme • responsive behavior • content guidance (label casing, max lengths) • do/don't examples • code + design (Figma) kept in sync — a system where design and code diverge is two systems.

The code-first / headless shift (ecosystem observation)

A visible mid-2020s trend: teams stop hand-building interaction logic and compose their system from headless (unstyled, accessible) primitives, adding only tokens + styling on top:

  • React Aria (Adobe) — hooks + components encoding years of ARIA/ interaction research; the deepest accessibility pedigree.
  • Radix Primitives (acquired by WorkOS) — popularized the pattern; the base of shadcn/ui; maintenance pace has visibly slowed since ~2024.
  • Base UI (MUI; v1.0 December 2025) — ~35 primitives built by ex-Radix/MUI engineers as the actively maintained successor niche.
  • shadcn/ui — not a library but a copy-the-code distribution model (own the source, restyle freely) layered on primitives.

Implication for system builders: buying focus management, keyboard behavior, and ARIA from a primitive layer is now often the responsible default — spend your effort on tokens, composition, and guidance instead. Evaluate maintenance health before committing; this layer churns.

AI-assisted component generation (emerging practice)

Coding agents and design-to-code tools increasingly generate UI directly. Consequences for systems (conventions forming, not settled standards): machine-readable assets pay off double — DTCG tokens, typed component props, and prose usage rules that an agent can ingest (some teams expose docs/tokens via MCP servers or llms.txt-style indexes); a well-documented system steers AI output toward itself, while a poorly documented one gets bypassed by plausible-looking bespoke code. Linting/CI that flags off-system colors, spacing, and raw HTML controls matters more, not less, when generation is cheap. Treat AI output as a contribution: same review bar, same accessibility checks.

Governance, versioning & breaking changes

  • Clear contribution model (who proposes, who approves); a visible roadmap; support channel with response-time expectations.
  • Semantic versioning as the contract: breaking changes (removed props, renamed tokens, DOM/markup changes that break selectors or overrides) only in majors. Batch breaking changes into infrequent majors rather than dribbling them out.
  • Every deprecation gets: a console/docs warning, a documented replacement, and a stated removal horizon (commonly one major).
  • Migration support is the adoption price: changelogs + written migration guides at minimum; codemods (automated rewrites) for anything mechanical — large systems (e.g., Material, Polaris historically) ship them routinely.
  • Token renames are breaking changes too — alias old names for a deprecation window.

Measuring adoption (analytics)

You can't govern what you can't see. Common, tool-supported metrics: component adoption rate (system vs. bespoke instances, in code via static analysis — e.g., Omlet, react-scanner — and in design via Figma library analytics); token coverage (share of hard-coded values vs. tokens, lintable); detachment/override rates (where the system fails people); version spread across consuming apps (migration lag = risk); docs traffic + support-request themes (what's confusing). Pair numbers with qualitative surveys — high adoption of a hated system is churn waiting to happen. (Metric set is convention, consolidated from practitioner writing, not a formal standard.)

Documentation pattern per component (template)

Purpose → anatomy diagram → variants & when to use each → behavior (states, keyboard, focus) → content guidelines → accessibility notes → related components → code reference.

Other notable systems worth studying (verified live, mid-2026)

  • IBM Carbon (carbondesignsystem.com) — exemplary open governance and framework spread (React, Angular, Vue, Svelte, Web Components); strong data-viz guidance.
  • Shopify Polaris (polaris.shopify.com) — exemplary admin/merchant UX guidance AND a live case study in platform strategy: Polaris React was deprecated (repo archived Jan 2026) in favor of framework-agnostic Polaris web components unified across Admin/Checkout (2025) — read it for both content and migration handling.
  • Atlassian Design System (atlassian.design) — exemplary token-first architecture and pattern depth for dense productivity software.
  • GOV.UK Design System (design-system.service.gov.uk) — exemplary evidence-backed patterns (each component documents research findings) and accessibility rigor; Frontend v6 (2026) shows disciplined breaking- release practice.
  • USWDS (designsystem.digital.gov) — U.S. federal system; exemplary Section 508/accessibility documentation and design-principle framing; actively maintained (v3.x line).

Sources

↑↓ to navigate · Enter to open · Esc to close