Primitive tokens explained
The raw values every system is built on.

Zander Whitehurst
9 min read
Every design system sits on top of a pile of raw values. The exact blue of your brand, the sizes your spacing jumps between, the weights your fonts come in. These are primitive tokens, and while they are the least glamorous part of any system, they decide how solid everything above them feels.
When I first started building systems I skipped this layer entirely. I picked colours straight from a colour picker, typed them into components and called it a day. A year later we had forty seven slightly different greys in production. I counted. It was not a fun afternoon, and it is the reason I now start every system with primitives before anything else.
What a primitive token is
A primitive token is a named raw value. It says nothing about where the value is used, only what it is. blue-500 is a specific blue. space-4 is a specific distance. font-weight-600 is a specific weight.
Think of primitives as your palette. A painter does not decide which colour goes on the sky while mixing paint. They mix a set of colours first, then choose from them. Primitives are the mixing stage.
Why you need them
Without primitives, every value in your product is a decision made in isolation. Someone needs a border colour, so they pick one. Someone else needs a slightly lighter one, so they pick another. Nobody is wrong, and yet the product slowly fills up with values that almost match.
Primitives fix this by limiting the choices. When there are only ten greys to choose from, nobody invents an eleventh by accident. Constraints like this are what make a product feel coherent, even when dozens of people are working on it.
Build colour as scales
Colour primitives work best as scales, where each hue has a range of steps from light to dark. A common pattern uses numbers from 50 to 950:
{
"blue": {
"50": "#eff6ff",
"100": "#dbeafe",
"500": "#3b82f6",
"700": "#1d4ed8",
"950": "#172554"
}
}
The numbers give you room. If you later need something between 500 and 700, you can add 600 without renaming anything. Try to keep the steps visually even, so moving from one step to the next feels like the same jump each time.
Spacing and sizing
Spacing primitives are usually built on a base unit, often 4 or 8 pixels. Each step is a multiple of that base:
:root {
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--space-6: 24px;
--space-8: 32px;
}
You do not need every multiple. Leaving gaps at the larger end of the scale is healthy, because it pushes people towards a handful of clear choices rather than endless fine tuning.
Typography primitives
Type primitives cover font families, sizes, weights and line heights. Keep each list short. Most products need two font families at most, three or four weights and a size scale of around eight steps.
I once inherited a project with eleven font weights loaded. The product used three of them. The other eight were just quietly slowing down every page load, like guests who stay long after the party ends.
Name them by what they are
Primitive names should describe the value, not the purpose. grey-200 is a good primitive name. card-border is not, because that is a job, and jobs belong in the semantic layer.
This separation matters. If a primitive is named after its purpose, you will eventually want to use it somewhere else and the name will start lying. Keeping primitives purely descriptive means they never need renaming when the product changes.
Keep primitives out of components
Here is the rule that surprises people: components should rarely use primitives directly. A button should not reference blue-500. It should reference something like action-primary, which in turn points at blue-500.
Primitives are the ingredients. Components should be cooking from a recipe, not grabbing ingredients off the shelf. This is what makes theming and rebranding possible later without touching every component in the product.
How many is enough
There is no perfect number, but here is a reasonable starting point for most products:
- One neutral scale and one brand scale of around ten steps each
- Small scales for success, warning and danger colours
- A spacing scale of eight to twelve steps
- A type scale of six to eight sizes
- Two or three radius values and two or three shadow values
If you find yourself with far more than this, ask whether every value is genuinely needed or whether some are near duplicates.
Primitives and AI agents
AI agents love a primitive. Give them access to blue-500 and they will use it everywhere, because it looks like a valid choice. That is exactly why primitives should be documented as a foundation layer that components and agents should not reach for directly. A single line in your docs saying "use semantic tokens, never primitives, in components" prevents a surprising amount of mess. The AI Color Token Skills give your agent this structure from the start.
Start with an audit
Open your product's code or your Figma file and list every colour value you can find. Group the ones that look nearly identical. You will probably find far more than you expected. Collapse them into a single neutral scale and a single brand scale, give each step a plain descriptive name and you have the first version of your primitives. Everything else in your system gets easier from there. We build the full token stack, from primitives up, in our AI Design Systems Bootcamp.
Memorisely