External palettes¶
External palettes store reusable color variables in a separate JSON file that the Flexible Horseshoe Card can load.
They are useful when several cards share the same color system or when large color definitions would make the card YAML difficult to read. A palette can also provide separate values for Home Assistant light and dark modes, allowing the card to adapt automatically to the active theme.
Basic usage¶
Define external palettes in the top-level palettes section of the card configuration.
Each entry contains:
- a palette name;
- the path to its JSON file.
In this example:
| Part | Meaning |
|---|---|
rainbow | The name used to identify the palette. |
/local/palettes/rainbow-palette-new.json | The location of the external JSON file. |
The browser loads the palette file separately. Once available, its variables can be used throughout the card configuration.
Palette loading and browser cache
A palette may take a moment to load the first time it is used or after a hard refresh.
Until loading is complete, colors that depend on the palette may temporarily fall back to black or another default value. The configured colors appear as soon as the palette becomes available.
Palette file structure¶
An external palette contains two main sections:
| Section | Purpose |
|---|---|
ref | Stores the base color references. |
modes | Maps palette variables to values for light and dark mode. |
This structure follows the same general idea as Home Assistant theme variables: define the base values once, then select suitable values for each display mode.
The ref section contains the actual color values. The modes section defines which references the card should use in light and dark mode.
Material Design 3 palette format¶
The palette structure is based on the Material Design 3 tonal palette concept.
Each color is represented by a range of tonal values, typically numbered from 0 to 100. Lower values are darker, while higher values are lighter.
| 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 selects which tone should be used for each display mode.
For example, a light theme might use red50, while a dark theme uses red70. The card YAML can continue using the same system variable, while the palette chooses the appropriate underlying color.
Creating your own palette¶
You can create an external palette with a dedicated palette generator, a design tool, or an AI assistant.
Palette generators are useful when you need precise Material Design 3 tonal output from one or more seed colors. An AI assistant can help produce the required JSON structure, consistent variable names, and separate mappings for light and dark mode.
A useful prompt should specify:
- the base or seed colors;
- the palette name or naming prefix;
- whether light and dark mode mappings are required;
- the expected
refandmodesstructure; - the required tone steps, 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
Treat AI-generated palettes as a starting point. Review them visually, verify sufficient contrast in both modes, and confirm that every generated variable name matches the name used in the card YAML.
Using palette colors¶
After loading the palette, use its variables like other CSS custom properties.
Palette variables can also be used in styles:
This keeps the card YAML readable while the external file manages the underlying color system.
Light and dark mode¶
The modes section can assign different references to the same system variable for light and dark mode.
In light mode, --fhs-sys-rainbow-red resolves to --fhs-ref-rainbow-red50. In dark mode, it resolves to --fhs-ref-rainbow-red70.
The card configuration can therefore keep using one variable:
The displayed color changes automatically with the active mode.
Example palette¶
The following rainbow palette includes tonal reference colors and separate mappings for light and dark mode.
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 a good choice when:
- multiple cards share the same color system;
- the color definitions are too large to keep in the card YAML;
- light and dark mode require different values;
- the dashboard uses a custom visual identity;
- the same color variables are reused in several places.
For a small, one-off card, inline color stops may be simpler. For larger dashboards and reusable designs, external palettes keep the configuration cleaner and easier to maintain.