@media (prefers-color-scheme: dark) lets you change your colours, but the browser keeps painting its parts light: the page background, default text colour, inputs, scrollbars, spellcheck underlines. It can't darken them on its own, because a page written before dark mode might put dark text on them.
color-scheme (CSS Color Adjustment 1) is the opt-in. Each element lists the schemes it supports; the browser picks a used colour scheme per element: the user's preference if it's listed, otherwise the first listed one, otherwise light.
:root { color-scheme: light dark; }
That one line turns the canvas, default text, form controls and the system colours (Canvas, CanvasText, Field, LinkText…) dark for users who prefer dark. On the root element it also covers the viewport's scrollbars and background. <meta name="color-scheme" content="light dark"> sets the page's supported schemes from the HTML, so it takes effect without waiting for a stylesheet. A subtree can pin itself with color-scheme: dark, and the only keyword (light only) forbids the browser from force-darkening the page.
light-dark(light, dark) (CSS Color 5) is the author version of a system colour: it computes to its first colour when the element's used scheme is light and the second when it's dark. So tokens are written once:
:root {
color-scheme: light dark;
--surface: light-dark(white, oklch(20% 0 0));
--text: light-dark(oklch(20% 0 0), oklch(95% 0 0));
}
[data-theme="dark"] { color-scheme: dark; }
A theme toggle now only changes color-scheme; every light-dark() follows, with no duplicated @media block. light-dark() shipped in Chrome 123, Firefox 120 and Safari 17.5; it accepts only colours, plus images since Chrome 150, Firefox 150 and Safari 27.