MailMode Learn Technical reference

Dark Mode CSS for HTML Email

A technical reference for the CSS, meta tags, client targeting methods and fallback patterns used to build dark-mode-aware HTML email.

Published: 8^th June 2026 Last updated: 9^th June 2026

layersStandards / Gmail / Outlook

strategyLayered fallbacks

ruleTest compiled HTML

Standards layer

Standards support

prefers-color-scheme, color-scheme and Apple/WebKit-style dark CSS for clients that honour authored themes.

Gmail layer

Gmail fixes

u + .body, Android selectors, doctype/body-class targeting and blend-mode tricks for specific Gmail failures.

Outlook layer

Outlook patches

data-og* reaction selectors, MSO conditionals and VML fallbacks for separate Outlook rendering families.

Defensive layer

Fallback design

Inline styles, bgcolor, image swaps and resilient colour tokens for clients that rewrite or ignore CSS.

This is an independent MailMode guide, not official documentation from Apple, Google or Microsoft. Dark mode email behaviour changes across clients, apps, operating systems and account types, so treat these techniques as practical patterns to test rather than universal guarantees.

Key takeaways

Dark mode email CSS is a layered system

Dark mode in email is not one feature; it mixes standards support, client rewriting and post-render colour transformation.
@media (prefers-color-scheme: dark) works well in Apple Mail and some modern clients, but not reliably in Gmail or Yahoo.
color-scheme and supported-color-schemes are useful signals, especially for Apple/WebKit clients, but they do not control every inbox.
Gmail requires client-specific targeting, a doctype/body class for reliable selectors, and sometimes blend-mode workarounds for specific contrast failures.
Outlook.com can expose data-ogsc, data-ogsb, data-ogac and data-ogab after it rewrites colours.
Outlook Windows is a separate Word-rendered path where MSO conditionals and VML remain scoped fallbacks.
CSS variables are useful where supported, but not safe as the only colour delivery system.
!important can help the cascade, but it cannot block a later client-side dark-mode transform.
The safest strategy is defensive: robust light mode, standards-based dark CSS, client-specific patches and real-client testing.

Technique overview

Which dark mode technique belongs where

Support notes in this matrix are MailMode’s synthesis of public email-client documentation, Can I Email feature data and email developer testing references. They are not copied support tables from any one source.

TechniqueWhat it doesBest supported inWeaknessRecommended use

@media (prefers-color-scheme: dark)Applies authored dark CSS when the client exposes dark preference.Standards-basedNot reliable in Gmail/Yahoo.Use for Apple Mail and standards-friendly clients.

color-scheme metaSignals light/dark scheme support.Standards-basedDoes not force all clients to obey.Pair with complete dark CSS.

supported-color-schemes metaLegacy email scheme hint.Standards-basedUseful hint, not a design.Keep alongside modern scheme declarations.

:root { color-scheme: light dark; }Keeps CSS and document scheme hints aligned.Standards-basedRoot/html support varies.Use as part of the Apple/WebKit stack.

CSS custom propertiesCentralises colour tokens.Partial supportWeak in older Outlook and some webmail.Helpful enhancement, not the only colour source.

Inline stylesSets baseline email-safe styling.Defensive fallbackCan still be rewritten by clients.Use for light-mode base and critical fallbacks.

!importantRaises override priority.Partial supportNot all clients preserve embedded CSS.Use sparingly for critical dark CSS overrides.

bgcolorAdds table/cell background fallback.Defensive fallbackCan conflict if CSS values diverge.Match with CSS background colours.

Image swappingShows light/dark assets as needed.Standards-basedOutlook hiding quirks need testing.Use for logos and icons that cannot survive both themes.

[data-ogsc] / [data-ogsb] / [data-ogac] / [data-ogab]Targets Outlook web colour and attribute rewrites.Outlook-specificReaction hooks only; not standards-based or Apple/Gmail targeting.Patch Outlook.com after it changes colours or colour attributes.

u + .bodyTargets Gmail document rewriting.Gmail-specificRequires a doctype/body class and does not cover every account path.Use for targeted Gmail-only fixes that survive CSS filtering.

div > u + .bodyNarrows some Gmail Android paths.Gmail-specificVersion/account dependent.Use only after testing the Android target.

mix-blend-modePreserves text contrast in Gmail iOS patterns.Use with cautionCan fail outside the intended Gmail case.Reserve for specific Gmail iOS contrast issues.

One-colour linear-gradient()Protects a surface colour from some Gmail rewrites.Use with cautionGmail Android gradient behaviour can be buggy.Test before production use.

MSO conditionalsTargets classic Outlook Windows.Outlook-specificIgnored by non-MSO clients.Use only for Outlook Windows fallbacks.

VMLCreates Outlook-safe fills, backgrounds and buttons.Outlook-specificVerbose, fragile and not useful outside Outlook Windows.Use for bulletproof buttons/background fills in Outlook Windows only.

Standards layer

Standards-based dark mode CSS

prefers-color-scheme lets a client apply your authored dark CSS when it exposes the user’s dark preference. It is strongest in Apple Mail, Samsung Email, Thunderbird-style environments and other standards-friendly clients.

Gmail and Yahoo should not be treated as reliable prefers-color-scheme environments for HTML email. They may strip, ignore or rewrite the query before your rules can help.

color-scheme, supported-color-schemes and root-level scheme declarations are useful signals, especially in Apple/WebKit clients, but they are capability hints rather than controls for Gmail or Outlook.

Works best in standards-friendly clients Pair meta tags with real dark CSS Do not rely on this for Gmail Keep inline fallbacks

Standards-based dark mode setup

<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;
  }

  @media (prefers-color-scheme: dark) {
    body,
    .email-shell {
      background-color: #111114 !important;
      color: #f5f5f7 !important;
    }

    .panel {
      background-color: #1f1f24 !important;
      border-color: #3a3a42 !important;
    }
  }
</style>

Image swaps

Use dark assets where automatic colour changes are risky

Logos need variants

Light and dark logo variants are often safer than relying on automatic colour changes or client inversion.

Apple Mail is a strong target

CSS show/hide image swapping works well in Apple-style authored dark mode paths when dark CSS is evaluated.

`<picture>` is not the safest email baseline

Use duplicate assets with email-safe hiding rather than assuming browser image markup survives every inbox.

Outlook needs caution

Classic Outlook can ignore display:none on images and nested tables, so critical swaps need MSO-aware fallbacks.

Email-safe light/dark logo swap

<style>
  .dark-logo {
    display: none;
    max-height: 0;
    overflow: hidden;
  }

  @media (prefers-color-scheme: dark) {
    .light-logo {
      display: none !important;
      max-height: 0 !important;
      overflow: hidden !important;
    }

    .dark-logo {
      display: block !important;
      max-height: none !important;
    }
  }
</style>

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

Gmail layer

Gmail-specific targeting and blend-mode fixes

Gmail does not provide a reliable prefers-color-scheme targeting model for HTML email. It can rewrite or sanitise CSS before the message reaches the app.

u + .body is a public email-development targeting pattern based on Gmail’s document rewriting; it needs a doctype and a body class to target from. div > u + .body can help isolate some Gmail Android cases.

GANGA, Gmail Apps with Non-Google Accounts, is weaker: style blocks, CSS variables and blend-mode fixes can be unavailable, so the email needs inline/base fallbacks.

Blend-mode patterns can help with specific Gmail iOS white-text contrast issues. They are research-inspired workarounds for a narrow rendering problem, not a universal dark mode system.

Target Gmail explicitly Expect account-type differences Keep CSS in <head> Use blend modes narrowly Test Gmail iOS and Android separately

Gmail targeting selectors

u + .body .mm-gmail-only {
  display: block !important;
}

div > u + .body .mm-gmail-android-only {
  display: block !important;
}

Gmail iOS blend-mode pattern

<style>
  u + .body .mm-gmail-blend-screen {
    background: #000000;
    mix-blend-mode: screen;
  }

  u + .body .mm-gmail-blend-difference {
    background: #000000;
    mix-blend-mode: difference;
  }
</style>

<body class="body">
  <div style="background:#663399; background-image:linear-gradient(#663399,#663399); color:#ffffff;">
    <div class="mm-gmail-blend-screen">
      <div class="mm-gmail-blend-difference">
        White text intended to remain readable in Gmail dark mode.
      </div>
    </div>
  </div>
</body>

Outlook layer

Outlook-specific selectors, MSO and VML

Outlook.com and some Outlook web/mobile surfaces can add data-ogsc, data-ogsb, data-ogac and data-ogab when they change CSS or attribute colours. These are reaction selectors, not standards-based theme selectors.

Classic Outlook Windows is different. It may need MSO conditionals and VML for bulletproof buttons, fills and background areas because it uses Word-style rendering.

For critical background colours, duplicating intent in CSS and attributes such as bgcolor can make Outlook-class rewrites easier to patch.

Outlook-specific fixes should not be used as if they apply to Apple Mail or Gmail.

Use data-og* for Outlook web Use MSO/VML for classic Windows Keep fixes scoped Do not copy to Apple/Gmail

Outlook.com colour rewrite targeting

[data-ogsc] .dark-text {
  color: #ffffff !important;
}

[data-ogsb] .dark-panel {
  background-color: #1f1f24 !important;
}

[data-ogac] .attribute-text {
  color: #ffffff !important;
}

MSO fallback wrapper

<!--[if mso]>
<table role="presentation" width="100%" cellpadding="0" cellspacing="0">
  <tr>
    <td bgcolor="#1f1f24">
<![endif]-->

<div class="panel" style="background-color:#1f1f24;">
  Outlook-safe content
</div>

<!--[if mso]>
    </td>
  </tr>
</table>
<![endif]-->

CSS support matrix

Client support is uneven by design

This matrix condenses MailMode’s interpretation of public support references and practical testing notes. CSS feature support does not always mean a client will allow full dark mode control.

FeatureApple MailGmailOutlook.comOutlook WindowsYahooSamsung / Thunderbird

prefers-color-schemeSupportedNot reliablePartialNot reliableNot reliableSupported / test required

color-scheme metaSupportedPartialPartialNot reliableNot reliablePartial

CSS variablesSupportedPartial; GANGA riskPartialNot reliablePartialSupported / test required

<style> blockSupportedPartialPartialPartialPartialSupported

Inline stylesSupportedSupportedSupportedSupportedSupportedSupported

display:noneSupportedPartialPartialTest requiredPartialSupported / test required

max-heightSupportedPartialPartialTest requiredPartialSupported / test required

background-imageSupportedPartial; URL sanitisation riskPartialVML fallbackPartialSupported / test required

linear-gradient()SupportedPartial; Android inline bug riskPartialVML onlyPartialSupported / test required

mix-blend-modeSupportedClient-specificNot reliableNot reliableNot reliableTest required

Client targeting selectorsNot neededClient-specificClient-specificMSO-specificLimitedTest required

MSO/VMLNot applicableNot applicableNot applicableSupportedNot applicableNot applicable

Failure patterns

Common dark mode CSS mistakes

Treating `prefers-color-scheme` as universal

What breaks: Gmail, Yahoo or Outlook ignore the intended dark CSS.
Affected clients: Gmail, Yahoo, Outlook Windows.
Why it happens: Support is not consistent across email clients.
Safer approach: Use standards CSS plus client-specific patches and fallbacks.

Meta tags without complete dark CSS

What breaks: Surfaces, borders and text no longer match.
Affected clients: Apple/WebKit-style clients.
Why it happens: The email signals dark support without defining a full dark state.
Safer approach: Declare dark support only with complete dark values.

Relying entirely on CSS variables

What breaks: Critical colours disappear when variables are stripped or unsupported.
Affected clients: Older Outlook, some webmail clients.
Why it happens: Variable support is uneven in email.
Safer approach: Use variables as enhancement, with inline/base fallbacks.

Using one logo for every background

What breaks: Transparent or single-colour logos disappear.
Affected clients: All dark mode paths.
Why it happens: The background changes but the asset does not.
Safer approach: Use logo swaps, outlines, glows or controlled containers.

Assuming Gmail is Chrome

What breaks: Browser-grade CSS expectations fail in the app.
Affected clients: Gmail iOS, Android, GANGA.
Why it happens: Gmail rewrites/sanitises the message.
Safer approach: Use tested Gmail selectors and keep fixes scoped.

Assuming Outlook.com is Outlook Windows

What breaks: Web Outlook patches do nothing in classic Windows Outlook.
Affected clients: Outlook.com, Outlook Windows.
Why it happens: They use different rendering families.
Safer approach: Use data-og* for web Outlook and MSO/VML for Windows.

Using blend-mode hacks everywhere

What breaks: Unexpected colour effects outside the intended Gmail iOS case.
Affected clients: Cross-client campaigns.
Why it happens: Blend mode support and colour composition vary.
Safer approach: Reserve blend modes for specific Gmail iOS contrast fixes.

Relying on inline gradients in Gmail Android

What breaks: Surface colour protection is inconsistent.
Affected clients: Gmail Android.
Why it happens: Gradient rewriting has known edge cases.
Safer approach: Use gradients cautiously and test the Android app.

Hiding images with methods Outlook ignores

What breaks: Both light and dark logos appear, or neither appears.
Affected clients: Classic Outlook Windows.
Why it happens: Outlook has table/image hiding quirks.
Safer approach: Use MSO-aware fallback structures for critical images.

Putting critical CSS in the wrong Gmail path

What breaks: Dark-mode fixes disappear in Gmail app account variants.
Affected clients: Gmail, especially GANGA.
Why it happens: Styles in <body>, large style blocks and non-Google account paths are fragile.
Safer approach: Keep targeted CSS compact in <head> and preserve inline fallbacks.

Defensive design system

Build the email in layers

Base

Robust light mode first

The email should remain readable if a client leaves rich HTML unchanged.

Tokens

Avoid extremes

Use off-white, near-black and mid-tone tokens instead of depending on pure black and white.

Standards

Add Apple/WebKit dark CSS

Use scheme declarations and prefers-color-scheme for clients that honour authored dark mode.

Assets

Swap fragile images

Prepare dark-mode logo/icon variants where a single transparent asset is not enough.

Outlook web

Add `data-og*` patches

Patch text, panels and borders after Outlook.com rewrites colours.

Gmail

Add Gmail fixes only when justified

Use Gmail selectors and blend modes for specific failures, not broad styling.

Windows Outlook

Use MSO/VML where needed

VML remains relevant for bulletproof buttons, backgrounds and fills.

Redundancy

Duplicate critical intent

Use inline CSS, matched bgcolor values and separate assets where client rewrites need concrete fallbacks.

Test compiled production HTML

Validate the final HTML output, not only framework source; follow the MJML or React Email workflow when either generates the message.

Known limitations

What CSS still cannot guarantee

Client transforms

The cascade is not the final step

A client can still run a dark-mode transform after your inline CSS, embedded CSS and !important rules have been computed.

Gmail constraints

Gmail is not browser Chrome

Gmail can filter selectors, strip account-specific style support, rewrite gradients and impose practical style-size constraints.

Outlook split

One Outlook fix is not enough

Outlook.com reaction selectors and Outlook Windows MSO/VML fallbacks solve different problems in different rendering engines.

Standards scope

Standards support is strongest in Apple/WebKit

prefers-color-scheme and color-scheme are valuable, but they do not provide a universal dark-mode control plane for email.

MailMode simulation

How these techniques map to MailMode

No-change preview is useful for standards-led clients where authored dark CSS is likely to be honoured with limited post-processing, such as Apple Mail, Samsung Email and Thunderbird.

Partial-invert preview is useful for selective colour-changing families, including Outlook.com-style reaction hooks and Gmail Android-style transformations.

Full-invert preview is useful for stress-testing aggressive transformations where already-dark designs, logos and buttons can break. MailMode previews are practical approximations, not exact replicas of every email client algorithm.

No-change/default Partial invert Full invert Client-specific patches

References

Sources & Further Reading

Last Updated: 9^th June 2026Sources Reviewed: 8^th June 2026