Dark Mode in Email: A Developer's Survival Guide | EmailForDevs

The Dark Mode Challenge in Email

Dark mode adoption has reached critical mass. Over 80% of iOS users and a growing majority of Android and desktop users have enabled system-wide dark mode. Email clients respect this preference, but how they implement dark mode varies wildly—and this inconsistency is what makes dark mode the single biggest email rendering challenge in 2025.

There are three distinct dark mode behaviors across email clients. No color changes: The client renders your email exactly as you coded it (Outlook desktop). Partial inversion: The client changes background colors but leaves your text and other elements alone (Gmail app on Android). Full inversion: The client completely inverts all colors—light backgrounds become dark, dark text becomes light (Apple Mail, Outlook on iOS). Understanding which behavior each client uses is the foundation of dark mode email development.

The color-scheme Meta Tag

The first step is declaring that your email supports dark mode. The color-scheme meta tag and CSS property tell email clients that you have intentionally designed for both light and dark appearances:

<head>
  <meta name="color-scheme" content="light dark">
  <meta name="supported-color-schemes" content="light dark">
  <style>
    :root {
      color-scheme: light dark;
    }
  </style>
</head>

Without this declaration, some clients (notably Apple Mail) will attempt to auto-invert your colors, which often produces poor results—your carefully chosen brand colors get mangled. With the declaration, you are telling the client “I have dark mode styles, use them instead of auto-inverting.”

CSS Media Queries for Dark Mode

The prefers-color-scheme media query lets you apply specific styles when the user has dark mode enabled. This works in Apple Mail, iOS Mail, Outlook on iOS and Android, and some webmail clients:

<style>
  /* Base (light mode) styles */
  .email-body { background-color: #ffffff; }
  .email-text { color: #1a1a1a; }
  .email-muted { color: #666666; }
  .email-card { background-color: #f5f5f5; border: 1px solid #e5e5e5; }

  /* Dark mode overrides */
  @media (prefers-color-scheme: dark) {
    .email-body { background-color: #1a1a1a !important; }
    .email-text { color: #f0f0f0 !important; }
    .email-muted { color: #a0a0a0 !important; }
    .email-card { background-color: #2a2a2a !important; border-color: #3a3a3a !important; }

    /* Force specific elements to keep their colors */
    .brand-logo { background-color: transparent !important; }
    .cta-button { background-color: #3b82f6 !important; color: #ffffff !important; }
  }
</style>

The !important declarations are necessary because dark mode styles need to override both your inline styles and any auto-inversion the client applies. This is one of the few legitimate uses of !important in CSS.

Targeting Specific Clients

Some developers use client-specific hacks to target dark mode styles to particular email clients. For example, Outlook.com (web) supports [data-ogsc] as a dark mode selector. However, these hacks are fragile and can break when clients update their rendering. A more robust approach is to design for graceful degradation: your email should be readable in both modes even if your dark mode styles are not applied.

Images and Logos in Dark Mode

Images are the trickiest element in dark mode email. A logo with a dark color on a transparent background becomes invisible on a dark background. There are several strategies to handle this:

<!-- Strategy 1: Add a light background/padding to the image -->
<img src="logo-dark.png" alt="Logo"
     style="background-color:#ffffff; padding:8px; border-radius:4px;" />

<!-- Strategy 2: Use a logo with built-in padding/background -->
<!-- Export your logo with a white or light rounded rectangle behind it -->

<!-- Strategy 3: Swap images with CSS (where supported) -->
<style>
  @media (prefers-color-scheme: dark) {
    .logo-light { display: none !important; }
    .logo-dark { display: block !important; }
  }
</style>

<img src="logo-for-light-bg.png" class="logo-light" alt="Logo"
     style="display:block;" />
<img src="logo-for-dark-bg.png" class="logo-dark" alt="Logo"
     style="display:none;" />

Strategy 3 (image swapping) provides the best visual result but only works in clients that support <style> blocks and prefers-color-scheme. For clients where this does not work, the light-mode logo displays. This is an acceptable fallback as long as your light-mode logo has sufficient contrast on a potentially inverted background—which brings us back to Strategy 1 as a safety net.

Bulletproof Fallback Strategies

Since not all email clients support prefers-color-scheme media queries, and some apply their own unpredictable color inversion, you need fallback strategies that ensure readability regardless of what the client does.

Avoid pure black (#000000) and pure white (#ffffff): Use near-black (#1a1a1a) and near-white (#f5f5f5) instead. When a client auto-inverts colors, pure black becomes pure white (and vice versa), which creates harsh contrast. Slightly off-pure colors invert to more comfortable tones.

Always define both background and text color: Never rely on the default text color. If a client inverts only the background but not the text (partial inversion), you end up with white text on a white background—invisible content. Explicitly set both on every text element.

<!-- Bad: relies on default text color -->
<td style="background-color: #ffffff;">
  <p>This text might become invisible in dark mode</p>
</td>

<!-- Good: explicit text and background colors -->
<td style="background-color: #ffffff; color: #1a1a1a;">
  <p style="color: #1a1a1a;">This text is always readable</p>
</td>

Test with forced dark mode: Use Brew’s dark mode preview or Litmus to see exactly how each client renders your email in dark mode. The differences between Apple Mail’s full inversion, Gmail’s partial inversion, and Outlook’s non-inversion are significant enough that you should review all three behaviors before every send.

A Complete Dark Mode Email Template

Here is a minimal but complete email template with proper dark mode support:

<!DOCTYPE html>
<html lang="en" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta name="color-scheme" content="light dark">
  <meta name="supported-color-schemes" content="light dark">
  <style>
    :root { color-scheme: light dark; }
    body { background-color: #f5f5f5; }
    @media (prefers-color-scheme: dark) {
      body { background-color: #1a1a1a !important; }
      .wrapper { background-color: #2a2a2a !important; }
      .text-primary { color: #f0f0f0 !important; }
      .text-secondary { color: #a0a0a0 !important; }
      .divider { border-color: #3a3a3a !important; }
    }
  </style>
</head>
<body style="margin:0; padding:0; background-color:#f5f5f5;">
  <table role="presentation" width="100%" style="background-color:#f5f5f5;">
    <tr>
      <td align="center" style="padding:24px;">
        <table role="presentation" class="wrapper" width="600" style="background-color:#ffffff; border-radius:8px;">
          <tr>
            <td style="padding:40px;">
              <h1 class="text-primary" style="font-family:Arial,sans-serif; font-size:24px; color:#1a1a1a; margin:0 0 12px;">
                Your heading here
              </h1>
              <p class="text-secondary" style="font-family:Arial,sans-serif; font-size:16px; line-height:1.5; color:#555555; margin:0 0 24px;">
                Your body text here. Readable in both light and dark mode.
              </p>
            </td>
          </tr>
        </table>
      </td>
    </tr>
  </table>
</body>
</html>

This template demonstrates the key principles: color-scheme meta tags and CSS property, explicit colors on every element, class-based dark mode overrides via prefers-color-scheme, and near-black/near-white values for graceful auto-inversion in clients that ignore your dark mode styles. It is not glamorous, but it works reliably across the widest range of email clients—and in email development, reliability always trumps elegance.