Dark mode with prefers-color-scheme, color-scheme and light-dark()

What it is

prefers-color-scheme is a media feature with the values light and dark; MDN describes it as detecting whether the user requested a light or dark theme through an operating-system or browser setting. It only answers a question. The color-scheme property does something: it declares which schemes an element can be rendered in (normal, light, dark, light dark, or only light to forbid overrides), and MDN lists what the browser then adapts to the used scheme: the canvas surface, default scrollbar colours, default form-control colours and other browser-provided UI such as spellcheck underlines. <meta name="color-scheme" content="light dark"> in head, placed before any stylesheet, tells the browser the same thing before CSS arrives; MDN recommends it to prevent a flash during page load. Finally light-dark(a, b) returns the first colour when the used scheme is light or unset and the second when it is dark, without a media query; MDN states that it only works when color-scheme has the value light dark, usually set on :root.

Why it matters

A stylesheet that only darkens backgrounds under the media query produces a dark page with white native inputs, white scrollbars and a white flash before styles apply. Declaring color-scheme fixes the native parts; the media query and light-dark() handle the author's own colours.

How to apply

• Put color-scheme: light dark on :root and the equivalent meta tag in head; the browser now renders native controls correctly in both schemes.
• Define the palette as custom properties in one place, either with two blocks (:root { … } @media (prefers-color-scheme: dark) { :root { … } }) or with light-dark() per token.
• Avoid pure black on pure white and vice versa; reduce saturation of accent colours in the dark palette and check contrast in both schemes, since a ratio that passes on white can fail on dark grey.
• Replace or recolour images: <picture> with a media="(prefers-color-scheme: dark)" source for logos and diagrams; inline SVG can use currentColor.
• For a user toggle, set a class or data-theme attribute on html from an inline script that runs before first paint, store the choice, and treat "system" as the default state.

Pitfalls

Shadows disappear on dark backgrounds; elevation needs lighter surfaces instead. Transparent PNGs assume a light page. Third-party embeds and iframes do not inherit the choice. only light opts an element out of the user's scheme, which is rarely justified.

A toggle must also set color-scheme

A theme toggle that only swaps custom properties leaves native controls in the operating-system scheme: dark page, light inputs and scrollbars. Make the attribute set color-scheme too:

:root { color-scheme: light dark; }
:root[data-theme="light"] { color-scheme: light; }
:root[data-theme="dark"] { color-scheme: dark; }

With this in place light-dark() tokens follow the toggle automatically, because the function resolves from the element's used colour scheme; a palette written as two prefers-color-scheme blocks does not, and needs its dark block repeated under [data-theme="dark"]. Apply the stored choice from an inline script before first paint (with a nonce or hash under a strict Content Security Policy), update <meta name="color-scheme"> from the same script, and keep 'system', which sets no attribute, as the default.