Dark mode

Dark mode support via light-dark() role tokens, color-scheme meta tags, and the .dark class.

Zazz enables dark mode by default. :root declares color-scheme: light dark, and semantic role tokens resolve through light-dark(). Role-based styles adapt across themes without duplicated rules.

<section class="bg-background text-foreground p-lg">
  <h2 class="text-h3">Works in both themes</h2>
  <p class="text-muted-foreground">Adapts automatically across light and dark modes.</p>
</section>

How roles resolve

Each semantic role specifies values for light and dark modes:

/* from _variables.css */
--background: light-dark(var(--white), var(--neutral-900));
--foreground: light-dark(var(--neutral-900), var(--white));
--muted-foreground: light-dark(var(--shade-600), var(--tint-600));

Use semantic roles (--primary, --background) to ensure theme compatibility. Use fixed scale steps (--primary-600) only when colors must remain static.

Theme configuration modes

1. System preference (default)

Include the <meta name="color-scheme" content="light dark"> tag in <head> so native elements match OS preferences before styles load.

2. Manual toggle with `.dark`

Add the .dark class to <html> to pin dark mode:

<html class="dark">
  ...
</html>

3. Inverted surfaces

Popovers and menus support an inverted scheme. Opt out using CSS variables or attributes:

:root {
  --use-inverted-popovers: false;
}

<div popover data-use-inverted-menu="false">...</div>

Building a theme toggle

Use an inline script in <head> to read preferences from localStorage and set the .dark class before first render:

<meta name="color-scheme" content="light dark" />
<script>
  {
    const choice = localStorage.getItem("color-scheme");
    if (choice) {
      document.querySelector('meta[name="color-scheme"]').content = choice;
      document.documentElement.classList.toggle("dark", choice === "dark");
    }
  }
</script>

Section-level color scheme

Set color-scheme on a container to force a specific mode for a subtree (such as a code block):

pre {
  color-scheme: dark;
}

Browser support

color-scheme is Baseline widely available. light-dark() is Baseline 2024 (Chrome/Edge 123, Firefox 120, Safari 17.5).

Dark mode

On this page