Some of the inboxes your Klaviyo template lands in will re-color it, and you get no say in which ones. What you do get is the choice of building it so the re-coloring does not matter. That is the practical goal of dark mode email design.
Building the template so it survives whatever a mail client does to your colors is achievable work. The logo stays visible and the button still looks like a button. Almost all of it is design work. You can brief it this week.
We build and run Klaviyo accounts for DTC brands, and template rendering sits in the standing checklist for every account review. It earns that place because the flows carrying the most revenue tend to carry the most fragile artwork.
What follows is the dark mode email checklist we work from: what to change, what to hand over, and what to stop worrying about.
Color, Logo And Image Choices That Survive Any Inversion
Dark mode damage is predictable by element type. A mail client will do one of a small number of things to your email, and each one breaks a specific kind of element in a specific way.
Because the damage is predictable, the decisions become fairly obvious once you know which elements are exposed. Almost none of them need code. That is why this section comes before the one about the declaration.
Designing Dark-First Is The One Choice That Makes Gmail Predictable
One decision comes before any individual color. Is your template light by default with a dark variant, or dark by default with no variant at all?
That second option is the one almost nobody discusses, and it carries a significant advantage. Buttondown, whose engineers publish a technical series on email, describe a Gmail workaround that nearly works. Design the email's CSS in dark mode from the start with no substitutions, and Gmail should render it correctly. An email that is already dark cannot be turned dark.
That robustness comes at a price you should weigh honestly. A dark-by-default email looks deliberate in a dark interface and slightly severe in a light one. It also commits your campaign artwork to a palette your brand may not want.
Given that cost, most DTC brands are better off light-first with sensible values. Where dark-first pays off is on accounts that have written Gmail off as unmanageable, because it is the one construction that makes Gmail behave.
White emails deserve a mention before we leave palette direction. mailpeek's write-up on client behavior covers the ones that leave your email untouched. This sounds ideal, but it creates a jarring experience. Your bright white email sits inside a dark interface like a flashlight in a dark room.
Some recipients read that as your email failing to support dark mode, which is hard on a sender whose mail client made that call for them. A pure white email is therefore a design decision even where nothing touches it.
Pure Black And Pure White Are The Values That Trigger Apple Mail's Inversion
If you change one thing after reading this, change these two values.
They matter because Apple Mail leaves most emails alone. It intervenes when it finds a pure white background carrying pure black text, and that specific combination triggers its inversion.
Use #FFFFFF and #000000 and you have asked for the transformation. Swap in an off-white and an off-black and the email renders as you built it.
Designmodo ship this as a default in their email builder and make the same point from the other direction. Off-black and off-white sit outside the range that triggers the most aggressive handling, while still reading as black and white to anyone looking at the email. Nobody notices that your background is #FDFDFB. The mail client does.
Because the change applies at template level, it propagates across every campaign built on that template. Two hex values, changed once. That makes it the cheapest fix in this entire article.
A Transparent Logo Cannot Be Safe In Both Modes At Once
Transparent PNGs are the asset that fails most reliably. The mechanism is worth stating precisely, because the remedy follows directly from it.
A transparent background takes the color of whatever sits behind it. That leaves the mark's own color as the only thing separating it from the background.
So a dark logo on transparency reads perfectly on white and vanishes on black, and a white logo does the reverse. The designers at Email Love write up their own sends, and they state it plainly: dark logos on transparent backgrounds disappear in dark mode, and white logos disappear in light mode.
That leaves no version of a transparent single-color logo that is safe in both. Testing will not produce one, because none exists.
Three fixes exist and two of them need no code. Put a solid background plate behind the mark so it carries its own contrast. Supply a two-tone version that reads against either background. Or swap the image in the clients that support substitution, which needs a developer and works only in some inboxes. That last one is a fair bit of faff for partial coverage.
For most brands the background plate sorts it out, and it is a fifteen-minute job for a designer.
Footers deserve a specific look while you are doing this. Badsender, a French email consultancy that publishes long technical teardowns, walks through a real send where footer icons and a secondary logo land on a light background and become unreadable while the rest survives. Small monochrome assets live in footers, which is exactly where transparency bites.
Pastels And Mid-Tones Are The Palette Most Likely To Disappear
Logos are one asset. Your whole palette is the other, and some palettes survive dark mode more or less untouched while others were always going to struggle.
Either way, trouble concentrates in the middle of the range. Email Love are blunt about the first half of it: if your brand uses light pastels or subtle grays, they're probably going to disappear against a dark background. Those colors were relying on a white page to read as anything at all.
Mid-tones fail for a related but distinct reason. A color that is neither clearly light nor clearly dark gives an inversion algorithm nothing to work from, so whatever it decides becomes effectively arbitrary. Knak, who build template systems for enterprise marketing teams, identify mid-tones as the zone that behaves least predictably.
All of which means a palette committed to being clearly light or clearly dark beats a tasteful one hovering in between. That is a brand guideline decision, so it belongs with you and your designer.
Contrast deserves one extra check while you are in the palette. A ratio that passes in light mode tells you nothing about the dark version. WebAIM, the accessibility center at Utah State University, describe contrast as the difference in perceived luminance between two colors. Change the background and you change the measurement, so your dark variant needs its own separate check.
Buttons Fail Because Label And Background Transform Separately
Palette decisions protect your text. Buttons need their own attention, because the button is the element whose failure costs you money directly.
Its mechanism is straightforward once you see it. A button's background color and its label color are two separate values, and the mail client transforms them independently. It makes two unrelated decisions about them.
So a combination you chose deliberately can come apart. White text on your brand color might arrive as low-contrast text on a shifted background. Sometimes the text moves one way while the background moves the other.
Topol.io document this behavior in their email builder, and they treat buttons as their own category of risk for exactly that reason.
Giving the button enough contrast to survive either decision is the fix. Check it specifically. Do not assume it inherited the safety of the surrounding text. The accessibility guidelines give you a number to build to. WebAIM's summary of the WCAG contrast requirements puts the threshold at 4.5:1 for normal text and 3:1 for large text, where large means 18 point, or 14 point bold.
Think about which flow this lands in. An abandoned-cart email whose call to action nobody can read is a recovery you already paid to earn.
Brief Your Designer, Then Check The Send
Everything above is a decision. This is how those decisions become a template, and how you confirm they arrived.
Three Lines Of Color-Scheme Declaration Belong In Every Klaviyo Template
Some code is involved after all, and it is a short block.
For the exact syntax, the starting point comes from Parcel, the email development environment used by a good number of working email developers. Their guide on color-scheme in email opens with it: "First up, we need to tell the email client which color schemes we would like to support. This can be done with either a <meta> tag or in CSS."
Following that guidance, three things go in the template head. A color-scheme meta tag set to light dark. The same declaration as a CSS property on :root. And a supported-color-schemes meta tag, which covers older versions of Apple Mail.
Parcel recommend including both the meta and the CSS forms. The CSS version has broader support, though edge cases run the other way.
Two things make this worth doing. It tells the clients that read it which schemes you support instead of leaving them to guess. It also belongs in the template head once, so every campaign inherits it.
SendLayer ship a dark-mode-safe template alongside their explanation and make the same argument for working at template level. The template is the unit of the fix. If you are rebuilding templates anyway, our walkthrough of six real Klaviyo templates covers the structural decisions that sit alongside this one.
Briefing all of it is short work. Off-white background, off-black text, and a logo on a solid plate or supplied two-tone. Buttons contrast-checked in both variants, with the color-scheme declaration in the template head.
Send Yourself The Template And Open It In Gmail On An iPhone
Then check it, on the one surface that will show you a problem.
Most senders go wrong here, and mailpeek describe the trap exactly. You test your email in Gmail. It looks great. You toggle dark mode and check again, nothing has changed, and you relax. Somebody then opens that same send in the Gmail app on a phone and the logo has gone.
It looked fine on the laptop because Gmail in a desktop browser darkens its own interface while leaving your email body alone. You have not really tested anything at all.
Open the same send in the Gmail app on an iPhone and you will see full inversion. That is the version a large part of your list is getting.
Email Love's designer describes finding this out the hard way. "The email didn't just look bad in dark mode," they write, before explaining that it had gone out that way to most of their audience without them realising.
Quiet underperformance is the defining feature of this problem. It generates no complaints, and your own inbox stays quiet about it. That puts it in the same family as the other email mistakes that go unnoticed until somebody audits the account.
Dedicated pre-send tools will preview dark variants on real devices, and Email on Acid is one of them. Running that dark mode email check on a phone still takes a minute and needs no subscription.
Put it in your pre-send routine next to the link check, and it stops being something you remember only after somebody complains.
Dark Mode Has No Standard, So Control Is Not On The Table
Now for why the advice above is all design and almost no code.
It comes down to governance. Dark mode on the web is governed by a specification. In email it is governed by nothing. mailpeek put it about as directly as it can be put: "There is no spec. There is no standard. Every client does whatever it wants."
Each mail client therefore decides for itself what to do with your message, and the decisions conflict. As mailpeek set out, email clients fall into three broad categories of behavior. One group leaves the body untouched, one inverts everything, and one selectively replaces certain colors.
Gmail On Desktop Leaves Your Email Alone; Gmail On iPhone Inverts It
One mail brand uses two of those categories at once, which makes it the clearest illustration.
Gmail in a desktop browser applies no transformation to your email body. Its interface goes dark around the message while the message stays exactly as you wrote it.
Its iOS app does the opposite and applies full inversion across the body. Same provider and same account, two opposite results.
A Gmail check on its own proves very little. That split is also why the phone check matters so much, because the surface most people test on is the one guaranteed to show them nothing.
Partial Inversion Swaps Your Brand Color For The Client's Own Choice
A third behavior damages brands specifically, and it is often mistaken for a gentler version of full inversion. Less predictable is the more accurate description.
Here is why. A mail client applying partial inversion selects certain colors and replaces them with what it considers a reasonable equivalent for a dark interface. Those replacements are judgments made without reference to your palette.
A brand green can arrive as a shade of teal. Nothing is broken in a way a contrast checker would flag, and the email stays perfectly legible. It is just not quite your brand anymore.
Every automated check you might run is blind to that failure mode. The palette decisions in the first section therefore matter more than any test you bolt on afterwards.
The CSS Everyone Recommends Never Reaches Gmail Or Yahoo
Now the part that is rarely stated plainly.
The @media (prefers-color-scheme: dark) block is worth including in a dark mode email template. It does not reach everyone, though, and the split is worth seeing in full. This is who honors it, from Can I Email's support data as updated on 10 August 2026.
Every Gmail surface says no, and so does every Yahoo surface.
Practitioners have known this for a while. Email Love add the caveat in the middle of explaining how to write the media query, noting that it only works in clients that support it.
Read all that against your own list. For a DTC audience weighted toward Gmail, the remedy reaches a minority of the people you are sending to.
Writing it is still worthwhile, because the Apple and modern Outlook families make up a substantial share of opens and they honor it properly. Mistaking it for a solution is the error.
Gmail widens that gap by publishing nothing about how its inversion calculates replacement colors. Buttondown are explicit about the consequence. What it won't do is read your prefers-color-scheme CSS, they write, so any dark mode colors or image substitutions you set there will be ignored. No rule exists to reason from. You send the message and you look at it.
Gmail is not unusual in that respect. Every dark-mode technique shares the same partial coverage. Badsender work through the Outlook attribute method in detail and conclude that like any workaround in email marketing it is not universal and does not work everywhere. Spending your effort on design decisions that hold everywhere is the better trade.
New Outlook Is Fixing The Worst-Rendering Client Without You
One constraint here has an expiry date, which is worth knowing before you commission a workaround for it.
Classic Outlook for Windows has caused email developers more trouble than the rest combined. It renders on the Word engine and honors none of this. Its replacement does.
New Outlook runs on WebView2 and Chromium, and it behaves broadly like Outlook.com on the web, which supports the media query. Microsoft began the opt-out phase for classic Outlook on Windows in April 2026, so it is no longer the default experience for most users. Existing installations remain supported for some years yet.
Be careful with the dates circulating on this. A widely repeated claim says classic Outlook loses support in October 2026, and that claim is wrong. It conflates two unrelated retirements, and neither one ends support for classic Outlook on Windows.
Practically, this concerns the Outlook-specific attribute hacks. They are real, and developers including Rémi Parmentier and Mark Robbins worked them out. But they solve a problem that is slowly solving itself, so where developer time is limited you should spend it on the design decisions instead.
Get Your Klaviyo Templates Audited For Dark Mode Rendering
If you would rather know than guess, this is one of the things we look at. Our free Klaviyo audit reviews template design and dark mode email rendering as a standing part of its scope, with flow performance, deliverability and segmentation logic inside the same review.
Reviewing every flow at once rather than one send at a time matters here. Flows that break quietly are rarely the ones you happen to check.
Rebuilding a template library is usually one piece of a larger retention job, and we have done that across more than 140 DTC brands.
Those rebuilds sit behind $58.2M in Klaviyo Attributed Value. You can see the account-level detail in our client results.
Template work also runs through our email marketing automation service.
Get your free Klaviyo audit and we will tell you which templates are breaking in dark mode, and which flows it is costing you.