CorrectByDesign
A standard for agent-ready design systems Text and diagrams CC BY 4.0
← The Index
System 8 of 10
Open Home Foundation / Home Assistant (community, non-profit; HQ jurisdiction unverified) · Lit web components, inside the product
Pinned 2026-09-09

Home Assistant frontend.

Home Assistant frontend has no separate design system to adopt: its 401 ha-* components are the product itself, not a library other code imports. The tokens behind them hold together reasonably well, but documentation has not kept pace with the component count, so an agent extending the frontend has little written guidance beyond the source and has to read code to learn a component's contract. Measured at src/components.

1Scores

What the instrument measured.

7Single source · strong684 distinct token(s) across 10 sources; 59% of colour/size references in system source resolve to a token; dark-mode handling is unobservable.
3Legibility · partial103 of the 401 components found in system source carry documentation in some form (a head comment, a colocated doc artifact, or a docs/ entry). Scored from what is in the repository. Documentation held outside it (e.g. Confluence, Notion, Figma) cannot be detected and is neither credited nor penalised.
not measuredAdherencefound 2431 application source files (2407 readable), but none import the design system, use one of its components, or carry a style declaration this instrument can read. Adherence is not scored rather than scored as clean: there is nothing here to adhere to or drift from.
5Mean of 2of measured
—Constraintnot computed by this instrument: scoring it requires parsing component APIs per framework, which is done in the deep audit of a single system rather than across a field
—Fidelitynot computed by this instrument: scoring it requires parsing component APIs per framework, which is done in the deep audit of a single system rather than across a field
—Completenessrequires a live agent run: a gap only exists relative to something someone tried to build
TrialNot trialled
2What the instrument read

Measured against a pinned commit.

Repository
home-assistant/frontend
Revision
94fdea6f00f5, committed 2026-09-08
System directory
src/components
Components found
401, of which 103 carry documentation and 0 have a colocated doc artifact
Agent context
2 context files, 12 skills
Tokens
684 distinct, across 10 sources (10 authored); dark mode unobservable
Adherence surface
2,431 files outside the system, graded first-party: the frontend is the product, so the components and their consumers share one tree.
3Findings

What the counts point at.

Each finding carries its count, its severity and up to three file references. A finding on a property that was not banded is still a finding; it is reported without a score.

Single source7
1,250 hardcoded colour and size values in component sourcemajor

The design system's own component source hardcodes colour and size values instead of referencing its own tokens. This happens in 1250 of 3023 total colour/size references in system source (41.3%), so an agent copying that file as a pattern copies the hardcoding along with it.

  • src/components/media-player/ha-media-player-browse.ts:656 175px
  • src/components/data-table/ha-data-table.ts:1129 rgba(
  • src/components/chart/ha-chart-base.ts:467 450px
10 separate places tokens are declaredmajor

Design tokens are declared in more than one place in this repository's own authored source, so a value changed in one must be kept in agreement with the others by hand.

  • src/resources/theme/color/color.globals.ts css-in-js, 317 token(s)
  • src/resources/theme/color/semantic.globals.ts css-in-js, 103 token(s)
  • src/resources/theme/color/wa.globals.ts css-in-js, 59 token(s)
Legibility3
298 undocumented componentsmajor

Some components carry no documentation an agent could find. That is 298 of the 401 components found in system source, with no head comment on their own source, no colocated doc artifact matching their name, and no docs/ entry, so an agent must reverse-engineer their contract from implementation alone.

  • src/components/chart/axis-label.ts
  • src/components/chart/chart-sonification.ts
  • src/components/ha-form/compute-initial-ha-form-data.ts

Adherence (reported, not banded)

723 hardcoded colour valuesmajor

The application hardcodes colour values instead of using the design system's own tokens, so an agent editing nearby code has no signal that a token exists and will likely repeat the pattern.

  • src/resources/theme/color/color.globals.ts:5 #ffffff
  • src/panels/config/config-sections.ts:60 #0D47A1
  • src/resources/theme/color/core.globals.ts:11 #000000
7 components that duplicate one the system already shipscritical

The application defines its own component under the same name as one the design system already ships. This happens for 7 of the 332 component names the design system exports, so an agent importing that name by convention can silently get the wrong implementation.

  • src/common/color/convert-light-color.ts DEFAULT
  • src/common/map/base-layer.ts MAP
  • src/data/automation.ts CONDITION
4The trial

Not trialled.

The trial requires a system that can be installed from its own documentation into a clean scaffold. This one cannot be, because there is no published package. The components are the product's own tree, so there is nothing to install into a scaffold that is not the product itself. It keeps its row in the static index with that reason stated, per the standing rule.

5Reproduce it

Clone the repository at the revision above, point the instrument at the system directory, and the same numbers come out. The field manifest, the run script and the full payload this page was built from are committed beside it. Methods.