Investigating activity summary email dark mode issues

[simon]

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):

.digest-header {
    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 #ffffff.)

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 dark_mode_digest_logo and 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 digest.html.erb file.)

[simon]

I realized I might not have stated the most obvious issue clearly enough. The apply custom styles to digest site setting is enabled by default. That setting is used to add meta tags and CSS rules that cause iOS email clients to display emails in dark mode if the user has enabled dark mode on the device.

Unless special care is taken to upload a digest logo that has sufficient contrast against both light and dark backgrounds, digest emails from sites that have a logo optimized for light backgrounds, viewed in dark mode on popular email clients will look similar to this:

Disabling the apply custom styles to digest site setting will actually produce better results. With that setting disabled, dark mode styles will not be applied to iOS mail apps. They will still be applied to Andriod email clients and the iOS Gmail app though.

Possibly the current best practice should be to try to upload a logo to the digest logo site setting that displays well against both light and dark backgrounds. If that can’t be done, Discourse sites with a light default color scheme should disable the apply custom styles to digest site setting. Discourse sites with a dark default color scheme should keep the setting enabled. Don’t take the advice about the apply custom styles to digest site setting as definitive yet, but based on some testing, it seems likely to be the correct approach.

@simon

it might be worth looking into providing dark_mode_digest_logo and light_mode_digest_logo settings. On at least some email clients, it will be possible to detect the mode and display the appropriate logo.

This would only work for email client that support @media (prefers-color-scheme) : Can I email… @media (prefers-color-scheme). There would be some risk of causing both versions of the logo to appear on other email clients.

[Canapin (Coin-coin le Canapin)]

Thank you for this thorough work Simon

@simon

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

This is terrible. I experience this on my smartphone and I don’t even understand how forcefully inverting colors regardless of the content was seen as a good idea.

[jordan-vidrine]

I wonder if a possible solution could be that instead of using the logo, we create an image within a rectangle format using the site logo & the header background color the site currently uses.

We would need to do this on the backend, but using an image block with the included color as the background would prevent gmail from inverting the color of the background.

For what it’s worth, I tested out multiple large brand emails in my gmail app while set on dark mode, and the majority of them have not solved for this either.

[simon]

@jordan-vidrine

I wonder if a possible solution could be that instead of using the logo, we create an image within a rectangle format using the site logo & the header background color the site currently uses.

Without doing that, it’s possible to force specific background colors on most email clients, the exceptions seem to be some of the older Outlook desktop email clients. (I’m guessing that dark mode doesn’t get that much use on desktop clients.)

For iOS (excluding Gmail) email clients, Discourse is already doing this if the apply custom styles to digest setting is enabled. The problem is that it’s hardcoding in the background color and not respecting the site’s “header background” color:

discourse/discourse/blob/main/app/helpers/email_helper.rb#L82-L84

The [dm='header'] rule could be changed to:

"
[dm='header'] {
  background: ##{ColorScheme.hex_for_name('header_background')} !important;
}
"

If it made sense, a similar approach could be taken for the “Since your last visit” section:

"
[dm='body_primary'] {
  background: #{SiteSetting.email_accent_bg_color} !important;
  color: #{SiteSetting.email_accent_fg_color} !important;
}
"

Note that the dm attribute for dark mode styles gets added to the email here: discourse/lib/email/styles.rb at main · discourse/discourse · GitHub.

Something like that should work to fix the issue on iOS (excluding Gmail) email clients.

For the iOS Gmail client, the background colors can be forced by setting them with a linear gradient. There don’t seem to be any unintended side effects of setting a linear gradient background in this way for all email clients. So it should be ok to just add a linear gradient background color to the inline CSS that’s sent to all email clients.

My suspicion is that the easiest solution for dealing with the “Since your last visit” section for email clients that perform a full color invert would be to just let the clients perform the invert, but make sure there is lots of contrast between the email accent accent bg color and email accent fg color settings:

That should prevent cases like this (with the default values of those settings):

[simon]

The easiest change that Discourse could make now to increase the likelihood that summary emails are displayed correctly in dark mode would be to not enable the apply custom styles to digest site setting by default. (Note, this will only affect iOS email clients.)

Another small change would be to update the copy of the digest logo site setting to encourage uploading a logo that has sufficient contrast when displayed against either a light or a dark background color. The go-to trick for dark logos is to add a white outline to the logo.

Possibly, the Emails / Preview summary page should give a warning that some email clients will perform a “full color invert” when the email is viewed in dark mode. Site owners could be encouraged to test their summary emails in dark mode on whatever email clients they have access to.

[damienalexandre]

Thanks for the details!

As a quick workaround, I added this CSS to the Emails settings:

@media (prefers-color-scheme: dark) {
    body > div > table > tbody > tr > td > table[dm="header"] {
        background: #c89f4c !important;
    }
}

It make the header background lighter and my Logo is now displayed properly (in preview at least).