Class first, then system

An explicit dark class wins; with none, follow the system.

Adam Wathan@adamwathan
Dark mode variant that respects the `dark` class if present, but just relies on the media query if not 🤔 Kinda wish this was the default in Tailwind, maybe I'll tag v5 today.
Nov 18, 2025View on X ↗

Demo scope: only the two cards, not this site's theme.

Setting

Who wins, class or system

Pick Light or Dark. Only one card obeys.

Media query onlyBad
Class, then systemGood
.card { --bg: #fff; --fg: #0a0a0a; }

/* 1. an explicit class always wins */
.card[data-mode="dark"] { --bg: #171717; --fg: #fafafa; }

/* 2. no class: follow the system */
@media (prefers-color-scheme: dark) {
  .card:not([data-mode]) { --bg: #171717; --fg: #fafafa; }
}

Why it matters, pros and cons

Why it matters

A saved choice is more specific than an OS default. The class states it; the media query is the fallback.

Pros

  • The visitor's toggle always beats the OS setting.
  • With no choice made, the page still follows the system.
  • One stylesheet covers both cases, with no flash of the wrong theme.

Cons

  • Dark values are written twice unless a tool generates them.
  • Needs a small script to store the choice and set the class early.
  • If you never offer a toggle, the media query alone is enough.