> For the complete documentation index, see [llms.txt](https://doc.batch.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.batch.com/guides-and-best-practices/message/email/design-and-layout/how-to-optimize-your-email-designs-for-dark-mode.md).

# How to optimize your email designs for dark mode?

*Dark mode is now available in most inboxes, and many of your recipients read their emails with it turned on. The catch: each email client applies it differently, and you can't fully control the result. This article explains what actually happens to your email in dark mode, and gives you our best practices to design templates that stay readable and on-brand in every inbox.*

### Why dark mode matters

Recipients choose dark mode for comfort: it's easier on the eyes in low light and saves battery. When an email isn't designed with it in mind, the damage is very visible: a logo disappears on a dark background, a white box appears around a product image, a button blends into the page, or a brand color turns brown.

Optimizing for dark mode keeps your message **accessible**, your **brand identity consistent**, and your campaigns **professional**, whatever the reader's settings.

***

### How email clients apply dark mode

There is no single "dark version" of your email. Depending on the client, one of three things happens:

| Behavior           | What it does to your email                                                                                       |
| ------------------ | ---------------------------------------------------------------------------------------------------------------- |
| **No change**      | The inbox interface turns dark, but your email stays exactly as you designed it.                                 |
| **Partial invert** | Only light areas are darkened, and dark text on them is lightened. Areas that are already dark stay as they are. |
| **Full invert**    | Every color is inverted, light and dark alike. An email that was already dark can end up light.                  |

<figure><img src="https://509463063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfiAYaWDWqtFZeXxyg67F%2Fuploads%2FWphoaHe4ncn0BS2Ewzvx%2Fvisuel-1-comportements.png?alt=media&amp;token=f7769211-889f-496a-a270-e3b3f029ce9b" alt=""><figcaption></figcaption></figure>

Here is how the main clients behave:

| Email client                              | Default behavior                                       | Can you apply your own dark styles? |
| ----------------------------------------- | ------------------------------------------------------ | ----------------------------------- |
| Apple Mail (iOS & macOS)                  | No change, unless your HTML declares dark mode support | ✅ Yes                               |
| Gmail (web)                               | No change                                              | ❌ No                                |
| Gmail app (Android)                       | Partial invert                                         | ❌ No                                |
| Gmail app (iOS)                           | Full invert                                            | ❌ No                                |
| Outlook.com & Outlook apps (iOS, Android) | Partial invert                                         | ⚠️ Partially                        |
| Outlook desktop (Windows)                 | Full invert                                            | ❌ No                                |
| Yahoo Mail, AOL                           | No change                                              | —                                   |

{% hint style="info" %}
Email clients update their rendering rules regularly, so this table can evolve. Since you can't control every client, the goal is not to force one look everywhere, but to **design emails that hold up in all three scenarios**.&#x20;
{% endhint %}

***

### Our best practices 👇

#### 1. Use transparent PNGs for your logo and icons

Images with a white background create a visible white box once the email turns dark. Export your logo, icons and cut-out visuals as **transparent PNGs** instead.

If your logo is dark (black or navy text), it may become invisible on a dark background. To keep it readable in every mode, add one of the following to the image file itself:

* a **light glow** or **thin white outline** around the dark parts: invisible on a white background, it makes the logo stand out on a dark one;
* a **light shape behind the logo** (rounded rectangle, circle) if you prefer keeping its original look.

<figure><img src="https://509463063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfiAYaWDWqtFZeXxyg67F%2Fuploads%2FKE2ziY2Oj4jrdeWasWFr%2Fvisuel-2-logo.png?alt=media&amp;token=b91e6662-ec64-4b7a-a737-03ff921f386a" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
💡 For photos that can't be transparent (product shots, banners), leave some padding around the subject and use a background color that works on both light and dark pages, so the image edge doesn't look like a hard cut.
{% endhint %}

#### 2. Avoid pure white and pure black

Some clients only invert specific values like `#FFFFFF` and `#000000`. Using **near-white** and **near-black** colors gives you more predictable results:

* Backgrounds: `#FAFAFA` or `#F5F5F5` instead of `#FFFFFF`
* Text: `#1A1A1A` or `#222222` instead of `#000000`

In the Email Composer, set these in **Styles → Global Styles & Layout** (background color) and in **Stripes Styles** (content background and font colors), so they apply to the whole template at once.

#### 3. Choose colors that work on both light and dark backgrounds

Very light or very dark brand colors are the most affected by inversion. **Mid-tone colors** keep enough contrast against both a white and a dark background.

Check every text and background combination with a contrast checker like [WebAIM](https://webaim.org/resources/contrastchecker/) and aim for at least the **WCAG AA** level (contrast ratio of 4.5:1 for body text).

#### 4. Keep your text as real text, not images

Text written in Text blocks is adjusted by the email client and stays sharp. Text embedded in an image is not: it can become unreadable once the background around it changes. Keep your key messages, prices and CTAs as **live text**, and use images for visuals only.

#### 5. Add a border to your buttons

When a client inverts your button and the background around it, the two can end up the same color and the CTA disappears. A **border in a contrasting color** keeps the button visible in every case.

In the Email Composer, set it once for all buttons in **Styles → Buttons** (border width and border color).

<figure><img src="https://509463063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfiAYaWDWqtFZeXxyg67F%2Fuploads%2FtRPfoMaCjYOrHi1HYfpJ%2Fvisuel-3-bouton.png?alt=media&amp;token=662d6dc2-a080-47b7-8e41-e4619137fd47" alt=""><figcaption></figcaption></figure>

#### 6. Avoid thin fonts

Light text on a dark background looks thinner than it is. Avoid light or extra-light font weights for body text, and prefer **regular** or **medium**.

#### 7. Respect your reader's choice

Some HTML tricks force an email to stay in light mode. We don't recommend them: recipients who turned on dark mode often did it for comfort or accessibility reasons. Design an email that works in dark mode rather than fighting it.

***

### Test before sending

The best way to check the dark mode rendering, is to use the **Send test** feature and open the email on real devices with dark mode turned on.

👉 **Our recommendations:**

* Test at least on **Gmail app (iOS)**, **Gmail app (Android)**, **Apple Mail (iPhone)** and **Outlook**: together, they cover the three behaviors.
* Check in particular: is the **logo visible**? Are there **white boxes** around images? Are **buttons** still distinguishable? Is all **text readable**?

<figure><img src="https://509463063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfiAYaWDWqtFZeXxyg67F%2Fuploads%2FBNUnxUYv6fSoaUZ1xZVt%2Fvisuel-4-do-dont.png?alt=media&amp;token=e519fac5-0ece-48da-a2f8-3662d21d3492" alt=""><figcaption></figcaption></figure>

***

### For HTML templates: add your own dark theme

If you [upload your own HTML template](https://doc.batch.com/guides-and-best-practices/message/email/templates-and-modules-management/how-to-upload-your-email-templates), you can define dark mode colors yourself for the clients that support it (mainly Apple Mail, and partially Outlook apps). Other clients will ignore this code and apply their default behavior, so the best practices above still apply.

<details>

<summary>See the code</summary>

**1. Declare dark mode support** in the `<head>` of your template:

```html
<meta name="color-scheme" content="light dark">
<meta name="supported-color-schemes" content="light dark">
```

**2. Add your dark styles** in a `<style>` tag, using classes you add to your HTML elements:

```html
<style>
  :root {
    color-scheme: light dark;
    supported-color-schemes: light dark;
  }

  @media (prefers-color-scheme: dark) {
    .email-body { background-color: #1A1A1A !important; }
    .email-text { color: #F2F2F2 !important; }
    .email-link { color: #8AB4F8 !important; }

    /* Swap logos: hide the light version, show the dark one */
    .logo-light { display: none !important; }
    .logo-dark  { display: block !important; max-height: none !important; }
  }
</style>
```

**3. Add both logo versions** in your HTML. The dark one is hidden by default:

```html
<img class="logo-light" src="https://example.com/logo-dark-text.png" alt="Brand" width="160">
<!--[if !mso]><!-->
<img class="logo-dark" src="https://example.com/logo-white-text.png" alt="Brand" width="160"
     style="display:none; max-height:0; overflow:hidden;">
<!--<![endif]-->
```

{% hint style="info" %}
Outlook apps (iOS, Android) and Outlook.com don't read `@media (prefers-color-scheme: dark)`. To target them, duplicate your dark rules with the `[data-ogsc]` prefix (for text colors) and `[data-ogsb]` prefix (for background colors), for example: `[data-ogsc] .email-text { color: #F2F2F2 !important; }`.
{% endhint %}

</details>

***

### Recap ✅

* Logos and icons in **transparent PNG**, with a glow or outline if they're dark
* **No pure white or pure black**: use near-white and near-black
* **Mid-tone colors** with an AA contrast ratio
* Key messages in **live text**, not images
* **Bordered buttons**
* No thin fonts
* **Test with Send test** on real devices in dark mode


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://doc.batch.com/guides-and-best-practices/message/email/design-and-layout/how-to-optimize-your-email-designs-for-dark-mode.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.