CSS Academy · Lesson

prefers-color-scheme Media Query

Detect the user's system dark or light mode preference using the prefers-color-scheme media query.

prefers-color-scheme Media Query is a free CSS Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the CSS Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Auto Dark Mode?

Many users enable dark mode at the OS level for comfort, battery life (OLED screens), or accessibility. The prefers-color-scheme media query detects this preference and lets your site adapt automatically.

Query Values

Two values:

light — user prefers a light color scheme (or no preference)
dark — user prefers dark mode

@media (prefers-color-scheme: dark) {
  body { background: #111; color: #eee; }
}

Mobile-First Dark

If most of your users are on OLED mobile devices, consider making dark the base style:

/* Dark by default */
body { background: #111; color: #eee; }

@media (prefers-color-scheme: light) {
  body { background: white; color: #111; }
}

CSS Variables Approach

The cleanest implementation — define a token set per scheme:

:root {
  --bg: white;
  --text: #111;
  --border: #e0e0e0;
}

@media (prefers-color-scheme: dark) {
  :root {
    --bg: #1a1a2e;
    --text: #e0e0e0;
    --border: #333;
  }
}

Images in Dark Mode

Reduce image brightness in dark mode to avoid glaring images:

@media (prefers-color-scheme: dark) {
  img, video {
    filter: brightness(0.85) contrast(1.05);
  }
}

Detecting in JavaScript

Check dark mode preference in JavaScript for dynamic behavior:

const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;

window.matchMedia('(prefers-color-scheme: dark)')
  .addEventListener('change', e => {
    updateTheme(e.matches ? 'dark' : 'light');
  });

Testing in DevTools

In Chrome DevTools → Rendering tab → Emulate CSS prefers-color-scheme. Toggle between light and dark without changing OS settings. In Firefox: DevTools → Inspector tab → the eye icon menu.

Dark Mode Color Principles

Effective dark mode:

Use dark gray (not pure black) for backgrounds — reduces eye strain
Reduce elevation shadows — use lighter background tones for higher surfaces
Adjust border colors to be lighter for visibility
Check text contrast ratios — different ratios may be needed

Invert Colors Anti-Pattern

Never simply invert all colors with filter: invert(1) for dark mode. Images and icons become bizarrely colored. Use proper dark mode tokens with appropriate colors for each element.

Performance: Avoiding Flash

If you use JavaScript-driven theme switching, prevent a Flash of Unstyled Theme (FOUT) by applying the theme class to <html> synchronously in a <script> tag in <head> before the page renders.

Meta Theme Color

Update the browser chrome color (mobile address bar, task switcher) to match the dark theme:

<meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff">
<meta name="theme-color" media="(prefers-color-scheme: dark)"  content="#1a1a2e">

Quick Check

Which media query value should you use to apply dark mode styles when the OS is set to dark mode?

Recap

prefers-color-scheme: dark detects the OS dark mode preference. Implement auto dark mode using CSS variables that swap token values inside the media query. Reduce image brightness in dark mode. Test in DevTools. Update the browser theme-color meta tag for a complete mobile experience.

Frequently asked questions

Is the “prefers-color-scheme Media Query” lesson free?

Yes — the full text of “prefers-color-scheme Media Query” is free to read here on the web, and the CSS Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the CSS Academy course, upgrade to CoddyKit PRO.

What will I learn in “prefers-color-scheme Media Query”?

Detect the user's system dark or light mode preference using the prefers-color-scheme media query. You practise CSS Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start CSS Academy?

No prior experience is required. CSS Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “prefers-color-scheme Media Query” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this CSS Academy lesson?

Yes. Every CSS Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to CSS Academy