# Dark mode

> How the theme handles dark mode, including the toggle, persistence, and custom dark styles.

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:

```js
(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:

```css
.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:

```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.
