What is prefers-color-scheme (dark mode in CSS)?
Definition prefers-color-scheme is a CSS media feature that tells a page whether the user has asked for a light or dark color theme, usually through the operating system's dark mode. Its values are light and dark. A site supports dark mode by changing its colors inside @media (prefers-color-scheme: dark) and by declaring color-scheme, so browser-drawn parts such as form controls and scrollbars match.
How to fix it: How to test your website in dark mode on mobile
How does prefers-color-scheme work?
iOS and Android both have a system-wide dark mode, often on a schedule. Browsers pass the setting to pages through this media query; it updates instantly when the setting changes, without a reload. JavaScript reads it with matchMedia('(prefers-color-scheme: dark)').
A related piece is the color-scheme property, or the <meta name="color-scheme"> tag. It tells the browser which schemes the page supports, so the default background, text, form fields and scrollbars use dark colors too. Without it, a dark page can still show white input boxes.
Example
<meta name="color-scheme" content="light dark">
:root { --bg: #ffffff; --text: #1f1f1f; --muted: #5f5f5f; }
@media (prefers-color-scheme: dark) {
:root { --bg: #121212; --text: #ececec; --muted: #a8a8a8; }
}
body { background: var(--bg); color: var(--text); }Using custom properties keeps the two themes in one place. The newer light-dark() function (color: light-dark(#1f1f1f, #ececec)) does the same per property in current browsers.
Images can switch too: a <source media="(prefers-color-scheme: dark)" srcset="logo-dark.svg"> inside <picture> serves a dark-friendly logo or chart.
Common dark mode problems
- text color switched but background not, or the reverse, leaving dark text on dark backgrounds;
- grays that pass the contrast ratio on white but fail on near-black;
- logos and icons with transparent backgrounds that vanish on dark;
- hard-coded colors in inline styles or third-party widgets that ignore the theme.
On iPhone vs Android
Safari and Chrome both support prefers-color-scheme and color-scheme the same way. The difference is automatic darkening: Samsung Internet and some Chromium-based browsers can recolor pages that don't declare a dark theme, sometimes with odd results. Declaring color-scheme and styling dark mode yourself keeps you in control. Dark mode support is optional, but whatever visitors see must still be readable.
How MobileCheck checks it
MobileCheck loads every page a second time with prefers-color-scheme: dark and runs the same checks, including contrast against WCAG AA (4.5:1 for normal text, 3:1 for large text), so dark-mode-only problems show up with their own screenshots.