luma-home/design-system/README.md

Luma Home design system

The design for the Home Assistant tab of Luma: a 10-foot UI driven only by the remote's arrows, OK and Back, viewed from 5–6 m on a 65" TV.

Exported 2026-10-27 from the "Luma — 10-foot redesign" design canvas and the "Luma Home" design system on claude.ai. Those stay the place to change the design; re-export this folder after changes.

Read in this order

File	What it is	When to use it
ux-mechanics.md	The behaviour contract. Global rules (tap vs hold, focus, grid, panels, errors) and every card's keys, panel, states, hint bar and HA calls.	Before writing any input or state logic. Numbers here are the spec.
components.md	Layout and look of the shell, each card type and each panel.	When drawing a card or panel.
tokens.json	Colours, type sizes, spacing, radii, timings — at logical 1920 × 1080.	Source of every constant. Don't hard-code values that exist here.
tokens.css	The same tokens as CSS variables.	Lovelace cards in cards/ and web previews.
screens/	PNG renders of every design board.	Visual reference; compare desktop screenshots against these.
icons/	58 single-colour SVG icons + name map and attribution.	Compile to .lvec like other vector assets.
assets/roborock-s7.png	Transparent vacuum photo for the vacuum card.	Vacuum card middle band.

Room photos come from Home Assistant, not from this folder or the app. The room card shows the picture set on each Home Assistant area, loaded over the existing HA connection (rules: ux-mechanics.md §B11, Room photos). The blurred room photos in screens/ are mock-up placeholders: never add them, or any room photo, to the repository or the IPK.

Screens

Render	Shows
Main.png / Main3.png	A room (Living Area) on the 4-column and 3-column grid, hint bar for the focused card
Home.png	Home overview: weather 1×2, media 1×2, vacuum, pinned devices, a row of room cards
CardSizes.png	Allowed card sizes on the grid
Interactions.png	Tap vs hold, media keys, every card at a glance
LightOnOffStates.png	On/off light — states (no panel)
LightStates.png	Dimmable light — states + panel
LightColorStates.png	Colour light — states + panel
LedStates.png	LED strip / TV lights — states, colour panel, white panel, All effects
ClimateStates.png	Air conditioner — states + panel
HeatingStates.png	Heating — radiator valve and wall thermostat: states + both panels
CurtainStates.png	Curtain — states + panel
SwitchStates.png	Switch / plug / lock — states (no panel)
WeatherStates.png	Weather 1×1 and 1×2 + panel
MediaStates.png	Media 1×1 / 1×2, seeking and volume states + panel
MediaSpec.png	Media interaction spec (same content as ux-mechanics §B9)
RoomStates.png	Room card (Home overview) — photo, dark, warning, no-photo states + quick panel
VacuumStates.png	Vacuum — docked, dock needs attention, cleaning + panel

Sample names, rooms and track titles in the renders are placeholders; real data comes from Home Assistant.

Implementation notes for this repo

• The native app is Rust/SDL2/OpenGL ES (see agents.md); there is no browser UI. Treat CSS-like values in tokens.json (gradients, shadows) as descriptions to reproduce in the renderer.
• Keep the logical 1920 × 1080 layout; textScale (1.0–1.6) multiplies type sizes only.
• Tap vs hold must be timed from SDL key-down to key-up, acting on release for taps (ux-mechanics.md §A1). The existing hold action in src/state.rs is the place to wire it.
• Verify behaviour on the TV; desktop smoke tests don't prove remote timing.
• Where the current code differs from this design (e.g. the media card's transport buttons or icon set), the design wins unless a change is agreed.
• Icons require the visible credit "Uicons by Flaticon" (Settings → About).