docs(best-practices): fix stale dashboard guidance, add sizing/responsive mechanics

[jasonjhofmann]

What this PR fixes

dashboard-guide.md predates several frontend changes and contained guidance that produces broken or deprecated config. Everything below was verified against the HA 2026.5 frontend source (src/data/lovelace/config/*.ts), official docs, and release notes; two items were additionally caught by rendering real dashboards and are marked render-verified.

Corrections

Was	Now	Evidence
Section examples use {"title": ..., "cards": [...]}	Heading card as first card	section.ts marks title @deprecated Use heading card instead
Action list includes call-service	perform-action (+ missing assist)	renamed in 2024.8; actions docs
"background": {"image": "url(/local/bg.jpg)", "opacity": 0.3}	plain path + integer 0–100	view.ts background schema; url() belongs to the legacy string form only
Features table missing 2025.9–2026.5 features; lists datetime-picker	Current feature inventory; date-set	features docs — datetime-picker does not appear there
:root { --primary-color: ... } CSS as "theme overrides"	HA theme YAML with modes: {light, dark}	themes docs
layout-card listed without context	noted as superseded by sections for new builds	sections views provide native sizing/spanning since 2024.9–2024.11
2026.4 row says sections support background_color	key is background: {color, opacity} (or true)	LovelaceSectionBackgroundConfig in section.ts

Additions (official behavior only, per CONTRIBUTING's "no opinionated conventions")

• Card Sizing and Responsive Layout section: the 12-column section grid, grid_options (and deprecated layout_options), how section columns reflow with viewport width, standard breakpoints for screen visibility conditions, badges_wrap.
• column_span: N sections have N×12 grid columns on wide screens but 12 when collapsed (render-verified: three 6-column tiles fit one row in a column_span: 2 section on desktop, two-up on phones) — with guidance for values that degrade well.
• Pitfalls: map label_mode is a per-entity option (render-verified: card-level silently no-ops and markers show name initials), map cards only plot entities with latitude/longitude attributes, spanned-section sizing.
• Visibility condition inventory (state, numeric_state, screen, user, time, location, and/or/not) and a perform-action example with confirmation.
• Visual-iteration caveats: test per breakpoint class; history-backed cards hydrate asynchronously, so screenshots can capture half-drawn charts on slow recorders.

Validation

• uvx --from skills-ref agentskills validate skills/home-assistant-best-practices → Valid skill
• All JSON example blocks parse (placeholders excepted)
• No tool names, no user-specific conventions introduced
• Both render-verified behaviors reproduce in any sections dashboard in minutes: (1) put three "columns": 6 tiles in a column_span: 2 section — they fit one row on desktop, two-up on phones; (2) set label_mode: state at map-card level vs. per-entity and compare markers.

Scope note

Corrections and additions land as one commit because they touch the same sections of the same file; happy to split into a corrections-only PR plus a follow-up if you prefer smaller reviews.

[gemini-code-assist]

Code Review

This pull request comprehensively updates the Home Assistant Lovelace dashboard guide to reflect modern best practices up to version 2026.5. Key updates include detailing the sections view layout with its 12-column grid and responsive behavior, replacing deprecated section titles with heading cards, updating the available card features and action types (such as perform-action), and transitioning from raw CSS overrides to YAML-based themes. It also expands on visibility conditions, HACS card recommendations, troubleshooting steps, and adds testing caveats for screenshots. There are no review comments, so I have no feedback to provide.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[jasonjhofmann]

Heads up: this overlaps #59/#60 in dashboard-guide.md (which predate this PR). Duplicated if those merge first: the perform-action action-list fix, parts of the features-table update (date-set, favorites), and the grid_options/12-column basics — I'll drop those hunks and rebase the remainder (example fixes, background/theme corrections, responsive mechanics, verified pitfalls) promptly once they land. Merge order is your call; happy to go second.