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

# Primitive Tokens: Raw Design Scales in Clementine DS

> Tier 1 of the Clementine DS cascade. Primitive tokens are raw scales with no intent — literal hex colors, pixel dimensions, and type scales.

Primitive tokens are **tier 1 of the 3-tier cascade**. They live in `packages/tokens/src/primitives.json` and contain every raw value the design system knows about — literal hex colors, pixel dimensions, type scales, shadow definitions, and motion durations. Primitives carry no intent. `color.blue.6` is a hex value. It does not know whether it is a button background, a link color, or a focus border. That meaning lives one tier up, in semantic tokens.

You will rarely touch this file. When you do, you are extending the design language itself.

***

## Token groups

### Color

Five perceptual ramps (0 = lightest tint, 9 = darkest shade) plus two literals.

#### `color.blue` — Cool, primary action

| Step | Value |
| - | - |
| `color.blue.0` | `#eff4ff` |
| `color.blue.1` | `#dbeafe` |
| `color.blue.2` | `#bfdbfe` |
| `color.blue.3` | `#93c5fd` |
| `color.blue.4` | `#60a5fa` |
| `color.blue.5` | `#3b82f6` |
| `color.blue.6` | `#2563eb` |
| `color.blue.7` | `#1d4ed8` |
| `color.blue.8` | `#1e40af` |
| `color.blue.9` | `#1e3a8a` |

#### `color.red` — Error, destructive actions

| Step | Value |
| - | - |
| `color.red.0` | `#fef2f2` |
| `color.red.1` | `#fee2e2` |
| `color.red.2` | `#fecaca` |
| `color.red.3` | `#fca5a5` |
| `color.red.4` | `#f87171` |
| `color.red.5` | `#ef4444` |
| `color.red.6` | `#dc2626` |
| `color.red.7` | `#b91c1c` |
| `color.red.8` | `#991b1b` |
| `color.red.9` | `#7f1d1d` |

#### `color.gray` — Surfaces, text, borders

| Step | Value |
| - | - |
| `color.gray.0` | `#fafaf8` |
| `color.gray.1` | `#f3f3f0` |
| `color.gray.2` | `#e5e5e0` |
| `color.gray.3` | `#d4d4cf` |
| `color.gray.4` | `#a3a39e` |
| `color.gray.5` | `#737370` |
| `color.gray.6` | `#6b6b66` |
| `color.gray.7` | `#52524e` |
| `color.gray.8` | `#3a3a37` |
| `color.gray.9` | `#1a1a18` |

#### `color.green` — Success

| Step | Value |
| - | - |
| `color.green.0` | `#f0fdf4` |
| `color.green.1` | `#dcfce7` |
| `color.green.2` | `#bbf7d0` |
| `color.green.3` | `#86efac` |
| `color.green.4` | `#4ade80` |
| `color.green.5` | `#22c55e` |
| `color.green.6` | `#16a34a` |
| `color.green.7` | `#15803d` |
| `color.green.8` | `#166534` |
| `color.green.9` | `#14532d` |

#### `color.orange` — Warning, the Clementine accent

| Step | Value |
| - | - |
| `color.orange.0` | `#fff7ed` |
| `color.orange.1` | `#ffedd5` |
| `color.orange.2` | `#fed7aa` |
| `color.orange.3` | `#fdba74` |
| `color.orange.4` | `#fb923c` |
| `color.orange.5` | `#f97316` |
| `color.orange.6` | `#ea580c` |
| `color.orange.7` | `#c2410c` |
| `color.orange.8` | `#9a3412` |
| `color.orange.9` | `#7c2d12` |

#### Literals

| Token | Value |
| - | - |
| `color.white` | `#ffffff` |
| `color.black` | `#0a0a09` |

***

### Radius

Border-radius scale. Used by component tokens to set corner curves.

| Token | Value |
| - | - |
| `radius.xs` | `2px` |
| `radius.sm` | `4px` |
| `radius.md` | `6px` |
| `radius.lg` | `8px` |
| `radius.xl` | `99px` (pill) |

***

### Spacing

Layout and padding scale.

| Token | Value |
| - | - |
| `spacing.xs` | `4px` |
| `spacing.sm` | `8px` |
| `spacing.md` | `16px` |
| `spacing.lg` | `24px` |
| `spacing.xl` | `32px` |

***

### Shadow

Elevation scale from hair-thin to dramatic.

| Token | Value |
| - | - |
| `shadow.xs` | `0 1px 2px rgba(0,0,0,0.05)` |
| `shadow.sm` | `0 1px 3px rgba(0,0,0,0.08)` |
| `shadow.md` | `0 4px 12px rgba(0,0,0,0.12)` |
| `shadow.lg` | `0 8px 24px rgba(0,0,0,0.16)` |
| `shadow.xl` | `0 16px 48px rgba(0,0,0,0.2)` |

***

### Typography

#### `typography.font-family`

| Token | Value |
| - | - |
| `typography.font-family.sans` | `'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif` |
| `typography.font-family.mono` | `'JetBrains Mono', 'IBM Plex Mono', 'Fira Code', monospace` |

#### `typography.font-size`

| Token | Value |
| - | - |
| `typography.font-size.xs` | `12px` |
| `typography.font-size.sm` | `14px` |
| `typography.font-size.md` | `16px` |
| `typography.font-size.lg` | `18px` |
| `typography.font-size.xl` | `20px` |

#### `typography.line-height`

| Token | Value |
| - | - |
| `typography.line-height.xs` | `1.4` |
| `typography.line-height.sm` | `1.45` |
| `typography.line-height.md` | `1.55` |
| `typography.line-height.lg` | `1.6` |
| `typography.line-height.xl` | `1.65` |

***

### Motion

| Token | Value |
| - | - |
| `motion.duration-fast` | `100ms` |
| `motion.duration-normal` | `200ms` |
| `motion.duration-slow` | `300ms` |

***

## JSON source example

Here is the actual structure of `packages/tokens/src/primitives.json` for the color and radius groups:

```json theme={null}
{
  "color": {
    "blue": {
      "0":  { "$value": "#eff4ff", "$type": "color" },
      "1":  { "$value": "#dbeafe", "$type": "color" },
      "2":  { "$value": "#bfdbfe", "$type": "color" },
      "3":  { "$value": "#93c5fd", "$type": "color" },
      "4":  { "$value": "#60a5fa", "$type": "color" },
      "5":  { "$value": "#3b82f6", "$type": "color" },
      "6":  { "$value": "#2563eb", "$type": "color" },
      "7":  { "$value": "#1d4ed8", "$type": "color" },
      "8":  { "$value": "#1e40af", "$type": "color" },
      "9":  { "$value": "#1e3a8a", "$type": "color" }
    },
    "white": { "$value": "#ffffff", "$type": "color" },
    "black": { "$value": "#0a0a09", "$type": "color" }
  },
  "radius": {
    "xs": { "$value": "2px",  "$type": "dimension" },
    "sm": { "$value": "4px",  "$type": "dimension" },
    "md": { "$value": "6px",  "$type": "dimension" },
    "lg": { "$value": "8px",  "$type": "dimension" },
    "xl": { "$value": "99px", "$type": "dimension" }
  }
}
```

Every entry is a `$value` / `$type` pair. Nothing references another token. Primitives are always terminal — they hold the actual values every other tier resolves to.

***

## The cascade rule: never skip a tier

> [!WARNING]
>
> Do not reference primitive tokens from component token files. The cascade
> requires the semantic tier in between. A component file that references a
> primitive directly will fail the `agentic-spec validate` check with a
> `bad-token-tier` finding, break theme switching, and produce ambiguous agent
> contracts.

Here is what that violation looks like, and the correct form:

```json theme={null}
// WRONG — component file referencing a primitive directly
{
  "button": {
    "bg": {
      "default": { "$value": "{color.blue.6}" }
    }
  }
}

// RIGHT — component file referencing a semantic, which binds the primitive
{
  "button": {
    "bg": {
      "default": { "$value": "{action.primary}" }
    }
  }
}
```

The semantic `action.primary` resolves to `{color.blue.6}` in light mode and `{color.blue.4}` in dark mode. The component token does not need to know which — it only needs to know the intent.

***

## When to add a new primitive

You almost never need to. The existing scales cover the visual surface area of a small design system. The two cases where adding a primitive is warranted are:

1. **A new color family.** A brand accent color that does not fit any existing ramp — for example, a violet family for a new product line. You add the full 10-step scale (0–9), then add semantics that use it, then add component tokens that reference those semantics.
2. **An additional step in an existing scale.** A tint lighter than `color.blue.0` or a shade darker than `color.blue.9` that the design language genuinely requires.

If you add a primitive, the workflow is: extend `primitives.json` → run the build → add a semantic that uses the new primitive → add or update a component token that references that semantic. Do not skip any step.


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