Short answer: dark mode is not light mode with the colours flipped. Pure black backgrounds and pure white text produce eye strain, saturated brand colours that looked fine on white become vibrating neon on dark, and shadows stop working as a depth cue. Getting dark mode right in a chat widget means rethinking surfaces, contrast and brand colour rather than inverting values.
Should the widget follow the site or the system?
Three defensible policies, and it is worth choosing deliberately.
Follow the site. If your site is dark, the widget is dark. This is the safest default, because a light widget on a dark site is a flashlight in the corner, and the mismatch reads as an unrelated third-party thing pasted on top.
Follow the system preference. If your site already respects the visitor's operating-system dark mode preference, the widget should too, and switch with it. Consistency inside your own page is the goal.
Fix it. Some brands are committed to a single look. That is fine as long as the fixed choice matches the site, and as long as contrast holds up.
What you should not do is let the widget pick independently of your site. A dark widget on a light page, or the reverse, is the single most obvious sign that the widget is a bolt-on.
Do not use pure black
The most common dark mode mistake is a background of pure black with pure white text. That combination has enormous contrast, which sounds good and is actually uncomfortable: at very high contrast, light text on dark backgrounds produces a halation effect where the letters appear to bleed, and it is more tiring to read for extended periods, particularly for people with astigmatism.
Use a very dark neutral rather than pure black, and a slightly off-white rather than pure white. You lose nothing in accessibility terms, since the ratio remains far above the 4.5:1 body-text requirement, and you gain a considerably more comfortable read.
Pure black also removes your ability to show elevation, which brings us to the next problem.
Elevation without shadows
In light mode, depth comes from shadows. A panel floats above a page because it casts a shadow onto it. In dark mode shadows barely register, because a dark shadow on a dark background is nearly invisible.
The dark-mode convention is to signal elevation with lightness instead: surfaces that are conceptually closer to the viewer are slightly lighter. In a chat widget that gives you a layered stack: the page behind, then the panel surface slightly lighter, then message bubbles lighter again, then the input field distinguished from the panel by a small step.
Each step should be subtle. Three or four barely-perceptible steps read as a considered interface. Large jumps read as a patchwork. And keep enough separation between the input field and the panel that the field is obviously a field, because in dark mode a low-contrast input can genuinely disappear.
Brand colour is the hard part
Here is where most dark modes fall apart. A brand colour chosen against a white background is usually mid-to-deep in tone with reasonable saturation. Put that same colour on a dark surface and two things go wrong: it loses contrast against the background because both are dark, and if it is highly saturated it appears to vibrate against the dark surround.
The fix is to use a lighter, less saturated variant of your brand colour in dark mode. Same hue, lifted lightness, pulled-back saturation. It still reads as your colour. It just stops fighting the background.
The place this shows up most in a chat widget is the visitor's message bubble, which is typically brand-filled. The pairing that works in light mode, brand fill with white text, frequently fails in dark mode, either because the fill no longer separates from the panel or because the text contrast drops below 4.5:1.
This is exactly the failure Clerkzo's contrast checking is there to prevent. Set a brand colour, and text tone is adjusted so it stays readable rather than letting an unreadable pairing ship in either mode. Combined with light and dark modes across the eight themes in Widget Studio, the practical effect is that you can pick your colour and not have to hand-tune two palettes.
Test both modes, every time
The single most useful habit: whatever you change, look at it in both modes before publishing.
Things that pass in light and fail in dark, in roughly descending order of frequency:
- Timestamps and metadata, usually rendered as light grey, which becomes low-contrast dark grey and vanishes
- Placeholder text in the input, which is already the lowest-contrast text in the interface
- Borders and dividers, which either disappear entirely or become harsh white lines
- Disabled button states, which in dark mode can look identical to enabled ones
- Focus rings, which frequently rely on a single colour that works against one background only
- The launcher icon against the launcher fill
The live preview in Widget Studio makes this a matter of toggling and looking, which is the point. A design decision you cannot see is a design decision you will get wrong.
Images, logos and the transparent PNG problem
If your widget shows a logo or avatar, check it in dark mode. A logo exported as a dark PNG with a transparent background disappears on a dark surface, and this is one of the most common dark-mode bugs on the entire web.
Options, in order of preference: supply a light variant for dark mode, use a monochrome mark that can be recoloured, or place the logo on a small light-coloured chip that stays constant across modes. What does not work is hoping nobody notices.
Switching modes without jarring
If your widget follows the system preference and the visitor changes it mid-session, or if their device switches at sunset, the transition should be calm. An instant hard flip from light to dark is startling. A short cross-fade on colours is enough to make it feel intentional.
And as with all motion, honour the reduced-motion preference: when it is set, switch instantly rather than animating. The full accessibility picture is in chat widget accessibility.
Dark mode does not excuse you from contrast rules
Worth stating plainly because it gets forgotten. WCAG AA still requires 4.5:1 for body text and 3:1 for large text and interface component boundaries, in dark mode exactly as in light. Dark mode is not automatically more accessible; it is a different set of ways to fail.
The specific dark-mode trap is that low-contrast greys look tasteful. A muted grey timestamp on a dark panel looks restrained and elegant in a screenshot and is unreadable on a phone in daylight. Check the numbers, not the vibe.
Frequently asked questions
Should my chat widget default to dark mode?
Default to whatever your site does. If your site follows the system preference, follow it too. Consistency within the page matters more than either choice on its own.
Why does my brand colour look wrong in dark mode?
Because it was chosen against white. Use a lighter, less saturated variant of the same hue for dark surfaces, and it will read as the same colour without vibrating.
Is pure black bad for dark mode?
For extended reading, yes. It maximises contrast in a way that causes halation and eye strain, and it removes lightness as an elevation cue. Use a very dark neutral instead.
Does dark mode improve accessibility?
Not inherently. It helps some people, particularly those sensitive to bright screens, and hinders others, notably some people with astigmatism. Offering both and respecting the system preference is the accessible answer.
Do I have to configure two themes by hand?
No. Clerkzo's themes ship with light and dark variants and check contrast when you set your brand colour, with a live preview for both. See how it works or pricing for what is included.