Memorisely
Design Systems

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.

Numbered steps leave room to add blue-600 later without renaming anything.

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.

Descriptive names never start lying when a value gets used somewhere new.

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.

The button points at a semantic token, which points at the primitive, so a rebrand changes one line.

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.

Keep reading

View all
View all

Optimize your AI for better experiences, not AI slop.

View all

AI Prototyping Skills

Prototype with AI using clean UI patterns and guardrails so flows feel product-grade, not generic template slop.

$99

AI UI Motion Skills

Motion and micro-interaction patterns that make AI-built UI feel designed, polished, and trustworthy in real products.

$99

Fix AI Slop Skills

Spot AI slop early and fix type, spacing, and components so your product looks intentional, not like a template.

$99

AI Responsive Design Skills

Responsive layout patterns for rails, sidebars, and breakpoints so AI-generated UI adapts cleanly from narrow to wide.

$99

AI Dark Mode Skills

Dark theme tokens, contrast, and surfaces that keep AI-generated UI readable and product-grade, not flat gray on black.

$99

AI Color Token Skills

Neutral and primary ramps with clear steps so AI palettes stay systematic, not a random set of accent hex codes.

$99
View all