Color Token Reference

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 for the model.

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.

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:

: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:

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

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 and Android.

​Intent primitives

​Baked per-mode triptychs

​Using color in markup

​Cross-platform parity

Intent primitives

Baked per-mode triptychs

Using color in markup

Cross-platform parity