Skip to content

Theme structure

Home Assistant Theme Structure

Each Home Assistant dark/light theme follows the same structure. It has definitions for both dark and light mode, and a specific section to define colors specific to dark or light mode:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
  Theme Name:
    #
    # Generic definitions
    #
    css-var-1: #123456
    css-var-2: var(--css-var-1)

    #
    # Light and Dark specific definitions
    #
    modes:
      light:
        css-text-color: black
      dark:
        css-text-color: white

Home Assistant Material 3 Theme Structure

The HAM3 theme structure is no different, it has to comply with the Home Assistant theme structure.

An Home Assistant Material 3 theme is divided into 3 blocks:

Block 1 - Copy/paste Material 3 Theme generated definitions
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
  Theme Name:
    #
    # M3 Theme generated definitions
    #
    # This is the ONLY part of the theme that is changed
    # The rest of the theme definition is GENERIC!!!!!!!
    #
    theme-ref-palette-* light and dark definitions
    theme-ref-elevation-* light and dark definitions

    ...
Block with the Material 3 Theme definitions

Block 2 - Generic Dark/Light mappings of the reference colors using Material 3 guidelines
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
    #
    # Light and Dark specific definitions
    # Derived from theme-ref-palette-* definitions
    #
    # NOT to be changed on a per theme basis.
    # The Light and Dark modes map a Material 3 reference color
    # to a Material 3 system color!
    #
    modes:
      light:
        theme-sys-color-* light theme definitions
        theme-sys-palette-* light theme definitions
        theme-sys-elevation-* light theme definitions

        theme-* definitions for use with Material 2 / Home Assistant
      dark:
        theme-sys-color-* dark theme definitions
        theme-sys-palette-* dark theme definitions
        theme-sys-elevation-* dark theme definitions

        theme-* definitions for use with Material 2 / Home Assistant
    ...
Block with the Dark/Light mode mappings, including dark mode modifications for some Home Assistant theme colors

Block 3 - Mapping of Material 2 and Home Assistant CSS variables
1
2
3
4
5
6
7
    #
    # Generic CSS Material 2 / Home Assistant definitions using
    # definitions from the light or dark mode colors
    #
    primary-color: var(--theme-sys-color-primary)
    <etcetera>
    ...
Block with the Material 2 and Home Assistant color mappings.

Home Assistant Material 3 Theme Template

Github repository

Since the HAM3 theme mainly maps Material 3 reference colors to system colors (light/dark independent) and existing Home Assistant theme settings, it is very easy to use a HAM3 theme template and only assign the generated Material 3 reference color definitions to add to an entirely new theme.

Using a generic theme section where you just need to enter the Material 3 reference colors has proven to be very effective: I created the 7 dynamic theme samples in less than an hour. The primary colors are derived from an image from my image library to generate the M3 color definition.

The following parts should be changed and filled in by you:

  • the hacs.json file if you want to publish your theme on HACS
  • the .github actions if you want to publish your theme on HACS (just rename the hacs-action file to .yml
  • the READme
  • the main one: the themes/m3-xx-yyyy.yaml file. It should be renamed of course, and the generated m3 reference definitions should be inserted (see comments in that file where that should be done)

To keep compatibility between HAM3 themes, it is strongly advised NOT to change generic theme parts!

Back to top