Skip to main content

Dark mode

The theme ships with full dark mode support. Light mode is the default, and users can toggle between modes using the native button in the footer.

How it works

Dark mode is driven by a data-theme attribute on the <html> element. When data-theme="dark" is set, the theme’s tokens.css switches color-scheme to dark, and every colour token declared with light-dark() resolves to its dark value — darker backgrounds, lighter text, and adjusted accent opacities.

The toggle state is persisted in localStorage under the key at-theme. On subsequent visits, the stored preference is applied before the page renders.

Flash prevention

BaseLayout includes an inline script in the <head> that runs before any content is painted:

(function () {
  var t =
    localStorage.getItem("at-theme") ||
    (matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
  document.documentElement.dataset.theme = t;
})();

This reads the stored preference, falling back to prefers-color-scheme, and sets data-theme immediately. Because the script is inline and synchronous, the browser never flashes the wrong theme.

Theme toggle

The footer renders a progressively enhanced button that switches between light and dark modes, included automatically with BaseLayout. It updates both the data-theme attribute and the localStorage value when clicked.

Adding custom dark mode styles

If you’re writing custom CSS that needs to adapt for dark mode, target the [data-theme="dark"] selector:

.my-card {
  background: var(--at-bg-elevated);
  border: 1px solid var(--at-border);
}

[data-theme="dark"] .my-card {
  box-shadow: 0 2px 8px rgba(0 0 0 / 40%);
}

Where possible, use the semantic colour tokens (--at-bg, --at-text, --at-border, and so on) rather than hard-coded colours — they already adapt between modes, so a separate dark mode rule is often unnecessary.

Forcing a specific theme

If your site should only use one mode, you can set the data-theme attribute directly and hide the toggle. Add this to your override CSS:

/* Force light mode */
:root {
  color-scheme: light;
}

/* Hide the theme toggle button */
.at-footer-theme-toggle {
  display: none;
}

Prefer <BaseLayout colorScheme="light"> or "dark": that fixes the data-theme value, skips preference detection, and tells the footer not to render the toggle. The CSS override above is useful only in a layout that controls the document shell itself.