Design systems guide: what to build, when, and what to leave out
Most design systems fail for the same two reasons: they were started too early, or they were built as a library instead of a set of decisions. This is the order I build them in, on real products, with small teams.
What a design system is
A design system is the set of decisions a product has already made, written down in a form that is easier to reuse than to re-argue.
A component library is one output of that. So is a token file, a documentation site, and a page of writing rules. If you have components but no decisions behind them, you have a folder of parts and the arguments still happen on every ticket.
- Foundations: color, type scale, spacing, radius, elevation, motion, iconography.
- Components: the parts, with their states and their rules of use.
- Patterns: how parts combine for recurring jobs, such as an object page, a table view, an empty state, a destructive confirmation.
- Language: naming, tone, and the words the product uses for its own objects.
- Governance: who decides, how a change lands, and how deprecation works.
When to start one
Starting on day one produces a system built on guesses. Starting after fifty screens produces a migration project. The signal to watch for is repetition, not size.
| Stage | What to have | What to skip |
|---|---|---|
| Prototype, first weeks | Type scale, spacing scale, one color set, buttons and inputs | Documentation site, versioning, contribution process |
| First real product, three or more screens | Tokens in code, a small component set, one documented pattern | Theming, multi-brand support, exhaustive variants |
| Multiple people shipping | Usage rules, review path, a place changes are announced | A dedicated systems team you cannot staff |
| Multiple products or brands | Layered tokens, published package, deprecation policy | Nothing, this is when the full apparatus earns its keep |
Tokens, done simply
Tokens are named decisions. The mistake is naming them after what they look like, which locks the system to one appearance and makes dark mode, theming and rebrands painful.
- Name by role, not by value. Use surface, foreground, muted, border, accent, danger, rather than gray-900 or brand-blue.
- Two layers is usually enough: a small palette of raw values, and a set of semantic tokens that point at them.
- Keep the type and spacing scales short. Six sizes and eight spacing steps beat twenty of each, because a short scale forces hierarchy decisions.
- Put tokens where the code reads them, so there is one source of truth rather than a design file and a stylesheet that drift apart.
- Include motion. Two or three durations and one or two easing curves make an entire product feel deliberate.
If a designer and an engineer describe the same color with different names, the system has already started to fail.
Building components that get used
- 01
Start from real screens
Extract components out of shipped work rather than inventing a library in isolation. Anything you cannot point at in a real screen does not belong yet.
- 02
Design every state before you ship one
Default, hover, focus, active, disabled, loading, error, empty, and the version with far too much text in it.
- 03
Prefer composition over configuration
A component with eleven boolean props is a design decision nobody made. Break it into smaller parts that combine.
- 04
Write the rule, not just the part
One or two lines: what this is for, when to use something else. That sentence prevents most misuse.
- 05
Give it an escape hatch
Systems that forbid deviation get bypassed entirely. Allow a documented way to go off-system, and watch what people build there. That is your roadmap.
Systems worth studying
Read these for their decisions and their writing, not to copy their components into a product with a different job.
Atlassian Design System
The clearest example of usage guidance written for large teams, and of documentation that explains when not to use a component.
Polaris by Shopify
Strong on content and language rules, which most systems ignore entirely.
Material Design
Useful as a reference for tokens, theming and accessibility rigor. Adopt the structure, not the aesthetic, unless you want to look like everyone else.
Apple Human Interface Guidelines
The best writing on platform conventions and why breaking them costs you.
shadcn/ui
A different model entirely: components you own and edit rather than a dependency you upgrade. Well suited to small teams building a distinctive product.
Why design systems get abandoned
- Built as a side project with no owner, so it stops matching the product within two releases.
- Documented in a place nobody works, instead of in the code and the design file people open daily.
- Too rigid, so shipping teams route around it and the system becomes a museum.
- Too generic, so the product loses whatever made it recognizable and the marketing site and app stop matching.
- Started as a rewrite rather than absorbed gradually, so it needs a quarter nobody has.