Dark Mode
<html> attributes, persists the choice and renders the
first paint without a flash.The rule
- Pass one light-mode
colorsconfig and a mode preference toApollionProvider. Never hand-build a dark palette. - Style with the ladder tokens —
surface.*,ink.*,edge.*,wash.*— so every ground reads the same in both modes. - With server rendering or persistence, render the pre-paint script and pass
initialMode.
Two independent axes compose freely:
Axis | Values | Changes |
|---|---|---|
mode | light, dark, system | polarity: the baseLight↔baseDark and deepLight↔deepDark swap and the ladder |
a11y | null, grayscale, high-contrast, colorblind | the seeds, remapped before light and dark are derived |
useApollionTheme() returns mode (the preference), resolvedMode (what renders), setMode, a11y and
setA11y.
How it works
The surface ladder. From the contrast anchors alone, the engine derives grounds (surface.canvas,
sunken, paper, raised, overlay, scrim), inks (ink.primary, secondary, muted, disabled),
edges (hairline, border, strong) and washes (hover, pressed, selected). Paper is lighter than
the canvas in both modes, every ink clears WCAG AA and the APCA tiers over the paper, and floors keep the
dark canvas off pure black.
light
Paper over canvasdark
Paper over canvasThe flip. Every color is a light-dark() pair, and the provider writes data-apollion-mode and
color-scheme on <html>. A mode change is an attribute change: same class names, no React re-render.
Each painted ground also publishes --apollion-on-ground-* variables, so text inside
<Paper bgColor="main"> resolves its ink against main. For a ground the design system did not paint,
such as a photo, wrap it in <Ground bg="#0b2a3a"> from @apollion-dsi/core/themes/ground.
Persistence and SSR. persist="localStorage" or "cookie" stores the preference under
apollion-mode (the preset under apollion-mode-a11y). initialMode is the hydration contract: the
server and the first client render use it, and the stored preference applies before paint.
In a Next.js App Router layout, read the cookie on the server and pass both values:
import { headers } from 'next/headers';
import { readModeFromCookie } from '@apollion-dsi/core/themes/mode';
export async function readMode() {
const mode = readModeFromCookie((await headers()).get('cookie')) ?? 'system';
return { defaultMode: mode, initialMode: mode === 'dark' ? 'dark' : 'light' } as const;
}
// <head>: <ApollionModeScript persist="cookie" defaultMode="system" />
// <body>: <ApollionProvider {...await readMode()} persist="cookie">{children}</ApollionProvider>Without React components in the head, inline getModeScript({ persist: 'localStorage' }) instead. Static
pages link the tokens output.cssModes stylesheet, which carries both modes behind the same attribute.
Pitfalls
- A second, hand-tuned dark theme for a routine rebrand → seed
colorsonce; keeplightTheme/darkThemefor a genuinely non-canonical dark design. bgColor="#fff"on a card →bgColor="surface.paper", which follows the mode.- Several providers writing to
<html>→ passsyncDocument={false}to every nested provider.