External palettes¶
External palettes let you define reusable color variables in a separate JSON file and load them into the Flexible Horseshoe Card.
This is useful when you want a consistent color system across multiple cards, or when you want to keep large color definitions out of your card YAML. A palette can also define different colors for light and dark mode, so your card can adapt to the active Home Assistant theme.
Basic usage¶
A palette is defined in the top-level palettes section of the card configuration.
Each palette has:
- a name
- a path to a JSON palette file
Example:
1 2 | |
In this example:
| Part | Meaning |
|---|---|
rainbow | The palette name |
/local/palettes/rainbow-palette-new.json | The location of the JSON palette file |
The palette file is loaded by the browser. After it has been loaded, the variables from the palette can be used in the card configuration.
Palette loading and browser cache
External palettes are loaded separately by the browser. The first time a palette is used, or when it is not yet available in the browser cache, loading can take a short moment.
During that time, colors that depend on the palette may temporarily fall back to black or another default value. Once the palette has loaded, the configured colors are applied.
This usually only affects the first load or a hard refresh.
Palette file structure¶
An external palette is a JSON file with two main parts:
| Section | Purpose |
|---|---|
ref | Defines the base color references |
modes | Defines which colors are used in light and dark mode |
The structure follows the same idea as Home Assistant theme variables: base values are defined once, and mode-specific variables refer to those values.
A simplified palette looks like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | |
The ref section contains the actual color values. The modes section defines the variables that should be used by the card in light and dark mode.
Material Design 3 palette format¶
The palette structure is based on the Material Design 3 tonal palette idea.
In a Material Design 3 palette, each color is available in a range of tonal values, usually named from 0 to 100. Lower values are darker, higher values are lighter. For example:
| Token | Meaning |
|---|---|
fhs-ref-rainbow-red0 | Darkest red tone |
fhs-ref-rainbow-red50 | Mid-range red tone |
fhs-ref-rainbow-red90 | Very light red tone |
fhs-ref-rainbow-red100 | Lightest red tone |
The ref section stores these tonal values. The modes section then chooses which tone should be used for light and dark mode.
For example, a light theme may use red50, while a dark theme may use red70. Your card YAML can keep using the same variable name, while the palette decides which actual color fits the active mode.
Creating your own palette¶
You can create an external palette in different ways.
Previously, tonal palettes like this were usually created with dedicated palette generators or design tools. Those tools are still useful, especially when you want exact Material Design 3 output from a seed color.
You can also create a palette with an AI assistant, such as ChatGPT. This can be helpful when you want a palette in the correct JSON structure, with consistent variable names and separate light and dark mode mappings.
A good prompt should include:
- the base colors or seed colors you want to use
- the palette name or naming prefix
- whether you want light and dark mode mappings
- the expected JSON structure with
refandmodes - the tone steps you want, such as
0,10,20,30,40,50,60,70,80,90,95,99, and100
Example prompt:
Create a Material Design 3 style tonal palette as JSON for the Flexible Horseshoe Card.
Use the prefix fhs-ref-energy and create tonal values from 0 to 100 for green, yellow, orange, and red.
Add a modes section with light and dark mappings using fhs-sys-energy-green, fhs-sys-energy-yellow, fhs-sys-energy-orange, and fhs-sys-energy-red.
Use this structure:
{
"ref": {},
"modes": {
"light": {},
"dark": {}
}
}
Review generated palettes
AI-generated palettes are a good starting point, but always review the result visually. Check that the colors have enough contrast in both light and dark mode and that the generated variable names match the names used in your card YAML.
Using palette colors¶
After the palette is loaded, its variables can be used in card configuration just like other CSS variables.
For example:
1 2 3 4 5 6 7 8 9 | |
You can also use palette variables in styles:
1 2 3 | |
This keeps the card YAML readable while the actual color system stays in the external palette file.
Light and dark mode¶
The modes section allows a palette to define different values for light and dark mode.
Example:
1 2 3 4 5 6 7 8 9 10 | |
In light mode, --fhs-sys-rainbow-red uses --fhs-ref-rainbow-red50.
In dark mode, the same variable uses --fhs-ref-rainbow-red70.
This means your YAML can keep using the same variable name:
1 | |
The actual color changes automatically with the active mode.
Example palette¶
The following example shows the structure of a rainbow palette with reference colors and light/dark mode mappings.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 | |
When to use external palettes¶
External palettes are useful when:
- multiple cards should use the same color system
- the list of colors is too large to keep inside the card YAML
- you want different colors for light and dark mode
- you want to create a custom look or branding for your dashboard
- you want to reuse color variables in several places
For small one-off cards, inline color stops may be simpler. For larger dashboards or reusable themes, external palettes keep the configuration cleaner and easier to maintain.