# Match theme-color to the Page Background **SHOULD** · **ID:** `design-theme-color-meta` · **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-theme-color-meta > SHOULD: Match the mobile browser and PWA chrome to the page background by shipping one `` per scheme with the literal background value — a `` tag cannot read CSS custom properties, and leaving it unset puts a default light address bar above a dark page. Declare a per color scheme so browser chrome matches the page 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 ``. Leave it unset and that chrome keeps a default light fill, producing a hard seam above a dark page. A `` 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. ## Rule snippet ```tsx ``` ## Bad — do not do this `design-theme-color-meta-bad` ```tsx /** * BAD: No . The page ships a dark surface, but mobile * browser chrome (Safari/Chrome address bar, the PWA title bar, the Android task * switcher card) keeps its default light fill — so the app ends up wearing a * bright collar it never asked for. */ export function ThemeColorMetaBad() { return ( 
{`
  Dashboard
  
  
`}
{/* Phone mockup */}
{/* Browser chrome — NOT in the dark scope: default light fill */}
9:41 ••••
acme.app
{/* The actual page: dark */}
Dashboard

A hard seam: the browser chrome bar stays light while the page below it is dark. On iOS and Android this is the first thing the user sees.

); } ``` ## Good — do this `design-theme-color-meta-good` ```tsx /** * GOOD: is declared once per color scheme, each value * equal to that scheme's page background. Mobile browser chrome and the PWA title * bar adopt the page surface, so the app extends edge-to-edge with no visible seam. */ export function ThemeColorMetaGood() { return ( 
{`
  Dashboard
  
  
`}
{/* Phone mockup */}
{/* Chrome AND page share one dark scope: one continuous surface */}
{/* Browser chrome — now painted with the page background */}
9:41 ••••
acme.app
{/* The actual page */}
Dashboard

Chrome bar and page share one surface — the seam is gone and the app reads as edge-to-edge.

); } ``` ## References - [MDN: meta name="theme-color"](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/meta/name/theme-color)