Better theming documentation

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](https://github.com/vector-im/element-web/blob/develop/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. \#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](https://github.com/vector-im/element-web/blob/develop/docs/labs.md#custom-themes-feature_custom_themes) 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](https://github.com/aaronraimist/element-themes) provides a directory of custom themes. You can copy a theme's URL directly from there, for example: [Solarized Dark.json](https://raw.githubusercontent.com/aaronraimist/element-themes/master/Solarized/Solarized%20Dark/Solarized%20Dark.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](https://github.com/vector-im/element-web/blob/develop/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.:

```json
"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](https://github.com/vector-im/element-web/blob/develop/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](https://github.com/vector-im/element-web/blob/develop/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](#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](https://github.com/matrix-org/matrix-react-sdk/tree/develop/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?