Better theming documentation

[psrpinto]

I've been researching how themes work in Element, originally with the goal of providing a fix for #16804. However, I've hit a roadblock since there are many things I am not able to understand on my own. Since I believe other newcomers to Element theming will have similar trouble, I'm opening this issue to document my findings, and in hopes of gathering contributions and discussion from the community. If this endeavor is successful, I can then propose changes to theming documentation in the form of a PR.

---

Existing documentation

AFAICT, the only existing documentation for themes is docs/theming.md. However, this documentation is outdated (see #16804) and, I believe, incomplete. If you're aware of other pieces of documentation on theming please leave a comment below.

Previous efforts to improve theming documentation

1. Updated theming.md with proper namings #16802, which has now been closed and the code is no longer available.

Findings

Selecting a theme

The user can select their active theme under Settings -> Appearance. By default, they can choose between one of the bundled themes which are Dark or Light. Additionally, they have the option to Match system theme, in which case the selected theme will automatically follow the Operating System's setting.

Custom themes Labs feature

If the custom_themes Labs feature is enabled, in addition to being able to select from the bundled themes (Light and Dark), an additional input field is displayed, in which the user can paste the URL to the JSON definition of a custom theme.

aaronraimist/element-themes provides a directory of custom themes. You can copy a theme's URL directly from there, for example: Solarized Dark.json

Once a custom theme is installed, it becomes available for the user to select as their active theme.

It's currently not possible to delete (#13221) nor update (#13222) a previously installed theme. Changing the remote .json and trying to re-add a theme with the same name doesn't seem to do anything. A workaround for this is to create a new theme for each existing theme change.

Default theme

It's possible to configure a default theme, which will be applied to users who haven't specifically selected a theme. This can be done through the default_theme setting, documented in docs/config.md:

default_theme: name of theme to use by default (e.g. 'light')

I think this could be expanded to state the following:

default_theme: name of the theme to use by default (e.g. 'light'). When a user explicitly selects a theme (under Settings -> Appearance), their selection is saved in Local Storage (mx_local_settings.theme). The default_theme option only applies to sessions which do not have the mx_local_settings.theme option set.

When setting default_theme to a custom theme that has previously been installed from the URL of a JSON file, the theme name should be preceeded by custom-, e.g.:

"default_theme": "custom-Solarized Dark"

However, this doesn't appear to work correctly: when navigating to Settings -> Appearance, the custom theme is indeed selected, but the UI is rendered with the Light theme instead. EDIT: this issue is tracked in #17721.

Message layouts

It's possible to change the appearance of messages on the timeline. There are several layouts available, which can be selected under Settings -> Appearance -> Show advanced. Currently, the available layouts are:

• Modern (the default)
• IRC
• A more compact version of the Modern layout

Additionally, when the New layout switcher Labs feature is enabled, a new bubbles layout becomes available, along with a different method for selecting layouts, available under Settings -> Appearance:

The "compact modern" layout can still be selected under Show advanced.

Questions

If you have information related to these questions, please add a comment with everything you know.

Custom themes (aka JSON themes?)

In docs/theming.md, there's a section on "Custom Themes", which can be enabled through the JSON config. These JSON themes appear to extend another theme, but it's not clear which theme they are extending. Are they extending the included light (or dark) theme? Or the legacy-light (or legacy-dark) themes? What if my selected theme is something else, will they extend that one instead?

Another kind of custom themes

In docs/theming.md, on top of the file there's a section describing how to create a custom theme, using SCSS. This appears to be a different thing than the custom JSON themes. How would these SCSS themes be distributed? Meaning, how can a user create and then start using the theme they just made? Is this just intended to be documentation on how to create a theme for bundling with Element?

Custom themes Labs feature

Custom themes installed from the URL of a JSON file (see Custom themes Labs feature above) appear to persist across sessions, for example, they're still available on an Incognito window. Where are these themes installed?

Message layouts (Modern, IRC, bubbles)

Under Settings -> Appearance, the user can select a message layout (see Message layouts section above).

• How are these layouts technically implemented? Through extra stylesheets that are applied on top of the selected theme's stylesheets?
• Are there specific things custom themes need to do to guarantee compatibility with these layouts?

legacy and custom themes

Under matrix-react-sdk/res/themes, there are legacy and custom themes.

legacy themes

• What are the legacy-light and legacy-dark themes?
• How can I select one of the legacy-* themes as my active theme?

custom themes

• What are the light-custom and dark-custom themes?
• How can I select one of the *-custom themes as my active theme?
• How come the light-custom and dark-custom themes use resources from the legacy-light theme? Does this mean this *-custom themes are also legacy?
• Why does dark-custom use resources from legacy-light? Shouldn't it use resources from legacy-dark instead?

[Oha-you]

Regarding

the custom theme is indeed selected, but the UI is rendered with the Light theme instead

It's an open issue: #17721. Noticed it as well and it's quite annoying to set the theme on each app restart.

--
Another question I have: how do you update a custom theme added from a URL?
Changing the remote .json and trying to re-add a theme with the same name doesn't seem to do anything.
So basically you have to create a new theme for each existing theme change. And you can't remove old themes either 🤷‍♂️

UPD: there's an issue for it too.. #13222

[psrpinto]

Thanks @Oha-you! I've updated the issue description with the points you raised.

[psrpinto]

Added section on Message layouts to issue description.