By April we had three active projects running component libraries. Each one had a Button, a Card, and a Modal. None of them were compatible. The components looked similar but behaved differently — different prop interfaces, different spacing scales, different accessibility patterns.
We had components. We did not have a system.
What makes it a system
A design system is not a folder of reusable components. It is a shared language between designers and developers. It includes decisions about spacing, typography, color, interaction patterns, and naming — and those decisions are documented and enforced.
The components are an output of the system. They are not the system itself.
The inventory exercise
We started by auditing all three projects. We listed every component, its props, its variants, and its actual usage. The results were illuminating:
- Fourteen different button variants across three projects. Only four were meaningfully distinct.
- Three different spacing scales. One used multiples of 4px, one used multiples of 8px, one used Tailwind defaults.
- Two competing patterns for form validation — one inline, one toast-based.
The audit took two days. It saved weeks of future inconsistency.
Tokens before components
We rebuilt the system from the bottom up, starting with design tokens — the atomic values that everything else references. A single source of truth for colors, spacing, typography, shadows, and border radii.
These tokens are defined in one JSON file and consumed by both Figma (through a plugin) and code (through CSS custom properties). When the brand color changes, it changes in one place.
Documentation is the product
The design system’s primary deliverable is its documentation site. Every component page includes:
- A live example with interactive controls.
- Usage guidelines explaining when to use the component and when not to.
- Accessibility notes covering keyboard behavior, ARIA attributes, and screen reader expectations.
- Code snippets showing correct implementation.
We discovered that adoption correlated directly with documentation quality. Well-documented components were used consistently. Poorly-documented ones were reimplemented from scratch by developers who could not figure out the intended API.
Governance without bureaucracy
Adding a new component follows a lightweight process: write a proposal (two paragraphs explaining the need), build a prototype, get one design review and one code review, add documentation, merge.
Changing an existing component requires a migration note. If the change is breaking, provide a codemod or a clear upgrade guide. Developers should never discover a breaking change through a failed build.
What we stopped doing
We stopped building speculative components. If only one project needs a DateRangePicker, it lives in that project. A component earns its place in the system when it is needed in three or more contexts.
We also stopped designing components in isolation. Every new component is first designed in context — inside an actual page layout — to ensure it works with real content and real constraints.
The current state
Our design system is small: around forty components. It covers forms, navigation, layout, feedback, and data display. It does not try to be comprehensive. It tries to be correct, consistent, and well-documented.
That turns out to be enough.
