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:
- Design tokens: color, spacing, typography, radius, shadow, motion, defined once as CSS custom properties.
- A component library: roughly 10 to 15 components that cover 80% of your interface.
- 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 |

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.

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:
- Visual variations use a
variantprop, never a boolean per style. - Sizes use
sizewith the same values everywhere:sm,md,lg. - Every component forwards
classNameand remaining props to the root element. - No business logic inside a component. No API calls, no routing assumptions.
- 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.mdwith one line per choice (“2026-10-14: radius-md is 8px everywhere, no exceptions for cards”) prevents the same debate in March.

The Figma Side, Kept Minimal
With one designer, do not build a mirror-image component library in Figma with every variant. Build this instead:
- Variables for colors, spacing and radius using the exact same names as your CSS tokens. Same names is the whole trick.
- Text styles matching your six font sizes.
- 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.

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:
- Hardcoded value count: rerun the grep from Step 0 every month. The line should go down.
- 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.
- Design review comments about spacing and color: if they disappear, the system is doing its job.

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.

