How to Build a Design System from Scratch: Tokens, Components, and Documentation

Most articles about how to build a design system are written by teams with a dedicated design ops function, three designers and a six month runway. That is not the reality for the majority of product teams. If you are two or three developers and one designer shipping a web app, you still need consistency, but you need it without turning the design system into a second product.

This guide is the playbook we use at coding4.net when we help small teams build a design system from scratch. It goes from the first audit all the way to tokens, React components, Storybook documentation, naming conventions and versioning rules. Everything here is designed to be shipped incrementally, in production, by people who also have features to deliver.

What a design system actually is (and what it is not)

A design system is the single source of truth for how your product looks, behaves and is built. In practice it has four layers:

  • Foundations / design tokens: the raw decisions (color, spacing, typography, radius, elevation, motion) stored as data.
  • Components: reusable, accessible UI pieces that consume those tokens.
  • Documentation: how and when to use each component, with live examples.
  • Governance: naming conventions, contribution rules, versioning and deprecation policy.

A design system is not a Figma file full of screens. It is not a component library alone either. The library is the code artifact, the system is the library plus the rules that keep it coherent over time.

Why small teams benefit the most

Large organizations build design systems to align many squads. Small teams build them for a different reason: to stop re-deciding the same things. Every time a developer picks a padding value or a shade of blue by hand, that is a micro decision that costs time and creates drift. Tokens and components remove those decisions from daily work.

design system components

How to build a design system: the 7 step process

  1. Run an interface inventory of what you already ship
  2. Define your design tokens (color, spacing, typography first)
  3. Set naming conventions before writing any code
  4. Build a token pipeline from source of truth to CSS variables
  5. Build the first 10 React components, not 50
  6. Document everything in Storybook
  7. Add versioning, release and deprecation rules

Each step below is actionable in days, not months. A realistic first release for a small team is four to six weeks part time. Design Systems 101 tackles the same question from another angle.

Step 1: Run an interface inventory

Before you design anything new, screenshot every screen of your current web app and group what you find. You are looking for duplication, not beauty.

Create a simple spreadsheet with one row per element type:

Element Variants found Should exist Priority
Buttons 14 (5 blues, 4 heights) 4 High
Text inputs 7 2 High
Grey values 23 10 High
Modals 3 1 Medium

This inventory is your business case and your backlog at the same time. It also tells you which components are used on 80% of screens, and those are the only ones you build first.

design system components

Step 2: Define your design tokens

Design tokens are named design decisions stored as data, so they can be consumed by code, Figma and documentation from one source. This is the part people skip, and it is the part that makes a design system scale.

Use three token tiers

The three tier model is what keeps a system flexible without chaos:

Tier Purpose Example Used directly in components?
1. Primitive Raw palette, no meaning blue.600 = #2563EB No
2. Semantic Meaning and intent color.action.primary.bg = blue.600 Yes, most of the time
3. Component Scoped to one component button.primary.bg.hover Only when needed

Rule for small teams: never reference a primitive token inside a component. If you ever rebrand or add a dark theme, only the semantic layer changes and nothing else breaks.

Color tokens

Start with far fewer colors than you think. A workable starting set:

  • One brand ramp (9 to 11 steps, 50 to 950)
  • One neutral ramp (used for text, borders, surfaces)
  • Four status ramps: success, warning, danger, info

Then map semantics on top:

  • color.bg.page, color.bg.surface, color.bg.subtle
  • color.text.primary, color.text.secondary, color.text.inverse, color.text.disabled
  • color.border.default, color.border.strong, color.border.focus
  • color.action.primary.bg, color.action.primary.bg.hover, color.action.danger.bg

Check contrast as you define them, not after. Every text on background pair should hit at least 4.5:1 for body text and 3:1 for large text and non text UI such as borders and icons.

Spacing tokens

Use a single base unit of 4px with a non linear scale. This kills the “is it 13 or 14 pixels” debate forever.

Token Value Typical use
space.100 4px Icon to label gap
space.200 8px Inside small controls
space.300 12px Input padding
space.400 16px Default gap, card padding
space.600 24px Between form groups
space.800 32px Section spacing
space.1200 48px Page sections

Numeric names (100, 200, 400) are better than t-shirt sizes (sm, md, lg) because you can insert a value between two steps later without renaming everything.

Typography tokens

Define a type scale with a ratio between 1.2 and 1.25, then expose composite tokens rather than loose font sizes:

  • text.display, text.heading.lg, text.heading.md, text.heading.sm
  • text.body.lg, text.body.md, text.body.sm
  • text.label.md, text.code.md

Each composite token bundles font family, size, line height, weight and letter spacing. That way a developer applies one token instead of five properties, and headings stay consistent across the app.

Step 3: Agree on naming conventions first

Naming is where small design systems rot. Lock a formula before the first commit:

category.concept.property.variant.state

Examples:

  • color.action.primary.bg.hover
  • color.feedback.danger.text
  • space.inset.400
  • radius.control.md

Four practical rules:

  1. Describe purpose, not appearance. color.action.primary.bg survives a rebrand, color.blue.button does not.
  2. Stay consistent on abbreviations. Pick bg or background and never mix.
  3. Order from general to specific. It makes autocomplete usable and files sortable.
  4. Components use PascalCase, props use camelCase, tokens use kebab or dot case. Document it once in the README.

Write these rules in a CONTRIBUTING.md file on day one. It is the cheapest piece of governance you will ever create.

design system components

Step 4: Build the token pipeline

Your tokens should live in one place and be generated everywhere else. The common setup today:

  • Source of truth: JSON files in the DTCG format (the W3C Design Tokens Community Group format with $value and $type), stored in your repo. Figma Variables can sync in and out of it.
  • Transformer: Style Dictionary to generate CSS custom properties, TypeScript constants, Tailwind theme config, iOS or Android output if ever needed.
  • Consumers: your React app, your marketing site, your emails.

A token file looks like this:

{
  "color": {
    "blue": {
      "600": { "$type": "color", "$value": "#2563EB" }
    },
    "action": {
      "primary": {
        "bg": { "$type": "color", "$value": "{color.blue.600}" }
      }
    }
  }
}

And the generated CSS output:

:root {
  --color-blue-600: #2563EB;
  --color-action-primary-bg: var(--color-blue-600);
  --space-400: 1rem;
}

Theming becomes trivial: a [data-theme="dark"] block redefines only the semantic layer. Components never change. Anyone digging further should read The Design System Guide.

Tailwind or plain CSS?

Both work. If you use Tailwind, feed your tokens into the theme configuration so utility classes and component styles share the same values. If you use CSS Modules or vanilla-extract, consume the CSS variables directly. What matters is that no hardcoded hex value or pixel value ever appears in a component file. Enforce it with a lint rule.

Step 5: Build the first components in React

Resist the urge to build a full library. Ship these ten first, because they cover the overwhelming majority of screens in a typical web app:

  1. Button
  2. Input (plus Label, HelpText, ErrorText)
  3. Select
  4. Checkbox and Radio
  5. Card / Surface
  6. Stack and Grid layout primitives
  7. Text / Heading typography components
  8. Badge / Tag
  9. Modal / Dialog
  10. Toast / Alert

Component API rules that save you later

  • Variants over booleans. Use variant="primary" | "secondary" | "ghost" | "danger" instead of isPrimary, isGhost. Booleans multiply into invalid combinations.
  • Forward refs and spread the rest. Every component should accept native props and a ref, otherwise consumers will fork it.
  • No business logic inside. A Button does not know about your checkout flow.
  • Escape hatches, carefully. Allow className but do not allow arbitrary style objects as the default pattern.
  • Accessibility is part of the component, not the consumer. Use an unstyled primitive library for the hard pieces (dialogs, popovers, menus, comboboxes) and style them with your tokens.

A minimal Button:

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  function Button({ variant = "primary", size = "md", ...rest }, ref) {
    return (
      <button
        ref={ref}
        data-variant={variant}
        data-size={size}
        className={styles.button}
        {...rest}
      />
    );
  }
);
.button[data-variant="primary"] {
  background: var(--color-action-primary-bg);
  color: var(--color-text-inverse);
  padding: var(--space-200) var(--space-400);
  border-radius: var(--radius-control-md);
}

Monorepo or in-app folder?

For a team of under six people, start with a folder inside the app repository, for example src/ui. Extract it to a separate package only when a second product or marketing site needs it. Premature package extraction adds release overhead before you get any benefit from it.

Step 6: Document everything in Storybook

Storybook is where the design system becomes usable by people who did not build it. Install it in the same repo and write stories as you build, not afterwards.

What each component page must contain

  • Default story: the canonical usage
  • All variants and sizes in a single view for visual comparison
  • States: hover, focus, disabled, loading, error
  • Props table auto generated from TypeScript types
  • Do and Do not guidance: two or three short bullets, this is what prevents misuse
  • Accessibility notes: keyboard behavior, required labels

A CSF story stays short:

export default { title: "Actions/Button", component: Button };

export const Primary = { args: { children: "Save changes" } };
export const Danger = { args: { variant: "danger", children: "Delete" } };

Three Storybook add-ons worth the setup time

  1. Accessibility add-on: runs automated axe checks on every story.
  2. Interaction testing: turns stories into tests, so your docs and your test suite are the same artifact.
  3. Visual regression (Chromatic or an open source alternative): catches the unintended 2px shift that no code review spots.

Also publish a Foundations section in Storybook that renders your tokens straight from the generated files: color swatches with values, the spacing scale, the type scale. When a token changes, the docs update themselves.

design system components

Step 7: Versioning, releases and deprecation

This is what separates a design system from a folder of components. Even a one package system needs rules.

Semantic versioning applied to UI

Change Version bump Example
Bug fix, no API or visual impact Patch (1.4.2) Fix focus ring clipping
New component, new optional prop, new token Minor (1.5.0) Add Tooltip, add size=”xs”
Removed or renamed prop, removed token, changed default Major (2.0.0) Rename isPrimary to variant
Significant visual change to an existing component Major New default border radius everywhere

That last row surprises people. In a design system, a visual change is a breaking change because it can break layouts and brand consistency downstream. Treat it as such.

A lightweight release workflow

  1. Every PR that touches the system includes a changeset describing the bump type and a human readable summary.
  2. CI runs lint, type check, unit tests, accessibility checks and visual regression.
  3. Merging to main publishes the package and updates the changelog automatically.
  4. Storybook deploys to a static URL on every merge so the docs are never stale.

Deprecation policy

Write it once, in three lines: Deprecated props and components stay available for at least two minor releases. They log a console warning in development with the recommended replacement. Removal only happens in a major release, with a codemod or a migration note in the changelog.

Governance without a design ops person

You do not need a dedicated role, you need three agreements:

  • One owner per release cycle. Rotate it monthly. That person reviews system PRs and keeps the backlog.
  • A contribution path. Anyone can open a proposal issue with a screenshot and the use case. If the pattern appears in three or more places, it becomes a component. Fewer than three, it stays local to the feature.
  • A 30 minute monthly review. Look at new local components created in feature code, decide what gets promoted into the system and what gets deleted.

Adoption metrics that matter

  • Percentage of UI code importing from the system versus local components
  • Number of hardcoded hex and px values remaining (a lint rule can count them)
  • Number of distinct button implementations in the codebase, target is one
  • Accessibility violations in CI, target is zero
design system components

A realistic timeline for a small team

Phase Duration Output
Audit and alignment 3 to 5 days Inventory spreadsheet, priority list
Tokens and naming 1 week Token JSON, CSS variables, CONTRIBUTING.md
First 10 components 2 to 3 weeks Typed, accessible, token driven components
Storybook and CI 1 week Published docs, visual regression, a11y checks
Migration of one real screen 1 week Proof it works, list of gaps

Migrate screen by screen, starting with the highest traffic flow. Do not plan a big bang rewrite, it never ships.

Seven mistakes that kill small design systems

  1. Building components before tokens. You will refactor everything twice.
  2. Naming tokens after colors. color.green.button becomes a lie the day the brand changes.
  3. Too many components too early. Ten used components beat fifty unused ones.
  4. Docs written at the end. They never get written.
  5. No versioning rules. Every update becomes a surprise for the feature team.
  6. Design and code drifting apart. If Figma variables and your token file are not synced, the system loses credibility within a quarter.
  7. Treating accessibility as a later phase. Retrofitting keyboard and screen reader support into 30 components costs more than building it in from the start.

FAQ

How do I create a design system?

Audit your existing interface, define design tokens for color, spacing and typography, agree on naming conventions, generate CSS variables from a single token source, build around ten core React components that consume those tokens, document them in Storybook, then add semantic versioning and a deprecation policy. Start small and migrate one screen at a time.

How long does it take to build a design system?

A usable first version for a small team takes roughly four to six weeks of part time work. A mature system with full coverage, theming and visual regression testing is an ongoing product, not a project with an end date.

What is the 60-30-10 rule in design?

It is a color balance guideline borrowed from interior design: around 60% of the interface uses a dominant neutral, 30% a secondary color, and 10% an accent used for actions and emphasis. In a design system it translates into mostly neutral surfaces and text, a secondary tone for structure, and a brand color reserved for primary actions so those actions stay visible.

What are the pillars of a design system?

Four pillars: foundations (tokens and principles), components (the coded library), documentation (usage guidance and live examples), and governance (naming, contribution, versioning and deprecation rules). Skip governance and the system degrades within months.

Should I build a design system in Figma or in code?

Both, with one source of truth for tokens. Figma Variables and your token files should sync so designers and developers reference the same values. The code library is what ships to users, so it is the authority for component behavior, while Figma is the authority for exploration and intent.

Do I need Storybook to build a design system?

No, but you need somewhere to render components in isolation with their variants and states. Storybook is the most common choice because it gives you props tables, accessibility checks, interaction tests and a publishable static site with little configuration.

When is a design system not worth it?

If you have a single short lived landing page, a well configured utility CSS setup is enough. The moment you have more than one developer touching the UI, more than about 15 screens, or plans for a second product surface, tokens and a shared component layer pay for themselves quickly.

Next steps

Knowing how to build a design system is mostly about sequencing: tokens before components, components before documentation, documentation before expansion, and governance from day one. Start this week with the interface audit and the token file. Those two artifacts alone will change how your team ships UI.

If you want a second pair of eyes on your token architecture, component API or Storybook setup, the team at coding4.net works with small product teams on exactly this kind of groundwork. Related reading: Design Systems: A Beginner’s Guide.

Leave a Comment

Your email address will not be published. Required fields are marked *