Dark Mode CSS: Fixing color-scheme and Contrast Issues

How the browser decides between light and dark

Three separate things are involved, and dark mode problems usually come from one of them being missing or out of step with the others.

1. The visitor's preference. The operating system or browser tells the page whether the visitor prefers a light or dark appearance. CSS reads this with the prefers-color-scheme media feature.
2. The page's declaration. The color-scheme property, or a <meta name="color-scheme"> tag, tells the browser which schemes the page is designed for. Without it, the browser assumes the page is light only.
3. Your colours. The actual background, text, border and accent colours you set in CSS.

The declaration matters more than people expect. When a page declares that it supports dark, the browser switches its own built-in styling to dark as well: the default page background, text inputs, select menus, checkboxes, scrollbars and the default link colours. If you set a dark background yourself but never declare the scheme, the browser still draws light form controls and scrollbars, which is where the familiar white input boxes on a dark page come from.

Testing both modes without changing your computer

You do not need to switch your whole operating system back and forth. In Chrome or Edge, open DevTools, open the command menu (Ctrl+Shift+P, or Cmd+Shift+P on a Mac), type "Rendering", and in the Rendering panel set Emulate CSS media feature prefers-color-scheme to dark or light. Firefox has buttons for the same thing in the Inspector's rules view. Then walk through the pages that matter:

• Home, a content page, a product or service page, the contact form and any checkout or booking step.
• Every form control: text boxes, drop-downs, checkboxes, radio buttons, date pickers and file inputs.
• Hover, focus and active states for links and buttons, and any error or success messages.
• Menus, modals, cookie banners, tables, code blocks and embedded maps or videos.

Also test on a real phone with the system dark theme switched on, and reload with the cache disabled on a throttled connection. The flash of a light page before dark styles arrive often only shows when the network is slow.

The CSS Checker flags dark-mode issues alongside its validation, render-blocking, unused-CSS, specificity, prefix and size checks, so run it before and after to see what it reports for your stylesheets.

The fix, step by step

A complete, minimal implementation

This setup for a fictional café, Juniper Lane Coffee, follows the system preference by default, lets visitors override it, and avoids a light flash on dark pages.

In the head, before any stylesheet

<meta name="color-scheme" content="light dark">
<script>
  (function () {
    try {
      var t = localStorage.getItem('theme');
      if (t === 'light' || t === 'dark') {
        document.documentElement.dataset.theme = t;
        document.documentElement.style.colorScheme = t;
      }
    } catch (e) {}
  })();
</script>
<link rel="stylesheet" href="/css/site.css">

In the stylesheet

:root {
  color-scheme: light dark;
  --surface:    light-dark(#ffffff, #16181d);
  --surface-2:  light-dark(#f4f1ec, #22252c);
  --text:       light-dark(#1f2328, #e6e6e3);
  --text-muted: light-dark(#5b6168, #a9adb3);
  --border:     light-dark(#d9d4cc, #3a3e46);
  --accent:     light-dark(#8a3b12, #f0a36b);
}
:root[data-theme="light"] { color-scheme: light; }
:root[data-theme="dark"]  { color-scheme: dark; }

body   { background: var(--surface); color: var(--text); }
.card  { background: var(--surface-2); border: 1px solid var(--border); }
a      { color: var(--accent); }
input, select, textarea { accent-color: var(--accent); }

Because light-dark() picks its value from the element's used colour scheme, setting color-scheme on the root is all the toggle needs to do; every token follows. If you must support browsers older than the ones that introduced light-dark(), define the light values on :root and repeat the dark values inside a prefers-color-scheme: dark media query and a [data-theme="dark"] rule instead.

Swapping a logo

<picture>
  <source srcset="/img/logo-light-on-dark.svg" media="(prefers-color-scheme: dark)">
  <img src="/img/logo.svg" alt="Juniper Lane Coffee" width="180" height="48">
</picture>

Edge cases

• Embedded frames. When an iframe's colour scheme differs from the page around it, the browser gives the frame an opaque background so its content stays readable. That is why a light-only booking or map widget shows as a white rectangle on a dark page. Check the provider's options for a dark theme parameter.
• Automatic darkening. Some browsers can darken light-only pages automatically. Results vary and can make brand colours look wrong. Declaring your supported schemes properly is the reliable way to keep control of how the page looks.
• Browser toolbar colour. A theme-color meta tag can take a media attribute, so you can give one colour for light and another for dark in browsers that support it.
• Charts and maps. Chart libraries and map tiles have their own colours. Pass them your custom property values, or choose a dark style, rather than leaving a bright white chart in the middle of a dark page.
• Printing. Visitors who print a page in dark mode rarely want a black page. Reset to light colours in a print media query.
• Themes and builders. WordPress themes, Shopify colour schemes and page builders may apply colours per section. Change them at the theme level rather than overriding each block. See the WordPress and Shopify CSS guides.

Keeping dark mode working

1. Ban raw colour values outside the token definitions with a Stylelint rule, so new components cannot bypass the theme.
2. Add dark-mode screenshots to your visual checks, or at least test new pages in both schemes before they go live.
3. Keep the token list short and named by role, so a designer can adjust the whole dark theme in one place.
4. Re-run the CSS Checker after theme or plugin updates, which often bring in hard-coded colours.
5. Check contrast whenever brand colours change; a new accent colour that works on white may fail on dark grey.

For accessibility checks beyond colour, see the CSS Checker Guide and the other fixes in the CSS Checker Fixes hub.