Core Concepts Behind Substrate's Token Architecture

​

Computed vs. Static Tokens

• Solver inputs — each intent’s hue and chroma, with lightness deliberately absent (it stays solver-owned).
• Style descriptors — per-component styling rules expressed as data, interpreted by a runtime kernel on each platform.
• Baked per-mode token files — static snapshots (light, dark, highContrast, darkHighContrast) for platforms and moments where the runtime hasn’t run yet.

​

Color Intent

intents:
  brand:
    hue: 277        # Acme Indigo
    chroma: 0.268
  neutral:
    hue: 251        # cool-tinted neutrals
    chroma: 0.012
  danger:
    hue: 11
    chroma: 0.228
  # Custom intents are first-class — same treatment as the system names
  acme-cyan:
    hue: 228
    chroma: 0.147

intents:
  neutral:
    hue: 210
    chroma: 0.02
    scheme-end: { hue: 220, chroma: 0.04 }  # slightly richer chroma at the dark end

​

Why OKLCH?

• L — Lightness (0–1), perceptually uniform
• C — Chroma (0–~0.4), the intensity or colorfulness
• H — Hue (0–360°), the color angle

​

APCA Contrast Solving

1. Each intent’s scheme track is evaluated at the current scheme position, yielding its hue and chroma.
2. Two user-compensation transforms run first — warmth, then cvd — so color is adjusted for the user before any contrast math.
3. The solver takes the actual surface the content sits on (exposed to CSS as --ctx-surface-l) and binary-searches the OKLCH lightness that achieves the target Lc against it.
4. The targets come from a fixed, named policy: foreground Lc 75, border Lc 50, focus ring Lc 60, each scaled by the user’s continuous contrastFactor (bounded per brand by flexibility.contrast).
5. The solved values are written as --ucs-{intent}-{hue,chroma,fg-l,border-l,surface-l} primitives; the generated CSS composes final colors from them with calc().

​

Modes

light:            { scheme: 0,    contrastFactor: 1.0 }
dark:             { scheme: 1,    contrastFactor: 1.0 }
dimmed:           { scheme: 0.65, contrastFactor: 0.95 }
highContrast:     { scheme: 0,    contrastFactor: 1.3 }
darkHighContrast: { scheme: 1,    contrastFactor: 1.3 }

​

Cascading Inheritance

name: Aurora Airways - Rewards

intents:
  brand:
    chroma: 0.220        # hue: 15 is inherited from ../config.global.yaml
  tier-gold:
    hue: 51
    chroma: 0.116

typography:
  heading-family: "'Aurora Display', Verdana, system-ui, sans-serif"

• Updating the family’s shared config propagates to every sub-brand on the next generation.
• Adding an intent in config.global.yaml gives every sub-brand that intent automatically.
• A new sub-brand requires only a handful of lines to bootstrap a full, accessible token set — with the same solver guarantees as every other brand in the system.

​

Platform Output

:root {
  --effective-ratio: calc(1 + (var(--scale-ratio) - 1) * var(--type-scale-factor));
  --radius: calc(var(--radius-base) * var(--density));
  --duration: calc(var(--duration-base) * var(--motion-factor));
}

.sub-badge[data-ucs] {
  /* 8px at default density=1, scale=1, space-unit=4 */
  --surface-padding-x: calc(var(--density) * var(--scale) * var(--space-unit) * 2);
}

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

import SwiftUI

public struct SubstrateSystemTokenSet {
    public let surface: Color
    public let text: Color
    public let border: Color
}

public enum SubstrateSystemTokens {
    public static let surface = SubstrateSystemTokenSet(
        surface: Color(.displayP3, red: 0.9588, green: 0.9594, blue: 0.9728, opacity: 1.0000),
        text: Color(.displayP3, red: 0.0424, green: 0.0427, blue: 0.0511, opacity: 1.0000),
        border: Color(.displayP3, red: 0.4431, green: 0.4436, blue: 0.4553, opacity: 1.0000)
    )
}

import SubstrateKernel

public enum BadgeComponent {
    public static let style = ComponentStyleDescriptor(
        component: "badge",
        nodes: [
            StyleNode(scope: .component, properties: [
                StyleProperty(name: "padding-x", value: .spatial(2)),
                StyleProperty(name: "shape", value: .radiusCapsule),
            ]),
        ]
    )
}

import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.colorspace.ColorSpaces

data class SubstrateSystemTokenSet(
    val surface: Color,
    val text: Color,
    val border: Color,
)

object SubstrateSystemTokens {
    val surface = SubstrateSystemTokenSet(
        surface = Color(red = 0.9588f, green = 0.9594f, blue = 0.9728f, alpha = 1f, colorSpace = ColorSpaces.DisplayP3),
        text = Color(red = 0.0424f, green = 0.0427f, blue = 0.0511f, alpha = 1f, colorSpace = ColorSpaces.DisplayP3),
        border = Color(red = 0.4431f, green = 0.4436f, blue = 0.4553f, alpha = 1f, colorSpace = ColorSpaces.DisplayP3),
    )
}