Lesson 22 of 23

In progress

Course progress

HTML and CSS

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-scheme with 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

HTML
Editable. Runs in your browser.





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.

HTML
Editable. Runs in your browser.





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:

  1. :root light tokens.
  2. @media (prefers-color-scheme: dark) with :root:not([data-theme="light"]) overrides.
  3. [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
HTML
Editable. Runs in your browser.





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?
Follow the system setting, and let the user override. Forcing dark on everyone ignores a preference as much as forcing light does.
Do I need a separate dark stylesheet?
No. Token overrides in the same file keep the cascade visible and avoid downloading a second file.

Progress is saved in this browser only. No account, no email.

Admin

About the author

Admin

Instructor and technical writer at tutorials.in

Writes beginner lessons for tutorials.in. Each lesson is checked against the language or tool documentation, and examples are run before publishing.

Reviewed by the editorial team before publishing. Last updated November 16, 2026.