Theming, Config-First
The rule
Every resolved theme is one cell of a product of four axes:
Axis | Values | Controls |
|---|---|---|
brand | your keys ( default, acme, …) | which seeds derive the palette |
mode | light / dark | the seed swap and the surface ladder — Dark Mode |
surface | positive / negative | subtree inversion — Surface Inversion |
dimension | compact / normal / spacious | spacing density — Spacing & Dimensions |
One brand gives twelve variants. Text size (textSize) and weight (typeWeight) are separate settings
that change only font tokens — see Text Size. Brand, surface, dimension and
typeWeight are the author's choice; mode, the accessibility preset and text size are the reader's.
How it works
Runtime. Pass seeds to ApollionProvider (or build a theme with createTheme). Omitted slots keep
the stock values.
import { ApollionProvider } from '@apollion-dsi/core/themes';
const colors = {
main: '#003750',
primary: '#32AFDC',
success: '#2CB567',
danger: '#E12712',
baseLight: '#FCFCFC',
baseDark: '#26292E',
};
<ApollionProvider colors={colors} defaultMode="system" dimension="normal" typeWeight="regular">
<App />
</ApollionProvider>;baseLight is the light page canvas (surface.canvas); baseDark is the primary ink and becomes the dark
canvas after the mode swap. deepLight and deepDark are the anchors the color ramps mix toward, not
grounds. To retint the page, seed baseLight.
typeWeight (light, regular, stronger) moves the whole weight ladder: regular is 300/400/600/900,
light is 300/300/400/600, stronger is 400/600/700/900. A call-site fontWeight still wins.
Build time. apollion.config.mjs expresses the same seeds as data for CSS, JSON, TypeScript and
Tailwind output — see Build CLI. Runtime and build share one derivation, pinned
by a parity test suite, so the same seed produces byte-identical values.
Guarantees. Every named palette emits an onLight ink with at least 4.5:1 contrast against its
light fill. Dark mode runs through the same engine, so state floors and tonal pairs resolve on dark by
construction. The token build is deterministic and fingerprinted in a manifest.
Breakpoints. The viewport scale (xs 0, sm 575, md 767, lg 990, xl 1200 px) is part of the
token contract: the build emits it as breakpoint.* tokens, informational --apollion-breakpoint-*
variables and Tailwind screens. Bands are half-open and ascend by min-width.
Pitfalls
- Hand-building a second palette for dark mode → seed one light config; the engine derives dark.
- Overriding a derived color with a literal → the engine applies it verbatim and skips its contrast guarantee for that slot; prefer a Foundation alias.
- Seeding
deepLightto change the page background → seedbaseLight.