manage/openspec/changes/mobile-responsive-parity/tasks.md

Tasks — Mobile responsive parity

Change: mobile-responsive-parity Phase: tasks Date: 2026-06-26

Review workload forecast

Field	Value
Estimated changed lines	~2200–2800
Chained PRs recommended	Yes (10 slices)
Chain strategy	stacked-to-main
Slice order	1 (primitives) → 2 (Dashboard) → 3–5 (tables) → 6–8 (forms) → 9 (touch audit) → 10 (docs + verify)

Each slice is committed separately (user pref). Every slice must leave cd frontend && npm run lint && npm run build && npm run test green. Every touched page gains a Vitest case asserting behavior at <768px and ≥768px.

---

Slice 1 — Shared primitives

Goal: Land the four building blocks every later slice depends on. No page-level behavior changes yet.

• 1.1 useIsMobile() hook

  • Files: frontend/src/hooks/useIsMobile.ts (new)
  • Lines: ~20
  • Details: SSR-safe matchMedia("(max-width: 768px)") listener per design.

• 1.2 MobileCardRow component

  • Files: frontend/src/components/ui/mobile-card.tsx (new), plus a Vitest spec frontend/src/components/ui/__tests__/mobile-card.test.tsx.
  • Lines: ~80 + ~60 test
  • Details: generic <T,>, fields list, primary field, optional onRowClick and actions slot per design. 44px min card height.

• 1.3 SheetForm component

  • Files: frontend/src/components/ui/sheet-form.tsx (new), plus spec.
  • Lines: ~70 + ~50 test
  • Details: wraps shadcn Sheet; sticky header + sticky footer; h-[100dvh]; props per design. Dirty-state confirm on outside click.

• 1.4 EditActionButton — extend HoverEditButton

  • Files: frontend/src/components/HoverEditButton.tsx
  • Lines: ~15
  • Details: add mobile="always" | "hover" (default always). Tailwind: always visible below md, hover-revealed at md: and up.

• 1.5 mobile-touch-target utility

  • Files: frontend/src/index.css (add utility)
  • Lines: ~10
  • Details: media-gated 44×44 min hit area per design.

• 1.6 Replace inline matchMedia in App.tsx

  • Files: frontend/src/App.tsx
  • Lines: ~10 removed, ~3 added
  • Details: use useIsMobile(); preserve current shell behavior exactly.

---

Slice 2 — Dashboard (R7)

Goal: Dashboard collapses to single column + section anchor bar on mobile.

• 2.1 Single-column grid below md

  • Files: frontend/src/pages/Dashboard.tsx
  • Lines: ~20
  • Details: widget list uses grid grid-cols-1 md:grid-cols-* (match existing desktop column count). Respect configured sort order.

• 2.2 Section anchor bar

  • Files: frontend/src/pages/Dashboard.tsx
  • Lines: ~40
  • Details: group widgets (Observability / Media / Backups / Custom). Anchor bar md:hidden, horizontal scroll of pills, jumps to section by id.

• 2.3 Tests

  • Files: frontend/src/pages/__tests__/Dashboard.test.tsx
  • Lines: ~40
  • Details: assert single column at 375px, grid at 1280px, anchor bar visible only at <768px.

---

Slice 3 — Media table (R3.1, R3.5)

• 3.1 Mobile fields + card render

  • Files: frontend/src/pages/Media.tsx
  • Lines: ~60
  • Details: card primary = title; fields = size, HDR flag, library, year. Hide column-visibility toggle below md. Preserve pagination controls.

• 3.2 Tests

  • Files: frontend/src/pages/__tests__/Media.test.tsx
  • Lines: ~40

---

Slice 4 — FileBrowser table (R3.1)

• 4.1 Mobile fields + card render

  • Files: frontend/src/pages/FileBrowser.impl.tsx
  • Lines: ~60
  • Details: card primary = name; fields = size, mtime, type. Preserve directory-navigation tap target (whole card). Preserve ffprobe/job affordances.

• 4.2 Tests

  • Files: frontend/src/pages/__tests__/FileBrowser.test.tsx
  • Lines: ~30

---

Slice 5 — Users + Backups tables (R3.1)

• 5.1 UsersPage card

  • Files: frontend/src/pages/UsersPage.impl.tsx
  • Lines: ~70
  • Details: card primary = display name; fields = username, activity badge, email (if present). Preserve selection checkboxes (44px) and drawer open.

• 5.2 Backups cards (3 tables)

  • Files: frontend/src/components/BackupAlertsTable.tsx, frontend/src/components/BackupJobsTable.tsx, frontend/src/components/BackupRunsTable.tsx
  • Lines: ~120 (3 × ~40)
  • Details: per-table primary + 3 fields; preserve acknowledge/run actions on the card.

• 5.3 Tests

  • Files: existing component test files
  • Lines: ~90

---

Slice 6 — ServicePage form (R4)

• 6.1 Sheet form below md

  • Files: frontend/src/pages/ServicePage.tsx
  • Lines: ~60
  • Details: branch on useIsMobile(); reuse form body inside SheetForm. Single-column fields. Preserve save semantics.

• 6.2 Tests

  • Files: frontend/src/pages/__tests__/ServicePage.test.tsx (new or extend)
  • Lines: ~50

---

Slice 7 — Settings form (R4)

• 7.1 Machines + SSH-key editors in Sheet

  • Files: frontend/src/pages/Settings.tsx
  • Lines: ~100
  • Details: both machine editor and SSH-key editor open in SheetForm below md. Validate-on-save preserved.

• 7.2 Tests

  • Files: frontend/src/pages/__tests__/Settings.test.tsx
  • Lines: ~40

---

Slice 8 — Message compose + WidgetConfigDialog (R4)

• 8.1 Message compose Sheet

  • Files: frontend/src/pages/UsersPage.impl.tsx
  • Lines: ~60
  • Details: compose dialog → SheetForm below md. HTML body textarea + iOS Safari attachment upload verified manually.

• 8.2 WidgetConfigDialog Sheet

  • Files: frontend/src/components/WidgetConfigDialog.tsx
  • Lines: ~60
  • Details: reorder list and per-widget config render inside SheetForm below md. Sticky save bar.

• 8.3 Tests

  • Files: extend existing
  • Lines: ~60

---

Slice 9 — Touch-target audit (R6)

• 9.1 Apply mobile-touch-target across routes

  • Files: all 9 pages + shared components (SessionActivityPanel, ObservabilityPage, etc.)
  • Lines: ~150 (sprinkled)
  • Details: icon buttons, checkboxes, switches, badges-as-buttons, row taps. Manual device-mode pass at 375px logging violations; fix each.

• 9.2 Audit log

  • Files: this PR description
  • Details: list every element touched with before/after hit-area size.

---

Slice 10 — Docs + verify

• 10.1 Update docs/REQUIREMENTS.md

  • Files: docs/REQUIREMENTS.md
  • Lines: ~20
  • Details: add a Mobile section documenting the breakpoint, card/Sheet behavior, 44px policy, and the polling follow-up risk.

• 10.2 Cross-route manual pass

  • Details: walk all 9 routes at 375px (iPhone 12 Pro preset) and at 1280px. Confirm no regressions; file follow-ups for any iOS Safari quirks found.

• 10.3 Verify report

  • Files: openspec/changes/mobile-responsive-parity/verify-report.md
  • Lines: ~80
  • Details: per-AC evidence (AC1–AC8), tool versions, manual test notes.

---

Notes

• Each slice's diff should stay well under 400 changed lines. If a slice (e.g. Settings at ~100 + 40 test) approaches the budget, split along the natural sub-section boundary.
• Slices 3–5 (tables) and 6–8 (forms) can be reordered or parallelized across branches if helpful, but each must merge green.
• No slice touches the backend.