Skip to the content

Theming, Config-First

Apollion themes are derived, not hand-painted. You supply a handful of brand seed colors; the engine derives every palette, both modes, both surfaces and three densities — the same way at runtime and at build time.
Theming

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
Scrolls sideways inside the table. The page does not.

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 deepLight to change the page background → seed baseLight.

See also