Skip to the content

Dark Mode

Dark mode and the accessibility color modes belong to the engine. You declare a mode preference; the design system derives the dark theme, writes the <html> attributes, persists the choice and renders the first paint without a flash.
Theming

The rule

  • Pass one light-mode colors config and a mode preference to ApollionProvider. 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
Scrolls sideways inside the table. The page does not.

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 canvas
dark
Paper over canvas

The 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 colors once; keep lightTheme/darkTheme for a genuinely non-canonical dark design.
  • bgColor="#fff" on a card → bgColor="surface.paper", which follows the mode.
  • Several providers writing to <html> → pass syncDocument={false} to every nested provider.

See also