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 ofpackages/tokens/src/primitives.json for the color and radius groups:
$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
Here is what that violation looks like, and the correct form: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:- 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.
- An additional step in an existing scale. A tint lighter than
color.blue.0or a shade darker thancolor.blue.9that the design language genuinely requires.
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.