How it works
Components know only the names: background: var(--raised), color: var(--ink-3). The values live in one file, in
three places: the light ones in :root, the dark ones for the toggle and for the system theme. The theme changes by
substituting other values under the same names, without touching the components’ CSS.
The file
:root {
color-scheme: light;
--ground: #f4f2ee;
--raised: #ffffff;
--sunken: #f0ece5;
--ink: #1a1816;
--ink-2: #4a4540;
--ink-3: #66605a;
--line: #e3ded5;
--line-strong: #d3ccc0;
}Names by role: the page background, a card, a field; three levels of text; lines. Compute pairs, not colors: --ink-3 on --ground is 5.55:1, on --raised 6.20:1, on --sunken 5.27:1, so a caption passes AA on any of the site’s backgrounds. color-scheme: light tells the browser its fields and scrollbars are light.
default:color-scheme normal
:root {
--accent: #cc3f23;
--accent-hover: #b73519;
--accent-ink: #bc3a1f;
--accent-soft: rgba(204, 63, 35, 0.09);
--on-accent: #ffffff;
}One accent, five roles. --accent is the button fill; white text on it is 4.88:1. The same color as text on the #f4f2ee background is 4.37:1, short of AA, so links get their own slightly darker --accent-ink: 4.99:1. --accent-soft is a 9% tint, --on-accent the text on the fill: in dark mode it turns dark.
:root {
--ok: #2e7d4f;
--ok-soft: rgba(46, 125, 79, 0.1);
--warn: #9a4e0a;
--warn-soft: rgba(240, 160, 40, 0.14);
--on-warn: #ffffff;
}States. --ok on the background is 4.51:1, a hundredth above the threshold; --warn is 5.42:1, and white text on it 6.06:1. The pale -soft ones are tints under blocks; text on them stays the regular --ink.
:root[data-theme='dark'] {
color-scheme: dark;
--ground: #131210;
--raised: #1f1d1a;
--ink: #f2eee8;
--ink-3: #a39b90;
--accent: #ff7a55;
--accent-ink: #ff9473;
--on-accent: #1a0d08;
/* … the remaining tokens — same names */
}The toggle’s choice is a data-theme attribute on <html>. Same names, values picked anew: the background isn’t black and the text isn’t white — 16.2:1, captions #a39b90 at 6.82:1. The old accent #cc3f23 would give 3.84:1 on the dark background; the new #ff7a55 gives 7.28:1. White text on it is 2.57:1, so --on-accent is dark: 7.39:1.
@media (prefers-color-scheme: dark) {
:root:not([data-theme='light']) {
color-scheme: dark;
--ground: #131210;
/* … the same dark set in full */
}
}The system theme — until light is chosen with the toggle. Without :not([data-theme='light']) a dark system would override the choice. The cost: the dark set is written in the file twice, and a dark color is edited in two places.
:root {
color-scheme: light dark;
--ground: light-dark(#f4f2ee, #131210);
--ink: light-dark(#1a1816, #f2eee8);
--accent: light-dark(#cc3f23, #ff7a55);
}
:root[data-theme='light'] {
color-scheme: light;
}
:root[data-theme='dark'] {
color-scheme: dark;
}A version without the repetition: light-dark() takes the first value with a light scheme and the second with a dark one, and color-scheme sets the scheme — by system or by toggle. Each color is one line; Chrome 123, Firefox 120, Safari 17.5. This site doesn’t use it: some dark values aren’t colors. Shadows in dark mode have a different shape, a 0 0 0 1px ring instead of a soft shadow, and --when-dark switches display; light-dark() chooses only between colors or images.
The choice — before the first paint
<script>
try {
const theme = localStorage.getItem('theme');
if (theme === 'light' || theme === 'dark') document.documentElement.dataset.theme = theme;
} catch {}
</script>
The script sits in <head> and is a plain one — not a module and without defer: the browser runs it while parsing
<head>, and the page paints in the chosen theme right away. In Astro such a script is written with is:inline;
otherwise Astro bundles it into a module, and it runs after the paint. The try covers the case where the site isn’t
allowed to store data: then accessing localStorage throws. The toggle writes the choice to localStorage.theme and
sets the same attribute; without a choice there’s no attribute, and the system decides the theme.
The color of the browser’s bar on a phone is set by HTML, which CSS variables don’t reach — these are the site’s only hex values outside the tokens file:
<meta name="theme-color" media="(prefers-color-scheme: light)" content="#F4F2EE" />
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="#131210" />
How to check
- DevTools, the Rendering panel, Emulate CSS media feature prefers-color-scheme: dark — the site goes dark without the toggle. Choose light with the toggle — the site stays light even under the dark emulation.
- Check the contrast of every text token in both themes with the DevTools picker (Text contrast).
Find hex values outside the tokens file like this — here only the two theme-color lines turn up; anything else would
be a color bypassing the palette:
grep -rnE '#[0-9a-fA-F]{3,8}' src --include=*.css --include=*.astro | grep -v tokens.css
If it doesn’t work
The theme switched, but some elements stayed light
- Cause
- A component has a color written as a hex value instead of a token, and the dark set doesn’t change it.
- Fix
- Find hex values outside the tokens file —
grep -rnE '#[0-9a-fA-F]{3,8}' src --include=*.css --include=*.astro | grep -v tokens.css— and replace them withvar(--…).
Chose the light theme, and with a dark system the site is still dark
- Cause
- The dark set in
@media (prefers-color-scheme: dark)sits on a bare:rootand overrides the toggle’s choice. - Fix
- Use the condition
:root:not([data-theme='light']): the system theme applies until light is chosen.
Dark mode flashes light on every navigation
- Cause
- The choice from
localStorageis read by a script at the end of<body>, withdeferor as a module — the page manages to paint light first. - Fix
- Put the script in
<head>, a plain one, withoutdeferortype=module: it runs before the first paint. In Astro,<script is:inline>.
light-dark() always returns the light value
- Cause
- The element has no
color-schemethat includesdark: the function looks at that, not at the system theme directly. - Fix
color-scheme: light darkon:root; the toggle switchescolor-schemetolightordark.