A design system is not a Figma file full of buttons. It is an agreement — between designers, engineers, and the product — about what things look like and how they behave. The file is just where the agreement is written down.
When you need one
The moment you ship a second surface. A marketing site and an app. An admin panel and a customer dashboard. The day two teams build the same modal differently is the day a system would have paid for itself.
Tokens: the layer that makes it work
Colours, spacing, type, and radius should be named values, not hex codes scattered across the codebase. We use three layers: primitive tokens (blue-600), semantic tokens (color-action), and component tokens (button-background). Change one semantic token and every button on every product updates.
- Primitive: the raw palette and scale. Never used directly in components.
- Semantic: meaning-based aliases — surface, text-muted, border-strong.
- Component: the handful of values a specific component needs, mapped from semantic tokens.
Design and code must not drift
A system that lives only in Figma is a suggestion. Every component we design has a coded twin in Storybook, and visual regression tests catch the moment they diverge. When designers and engineers look at the same source of truth, the review meetings get very short.
Documentation is the product
Usage rules, do-and-don't examples, and accessibility notes are what turn a component library into a system. Without them, every engineer reinvents the guidance — usually wrong. Write the docs as if the reader joined yesterday, because someone always did.
Consistency is not about sameness. It is about never making the user re-learn your product.
