ha-lovelace-card-scaffold

HA Lovelace Card Scaffold

Spec: https://github.com/nolte/claude-home-assistant/blob/develop/spec/claude/ha-lovelace-card-scaffold/de.md (DE canonical) / en.md.

When this skill activates

Use this skill when the user wants to add a custom Lovelace card to an existing HA Custom Integration — a vanilla-JS card living under custom_components/<domain>/www/, auto-registered through __init__.py.

When NOT to activate

• greenfield integration setup → ha-integration-scaffold
• TypeScript or Lit cards → separate spec planned
• card removal → manual code edit
• multi-card scaffold in one call → call once per card

Hard rules

1. Never set hard-coded hex colours. Use HA CSS custom properties (var(--primary-text-color) etc.) so the card respects the active theme.
2. Always set cache_headers=False in the StaticPathConfig. Otherwise updated cards stay stale for cached browsers.
3. Always include getCardSize, getGridOptions, setConfig, and getStubConfig. Sections-layout and the card picker depend on them.
4. Always perform entity-change detection in set hass. Re-rendering on every HA state tick burns CPU for nothing.
5. Never reference external CDN assets. Cards run offline-capable.
6. Never ask the user to add Lovelace resources by hand. Auto-registration is the contract.

Inputs

Field	Required	Default	Notes
target_dir	yes	—	repo root
card_type	yes	—	lowercase kebab-case, prefixed with <domain>
display_name	yes	—	card-picker name
description	yes	—	description in the picker
entity_types	yes	—	list of platforms the card consumes
preview	no	false	preview in picker
grid_options	no	{columns: 6, rows: 3, min_columns: 3, min_rows: 2}	sections-layout defaults

Pre-flight

1. git -C <target_dir> rev-parse --is-inside-work-tree and clean working tree
2. Read domain from manifest.json
3. <target_dir>/custom_components/<domain>/www/<card-name>.js does not exist
4. No existing StaticPathConfig entry for this card name in __init__.py

Workflow

1) Resolve and confirm

Print the card name, type, picker label, grid options. Wait for user confirmation.

2) Generate

• custom_components/<domain>/www/<card-name>.js — the full skeleton (class, lifecycle methods, shadow DOM, render method with CSS custom properties, customElements.define, window.customCards push)
• __init__.py — append StaticPathConfig block (or extend the existing block list) with cache_headers=False
• tests/test_lovelace_cleanup.py (when present) — append assertion for the new card

3) Verify

ruff check custom_components/<domain>/__init__.py
pytest tests/ -v

4) Report

• file path of the new card
• auto-registration URL the card will be served from
• next-step hint to fill in the actual _render body

Boundaries

• TypeScript / Lit cards → planned follow-up spec
• Card editor element → consumer task
• HACS plugin distribution → out of scope