Skip to content
Tutorials Center
My learning

Topics

Lesson 113 of 139 ยท Best Practices

Dark Mode

Build a dark mode with CSS using prefers-color-scheme, color-scheme, light-dark() and custom properties, then add a manual toggle that overrides the system.

Most operating systems let people choose a light or dark appearance, and many people keep dark mode on all day. Some find it easier on the eyes at night, some have light sensitivity, and some just like it. A site that blasts a white page at them feels broken.

CSS gives you everything you need to respect that choice: a media query that reports the user's preference, a property that tells the browser which schemes your page supports, a function that picks between two colors, and custom properties to tie it all together. In this lesson you will build a theme that follows the system automatically, then add a manual switch so visitors can override it.

Step 1: tell the browser with color-scheme

Before you write a single dark color, add one line:

CSS
:root {
  color-scheme: light dark;
}

color-scheme declares which color schemes your page is designed for. With light dark, the browser uses the dark versions of its own built-in styles when the user prefers dark: the default page background, the default text color, form controls, scrollbars and the spelling underline all switch. Without it, a dark page can end up with bright white text inputs and scrollbars.

You can also set it in HTML with <meta name="color-scheme" content="light dark">. The meta tag is read before your CSS downloads, which avoids a brief white flash on dark-mode devices.

color-scheme alone

If your system is in dark mode, the whole preview, including the text field, button and slider, turns dark. You wrote no colors at all.

Step 2: detect the preference with prefers-color-scheme

To change your colors, use the prefers-color-scheme media query. Its values are light and dark. The cleanest pattern defines the palette as custom properties once, then swaps only the values:

CSS
:root {
  --bg: #fbfaf7;
  --text: #1f2328;
  --muted: #5d6670;
  --accent: #b4410c;
}

@media (prefers-color-scheme: dark) {
  :root {
    --bg: #15171c;
    --text: #e8e6e1;
    --muted: #a1a9b3;
    --accent: #ff9a5c;
  }
}

body {
  background: var(--bg);
  color: var(--text);
}

Every component then uses var(--text), var(--accent) and so on. Adding dark mode later means changing one block, not hunting through hundreds of rules.

Step 3: light-dark() for shorter themes

The light-dark() function takes two colors and returns the first in a light scheme and the second in a dark one:

CSS
:root {
  color-scheme: light dark;
  --bg: light-dark(#fbfaf7, #15171c);
  --text: light-dark(#1f2328, #e8e6e1);
}

Each token now lives on one line, with both values side by side. There is a catch: light-dark() doesn't read the media query directly. It follows the used color scheme of the element, which comes from color-scheme. If you forget color-scheme: light dark, it always returns the light value. That detail is exactly what makes a manual toggle easy, as you will see next.

Support: light-dark() has worked in all major browsers since 2024. It only accepts colors, so you can't use it for images or lengths. For those, use a prefers-color-scheme media query. The Modern Color lesson covers it alongside oklch() and color-mix().

A theme built with light-dark()

Step 4: a manual toggle

A system setting isn't always what someone wants for your site. Maybe they like dark apps but find long articles easier in light mode. Good practice is a three-way choice: system (the default), light and dark.

Because light-dark() follows color-scheme, a toggle only needs to change one property. Put the choice in a data-theme attribute on the root element:

CSS
:root { color-scheme: light dark; }          /* follow the system */
:root[data-theme="light"] { color-scheme: light; }
:root[data-theme="dark"]  { color-scheme: dark; }

When data-theme is missing, the page follows the system. When it says light or dark, that value wins, and every light-dark() color updates instantly.

System, light and dark toggle

Click each button and watch the page and the text field switch. The aria-pressed attribute tells screen reader users which option is active, and the same attribute drives the highlighted style.

Remembering the choice

On a real site, save the choice so it survives a reload. Store it in localStorage and apply it before the page paints, with a tiny inline script in the <head>:

HTML
<script>
  const saved = localStorage.getItem("theme");
  if (saved === "light" || saved === "dark") {
    document.documentElement.dataset.theme = saved;
  }
</script>

Running this early avoids a flash of the wrong theme. (The live previews in this course run in a sandbox without storage, which is why the demo above forgets your choice.)

Designing a good dark theme

Dark mode is not "invert all the colors". A few habits make it look deliberate:

  • Avoid pure black and pure white. A very dark gray background with slightly off-white text is easier to read and lets shadows and borders show.
  • Show depth with lighter surfaces. Shadows barely show on dark backgrounds, so raised elements such as cards and menus usually get a slightly lighter surface instead.
  • Lower the saturation of accents. A bright brand color that works on white can glow painfully on dark gray. Pick a lighter, softer version.
  • Check contrast in both themes. Every text and background pair needs enough contrast in light and dark. The Accessible CSS lesson explains the numbers.
  • Mind images. Logos with dark text vanish on dark backgrounds. Use <picture> with a media="(prefers-color-scheme: dark)" source, or give the image a light backing.
Elevation with lighter surfaces

Each layer is a little lighter than the one beneath it. Your eye reads the lighter surfaces as closer, which does the job shadows do in a light theme.

Testing both themes

You don't have to flip your whole operating system every time you want to check the dark theme. Browser DevTools can fake the preference for one tab: in Chromium browsers, open the Rendering panel and set "Emulate CSS media feature prefers-color-scheme" to dark or light. Firefox and Safari have a similar toggle in their inspectors.

When you test, walk through the whole page rather than glancing at the home screen. Dark mode bugs hide in the corners:

  • Hard-coded colors. Any color: #333 or background: white written outside your tokens stays the same in both themes. Search your stylesheet for raw color values.
  • Icons. Inline SVG icons that use fill="currentColor" follow the text color automatically. Icons with a fixed fill don't.
  • Third-party widgets. Embedded maps, payment forms and comment systems may ignore your theme. Give them a neutral frame so the contrast isn't jarring.
  • Focus rings and borders. A dark blue focus outline that looks great on white can disappear on a dark background. Define focus colors as tokens too.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does color-scheme: light dark on :root do by itself?

    color-scheme tells the browser which schemes the page supports, so its default background, text and controls follow the user's preference.
  2. 2. Why does light-dark() always return its first color on some pages?

    light-dark() follows the element's used color scheme, which comes from color-scheme. Without it, the scheme is light.
  3. 3. Which CSS makes a data-theme="dark" attribute force dark mode in a light-dark() theme?

    Setting color-scheme to dark on the root switches every light-dark() color to its second value.
  4. 4. In a dark theme, how should a raised card usually differ from the page behind it?

    Shadows are hard to see on dark backgrounds, so lighter surfaces are used to show elevation.

Summary

  • color-scheme: light dark makes the browser's own UI follow the user's preference.
  • @media (prefers-color-scheme: dark) lets you swap custom property values for dark mode.
  • light-dark(light, dark) picks a color based on the element's used color scheme.
  • A manual toggle can simply set color-scheme through a data-theme attribute on the root.
  • Offer system, light and dark; save the choice and apply it early to avoid a flash.
  • Design dark themes with dark grays, lighter raised surfaces, softer accents and checked contrast.

Next: Accessible CSS, where you will make sure your styles work for everyone, including keyboard users, screen reader users and people who zoom.