The usual way to support system-driven dark mode alongside a manual theme toggle is to redeclare every custom property twice — once inside a prefers-color-scheme media query and once under a theme class. The goal here is to drop that duplication, in keeping with DRY (Don't Repeat Yourself) thinking, and to do it with a single pair of switch variables rather than a long list.

The core trick

Lea Verou's --var: ; technique — where an empty custom property value is itself meaningful — makes this possible. Rather than nesting var(--light-value, var(--dark-value)), we place the two values side by side. The classic repeating pattern looks like this:

:root {
  --background: #fff;
  --text-color: #0f1031;
  /* etc. */
}

@media (prefers-color-scheme: dark) {
  :root {
    --background: #0f1031;
    --text-color: #fff;
    /* etc. */
  }
}

At a small scale the cost seems tolerable, but a palette with dozens of custom properties forces dozens of repeated declarations. The alternative is a single definition per color plus two mode flags:

--color: var(--light, orchid) var(--dark, rebeccapurple);

The mechanism depends on the fallback: with --light set to initial, the fallback (orchid) wins, which requires --dark to hold a whitespace character — a valid value. The computed result is then:

--color: orchid  ; /* Note the additional whitespace */

Flipping the flags gives the inverse case and a different computed value:

--color:   rebeccapurple; /* Again, note the whitespace */

Wiring up the contexts

The --light and --dark properties still have to be decided by context, of which there are three: a system light preference, a system dark preference, and an explicit user toggle. Lea's proposed on/off shorthand constants make each case easier to read at a glance:

:root { 
  /* Thanks Lea Verou! */
  --ON: initial;
  --OFF: ;
}

/* Light theme is on by default */
.theme-default,
.theme-light {
  --light: var(--ON);
  --dark: var(--OFF);
}

/* Dark theme is off by default */
.theme-dark {
  --light: var(--OFF);
  --dark: var(--ON);
}

/* If user prefers dark, then that's what they'll get */
@media (prefers-color-scheme: dark) {
  .theme-default {
    --light: var(--OFF);
    --dark: var(--ON);
  }
}

Every theme property can then be declared once, with no repetition. The examples place the theme-* classes on the html element so :root can serve as the selector, though declaring them on body works equally well if that better suits the cascade:

:root {
  --text: var(--light, black) var(--dark, white);
  --bg: var(--light, orchid) var(--dark, rebeccapurple);
}

Consumers call var() with a built-in fallback as a safety measure:

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

The payoff: two properties get defined and switched, while all the others are set once on :root.

Cleaner syntax with Sass

Seen out of context, a declaration like --text: light-dark( #112233, #c0ffee ); reads oddly, since a color is one value, not two. To smooth that over, a preprocessor function can generate the syntax; with Sass, the only part that needs editing is the actual custom property declaration. A light-dark function returns the CSS for you:

@function light-dark($light, $dark) {
  @return var(--light, #{ $light }) var(--dark, #{ $dark });
}

Call sites look like this:

:root {
   --text: #{ light-dark(black, white) };
   --bg: #{ light-dark(orchid, rebeccapurple) };
   --accent: #{ light-dark(#6d386b, #b399cc) };
}

The interpolation delimiters #{ … } are mandatory: without them Sass treats the result as a plain vanilla CSS function and outputs it unchanged. Exactly how much syntax sugar to build is a matter of taste.

Beyond two themes

More than two modes is possible, at the price of rapidly growing complexity. Each additional theme adds another set of ON/OFF variables and one more value in the list:

.theme-pride {
  --light: var(--OFF);
  --dark: var(--OFF);
  --pride: var(--ON);
}

:root {
  --text:
    var(--light, black)
    var(--dark, white)
    var(--pride, #ff8c00)
  ; /* Line breaks are absolutely valid */

  /* Other variables to declare… */
}

The approach is unambiguously hacky and would be a natural fit for proper CSS booleans, should they ever land. Until then it trades verbosity for a single point of change per color token.

CSS-Tricks star logo