Email Light and Dark Theme Design
Dark mode is now a normal inbox environment, not an edge case. Email clients handle it differently, so a reliable template needs a strong light design, explicit dark-theme decisions, and a testing process that catches client-specific color changes before the campaign is sent.
Why Dark Mode Is Difficult in Email
Unlike websites, email does not run in one consistent rendering engine. Gmail, Apple Mail, Outlook, Yahoo, and mobile apps each decide how much of your HTML and CSS they will respect. Some clients keep your colors. Some partially invert backgrounds or text. Some fully invert large areas. Others support prefers-color-scheme and dark-mode meta tags.
This means dark mode cannot be treated as a simple "black background" version of the email. It is a resilience problem:
- Text must stay readable when colors are preserved, darkened, or inverted.
- Logos and product images must remain clear on both light and dark surfaces.
- CTA buttons must remain visible even if the client changes surrounding colors.
- Backgrounds should avoid brittle assumptions about the inbox canvas.
- Test results must be reviewed in more than one client family.
Client Behavior Matrix
| Behavior | What the client may do | Common risk | Design response |
|---|---|---|---|
| No change | Preserves your HTML colors in dark mode | A light email can feel visually harsh in a dark inbox | Use softer light backgrounds and test dark previews anyway |
| Partial inversion | Changes light backgrounds or text while keeping some brand colors | Brand colors, icons, and borders can become low contrast | Use explicit dark colors for core blocks and avoid pale-on-pale combinations |
| Full inversion | Inverts most colors in the email | Logos, images, and buttons can look wrong | Use transparent image assets and avoid text embedded in images |
| CSS-supported dark mode | Respects dark-mode media queries and meta tags | Unsupported clients still need fallbacks | Build dark styles as progressive enhancement, not as the only readable path |
| Outlook-specific dark mode | Uses Outlook and Office-specific behavior, including data-ogsc and data-ogsb selectors | Windows Outlook may differ from browser Outlook | Test Outlook separately and keep fallbacks simple |
Recommended Design System
Start With The Light Theme
Start with a readable light-theme baseline, including a fallback for clients that ignore dark-mode CSS. The editor initially selects the email's light version. New documents start with transparent backdrop and canvas defaults; saved templates can contain explicit colors. Transparency is a layout choice, not a guarantee of contrast or client rendering. Review the foreground against the background that the recipient actually sees, and choose a filled surface when needed.
Define A Dark Theme Intentionally
For each reusable section, decide the dark-theme equivalent for:
| Element | Light theme example | Dark theme goal |
|---|---|---|
| Body text | Near-black text | Light gray text with enough contrast |
| Canvas | White or transparent | Transparent, deep neutral, or brand-safe dark |
| Section backgrounds | White, gray, or brand tints | Muted dark neutrals, not pure black by default |
| Links | Brand blue or accent | Brighter link color that still passes contrast |
| Dividers and borders | Light gray | Muted gray with visible separation |
| Buttons | Brand fill | Preserve brand fill if contrast works, otherwise define a dark-safe alternative |
Use the Email switch in the editor's toolbar (Light or Dark) to choose which version of the email you edit and preview, rather than creating a separate theme switch for each component. Theme-aware color controls edit the selected version using their light/dark values and fallbacks, and carry a Dark tag while the dark version is selected. Review the available controls for each block. Do not assume that raw HTML or every authored color automatically gains a separate dark value.
Keep Contrast Measurable
WCAG 2.2 SC 1.4.3 (Level AA) sets a 4.5:1 text-contrast threshold, with a 3:1 threshold for large-scale text and stated exceptions. Large-scale means at least 18-point regular or 14-point bold text, not every heading. Check the text against its actual background in both themes; a receiving client can alter either color.
The higher ratios below are optional design goals, not additional WCAG requirements. This checklist is not an accessibility audit or proof of conformance.
| Content | Minimum target | Practical email target |
|---|---|---|
| Body copy | 4.5:1 | 7:1 or higher where brand allows |
| Large-scale text | 3:1 when the large-scale definition applies | 4.5:1 or higher as a design goal |
| Button text | Apply the threshold for its text size | Extra contrast where practical; 7:1 is an optional goal |
| Borders/dividers | Text contrast alone does not assess every visual boundary | Review meaningful separation separately without unnecessary visual noise |
Prepare Images And Logos
Dark mode failures often show up in assets before text. Use these rules:
- Use logos with enough padding around the mark. Validate the image format in your target mail clients; a logo rendering in the editor does not establish inbox support for SVG.
- Avoid placing dark logos directly on transparent backgrounds unless a light alternate is available.
- Do not embed critical text inside images. Image blocking, scaling, and inversion all make this fragile.
- Add descriptive alt text to every meaningful image.
- Use product images with natural backgrounds where possible. Pure white product cutouts may look like harsh tiles in dark inboxes.
- If an asset must stay on a fixed background, make that background part of the image intentionally.
Oblic Editor Workflow
1. Build In Light Theme
Start with the Email switch on Light. Configure layout, hierarchy, content, image alt text, links, and CTAs. Review transparent defaults and choose explicit surfaces where they are needed for readability.
2. Switch To Dark Theme
Set the Email switch to Dark to edit and preview the email's dark version. This changes only the email: the editor's interface follows Oblic's light or dark theme, which the theme toggle in the email builder's header switches. Adjust the available theme-aware text, background, border, link, divider, and button controls. Review resolved values and fallbacks rather than assuming an automatic transformation is suitable for every block.
3. Use Side-By-Side Preview
Use Show light and dark previews side by side to compare the same editor renderer in both theme states. This can reveal an edit that weakens one theme, but it is not a receiving-client test.
Review:
- Text contrast in headings, paragraphs, buttons, captions, and footer content
- Logo visibility
- Product image edges
- Button fills and button text
- Borders and dividers
- Footer and unsubscribe links
- View-in-browser links
4. Review Inbox Preview
Inbox Preview places the same editor preview inside three styled frames named Gmail, Outlook and Apple Mail. It does not run Gmail, Outlook or Apple Mail rendering engines, reproduce their CSS rewriting or prove compatibility. Review the actual delivered message separately in the mailboxes and settings that matter for the campaign.
| Preview | What to check |
|---|---|
| Gmail | The frame provides layout context only. Check actual mobile and web messages for links, image scale and contrast. |
| Outlook | The frame does not exercise Windows or web Outlook engines. Inspect the received message's backgrounds, borders and text. |
| Apple Mail | The frame cannot confirm iOS or macOS behavior. Review the delivered message with the relevant theme and image settings. |
5. Run Spam Check
Spam Check is a local heuristic over the template document. It counts configured phrases, words, image/alt and link signals, raw HTML blocks, punctuation patterns and unsubscribe wording. It does not inspect sender reputation, DNS, recipient mailboxes or delivery. A wording match does not verify that the unsubscribe path works. Use the findings as prompts for review, not as a deliverability, accessibility or policy verdict.
Implementation Notes For Exported Email
The HTML exporter enables dark-mode support by default. With that support enabled, its output includes:
color-schemeandsupported-color-schemesmeta tags for clients that respect them.prefers-color-scheme: darkCSS for clients that support media-query-based dark mode.- Outlook dark-mode selectors such as
data-ogscanddata-ogsbwhere useful. - Explicit light-mode styles to review when dark-mode rules are ignored.
- Inline styles for critical layout and typography because many clients strip or rewrite CSS.
An export requested with darkMode: false omits the dark rules and declares a light-only color scheme; in-page preview configuration and exported email are different concerns. The emitted CSS is not a promise that a receiving client will honor the rules. Do not depend only on media queries: review dated client-support data and test the actual light fallback as well.
Research Notes
| Source | Finding to apply |
|---|---|
| Litmus dark mode guide | Vendor design reference; not evidence that an Oblic preview executes a mail client's engine. |
| Email on Acid dark mode guide | Vendor discussion of rendering patterns; validate the relevant client and version rather than assuming a universal rule. |
| EmailOctopus dark mode guide | Vendor design ideas for asset review, not a test result for your template. |
| Mail Designer 365 dark mode guide | Separate product guidance; it does not imply an Oblic integration or completed real-client tests. |
Can I Email prefers-color-scheme | Dated feature/client tests, not a guarantee of message delivery or your template's rendering. |
MDN prefers-color-scheme | Browser preference-feature documentation is not evidence of support in every email client. |
| W3C WCAG 2.2 | SC 1.4.3 defines AA text-contrast thresholds and exceptions; a preview or heuristic score does not establish whole-WCAG conformance. |
Theme Token Checklist
| Token | Light value question | Dark value question |
|---|---|---|
| Body background | Can this stay transparent? | Does the inbox background still feel intentional? |
| Canvas background | Is a filled canvas really needed? | Does a filled canvas create a harsh tile? |
| Section background | Does it separate content clearly? | Does it preserve hierarchy without pure black blocks? |
| Text primary | Is it readable on every local background? | Is it bright enough without blooming? |
| Text muted | Is it still readable on mobile? | Is it not too faint for footer links? |
| CTA fill | Does brand color support button text? | Does brand color still work after inversion? |
| Link color | Is it distinguishable from body copy? | Is it visible against dark surfaces? |
Pre-Send Checklist
- Light theme reviewed.
- Dark theme reviewed.
- Side-by-side preview reviewed.
- Framed inbox layouts reviewed, without treating them as client-engine tests.
- Real test email sent to key clients.
- No placeholder links remain.
- Every meaningful image has alt text.
- CTA contrast works in both themes.
- Footer wording is reviewed and the configured unsubscribe path is verified separately.
- Subject line and preview text match the email content.
- Spam Check findings are reviewed and not interpreted as a provider or accessibility verdict.