Ha Frontend Gallery

HA Frontend Gallery

Use this skill for all work under gallery/. Follow the persistent repository guidance in AGENTS.md and load the matching specialist skills alongside this gallery-specific guidance.

Quick Reference

Run commands from the repository root unless noted otherwise:

gallery/script/develop_gallery  # Start the gallery development server
gallery/script/build_gallery    # Build the static gallery
pnpm lint                       # ESLint, Prettier, TypeScript, and Lit checks
pnpm lint:types                 # TypeScript compiler, without file arguments

Never run pnpm lint:types or tsc with file arguments. File arguments make tsc ignore tsconfig.json and can emit .js files into src/.

Purpose

The gallery is a developer and designer reference for Home Assistant frontend UI patterns. It documents component APIs, shows realistic Lovelace and more-info states, captures brand and copy guidance, and provides reproducible demos that are safe to inspect outside a running Home Assistant instance.

• Prefer demonstrating real production components from src/ instead of creating gallery-only replacements.
• Keep fake state, sample data, and demo-only helpers inside gallery/.
• Do not move gallery stubs or demo data into production code unless a production feature explicitly needs them.
• Do not hand-edit generated output under gallery/build/ or gallery/dist/.

Structure

• gallery/sidebar.js: Defines gallery sections, headers, and explicit page ordering.
• gallery/script/develop_gallery: Wrapper for the develop-gallery gulp task.
• gallery/script/build_gallery: Wrapper for the build-gallery gulp task.
• gallery/src/entrypoint.js: Creates the <ha-gallery> shell.
• gallery/src/ha-gallery.ts: Renders the drawer, page routing, markdown descriptions, demos, edit links, and RTL toggle.
• gallery/src/html/index.html.template: HTML template used by the gallery build.
• gallery/src/pages/<category>/<page>.markdown: Optional page description and frontmatter.
• gallery/src/pages/<category>/<page>.ts: Optional live demo module for the same page ID.
• gallery/src/components/: Gallery-only demo wrappers like demo-card, demo-cards, demo-more-info, and page-description.
• gallery/src/data/: Fake hass, demo states, mock traces, and reusable sample data.
• gallery/public/: Static assets copied into the gallery output.

Page Model

Gallery pages are generated by gather-gallery-pages in build-scripts/gulp/gallery.js.

• A page ID is the path under gallery/src/pages/ without the extension, like components/ha-button.
• A .markdown file and a .ts file with the same page ID become one gallery page.
• A page may have only markdown, only a TypeScript demo, or both.
• Markdown can contain YAML frontmatter with title and optional subtitle.
• Markdown that contains only frontmatter contributes metadata without rendering a description block.
• TypeScript demo modules are dynamically imported for side effects when the page is opened.
• A demo module must define a custom element named demo-${category}-${page} with slashes replaced by hyphens, like demo-components-ha-button for components/ha-button.
• gallery/src/ha-gallery.ts renders that element with dynamicElement() based on the current page ID.

Sidebar

Use gallery/sidebar.js when a page needs a visible section, section header, or deterministic ordering.

• category must match the first directory name under gallery/src/pages/.
• header is the section label shown in the drawer.
• pages is optional. When present, listed pages keep that exact order.
• Pages in a category that are not listed are appended alphabetically after the listed pages.
• New categories without a sidebar entry are appended by the generator with their category name as the header.
• If a listed page does not exist, the generator logs an error during gather-gallery-pages.

Subsections

A section can group its pages under named subsections instead of one flat list. Use this for large categories where related pages should sit together.

• subsections is an array of { header, pages }. It is mutually exclusive with a flat pages array on the same group.
• Each subsection header is a non-collapsible label rendered inside the section's expansion panel; the section stays the only collapsible level.
• Listed pages keep their per-subsection order.
• Any pages found in the category but not listed in a subsection are collected into a generated Other subsection, appended alphabetically. The Other subsection is omitted when there are no leftovers.
• A listed page that does not exist still logs an error during gather-gallery-pages.
• Use sentence case for subsection headers and follow the content standards below.