Skip to content

docs: refresh Tab5 wireframes to match UI implementation #89

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
baba-dev merged 1 commit into from
Sep 19, 2025
Merged

docs: refresh Tab5 wireframes to match UI implementation #89

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
247 changes: 142 additions & 105 deletions docs/wireframes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,156 +1,193 @@
# Tab5 Home Controller — Low-Fi Wireframes (AI Source of Truth)

Target device: **M5Stack Tab5** (landscape 1280×720).
UI framework: **LVGL**.
Target device: **M5Stack Tab5** (landscape 1280×720).
UI framework: **LVGL**.
Primary integration: **Home Assistant (MQTT + Assist)**, **Frigate**.

## Design Tokens (names AI should reuse)
## Design tokens (names AI should reuse)

- Spacing: `space-4=4px`, `space-8=8px`, `space-16=16px`, `space-24=24px`, `space-32=32px`
- Radii: `radius-20=20px` (cards), `radius-12=12px` (chips)
- Elevation: `elev-1` (small), `elev-2` (medium)
- Colors: `surface-1=#0E1216`, `surface-2=#151B22`, `text=#E6EDF3`, `muted=#9AA6B2`, `accent=#22C55E`, `warn=#F59E0B`, `alert=#EF4444`
- Colors: `surface-1=#0E1216`, `surface-2=#151B22`, `text=#E6EDF3`, `muted=#9AA6B2`, `accent=#22C55E`,
`warn=#F59E0B`, `alert=#EF4444`
- Typography: `title-lg`, `title-md`, `body`, `caption`
- Motion: `dur-fast=90ms`, `dur-med=200ms`, `dur-slow=300ms`, `ease-out`
- Touch targets: **min 56×56 px**

> **Rule:** Prefer **RGB565** assets sized for on-screen use; avoid per-frame allocations; cap ambient animations to 30 FPS; interaction animations target 60 FPS.
> **Rule:** Prefer **RGB565** assets sized for on-screen use; avoid per-frame allocations; cap ambient
> animations to 30 FPS; interaction animations target 60 FPS.

---

## Global Structure (Navigation)
- Tabs: **Home**, **Rooms**, **Security**, **Climate** (optional **Media**)
- Left-side **nav rail** (implemented) with icon+label buttons for ESP32P4 demo, Rooms, Frigate Security, Local Climate Station, and TV Controls
- Full-bleed background uses a warm gradient (`linear-gradient(90deg, #fcff9e 0%, #c67700 100%)`) on custom pages
- **Control Center** opens as modal sheet (swipe down from header or tap status icons)
## Global structure (navigation)

- Left-side **nav rail** holds icon+label buttons for **ESP32P4**, **Rooms**, **Frigate Security**,
**Local Climate**, **Media**, and **Settings**.
- Rail is hidden by default; a left-edge drag reveals it, and releasing past one-third of the travel
keeps it open. Nav buttons close the rail after changing screens.
- A translucent scrim covers content while the rail is open; tapping the scrim or swiping the rail
left hides navigation and restores touch to the page.
- Wallpapered backgrounds remain visible beneath the scrim so the reveal feels attached to the
surface layer.

```mermaid
flowchart TD
Root[Tab Rail] --> Home
Root --> Rooms
Root --> Security
Root --> Climate
Root --> Media

Home --> CC[Control Center Sheet]
Security --> CamLive[Live View]
Security --> Events[Event Timeline]
Rooms --> RoomList
Rooms --> RoomDetail
Rail[Nav rail] --> ESP32P4
Rail --> Rooms
Rail --> Frigate
Rail --> Climate
Rail --> Media
Rail --> Settings
```

## Screen 1 — Home
## Screen 1 — Rooms

### Layout
### Layout — Rooms

```
Screen 1 — Home
-------------------------------------------------------- y=0
| Time 10:24 | Weather 26°C | Battery 78% | Wi-Fi -53dB | Header (56px)
-------------------------------------------------------- y=56
| [Alarm: Armed] [Doors: 1 Open] [Cams: OK] [Presence: 2]| Status Chips row (56px)
-------------------------------------------------------- y=112
| [ Lights ] [ Climate ] [ Security Snapshot ] | 3 Cards @ equal width
| - toggle - setpoint - last event thumb |
| - dimmer - humidity - Live button |
-------------------------------------------------------- y=424
| Quick Actions: [Goodnight] [I'm Home] [Away Mode] | QA row (72px)
-------------------------------------------------------- y=496
| ( content spacer ) |
-------------------------------------------------------- y=664
| Home | Rooms | Security | Climate | Media | Right-edge tab rail in code; shown here as bottom bar
-------------------------------------------------------- y=720
```text
Screen 1 — Rooms
+------------------------------------------------------+
| Rooms |
+------------------------------------------------------+
| [Bakery] [Bedroom] [Living Room] |
| toggle toggle toggle |
| temp/humidity badges update per room |
+------------------------------------------------------+
```

### Interactions
### Interactions — Rooms

- Tap card → expand to detail; animate scale 0.98 then expand (`dur-med`).
- Long-press Quick Action → confirm sheet (show list of changes).
- Status chip with anomaly uses `accent`/`warn`/`alert` tokens and navigates to source screen.
- Tap the toggle on any card to fire the room power signal with haptic-style feedback.
- Long-press anywhere on a card to request the detailed sheet for that room/entity pair.
- On first entry, toolbar and cards animate into place (slide/fade, 40 ms stagger).

### Acceptance
### Acceptance — Rooms

- From idle, key info readable in under 2 seconds.
- All primary controls reachable with no more than two taps.
- Three featured rooms remain above the fold with no scrolling.
- Climate badges stay legible even when MQTT updates arrive every second.

## Screen 2 — Rooms
## Screen 2 — Frigate Security

### Layout
### Layout — Frigate Security

```
Screen 2 — Rooms
+------------------+------------------------------------+
| Rooms | Living Room |
| [Living Room] ● | [Group Lights Dimmer 0—100%] |
| [Bedroom] | [Light 1][Light 2][Lamp][Strip] |
| [Kitchen] | [Fan: 0 1 2 3] [Osc ⟳] |
| [Office] | Sensors: T 24.1° H 48% Lux 120 |
| [Patio] | Scenes: [Movie][Bright][Night] |
+------------------+------------------------------------+
```text
Screen 2 — Frigate Security
+------------------------------------------------------+
| Frigate Security |
| [◀ Prev] Camera 2 of 6 [Next ▶] [Quality ▾] [🔈 Mute]
+------------------------------------------------------+
| Card: Backyard Camera |
| • Live feed placeholder fills card body |
| • Status line: "Streaming · 1080p60" |
+------------------------------------------------------+
| Event cards row (wraps): |
| [Front Door · Person] [Garage · Motion] ... |
+------------------------------------------------------+
| Actions row: [Open Gate] [Talk] [Snapshot] [Timeline]
+------------------------------------------------------+
```

### Interactions
### Interactions — Frigate Security

- Tap room → updates detail pane.
- Two-finger swipe left/right → next/previous room.
- Long-press a light → opens per-entity details.
- Prev/Next camera buttons are styled primary controls, ready to bind camera cycling.
- Event cards hide toggles and reserve space for timestamps; tapping can route to clip playback.
- Action buttons ship as large pills so gloves can trigger automations.

### Acceptance
### Acceptance — Frigate Security

- Room switch provides visible response within 150 ms.
- All per-room entities visible without scrolling for up to 8 devices; overflow uses wrap chips.
- Live feed container supports 280 px tall video without layout shifts.
- Four quick actions stay visible at 48 px minimum tap targets.

## Screen 3 — Security (Frigate)
## Screen 3 — Local Climate

### Layout
### Layout — Local Climate

```text
Screen 3 — Local Climate
+------------------------------------------------------+
| Local Climate Station |
+------------------------------------------------------+
| Card: Living Room Climate |
| Indoor temperature / humidity / HVAC mode stack |
+------------------------------------------------------+
| Card: Outdoor Sensors |
| sensor.tab5_temperature / sensor.tab5_humidity |
+------------------------------------------------------+
| Forecast label + three-day chip row |
+------------------------------------------------------+
```
Screen 3 — Security (Frigate)
Top Bar: [◀] Camera 2/4 [▶] [Quality: Auto] [Mute]

+----------------------------------------------+
| Live Video | (auto preview; tap to go live)
| (PIP shows if navigating away) |
+----------------------------------------------+
### Interactions — Local Climate

Recent Events (horizontal scroll):
[Person@Door 2m] [Vehicle@Drive 8m] [Motion Back 12m] [...]
- Cards are informational; toggles and spec rows are hidden to keep data dense.
- Forecast chips flex to fill the row and respond to theme color shifts.

Action row:
[Open Gate] [Talk] [Snapshot] [Timeline ▾]
```
### Acceptance — Local Climate

### Interactions
- Both indoor and outdoor cards stay readable without scrolling.
- Forecast row maintains equal spacing on 1280 px landscape.

- Event chip → opens clip viewer (PiP if live running).
- Alert mode (priority Home Assistant event): whole screen frames in `warn`/`alert`, auto focus, haptic tick (audible click).
## Screen 4 — Media

### Acceptance

- Live start under 1.5 seconds on local network (fallback from HLS → MJPEG → snapshot).
- Loss of stream shows “Low bandwidth” badge and retry call-to-action.

## Screen 4 — Control Center (Modal Sheet)

### Layout
### Layout — Media

```text
Screen 4 — Media
+------------------------------------------------------+
| Card: Now Playing |
| [240×240 album art] Track title / artist / source |
| Transport row: [Prev][Play/Pause][Next] [Volume ▬▬] |
+------------------------------------------------------+
| Card: Quick Scenes |
| [Morning] [Movie] [Night] [Party] |
+------------------------------------------------------+
```
Screen 4 — Control Center (Modal Sheet)
-------------------------------------------
| Control Center |
| Brightness [====------] 60% |
| Volume [===-------] 30% [Mute] |
| Toggles: [Do Not Disturb] [Auto Bright]|
| Network: MyWiFi_5G RSSI -53 dB |
| Power: [Sleep Now] [Restart UI] |
-------------------------------------------

### Interactions — Media

- Transport buttons use accent styling and stretch to equal widths for reliable taps.
- Volume slider tracks 0–100 with immediate value updates.
- Scene chips are pill buttons sized for one-thumb access.

### Acceptance — Media

- Album art and metadata remain side-by-side without overlap at 48 px padding.
- All transport controls sit within a single row to avoid reach shifts.

## Screen 5 — Settings

### Layout — Settings

```text
Screen 5 — Settings
+------------------------------------------------------+
| Connectivity card: Wi-Fi / Home Assistant / Cloud |
| • Each tester button with status pill |
+------------------------------------------------------+
| Theme & Display card: dark mode switch, palette |
| dropdown, brightness slider with value label |
+------------------------------------------------------+
| Network & Time card: Wi-Fi settings / Sync clock / |
| Display tools buttons (two-column layout) |
+------------------------------------------------------+
| Updates card: status label + (Check updates / Start |
| OTA) buttons |
+------------------------------------------------------+
| Diagnostics card: Run diagnostics / Export logs |
+------------------------------------------------------+
| Backup & Restore card: Backup now / Restore backup |
+------------------------------------------------------+
```

### Interactions
### Interactions — Settings

- Sheet appears via swipe-down from header or status tap; dismiss via swipe-down or background tap.
- Brightness and volume sliders use `dur-fast` easing for thumb feedback; Mute toggles instantly.
- Connection tester buttons fire async callbacks and surface status through colored pills.
- Dark mode switch, palette dropdown, and brightness slider emit events only when users interact
(not during state sync).
- Action buttons are grouped per card and reuse the same callback dispatcher for analytics.

### Acceptance
### Acceptance — Settings

- Controls remain operable without leaving current tab context.
- Critical toggles accessible within one gesture from any screen.
- Every control maintains ≥45 px touch height despite dense cards.
- Status labels update asynchronously without tearing hidden cards into view.
Loading