This note has an interactive demo. Try it in the original

If your site is light and never says a word about dark mode, Safari is about to make that decision for you. On 3 November the WebKit team introduced Adaptive Dark Mode in Safari 27.3 beta: when a user with a dark system turns it on, light pages get repainted in dark colors. The one line that decides whether your page is touched is color-scheme.

The demo above simulates it. Set the system to dark, leave "Nothing" selected and watch the warm, light page turn dark. The photo stays as it was, the black-and-white logo flips, and the <canvas> chart stays bright white in the middle of it all. Then switch to light dark and the page uses the dark palette its author designed, not one generated for it.

What Safari actually does

The WebKit post is unusually detailed about the mechanics, so this is worth reading carefully rather than guessing:

  • Who gets transformed. Pages that declare dark support with color-scheme: light dark are left unchanged. For everything else, Safari quickly estimates whether the page is mostly light or mostly dark; pages that are already dark with light text are left alone.
  • How. The core is a color matrix that inverts luminosity while preserving hue, so light backgrounds become dark and dark text becomes light. Text aims for the WCAG 4.5:1 contrast ratio, light CSS gradients are transformed too, and buttons, text over images and hover menus are adjusted so they stay usable.
  • Images. Most are left alone. SVG colors are transformed when needed, and for bitmaps Safari looks at the pixel histogram and inverts "simple black-and-white logos".
  • Things that may break. Masks and mix-blend-mode may be turned off on transformed elements, and <canvas> content is not changed. That is the white chart in the demo: anything you draw in light colors stays light.
  • The user decides. With the system set to dark, Safari offers a preview on a bright site and the user taps "Try".

It isn't the first browser to do this. MDN's color-scheme page already points to Chrome's Auto Dark Theme on Android as one of the overrides that only turns off. And the CSS Color Adjustment spec describes exactly this case: when the user prefers a color scheme the author hasn't supported, the user agent overrides it and auto-adjusts the other colors.

The fix is one declaration

If you already have a dark theme, say so, and say it early. WebKit recommends putting it in the HTML <head> or on :root rather than adding it later with JavaScript, and MDN suggests putting the meta tag before any CSS to avoid a flash on load:

<meta name="color-scheme" content="light dark"> 
:root { color-scheme: light dark; } body { background: light-dark(#FAF7F2, #16130F); color: light-dark(#1C1917, #F5F0E8); } 

That is the palette the demo uses in light dark mode. light-dark() returns the first color when the used scheme is light and the second when it is dark, and it only works when color-scheme allows both. color-scheme has been Baseline Widely available since January 2022 and light-dark() has been Baseline since May 2024, so you don't need a fallback for current browsers. The demo still has one: it checks CSS.supports('color', 'light-dark(#000, #fff)') and switches palettes with an attribute when the check fails.

If your page needs to stay light (a print-like document, a brand that has never had a dark version), the opt-out is the only keyword:

<meta name="color-scheme" content="light only"> 
:root { color-scheme: light only; } 

The spec grammar is normal | [ light | dark | <custom-ident> ]+ && only?, so light only and only light mean the same thing. You can also scope it to a single element (an embedded map, a diagram) instead of the whole page.

Gotchas

  • only didn't work in Safari 27.3 beta 1. WebKit says so in the post and adds that it may change during the beta. Declaring a real dark mode is the path that works today.
  • Your JavaScript can't see the transformation. For privacy, Safari doesn't let pages detect when Adaptive Dark Mode is applied. Reading CSS colors gives the original authored values and images drawn to a canvas render in their original form. The demo's middle readout shows this: the user sees a dark background while your script reads the light one.
  • Partial dark support counts. If only some components have dark styles, WebKit suggests putting color-scheme: light dark on those specific elements.
  • Canvas is on you. Neither Safari nor light-dark() will recolor what you draw. If you declare dark support, redraw charts with colors read from your theme. The demo deliberately doesn't, so you can see the gap in both modes.
  • The simulation is a simulation. The demo inverts lightness in OKLCH and keeps hue, which follows WebKit's description, but it's not Safari's algorithm. To see the real thing you need the Safari 27.3 beta.

What to keep an eye on

  • Whether the only keyword starts working during the 27.3 betas, and whether the behavior reaches the stable release unchanged.
  • How Safari handles prefers-color-scheme on transformed pages. The post doesn't say, so I wouldn't assume anything.
  • Sites that set color-scheme from JavaScript after load. WebKit explicitly advises against it; if a theme toggle does that today, it's worth adding a static declaration in the <head> as well.

Sources

Originally published at richi.codes.