✨🧑‍💻 - Build shared Home Assistant components with React Vue Angular and Svelte adapters #7

Is there an existing issue or feature request for this?

• I have searched the existing issues and feature requests.

What area does this improvement affect?

User Interface

What actions does this improvement affect?

Pull Request, Commit

Description of the idea or improvement

Establish the shared visual component library for Home Assistant applications. The owner requires a common maintained implementation used by Gateway and Domus, with React, Vue, Angular and Svelte adapters and direct Lit/HTML/JavaScript consumption. Domus owns its household experience; Gateway retains its own experience. The shared upper dashboard-style tab bar is the one common navigation pattern.

This repository owns the authoritative component/adapter contract, implementation, tokens, packaging, tests and Storybook. Domus adoption is tracked in vypdev/domus#30 and must reference this contract rather than maintain a second definition of its public component API. Start with the native SDD and an actual cross-framework foundation before broad component extraction.

R1. Deliver one framework-neutral public component API using DOM properties, attributes, slots, typed CustomEvents and CSS theme tokens/parts. Implement the common components with Lit. Keep application routes, authentication, HA services and business rules outside this package.

R2. Deliver the base package package: @vypdev/ha-ui and real adapters package: @vypdev/ha-ui-react, package: @vypdev/ha-ui-vue, package: @vypdev/ha-ui-angular, package: @vypdev/ha-ui-svelte in one repository. Each adapter depends only on the common package and its own framework. Keep one authoritative implementation of visual behavior and accessibility.

R3. Establish real compiled consumer fixtures for direct Lit/DOM use and each of the four adapters before extracting the broader component set. Test properties, events, slots, lifecycle, disabled/focus behavior, forms integration, themes and registration. Declare a pinned supported version matrix from actual passing builds and browser tests. Document and test import/client-rendering boundaries for Next.js, Nuxt and SvelteKit without claiming unimplemented shadow-DOM SSR/hydration.

R4. Extract the reviewed Gateway presentation families into that common implementation: tokens/type/spacing, dashboard tabs, buttons/icons, fields/selects/checkboxes, cards/rows/grids, dialogs and feedback states. Preserve current Gateway interaction semantics through integration tests and provide an explicit migration path. Preserve the MIT source notice and verify every reused asset's provenance.

R5. Build the component Storybook from the shipped implementation, including framework usage examples, interactive controls and normal/loading/disabled/error/empty/dialog states. Verify light/dark themes, English/Spanish content, narrow/wide layouts, keyboard and reduced-motion behavior. Publish the reviewed static catalog through this repository's GitHub Pages when its gates pass.

R6. Apply clean architecture and tests-first development. Require 100% supported authored executable coverage, including statements, branches, functions and lines for the components and delivered adapters. Independently inventory source files. The CI Check workflow runs all applicable tests for every PR update and blocks incomplete coverage, type, architecture, build, browser or packaging evidence. Keep existing Copilot resources unchanged apart from the expressly allowed project dependency setup action.

R7. Provide versioned ESM packages with declarations, per-component imports and reproducible packed artifacts. Validate installation of the actual packed artifacts in consumer fixtures. Record dependencies, licenses, source revision, integrity and compatibility. Verify npm publisher rights before publication; a proposed coordinate or a successful public lookup does not prove publication authority. Publish the packages as a reviewed compatible version cohort.

R8. Prove adoption of that same package in Gateway and Domus through their owning admitted work. Retire superseded local component implementations only after real consumer/browser checks pass. Keep Domus Ingress and standalone packaging self-contained, preserve existing task and administration recovery, and require zero open/reopened/unknown Bugbot findings before merge. Library publication, application adoption, owner HA dogfooding and human UX review are distinct acceptance evidence.

Approved native SDD delivery route

Engineering clarification after the native size diagnostic (106a5501-7537-4377-843e-4f2617693b8b, two draft attempts, expected response bound 18,000): do not weaken the bound or truncate scope, and do not repeat the complete existing foundation inside another appendix.

Use an approved companion under the same catalog owner:

• action=companion
• capabilityId=shared-ui-foundation
• selected path: specs/shared-ui-framework-delivery.md
• Trusted develop base after the documentation prerequisite: d885bccf2c3152c3151471d3efaabd901429d6bd.

The proposed path is absent and unregistered at this base. Preserve specs/shared-ui-foundation.md verbatim, including UIF-01..UIF-08, all 64 distinct baseline cases, every required adapter and both actual app-adoption gates. The companion must reference that retained baseline without redeclaring or recounting its cases. Keep one normative package capability, not competing visual implementations or a second catalog owner. Use a distinct fully qualified namespace for any genuinely additional refinement cases, with proportional numeric area totals, reciprocal traceability and actual prospective paths. The companion itself must be declared create; existing source documents are reference/update only as appropriate. Follow the installed original native publication checks; this clarification is not branch readiness.

Focus the companion on executable delivery: exact supported toolchain/peer pins, registration/DOM contract and adapter/form/SSR boundaries, tests-first coverage/CI enforcement, packed artifact/source integrity, provenance, staged publication and actual app acceptance. The foundation already owns the full goals, UX, 64-case inventory and architecture; do not restate those pages in the companion.

Read-only official registry metadata checked now gives candidate pins Lit 3.3.3, React 19.3.1, Vue 3.5.44, Angular 22.2.4, Svelte 5.57.3, Vite 8.3.5, Storybook 10.6.5, Vitest 5.1.0 and Playwright 1.64.1. These are candidates, not executed support claims. Angular compiler-cli 22.2.4 specifically requires TypeScript >=6.0 <6.1, so use the available TypeScript 6.0.3 candidate rather than blindly selecting registry-latest 7.0.2. Node 24.20.0 satisfies the inspected engines. Exact locks, compiler/browser execution and justified public peer ranges remain implementation gates. No broad or legacy-version support is inferred.

Avoid a release/adoption dependency cycle: first produce one reviewed immutable packed candidate and exercise it in fixtures and both apps without registry publication. After rights and integrity verification, publish those exact accepted package bytes through the authorized lifecycle, then pin the delivered cohort in actual consumer repositories and complete installed/deployment acceptance. Package publication may be a staged prerequisite; it does not mark the capability implemented before required adapters, Storybook and both app-adoption gates pass. No private temporary file path may become a shipped app dependency. A partial cohort publication is inspected and resumed by exact version/digest, never overwritten or claimed complete.

All source/issues/docs remain English. Copilot source and installed resources remain untouched. This is a routine engineering ownership/format clarification within the owner's existing authorization, with no change to product scope.

Native repository-reference clarification

The last candidate failed the repository-path phase after its bounded repair (reference 1ba54a12-7364-46e3-a5a6-3aaeeea885c6). The rejected candidate/token is not available; do not guess that token or weaken the native validator. Use the companion route above and this actual inventory for fresh drafting.

Package coordinates are package identifiers, not repository files. In the candidate, write them as ordinary text or clearly labeled spans such as package: @vypdev/ha-ui, never as a slash-bearing standalone inline-code path. Apply the same distinction to protocol/MIME/locale/framework notation. Cite real repository files only by their exact paths below. Avoid directory-only citations for absent future directories; reference a declared individual future file instead. Gateway/Domus external research uses descriptive absolute GitHub links, not nonexistent local file references. These are formatting distinctions; all source/path safety and full product scope remain intact.

At the trusted develop base d885bcc, the following is the approved prospective inventory. Include each actually cited future file in section 15, and do not invent additional current files or scripts. Additional necessary new files must be explicitly declared create before being cited. The companion itself is create; the retained primary is reference and stays verbatim. Catalog/index update is required to register the companion, not to claim implementation. Other existing documentation updates are prospective feature work.

Companion refinement inventory for native drafting

The normalized-input run 41766647717 no longer reports the repository-path failure. It stopped during assembly with requirement-mapping, section 17, expected count 0 / observed count 1, after two drafts (reference df083a71-2c73-48ff-a485-95207c51abb2). The rejected candidate is unavailable, so do not infer its missing identifier. Keep the native gate unchanged.

To make the companion delta explicit, use the following three new engineering refinements as its declared section 4 goals and the following six genuinely additional negative/recovery cases in section 14. These refine pinned toolchain and staged delivery behavior; they do not replace or recount the foundation's eight goals and 64 retained cases. The companion references that full baseline verbatim. Do not invent another counted alias, refer to a baseline case as if locally defined, or create a reverse mapping for a requirement absent from this companion's declaration table.

Failure-provider cases use isolated deterministic registry adapters/fixtures and are not claims of actual registry publication. Real package rights, packed real consumers, Storybook, Gateway/Domus adoption and actual release observations remain their separate baseline gates. The six-case budget is a floor for these refinements only. All authored implementation still needs complete supported coverage. Prospective delivery checks may use the explicitly proposed tooling/packaging.mjs, tooling/compatibility.mjs and tests/delivery.test.mjs paths; add them as create in the companion's section 15. No Copilot-owned files are changed. Keep a concise companion and one catalog owner.

Current limitations or challenges

The repository contains only a README and the official web-generated Copilot installation. No component package, adapter or Storybook is implemented or published. The installation is reviewed in #5; #6 propagates its unchanged tree to the already existing develop branch before managed feature implementation. Wait for that baseline and Action-published SDD/branch readiness; do not invent a contributor ref.

Gateway currently exposes Lit TemplateResult helper functions under the external Gateway presentation directory, and presentation styles span application and catalog files. Copying those helpers unchanged would expose Lit in the common interaction API. Establish the custom-element boundary and adapter matrix first, then move shared rendering/behavior once and adapt the consumers.

Expected impact

Gateway, Domus and future applications can reuse the same Home Assistant-style components while choosing their own framework and user experience. A common accessibility/theme fix reaches all adapters. Developers can inspect the exact shipped components in Storybook and verify compatibility with real applications rather than trusting an adapter name or generic interoperability claim.

Alternatives considered

Separate full visual implementations per framework would multiply behavior and accessibility maintenance. Copying Gateway CSS/functions into each consumer would not establish package reuse. Depending on HA private bundles or a running Gateway would couple unrelated applications and deployment lifetimes. The common custom-element implementation with tested adapters keeps those boundaries explicit.

Version of copilot

Installed by official web setup external tool package: @vypdev/copilot@3.10.7. Native workflows use external action: vypdev/copilot@v3; use each run's exact resolved revision as runtime evidence.

Additional context or comments

Owner decisions and framework scope: vypdev/domus#30 (comment) . Source reference: https://github.com/vypdev/homeassistant-gateway ; its local MIT notice is copyright 2026 vypdev. Preserve upstream notices; do not copy HA private runtime components.

Efra Espada is the accountable maintainer for publication rights and provenance. The owner explicitly authorizes repository work, tests, PRs and merges, subject to full coverage and no unresolved Bugbot findings. Package/consumer implementations and their public prose stay English; communication with the owner stays Spanish. Do not modify Copilot source or bypass its managed branch/SDD lifecycle. Runtime metadata publication errors are tracked in vypdev/copilot#882 and do not remove any product acceptance gate.