Skip to main content
Primitive tokens are tier 1 of the 3-tier cascade. They live in packages/tokens/src/primitives.json and contain every raw value the design system knows about — literal hex colors, pixel dimensions, type scales, shadow definitions, and motion durations. Primitives carry no intent. color.blue.6 is a hex value. It does not know whether it is a button background, a link color, or a focus border. That meaning lives one tier up, in semantic tokens. You will rarely touch this file. When you do, you are extending the design language itself.

Token groups

Color

Five perceptual ramps (0 = lightest tint, 9 = darkest shade) plus two literals.

color.blue — Cool, primary action

color.red — Error, destructive actions

color.gray — Surfaces, text, borders

color.green — Success

color.orange — Warning, the Clementine accent

Literals


Radius

Border-radius scale. Used by component tokens to set corner curves.

Spacing

Layout and padding scale.

Shadow

Elevation scale from hair-thin to dramatic.

Typography

typography.font-family

typography.font-size

typography.line-height


Motion


JSON source example

Here is the actual structure of packages/tokens/src/primitives.json for the color and radius groups:
Every entry is a $value / $type pair. Nothing references another token. Primitives are always terminal — they hold the actual values every other tier resolves to.

The cascade rule: never skip a tier

Do not reference primitive tokens from component token files. The cascade requires the semantic tier in between. A component file that references a primitive directly will fail the agentic-spec validate check with a bad-token-tier finding, break theme switching, and produce ambiguous agent contracts.
Here is what that violation looks like, and the correct form:
The semantic action.primary resolves to {color.blue.6} in light mode and {color.blue.4} in dark mode. The component token does not need to know which — it only needs to know the intent.

When to add a new primitive

You almost never need to. The existing scales cover the visual surface area of a small design system. The two cases where adding a primitive is warranted are:
  1. A new color family. A brand accent color that does not fit any existing ramp — for example, a violet family for a new product line. You add the full 10-step scale (0–9), then add semantics that use it, then add component tokens that reference those semantics.
  2. An additional step in an existing scale. A tint lighter than color.blue.0 or a shade darker than color.blue.9 that the design language genuinely requires.
If you add a primitive, the workflow is: extend primitives.json → run the build → add a semantic that uses the new primitive → add or update a component token that references that semantic. Do not skip any step.