Building a Design System from Scratch

Building a Design System from Scratch

A design system is the shared language a team uses to build interfaces: the tokens, components, and rules that keep a product coherent as it grows. This guide covers how to build one from nothing - the order to do things in, the architecture that survives contact with real teams, and the governance that keeps it alive after launch.

The Short Answer

• Build in this order: tokens first (color, type, spacing), then core components (button, input, card), then patterns (forms, navigation, empty states).
• Start from an audit of the existing product, not a blank page - the system should describe what the product already does, consistently.
• Document when to use each component and when not to; a component library without usage rules is just a parts bin.
• Assign ownership: someone must be able to say no to one-off components, or the system dies by a thousand exceptions.
• Ship a small, complete system over a large, aspirational one. Version 1 with 15 solid components beats version 0 of 80 planned ones.

1. Before You Build: The Audit

Do not start by designing components. Start by inventorying what exists:

1. Screenshot every distinct button, input, card, and heading in the product. You will find 14 button styles where you thought there were 3.
2. List every color, font size, and spacing value in use. The duplicates are your first tokens.
3. Note the inconsistencies - these are the decisions the system will make once, centrally.

The audit usually reveals that 80% of the product already uses 20% of the possible variations. The system's job is to bless that 20% and retire the rest.

2. Phase 1: Design Tokens

Tokens are the atomic decisions: color ramps, type scale, spacing scale, radii, shadows, motion durations. They are named values, stored once, referenced everywhere.

:root {
  /* Color */
  --color-primary-500: oklch(0.62 0.19 250);
  --color-primary-600: oklch(0.55 0.22 250);
  --color-primary-700: oklch(0.48 0.21 250);

  /* Type */
  --font-body: 1rem;
  --font-h2: clamp(1.56rem, 1.3rem + 1.3vw, 1.95rem);
  --leading-normal: 1.6;

  /* Spacing (4px base) */
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-4: 1rem;
  --space-8: 2rem;

  /* Shape */
  --radius-sm: 0.375rem;
  --radius-lg: 0.75rem;
}

Token rules that matter:

• Semantic over literal. --color-primary-600 beats --color-blue-600 when the brand color changes; --color-danger beats --color-red-500 for error states.
• One spacing scale. Base-4 (4px increments) or base-8; pick one and use it for margins, padding, and gaps. Arbitrary values are how rhythm dies.
• Type tokens pair size with leading. A font-size token without its line-height is half a decision (see our typography scale guide).

Tokens are also where color theory becomes production reality: the palette ramps you built become the color tokens.

3. Phase 2: Core Components

Build the components everything else is made of, in roughly this order: button, text input, select/checkbox/radio, badge/tag, card, avatar, tooltip, modal/dialog, tabs, toast/notification.

For each component, define:

• Variants (primary, secondary, ghost, danger for buttons) - and cap them. Every variant doubles the maintenance.
• States - default, hover, focus, active, disabled, loading. Focus states are not optional; they are an accessibility requirement.
• Sizes - small, medium, large at most.
• Anatomy and behavior - what it is made of, what it does on interaction, what happens at the edges (long labels, empty content, errors).
• Usage rules - when to use it and, critically, when not to. "Use a modal for confirmations that block progress; do not use modals for content users might want to reference while deciding."

Build components API-first: decide the props/interface before the visuals. A button with 40 props is a design smell - it means the variants were never decided.

4. Phase 3: Patterns

Patterns are how components combine to solve recurring problems: form layouts with validation, data tables with sorting and empty states, navigation structures, search with results, onboarding flows, error pages.

Patterns are documented as recipes, not just components: the layout, the copy guidance, the edge cases. A form pattern specifies label placement, error message wording and position, required-field marking, and what happens on submit - the things individual components cannot decide alone.

5. Documentation: The System Is the Docs

An undocumented system does not exist for anyone except its authors. Minimum viable documentation per component:

• Live, interactive example
• The variants and states, visible
• Dos and don'ts with visual examples
• Accessibility notes (keyboard behavior, ARIA roles, focus management)
• Code usage snippet

Document decisions, not just outcomes: "we use 4px base spacing because..." lets future contributors extend the system consistently instead of guessing.

6. Governance: Keeping It Alive

Systems die from neglect and from uncontrolled growth. Both need process:

• An owner or small council that reviews additions. Anyone can propose; the council decides.
• A contribution path. Teams that cannot contribute will fork the system silently. Make proposing a new component or variant easy, with clear criteria.
• Deprecation, not deletion. Mark old components deprecated with a migration path and a removal date. Deleting breaks products; deprecating guides them.
• Regular audits. Quarterly, check what is actually used. Components nobody uses get deprecated; one-off styles that spread get systematized.

7. Tooling Choices

• Design: Figma with variables for tokens and component variants. Keep the Figma library and the code in sync - drift between them is the most common system failure.
• Code: Component library in the product's framework (React, Vue, etc.), tokens as CSS custom properties or a token format like Style Dictionary for multi-platform.
• Docs: Storybook is the standard for component documentation with live examples.

You do not need all of this on day one. Tokens in CSS plus a documented component folder beats an elaborate toolchain nobody maintains.

8. Adoption: Rolling the System Out to a Team

A system nobody uses is documentation theater. The rollout matters as much as the components:

Start with one product area. Do not migrate the whole product at once. Pick a contained surface - the settings pages, or a new feature - and build it entirely with the system. This proves the system works, surfaces gaps early, and gives the team a reference implementation.

Migrate opportunistically. When a team touches an old screen for other reasons, they migrate it to the system. Dedicated "migrate everything" sprints stall; opportunistic migration compounds. Track progress visibly (percentage of screens on the system) so the migration does not quietly stop.

Train on the why, not just the what. A workshop walking through the token decisions and component rationales beats a link to the docs site. People follow rules they understand; they route around rules they do not.

Make the system the path of least resistance. Starter templates, code snippets, and Figma libraries should make using the system faster than going custom. If building custom is easier, the system has a distribution problem, not a quality problem.

Measure and report. Track adoption (components used vs one-offs created), and report wins: "settings pages now ship in half the time," "contrast violations down 80%." Systems survive on demonstrated value, not mandates.

Handle the holdouts. Some teams will resist. Usually the cause is a legitimate gap (the system lacks something they need) - treat resistance as a bug report, fill the gap, and convert the critics. Persistent resistance after gaps are filled is a management problem, not a design problem.

Common Mistakes

Frequently Asked Questions

How long does it take to build a design system? A usable v1 (tokens + 12-15 components + docs) takes a small team roughly 6-12 weeks alongside product work. It is never "done" - plan for ongoing maintenance.

Should a startup build a design system? A lightweight one, yes: tokens plus the core components. The full apparatus (governance council, multi-brand theming) can wait. The cost of no system - every screen reinvented - hits earlier than founders expect.

What is the difference between a UI kit and a design system? A UI kit is a set of pre-made components, usually for one design tool. A design system is the tokens, components, rules, documentation, and governance that keep a specific product coherent. You can bootstrap a system from a kit, but the kit alone is not a system. See our UI kit selection guide.

How do design tokens work across design and code? Tokens are defined once in a neutral format (or in Figma variables mirrored in code) and consumed by both. The practical minimum: CSS custom properties in code that match the Figma variable names, kept in sync by whoever changes either.

When should a component be added to the system? When it is used in three places or will be. Before that, it is a one-off. The "rule of three" prevents the system filling with speculative components.

Continue Reading

• Uber Base (Base Web) design system review - a production open-source system worth studying before you build your own
• Ant Design review - the enterprise-scale reference for token theming and component coverage at the other end of the spectrum
• IBM Carbon Design System review - the token-first reference for data-heavy products, with its four built-in themes and 2x grid
• Material Design 3 review - the dynamic-color reference: one source color expanded into tonal palettes in the HCT color space, with tokens shared across Android, Flutter, and the web
• Shopify Polaris review - the platform house-system reference: web components across every Shopify app surface, a deprecated React library, and a license that only fits Shopify-integrating apps
• Color Theory for Web Designers - building the color tokens
• Building a Typography Scale System - the type tokens
• UI Kit Selection: From Beginner to Pro - bootstrapping from a kit