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.