Summary of Changes

• Atum uses CSS variables instead of hardcoded colours all over the place
• Atum allows you to select the colour scheme: Always Light, Browser Decides, Always Dark
• You can override the colour scheme in your user profile: Use Default (whatever the template style says), Always Light, Browser Decides, Always Dark
• TinyMCE can auto-switch its skin to oxide-dark when the template communicates it will be using a dark colour scheme. This can be turned off BOTH at the template style level AND at the editor plugin level.
• TinyMCE can optionally load a minimal CSS to make content editing use a dark colour scheme. This can be turned off in the editor plugin, e.g. if the frontend template's editor.css already does that.
• CodeMirror can auto-switch its theme to an alternate theme when the template communicates it will be using a dark colour scheme. This can be turned off BOTH at the template style level AND at the editor plugin level.
• Introduced a new editor plugin method public function onTemplateDarkModeSupported(bool $forcedDark) and a matching \Joomla\CMS\Editor\Editor::notifyDarkMode method for templates to notify editors that dark mode is to be applied.
• Documented HOW (and WHY) one should build Joomla's SCSS files, since the contributor of this feature would not be bothered to in his PR a year ago and treats everyone who does not magically posses this undocumented knowledge like they are stupid.

Testing Instructions

Install one of the pre-built packages.

Test 1: Dark mode generally works

Switch your browser to Dark Mode (see How To Test Dark Mode below). The Joomla backend appears with a dark colour scheme.

Use as many core features as you can.

Test 2.A: Test forced light mode at the template style level

Switch your browser to Dark Mode.

Edit the default backend template style. In the Dark Mode tab set the dark mode option to Always Light.

All backend pages, including the login page are using a light colour scheme.

Test 2.B: Test forced dark mode at the template style level

Switch your browser to Light Mode.

Edit the default backend template style. In the Dark Mode tab set the dark mode option to Always Dark.

All backend pages, including the login page are using a dark colour scheme.

Test 3.A: Test forced light mode for a specific user.

Switch your browser to Dark Mode.

Edit the default backend template style. In the Dark Mode tab set the dark mode option to Browser Preference.

Edit your user. Under Basic Settings set the dark mode option to Always Light.

All backend pages, except the login page, are using a light colour scheme when you log into your site with this user account.

Test 3.B: Test forced dark mode for a specific user.

Switch your browser to Light Mode.

Edit the default backend template style. In the Dark Mode tab set the dark mode option to Browser Preference.

Edit your user. Under Basic Settings set the dark mode option to Always Dark.

All backend pages, except the login page, are using a dark colour scheme when you log into your site with this user account.

How to test Dark Mode

On Windows 10, Windows 11, macOS Catalina or later, iOS/iPadOS 13 or later, and GNOME it is generally sufficient to switch your Operating System colour scheme to dark.

All browsers except Safari and on all OS except macOS, iOS, and iPadOS let you choose whether the browser's colour scheme will follow the OS colour scheme or not. For example, Chrome has an option for the theme under settings, appearance. Using an option called Auto, System, or GTK will use the OS colour scheme.

If you are using Linux but NOT GNOME as your desktop environment auto-switch between light and dark mode may not work. Choose one.

If you don't know if your browser auto-switched to dark mode please visit duckduckgo.com or Dionysopoulos.me. If the site appears with a prominently dark background your browser has switched to dark mode.

Link to documentations

Please select:

• Documentation link for docs.joomla.org: See below; cannot do PRs to docs.joomla.org!

• Pull Request link for manual.joomla.org: Joomla Manual PR 66

Documentation for docs.joomla.org

Since it is not possible to make a PR to docs.joomla.org I am putting the documentation in four sections below and I'm waiting for instructions on how and when to proceed.

Docs: New options in Atum

URL: ATUM IS NOT DOCUMENTED(!!!) as per https://docs.joomla.org/JDOC:Joomla_4_Tutorials_Project

The Dark Mode section works similarly to the Colour Settings section. It allows you to set up the colours of the template — but for an optional, dark color scheme.

The Atum backend template lets you display the Joomla administrator backend in a dark colour scheme, suitable for low ambient light conditions and people with photosensitivity. Whether and when to use this color scheme is determined by the Dark Mode support option and can be overridden in the preferences of every user who has backend access. Please note that the setting of the Dark Mode support option in the default backend template style also controls whether the administrator login page will be displayed with a dark color scheme.

It can have one of the following settings:

• Always Light: the dark colour scheme will not be used at all.
• Browser Preference: This is the recommended and default option. The template will hoour the light or dark color scheme preference of the browser. Most browsers mirror the preference set system-side on most modern Operating Systems. Some browsers, especially those running under Linux, may allow the user to set their preferred colour scheme in the browser settings.
• Always Dark: the dark colour scheme will always be applied, regardless of the browser settings.

Atum can also communicate the dark colour scheme configuration to the editor plugins in Joomla, as long as the Dark Mode support in editors option is enabled. Please note that this only sends a signal to the editor plugin, communicating if and when a dark colour scheme needs to be applied. It is up to the editor plugin to act on this signal. The TinyMCE and CodeMirror editor plugins shipped with Joomla support and respect this signal. For third party editor plugins please refer to their documentation as supplied by their developers.

The rest of the options are identical to those found under Colour Settings and have the same meaning, but only apply when the dark colour scheme is in use.

New user options

URL: https://help.joomla.org/proxy?keyref=Help42:Users:_Edit_Profile&lang=en

(Place this under section 4.3 Basic settings, below “Backend Template Style”)

• Administrator Dark Mode: Choose the preferred color scheme of the administrator template. You can choose between a light and a dark colour scheme, or have it automatically follow your browser's preferences. In most cases, the browser preferences are identical to your Operating System's preference for light or dark display. Use Default uses the preference for this option defined in the administrator template style you are using. This option may not work for all administrator site templates.

Docs: Editor - CodeMirror

URL: https://docs.joomla.org/Chunk4x:Extensions_Plugin_Manager_Edit_Editor_Group/en#Editor_-_CodeMirror

Dark Mode.

This tab allows you to choose what happens when your site displays with a dark color scheme. Please note that options in this tab may not work with all front- and backend templates. The settings will only be applied if the template communicates that it's using a dark colour scheme.

• Auto-apply Dark Mode. The editor will use an alternate color theme when your template communicates that it is using a dark colour scheme.
• Dark Theme. The alternate theme to use when your template communicates that it is using a dark colour scheme. Please note that this drop-down list includes all CodeMirror themes. It is ultimately up to you to select a theme which looks dark to you and seems to work best with your site's dark colour scheme.

Docs: Editor - TinyMCE

URL: https://docs.joomla.org/Chunk4x:Extensions_Plugin_Manager_Edit_Editor_Group/en#Editor_-_TinyMCE

Dark Mode.

This tab allows you to choose what happens when your site displays with a dark color scheme. Please note that options in this tab may not work with all front- and backend templates. The settings will only be applied if the template communicates that it's using a dark colour scheme.

• Auto-apply Dark Mode. The editor will use an alternate color theme when your template communicates that it is using a dark colour scheme.
• Load dark color scheme compatibility CSS in the editor. Loads a small CSS file which tries to apply a dark colour scheme on the edited content. You are recommended to disable this option if your frontend template includes support for a dark colour scheme in its editor.css file. If unsure, ask your template developer.

Please note that the “Auto-apply Dark Mode” option only takes effect if you have selected either - Use Default - or oxide in the Plugin tab options “Site Skin” (applies to the site's frontend only) and “Administrator Skin” (applies to the site's backend only). If you have chosen a different skin that skin will be used when your template displays in both light and dark color schemes.

As noted, not all templates communicate their dark color scheme preference to editors — or can be configured not to do that. In this case the options in the Plugin tab apply.

Backwards compatibility notes

The PR is generally backwards compatible i.e. nothing breaks code-wise.

The introduction of the dark mode MAY cause minor display issues in some third party extensions. Extension developers are very strongly encouraged to support dark mode using the developer documentation (see the PR to manual.joomla.org).

Third party editor plugin developers are strongly encouraged to support dark mode using the developer documentation (see the PR to manual.joomla.org).

Translation impact

This PR introduces new language strings. This happens in the alpha stage which gives translation teams adequate time to work through these very few language strings.

Thoughts, questions, various information

There are CSS variables everywhere

Upon consulting with @crystalenka, I was told that the best way to go about implementing Dark Mode is to introduce CSS variables for distinct color patterns everywhere in the backend. Their utility reaches far beyond the implementation of dark mode. They can be used as a starting point for reworking the backend template into reusable components. They can be used to offer a real high contrast mode (instead of the current cop-out of just applying a filter which increases the overall contrast by 25%, with dubious results). In theory, someone could use them to provide an entirely different color scheme without having to override Bootstrap's SCSS defines, e.g. if someone with real commitment to their cause wants to create a child template of Atum.

Why is there extra CSS in TinyMCE?

TinyMCE unfortunately has its own weird way of handling CSS for its themes and it works by applying a CSS file in the IFRAME created in the Shadow DOM when the editor is initialised at runtime. It's not possible to load an additional CSS file after the fact, nor is it possible to load two or more CSS files (skins) at once. This normally limits TinyMCE to either a light (oxide) or dark (oxide-dark) skin.

In order to support dynamic colour scheme switching of the editor's UI following the browser settings (if that's what the user has opted for) I had to create a combined theme which is the oxide skin with the colour settings (and only the colour settings!) of the oxide-dark skin when the browser indicates we need to use a dark scheme. Hence the extra CSS.

Does X happen when Y?

If you have to ask this question it means you didn't test the PR ? Why don't you try it out for yourself? Chances are I have already thought of that and implemented it.

Seriously now, please DO NOT ask me questions which are self-evident if you actually test this PR. It will add to my workload and slow down this PR unnecessarily.

I do not see the light / dark mode when my system and browser settings are this and that

Hold up!

Visit the following sites:

• https://webkit.org/blog/8840/dark-mode-support-in-webkit/
• https://dionysopoulos.me/dark-mode-is-the-new-black.html
• https://www.akeeba.com
  All three sites have an automatic Light Mode / Dark Mode switch already implemented. The first one is maintained by Apple, the latter two by yours truly.

If you do NOT see the light/dark color scheme you expected, then the problem is with your setup. Remember that for dark mode to switch automatically you will need one of the following:

• Your Operating System using Dark Mode and your browser using an automatic color scheme. This is NOT the default case in Linux. If you're using anything other than GNOME even if you switch your desktop environment's theme you will be stuck with only light or only dark mode, depending on your browser settings. If you are using GNOME, sometimes you may have to log out and back into GNOME before the browser “takes” the new colour scheme.
• Your browser set to use a specific color scheme. This is typically set up in the browser's options. Safari does NOT have such an option; it always follows the display mode of macOS / iOS / iPadOS.

If you see the correct color scheme you expected in all three sites but not in the site you are testing please make sure that:

• you are NOT using Patch Tester; this PR changes CSS files therefore you'll need to either use the repository sources or one of the pre-built archives.
• you have run npm ci if you are using the repository sources (otherwise the CSS files WILL NOT BE REBUILT).
• cleared your browser's cache.
• set the Dark Mode option in the backend template style you are using.
• set the Dark Mode option in the user profile you are using (the user profile settings OVERRIDE the template style settings).

Remember that the default settings for the backend template is to follow the browser's preference and communicate the dark mode setting to the editor. The default for the user settings is to do whatever the template style says.

The editor is not changing to dark mode when the site is changing to dark mode

Make sure the template style has the Dark Mode support in editors option enabled (that's the default). Make sure that you are using either TinyMCE or CodeMirror supplied with Joomla itself; third party editors cannot possibly implement dark mode support before this PR is merged. Make sure that the editor you are using is set up to support dark mode (default).

Also remember that TinyMCE will only change its skin if you have selected the default skin, oxide. If you have selected oxide-dark, then oxide-dark will always be used and the content will NOT change to dark mode. This is deliberate as we don't want to catch users by surprise if they are using a non-default skin.

Do keep in mind that CodeMirror can be set up to use a non-default theme. It is possible that you've set it up to use a theme which is already dark. It is also possible to select a light-coloured theme for CodeMirror's dark mode as there is no positive indication in the theme names which one is light and which one is dark (at least, it's not consistent, therefore cannot be used).

Why show all CodeMirror themes for its Dark Mode when some are a light colour scheme?

Because the dark colour scheme themes DO NOT follow a consistent naming pattern. For example, Darcula and Dracula are dark colour scheme themes but do not have "dark" in their name.

To paraphrase Steve Jobs: “we have the reasonable expectation that our users are not stupid”.

I have a problem with extension X using Dark Mode

Chances are that it does not support Dark Mode for the simple reason that Dark Mode did not exist before Joomla 4.3, i.e. when this PR will be merged.

It is also likely that my own extensions will need a bit of a reworking to play well on Joomla 4.3 which is to say that I'm not giving myself an unfair advantage here. All of us 3PDs are in the same position.

I am getting some weird colours in Dark Mode

Do you have a 3PD extension implementing its own dark colour scheme, such as my DarkMagic plugin? Disable it!

The colour contrast is not accessible

There's only so much I can do when working with the limited palette of Dark Mode.

HOWEVER! Since we're using CSS variables everywhere I would expect that the fine folks at the Joomla Accessibility Team (most likely the design expert @angieradtke) can come up with a high contrast light and dark colour scheme we can very easily include in Atum. Moreover, if colours do need to be adjusted the JAT can very easily make the changes in the SCSS files as there are only two files (build/media_source/templates/administrator/atum/dark/_variables.scss and _root.scss) which need changing to tweak colours.

The idea here is to provide the groundwork for allowing multiple colour schemes in Joomla templates. We MUST NOT have the expectation that Joomla 4.3 will have a super duper ultra accessible and fully refined dark mode. This is something which will reasonably take the rest of the time to Joomla 4.4 / 5.0 to get there for two very simple reasons:

• You cannot know what you don't know, i.e. how 3PDs will interact with it.
• You cannot go through the entirety of Joomla with manual testing within a reasonable amount of time unless someone is paying you to spend the next several months doing that. Instead, we have to rely on what we bump into and reports we get as we go along after merging this PR.

Also keep in mind that unlike every other decision made in Joomla 4's templates, the decisions here are made in public, in the main repository. Everyone can see why at some point we have to say “that's good enough for version 1 of this feature” instead of making up a story. This is far more helpful in that it communicates the decision context and deadline limits we have to address when making these decisions. When we introduce a massive new feature we aim for a minimum viable product, not absolute perfection. Even multi-trillion dollar companies like Microsoft, Google, and Apple follow this approach; who are we to pretend we can do better with less than a billionth of their budget?