Skip to main content

Search rules

Search all UI Guides rules by name, category, or source

designVercel

Declare color-scheme for Dark Themes

MUST

MUST: Set `color-scheme` on `<html>` (`dark`, or `light dark` to follow the OS) so browser-drawn UI — scrollbars, checkboxes, radios, range tracks, date pickers, number spinners — repaints for the theme. This is separate from reading `prefers-color-scheme`, which only tells you what the user wants.

Set the CSS color-scheme property on <html> so native browser UI follows the theme

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

Bad

Good

Why it matters

Your CSS only paints what you render — scrollbars, checkboxes, radios, range tracks, date pickers, and number spinners are drawn by the browser itself, and it draws them light unless told otherwise. The `color-scheme` property is that signal: it switches the user agent's rendering intent, so those native widgets repaint dark for free. This is distinct from reading `prefers-color-scheme` (which tells *you* what the user wants, and prevents a theme flash) — `color-scheme` tells the *browser* what you chose. Set `color-scheme: dark` on the dark theme, or `light dark` on `<html>` to let the UA follow the OS.

Built by Gleb Stroganov, design engineer at Evil Martians.

The rules come from other people's skills and guidelines — Vercel, Rauno Freiberg, @Ibelick, impeccable, Emil Kowalski, Tailwind, RAMS — each one credited on the Sources page. The work here is extraction and wiring: every rule is pulled into one corpus, given a good and a bad example you can operate, a MUST/SHOULD/NEVER rule an agent can paste, and a link back to where it came from.