Dark mode: three clients, three different inversions

Why this is hard

On the web, dark mode is a solved problem: you write a @media (prefers-color-scheme: dark) block, the browser applies it, done. In email there is no equivalent standard behavior. Every client decided independently what to do when its user flips the dark switch, and the three big families made three incompatible choices.

The audience is too large to ignore. Litmus measured roughly a third of tracked opens happening in dark mode back in 2022, with steady growth, and most smartphone users keep their OS in dark mode today. And you can't segment your way out: nothing in an email address, an open event, or a click tells you whether a recipient reads in dark mode. You optimize blind, for everyone at once.

The deeper problem is a loss of authorship. In several major clients, dark mode is not something you design; it's something that happens to your email after you send it. A machine repaints your work, and each machine repaints it differently.

The three behaviors

When the client UI is in dark mode, your email meets one of three fates:

• No changes. The email renders exactly as designed, light background and all, inside a dark UI. Gmail desktop webmail, Yahoo, and AOL behave this way. Apple Mail mostly does too, with a catch: emails with a transparent or pure white background get auto-inverted by a heuristic.
• Partial color invert. Light backgrounds are darkened and dark text lightened, but areas that are already dark are left alone. Outlook.com, the Outlook apps on iOS and Android, and Gmail on Android work this way.
• Full color invert. Everything is transformed, including designs that were already dark, which come out light. The Gmail app on iOS, classic Outlook on Windows (2021 and Microsoft 365), and Windows Mail do this. If you shipped a dark email, these clients will proudly serve it in light mode.

Note that the same app behaves differently per OS: Gmail partial-inverts on Android and full-inverts on iOS. Testing "Gmail" once is not testing Gmail.

Two palettes, three fates

The working mental model: you author two palettes, a light one and a dark one, but only some clients ever look at the second.

• Authored. Apple Mail, Outlook on macOS, Outlook.com, and a few others honor your prefers-color-scheme media query. Dark-mode readers there get the dark palette you designed, pixel for pixel.
• Correctable. When the Outlook apps and Outlook.com transform your colors, they stamp the elements they changed with data attributes holding the original values. You can target those attributes to overrule the transform after the fact.
• Automatic. Gmail's apps ignore your dark palette entirely. They take your light palette and run their own undocumented color transform over it. The dark email a Gmail user sees is machine-generated from your light design.

The consequence is subtle and important: your light palette is not just a theme, it is the source material for someone else's recoloring algorithm. Pure white flips to near black and pure black text flips to white, which is usually fine. But saturated brand colors, subtle grays, and dark-on-transparent logos can come out muddy, low-contrast, or invisible. Dark mode in email is harm reduction plus progressive enhancement, not a second theme you fully control.

The standards path, and where it stops

Start with the part that works like the web. Declare support for both schemes in the <head>; the second meta tag covers older Apple Mail versions:

<!-- In the <head>: declare that this email supports both schemes -->
<meta name="color-scheme" content="light dark">
<meta name="supported-color-schemes" content="light dark">

<style>
  :root {
    color-scheme: light dark;
    supported-color-schemes: light dark;
  }
</style>

Then author the dark palette in a media query. The !important flags are load-bearing: these rules must beat the inlined styles that email HTML relies on (see CSS inlining):

/* The authored dark palette. Honored by Apple Mail, Outlook on
   macOS, Outlook.com, and a handful of smaller clients. */
@media (prefers-color-scheme: dark) {
  .email-body {
    background-color: #1f1f1f !important;
  }
  .card {
    background-color: #2b2b2b !important;
  }
  h1, p {
    color: #eeeeee !important;
  }
  .btn {
    background-color: #8b9cf4 !important;
    color: #1f1f1f !important;
  }
}

This is where the standard stops. Can I email puts support for @media (prefers-color-scheme) at around 42% of tracked clients, and the biggest one actively removes it: Gmail's CSS sanitizer rewrites the query so it can never match.

/* What you send */
@media (prefers-color-scheme: dark) {
  .card { background-color: #2b2b2b !important; }
}

/* What Gmail's sanitizer serves to the reader */
@media none {
  .card { background-color: #2b2b2b !important; }
}

Yahoo and AOL filter the query the same way. So the authored dark palette reaches Apple Mail and friends, and nobody else. For the rest, you're negotiating with an algorithm.

Outlook: the correctable transform

Outlook.com and the Outlook mobile apps partial-invert your email, but they do something unusually developer-friendly in the process: every element whose color they changed gets a data attribute recording the original value. Text color changes leave data-ogsc, background changes leave data-ogsb.

/* Outlook stores the colors it changed in data attributes:
   data-ogsc holds the original text color, data-ogsb the original
   background. Their presence doubles as a dark-mode signal you can
   target with descendant selectors. */

[data-ogsc] .btn {
  color: #ffffff !important;
}
[data-ogsb] .card {
  background-color: #2b2b2b !important;
}

This is undocumented and could change at any time, but it has been stable for years and remains the standard technique in every current guide. Classic Outlook on Windows is another story: it strips media queries entirely and applies its full invert with no fingerprints and no override channel (see Outlook and MSO rendering).

Gmail: designing for the inverter

Gmail supports <style> blocks (with conditions), but as shown above it surgically removes the one media query that would let you author dark mode. What its apps do instead is transform your light design themselves: partial invert on Android, full invert on iOS, and no transform at all in desktop webmail, where your light email simply floats in a dark UI.

The transform is proprietary. Community reverse-engineering, collected in Rémi Parmentier's email-bugs repository, shows it is not a naive inversion: hued colors and grays are handled differently, and the exact mapping is undocumented and has changed over time. You cannot opt out and you cannot predict it precisely. You have two levers left.

Lever one: make your light palette inversion-safe. Since Gmail generates its dark rendering from your light design, design the light version to survive recoloring. Avoid pure #ffffff on #000000 contrast extremes, prefer mid-tone accents that keep acceptable contrast when flipped, and never rely on a color's exact value for meaning.

Lever two: the blend-mode hack. For elements that absolutely must keep their colors, Rémi Parmentier's CSS blend-mode technique exploits two Gmail quirks at once: the inverter skips linear-gradient backgrounds, and mix-blend-mode math can cancel the inversion back out:

<style>
  /* u + .body only matches in Gmail, which replaces the doctype
     with a <u> element. Other clients never see these rules. */
  u + .body .gmail-blend-screen {
    background: #000000;
    mix-blend-mode: screen;
  }
  u + .body .gmail-blend-difference {
    background: #000000;
    mix-blend-mode: difference;
  }
</style>

<!-- The linear-gradient repeats the background color because
     Gmail's inverter skips gradients, preserving the original
     value for the blend math. -->
<div class="body" style="background-color: #663399;
     background-image: linear-gradient(#663399, #663399);">
  <div class="gmail-blend-screen">
    <div class="gmail-blend-difference">
      <p style="color: #ffffff;">
        This text stays white on the original purple,
        even after Gmail inverts the email.
      </p>
    </div>
  </div>
</div>

It's clever and it works, but know its limits before reaching for it: it reliably preserves white text on a chosen background color, not arbitrary palettes, and it adds two wrapper divs per protected block.

Images and logos

Clients never recolor raster images, which sounds like good news until your dark navy logo sits on a transparent background and the background behind it turns black. The logo is still there; nobody can see it.

• Bake protection into the asset. A subtle white stroke or outer glow around dark artwork keeps it legible on any background. Designers hate this technique; it's also the only one that works everywhere, because it travels inside the image itself.
• Avoid pure white and pure black. In image backgrounds and in CSS. Near-white like #fffffe dodges Apple Mail's auto-invert heuristic, and off-black keeps full inverters from producing glaring white.
• Swap images where you can. Ship a light and a dark variant and toggle visibility. This only works where you have a dark-mode signal: prefers-color-scheme clients and the Outlook data-ogsc family.

/* Ship both logos, show one. Works in Apple Mail and every other
   client that honors prefers-color-scheme. */
@media (prefers-color-scheme: dark) {
  .light-img { display: none !important; }
  .dark-img  { display: block !important; }
}

/* The Outlook.com / Outlook app variant of the same swap */
[data-ogsc] .light-img { display: none !important; }
[data-ogsc] .dark-img  { display: block !important; }

The markup needs one extra guard: classic Outlook ignores display: none on the hidden image, so wrap the dark variant in a conditional comment it can't see:

<img class="light-img" src="logo-dark-on-light.png" alt="Acme">

<!-- Hidden from classic Outlook, which would otherwise show both -->
<!--[if !mso]><!-->
<img class="dark-img" src="logo-light-on-dark.png" alt="Acme"
     style="display: none;">
<!--<![endif]-->

Gotchas to watch for

• Dark designs get flipped to light. The full inverters (Gmail iOS, classic Outlook on Windows) transform already-dark emails too. Shipping a dark-by-default design doesn't opt you out of dark mode handling; it means those clients invert you into an unplanned light mode.
• The test matrix multiplies. Light and dark, times partial and full invert, times OS. The same Gmail account renders three different ways across desktop web, Android, and iOS. Preview tools that simulate both invert styles are worth more here than in any other email problem.
• Your dark-mode fixes are invisible in light mode, until they aren't. Halos and strokes on logos, off-white backgrounds, mid-tone accents: each is imperceptible in light mode individually, but they constrain the design. Decide on them at design time, not as a retrofit after the first broken screenshot.
• Everything here is unofficial. The data-ogsc attributes, the gradient exemption, the u + .body selector: none of it is documented or guaranteed by the vendors. These techniques are observations about current behavior, and they have shifted before. Re-verify after any client update.
• You can't measure it. No header, pixel, or click reveals a recipient's color scheme, so you can't A/B test dark mode or report on it. Treat the roughly-a-third figure as a floor and make every send dark-mode-safe.

Sources

• Litmus: "Ultimate Guide to Dark Mode" - the three-behavior client classification and adoption data; updated February 2025
• Email on Acid: "Master the Art of Dark Mode Email" - per-client behavior table and image techniques; updated October 2025
• Can I email... @media (prefers-color-scheme) - the support table, including Gmail's @media none rewrite
• Can I email... color-scheme meta tag
• Parcel: Guide to color scheme in email
• hteumeuleu.com: "Fixing Gmail's dark mode issues with CSS Blend Modes" - the original write-up of the blend-mode technique shown above
• hteumeuleu.com: "Making emails react to Outlook.com's dark mode" - how the data-ogsc and data-ogsb attributes behave
• email-bugs: "Gmail's dark mode" (issue #68) - community reverse-engineering of Gmail's color transform