Frontend

Building Design Systems from Scratch: A Frontend Engineer's Guide

10 min read By Suraj Kumar Gorai

A design system is the single highest-leverage investment a frontend team can make. After building design systems for three enterprise applications — from initial component audit to published npm package — here's the practical guide to building one that teams actually use.

What a Design System Actually Is

A design system is not just a component library. It's three things:

  • Design tokens: The atomic values — colors, spacing, typography, shadows, border radii, breakpoints — that define your visual language.
  • Component library: Reusable UI components built with those tokens, from primitives (Button, Input) to composites (DataTable, Modal).
  • Documentation: Usage guidelines, accessibility requirements, do/don't examples, and live playground. Without documentation, components aren't discoverable and won't be adopted.

Phase 1: Audit Existing UI

Before building anything, audit your current applications:

  • Screenshot every unique UI pattern across all pages
  • Inventory all button variants, form styles, card layouts, and modal designs
  • Count how many shades of blue, font sizes, and spacing values exist

In our last audit, we found: 14 different blue shades, 9 font sizes used arbitrarily, and 23 distinct button variants that should have been 5. This audit builds the case for investment and defines the scope.

Phase 2: Define Design Tokens

Design tokens are the foundation. Start with:

  • Color palette: Brand colors, semantic colors (success, warning, error, info), neutrals (8-10 shades from near-white to near-black). Define both light and dark mode values.
  • Typography scale: 5-7 font sizes with corresponding line heights and weights. Use a modular scale (e.g., 1.25 ratio) for mathematical harmony.
  • Spacing scale: 4px base unit with a scale: 4, 8, 12, 16, 24, 32, 48, 64, 96. Every margin, padding, and gap uses this scale.
  • Shadows, radii, transitions: 3-4 shadow levels, 2-3 border radius values, standard transition durations.

Implement tokens as CSS custom properties for web or as a theme object for React Native. This allows theme switching (dark mode) by swapping token values.

Phase 3: Build Primitive Components

Start with 10-15 primitives that cover 80% of UI needs:

  • Button: Primary, secondary, ghost, destructive variants. Sizes: sm, md, lg. States: default, hover, active, disabled, loading.
  • Input: Text, email, password, number types. Error state with message. Helper text. Icons.
  • Typography: Heading (h1-h6), body text, caption, label components with semantic HTML output.
  • Card: Container with header, body, footer slots. Hover and selected states.
  • Modal/Dialog: Accessible overlay with focus trap, keyboard dismiss, and portal rendering.
  • Toast/Notification: Success, error, warning, info variants with auto-dismiss and stacking.

Each primitive must be: fully typed (TypeScript), accessible (ARIA attributes, keyboard navigation), themeable (uses design tokens), and documented (Storybook story with all variants).

Phase 4: Storybook & Documentation

Every component gets a Storybook story showing all variants, states, and sizes. Additionally:

  • Usage guidelines: When to use this component vs. alternatives
  • Do/Don't examples: Common correct and incorrect usage with visual comparisons
  • Playground: Interactive controls to experiment with props
  • Accessibility notes: ARIA roles, keyboard shortcuts, screen reader behavior

We host Storybook as a static site in our CI pipeline. Every PR updates the documentation automatically.

Phase 5: Publishing & Versioning

  • Publish as an internal npm package with semantic versioning
  • Use conventional commits to auto-generate changelogs
  • Breaking changes (removal, API changes) get major version bumps
  • Provide codemods for major version migrations where possible
  • Pin the design system version in consuming apps — updates are intentional, not accidental

Adoption Metrics

Track adoption to prove value:

  • Component coverage: What percentage of UI in each app uses design system components vs. custom one-offs?
  • Design system usage growth: Month-over-month increase in component imports across consuming apps
  • Custom component reduction: Decrease in one-off components as teams adopt the design system
  • Developer satisfaction: Survey developers quarterly on design system usability and completeness

Our design system reached 85% adoption within 6 months, reducing frontend development time by an estimated 25% through component reuse.

Ready to build a design system for your organization? Let's start with an audit of your current UI landscape.