Theme It
Own the configuration layer: brand seeds, the four-axis variant model, dark mode, density, and the accessibility contract the engine guarantees so you don't have to re-derive it by hand.
1. Seeds in, a full theme out
You supply ~14 brand colors; the engine derives palettes, ramps and both modes deterministically.
- Theming, Config-First — the four axes (brand × mode × surface × dimension) and where each is set.
- Create Theme — the full
createThemeruntime API. - Brand examples — two complete reference configs to start from.
2. Surface and dark mode
Containers declare what kind of surface they're on; children invert automatically. Dark mode is an engine concern: a canonical seed swap plus a mode-aware surface ladder, persisted and server-rendered without a flash — not a second hand-built palette.
- Dark Mode Engine —
mode×a11yaxes, the surface ladder, persistence, SSR. - Surface Inversion — the
surface="positive"/"negative"primitive. - Dimensions —
compact/normal/spaciousdensity and where it multiplies spacing.
3. The accessibility contract
Every named palette ships a WCAG AA tonal pair by construction — not an audit pass you run afterward.
- Semantic & Foundation Tokens — where the guarantee lives in the token graph.
- Accessibility Presets — high-contrast (AAA) and colorblind-safe (Okabe–Ito) palettes as drop-in alternatives.
4. Static output, when you need it
For CI artifacts, SSG output, or non-React consumers, the same seeds build
to CSS/JSON/TS through apollion-tokens — byte-identical to what
createTheme resolves at runtime.
- Build CLI — the
apollion-tokens buildflags and the variant matrix. - Output formats — CSS custom properties, TS literals, DTCG 2025.10 + Resolver, and the
Design.mdAI-context emission.
Responsible overrides
Every derived value accepts a per-slot override when you have a real reason — but it's an escape hatch, not the default. The engine applies it verbatim, including skipping the guarantees above for that slot. Prefer a new Foundation alias over reaching for a literal color; see Semantic & Foundation Tokens.
Common questions → where to go
| "How do I…" | Go to |
|---|---|
| create my brand's theme? | Create Theme |
| get real dark mode, not a placeholder? | Theming, Config-First |
| guarantee AA contrast on my own palette? | Semantic & Foundation Tokens |
| ship tokens without React? | Output formats |
| override one color without losing the rest? | Theming, Config-First |
Next step
Need to touch the engine itself — a new renderer, a factory, an SSR path? Move to Build On It.