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

# Clementine DS Token Cascade: Primitives to Components

> Three strict tiers — primitive, semantic, component — form the Clementine DS token cascade, enabling safe theming and mechanical drift detection.

Clementine DS organizes tokens into three tiers: primitive, semantic, and component. The cascade flows in one direction only — each tier may reference only the tier directly above it. Components never reference primitives. Semantics never reference components. Primitives reference nothing. This one rule is what makes safe theming, mechanical drift detection, and unambiguous agent contracts possible. Break the rule once and the entire guarantee collapses.

## 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 name `color.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.

```json theme={null}
{
  "color": {
    "blue": {
      "6": { "$value": "#2563eb", "$type": "color" }
    }
  },
  "radius": {
    "md": { "$value": "8px", "$type": "dimension" }
  }
}
```

You will rarely reference primitives directly in documentation or code. Their job is to be the single source of resolved values that the semantic tier draws from.

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

```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" }
  },
  "feedback": {
    "error": { "$value": "{color.red.6}", "$type": "color" }
  },
  "focus": {
    "ring": { "$value": "#ff8040", "$type": "color" }
  }
}
```

> [!NOTE]
>
> `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](https://clementineds.mintlify.site/concepts/agentic-specs.md) puts in `token_contract`.

**Files:** `packages/tokens/src/components/<name>.json`

Component tokens reference semantic tokens. Always semantic, never primitive, never raw hex.

```json theme={null}
{
  "button": {
    "bg": {
      "default": { "$value": "{action.primary}",       "$type": "color" },
      "hover":   { "$value": "{action.primary-hover}",  "$type": "color" },
      "active":  { "$value": "{action.primary-active}", "$type": "color" }
    },
    "border": {
      "focus":   { "$value": "{focus.ring}",            "$type": "color" }
    }
  }
}
```

## The cascade diagram

The full resolution path, from component file to resolved value in the browser:

```
primitives.json          tier 1: raw scales (literal hex, px, numbers)
    │
    │  semantic references primitive
    ▼
semantic-{light,dark}    tier 2: intent-named tokens
    │
    │  component references semantic
    ▼
components/<name>.json   tier 3: per-component bindings
    │
    │  TSX references component token
    ▼
packages/ui/src/...      tier 4: the code
```

The arrow goes one way. Skipping a tier is not allowed. A component token that binds directly to `{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:

| You have | You must NOT | You must instead |
| - | - | - |
| A new button hover color | Bind `button.bg.hover` directly to `{color.blue.7}` | Bind `button.bg.hover` to `{action.primary-hover}`, which references `{color.blue.7}` |
| A new error message style | Bind directly to `text.error` if `feedback.error-message` doesn't exist | Add `feedback.error-message` to the semantic tier first, then bind to it |
| A one-off page heading color | Inline a hex in TSX | Use an existing semantic that fits. If none does, propose a new one and add it properly |
| A component token | Reference `{color.blue.6}` from the component file | Find or create the right semantic token and bind through it |

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

## Do / Don't

| Do | Don't |
| - | - |
| Add a component token whenever a component needs a new value | Reference a primitive directly from a component file |
| Keep semantic names intent-shaped, not appearance-shaped (`text.primary`, not `text.dark`) | Reference one semantic from another semantic |
| Use `references` and `primitive` fields when documenting component tokens in `tokens.json` | Hardcode a hex value in TSX or CSS |
| Extend the semantic tier when a new intent genuinely doesn't exist yet | Add a component token with no semantic backing — if it's truly one-off, the design probably needs review |
| Verify the full cascade resolves after adding any new token | Skip the validator after making token changes |


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