# 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).