ha-badge-add

HA Badge Add

Spec: spec/claude/ha-badge-add/en.md (EN canonical) / spec/claude/ha-badge-add/de.md (DE translation).

Why this is a skill, not an agent

• Human-visible augmentation surface — the user describes a status display and reads back the badge element, the registration entry, and the conformance report; a skill keeps this on the visible command surface, like the sibling frontend skill ha-lovelace-card-scaffold.
• Mid-flow interactivity — the badge_type tag-name decision and the "graphical editor yes/no" choice are per-run dialogues the user approves before generation.
• Bounded, inline generation — one custom-element module plus its window.customBadges push and optional editor fit inline; no isolated agent context is needed.
• Counter-dimension considered: the draft→validate loop could be an agent, but the tag-name and editor-depth decisions belong in the user's working context; skill wins.

When this skill activates

Use this skill to add one custom badge — the small status widget at the head of a Lovelace view — to an existing frontend module (an integration's www/ folder or a standalone Lovelace module).

When NOT to activate

• a custom card (the larger content building block) → ha-lovelace-card-scaffold / ha/lovelace-card-patterns
• a tile card feature → ha/lovelace-card-features
• a dashboard strategy → ha/lovelace-strategies
• the config-changed graphical-editor detail pattern → ha/lovelace-card-editor
• deploying/importing into a running HA instance → out of scope

Hard rules

1. One badge, one run. No multi-badge batches.
2. Read spec/ha/lovelace-badges/en.md first. Do not generate from memory.
3. Custom element, no React. Define the badge as a subclass of HTMLElement (or LitElement) and register it via customElements.define("<badge-type>", <BadgeClass>); the tag name becomes the badge type custom:<badge-type>. Never use React as the rendering framework — custom elements and React are not compatible in HA badges.
4. setConfig contract. Implement setConfig(config); reject an invalid configuration with throw new Error("...") — HA catches it and renders an error badge.
5. hass setter. Implement the hass property as a setter; the badge updates itself to the latest state on every set. Read the consumed entity from hass.states[entityId] and render a sensible fallback (e.g. unavailable) when it is missing (see spec/ha/frontend-data-api/en.md).
6. Picker registration. Push an entry into window.customBadges (window.customBadges = window.customBadges || []; window.customBadges.push({...})) with at least the required type and name; description / documentationURL / preview are optional (preview defaults to false).
7. Graphical editor is optional. Add the static getConfigElement() / getStubConfig() only when an editor is wanted; do not spell out the config-changed event pattern here — that is governed by spec/ha/lovelace-card-editor/en.md.
8. Document the wiring. Reference the badge via type: "custom:<badge-type>" in a view's badges: list and add a module resource with the badge module URL (typically /local/<badge-name>.js); note the HA restart needed after first creating the www folder.
9. Name per spec/ha/naming-conventions/en.md and verify HA internals against the official docs (see spec/ha/upstream-docs-verification/en.md).
10. Honour the layout-antipattern catalogue (spec/ha/lovelace-layout-antipatterns/en.md). Badges do not render in panel or sidebar views (A2) — when documenting the wiring, note the target view must support badges (Sections, Masonry), not panel/sidebar.