> ## Documentation Index > Fetch the complete documentation index at: https://docs.lettr.com/llms.txt > Use this file to discover all available pages before exploring further. # Dark Mode Email Design > Design emails that look great in both light and dark mode with defensive CSS strategies and testing techniques Most email clients now offer a dark mode that automatically adjusts email colors. Gmail, Apple Mail, Outlook, and Yahoo Mail each handle dark mode differently — some invert colors, some blend backgrounds, and some leave emails untouched. Without defensive design, your carefully crafted email can end up with invisible text, clashing colors, or unreadable content in dark mode. *** ## How Email Clients Handle Dark Mode Email clients use three different strategies to render emails in dark mode, and the strategy varies by client and platform. | Strategy | What Happens | Clients | | --------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------- | | **No change** | Email renders exactly as coded, even in dark mode | Apple Mail (partial), Gmail (with dark-mode meta support) | | **Partial inversion** | Client changes background colors but preserves some text colors | Gmail Android, Outlook.com | | **Full inversion** | Client inverts all colors — light backgrounds become dark, dark text becomes light | Outlook Windows (desktop), Gmail iOS, Yahoo Mail | You cannot rely on any single strategy. Your email needs to look acceptable under all three scenarios. The techniques in this guide are defensive — they ensure readability regardless of what the client does. *** ## Defensive Design Fundamentals ### Always Set Explicit Colors The most important rule for dark mode compatibility: never rely on default colors. If you don't set a text color, the email client decides — and in dark mode, that default might become white text on a white background you specified. ```html theme={null}

This text has no explicit color.

This text is always visible.

``` ### Set Both bgcolor and background-color Outlook desktop uses the `bgcolor` HTML attribute, while other clients use CSS `background-color`. Set both. ```html theme={null}

Works in Outlook desktop and all other clients.

``` ### Avoid Pure Black and Pure White Pure white (#ffffff) backgrounds and pure black (#000000) text create harsh contrast in both modes. Use near-white and near-black values that feel softer and adapt better when inverted. ```html theme={null}

Slightly off-white background, dark (not black) text.

``` *** ## Images in Dark Mode ### Add Backgrounds to Transparent Images Logos and icons with transparent backgrounds are the most common dark mode casualty. A dark logo on a transparent PNG becomes invisible when the background turns dark. ```html theme={null} Company Logo Company Logo ``` Export logos as PNG with a built-in white or light padding around the artwork. This creates a visible "safe zone" around the logo regardless of the email background color. ### Use Images With Built-In Contrast For hero images and banners, ensure the image itself contains enough contrast to be readable on both light and dark backgrounds. Avoid images that bleed into the email background. ```html theme={null} Summer sale: 30% off all plans ``` *** ## Dark Mode Meta Tag Some email clients (notably Apple Mail and some versions of Gmail) support a meta tag that indicates your email is dark-mode-aware. Adding this can prevent the client from applying its own color transformations. ```html theme={null} ``` This meta tag tells the email client "I handle dark mode myself." If you add it, you must provide dark mode styles via `@media (prefers-color-scheme: dark)`. Adding the meta tag without corresponding styles can result in a broken appearance. *** ## CSS Dark Mode Styles For clients that support ` ``` The inline styles serve as the default (light mode) appearance. The `@media (prefers-color-scheme: dark)` block overrides them for clients that support it. The `!important` declarations are necessary because inline styles have higher specificity. *** ## Buttons in Dark Mode Buttons are particularly vulnerable to dark mode issues. A white button on a light background can become invisible, or a dark button can lose its border against a dark background. ### Bulletproof Dark Mode Buttons ```html theme={null}
View Dashboard
``` Key principles: * Use a background color with enough contrast against both light and dark email backgrounds * Add a border matching the button color — if the background gets inverted, the border maintains the button shape * Use white text on colored buttons — white text stays readable against most inverted backgrounds *** ## Testing Dark Mode ### Manual Testing Test your emails in dark mode on these clients, which cover the main rendering behaviors: System Preferences → Appearance → Dark. Apple Mail generally respects `prefers-color-scheme` and applies minimal auto-inversion. Gmail aggressively inverts colors in dark mode, especially on Android. Enable dark mode in the Gmail app settings and send yourself a test email. Outlook's Word-based renderer applies full color inversion. File → Office Account → Office Theme → Dark Gray or Black. This is typically the most aggressive dark mode. Click the gear icon → Dark mode. Outlook.com applies partial inversion and sometimes ignores explicit colors. Use Lettr's [test email](/learn/sending/test-emails) feature to send tests to your own accounts. Check both light and dark mode every time you update a template. ### What to Check | Check | Pass | Fail | | --------------------- | ----------------------------------------- | --------------------------------------- | | Body text readable | Text visible against all backgrounds | Text disappears or becomes hard to read | | Logo visible | Logo has contrast against dark background | Logo blends into dark background | | Buttons visible | Button shape and text clearly visible | Button blends in or text disappears | | Images look natural | Images have clear boundaries | Images bleed into background | | Links distinguishable | Links stand out from body text | Links indistinguishable from text | *** ## Common Mistakes If you don't set an explicit text color, the email client assigns one. In dark mode, the client may change it to white — which becomes invisible if you've set a white background that the client didn't invert. Always set explicit colors on every text element. A dark-colored logo on a transparent background disappears completely when the email background is inverted to dark. Either export logos with a built-in light background, or wrap the image in a container with an explicit white background. The `color-scheme: light dark` meta tag tells the client you handle dark mode. If you declare this but don't provide `@media (prefers-color-scheme: dark)` styles, the client may not apply any automatic adjustments, leaving your email unreadable in dark mode. Each email client handles dark mode differently. An email that looks perfect in Apple Mail dark mode may be unreadable in Outlook desktop dark mode. Test across at least three clients. Background images in CSS (`background-image`) are unsupported in many email clients and don't adapt to dark mode at all. Use solid background colors for containers. *** ## Related Topics Build and manage email templates with the Topol editor Make your emails accessible to all recipients How different email clients render HTML email Send test emails before going live