Skip to main content
Semantic tokens are tier 2 of the 3-tier cascade. They translate raw primitives into named intent. Where 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 full semantic-light.json action and focus blocks as they appear in source:
And the corresponding semantic-dark.json action block — same names, shifted primitives:
The vocabulary is identical. The resolution is different. That is the mechanism that makes theme switching a file swap.

Rules


When to add a new semantic token

Three signals tell you a new semantic is warranted:
  1. 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.
  2. 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.json and semantic-dark.json with matching names.
  3. Accessibility requires a distinct state. A visual state — focus, selected, indeterminate — that needs its own guaranteed color across all components.
One signal that you should not add a semantic: a single component needs a unique color. That belongs in a component token, not the shared semantic vocabulary.