Dark Mode Guide

How email clients handle dark mode

Different clients apply dark mode differently:

• Color inversion , light backgrounds become dark, dark text becomes light
• Media queries , prefers-color-scheme: dark styles are applied
• Selective override , only certain elements are modified
• No change , the email content is left untouched by the client's dark mode

Testing dark mode with Emailens

import { transformForClient, simulateDarkMode } from "@emailens/engine";

const transform = transformForClient(html, "gmail-web");
const darkMode = simulateDarkMode(transform.html, "gmail-web");

// Check for dark-mode-specific warnings
console.log(darkMode.warnings);

Or via the API , the response includes a darkMode object with variants for each client.

Best practices

Use prefers-color-scheme

Add dark mode styles in a media query:

<style>
  @media (prefers-color-scheme: dark) {
    .email-body { background-color: #1a1a1a !important; }
    .email-text { color: #e0e0e0 !important; }
  }
</style>

This is respected by Apple Mail, Outlook 365, and some others.

Use transparent images

Logos and icons with transparent backgrounds work better in dark mode than those with white backgrounds.

Avoid hardcoded light backgrounds

Instead of background-color: white, consider using transparent or easily-invertible colors.

Add color-scheme meta

Tell email clients your email supports dark mode:

<head>
  <meta name="color-scheme" content="light dark">
  <meta name="supported-color-schemes" content="light dark">
</head>

Test both variants

Always preview both light and dark mode. The Emailens web app shows both side by side, and the API returns both variants per client.

Client-specific behavior

Support levels come from the same data as the dark mode email guide.