Frontend docs for new dark mode themes (#17960)

Co-authored-by: Franck Nijhof <git@frenck.dev>
This commit is contained in:
Philip Allgaier 2021-05-25 13:36:43 +02:00 committed by GitHub
parent f7b6bbaa1b
commit e3c7718aea
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -49,7 +49,9 @@ frontend:
## Defining Themes
Starting with version 0.49 you can define themes:
### Theme format
The frontend integration allows you to create custom themes to influence the look and feel of the user interface.
```yaml
# Example configuration.yaml entry
@ -60,11 +62,50 @@ frontend:
text-primary-color: purple
mdc-theme-primary: plum
sad:
primary-color: blue
primary-color: steelblue
```
The example above defined two themes named `happy` and `sad`. For each theme you can set values for CSS variables. If you want to provide hex color values, wrap those in apostrophes, since otherwise YAML would consider them to be comments (`primary-color: '#123456'`). For a partial list of variables used by the main frontend see [ha-style.ts](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/resources/ha-style.ts).
The example above defines two themes named `happy` and `sad`. For each theme, you can set values for CSS variables. If you want to provide hex color values, wrap those in apostrophes, since otherwise, YAML would consider them a comment (`primary-color: '#123456'`). For a partial list of variables used by the main frontend see [ha-style.ts](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/resources/ha-style.ts).
### Dark mode support
It is also possible to create themes that are based on the default dark mode theme. New themes can also support both light and dark mode and allow the user to switch between those on the user profile page:
{% my profile badge %}
Extended example to show the mode definitions.
```yaml
# Example configuration.yaml entry
frontend:
themes:
happy:
primary-color: pink
text-primary-color: purple
mdc-theme-primary: plum
sad:
primary-color: steelblue
modes:
dark:
secondary-text-color: slategray
day_and_night:
primary-color: coral
modes:
light:
secondary-text-color: olive
dark:
secondary-text-color: slategray
```
Theme `happy`: Same as in the previous example. This legacy format is still supported and will behave as before and automatically use the default light theme as the base.
Theme `sad`: By using the new `mode` key plus the subkey `dark` this theme will now be based on the default dark theme. The final theme rules are determined in three steps: First, the default dark theme CSS variables will be applied, then second the CSS variables from the top level of the theme that are mode-independent (`primary-color: steelblue` in this example) and lastly the mode-specific CSS variables will be layered on top (`secondary-text-color: slategray`).
Note: Since this example theme only has a `dark` mode defined, this mode will automatically be used.
Theme `day_and_night`: This theme has both a `light` and a `dark` mode section. That tells the frontend to allow the user to choose which mode to use from the user profile (default selection is based on the system settings). Independent of the selection, the primary color will be set to green, but based on the chosen mode either the default light or dark theme will be used as the basis for rendering, plus the secondary text color will be either olive or slategray.
### Theme configuration splitting
As with all configuration, you can either:
- Directly specify the themes inside your `configuration.yaml` file
@ -75,9 +116,9 @@ For more details about splitting up the configuration into multiple files, see [
Check our [community forums](https://community.home-assistant.io/c/projects/themes) to find themes to use.
## Setting themes
## Setting Themes
There are 2 themes-related services:
There are two themes-related services:
- `frontend.reload_themes`: Reloads theme configuration from your `configuration.yaml` file.
- `frontend.set_theme`: Sets backend-preferred theme name.