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

# Component Tokens: Per-Component Design Bindings

> Tier 3 of the cascade. Component tokens give each component an explicit, named binding between semantic intent and a visible part — powering retheming and agent contracts.

Component tokens are **tier 3 of the 3-tier cascade**. Each component that has been migrated to the 3-tier model gets one JSON file in `packages/tokens/src/components/<name>.json`. A component token is an explicit, named binding between a semantic intent and a single visible part of a component — for example, the default background fill of a button, or the focus ring on a text input.

Component tokens are the tier that the spec's `token_contract` field lists. When an agent reads a spec and sees `token_contract: [button.bg.default, button.border.focus]`, those names are component tokens. The TSX reads them. The validator checks that they exist.

***

## Anatomy of a component token file

Every component token file follows the same structure: a top-level object keyed by component name, then by part, then by state. Here is `packages/tokens/src/components/button.json` in full:

```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" },
      "disabled": { "$value": "{surface.subtle}",         "$type": "color" }
    },
    "bg-destructive": {
      "default":  { "$value": "{action.destructive}",       "$type": "color" },
      "hover":    { "$value": "{action.destructive-hover}", "$type": "color" }
    },
    "bg-outline": {
      "default":  { "$value": "{surface.elevated}", "$type": "color" },
      "hover":    { "$value": "{surface.subtle}",   "$type": "color" }
    },
    "fg": {
      "on-filled":  { "$value": "{text.on-action}", "$type": "color" },
      "on-outline": { "$value": "{text.primary}",   "$type": "color" },
      "on-subtle":  { "$value": "{text.primary}",   "$type": "color" },
      "disabled":   { "$value": "{text.tertiary}",  "$type": "color" }
    },
    "border": {
      "default": { "$value": "{border.strong}",  "$type": "color" },
      "hover":   { "$value": "{action.primary}", "$type": "color" },
      "focus":   { "$value": "{focus.ring}",     "$type": "color" }
    },
    "radius": { "$value": "{radius.md}", "$type": "dimension" }
  }
}
```

Every `$value` on the right-hand side references a semantic token in curly-brace notation. No primitive appears directly. `{radius.md}` is permitted because it resolves through the semantic tier — `radius.md` is a primitive, but component tokens reference it via a semantic binding. (Where a dimension token has no semantic alias, component tokens reference the primitive by convention for non-color values.)

***

## Naming convention

Component token names follow one of two patterns:

* **`<component>.<part>.<state>`** — when a part has multiple states. Example: `button.bg.hover`, `button.fg.disabled`, `button.border.focus`.
* **`<component>.<part>`** — when a part has a single, stateless binding. Example: `button.radius`.

Use kebab-case for compound part names: `bg-destructive`, `fg-on-filled`, `bg-outline`. The full dot-path — `button.bg-destructive.hover` — is what the spec's `token_contract` and the validator use.

***

## Currently shipped component token files

| Component | File | Coverage |
| - | - | - |
| Button | `button.json` | Full: `bg`, `fg`, `border`, `radius` for all variants (filled, outline, destructive) and states (default, hover, active, disabled, focus) |
| Badge | `badge.json` | Full: `bg` per intent (neutral, success, error, warning, and all four risk tiers), `fg`, `radius` |
| Checkbox | `checkbox.json` | Full: `bg` per check state (unchecked, checked, indeterminate, disabled), `check`, `border`, `fg`, `radius` |
| Modal | `modal.json` | Full: `bg`, `overlay`, `fg` (title, body, secondary), `border`, `ring`, `radius` |
| Radio | `radio.json` | Full: `bg` per state (unchecked, disabled), `dot`, `border`, `fg` |
| Select | `select.json` | Full: `bg` (trigger, popover), `option` (bg and fg per state), `fg`, `border`, `ring`, `radius` |
| Switch | `switch.json` | Full: `track` (on, off, disabled), `thumb`, `border`, `fg` |
| Tabs | `tabs.json` | Full: `indicator`, `fg` per state (active, inactive, hover, disabled), `border` |
| TextInput | `text-input.json` | Full: `bg`, `fg`, `border` per state, focus ring, `radius` |
| Textarea | `textarea.json` | Full: `bg`, `fg`, `border` per state, `ring`, `radius` |

Every component in `packages/tokens/src/components/` has been migrated to the 3-tier model with a full token file. If you add a new component to the system, create its token file there before writing the TSX.

***

## Complete `tokens.json` entry example

The spec stores component token metadata in `specs/<component>/tokens.json`. Each entry records the full chain from component token to semantic to primitive to resolved light value. Here is a representative set from `specs/button/tokens.json`:

```json theme={null}
{
  "tokens": [
    {
      "name":       "button.bg.default",
      "tier":       "component",
      "role":       "default-fill",
      "path":       "button.bg.default",
      "references": "{action.primary}",
      "primitive":  "{color.blue.6}",
      "light":      "#2563eb",
      "status":     "existing"
    },
    {
      "name":       "button.bg.hover",
      "tier":       "component",
      "role":       "hover-fill",
      "path":       "button.bg.hover",
      "references": "{action.primary-hover}",
      "primitive":  "{color.blue.7}",
      "light":      "#1d4ed8",
      "status":     "existing"
    },
    {
      "name":       "button.fg.on-filled",
      "tier":       "component",
      "role":       "label-on-filled",
      "path":       "button.fg.on-filled",
      "references": "{text.on-action}",
      "primitive":  "{color.white}",
      "light":      "#ffffff",
      "status":     "existing"
    },
    {
      "name":       "button.border.focus",
      "tier":       "component",
      "role":       "focus-ring",
      "path":       "button.border.focus",
      "references": "{focus.ring}",
      "primitive":  "literal",
      "light":      "#ff8040",
      "status":     "existing"
    },
    {
      "name":       "button.radius",
      "tier":       "component",
      "role":       "corner-radius",
      "path":       "button.radius",
      "references": "{radius.md}",
      "primitive":  "6px",
      "light":      "6px",
      "status":     "existing"
    }
  ]
}
```

Each field has a precise meaning:

| Field | Purpose |
| - | - |
| `name` | The dot-path identifier. Matches `token_contract` entries in the spec. |
| `tier` | Always `"component"` for entries in this file. |
| `role` | Human-readable label for what this binding does. Used in drift reports. |
| `path` | Same as `name`. Used by the validator to look up the entry. |
| `references` | The semantic token this component token binds to. |
| `primitive` | The ultimately-resolved primitive (two hops: component → semantic → primitive). `"literal"` when the semantic holds a direct hex. |
| `light` | The resolved hex value in light mode. For documentation and drift checking. |
| `status` | `"existing"` for shipped tokens, `"pending"` for tokens declared in a spec but not yet implemented. |

***

## Why the indirection?

A component token can feel redundant on first read. If `action.primary` already exists, why does `button.bg.default` need to exist too? Three reasons:

### 1. Retheming without global side effects

You can point `button.bg.default` at a different semantic without affecting every other component that uses `action.primary`. This lets you retheme one component — for example, making marketing splash buttons use a brand accent — while keeping primary actions blue everywhere else. Without component tokens, every rethem decision is a global one.

### 2. Mechanical drift detection

When the TSX references `button.bg.default`, the validator can ask a yes/no question: does the TSX use this token? When the TSX references `action.primary` directly, the same value appears in Button, Badge, TextInput, and inline links — and the validator cannot tell which usage is intentional. Component tokens give the validator a component-scoped surface to check.

### 3. Unambiguous agent contracts

When an agent reads `token_contract: [button.bg.default]`, there is exactly one possible binding. The name encodes the component, the part, and the state. When an agent reads `action.primary` in a component spec, it must infer whether this is a button background, a link color, or a focus indicator. The narrower the name, the less the agent has to guess — and the less room there is for hallucination.

***

## When to add a new component token

Add a new entry to a component's token file — and to `specs/<component>/tokens.json` — when the spec's `token_contract` lists a name that does not yet exist, and the decision belongs to the component level rather than to the system level. Concrete cases:

* **A new state.** The Button gains a loading state. Add `button.bg.loading`, bind it to `surface.subtle` or a new semantic if needed.
* **A new variant.** The Badge gains a brand variant. Add `badge.bg.brand`, reference the appropriate semantic.
* **A new visible part.** Tabs gains a bottom-border indicator. Add `tabs.indicator.color`, bind it to `action.primary` or a new intent semantic.

Do not add a component token when:

* The intent spans multiple components. That belongs in semantic tier.
* You want a literal hex. A literal means either the primitive tier has a gap (extend it there) or the semantic tier lacks a named intent (add it there).

***

## Validation

The `agentic-spec validate` command checks component tokens in two ways:

1. **Contract completeness.** Every name listed in a spec's `token_contract` must have a matching entry in `specs/<component>/tokens.json`. A missing entry produces an `unknown-token` finding that blocks the spec from advancing to `AI-Ready` status.
2. **Tier correctness.** Every entry in `tokens.json` with `"tier": "component"` must have a `references` field that points at a valid semantic token — not a primitive. A component entry whose `references` field contains a primitive path (e.g., `{color.blue.6}`) produces a `bad-token-tier` finding.

The validator does not check whether `packages/tokens/src/components/<name>.json` matches the spec's declared entries — that file is the build output. The spec's `tokens.json` is the contract. Keep them in sync by running the token build after every spec change.


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