Dark mode looks simple until you’re three hours deep in a z-index issue, a mismatched SVG, and a modal rendering white-on-white. A toggle, a color switch, done\u2014that’s what most developers assume going in.<\/p>\n
This guide isn’t about whether dark mode looks cool. It does. It’s about building it correctly, knowing where to invest real effort, and recognizing which corners are safe to cut. Whether you’re implementing it for the first time or inheriting something that barely works, the same principles apply.<\/p>\n
Dark mode is a baseline user expectation now, not a nice-to-have. Over 80 percent of smartphone users enable it when available. If your product ignores system preferences, you’re already behind. The question isn’t whether to implement it\u2014it’s how to do it without creating two parallel design systems that drift apart and become a maintenance nightmare.<\/p>\n
This post covers the practical path: the CSS approach that scales, how to handle user preferences correctly, where theming breaks down, and what to prioritize when you’re a founder or product team with limited bandwidth.<\/p>\n
The shift toward dark mode isn’t purely aesthetic. There’s functional reasoning behind it.<\/p>\n
On OLED and AMOLED screens, dark pixels consume less power\u2014battery life improves meaningfully on mobile. For users spending six or more hours a day in a product, eye strain reduction is real, not marketing copy. And from a product retention angle, ignoring system-level preferences signals that your product is slightly behind. That matters when you’re competing for trust in a premium market.<\/p>\n
From a development perspective, dark mode has become a test of how well your design system is actually built. Teams that chose semantic color naming over literal values\u2014 There’s a broader signal here. Your product’s ability to adapt to a user’s environment is a proxy for how thoughtfully it was built overall. A site that flashes white on load, or renders links in a color that disappears against a dark background, loses a layer of trust before a word is read. Founders pitching premium services or enterprise clients feel that, even if no one names it.<\/p>\n The foundation of any robust dark mode implementation is CSS custom properties scoped to a theme attribute or class. Not inline styles. Not JavaScript-heavy theme objects passed through context. CSS at the root.<\/p>\n Set Most teams who struggle with dark mode are maintaining two separate visual states instead of one token layer. One source of truth for colors isn’t optional. It’s the entire strategy.<\/p>\n Before any user has set a preference in your product, respect what their OS already knows. The If you’re offering a manual toggle too, the logic works like this: system preference is the default, user preference stored in That single inline script, placed before any CSS loads, eliminates the flash. It’s one of the most commonly missed steps. Skip it and users see a white burst before dark mode kicks in\u2014jarring, and it feels broken.<\/p>\n Custom properties handle your own components well. They don’t automatically fix:<\/p>\n For SVGs you control, use Use this selectively. It works well for monochrome logos and icons. It breaks on photography and anything with complex color. For full control, maintain two image variants where it matters and swap them via Third-party embeds are harder. Many support their own dark mode parameters\u2014check the API or embed docs before writing workarounds. If they don’t support it, decide whether rebuilding the functionality natively is worth the effort.<\/p>\n This is the decision you’ll either thank yourself for or regret.<\/p>\n Naming a token Build your token system around roles, not values: surface, background, text-primary, text-secondary, border, accent, accent-hover, error, success. These translate across both themes. Gray-100 through gray-900 don’t.<\/p>\n If you’re inheriting a codebase with descriptive names, do the refactor before implementing dark mode. Layering dark mode on top of descriptively named tokens is how you end up with a token called Color transitions during theme switches can feel polished or glitchy. A simple transition on background and color goes a long way:<\/p>\n Don’t transition everything. Borders, shadows, and accent colors all shifting simultaneously produces a muddied animation where nothing feels intentional. Pick the most prominent properties and let the rest snap.<\/p>\n Also test what happens when the system theme changes while your app is open. Most apps ignore this entirely. It’s worth handling via a Small team, shipping fast? Here’s the honest prioritization.<\/p>\n Do first:<\/strong> Custom properties architecture, system preference detection, inline script for flash prevention.<\/p>\n Do when you have the cycles:<\/strong> Manual user toggle, preference persistence, theme-aware images.<\/p>\n Skip for now:<\/strong> Transitioning every UI element, building a full Storybook dark mode preview environment, supporting older browsers without CSS custom properties. They represent less than half a percent of your traffic and the workarounds cost days.<\/p>\n Dark mode at 80 percent beats dark mode not shipped\u2014as long as the core experience holds. The parts users actually notice are the text, the background, and whether the primary actions are readable. Get those right first.<\/p>\n Starting from a codebase with no theming infrastructure? The path is:<\/p>\n For teams running on a design system or component library, step one is aligning with whoever owns the tokens. Dark mode implementations that go rogue\u2014applied by one team without updating the system\u2014create a two-track problem. The whole point is a single layer that everything inherits from.<\/p>\n If you’re building a new product or redesigning from scratch, implement the token architecture on day one. It costs nothing at that stage and saves a week of refactoring later.<\/p>\ncolor-background<\/code> instead of #ffffff<\/code>\u2014implement dark mode in an afternoon. Teams that scattered hardcoded hex values across 80 components spend a week on it.<\/p>\n
\nKey Considerations<\/h2>\n
Start with a CSS custom properties architecture<\/h3>\n
:root {\n --color-background: #ffffff;\n --color-text-primary: #111111;\n --color-text-secondary: #555555;\n --color-surface: #f4f4f5;\n --color-border: #e4e4e7;\n --color-accent: #6366f1;\n}\n\n[data-theme="dark"] {\n --color-background: #0f0f0f;\n --color-text-primary: #f1f1f1;\n --color-text-secondary: #a1a1aa;\n --color-surface: #1a1a1a;\n --color-border: #27272a;\n --color-accent: #818cf8;\n}\n<\/code><\/pre>\ndata-theme<\/code> on the <html><\/code> element. Everything else inherits. You never fork your component styles\u2014you reference the variable, and the variable does the work.<\/p>\nRespect system preferences by default<\/h3>\n
prefers-color-scheme<\/code> media query exists for exactly this.<\/p>\n@media (prefers-color-scheme: dark) {\n :root {\n --color-background: #0f0f0f;\n --color-text-primary: #f1f1f1;\n \/* ... *\/\n }\n}\n<\/code><\/pre>\nlocalStorage<\/code> overrides it, and the data-theme<\/code> attribute reflects whichever wins. The key is setting that attribute as early as possible\u2014inline in the <head><\/code>\u2014to prevent a flash of the wrong theme on load.<\/p>\n<script>\n const saved = localStorage.getItem('theme');\n const preferred = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';\n document.documentElement.setAttribute('data-theme', saved || preferred);\n<\/script>\n<\/code><\/pre>\nHandle images, icons, and third-party embeds separately<\/h3>\n
\n
currentColor<\/code> instead of hardcoded fills wherever possible. For images that only work light, CSS can help:<\/p>\n@media (prefers-color-scheme: dark) {\n .logo-image {\n filter: invert(1) hue-rotate(180deg);\n }\n}\n<\/code><\/pre>\n<picture><\/code> with a media<\/code> attribute.<\/p>\nUse semantic color names, not descriptive ones<\/h3>\n
--color-gray-100<\/code> describes what it looks like. Naming it --color-surface<\/code> describes what it does. In dark mode, --color-gray-100<\/code> makes no conceptual sense as a dark background. --color-surface<\/code> does.<\/p>\n--color-white<\/code> set to #1a1a1a<\/code>\u2014and a team that’s stopped trusting the design system entirely.<\/p>\nTest transitions and animation<\/h3>\n
:root {\n transition: background-color 0.2s ease, color 0.2s ease;\n}\n<\/code><\/pre>\nmatchMedia<\/code> listener so users with automatic light\/dark switching see it reflected without a page reload.<\/p>\nWhat to skip if you have limited bandwidth<\/h3>\n
\nNext Steps<\/h2>\n
\n
var(--token-name)<\/code> across components.<\/li>\n[data-theme=\"dark\"]<\/code> overrides.<\/li>\n<head><\/code> script for flash prevention.<\/li>\n