Supporting System Dark Mode with prefers-color-scheme

With macOS, Windows, iOS, and Android introducing system-wide dark appearance settings, modern browsers now expose the user's operating system preference directly to stylesheets through the @media (prefers-color-scheme: dark) media query.

When paired with CSS Custom Properties, you can automatically respect the user's system theme on first visit without flashing a bright white screen while waiting for JavaScript to load.

Example #

@media (prefers-color-scheme: dark) {
  :root {
    --page-bg: #082840;
    --page-text: #f2fbf9;
  }
}

Input : Light-mode default CSS tokens
Output : Automatic dark-mode adaptation that respects OS preferences and reduced-contrast comfort.

Implementation #

/* 1. Default Light Mode Tokens */
:root {
  --bg-page: #ffffff;
  --bg-card: #ffffff;
  --border-subtle: #dedede;
  --text-heading: #082840;
  --text-body: #333333;
  --accent-link: #04ae92;
}

/* 2. Automatic OS Dark Mode Override */
@media (prefers-color-scheme: dark) {
  :root {
    --bg-page: #061b2e;
    --bg-card: #0c2b47;
    --border-subtle: #1c4970;
    --text-heading: #ffffff;
    --text-body: #dce7f0;
    --accent-link: #60e1cc;
  }
}

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

.postlist-item {
  background-color: var(--bg-card);
  border: 1px solid var(--border-subtle);
}

h1, h2, h3 {
  color: var(--text-heading);
}

a[href] {
  color: var(--accent-link);
}

Main Point: Avoid pure #000000 backgrounds with #ffffff text in dark mode; slightly desaturated dark navy or charcoal surfaces reduce halation and eye strain during long reading sessions.

Credits #

Photo by Sander Sammy

← Home