This was intended to be a short post with a few pictures and an easily applied solution. It’s gotten out of hand. HTML email is difficult. For some fun, here’s how it can go wrong: Gmail's dark mode · Issue #68 · hteumeuleu/email-bugs · GitHub
Feel free to skim this post and look at the pictures. By the end of the post I’d more or less come to the conclusion that due to the popularity of dark mode, it might be worth reworking the digest email, instead of trying to hack solutions onto its current code. That’s not up to me, and maybe I’ve just been looking at this for too long.
There have been some recent questions about how digest emails are rendered on email clients that are set to dark mode. The main issue is that the digest header’s background color gets inverted on email client that handle dark mode by performing a full color invert (Gmail app (iOS), Outlook 2021 (Windows), Office 365 (Windows), and Windows Mail.) This creates a contrast issue between the header color and the site logo.
These email clients also have an issue with the text color in buttons and the digest’s “Since your last visit” section.
All the images below are from the Litmus email testing service:
From a Discourse site with a dark color scheme, using a white PNG logo with a transparent background:
Expected (Gmail App Dark for Android):
Poor (Gmail Dark for iOS, OL Office 365 Dark, Outlook 2021 Dark, Windows 10 Mail Dark):
Mobile client overview (Gmail for iOS is the only client with obvious issues with the header color):
Here is the same test with the Meta digest email (default light color scheme, dark PNG logo on transparent background.) Note that Meta doesn’t have the
apply custom styles to digest site setting enabled, so it’s not getting the dark mode meta tags and styles for clients that support them (Apple Mail and recent versions of iOS mail.) If the
apply custom styles to digest setting was enabled, I suspect the iPhone Dark tests would also have issues with logo/background-color contrast.
There are a couple of ways that the email header background color can be forced to match the color of the site’s default color scheme:
For the Gmail app for iOS, the header background color can be set with a background image that’s created with a
linear-gradient. Background images created in this way don’t get their color inverted. The trick is to set both of the
linear-gradient colors to the value of the Discourse site’s default color scheme’s “header background” color.
This can be accomplished now by adding custom CSS to the Admin / Customize / Email Style / CSS tab. Set the color values to the value of your default color scheme’s “header background” color. (Note, it’s not possible to use
var(--header_background) to set the color in the Email CSS editor):
background-image: linear-gradient(#111, #111);
Testing this approach for the Meta digest email, I’m starting to have some doubts about it as a solution for sites that have a light default color scheme. The logo is legible, but does this look a little weird?
For the Outlook 2021 Dark and Windows 10 Mail Dark desktop email clients, the issue with inversion of the header’s background color can be fixed by adding an
!important rule to the
background-color that is set for the
.digest-header. This can not be accomplished via custom CSS because Discourse is already adding a
background-color style to the element without the
!important rule. That rule gets added after the custom CSS, so it takes precedence. (Note, this approach only seems to work to force the background color to a dark color. It fails when I try to use it to force the header background to
The issue with text color in the “Since your last visit” section for email clients that perform a full color invert does not seem to have an easy solution. There’s an iOS Gmail hack suggested here: Fixing Gmail’s dark mode issues with CSS Blend Modes — HTeuMeuLeu.com. It makes use of blend modes to trick Gmail into setting a white text color. It works in theory, but given the complexity of the digest email markup, I don’t think it’s worth pursuing.
Summing up, I think that for Discourse sites that have a dark color scheme as their default color scheme, a good solution for now would be to add the CSS I posted above to their Email Style / CSS tab. This will make the site logo legible on the iOS Gmail Dark app. Adding it has not caused any issues with other email clients that I’ve tested. For sites that have a default light color scheme, I’m less sure about that approach. Forcing a white header background on an otherwise dark screen doesn’t look great.
The digest email was developed before dark mode was commonly used. Maybe due to the recent popularity of dark mode, it would make sense to rework the digest email with the aim of getting it to display well in both dark and light mode on popular email clients.
If completely reworking the digest email is out of scope, it might be worth looking into providing
light_mode_digest_logo settings. On at least some email clients, it will be possible to detect the mode and display the appropriate logo.
To improve dark mode on Outlook desktop clients, Discourse could leave some class names in the email’s HTML instead of stripping them all out. These class names could be used to target dark mode on Outlook: https://litmus.com/community/discussions/8256-outlook-app-vs-dark-mode-on-ios-a-disaster#comment-16402. (Note, Outlook can’t handle multiple classnames on an element, so some class names would still need to be removed from the