Theming with CSS Variables: OS Dark Mode + Manual Override

intermediate

By FrontendAtlas Team · Updated Jan 30, 2026

Create a themeable panel using CSS custom properties. Define light defaults on :root, redefine the same tokens for OS dark mode via @media (prefers-color-scheme: dark), then add a manual html.theme-dark override after the media query so it wins by source order. The panel and button should consume theme tokens only for colors and shadow values.

What you'll practice:

CSS custom properties as live theme tokens
Semantic token naming for background, text, surface, border, accent, contrast, and shadow
prefers-color-scheme for OS-level dark mode
Cascade/source order for predictable theme overrides
Manual root-level theme overrides with html.theme-dark

Requirements

Define light theme tokens on :root: --bg, --text, --surface, --accent, --border, --accent-contrast, and --panel-shadow.
Define dark values for the same tokens inside @media (prefers-color-scheme: dark).
Define html.theme-dark after the media query and repeat the dark token values there.
Use token references inside .panel and .btn; do not place literal color values in those component declarations.
Use --accent-contrast for button text so the accent background has an explicit readable foreground token.

Acceptance criteria

No hard-coded component colors or colored shadows remain inside .panel or .btn.
Dark OS preference switches the page, panel, border, accent, contrast, and panel shadow through variables.
Adding class="theme-dark" to html forces the dark token set even when the OS preference is light.
Button text contrast is handled through --accent-contrast rather than a literal color.

Expected behavior

Your CSS theme should:

Render a light theme by default from :root tokens.
Switch to dark values when the system prefers a dark color scheme.
Let html.theme-dark win because it is declared after the media query.
Keep component styles stable while only token values change between themes.

Implementation notes

Keep the same variable names across :root, @media (prefers-color-scheme: dark), and html.theme-dark.
Put html.theme-dark after the media query; the point is cascade order, not higher specificity.
Treat --panel-shadow as part of the theme token set because shadows include color.
Use rgb(... / alpha) or another color syntax inside token definitions, not inside constrained component declarations.

Common mistakes

Placing html.theme-dark before the media query so the OS preference can override the manual class.
Changing body colors while .panel or .btn keep hard-coded backgrounds, borders, text colors, or shadows.
Forgetting --accent-contrast and making button text unreadable in one theme.
Increasing selector specificity instead of solving the override with source order.

Interview explanation

This pattern matters because real UI systems need components that consume semantic tokens instead of owning theme colors directly. CSS custom properties let a design system swap values at runtime without recompiling styles or rewriting every component. prefers-color-scheme respects the user's OS preference, while a root class gives product UI a manual override. The interview signal is understanding cascade order, token completeness, and contrast instead of only toggling a body background.

Testing checklist

Test with a light OS preference and confirm :root values are used.
Test with a dark OS preference and confirm @media (prefers-color-scheme: dark) values are used.
Add html.theme-dark manually and confirm it wins over the OS preference.
Inspect computed styles for .panel and .btn to verify variables resolve to the final colors and shadow.

<html> HTML

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Theme Demo</title>
</head>
<body>
  <!-- To test the manual override, change <html lang="en"> to <html class="theme-dark" lang="en">. -->
  <div class="panel">
    <h2>Theme Demo</h2>
    <p>This panel and button read colors from CSS variables.</p>
    <button class="btn" type="button" aria-label="Static themed button sample">Tokenized button</button>
  </div>
</body>
</html>

# CSS

/* TASK
  1) Define variables on :root (light defaults):
     --bg, --text, --surface, --accent, --border, --accent-contrast, --panel-shadow
  2) OS dark mode:
     @media (prefers-color-scheme: dark) {
  :root {
  ...same vars, dark values...
}
}
3) Manual override:
     html.theme-dark {
  ...same vars, dark values...
}
IMPORTANT: place html.theme-dark AFTER the media query so it always wins.
     Test it by editing the opening <html> tag in the HTML panel.
  Constraint:
    - .panel and .btn must use ONLY variables for colors and colored shadow values.
*/
/* Base page styles using variables (you will define them) */
html, body {
  height: 100%;
}
body {
  font-family: system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif;
  margin: 0;
  line-height: 1.6;
  background: var(--bg);
  color: var(--text);
  display: grid;
  place-items: center;
  padding: 2rem;
}
.panel {
  background: var(--surface);
  color: var(--text);
  border: 1px solid var(--border);
  border-radius: 12px;
  padding: 1.25rem;
  box-shadow: var(--panel-shadow);
  max-width: 520px;
}
.btn {
  background: var(--accent);
  color: var(--accent-contrast);
  border: 0;
  padding: .5rem .9rem;
  border-radius: .6rem;
  font-weight: 600;
}

Live preview updates as you type

Building preview…