> ## Documentation Index
> Fetch the complete documentation index at: https://clementineds.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Semantic Tokens: Intent-Based Design Vocabulary

> Tier 2 of the cascade. Semantic tokens name what a value is for, not what it looks like — enabling dark mode, theming, and intent-driven design.

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.

| Token | Light value | Dark value | Role |
| - | - | - | - |
| `action.primary` | `{color.blue.6}` → `#2563eb` | `{color.blue.4}` → `#60a5fa` | Primary action fill |
| `action.primary-hover` | `{color.blue.7}` → `#1d4ed8` | `{color.blue.3}` → `#93c5fd` | Hover state |
| `action.primary-active` | `{color.blue.8}` → `#1e40af` | `{color.blue.5}` → `#3b82f6` | Mouse-down / pressed state |
| `action.destructive` | `{color.red.6}` → `#dc2626` | `{color.red.4}` → `#f87171` | Irreversible action fill |
| `action.destructive-hover` | `{color.red.7}` → `#b91c1c` | `{color.red.3}` → `#fca5a5` | Destructive hover state |

***

### Surface

Background fills. Page canvas, elevated containers, hover washes, and modal backdrops.

| Token | Light value | Dark value | Role |
| - | - | - | - |
| `surface.default` | `{color.gray.0}` → `#fafaf8` | `#1a2735` | Page background |
| `surface.elevated` | `{color.white}` → `#ffffff` | `#243447` | Card, modal, popover |
| `surface.subtle` | `{color.gray.1}` → `#f3f3f0` | `#15202e` | Hover wash, subtle fill |
| `surface.overlay` | `rgba(0,0,0,0.4)` | `rgba(0,0,0,0.6)` | Modal backdrop scrim |

***

### Text

Foreground colors for prose, labels, and controls.

| Token | Light value | Dark value | Role |
| - | - | - | - |
| `text.primary` | `{color.gray.9}` → `#1a1a18` | `#f0f4f8` | Default body and label text |
| `text.secondary` | `{color.gray.6}` → `#6b6b66` | `#a0aec0` | Subdued text, helper copy |
| `text.tertiary` | `{color.gray.4}` → `#a3a39e` | `#718096` | Placeholder, disabled label |
| `text.on-action` | `{color.white}` → `#ffffff` | `{color.white}` → `#ffffff` | Label on filled action button |
| `text.link` | `{color.blue.6}` → `#2563eb` | `{color.blue.4}` → `#60a5fa` | Inline hyperlink |

***

### Border

Line and stroke colors for inputs, dividers, and focus indicators.

| Token | Light value | Dark value | Role |
| - | - | - | - |
| `border.default` | `{color.gray.2}` → `#e5e5e0` | `#4a5568` | Subtle divider |
| `border.strong` | `{color.gray.3}` → `#d4d4cf` | `#718096` | Input and control border |
| `border.focus` | `{color.blue.6}` → `#2563eb` | `{color.blue.4}` → `#60a5fa` | Focused input border |

***

### Focus

The one intentional literal in the semantic layer.

| Token | Light value | Dark value | Role |
| - | - | - | - |
| `focus.ring` | `#ff8040` | `#ff8040` | Focus ring for all interactive elements |

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.

| Token | Light value | Dark value | Role |
| - | - | - | - |
| `feedback.error` | `{color.red.6}` → `#dc2626` | `{color.red.4}` → `#f87171` | Error border and text |
| `feedback.error-subtle` | `{color.red.0}` → `#fef2f2` | `#3b1515` | Error background fill |
| `feedback.success` | `{color.green.6}` → `#16a34a` | `{color.green.4}` → `#4ade80` | Success border and text |
| `feedback.success-subtle` | `{color.green.0}` → `#f0fdf4` | `#15302b` | Success background fill |
| `feedback.warning` | `{color.orange.5}` → `#f97316` | `{color.orange.4}` → `#fb923c` | Warning border and text |
| `feedback.warning-subtle` | `{color.orange.0}` → `#fff7ed` | `#302015` | Warning background fill |

***

### 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.

| Token | Light value | Dark value | Role |
| - | - | - | - |
| `risk.critical` | `{color.red.9}` → `#7f1d1d` | `{color.red.4}` → `#f87171` | Critical severity foreground |
| `risk.critical-subtle` | `{color.red.0}` → `#fef2f2` | `#3b1515` | Critical severity background |
| `risk.high` | `{color.orange.7}` → `#c2410c` | `{color.orange.4}` → `#fb923c` | High severity foreground |
| `risk.high-subtle` | `{color.orange.0}` → `#fff7ed` | `#302015` | High severity background |
| `risk.medium` | `{color.orange.5}` → `#f97316` | `{color.orange.3}` → `#fdba74` | Medium severity foreground |
| `risk.medium-subtle` | `{color.orange.1}` → `#ffedd5` | `#2a1d10` | Medium severity background |
| `risk.low` | `{color.green.6}` → `#16a34a` | `{color.green.4}` → `#4ade80` | Low severity foreground |
| `risk.low-subtle` | `{color.green.0}` → `#f0fdf4` | `#15302b` | Low severity background |

***

## JSON source example

Here is the full `semantic-light.json` `action` and `focus` blocks as they appear in source:

```json theme={null}
{
  "action": {
    "primary":        { "$value": "{color.blue.6}", "$type": "color" },
    "primary-hover":  { "$value": "{color.blue.7}", "$type": "color" },
    "primary-active": { "$value": "{color.blue.8}", "$type": "color" },
    "destructive":       { "$value": "{color.red.6}", "$type": "color" },
    "destructive-hover": { "$value": "{color.red.7}", "$type": "color" }
  },
  "focus": {
    "ring": { "$value": "#ff8040", "$type": "color" }
  }
}
```

And the corresponding `semantic-dark.json` action block — same names, shifted primitives:

```json theme={null}
{
  "action": {
    "primary":        { "$value": "{color.blue.4}", "$type": "color" },
    "primary-hover":  { "$value": "{color.blue.3}", "$type": "color" },
    "primary-active": { "$value": "{color.blue.5}", "$type": "color" },
    "destructive":       { "$value": "{color.red.4}", "$type": "color" },
    "destructive-hover": { "$value": "{color.red.3}", "$type": "color" }
  },
  "focus": {
    "ring": { "$value": "#ff8040", "$type": "color" }
  }
}
```

The vocabulary is identical. The resolution is different. That is the mechanism that makes theme switching a file swap.

***

## Rules

| You can | You cannot |
| - | - |
| Reference any primitive on the right side of `$value` | Reference another semantic token |
| Add a new semantic when a new intent is genuinely missing | Add a semantic for a one-off appearance used by a single component |
| Use any semantic token as the `$value` in a component token file | Use a primitive token as the `$value` in a component token file |
| Assign different primitive references per theme file | Invent new token names in one theme file but not the other |

***

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.