Skip to main content

Support dark mode

Roughly a third of readers open email with dark mode on. What they see depends on the client: Apple Mail applies the dark styles you write, Gmail repaints the email itself, and Outlook sits somewhere in between. This guide covers what to put in a Design System so the clients that listen to you get a design you chose, and the clients that do not still get something readable.

Use the dark mode preview in the Campaign Workspace and the Design System preview window to check each step. The Dark option shows your own dark styles; the two Forced dark options show what Gmail does regardless.

Step 1: Declare dark mode support​

Add both meta tags to the head of the Template Base, and the matching CSS property on the root:

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

Apple Mail applies your dark styles only when the color-scheme meta is present. Without it, Apple Mail shows the email exactly as in light mode, and so does the Dark preview option, which shows a notice instead.

One thing to know: with the meta tags in place but no dark styles, Apple Mail partially inverts the email on its own. Do not stop after this step.

Step 2: Write the dark block​

Put every colour that should change in an @media (prefers-color-scheme: dark) block, and mark each declaration !important so it wins over the inline styles email clients favour. Give the elements you recolour a class, so the block stays short:

<style>
  .bg-page { background-color: #eef0ec; }
  .bg-card { background-color: #ffffff; }
  .tx-ink { color: #1a2420; }
  .tx-body { color: #4a5550; }

  @media (prefers-color-scheme: dark) {
    .bg-page { background-color: #121714 !important; }
    .bg-card { background-color: #1b231e !important; }
    .tx-ink { color: #ecf0ea !important; }
    .tx-body { color: #a9b3aa !important; }
  }
</style>

Pick a dark palette rather than inverting the light one. Off-black backgrounds (#121714, not #000000) and off-white text (#ecf0ea, not #ffffff) read better and avoid the pure black and white values some clients flip on their own.

The Vandra demo Design System in your workspace uses this pattern in its Template Base.

Step 3: Mirror the block for Outlook​

Outlook.com and the Outlook apps on iPhone and Android do not honour the media query reliably. They recolour text and backgrounds that lack contrast against their dark theme, and they record the original colour on the element in data-ogsc (colour) and data-ogsb (background) attributes. Repeat each dark rule with those prefixes, one prefix per selector:

[data-ogsc] .tx-ink { color: #ecf0ea !important; }
[data-ogsc] .tx-body { color: #a9b3aa !important; }
[data-ogsb] .bg-page { background-color: #121714 !important; }
[data-ogsb] .bg-card { background-color: #1b231e !important; }

Only [attribute] and element[attribute] selectors work in Outlook.com, so target descendants of the attributed element as above, never .class[data-ogsb].

Step 4: Fix the images​

Images are the part no client recolours, which makes them the most common dark mode failure:

  • Dark logos and icons on transparent backgrounds vanish on a dark canvas. Give them a light outline or a subtle glow in the image itself, or place them in a container whose background you control in the dark block.
  • Images with a baked-in white background become bright rectangles. Export them with transparency or with the page background colour.
  • Text over a background image is recoloured while the image is not. Keep the text on a solid background or give the image enough headroom for both light and dark text.

Where a logo genuinely needs two versions, ship both and swap them in the dark block:

<!--[if !mso]><!-->
<img class="dark-img" src="logo-light.png" alt="Vandra" style="display: none;" />
<!--<![endif]-->
<img class="light-img" src="logo-dark.png" alt="Vandra" />
<style>
  @media (prefers-color-scheme: dark) {
    .dark-img { display: block !important; }
    .light-img { display: none !important; }
  }
  [data-ogsc] .dark-img { display: block !important; }
  [data-ogsc] .light-img { display: none !important; }
</style>

Step 5: Accept what Gmail does​

Gmail ignores the media query and the meta tags and recolours the email itself: partially on Android, fully on iPhone. Nothing in your CSS changes that today, so design for it instead:

  • Prefer mid-tone brand colours for buttons and accents. They survive Gmail's partial recolouring, which only touches very light backgrounds and very dark text.
  • Check the two Forced dark preview options for every module. If a module only works because of a light background, it will not work in Gmail.
  • Do not rely on the gradient background trick (background-image: linear-gradient(#fff, #fff)) to protect a colour. It holds on iPhone and breaks on Android.

In August 2026 Google marked its long-standing request for prefers-color-scheme support in the Gmail apps as fixed, without describing the change. If Gmail starts applying dark styles, everything above is what makes an email ready for it.

Step 6: Test in real clients​

The preview options are an approximation built on the clients' documented and observed behaviour. Before an important send, use Client Previews on the Review tab of a Campaign for real renders in Apple Mail, Outlook and Gmail. See Review & testing.