How to Build a Design System for a Small Development Team: Tokens, Components and Documentation

Why a Design System for a Small Team Looks Nothing Like Atlassian’s

Search for design system inspiration and you land on Material, Carbon, Polaris or Atlassian. Those systems are maintained by teams of 10 to 40 people with dedicated design ops, accessibility specialists and release managers. If you are four people shipping a product, copying that model is the fastest way to abandon the project by month two.

A design system for a small team is a different animal. It is a short set of shared decisions, encoded in code, that stops your team from re-answering the same question every sprint: what blue is this, how much padding, which button, what does the error state look like?

This walkthrough is written for a realistic setup: one designer, three developers, no design ops, no budget for new tooling, and a product that already exists and is messy. The target is a working system in about six weeks of part-time effort, not a quarter-long initiative.

What You Are Actually Building (Scope Check)

Before any code, agree on the boundaries. A small team system has exactly three layers:

  1. Design tokens: color, spacing, typography, radius, shadow, motion, defined once as CSS custom properties.
  2. A component library: roughly 10 to 15 components that cover 80% of your interface.
  3. Documentation: usage rules that live next to the code, not in a separate portal.

Everything else is optional. Here is the honest split between what pays off immediately and what is enterprise overhead for a four-person team:

Do this now Skip until you are 15+ people
CSS variables for tokens Multi-platform token pipeline (Style Dictionary, JSON to iOS/Android)
10 components in your existing repo A separately versioned npm package
README per component + a demo page A standalone documentation website with search
One Figma file with linked styles Figma to code automation and token sync plugins
A 30 minute monthly review A contribution RFC process and governance council
Manual accessibility checks on focus and contrast Full automated visual regression on every PR
design system components

Step 0: The Two Hour UI Inventory

You cannot standardize what you have not counted. Block two hours, screenshot every screen in your product, and paste them into one document. Then count:

  • How many distinct button styles exist? (Most teams find 6 to 12.)
  • How many grey values are in use? Run a quick grep for hex codes in your stylesheets.
  • How many font sizes appear? Anything above 8 is noise.
  • How many spacing values? If you see 13px, 17px and 22px, those are accidents.

This inventory is your business case and your backlog at the same time. A team that discovers 34 unique hex colors stops arguing about whether a design system is worth it.

Useful grep commands:

grep -rhoE "#[0-9a-fA-F]{3,8}" src/ | sort | uniq -c | sort -rn
grep -rhoE "[0-9]+px" src/ | sort | uniq -c | sort -rn

Step 1: Define Design Tokens in CSS Variables

Tokens are the smallest unit of your system: named values that replace hardcoded numbers. For a small team, plain CSS custom properties are the right choice. They work in every browser you support, need no build step, can be overridden per theme, and are readable by both designers and developers.

Use two tiers, not three

Large systems use primitive, semantic and component tokens. With four people, two tiers are enough:

  • Tier 1, primitives: the raw palette and scales. --blue-500, --space-4.
  • Tier 2, semantic: what the value means in context. --color-action, --color-danger, --surface-raised.

Components reference tier 2 only. That single rule is what lets you ship a dark theme later without touching a component file.

A starter token file

:root {
  /* ---- Tier 1: primitives ---- */
  --blue-100: #e8f0fe;
  --blue-500: #2f6feb;
  --blue-700: #1b4bb5;
  --grey-0:   #ffffff;
  --grey-50:  #f7f8fa;
  --grey-200: #e2e5ea;
  --grey-500: #6b7280;
  --grey-900: #14161a;
  --red-500:  #d92d20;
  --green-500:#0f9d58;
  --amber-500:#f0a202;

  /* spacing: a 4px base scale, 7 steps is plenty */
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-5: 24px;
  --space-6: 32px;
  --space-7: 48px;

  /* type: 6 sizes maximum */
  --font-sans: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
  --text-xs: 0.75rem;
  --text-sm: 0.875rem;
  --text-md: 1rem;
  --text-lg: 1.25rem;
  --text-xl: 1.5rem;
  --text-2xl: 2rem;
  --leading-tight: 1.25;
  --leading-normal: 1.5;
  --weight-regular: 400;
  --weight-medium: 500;
  --weight-bold: 700;

  /* radius, border, shadow, motion */
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-full: 999px;
  --border-width: 1px;
  --shadow-1: 0 1px 2px rgba(20, 22, 26, 0.08);
  --shadow-2: 0 4px 12px rgba(20, 22, 26, 0.12);
  --duration-fast: 120ms;
  --duration-base: 200ms;
  --ease-standard: cubic-bezier(0.2, 0, 0, 1);

  /* ---- Tier 2: semantic ---- */
  --color-text:          var(--grey-900);
  --color-text-muted:    var(--grey-500);
  --color-text-inverse:  var(--grey-0);
  --color-surface:       var(--grey-0);
  --color-surface-sunken:var(--grey-50);
  --color-border:        var(--grey-200);
  --color-action:        var(--blue-500);
  --color-action-hover:  var(--blue-700);
  --color-action-subtle: var(--blue-100);
  --color-danger:        var(--red-500);
  --color-success:       var(--green-500);
  --color-warning:       var(--amber-500);
  --color-focus-ring:    var(--blue-500);
}

[data-theme="dark"] {
  --color-text:           var(--grey-0);
  --color-text-muted:     #a1a7b3;
  --color-surface:        #16181d;
  --color-surface-sunken: #0f1115;
  --color-border:         #2a2e36;
}

Naming rules that prevent arguments

  • Primitives are named after what they are. Semantic tokens are named after what they do. Never name a token --color-login-button.
  • Use numeric scales with gaps of 100 for color so you can insert values later.
  • One scale for spacing, used for padding, margin and gap alike. Do not create separate margin tokens.
  • If a value is used once, it does not need a token yet.

Enforce them cheaply

Tokens that are optional get ignored. Add a lint rule rather than a policy document. With Stylelint, declaration-property-value-disallowed-list can block raw hex values in component files. In Tailwind projects, map your theme directly to the CSS variables so utility classes and tokens cannot drift apart.

design system components

Step 2: The First 10 Components to Standardize

Component selection is where small teams waste the most time. The right criterion is not “what is interesting to build” but frequency times inconsistency. Build the thing that appears on 20 screens in 7 different flavors.

Here is a battle-tested first ten for a typical web product, in build order:

# Component Why it comes first States to cover Effort
1 Button Highest count, worst drift default, hover, active, focus, disabled, loading M
2 Text input Every form depends on it default, focus, error, disabled, read-only M
3 Form field wrapper Label, hint, error message, ids and aria wiring in one place with hint, with error, required S
4 Select / dropdown Usually the most broken control in the app closed, open, keyboard nav, error L
5 Checkbox and radio Cheap win, instantly visible consistency unchecked, checked, indeterminate, disabled S
6 Card / surface Locks down padding, radius and shadow decisions flat, raised, interactive S
7 Modal / dialog Focus trap and escape handling should be solved once open, scrollable body, confirm variant L
8 Toast / inline alert Standardizes success, error and warning language info, success, warning, danger, dismissible S
9 Table / data list B2B products live here; include empty and loading states default, sorted, empty, loading, row actions L
10 Badge / status tag Forces you to define your status color semantics neutral, success, warning, danger, info S

Two silent extras worth adding immediately because they remove layout guesswork: a Stack (vertical spacing using the space scale) and an Icon wrapper that normalizes sizing and aria-hidden.

Components to deliberately postpone

  • Date picker, rich text editor, combobox with async search, charts. Use a well-maintained library and just skin it with your tokens.
  • Navigation shells. They are usually used once, so a token-compliant page component is enough.
  • Anything that currently exists in only one place.

Build on a headless base, do not write a11y from scratch

Accessible dialogs, menus and listboxes are a full-time job. In 2026, a four-person team should wrap an unstyled primitive library (Radix, React Aria, Ark UI, Headless UI, or Melt for Svelte) and apply tokens on top. You keep full visual control and inherit keyboard and screen reader behavior. That decision alone saves weeks.

One component API pattern for all ten

Consistency in the API matters as much as consistency in pixels. Agree on these five rules and write them down:

  1. Visual variations use a variant prop, never a boolean per style.
  2. Sizes use size with the same values everywhere: sm, md, lg.
  3. Every component forwards className and remaining props to the root element.
  4. No business logic inside a component. No API calls, no routing assumptions.
  5. Spacing between components is the parent’s job, never a margin baked into the child.

Step 3: Documentation That Lives Next to the Code

Documentation in Notion or Confluence dies within a quarter, because it is updated by a different action than the one that changes the code. The fix is proximity: docs sit in the same folder as the component and change in the same pull request.

The folder structure

src/ui/
  tokens.css
  button/
    Button.tsx
    Button.css
    Button.stories.tsx
    README.md
  input/
    ...
  docs/
    getting-started.md
    contributing.md

A component README template you can copy

# Button

Triggers an action. Not for navigation, use Link for that.

## When to use
- Submitting a form
- Confirming a destructive action (variant="danger")

## When not to use
- Navigating to another page -> use Link
- More than one primary button per view

## Props
| Prop     | Type                                   | Default   |
|----------|----------------------------------------|-----------|
| variant  | primary | secondary | ghost | danger  | primary   |
| size     | sm | md | lg                           | md        |
| loading  | boolean                                | false     |

## Accessibility
- Always provide a text label; icon-only buttons need aria-label
- Focus ring uses --color-focus-ring, never remove outlines

## Do / Don't
- Do: "Save changes"
- Don't: "Click here", "OK" for destructive actions

That is 25 lines. It takes ten minutes to write and it answers the three questions developers actually ask: should I use this, what props exist, what will break accessibility.

The one piece of tooling worth adding

Install Storybook (or a single in-app /kitchen-sink route if Storybook feels heavy). You need one URL where anyone can see all states of all components side by side. That page is your review tool, your QA checklist and your designer handoff, all at once. If a state is not in the kitchen sink, it is not supported.

Keep the docs honest with three habits

  • Add a PR checklist item: “Component README and stories updated”.
  • Write usage rules as Do / Don’t pairs with examples, not as paragraphs of theory.
  • Date-stamp decisions. A short decisions.md with one line per choice (“2026-10-14: radius-md is 8px everywhere, no exceptions for cards”) prevents the same debate in March.
design system components

The Figma Side, Kept Minimal

With one designer, do not build a mirror-image component library in Figma with every variant. Build this instead:

  1. Variables for colors, spacing and radius using the exact same names as your CSS tokens. Same names is the whole trick.
  2. Text styles matching your six font sizes.
  3. Components for the ten items above with variants for the states that designers actually place, not every permutation.

When names match on both sides, a design review becomes “this uses color-action and space-4” rather than “this blue looks slightly different”. Automated Figma to code token sync is a nice-to-have, not a requirement at this size.

A Realistic Six Week Plan

Week Focus Deliverable Time cost
1 UI inventory and token draft tokens.css merged, Figma variables created ~6 h total
2 Button, Form field, Input 3 components + stories + READMEs ~10 h
3 Checkbox, Radio, Badge, Card, Stack 5 small components ~8 h
4 Modal, Toast (on headless base) Focus trap and a11y verified ~10 h
5 Select, Table Empty and loading states included ~12 h
6 Migrate two real screens + lint rules Proof it works, stylelint blocks raw hex ~10 h

Migration rule: do not stop feature work to refactor the whole app. Adopt the boy scout approach: any screen you touch for a feature gets migrated to system components in the same PR. Most products reach 80% coverage in three to four months this way, with zero dedicated refactor sprints.

design system components

Governance When Nobody Owns Design Ops

You still need rules, just very few of them:

  • One named owner, rotating quarterly. Not a committee. Their job is to say no and to merge.
  • The rule of three: a pattern becomes a component only after it appears in three places. Before that, it stays local.
  • Escape hatch allowed: developers can write custom CSS, but only using tokens. Pure freedom causes drift, pure rigidity causes workarounds.
  • 30 minutes a month: review the kitchen sink page together, kill unused variants, log new decisions. That meeting is the entire governance process.
  • Semantic-ish versioning: if the system lives in the app repo, you do not need releases. If it is a package, bump minor for additions and major for renamed props, and keep a one line changelog.

How to Tell It Is Working

Avoid vanity metrics like “number of components”. Track three things, informally:

  1. Hardcoded value count: rerun the grep from Step 0 every month. The line should go down.
  2. Time to build a standard screen: ask the team to estimate before and after. A settings page going from two days to half a day is the real ROI.
  3. Design review comments about spacing and color: if they disappear, the system is doing its job.
design system components

Five Mistakes Small Teams Make

  • Starting with a brand refresh. Encode what you have today. Redesigning and systematizing at once doubles the risk and halves the chance of finishing.
  • Building components nobody asked for. If it is not in the inventory three times, it is a hobby project.
  • Publishing an npm package on day one. Versioning overhead with no consumers. Keep it in the app repo until a second product exists.
  • Documenting in a separate tool. Distance equals decay. Docs in the repo, in the same PR.
  • Treating it as a project with an end date. It is a product with a small, permanent maintenance cost. Budget roughly half a day per month after launch.

FAQ

How small is too small for a design system?

Two developers and one product is already enough to benefit from a token file and five components. Below that, a single tokens.css plus a one page style guide is the correct amount of system. The cost of tokens is almost zero, so there is no team too small for that layer.

Should a small team use an existing design system instead of building one?

Often yes. Adopting an open system (such as a headless primitive library skinned with your own tokens, or a complete kit like Material or Radix Themes) is faster and perfectly legitimate. Build custom components only where your product has a genuinely distinct interaction or brand requirement. The hybrid approach, open components plus your own tokens, is the default recommendation for teams under ten people.

How long does it take to build a design system for a small team?

Roughly six weeks of part-time work for tokens, ten components and basic docs, as shown in the plan above. Full migration of an existing product takes longer and should happen gradually alongside feature work rather than in a dedicated refactor phase.

CSS variables or a token tool like Style Dictionary?

CSS variables, unless you ship to iOS and Android natively as well. A token pipeline adds build configuration, a source of truth file format and a sync process. That is justified when three or more platforms consume the same values, not for a single web app.

Who should own the design system when there is no design ops role?

One person, usually the designer or the most senior frontend developer, with a rotating ownership every quarter so knowledge does not sit in a single head. Their responsibility is reviewing additions and keeping the kitchen sink page accurate, around two to four hours per month.

Do we need Storybook?

You need a single page showing every component in every state. Storybook is the easiest way to get it, but an in-app route rendering all components works just as well and costs nothing to maintain. Pick whichever your team will actually open.

What about accessibility without a specialist?

Cover the basics inside the components so individual screens cannot get them wrong: visible focus rings, 4.5:1 text contrast, labels tied to inputs, keyboard operability for modals and menus, and aria-live for toasts. Building on a headless primitive library handles most of the hard parts. Add an automated axe check in CI once the first ten components are stable.

Key Takeaway

A design system for a small team succeeds through restraint. Two tiers of tokens in CSS variables, ten components chosen by frequency, documentation that cannot drift because it lives beside the code, and a 30 minute monthly review. Skip the package publishing, the token pipeline, the documentation site and the governance council until the team size actually demands them. Ship the small version in six weeks, and let it grow only when real usage pushes it.