structural optimisation - 57% fewer tokens on every request

ha-bubble-dashboard — v1.3 Release Notes

2026-06-05

---

What this release is

A structural optimisation release. No new features, no behaviour changes — same content, significantly leaner token footprint.

The skill now loads 57% fewer tokens on every request by reorganising content from always-in-context to on-demand reference loading. SKILL.md went from 2162 to 937 lines. Everything that was removed from it is still there — it just lives in a reference file that Claude reads when that specific task arises.

---

Why it matters

Skills loaded into a Claude Project are always in context. Every token in SKILL.md costs context window on every single message — including messages that have nothing to do with full dashboard generation, health checks, or typography. v1.3 moves the heavy content to reference files so that a simple "add a cover card" request doesn't carry the weight of a 400-line health-check mode it will never use.

---

What changed

Two new reference files

health-check-ref.md
The full health-check mode (§9) extracted into its own file. Contains the structured parse template (5 steps), all structural pattern examples with correct/wrong YAML, colour scan rules, entity scan rules, engagement-type mixing detection, finding categories with severity tables, output format, tone guides for automate-first findings, and partial YAML handling. SKILL.md §9 is now a 3-line pointer.

recipes-5view.md
Recipes 7–14 extracted from recipes-extended.md into a dedicated 5-view recipes file. Contains the outer scaffold (R7) and per-view card YAML for all five standard views (R8–R12) plus the Energy and Music extension views (R13–R14). Only loaded when generating a full 5-view dashboard.

recipes-extended.md restructured

Now contains: room-specific pop-up patterns (security, vacuum, presence, bathroom, garage, office, Streamline templates) + core Recipes 1–6 (room pop-up, HBS, media player, climate, chip bar, Streamline). The 5-view recipes (R7–R14) have moved to recipes-5view.md.

Content gaps filled (found during cross-check)

Two pieces of content were referenced in SKILL.md stubs but missing from the target reference files:

• Font-only update variable list — the complete set of ha-font-family-*, paper-font-*, and primary-font-family variables needed for a font-only theme diff. Added to typography-ref.md#font-only-update.
• Streamline two-block delivery format — the labelled Block 1 (template) / Block 2 (usage) structure with examples. Added to streamline-ref.md#delivery-format.

SKILL.md internal cleanup

• §2 UX Principles: lookup tables and reference diagrams moved to dashboard-system.md; behavioural principles (automate-first, engagement-type model) kept in-context
• §3b, §5, §6 compressed to route-only stubs — detail already existed in typography-ref.md, sidebar-ref.md, streamline-ref.md
• §8 pitfalls: 4 entries removed (direct repeats of Iron Law); cross-skill handoffs condensed to a table; performance notes moved to bubble-card-ref.md
• Stale text corrected throughout

Minor fixes

• Recipe 1–6 anchor format standardised from inline {#anchor} to ## #anchor — consistent with all other anchors in the skill
• README file tree updated to reflect actual file structure
• Version metadata bumped to 1.3

---

Upgrading

If you use Option B (files uploaded to a Claude Project):
Replace all uploaded files with the v1.3 versions. The two new files (health-check-ref.md, recipes-5view.md) need to be added as new uploads. Remove the old recipes-extended.md and upload the new one.

If you use Option A (on-disk with system prompt):
Replace the ha-bubble-dashboard/ folder contents. The available-skills-entry.md is unchanged — no system prompt update needed.

---

File count

20 files → 22 files (added health-check-ref.md, recipes-5view.md)

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

v1.1 — Community findings, source code analysis, Mushroom expansion

v1.1 — Community findings, source code analysis, Mushroom expansion

---

What's new

Bubble Card — source code analysis

A full read of the Bubble Card 3.2.2 source revealed several undocumented or
incorrectly documented options. All of these are now in bubble-card-ref.md.

Pop-up card — newly documented options:

Option	What it does
popup_style	classic gives a traditional dialog header instead of the default bottom-sheet style
popup_mode: adaptive-dialog	Fourth popup_mode — centered on desktop, bottom sheet on mobile
show_header	Hide the entire pop-up header including close/back buttons
show_close_button	Hide the X button while keeping the header
show_previous_button	Show a back (←) button in the header
buttons_position	right / left — position of header action buttons
main_buttons_position	Position pop-up header sub-buttons: default (inline) or bottom (as a row below header)
main_buttons_alignment	Alignment of bottom-positioned header sub-buttons
close_on_click	Close the pop-up after any tap inside it
auto_close	Auto-close after N milliseconds
slide_to_close_distance	Swipe distance to close (default 400px)
bg_opacity	Default is 88 (not 100) — pop-ups are semi-transparent by default
width_desktop	Default is 540px (corrected from 560px)
backdrop_blur	Blur the backdrop behind the pop-up (separate from bg_blur)
performance_mode	performance delays rendering and disables blur for slow devices
close_action	Action triggered when the pop-up closes
trigger + trigger_close	Conditions array for auto-opening; confirmed trigger_entity/trigger_state are deprecated
empty-column card type	Blank placeholder card for grid alignment

Sub-buttons — footer_mode: The sub-buttons card can be pinned as a fixed footer
bar with footer_mode: true, footer_full_width, footer_width, and footer_bottom_offset.

HBS — undocumented options: rise_animation, hide_gradient, margin, width_desktop
now documented. rise_animation: false recommended for wall panels (plays on every load).

---

Bubble Card — community forum (pages 149–153)

• Two-tap pop-up navigation — navigating from one open pop-up to another now
  closes the first pop-up in v3.2.x. Added as a pitfall row and troubleshooting entry.
• ha-view-sections-row-gap — HA 2026.4 increased default section row spacing.
  Added to css-theme-ref.md with override pattern, and to troubleshooting.
• rows: key — decimal multiplier for card height (e.g. rows: 1.4).
  Documented in button options table.
• Sub-button font CSS selectors — .bubble-sub-button and
  .bubble-sub-button-bottom-container .bubble-sub-button for per-row font size control.
• card-mod overflow: hidden clipping — new #cardmod-overflow-clipping
  troubleshooting section with CSS workaround and Bubble Card module alternative.
• Patreon modules — Bubble Badges v2, Bubble Weather, Bubble Calendar Enhanced,
  Bubble Neon, Custom Dropdown documented with Patreon link and guidance on how to
  handle them in prompts.
• HA 2026.4 / 2026.5 compatibility — both breaking changes documented in
  version-compat with affected versions and fixes.
• background_update — v3.2.1 does intelligent lazy updates by default;
  manual background_update: true no longer recommended.
• Sub-buttons on pop-ups — v3.2.1 automatically shows header when sub-buttons
  are configured on a pop-up card.
• Version pin corrected to 3.2.1 (stable release).

---

Streamline Card — source code analysis

Three findings from evaluateJavascript-helper.js, evaluateVariables-helper.js,
and templateLoader.js:

areas context variable — The JS evaluation context exposes four variables:
states, user, variables, and areas. The areas object (HA area registry,
keyed by area ID) was undocumented. Now documented with two worked examples:
displaying an entity's area name via CSS, and dynamically generating cards for
all lights in a named area.

!include tag — Streamline's own !include tag loads external YAML files
relative to the current file's URL. Unlike HA's !include_dir_named, this works
in both UI-mode and YAML-mode and supports nested includes. Documented with a
comparison table and folder structure example.

Background revalidation — After the initial load, Streamline fetches templates
in the background with a cache-busting URL and updates cards automatically when the
content changes. Hard refresh is usually not required after template edits. The
previously overstated "always hard refresh + restart HA" instruction has been
corrected across streamline-ref.md, troubleshooting-ref.md, and SKILL.md.

---

Mushroom Cards — expanded documentation

New #mushroom-cards-overview section in mushroom-theme-ref.md:

• Bubble vs Mushroom decision guide — when to use each for the same entity
• Mushroom entity card — icon_color options, state-based colour, fill_container
• Mushroom light card — full RGB/CCT colour picker, when to use vs Bubble Card sliders
• Mushroom person card — photo support, layout options
• Mushroom climate card — compact HVAC mode selector, when to use vs Bubble Card climate

---

SKILL.md — description trimmed

The description: field is now 727 characters (was 3,580), within the
1,024-character limit for Claude Project uploads.

---

Files changed

File	Changes
references/bubble-card-ref.md	Pop-up options table extended (+18 options), sub-button font selectors, footer_mode, HBS options, Patreon modules, HA 2026.4/5 compat, rows: key, cardmod-overflow-clipping
references/streamline-ref.md	!include tag section, areas context variable with examples, background revalidation corrected
references/troubleshooting-ref.md	#cardmod-overflow-clipping section, Streamline cache advice corrected, ha-view-sections-row-gap row
references/mushroom-theme-ref.md	#mushroom-cards-overview section (entity, light, person, climate cards)
references/css-theme-ref.md	ha-view-sections-row-gap structural variable
SKILL.md	Description trimmed to 727 chars, pitfall rows for two-tap nav + font loader, Streamline cache pitch softened

Component versions

Component	Version
Bubble Card	3.2.1 (stable)
Bubble Card Tools	1.0.2
Streamline Card	0.2.2
Sidebar Card	0.1.9.9
HA minimum	2024.3.0

Claude skill library for building Home Assistant dashboards with Bubble Card, Streamline Card, Sidebar Card, and Mushroom Cards

v1.0 — Initial public release

This is the first public release of HA_Bubble_Skill — a Claude skill library for building Home Assistant dashboards with Bubble Card, Streamline Card, Sidebar Card, and Mushroom Cards.

---

What's included

16 files across three folders:

• SKILL.md — the main skill file with iron laws, process flow, UX principles, installation guide, eight content sections, pre-output checklist, and cross-skill handoffs
• references/ — 11 reference files covering every card type, the full CSS theme variable catalogue, colour intelligence with palette recipes, Mushroom ↔ HA integration, typography, troubleshooting, and extended room recipes
• theme/Casa5HeyneV2.yaml — the base HA theme with full Bubble Card and Mushroom state-colour integration, six palette zones, light and dark mode

---

Key capabilities

• Bubble Card 3.2.x — all card types documented with version compatibility flags; v3.2 standalone pop-up format enforced
• Merged CSS theme — --bubble-* variables chain to HA variables; Mushroom entity-domain state colours wired via ZONE 6 bridge; single accent change repaints the entire UI
• Colour intelligence — 6 accent swap recipes, 6 full palette recipes, WCAG contrast pre-flight, advisory and prescriptive modes, bring-your-own-hex template
• Typography — three font loading methods (CDN, self-hosted variable font, system stack), wall-panel size overrides, four ready-made font swap recipes
• Single-mode themes — wall-panel and kiosk support; light-only or dark-only theme generation with HA mode-selection explanation
• Mushroom chip cards — full chip type documentation including template chip with Jinja2 icon/colour/content patterns
• Troubleshooting — 14 symptom sections with cause/fix tables covering every common failure mode
• Test dashboard — importable Lovelace YAML assembling core recipes; works in both UI-mode and YAML-mode Lovelace

---

Two usage modes

On disk (Claude computer-use, Claude Code, custom system prompt): place the skill folder at /mnt/skills/user/HA_Bubble_Skill/ and paste available-skills-entry.md into your <available_skills> system prompt block. Claude loads the skill automatically when it detects relevant requests.

Uploaded to Claude (claude.ai Projects): upload all .md files and references/casa5heynev2-template.yaml as project knowledge. Skip available-skills-entry.md — it is not needed when files are uploaded directly.

---

Component versions pinned

Component	Version
Bubble Card	3.2.2
Bubble Card Tools	1.0.2
Streamline Card	0.2.2
Sidebar Card	0.1.9.9
HA minimum	2024.3.0