Design systems get either too much hype or too little discipline. Done well, they speed every product decision and protect quality at scale. Done badly, they become bureaucratic theater. This guide covers what's actually in a design system and how to build one without losing the team in the process.
The Layers
| Layer | Contents | Purpose |
|---|---|---|
| Tokens | Color, type, spacing, radius, shadow values | Atomic, semantic values; theming foundation |
| Components | Buttons, inputs, modals, cards, nav | Reusable building blocks with defined behaviour |
| Patterns | Forms, empty states, navigation, data tables | How components combine for common UX flows |
| Templates | Page layouts, dashboard structures | Higher-level scaffolds |
| Documentation | Usage rules, props, examples, accessibility | Enables adoption without 1:1 support |
| Governance | Contribution process, review, versioning | Keeps the system trustworthy as it grows |
Tokens First
The foundation of every design system is a token layer — named values that everything else references. Common starter set:
- Color: primitive scales (gray-100 to gray-900, brand-50 to brand-900) and semantic aliases (--bg-surface, --text-primary, --border-default).
- Type: a scale (xs, sm, base, lg, xl, 2xl...) plus line-height and weight tokens.
- Spacing: a step scale (4, 8, 12, 16, 24, 32, 48, 64) used for padding, margin, gap.
- Radius: typically 4-6 values (none, sm, md, lg, full).
- Shadow: 3-5 elevation steps.
- Motion: durations and easing curves.
Component Patterns That Work
- Define variants explicitly — primary, secondary, ghost, danger — not ad hoc styling.
- Standardise sizes — sm, md, lg — consistent across the component set.
- Specify states — default, hover, focus, active, disabled, loading — every component, every variant.
- Accessibility is non-optional — focus rings, ARIA, keyboard, contrast must all be solved at the component level.
- Document props and examples in code — Storybook or equivalent. A Figma file alone is insufficient.
Avoid Common Mistakes
- Launching the system before consumers adopt it. Build with one team's real needs, then expand.
- Token names that encode the value (--color-blue-500). Encode meaning (--color-brand-500).
- No governance — anyone can add components, no one removes anything. The library balloons and trust collapses.
- Skipping documentation. Undocumented systems are abandoned systems.
Rolling It Out Without Losing Trust
A design system succeeds on adoption, not on how complete the library looks. A pragmatic rollout:
- Start from real usage. Build the handful of components one product team actually needs today, ship them in a real feature, then generalise — don't speculatively design 60 components nobody asked for.
- Version and changelog everything. Consumers need to know what changed and whether it breaks them; semver plus release notes keeps trust intact.
- Appoint owners. Someone must be able to say no, deprecate duplicates, and keep the surface area small. Ungoverned libraries balloon and collapse.
- Document in code, not just Figma. A live component playground with props and examples is what makes engineers reach for the system instead of rebuilding.
- Measure adoption — track which teams use the tokens and components, and treat low uptake as a signal to fix the system, not to mandate it.
Try It Yourself
Build a token palette with DesignKit's color and gradient tools.
Color Palette Extractor →