Lesson 22 of 23
In progress
A dark theme that is actually readable
Build dark mode from tokens, follow the system setting, add a manual toggle, and keep contrast and images from turning muddy.
Dark mode is not an inverted stylesheet. A straight inversion turns shadows into glows, photos into negatives and pure white text into a headache. The work is in choosing a second set of surfaces and checking them.
What you will learn
- Follow
prefers-color-schemewith a token override. - Add a manual toggle without a flash of the wrong theme.
- Fix the contrast, image and shadow problems dark themes expose.
Tokens first, colours second
Editable. Runs in your browser.
@media (prefers-color-scheme: dark) {
:root {
–bg: #12132a;
–surface: #1b1d38;
–ink: #ececf7;
–ink-soft: #a9abcb;
–border: #2c2e4d;
–brand: #a98bf0;
}
}
body { background: var(–bg); color: var(–ink); margin: 0; padding: 24px; }
.card { background: var(–surface); border: 1px solid var(–border); padding: 20px; border-radius: 10px; }
.muted { color: var(–ink-soft); }
</style>
<div class="card">
<h2>Theme-aware card</h2>
<p class="muted">Switch your system theme and this page follows.</p>
</div>
Press Run to see the output.
Every rule reads tokens, so the media query only redefines values. The structure, spacing and components stay identical across themes.
Contrast changes in the dark
The same grey that passes on white often fails on navy. Check each pair again:
- Body text on the dark surface should still reach 4.5:1.
- Secondary text needs its own value, not an opacity applied to white.
- Brand colours usually need lightening, because a dark purple on a dark background disappears.
- Borders need to be visible without becoming bright lines.
Pure white #FFFFFF on pure black is the maximum contrast and, for long reading, harsh. Off-white text on a dark navy surface is easier on the eyes and still passes comfortably.
Avoid pure black backgrounds as well. A very dark blue or grey gives depth and lets shadows read as shadows.
Images, shadows and colour
Photographs often look too bright beside a dark surface. A slight brightness or contrast adjustment on large hero images can help, but do not filter every image; it may distort brand assets and charts.
Shadows in dark themes are weak, because there is little light to block. Use a subtle lighter border or a slightly lighter surface instead. A black shadow on a near-black background is invisible.
Charts and illustrations with hard-coded white backgrounds are a common failure. Either use transparent assets or place them on a light panel that stays light in both themes.
A manual toggle
Following the system setting is the default. A toggle lets people override it, and it should persist.
Editable. Runs in your browser.
<button id="toggle" type="button">Switch theme</button>
<p id="status">Theme: system</p>
<script>
var root = document.documentElement;
var button = document.getElementById('toggle');
var status = document.getElementById('status');
button.addEventListener('click', function () {
var next = root.getAttribute('data-theme') === 'dark' ? 'light' : 'dark';
root.setAttribute('data-theme', next);
status.textContent = 'Theme: ' + next;
});
</script>
Press Run to see the output.
The attribute wins over the media query only if the tokens are ordered so the attribute block comes later, or is more specific. A common structure is:
:rootlight tokens.@media (prefers-color-scheme: dark)with:root:not([data-theme="light"])overrides.[data-theme="dark"]explicit overrides.
That way the system preference applies until the user chooses, and the choice survives reloads if you store it.
The button should have an accessible name and a aria-pressed state if it behaves like a switch. Text such as "Switch theme" is enough for a simple toggle.
No flash of the wrong theme
If the stored preference is read in a script at the end of the body, the page paints light first and then switches, which is a visible flash. Read the preference in a small inline script in the head, before the stylesheet paints.
<script>
try {
var saved = localStorage.getItem('theme');
if (saved) document.documentElement.setAttribute('data-theme', saved);
} catch (e) {}
</script>
Keep it tiny and wrapped in try, because storage can throw in private modes. The rest of the theme logic can live in the main script.
Using filter: invert(1) on the whole page to get dark mode inverts photographs, logos and status colours, and produces unreadable images. Build a real token set instead; inversion is a demo trick, not a theme.
Add a dark token set to a page with a card, a link and secondary text. Make the link lighter in dark mode, keep body contrast above 4.5:1, and add an explicit [data-theme="dark"] block that works without the system setting.
Show solution
Editable. Runs in your browser.
<div class="card" data-theme="dark">
<h2>Dark card</h2>
<p class="soft">Secondary text uses its own token, not opacity.</p>
<p><a href="#">A lighter link for a dark surface</a></p>
</div>
Press Run to see the output.
The explicit attribute block makes the card dark regardless of the system setting, and the link token is lightened so it stays readable on navy.
Recap
- Dark mode is a second token set, not a filter or an inversion.
- Recheck contrast: text, secondary text, links and borders all change behaviour.
- Follow the system preference, allow an explicit override, and apply it before paint.
Next, you will put the whole track together in a responsive landing page.
Should dark mode be the default?
Do I need a separate dark stylesheet?
Progress is saved in this browser only. No account, no email.