Dark mode is documented only at Apple

by Francis Rozange | Sep 8, 2026 | Email Marketing

Abstract 3D render: the same glass object rendered twice, one crisp, the other badly inverted

One day a client writes to say your newsletter is unreadable. Screenshot attached: dark background, dark text, a logo cut out inside a white square.

You go looking for the dark mode compatibility matrix by mail client. You will find several. None of them is published by a vendor.

What Apple documents, and it is the only one

The most precise source on the subject is an Apple technical session from 2019, on dark mode in web content. It addresses email explicitly.

For simple messages, Apple applies an automatic transformation:

“Simple email messages composed directly in mail on iOS 13 are ready to go in both light and dark appearances even if they include in-line image attachments […] because of mail’s auto darkening transformations.”

For marketing emails it is the opposite, and the sentence is decisive:

“If you are an email template designer creating designs for a campaign that includes remotely loaded images, you will need to adopt the same styling techniques I covered earlier for web content. Without adopting the color scheme property mail will display your email message in the light appearance and will not employ any auto darkening transformations that simple email messages receive.”

In other words: a marketing email with remote images renders in light mode by default, even on a device set to dark. No automatic transformation applies to it.

The session summary says it a second time: “rich email messages with remote images like custom email marketing campaigns will use the light color scheme by default. You can declare support for the dark color scheme in your marketing email messages and use the media query for custom color and image customizations.”

You have to declare your support. Without a declaration, no dark mode at Apple, and therefore no accident either.

How you declare it

Two mechanisms, and you need both.

The CSS color-scheme property, set on the root element, announces that the document can live in both appearances. Apple puts it this way: “Specifying the values light and dark on the root element lets the rendering engine know both modes are supported by the document.”

The prefers-color-scheme media query then lets you write the specific rules. Its definition comes from the W3C Media Queries Level 5 working draft:

“The prefers-color-scheme media feature reflects the user’s desire that the page use a light or dark color theme.”

A point of status is required here, because it is nearly always passed over: Media Queries Level 5 is a Working Draft, dated 19 February 2026. Not a W3C Recommendation. Calling it an established standard would be inaccurate.

The document also gives a writing tip few people follow:

“The values for this feature might be expanded in the future […] As such, the most future-friendly way to use this media feature is by negation such as (prefers-color-scheme: dark) and (not (prefers-color-scheme: dark)).”

Write by negation rather than by enumeration. A detail that saves you a rewrite the day a new value is added.

What Microsoft says, and what it does not

Microsoft’s only statement on the subject sits in product documentation, and it is remarkably cautious:

“However, email rendering is controlled by each email client, like Outlook, Gmail, or Apple Mail, which may in dark mode, apply no changes, partially/fully invert colors, or override styles.”

Four possible behaviours, listed without saying which applies to which client. Including its own.

The recommendation that follows is an admission: “Test rendering across major clients like Outlook, Gmail, and Apple Mail, on desktop and mobile.”

Microsoft does not publish a specification. It asks you to test.

As for Google, no official documentation on prefers-color-scheme support in Gmail exists. Not on the developer site, not in the help centre, not on the Workspace blog. The only traces are community forum threads.

No primary source found. That is the real status of the question, and any compatibility matrix you consult rests on provider testing, not vendor commitments.

The three classic accidents

Since nobody publishes a specification, you have to reason from mechanisms.

The first accident comes from partial inversion. A client that darkens backgrounds without touching declared text colours produces dark text on a dark background. The fix is not to freeze the colours, it is to declare both sets.

The second comes from logos. A black logo on a transparent background becomes invisible on a dark background. A black logo on an opaque white background cuts a white rectangle into the middle of the page. Neither version works: you need two, served by the media query.

The third comes from implicit borders. A zone whose legibility rests on the contrast between two very close greys disappears entirely as soon as one grey is inverted and the other is not.

These three accidents share one property: they make the message unreadable without producing any error. Nothing is reported, nothing fails, and you only learn about it from a customer.

What to do tomorrow morning

First check whether the subject concerns you at all. An email built in text, on a white background, with strong colours and a logo that works on both grounds, crosses dark mode without damage. It is complex layouts that break.

If you must declare support, do it completely: the color-scheme property on the root, and a set of rules under the media query. A half-done declaration is more dangerous than none, since it authorises the client to transform without your having described the intended result.

Prepare two versions of your logo, and serve the second through the media query. That is the fix that resolves the most complaints for the least work.

And test on real devices, starting with an iPhone, because it is the only environment whose behaviour its vendor documents. For the others you are in the realm of observation, and you should know that before promising a rendering.

Sources

LaFactory works email on the evidence: headers, DNS records, rejection logs. No open rate promises, ever. Get in touch for a deliverability audit.