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.

How to build a design system: the 7 step process
- Run an interface inventory of what you already ship
- Define your design tokens (color, spacing, typography first)
- Set naming conventions before writing any code
- Build a token pipeline from source of truth to CSS variables
- Build the first 10 React components, not 50
- Document everything in Storybook
- 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.

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.subtlecolor.text.primary,color.text.secondary,color.text.inverse,color.text.disabledcolor.border.default,color.border.strong,color.border.focuscolor.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.smtext.body.lg,text.body.md,text.body.smtext.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.hovercolor.feedback.danger.textspace.inset.400radius.control.md
Four practical rules:
- Describe purpose, not appearance.
color.action.primary.bgsurvives a rebrand,color.blue.buttondoes not. - Stay consistent on abbreviations. Pick
bgorbackgroundand never mix. - Order from general to specific. It makes autocomplete usable and files sortable.
- 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.

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
$valueand$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:
- Button
- Input (plus Label, HelpText, ErrorText)
- Select
- Checkbox and Radio
- Card / Surface
- Stack and Grid layout primitives
- Text / Heading typography components
- Badge / Tag
- Modal / Dialog
- Toast / Alert
Component API rules that save you later
- Variants over booleans. Use
variant="primary" | "secondary" | "ghost" | "danger"instead ofisPrimary,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
classNamebut do not allow arbitrarystyleobjects 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
- Accessibility add-on: runs automated axe checks on every story.
- Interaction testing: turns stories into tests, so your docs and your test suite are the same artifact.
- 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.

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
- Every PR that touches the system includes a changeset describing the bump type and a human readable summary.
- CI runs lint, type check, unit tests, accessibility checks and visual regression.
- Merging to main publishes the package and updates the changelog automatically.
- 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

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
- Building components before tokens. You will refactor everything twice.
- Naming tokens after colors.
color.green.buttonbecomes a lie the day the brand changes. - Too many components too early. Ten used components beat fifty unused ones.
- Docs written at the end. They never get written.
- No versioning rules. Every update becomes a surprise for the feature team.
- Design and code drifting apart. If Figma variables and your token file are not synced, the system loses credibility within a quarter.
- 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.

