MJML Dark Mode Email Guide

• MJML does not provide native dark mode support or a magic dark mode switch; the hard constraints come from email clients.
• MJML components compile into generated wrappers, tables and inline styles that can change where classes and styles land.
• css-class may be placed on an outer generated node, so inspect the compiled HTML before writing final selectors.
• Current MJML can place css-class from mj-body on the generated body tag, which is useful for Gmail targeting, but this still needs compiled-output verification.
• MJML 5 changed body/class placement and minification behaviour, so upgrades should trigger a visual dark mode re-check.
• Dark mode CSS usually belongs in <mj-style> inside <mj-head>.
• Keep media queries and client-targeting selectors in embedded mj-style, not mj-style inline="inline".
• Dark mode meta tags usually need <mj-raw> inside <mj-head>.
• Apple Mail is the strongest target for authored prefers-color-scheme CSS.
• Gmail requires targeted selector patterns like u + .body, and those do not cover every Gmail account type.
• Outlook.com can require [data-ogsc] and [data-ogsb] reaction selectors.
• Classic Outlook for Windows remains the MSO/VML fallback path, not a modern CSS target.
• Use mj-attributes, mj-class or your build system for colour tokens; runtime CSS variables are not production-safe across Gmail, Outlook and Yahoo.
• Always test the compiled HTML, not just the MJML source.

<mjml>
  <mj-head>
    <mj-raw>
      <meta name="color-scheme" content="light dark">
      <meta name="supported-color-schemes" content="light dark">
    </mj-raw>

    <mj-style>
      :root {
        color-scheme: light dark;
        supported-color-schemes: light dark;
      }
    </mj-style>
  </mj-head>
</mjml>

These declarations are most useful for standards-friendly clients such as Apple Mail. color-scheme is the modern hint, while supported-color-schemes remains useful for Apple Mail history. They do not force Gmail, Yahoo or Outlook Windows to behave like Apple Mail.

<mj-head>
  <mj-style>
    @media (prefers-color-scheme: dark) {
      .email-shell {
        background-color: #111114 !important;
      }

      .surface {
        background-color: #1b1b22 !important;
        color: #f5f5f7 !important;
      }

      .muted-text div {
        color: #b8b8c7 !important;
      }
    }
  </mj-style>
</mj-head>

<mj-body css-class="email-shell" background-color="#f6f4ff">
  <mj-section css-class="surface" background-color="#ffffff">
    <mj-column>
      <mj-text css-class="muted-text">Dark mode-aware copy</mj-text>
    </mj-column>
  </mj-section>
</mj-body>

The selector .muted-text div is intentional: many mj-text styles land on a generated inner div. This media query is mainly for standards-friendly clients such as Apple Mail; it should not be treated as a Gmail or Yahoo dark mode strategy. Inspect your compiled HTML before relying on the exact selector.

<mj-head>
  <mj-style>
    .dark-logo { display: none; max-height: 0; overflow: hidden; }

    @media (prefers-color-scheme: dark) {
      .light-logo { display: none !important; max-height: 0 !important; overflow: hidden !important; }
      .dark-logo { display: block !important; max-height: none !important; }
    }
  </mj-style>
</mj-head>

<mj-section>
  <mj-column>
    <mj-image css-class="light-logo" src="https://example.com/logo-light.png" alt="Brand" width="160px" />
    <mj-image css-class="dark-logo" src="https://example.com/logo-dark.png" alt="Brand" width="160px" />
  </mj-column>
</mj-section>

This works best in standards-friendly clients. MJML may place the class on a generated container rather than directly on the img, so confirm the compiled selector. Some clients may download both assets, hide/show differently or ignore the embedded CSS. Transparent logos still need testing on changed surfaces. Use hosted production asset URLs rather than relying on local filenames.

<mj-head>
  <mj-style>
    u + .body .gmail-surface {
      background: #1f1f23 !important;
      background-image: linear-gradient(#1f1f23, #1f1f23) !important;
      color: #ffffff !important;
    }

    u + .body .gmail-surface div {
      color: #ffffff !important;
    }

    div > u + .body .gmail-android-fix {
      background-color: #1f1f23 !important;
    }
  </mj-style>
</mj-head>

<mj-body css-class="body">
  <mj-section css-class="gmail-surface" background-color="#663399">
    <mj-column>
      <mj-text>Gmail-targeted content</mj-text>
    </mj-column>
  </mj-section>
</mj-body>

This pattern depends on a doctype and a generated body class. Gmail Apps with Non-Google Accounts can have reduced CSS support, and blend-mode or single-colour gradient workarounds are targeted hacks rather than reliable universal fixes. Do not assume Gmail iOS, Gmail Android, Gmail Web and GANGA behave the same.

<mj-head>
  <mj-style>
    [data-ogsc] .outlook-surface {
      background-color: #1f2937 !important;
      color: #ffffff !important;
    }

    [data-ogsc] .outlook-surface div {
      color: #ffffff !important;
    }

    [data-ogsb] .outlook-button {
      border-color: #8b5cf6 !important;
    }
  </mj-style>
</mj-head>

<mj-raw>
  <!--[if mso]>
  <style>
    .mso-button { background: #111827 !important; color: #ffffff !important; }
  </style>
  <![endif]-->
</mj-raw>

data-og* is for Outlook.com-style rewriting and some related app surfaces. MSO conditionals and VML are for classic Outlook Windows. Outlook.com, new Outlook and classic Outlook Windows are not the same rendering model.

• Start with a robust light email that remains readable if a client makes no colour changes.
• Keep component defaults in mj-attributes, but keep runtime dark CSS in mj-style.
• Add dark mode meta tags deliberately through mj-raw.
• Use css-class for semantic hooks, then verify where those hooks land in the compiled HTML.
• Use a body class for Gmail targeting when needed, but confirm how your MJML version emits it.
• Use prefers-color-scheme for standards-friendly clients, especially Apple Mail.
• Use Gmail and Outlook targeting only for their own client families.
• Avoid exact black/white as the only contrast plan; use near-black, off-white and explicit border tokens.
• Prefer MJML compile-time tokens or build-time variables over runtime CSS variables for production email colours.
• Test logos, buttons, borders, cards and footer sections in the compiled HTML.
• Track your MJML compiler version so output changes are visible during QA.