Skip to main content
UI Guides

Search rules

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

designVercel

Match theme-color to the Page Background

SHOULD

SHOULD: Match the mobile browser and PWA chrome to the page background by shipping one `<meta name="theme-color">` per scheme with the literal background value — a `<meta>` tag cannot read CSS custom properties, and leaving it unset puts a default light address bar above a dark page.

Declare a <meta name="theme-color"> per color scheme so browser chrome matches the page

<meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)">
<meta name="theme-color" content="#0a0a0a" media="(prefers-color-scheme: dark)">

Bad

Good

Why it matters

On mobile, the surface directly above your page is not yours — Safari and Chrome tint the address bar, and an installed PWA tints its title bar and task-switcher card, from `<meta name="theme-color">`. Leave it unset and that chrome keeps a default light fill, producing a hard seam above a dark page. A `<meta>` tag cannot read CSS custom properties, so ship one tag per scheme with the literal background value and a `media` attribute: `media="(prefers-color-scheme: dark)"` and a matching light one.

References

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.