The past few years we've seen an explosion of ″dark mode″ interfaces: bright foreground on a dark background. In this article we'll see why it's important to support it and how you can implement it on your Joomla! sites, including the emails they send out.

What it is and what it is not

Dark Mode is an alternative color scheme for your site. It is not an entirely different template and it's not meant to supplant your existing site's template.

We can neither say that Dark Mode is an accessibility feature nor that it's not an accessibility feature. It can be an accessibility feature for some people while for others it will be a hindrance. Because of its subjective and conditional nature as an accessibility feature it is best for your site to implement Dark Mode but only enable it when the user wants it.

Moreover, you should consider that the same user may have different colour scheme preferences throughout the day or on different days. Don't treat it as something only a logged in user can select, hidden under layers of user interface options (StackOverflow, I'm glaring in your general direction). Here's my personal use case. When I wear contact lenses which only address my myopia, not my astigmatism, I need a lot of light to resolve small detail like 11pt or smaller text on a screen even during the night. Otherwise I get a headache. In this case I need to use light mode. When I'm wearing glasses, though, being exposed to a lot of light after dusk gives me a headache so I need to use dark mode.

The two ways to go about it

The ideal way to go about it is having this feature implemented as a tristate interface switch with options for automatically enabling dark mode when appropriate (more on that later), always use dark mode or always use light mode, saved in the user state or a cookie. While offering the best accessibility – catering even for people who generally prefer dark mode but can only stand reading long form text in light mode – it is also the most complicated to implement. You'd need to code your own custom template at the least and ideally system plugin and module to implement the switch. You'd also need to be in total control of the CSS applied on your site, even for third party extensions. This gets very complicated, very fast.

An easier and relatively safe way to implement it is having your site respect the user's choices as expressed through their Operating System color scheme choice, something that the browser already knows about. This allow you to do an automatic color scheme switch based on the user's preferences without the user having to do anything. This is the best compromise between user choice and user experience but doesn't cater for a minority of edge cases; if the user would like to consume your content in light or dark mode they need to make sure their system settings are in sync with their intention. In any case, this is the solution we'll be discussing in this article.

How does automatic Dark Mode work?

Since Dark Mode is an alternative color scheme for your site you need to load and apply a set of CSS rules which change only (or mostly) the colors of your site. This CSS needs to be applied conditionally, when the user has selected a dark / night mode on their device. This is done with CSS media queries.

Modern versions of Windows, macOS, iOS/iPadOS, Android and even most Linux desktop environments have OS-level controls to turn on dark / night mode. This information can be communciated from the OS to the browser, therefore the browser can make a special type of media query available for that preference. This media query was originally introduced in Safari for iOS 13 and macOS Mojave. Pretty soon other browsers followed suite and the original Safari implementation, with some minor changes, made it into two W3C Working Drafts titled CSS Color Adjustment Module Level 1 and Media Queries Level 5.

The theory first

Before we delve into the implementation we need to consider how the two aforementioned W3C Working Drafts are applied to your site to achieve the desired Dark Mode support. It boils down to two simple things.

Communicate that you support Dark Mode

First, you need to tell the browser that your site supports Light and Dark Modes. The reason is that browsers will use a light mode default stylesheet for all page elements even when the OS is set in Dark Mode unless the site explicitly states that it is aware of Dark Mode and implements a special CSS stylesheet for it. This is a clever solution which prevents legacy, light mode-only sites from looking weird when the user enabled dark / night mode on their device.

You can communicate your site's support for Dark Mode in either of two ways. The recommended way is through CSS:

:root {
    color-scheme: light dark;
}

Alternatively, you can use a META tag in your HTML document's HEAD:

<meta name="color-scheme" value="light dark">

If you go the CSS way you need to do this in any of the site's CSS files which are loaded unconditionally (in both light and dark modes). For most templates this means adding something the the custom.css, user.css or a similarly named file. If unsure ask your template developer.

If you don't want to or cannot modify / create a CSS file to add the CSS attribute you can always add the meta tag to your template's index.php, at the top of the HEAD section. If you don't want to modify the file itself you can always use the third party Phoca Site Plugin to do this.

Whether you need to do this is a subject of debate, especially when your site is already using a CSS framework which completely overrides (resets) the browser's default stylesheet. In my opinion there's nothing to lose by including this. Conversely, not including it may cause problems further down the line. Remember, are talking about a W3C Working Draft; things might change in the future.

Apply different stylesheets based on the user's preferred color scheme

It's a relatively straightforward media query. In its simplest form it can be this kind of section in your CSS file:

@media (screen and prefers-color-scheme: dark)
{
    /* Your Dark Mode CSS goes here */
}

Of course it being a media query it doesn't have to be in your CSS file but rather appear in the LINK tag that loads your CSS. For example:

  <link href="/templates/MY_TEMPLATE/css/dark.css" rel="stylesheet" type="text/css" media="screen and prefers-color-scheme: dark">

This is something you need to put at the end of your template's HEAD element. If you don't fancy modifying your template you can add this tag to your site's HEAD using the third party Phoca Site Plugin.

How do you create a dark.css file?

If your site's template comes with LESS or SCSS sources it'd be a good idea to copy them to a separate location on your computer and start editing them. Remove anything that defines anything other than color properties. It's a dull and laborious process which will leave you with a skeleton of LESS/SCSS files that contain color, border, border-color, background and background-color properties (off the top of my head; I might be missing something). Now you can start editing the colors and compile the result into dark.css for inclusion to your site.

Don't ask me about how to choose your dark mode colors. I am not a designer. When in doubt, I ask our designer. She comes up with palettes that look good and work good. That said, you can also read about color in design systems, think about how color contrast affects readability use your eyes – but don't trust them if you don't have a disability yourself – and use WebAIM's contrast checker.

Two notes.

Contrast checking tools are a good starting point but they are currently not very good at this, being based on an obsolete color theory model which fails in some edge cases. Unfortunately, dark mode finds the edge cases especially when you have red text on gray backgrounds. For example #FF4444 text on #404040 background fails WCAG AA under the current color model but is borderline acceptable under the proposed, but not yet accepted, color model. Exercise common sense. If you can't read the text in a dark room with your monitor brightness turned less than a quarter down it's probably hard to read by people with visual disabilities.

Bright text on a dark background is generally harder to read. If you increase the contrast to make it more readable your users end up with “ghost” images in their eyes when they move their gaze about your page or when they close their eyes. This is disorienting or worse. Lowering the contrast to prevent “ghosting” makes the text harder to read. The solution to that is to also increase the text size by 10% to 20% and increase the line spacing by another 50% to 100%. This is what I'm doing on my own site at the time of this writing (May 2020). The text is bigger, more spaced apart, a bit low on contrast but easier to read than if I didn't do either of the above.

Finally, regarding how to test Dark Mode. The obvious way is to set your OS to dark mode. If you don't want to do that, only Safari offers a web developer tool to toggle dark and light mode regardless of the system settings. If you're on Linux and you're NOT using a Gtk-based desktop environment – e.g. you're using KDE – you will need to set the GTK3 theme to a dark one like Adawaita-dark and restart your browser. In my tests Chrome on Kubuntu was a hit and miss, Firefox worked flawlessly.

Images

Generally speaking, images shouldn't need to be touched for Dark Mode. The whole point of Dark Mode is to make your content – especially images – more prominent. There are, however, three use cases which warrant a different image for light and dark modes:

• Logos. If you're using a transparent background logo you will probably need a different version of it depending on whether it sits atop a light or dark background. This is what we did for our business site. Light Mode uses a four color logo with a transparent background, its primary color being dark gray. On Dark Mode the background it sits atop is also dark gray making the logo disappear. So we chose to use a monochrome, light gray version of the logo for better display.
• Screenshots. The easy way out is to take screenshots using Dark Mode whenever possible. They will display beautifully on Light and Dark Mode. If you want to be thorough, you can take the same screenshot on both Light and Dark Mode and display the correct one depending on how your user is viewing your content.
• Artistic choice. If you have this use case you're probably not reading this blog post. An example for that could be a fancy About Us page for a landscaping agency which shows the same garden in the morning on Light Mode and at night on Dark Mode. Small details like that can have a wow-factor effect and are a nice selling point for the more expensive site projects.

Images can be customised using the same media query and a <picture> tag.

So, let's say you had this image:

<img src="/images/light.jpg" />

Change your HTML to read:

<picture>
    <source srcset="/images/dark.jpg"
            media="(screen and prefers-color-scheme: dark)">
	<img src="/images/light.jpg" />
</picture> 

The light.jpg image is displayed by default. When in Dark Mode the dark.jpg will be displayed. This is a great solution because older browsers which understand neither the picture element nor Dark Mode will still display the light.jpg image.

Depending on the HTML editor you're using in Joomla you might need to edit the source code to add the picture element.

Moreover, if you're using the Whitelist option for the Text Filters in Joomla's Global Configuration page you need to remember adding both picture and source in the whitelist or Joomla will remove your custom HTML solution, only leaving the img tag for light.jpg in your article!

Dark mode for the Joomla administrator

Both Joomla 3 and Joomla 4 only offer a Light Mode administrator interface with a standard color scheme, save for user-selectable accents. If you want to use a Dark Mode interface in the backend of your site you need a third party extension.

For Joomla 3 there's DarkMagic, a small plugin which uses a third party CSS file which was developed to give the Joomla 3 backend a Dark Mode interface. Moreover, it uses a darker skin for the HTML editor. Do note, however, that it does NOT change the color of the main content edit area; this still respects your frontend template's style. If your frontend template is dark or Dark Mode aware and has the correct editor.css file in place then the content edit area will also appear dark. DarkMagic allows the automatic switch of the site's template to Dark or Light Mode.

For Joomla 4 there's the third party administrator template Bettum. This is a better implementation than DarkMagic since it's a full-blown template but it doesn't support switching between Dark and Light Modes – it's only dark.

Do keep in mind that most extension developers base their interface designs on the fact that Joomla! only offers a Light Mode in the backend. As a result most third party extensions will not display properly on a Dark Mode administrator template. I can tell you that Akeeba extensions do support Dark Mode and can be configured to display Light or Dark Mode automatically, always display Dark Mode or always display Light Mode. I personally prefer automatic switching on my live and dev sites but I won't judge if you prefer one over the other; whatever floats your boat!

Emails

Trying to create Dark Mode emails is exposing you to a world of pain. No two email clients support the same feature set. Y

ou can of course use media queries to target Apple Mail on iOS and macOS and Thunderbird but that's about it.

Gmail and Outlook have very different behaviours depending on whether you're using them on the web, on Windows or on mobile – even on which mobile OS you use. There's more in depth information on this blog post by the email testing service Litmus.

There are other, lesser used email clients which also do their own thing or are completely oblivious to Dark Mode.

As a rule of thumb, I recommend testing on a mail client that follows Dark Mode (i.e. Apple Mail or Thunderbird), Gmail and Outlook. More often than not a few tweaks in your logos and the accent colors you use will be enough to create a pleasant, though not true to your design, experience on email clients which do not support Dark Mode correctly.