> ## Documentation Index
> Fetch the complete documentation index at: https://substrate.docs.unknowncreatives.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Color Token Reference

> Every color custom property Substrate emits: the --ucs-* intent primitives the solver writes, the baked per-mode triptychs, and the context variables.

Substrate does not emit a palette of named color tokens. It emits **per-intent solver primitives** — hue, chroma, and solved lightness channels — and the generated CSS composes final colors from them with `calc()`. Every variable below exists for *every intent the brand declares*: the conventional names (`brand`, `neutral`, `danger`, `warning`, `success`, `info`, `beta`) and any custom intents (`tier-gold`, `acme-cyan`, …) get identical treatment. See [Core Concepts](/core-concepts#computed-vs-static-tokens) for the model.

<Note>
  There is no `--color-*` namespace. Intent names come solely from the brand's `intents:` map — the demo configs and these docs use the conventional `danger` for destructive states, and no `error` intent exists unless a brand declares one. The reference tables on this page are generated from the ground-truth manifest extracted from the engine.
</Note>

## Intent primitives

The runtime solver writes these for each declared intent, scoped to the surface they were solved against:

| Variable                   | Description                                                                                      |
| -------------------------- | ------------------------------------------------------------------------------------------------ |
| `--ucs-{intent}-hue`       | OKLCH hue (0–360), constant from the brand config (or the scheme track at the current position). |
| `--ucs-{intent}-chroma`    | OKLCH chroma (0–0.4), constant from the brand config (or the scheme track).                      |
| `--ucs-{intent}-fg-l`      | Solver-written foreground lightness — APCA Lc 75 (× contrastFactor) against the context surface. |
| `--ucs-{intent}-border-l`  | Solver-written border lightness — APCA Lc 50 (× contrastFactor) against the context surface.     |
| `--ucs-{intent}-surface-l` | Solver-written accent surface lightness (deriveSurface).                                         |
| `--ucs-{intent}-pattern`   | CSS background-image pattern used in achromat mode so meaning never rides on color alone.        |

Two additional solver outputs are not per-intent:

| Variable           | Description                                                             |
| ------------------ | ----------------------------------------------------------------------- |
| `--ucs-focus-ring` | The solved focus-ring color (target Lc 60, scaled by `contrastFactor`). |
| `--ctx-surface-l`  | The lightness of the actual surface the solver resolved against.        |

Per **text role**, the solver also writes a role-specific foreground lightness — `--ucs-{intent}-fg-l-{role}` for the roles `heading`, `label`, `caption`, `code`, and `kbd` — because APCA targets depend on the size and weight a role implies.

## Baked per-mode triptychs

For the no-JS floor and native platforms, the pipeline also bakes resolved values per mode into `generated/brands/<brand>/css/tokens.{light,dark,highContrast,darkHighContrast}.gen.css`. Each intent resolves to a **surface / text / border** triple, as hex. For example, `generated/brands/aurora/booking/css/tokens.light.gen.css`:

```css theme={null}
:root {
  --ucs-surface-surface: #eff7f9;
  --ucs-surface-text: #080c0d;
  --ucs-surface-border: #6d7374;
  --ucs-brand-surface: #bf0039;
  --ucs-brand-text: #c7003f;
  --ucs-brand-border: #ff5674;
}
```

There is no `-subtle` variant and no `on-*` naming — the foreground for an intent is its `text` channel, derived by the solver, never hand-picked.

## Using color in markup

Elements opt into the cascade with `data-ucs`, and select an intent with the `data-mode` role attribute (a space-separated token list, so state tokens combine) — the full contract is on [Markup Opt-In](/markup):

```html theme={null}
<div data-ucs data-mode="brand">Solved brand surface</div>
<div data-ucs data-mode="danger">Solved danger surface</div>
```

The runtime identifies the active brand by setting `data-brand="<slug>"` on the root. There is no theme attribute — scheme is a continuous preference; see [Modes](/modes/overview).

## Cross-platform parity

The same brand data produces per-mode Swift (`SubstrateSystemTokens`, Display P3) and Kotlin/Compose artifacts with the same surface/text/border triptych, plus DTCG JSON for design tooling. See [iOS](/platforms/ios-swift) and [Android](/platforms/android-kotlin).