rgoussu.dev
rgoussu@goussu: ~/library/frontend
❯ ~/library/frontend cat design-systems.md

Design systems

# The shared language of product UI — design tokens, component libraries, documentation, and the governance that keeps them alive.

Conceptsaved 2026-08-08updated 2026-08-09 #frontend#design-systems#components#ui

Overview

A design system is the single source of truth for a product's UI: design tokens (color, spacing, typography as named decisions), a component library implementing them, usage guidelines, and the governance to evolve it all coherently. It is a product serving products — its success is measured in adoption and consistency across teams, not in the beauty of its Storybook. Reference points: Material Design, Atlassian, Shopify Polaris, GOV.UK.

Key points

  • Design tokens are the foundation: platform-agnostic named values (color.action.primary, space.200) flowing from a source of truth into CSS variables and component code; semantic tokens (by purpose) over raw palette values — they make theming and dark mode tractable.
  • Component library: accessible by default (WAI-ARIA patterns, focus management — centralizing a11y is a top payoff), themeable, versioned and published like any dependency; headless libraries (Radix, React Aria) separate behavior from skin.
  • Documentation is half the system: do/don't usage guidance, live examples (Storybook), contribution process — an undocumented system doesn't get adopted.
  • Governance models: central team vs. federated contributors vs. hybrid; breaking changes, deprecation policy, and versioning discipline decide whether teams trust it.
  • Failure modes: the system nobody adopts (built in isolation from product needs), the fork-per-team drift, tokens defined but bypassed with hard-coded values.
  • To explore: design/code sync (Figma tokens → code), visual regression testing (Chromatic), multi-brand theming, atomic design as the structuring methodology.

Practice

  • Token retrofit (source) — take an existing side project, extract every hard-coded color/space value into semantic tokens (CSS variables), then add dark mode by swapping only the token layer; proves the tokens earn their keep.
  • Storybook-driven component build (source) — build three components in isolation with a story per state, do/don't docs, and the a11y addon wired in; documentation-first is the habit being drilled.
  • Headless re-skin (source) — wrap Radix (or React Aria) primitives in your own tokens; teaches the behavior/skin separation and how much a11y you get to not rewrite.
  • Design system from scratch (source) — the full flagship build: tokens → accessible atomic components → documented, versioned library.

Related