Dark mode has quietly become an expectation rather than a differentiator, and visitors increasingly notice its absence. Getting it right is mostly a design and CSS discipline problem, which is why our maintenance work tends to treat it as a front-end quality issue rather than a plugin decision.
This guide covers how dark mode actually works in the browser, the mistakes that make sites look broken, and whether you should use a plugin or do it properly.
How Dark Mode Works
Operating systems expose a user preference for light or dark appearance. Browsers pass that to CSS through the prefers-color-scheme media query, so a site can respond automatically without asking anyone to click anything.
There are effectively three states worth handling: the user explicitly chose light, the user explicitly chose dark, and the user has expressed no preference and is following their system. Designs that only handle two of these end up with a toggle that fights the system setting.
Use CSS Custom Properties
The maintainable approach is to define your colours once as custom properties and redefine only those properties for dark mode, rather than writing a second stylesheet.
Define the complete light palette on the root element as your default. Redefine only the tokens inside a dark-mode media query. If you offer a manual toggle, redefine them again for your explicit dark attribute so the toggle can win in both directions. The rule that saves the most debugging is simple: never give a colour its only definition inside a media query.
The Mistakes That Make Sites Look Broken
- Pure black backgrounds: harsh against white text; a very dark grey reads better and reduces halation
- Inverting brand colours: a brand blue that works on white often fails contrast on dark and needs a lighter variant
- Forgetting images: logos and diagrams with white backgrounds appear as glaring rectangles
- Unstyled form fields: inputs that stay white while everything around them is dark
- Missed shadows and borders: shadows that were subtle on white become invisible on dark
- Transparent body background: which borrows whatever is behind it and produces unreadable text
Plugin or Custom Implementation?
What Plugins Do
Most dark mode plugins apply a CSS filter that inverts the page, then re-inverts images to stop them looking like negatives. It is a clever trick and it works acceptably on simple sites.
Where They Fall Down
Filter-based inversion has no understanding of your brand. It will produce a dark site, but not one you designed. On a site with a considered visual identity the result usually looks like an accident, and it can hurt performance because the filter forces repaints.
For a brochure or blog, a plugin is a reasonable shortcut. For a site where brand consistency matters commercially, implement it properly in your theme.
Getting Contrast Right
Dark mode is not exempt from accessibility requirements. Light grey text on dark grey backgrounds fails contrast just as reliably as the reverse, and it is a very common outcome because designers reduce contrast to soften the look.
- Check body text contrast against your dark background, not just your light one
- Give brand accent colours a lighter variant for dark mode rather than reusing them
- Verify link colours remain distinguishable from body text in both modes
- Test focus indicators in dark mode, where they are frequently invisible
- Review every component, not just the homepage: forms, tables, alerts, and cards
Do Not Forget Email and PDFs
If your site sends transactional email or generates PDFs, those have their own rendering rules. An email template with a transparent background can become unreadable in a dark-mode mail client, which is a support problem you will hear about eventually.
The Bottom Line
Dark mode done properly is a colour architecture exercise: tokens, contrast, and testing every component. Done as a bolt-on filter it usually looks like something went wrong. Decide which of those your brand can afford.
If your site needs front-end work of this kind, tell us what you have in mind and we will scope it.
Get a free audit covering security, updates, backups, and performance gaps. Takes 60 seconds to request and costs nothing.
