My approach to building design systems — from tokens and primitives to the decisions I've reversed after building several production systems, and the single question that makes every design system decision easier.
A design system is a bet. You're betting that the investment in consistency, documentation, and abstraction will pay off more than the time it costs to build and maintain. For small projects, that bet is often wrong. For anything beyond a single landing page, it's almost always right.
I've built design systems from scratch for three projects now, inherited a poorly documented one, and contributed to a larger team's system. Here's what I've learned.
The most common mistake I see when people start building design systems — including early me — is jumping straight into token definitions. What's the spacing scale? What are the brand colours? What's the type ramp?
These are important questions. But they're not the first question. The first question is: what is this system for?
Specifically:
The answers to these questions determine the architecture of the system before you've written a single token. Get them wrong and you'll spend months rebuilding.
After experimenting with several approaches, the hierarchy I keep returning to has three layers:
The raw values. These should be named for what they are, not what they do.
Aliases that map primitives to purpose. These are what components reference.
Scoped tokens for specific components. Optional, but useful when a component has many configurable properties.
"The semantic layer is where the real design system lives. Primitives are facts. Semantics are decisions."
I used to advocate hard for 4px base spacing grids. Multiples of 4. Everything divisible by 4. It felt rigorous and mathematical.
I've softened on this. The 4px grid is excellent for component-level spacing — padding, gaps, border radii. But applying it rigidly to layout-level spacing creates strange constraints. Layout spacing is not the same problem as component spacing, and trying to solve both with the same scale produces either a scale with too many steps (hard to choose from) or one with too few (too coarse).
My current approach: 4px base for component spacing, a separate geometric scale for layout spacing (0.5rem, 1rem, 2rem, 4rem, 8rem, 12rem).
Early on, I built systems with very granular primitives. A Text component. A Box component. A Stack component. Every UI element assembled from these atoms.
The problem: the abstraction is leaky in every direction. The "atoms" are too low-level for designers to think in, and too high-level for engineers who need fine-grained control. You end up with a system that nobody actually wants to use, because it doesn't match anyone's mental model.
Now I build systems that match the vocabulary the team already uses. If the team says "card," there's a Card component. If they say "toolbar," there's a Toolbar. The design system is documentation of the team's shared language, not an abstract architecture.
The most underinvested part of every design system is documentation. And the most valuable kind of documentation is not "here's the API" — it's "here's when to use this, and here's when not to."
Decision criteria are more valuable than specifications. A specification tells you what a component does. Decision criteria tell you when to reach for it.
When I'm stuck on a design system decision — whether to add a new component, whether to break a token out of a parent token, whether a variant should be a prop or a separate component — I ask a single question:
Does this make it easier to do the right thing and harder to do the wrong thing?
A design system is a set of constraints. Good constraints liberate. They narrow the decision space to the point where doing good work becomes the path of least resistance. If an addition makes it easier to build consistent, accessible, performant UI — it belongs in the system. If it increases complexity without a proportional benefit, it doesn't.
I consult on design system architecture and implementation through Greene Studios.