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 the color-scheme meta tag to the head of the Template Base and the CSS property on the root:

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

The two lines do different jobs. Since September 2026, Gmail on a Google account reads light only as "show the light design", which switches off its own recolouring; it does not read dark styles at all. Apple Mail reads the same meta as "no dark mode", so the CSS declaration on the root is what tells Apple Mail to apply the dark block you write in the next step. With the meta alone, Apple Mail shows the light design and the Dark preview option shows a notice instead. Gmail users on a non-Google account and the Outlook apps still recolour the email whatever the meta says.

If you would rather not opt out of Gmail's recolouring, use content="light dark" on the meta instead; the rest of this guide is the same.

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 recolours the email itself: partially on Android, fully on iPhone. The light only meta from step 1 switches that off for readers on a Google account, and nothing else does, so design for the rest:

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

Google's answer to its long-standing request for prefers-color-scheme support in the Gmail apps, posted 11 September 2026, is the light only opt-out, not support for dark styles. The dark block still matters for Apple Mail, Outlook for Mac and Samsung Email.

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.