The first design system I built seriously had a full component layer, tokens scoped per component, and a product still in production underneath it. It looked like maturity. It was rework.
The system that was rework
Every product change broke something three layers down, and a live product changes every week. I spent more time keeping the system coherent than designing in it.
The problem was never technical. I knew how to build the layers. The problem was judgment: I never asked whether that product, at that moment, needed all of it. It did not.
The five layers, and what each one holds
The architecture I use has five levels, and all of them exist. Having all of them on a given project was never the goal.
| Layer | What it holds |
|---|---|
| Core | The raw values. |
| Palette | The colour ramps built on top of Core. |
| Brand | What each client pulls from Palette and Core. |
| Semantic | The purpose of each token. |
| Component | Tokens scoped to a single piece. Usually one layer too many. |
The four-layer version of this is what actually shipped on the Vellumwire design system. It stops at Semantic.
What the system has to do is prevent consistency errors without generating maintenance nobody asked for. Every layer past that point is cost.
The component layer is the first place you can overdo it
It earns its place in a large product, with several teams touching the same components, where each piece has to be protected individually.
In a small product, or one still changing shape every week, it is dead weight. You write a rigid contract for something that has not decided what it wants to be yet. For a small company the right ceiling is Semantic, and stopping there is sizing the system to the product it actually serves.
Fine: the escape hatch in the spacing scale
Where the line sits exactly is the part nobody documents. Two of my own decisions describe it well. The first is what I call Fine.
The spacing Core is built on multiples of 4 and 8, consolidated values that stop every screen inventing its own rhythm. But blind restriction produces ugly components. Sometimes you need 6, or 10, or 2, and refusing that only because it is not a multiple of 8 ships a worse result.
So Semantic carries a Fine range for those cases. The system stays restrictive enough to prevent a mess, and flexible enough that the rule never forces you to deliver something crooked in its name.
The second decision: when not to create a token
Tokens cover around 90% of the decisions. The other 10% are not worth the structure.
An avatar with no photo can take 25 different colours depending on the person's initials. Tokenizing that means creating 25 tokens nobody will reuse, to solve a case a function solves better. Covering everything only makes the system heavier without making it stronger. What earns a token is what repeats.
The mandatory few, and documenting the rest
The same care applies when the system scales. Early on I created too many tokens, and a bloated system is as bad as a loose one, because nobody can remember what exists.
The mandatory ones are few and pull straight from Core: font size, icon size, line height, padding. Documenting Semantic properly is what keeps the rest from turning into a mess, because documentation is what stops a token being used where it should not be. Padding and margin are the classic pair that goes wrong the moment that rule is not explicit.
None of this matters if the values never reach the screen as tokens in the first place. That failure has its own article: design tokens vs. hardcoded values.
Where the line actually sits
I started shaping this logic on freelance work, testing it on small projects where being wrong was cheap. Instivo was the first product with enough scale to stress all of it and show what held. The rest came with time and a fair amount of being wrong in public.
The maturity of a design system is not measured by how many layers it has. It is measured by knowing the smallest architecture that solves that product's problem, at that moment.
More layers is easy. Stopping at the right point is what separates a system from decoration.