Web: The Generated CSS Cascade and the Runtime Solver

Substrate’s web output has two layers that work together. The generated CSS establishes a cascade built entirely from continuous scalars composed with calc(), and the JavaScript runtime solves APCA contrast against the actual surface and writes the results back as custom properties. APCA attribution and use restrictions: see About APCA.

A JavaScript runtime is required. The static CSS includes a baked no-JS snapshot so a server-rendered page paints accessibly at first paint, but that snapshot is an accessible floor covering the page surface under four preset combinations. Continuous scheme positions, CVD compensation, warmth, density, and scoped surfaces all need the runtime.

Getting the CSS

The pipeline writes into generated/, with globally shared artifacts under generated/global/ and per-brand artifacts under generated/brands/<brand>/<sub-brand>/. Load the barrel once at your app entry — it pulls in the layer definitions, the token layer, the @property declarations, the role selectors, every brand’s CSS, the component styles, and the CVD pattern overlays:

import '@substrate/generated/global/css/index.gen.css';
import { initializeSubstrate } from '@substrate/engine';

const { brand, preferences } = initializeSubstrate();

initializeSubstrate() defaults to the first registry brand and defaultPreferences(), accepts { brand, preferences } overrides, and is exactly equivalent to the lower-level sequence:

import {
  syncBrandToCssVars, syncPrefsToCssVars, updateAllVars,
  defaultPreferences, BRAND_REGISTRY,
} from '@substrate/engine';

const brand = BRAND_REGISTRY[0];
const prefs = defaultPreferences();

syncBrandToCssVars(brand);   // data-brand + typography, shape, motion, spacing vars
syncPrefsToCssVars(prefs);   // --scheme, --contrast-factor, --density, …
updateAllVars(brand, prefs); // solves APCA, writes per-intent --ucs-* to :root

Any preference change repeats the last two sync calls. The substrate setup path generates this module for you as src/substrate.setup.ts. Full detail on the call sequence and the alias contract is on the Runtime & Imports page; nested surfaces need the Surface component.

Using it in your CSS

Opt an element into the cascade with data-ucs and give it a role:

<div data-ucs data-mode="brand">Solved brand surface</div>
<div data-ucs data-mode="danger">Solved danger surface</div>

Then compose colors from the primitives the same way the generated CSS does:

.my-panel[data-ucs] {
  background: oklch(var(--intent-surface-l) var(--intent-chroma) var(--intent-hue));
  color:      oklch(var(--intent-fg-l) var(--intent-chroma) var(--intent-hue));
  border:     1px solid oklch(var(--intent-border-l) var(--intent-chroma) var(--intent-hue));
  border-radius: var(--radius);
  transition: background var(--duration);
}

Because you compose from primitives rather than hard-coded colors, the same rule tracks every preference change automatically — scheme, contrast, CVD, and warmth all flow through without a second declaration.

Other output targets

CSS is one target among several. The same brand model is emitted as DTCG JSON (the W3C design-token format, for Tokens Studio and Style Dictionary), Swift, Kotlin/Compose, React Native, Xcode asset catalogs, and JSON conformance vectors used to hold the native kernel ports to the TypeScript kernel’s behavior.

npm run generate:tokens:dtcg
npm run generate:tokens:swift
npm run generate:tokens:compose

Runtime & Imports

The runtime call sequence and the three import aliases.

Surface Component

Re-solving contrast against a nested surface’s own background.

iOS / Swift

Per-mode Display P3 token files and the SubstrateKernel package.

Get Started

Integrate

Tooling

Brand Config

Component Config

Modes & Accessibility

Platforms

Web: The Generated CSS Cascade and the Runtime Solver

Getting the CSS

Using it in your CSS

Other output targets

Runtime & Imports

Surface Component

iOS / Swift

​Getting the CSS

​Using it in your CSS

​Other output targets

Runtime & Imports

Surface Component

iOS / Swift

Getting the CSS

Using it in your CSS

Other output targets