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.
Try It Yourself
Build a token palette with DesignKit's color and gradient tools.
Color Palette Extractor →