Modo escuro em e-mail HTML: monte a paleta em pares e saiba quem lê o seu CSS

Três grupos de clientes, três estratégias

A tabela da Litmus separa os clientes pela reação ao modo escuro: quem não mexe no e-mail, quem inverte as cores em parte (só fundos claros viram escuros) e quem inverte tudo, inclusive fundos que você já tinha feito escuros. Cruzando isso com a capacidade de ler o seu CSS, o que importa na prática são três grupos.

O que a documentação diz sobre declarar o suporte

O blog do WebKit, em Dark Mode Support in WebKit, explica que o Safari não escurece conteúdo da web automaticamente: o documento precisa declarar color-scheme. Para e-mail, o mesmo texto afirma que a propriedade informa ao Mail qual esquema usar e pode afetar as transformações automáticas; declarar light dark avisa que a mensagem tem estilo próprio para o modo escuro, e light only pede ao Mail que não transforme uma mensagem pensada só para o modo claro. A ficha de color-scheme do caniemail registra suporte no Apple Mail (só no elemento raiz), no Samsung Email e no Thunderbird, e nenhum no Gmail, no Outlook para Windows e no Outlook.com. A ficha do metatag mostra suporte no Apple Mail para macOS, mas não no iOS; por isso o CSS em :root acompanha o metatag.

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

Monte a paleta em pares

O erro mais comum de quem começa é inverter as cores de cabeça: o fundo claro vira escuro e o texto escuro vira claro, e ninguém confere o resultado. Faça o contrário. Liste cada papel de cor do e-mail (fundo, cartão, texto, texto de apoio, link, botão, erro) e defina o valor claro e o escuro lado a lado. O WCAG 2.2, no critério 1.4.3 Contraste (mínimo), exige pelo menos 4,5:1 para texto comum; a tabela abaixo mostra um conjunto que passa nos dois modos.

Com a tabela pronta, o CSS é só tradução. Cada papel vira uma classe, e a media query reescreve o valor do par escuro com !important, porque o estilo inline do modo claro tem prioridade. Para o Outlook.com e os apps do Outlook, a Litmus recomenda duplicar as mesmas regras com os prefixos [data-ogsc] (texto) e [data-ogsb] (fundo); a ficha do caniemail confirma que esses clientes adicionam atributos data-og ao e-mail em modo escuro.

<style>
  @media (prefers-color-scheme: dark) {
    .fundo   { background-color: #1a1a1a !important; }
    .card    { background-color: #2d2d2d !important; }
    .texto   { color: #f2f2f2 !important; }
    .apoio   { color: #b3b3b3 !important; }
    .link    { color: #7aa7ff !important; }
    .botao   { background-color: #7aa7ff !important; color: #1a1a1a !important; }
    .erro    { color: #ff8a80 !important; }
  }

  /* Outlook.com e apps do Outlook: mesmas regras com atributos data-og */
  [data-ogsb] .fundo { background-color: #1a1a1a !important; }
  [data-ogsb] .card  { background-color: #2d2d2d !important; }
  [data-ogsc] .texto { color: #f2f2f2 !important; }
  [data-ogsc] .link  { color: #7aa7ff !important; }
</style>

Repare que o botão não só troca de cor: a cor do texto também. Um botão azul-claro com texto branco daria cerca de 2,4:1, por isso o texto passa a #1a1a1a. Trocar o fundo sem revisar o texto é a causa mais frequente de botões ilegíveis em modo escuro.

Evite os extremos

Em um artigo de outubro de 2025, a Email on Acid observa que o Apple Mail tende a inverter o preto puro (#000000) e o branco puro (#FFFFFF) sem olhar o contraste, e sugere valores quase idênticos, como #000001 e #FFFFFE, para evitar surpresas. A Litmus confirma o lado do branco: no Apple Mail, fundos #ffffff puros são invertidos quando o metatag está presente. Por isso a paleta acima usa #f5f5f5 e #333333 em vez dos dois extremos.

Logos, ícones e imagens

Um logo com texto escuro e fundo transparente é legível no modo claro e some no escuro. A Email on Acid lista três saídas: usar PNG transparente com cuidado, adicionar um contorno ou brilho claro, ou criar uma versão do logo para o modo escuro e trocá-la. A Litmus acrescenta que, para clientes com pouca margem de personalização, como o app do Gmail e o Outlook 2019 para Windows, um contorno semitransparente em volta do PNG ajuda.

<style>
  .logo-escuro { display: none; }
  @media (prefers-color-scheme: dark) {
    .logo-claro  { display: none !important; }
    .logo-escuro { display: block !important; max-height: none !important; }
  }
</style>

<img class="logo-claro" src="https://exemplo.com.br/img/logo-texto-escuro.png" width="150" alt="Loja Exemplo">
<!--[if !mso]><!-->
<img class="logo-escuro" src="https://exemplo.com.br/img/logo-texto-claro.png" width="150" alt="Loja Exemplo" style="display:none; max-height:0;">
<!--<![endif]-->

A troca por classes funciona nos clientes que leem a media query. A alternativa com <picture> e media="(prefers-color-scheme: dark)", que o WebKit mostra para páginas web, não é segura em e-mail: a ficha de picture informa que o Gmail troca as tags picture e source por u, e que o Apple Mail às vezes remove a tag. Quanto ao formato, a ficha de SVG avisa que o Gmail renderiza SVG, mas rasterizado como PNG, então um logo vetorial não escala por lá; mantenha PNG com o dobro da largura para telas de alta densidade.

Frameworks e o modo escuro

Nenhum framework resolve o modo escuro por você. A documentação do MJML que consultei não traz componente próprio para isso, de modo que as regras vão em mj-style (que aceita CSS livre, no head ou inline) e o metatag, em um mj-raw. A documentação do Maizzle descreve a variante dark: do Tailwind, que compila para @media (prefers-color-scheme: dark), e as variantes ogsc: e ogsb: para o modo escuro do Outlook.com; ela também avisa que empilhar dark: com ios: gera at-rules aninhadas, que o Gmail trata descartando a tag style inteira, e recomenda separar esses utilitários em um bloco Tailwind próprio. Para a comparação entre os dois, veja MJML contra React Email.

Testando o resultado

1. Teste em aparelhos reais. Ative o modo escuro no celular e no computador, envie a mensagem para contas do Apple Mail, do Gmail e do Outlook e abra nos dois tipos de tela.
2. Teste a inversão. Se o Gmail para iOS faz inversão completa, o que você vê ali é a paleta "no escuro" que você nunca desenhou. Confirme se texto, link e botão continuam legíveis.
3. Use previews para ampliar, não para decidir. A Litmus e a Email on Acid mostram o modo escuro de vários clientes; confira em cada página de preços como o plano conta as visualizações antes de contratar, e leia o comparativo entre as duas.
4. Documente. Anote cliente, modo, data e o que ficou imperfeito.

Para o restante do CSS que afeta estas decisões, veja o guia de CSS em e-mail; para contraste e texto alternativo, o guia de acessibilidade; para o panorama dos motores de renderização, o guia de compatibilidade entre clientes.