# Declare color-scheme for Dark Themes **MUST** · **ID:** `design-color-scheme` · **Category:** design **Source:** [Vercel](https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md) **Interactive version:** https://ui-guides-agent-rules.netlify.app/principles/design-color-scheme > MUST: Set `color-scheme` on `` (`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 so native browser UI follows the theme 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 `` to let the UA follow the OS. ## Rule snippet ```tsx html { color-scheme: light dark; } html[data-theme="dark"] { color-scheme: dark; } ``` ## Bad — do not do this `design-color-scheme-bad` ```tsx /** * BAD: The page is painted dark by CSS, but `color-scheme` is never declared on * . The browser therefore keeps its default light rendering intent, so every * piece of *native* UA chrome — scrollbar track/thumb, checkbox, range track, date * picker — is drawn light on top of the dark surface. * * The `colorScheme: 'light'` below is what an undeclared effectively gives you. */ export function ColorSchemeBad() { return ( 
{`html.dark {
  /* every token flipped to dark… */
  /* …but nothing here tells the   */
  /* browser how to paint its own  */
  /* scrollbars and form controls. */
}`}
{/* A dark-themed page region. No matching color-scheme. */}

Dark page, light native widgets

Scroll me. The scrollbar next to this text is still the light-mode one.

It sits on a dark panel and glares.

Same for every control below.

None of them got the memo.

Because the browser was never told.

Scrollbar, checkbox, slider and date picker render in light mode on a dark page — the browser was never told the page is dark.

); } ``` ## Good — do this `design-color-scheme-good` ```tsx /** * GOOD: `color-scheme: dark` is declared alongside the dark tokens, so the browser * renders its own chrome — scrollbars, checkboxes, range tracks, date pickers, * spinners — in dark mode too. One CSS property, zero custom widget styling. */ export function ColorSchemeGood() { return ( 
{`html.dark {
  /* every token flipped to dark… */
  color-scheme: dark; /* ← tell the UA */
}

/* Or let the UA follow the OS: */
html { color-scheme: light dark; }`}
{/* Same dark-themed page region, now with a matching color-scheme. */}

Dark page, dark native widgets

Scroll me. The scrollbar is dark, because the UA knows the page is.

It blends into the panel instead of glaring.

Same for every control below.

All of them got the memo.

One declaration did it.

Scrollbar, checkbox, slider and date picker all follow the theme — no custom widget CSS, just `color-scheme`.

); } ``` ## References - [MDN: color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) - [web.dev: Improved dark mode default styling](https://web.dev/articles/color-scheme)