Theme toggle

A theme toggle lets the reader choose a light or dark colour scheme instead of following the operating system silently. The shared header partial renders it on both sites; token collections provide the mode-specific semantic colour values.

Example#

When to use#

• One toggle per site, in the page chrome — header or footer — not in page content
• Offer it once the token layer exists; a toggle without tokens hard-codes a second palette
• Not for per-page or per-component styling choices

Behaviour#

The first inline script reads the saved bhdicaire-theme choice. When no choice exists, it follows prefers-color-scheme; this runs before the stylesheet is applied to avoid a light-theme flash. The control writes an explicit light or dark choice to local storage. A later system preference change updates the site only while no explicit choice exists.

assets/css/generated/themes.css is generated from tokens/themes/light.tokens.json and tokens/themes/dark.tokens.json. Each collection overrides the same semantic colour paths under data-theme, so components keep consuming roles such as --color-paper and --color-ink rather than mode literals.

Accessibility#

• The initial state must follow the system preference; the toggle records an explicit choice and never overrides it silently
• The control must carry a screen-reader label that names the action, not just an icon
• It must be fully keyboard operable — reachable with Tab, activated with Enter or Space
• It is a native button with aria-pressed reflecting whether dark mode is active; its accessible label names the next action
• The sun and moon SVGs are decorative; the localized text label remains available to assistive technology