principled dashboard design system

HA_Bubble_Skill v1.2

Release date: 2026-06-05
Skill covers: Bubble Card 3.2.1 · Streamline Card 0.2.2 · Sidebar Card 0.1.9.9 · Mushroom Cards · Casa5HeyneV2 theme
Size: 17 files · 12,592 lines · 125 KB

---

What's new in v1.2

This release adds three substantial capabilities: a principled dashboard design
system, a complete multi-view architecture with copy-paste YAML, and a
health-check mode for auditing existing dashboards.

---

1. UX philosophy — §2 rewritten from scratch

The previous §2 used a 3-tier importance hierarchy (Glanceable → Actionable →
Detailed). This release replaces it with an engagement-type model that asks
a different question: not "how important is this device?" but "what type of
engagement does this actually need?" — and before that, whether it needs any
UI at all.

The engagement-type model:

Type	Interaction cost	HA equivalent	Rule
No UI at all	Zero — automated	Automation / script	Everything a human doesn't need to decide
Complications	Zero — passive	Chip bar, Overview	State that informs without action
Brief interaction	One tap	Room button → pop-up	Things adjusted manually, regularly
Deep engagement	Multi-step	Secondary view	History, config, rarely-changed settings

The key addition: Tier 0. The first question for every card is now "should
this be automated instead?" Motion sensors, time-based covers, and presence
triggers belong in automations — not on the dashboard. The dashboard is for what
automation genuinely cannot handle.

New in §2:

• Automate first — the new opening principle with optional opening question
  and explicit skip conditions
• Full-dashboard design workflow — six-step design-first process: collect
  entities → classify into Buckets 0–3 → present classification to user →
  apply device-type profile → generate from 5-view system → offer follow-up.
  Classification is always shown before any YAML is generated. Claude never
  refuses a user's classification decision.
• Device-type profiles — one lookup table (phone / wall tablet / desktop /
  e-ink / both) provides max_columns, card_layout, font size, nav pattern, and
  theme mode. Replaces six separate questions.

---

2. 5-view dashboard system (references/dashboard-system.md — new file)

A complete information architecture for new dashboards. Each view has exactly
one purpose and one engagement type.

Core 5 views:

View	Purpose	Engagement type
Overview	What is happening right now	Complications — passive
Rooms	What I want to control	Brief interaction
Scenes	How I want the home to feel	Brief interaction
Activity	What has happened	Passive review
Settings	How the home is configured	Deep engagement

Two optional extension views:

• +Energy — consumption, solar production, cost monitoring
• +Music — multi-room audio control across zones

The Activity view uses a unique hide/show graph mechanism. Eight event
categories in two groups — Home Activity (Presence, Doors & Windows, Motion,
Automation) and Home Health (Energy, Maintenance, Devices, Infrastructure).
Each category shows a curated event card. Tapping reveals a pattern graph
inline — no pop-ups, no navigation changes, no extra clutter. Eight
input_boolean helpers toggle visibility per category.

dashboard-system.md contains:

• Navigation layer — Sidebar Card (desktop) + HBS footer (mobile) config
• Full YAML scaffolds for all 7 views with placeholder entity IDs
• ha-yaml handoff blocks for required helpers and template sensors
• Classification → view mapping table

---

3. Recipes 7–14 (references/recipes-extended.md)

Eight new copy-paste YAML recipes covering the complete 5-view system:

Recipe	Content
R7	5-view dashboard outer scaffold
R8	Overview view — chip bar, alert strip, room status, away panel
R9	Rooms view — room grid, pop-ups, quick actions bar
R10	Scenes view — grouped scene buttons, active scene chip, guest mode
R11	Activity view — all 8 category pairs with hide/show mechanism
R12	Settings view — overrides, maintenance, thresholds, quick links
R13	Energy extension view
R14	Music extension view

---

4. Health-Check Mode (§9 — new section in SKILL.md)

Paste existing dashboard YAML and get a prioritised findings list with specific
fixes. Starts immediately — no upfront questions. Works with partial YAML and
notes coverage gaps at the end.

Parse approach — five structured steps:

1. Structured parse template — forces full structural reading before any
   conclusions. Inventories view type, top-level cards, all pop-up hashes, all
   navigation targets, cross-references, colour values, entity types, card counts.

2. Structural YAML patterns — side-by-side correct/incorrect examples for
   pop-up placement, HBS positioning, theme placement, colour values, and
   navigation cross-references.

3. Colour scan with exclusions — scans only colour-relevant properties.
   Explicitly excludes: YAML comments, entity IDs, icon values, pop-up hashes,
   navigation paths, Mushroom named colour tokens (icon_color: "amber" is
   correct — not flagged).

4. Entity scan rules — only flags interactive cards (switch, slider, toggle).
   Read-only state displays are never flagged. input_boolean, input_select,
   input_number always excluded — they are designed for manual control.

5. Engagement-type mixing detection — classifies cards per view and flags
   mixed engagement types with specific suggestions for which view each card
   type belongs in.

Three severity tiers:

🔴 Critical — fix before using (Iron Law violations, broken structure):
hardcoded colours, pop-up inside sections, masonry view type, missing pop-up
hash, deprecated open_popup: true, broken navigation cross-references.

🟡 Significant — fix soon (materially degraded UX): HBS not last card,
background_update: true on non-realtime entity, mixed engagement types,
theme: on individual cards, with_bottom_offset missing with HBS.

🟢 Advisory — improvement opportunities (never prescriptive): automate-first
candidates, missing chip bar, rise_animation: true on fixed display, missing
column_span, 5-view alignment opportunity.

Automate-first findings use a neutral tone — name the entity, note what it
typically indicates, suggest the automation alternative, acknowledge the user
may have a reason for keeping it.

5-view alignment is always Advisory — framed as an option with a concrete
mapping of existing content to the 5-view structure, never as a requirement.

---

Files changed

File	Change
SKILL.md	§2 full rewrite · §9 Health-Check Mode added · Process flowchart updated · Pitfall row added
references/dashboard-system.md	New file — 1,803 lines
references/recipes-extended.md	Recipes 7–14 appended (+927 lines)
CHANGELOG.md	v1.2 entry
README.md	5-view system section · version bump

---

Upgrading from v1.1

No breaking changes to existing recipes or reference files. All v1.1 card
patterns, CSS architecture, colour intelligence, and troubleshooting content
is unchanged.

New capabilities are additive:

• Existing single-view dashboards continue to work exactly as before
• The 5-view system is the new recommended starting point for full dashboards
• The health-check mode works on any existing YAML regardless of structure
• §2 changes affect new generation behaviour — Claude now classifies before
  generating, but produces the same card YAML patterns as before

---

Known limitations

• Activity view template sensors require ha-yaml skill handoff — the recipes
  include placeholder entity IDs and a ha-yaml context block, but the sensors
  themselves are not auto-generated
• Health-check cross-reference validation (navigation_path → pop-up hash
  matching) works within the pasted YAML only — cannot validate links to
  views or pop-ups not included in the paste
• The health-check artifact (AI-powered interactive YAML parser with
  structural validation) is planned for a future release