The email dark-mode bug that hides between light and dark

A headline in a test email came out white on white. The code said dark gray. The mail client said dark mode was off. Both were telling the truth.

What I saw

The email is a newer card-style layout: a white content card with a soft shadow, sitting on the page background. In Outlook on the web, with Outlook's own dark mode switched off, the big headline vanished. You could select it. You couldn't read it.

The inline style on the headline was fine:

<div style="font-size: 36px; font-weight: bold; color: #2A2729;">
  Headline goes here</div>

Dark gray, on a card with bgcolor="#FFFFFF". Nothing in the content blocks was wrong. I diffed two test sends to be sure, and the markup for the headline was byte-identical in both.

The rule doing it

The template's <head> carries a dark-mode block:

@media (prefers-color-scheme: dark) {
  body, div { color: #ffffff !important; }
  body { color: #ffffff !important; background-color: #2b2b2b !important; }
  .container { color: #ffffff !important; background-color: #2b2b2b !important; }
}

The first rule is the problem. !important in a stylesheet beats a plain inline color, so every div goes white. The rule darkens the body and the outer container. It never touches the card, because the card's white comes from an inline bgcolor and an inline style that the rule doesn't target.

On older single-column layouts that was fine. Text sat straight on the container, the container went dark, white text on dark gray. The card design added a white layer the dark-mode CSS was never told about.

Why nobody caught it

prefers-color-scheme follows the operating system or the browser. It does not follow the mail client's own dark-mode toggle. So there are really two switches, and they don't have to agree:

• OS light, client light: the media query never fires. Looks right.
• OS dark, client dark: the client applies its own dark handling on top, the card goes dark too. Looks right.
• OS dark, client light: the media query fires and whitens the text, the client leaves the card white. White on white.

If you test "light mode" and "dark mode," you test the first two and ship the third. I only hit it because my Windows theme is dark and I'd left webmail on its default. That mismatch is probably common. Plenty of people run a dark OS and never touch their mail client's settings.

The fix is one line

Delete the rule that whitens every div:

@media (prefers-color-scheme: dark) {
  /* body, div { color: #ffffff !important; } */
  body { color: #ffffff !important; background-color: #2b2b2b !important; }
  .container { color: #ffffff !important; background-color: #2b2b2b !important; }
}

The surround still goes dark. The card stays white with its dark inline text, which for a card design is the correct dark-mode look anyway. Full dark mode is unchanged, because the clients that do real dark mode lean on their own attribute selectors ([data-ogsc], [data-ogsb] in Outlook's case) rather than this block.

If you can't touch the template's head, there's a per-email workaround: put !important on the inline color in your own text blocks. Inline !important beats stylesheet !important.

<div style="... color: #2A2729 !important;">

It works, and it's nine blocks of noise instead of one deleted line. Fix the template if you can.

While I was in there

Two smaller things from the same test round, because they bite the same way: they look fine in the clients most people test in.

• Image widths. A "scale to fit" image option wrote the file's own pixel width into the width attribute (1072) and relied on width: 100% in CSS to shrink it. Gmail and Apple Mail follow the CSS. Outlook for Windows renders through Word and uses the attribute, so the image comes out 1072 pixels wide in a 600 pixel email. Typing the display size explicitly fixed it.
• Alt text is plain text. I put ’ in an alt field. The editor escaped the ampersand and the alt text read School’s in the inbox. Type the apostrophe.

What I'd do differently

I diagnosed this in one client, Outlook on the web, plus a reading of the CSS. I didn't run it through a rendering service, and I haven't confirmed the one-line fix in Apple Mail or Gmail's apps, where dark mode is handled differently again. n=1 client, one template. The two-switch test matrix is the part I'd keep: OS theme and client theme, all four combinations, before calling dark mode tested.