
ha-lovelace-taste
Build Home Assistant dashboard cards, editors, badges and dialogs that look and behave like native Home Assistant UI.
- GitHub stars
- 18
Install
/plugin install ha-lovelace-taste@ha-lovelace-tasteRun it inside Claude Code after adding the marketplace with /plugin marketplace add fabioscarparo/home-assistant-lovelace-taste-skill.
Contents
Discovered from sourceSkills 1
Home Assistant cards that feel native
A good custom card is one a user can't tell apart from a core card. Home Assistant users switch between light and dark themes, custom themes, languages, 12 and 24 hour clocks, masonry and sections dashboards, phones and wall tablets. A card that hard-codes a color, a font or a pixel width breaks on some of these, and users notice at once. So the rule behind everything below: take every visual decision from Home Assistant itself, and add your own design only on top of its tokens.
Read the reference files when you get to that part of the work:
references/design-tokens.md- the tokens with their light and dark defaults, and ready-made CSS for the native patterns (tile header, badges, alerts, features, segmented control, select rows, charts, dialogs and bottom sheets)references/card-api.md- card and editor skeletons, re-rendering, registration that survives the frontend's registry swap,hasshelpers, events, distribution through HACS or the integration itselfreferences/verification.md- the mockhassdemo page, scenarios from real data, the regression check between versions, README images in both themes, the release checklist
Workflow
- Start from the data, not the mock-up. Ask for (or find) the real entities: domain,
translation_key, states, attributes, units, device class, which ones are disabled by default orunavailable. An export of the entities of one device, taken in a few states (off, ready, running, finished), is worth more than any description. If the integration has more than one version or fork, collect data from each: keys, state casing and option order often differ. - Pick the closest native pattern and mirror it. Before inventing a layout, look at what core
already does for the same job: tile card (header, icon tinted by state), thermostat card (dial,
minus and plus), entities card rows, badges,
ha-alert, more-info dialogs, card features. Reuse their sizes, typography and behavior. - Build with tokens only (next section). Raw values appear only as fallbacks inside
var(). - Wire it the Home Assistant way: formatting through
hass, actions through standard services, more-info on tap, a visual editor withha-form, entities found from the device. - Verify in light and dark, in every supported language, at phone width and in a sections grid, against real data, and against the previous release so nothing else changed.
- Ship with a version, short release notes and images rendered from the real card.
Design system essentials
Full list and copy-ready CSS in references/design-tokens.md. The parts that matter most:
- Let
ha-cardown the surface. Wrap the card in<ha-card>: it already applies the theme's background, border, radius and shadow (--ha-card-background,--ha-card-border-*,--ha-card-border-radius,--ha-card-box-shadow). Don't paint your own card background. - Text:
--primary-text-color,--secondary-text-color,--disabled-text-color, and--text-primary-colorfor text on an accent fill. Never#000,#ffforrgba(0,0,0,.6). - Type scale:
--ha-font-family-body,--ha-font-size-xs/s/m/l/xl/2xl/3xl,--ha-font-weight-normal/medium/bold,--ha-line-height-condensed/normal. The tile card's name is size m (14px) at medium weight, its secondary line size s (12px) in the secondary color. - Spacing and radii:
--ha-space-1to--ha-space-20(steps of 4px) and--ha-border-radius-sm/md/lg/xl/2xl/3xl/pill, instead of your own numbers. - Colors: the named palette
var(--{name}-color)(red, pink, purple, deep-purple, indigo, blue, light-blue, cyan, teal, green, light-green, lime, yellow, amber, orange, deep-orange, brown, grey, blue-grey...), the semantic ones (--info-color,--warning-color,--error-color,--success-color) and the state ones (--state-icon-color,--state-inactive-color). Let the user pick the card color with theui_colorselector and turn names intovar(--{name}-color). - Tints instead of new colors: core components put a layer of the color behind the content
(
::beforewithopacity: 0.2for tile icons and buttons,0.12for alerts);color-mix(in srgb, var(--accent) 20%, transparent)does the same where a layer doesn't fit. Both are right in light and dark, because they show whatever is behind them. - Neutral controls use
--disabled-colorat 0.2 opacity, 42px high, like card features. - Component tokens: honor
--ha-tile-icon-border-radius,--ha-card-features-border-radius,--ha-badge-border-radius,--ha-dialog-border-radiusand--ha-dialog-surface-backgroundin the matching pattern, so a theme that restyles core cards restyles yours too. - Icons:
<ha-icon icon="mdi:...">sized with--mdc-icon-size. Check that every icon name exists in the MDI version Home Assistant ships (a missing name renders as an empty square). - Always give a fallback,
var(--ha-font-size-m, 14px): older Home Assistant versions and some themes don't define the newer tokens.
Design on top, not instead: a custom dial, a hob map or a usage chart is fine, as long as its strokes, fills, text and states come from the same tokens. Check it with a dark theme and with a custom theme that changes the primary color.
Light and dark, always both
Every card must look right in the light theme and in the dark theme from the first draft, not as a fix later. Users switch themes by hand, by schedule or with the sun, and a card that only works in one of them is broken for half of them.
- The theme comes from Home Assistant, not from the operating system. Don't use
prefers-color-schemeinside a card: the user can run a dark Home Assistant on a light OS. Read colors from the theme tokens; if logic really needs to know, usehass.themes.darkMode. - No fixed colors for text, surfaces, lines or fills. Every one of them comes from a token, so
the theme changes them for you. The only fixed colors are fallbacks inside
var(). - Tint with an opacity layer or
color-mix(..., transparent), never by mixing with white or black: the tint then sits on the light or dark card background and keeps its meaning in both. - Defaults change with the theme, not only the background:
--disabled-colorgoes from#bdbdbdto#464646,--energy-grid-return-colorchanges too. Colors computed in JavaScript (chart shades read withgetComputedStyle) must be recomputed whenhass.themeschanges. - Text on a filled shape (a full accent button, a zone at high power) uses
--text-primary-coloror white, and the fill must be strong enough for it in both themes: set a minimum opacity rather than letting a pale fill carry white or dark text. - Shadows and scrims stay neutral and soft (
rgba(0, 0, 0, 0.28)and similar); they read in both themes. Borders use--divider-coloror the card border tokens. - SVG drawn by the card uses
currentColoror the same tokens infillandstroke, never literal colors. - Check both themes on every change: in the demo, in screenshots and in the release images.
README images ship as a pair inside
<picture>with<source media="(prefers-color-scheme: dark)">, because GitHub follows the reader's theme.
Behavior that feels native
- Tap the header or a value to open more-info (
hass-more-infoevent): users expect to reach the entity, its history and its settings from anywhere on a card. - Use standard services (
switch.toggle,select.select_option,number.set_value,button.press), so actions show in the logbook and can be reproduced in automations. - Format with Home Assistant:
hass.formatEntityState(stateObj)for states and units;Intlformatters that followhass.locale.number_format(decimal separator chosen by the user, not by the language),hass.locale.time_format(12, 24, language, system) andhass.locale.time_zone. Don't format numbers or dates by hand. - Optimistic UI with a timeout: show the new value at once, mark it as pending, and drop the pending value when the state arrives or after a few seconds.
- Debounce repeated taps on minus and plus, then send one call, like the thermostat card.
- Don't re-render what didn't change:
hassis replaced on every state change in the instance. Redraw only when the card's own entities, the registry, the language or the theme changed, and then patch the DOM rather than replacing it, so open selects, focus and animations survive. - Errors go to a toast (
hass-notificationevent) in the user's language. - Unavailable is not off: show
unavailableandunknownas such, hide features whose entities never report a value, and don't treat an entity left behind by an old version (restored: truein its attributes) as the real one.
Finding entities
Don't ask users to type entity ids. Let them pick the device in the editor (device selector
filtered by integration and model), then read hass.entities (the entity registry) and keep the
entities of that device, recognized by their translation_key. Renamed entities keep working,
and the card works in every language. When versions of the integration name a key differently,
keep a small alias table; when an old and a new entity share a key, prefer the one that has a
state.
Languages
Follow the user's language (hass.locale.language, then hass.language), with English for
anything else. Ship your own strings for what the integration doesn't translate (program names,
options), named like the vendor's own app in that language, and keep them in one table that can be
exported for translators. Program and option ids from different appliances can collide: scope
names by appliance type when the same id means different things.
Layout and accessibility
- Grid size: implement
getGridOptions()for sections dashboards (for example{ columns: 12, min_columns: 6 }) andgetCardSize()for masonry. - Container queries (
container-type: inline-sizeon the card) instead of viewport media queries: the same card can be a third of a desktop or a full phone width. - Touch targets of at least 40px, rows of 42px like card features.
- Keyboard:
role="button",tabindex="0", Enter and Space on anything clickable;aria-pressedon toggles;aria-labelon icon-only buttons; a:focus-visiblering in the accent color. - Dialogs: a native
<dialog>styled like Home Assistant's (580px wide, 24px radius), that becomes a bottom sheet on phones (core switches below 870px wide or 500px tall) with room for the safe area. - Reduced motion: stop or shorten animations under
prefers-reduced-motion: reduce, as core does.
Changing an existing card
Treat every card that already ships as a contract: adding a card or a feature must not change the
others. Before proposing a commit, render every card, in every state and language, with the
published version and with the new one, and explain every difference (see
references/verification.md). Data from real users, including the other version of the
integration, belongs in that check. Shared code (base classes, string tables, alias tables,
helpers) is where accidental changes come from: give new behavior a hook that does nothing by
default, so the output of the other cards stays identical byte for byte.
Lessons from real appliances that a mock won't show:
- Durations in hours as floats: one minute is
0.0166666666666667 h, which is 60.0000001 seconds. Round before comparing with thresholds. - Options listed as text, so
min120comes beforemin30: sort stepped values by their number. - State casing differs between versions (
Runandrun): normalize before comparing. - An entity can exist and stay
unavailableforever because the appliance lists the feature but never reports it. - Several entities can share one
translation_key(zones, cavities): tell them apart by the number in the entity id or friendly name.
Shipping
- One ES module file: hand-written vanilla JavaScript, or Lit and TypeScript bundled by
esbuild. A
VERSIONconstant and a console banner with it. - Register after the app has started. Home Assistant swaps
window.customElementsfor a polyfilled registry while it boots; an element defined before that is unknown to the dashboard ("Custom element doesn't exist"). Wait forhome-assistant(orhc-main) to be defined, then define the card and editor if not defined yet. Push the card intowindow.customCardsonce, withpreview: true, so it shows in the card picker. - Distribution: a HACS plugin repository (
hacs.jsonwith the file name), or the card served by its own integration (static path plusadd_extra_js_url, with a?v=that changes with the file), so users install one thing. Details inreferences/card-api.md. - A release per version with short notes.
- README images rendered from the real card in light and dark, text drawn as paths, with demo data that contains nothing personal (names, IP addresses, serial numbers).
Sponsors
Details
- Marketplace
- fabioscarparo/home-assistant-lovelace-taste-skill
- Category
- Development
- Keywords
- home-assistant, lovelace, dashboard, custom-card, hacs