The Library Trap
Most teams say they have a design system when what they actually have is a component library. Buttons, inputs, modals — neatly packaged in Figma and mirrored in React. That's useful. It's necessary. But it's not the whole thing.
A design system is the shared language that lets a product team make consistent decisions without asking permission every time. Components are the vocabulary. Tokens, patterns, documentation, and governance are the grammar.
Without the grammar, you get ten slightly different primary buttons and nobody knows which one is correct.
What Actually Belongs in a System
Design tokens are the atomic layer. Color, typography, spacing, elevation, motion duration — defined once, consumed everywhere. When your brand shifts from blue to indigo, you change a token, not four hundred files.
Components are compositions of tokens with defined behavior. A button isn't just a rectangle; it's a contract: sizes, states, loading behavior, icon placement, accessibility requirements.
Patterns are how components combine to solve recurring problems. How does a form handle validation? What does an empty state look like? How do you structure a settings page? Patterns are where consistency either holds or breaks.
Content guidelines are the most overlooked layer. Voice, tone, error message structure, capitalization rules. Two products can share identical components and still feel like different companies because one says "Oops!" and the other says "Error 422: Unprocessable Entity."
Governance is how the system evolves. Who can propose a change? How do you deprecate a component? What's the review process? A system without governance becomes a graveyard of half-maintained experiments.
Start With Decisions, Not Deliverables
The biggest mistake I see is teams building a Figma library before they've agreed on fundamentals. They create 40 components, then discover half the team uses 8px spacing and the other half uses 4px.
Start by writing down the decisions:
- What is our base spacing unit?
- How many type sizes do we actually need?
- What are our semantic color roles (not just hex values)?
- Which components are shared, and which are product-specific?
These decisions don't need to be perfect. They need to be made. A mediocre decision applied consistently beats a perfect decision applied inconsistently.
Tokens Before Components
If I were starting a design system from scratch today, I'd spend the first two weeks on tokens alone.
Define your color palette as semantic roles: text-primary, surface-elevated, border-subtle, action-primary. Not blue-500 and gray-200. Semantic naming means the token survives a rebrand. The implementation changes; the role stays.
Do the same for spacing. Pick a scale — 4px base, powers of two, whatever fits your density — and commit. Every margin, padding, and gap should come from that scale. No arbitrary values.
Typography follows the same pattern: font families, size scale, line heights, letter spacing. Lock them down before you design a single screen.
The Adoption Problem
The best design system in the world is worthless if nobody uses it. Adoption fails for predictable reasons:
It's too slow. If importing a system component takes longer than copying a div from last week's PR, people will copy the div.
It's too rigid. Systems that don't allow escape hatches get forked. Provide composition primitives and clear guidance on when to break the rules.
It's too distant. If the system team sits in another building and ships updates quarterly, the product team will route around them. Embed system maintainers in product work. Make the system a service, not a mandate.
It's undocumented. A component without usage examples, do's and don'ts, and accessibility notes is just code someone else has to read. Documentation is not overhead — it's the product.
Measuring What Matters
Don't measure design system success by component count. Measure it by:
- Coverage: What percentage of UI in production uses system components?
- Drift: How often do teams create one-off variants instead of extending the system?
- Time to ship: Does using the system make features faster or slower?
- Consistency score: Can a new user navigate two different product areas without feeling a jarring shift?
A system with 12 well-maintained components that covers 80% of your UI is better than one with 200 components where 150 are unused.
When to Break Your Own Rules
Every mature system needs an escape valve. Document when breaking the system is acceptable:
- Experimental features that may not ship
- Brand-specific marketing pages with unique visual needs
- Performance-critical surfaces where bundle size matters
- Accessibility requirements the system doesn't yet support
The key is making the break visible. A one-off component in a product folder is fine. A forked button that silently diverges from the system is not.
Closing Thought
Design systems are infrastructure. They're boring until they're not — until a rebrand takes two weeks instead of six months, until a new engineer ships a polished feature on day three, until your product feels like one thing instead of twelve things stitched together.
Build the library. But don't stop there. Encode the decisions, write the docs, and create the process that keeps everything aligned as the team grows.
That's the system.