The three tiers
Tier 1: Primitives
Primitives are raw scales with no intent attached. A primitive says what a value is, not what it’s for. The namecolor.blue.6 tells you the scale step, not where it should appear.
File: packages/tokens/src/primitives.json
Primitives reference nothing. They hold literal values — hex colors, pixel measurements, number scales.
Tier 2: Semantic tokens
Semantic tokens express intent. The name says what the value is for, not what it looks like.action.primary tells you where to apply the token; it says nothing about whether it resolves to blue, teal, or orange — that’s determined by the primitive it references, and by which semantic file (light or dark) is active.
Files: packages/tokens/src/semantic-light.json, packages/tokens/src/semantic-dark.json
Semantic tokens reference primitives. They never reference each other, and they never reference component tokens.
focus.ring uses a raw hex rather than a primitive reference because the Clementine orange focus colour doesn’t belong to any named scale in primitives.json. This is a deliberate exception: the value is design-owned, not scale-derived. You’ll see it in both semantic-light.json and semantic-dark.json unchanged. Don’t treat it as a template for new semantic tokens — most semantics must reference a primitive.Tier 3: Component tokens
Component tokens are per-component bindings. The name encodes both the component and the part:button.bg.default is the button’s root background in the default state. These names are what the agentic spec puts in token_contract.
Files: packages/tokens/src/components/<name>.json
Component tokens reference semantic tokens. Always semantic, never primitive, never raw hex.
The cascade diagram
The full resolution path, from component file to resolved value in the browser:{color.blue.6} has skipped tier 2 — the intent is missing, the theming guarantee breaks, and the validator will flag it.
The cascade rule
The constraint is simple but absolute. Here’s how it applies to common situations:Why three tiers?
Two tiers — primitive plus semantic — is enough for a small system. The pain shows up when you need to work at scale. Retheming a single component. Without a component tier, you can’t change the button’s hover color without potentially affecting every other surface that uses the same semantic. With a component tier,button.bg.hover is a single binding you update in isolation.
Drift detection. When you upgrade a semantic token, you need to know which components are affected. With a component tier, the answer is mechanical: find every component file that references the changed semantic. Without a component tier, you have to audit every line of every TSX file.
Agent contracts. When an agent asks “what color should the button hover state be?”, the answer with a component tier is button.bg.hover — unambiguous, one lookup. Without a component tier, the agent has to derive which semantic is currently bound to the interactive-hover intent and whether it’s the right one for this component. That’s the gap where hallucinations happen.
The third tier costs you one extra JSON file per component. The payoff is that every spec’s token_contract is unambiguous, machine-checkable, and immune to drift.
Light and dark mode
Light and dark mode do not require two separate component tiers. The component tokens —button.bg.default, badge.bg.success, text-input.border.focus — are identical in both modes. The difference lives entirely in the semantic tier.
semantic-light.json and semantic-dark.json use exactly the same token vocabulary. action.primary exists in both files. In the light file it resolves to {color.blue.6}. In the dark file it may resolve to a different step on the same scale, or a different scale entirely — whatever the design calls for.
Switching themes is a file swap: resolve through semantic-light.json or semantic-dark.json. No component token names change. No code changes. The cascade does the rest.
This means you should never hardcode a resolved value in a component token. button.bg.default: "#2563eb" is wrong even if it looks right in light mode. button.bg.default: "{action.primary}" is right because it stays correct when the theme changes.