color.blue.6 is a hex value, action.primary is a decision: this is the fill for a primary interactive control. Semantic tokens are what the system uses to answer the question why is this value here?
Two files define the semantic vocabulary: packages/tokens/src/semantic-light.json and packages/tokens/src/semantic-dark.json. Both files use identical token names. Only the primitive bindings change between them. Theme switching is a file swap, not a vocabulary swap — no component token or TSX file changes when you move from light to dark.
Token categories
Action
User-initiated interactions: buttons, links, interactive icons. Every interactive fill in the system traces back to one of these tokens.Surface
Background fills. Page canvas, elevated containers, hover washes, and modal backdrops.Text
Foreground colors for prose, labels, and controls.Border
Line and stroke colors for inputs, dividers, and focus indicators.Focus
The one intentional literal in the semantic layer.
Clementine uses an orange focus ring across both themes for instant, high-contrast visibility. It is not a primitive reference — it is the same literal hex in both
semantic-light.json and semantic-dark.json. Do not change this value without verifying WCAG 3:1 non-text contrast on every surface color.
Feedback
Inline status indicators: error states, success confirmations, and warnings. Each intent ships a strong foreground variant and a subtle background variant.Risk
Four severity tiers for UI surfaces that rank risk, impact, or urgency. Each tier has a strong foreground and a subtle background variant. The risk scale runs on the red and orange ramps — the same color families as destructive actions and warnings, but scoped to classification rather than interaction.JSON source example
Here is the fullsemantic-light.json action and focus blocks as they appear in source:
semantic-dark.json action block — same names, shifted primitives:
Rules
When to add a new semantic token
Three signals tell you a new semantic is warranted:- Repeated cross-component binding. You find yourself writing the same primitive reference in three or more component token files for the same reason. That repeated reason is an intent the system has not named yet. Promote it to a semantic.
- Theme switching requires it. A value needs to differ between light and dark under the same name. If you cannot express that with an existing semantic, you need a new one — and you must add it to both
semantic-light.jsonandsemantic-dark.jsonwith matching names. - Accessibility requires a distinct state. A visual state — focus, selected, indeterminate — that needs its own guaranteed color across all components.