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

Spec — Mobile responsive parity

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

Scope

All 9 application routes must be fully operable in phone portrait viewports (≥360px) at a single md: (768px) breakpoint. Tablets and wider viewports keep the existing desktop layout unchanged. No product behavior changes; this is a presentation-layer parity change only.

Requirements

R1 — Viewport & breakpoint policy

• R1.1 The viewport meta stays width=device-width, initial-scale=1.0 (no zoom lock). User zoom remains enabled.
• R1.2 There is exactly one responsive cut: md: (768px). Below is "mobile"; at-or-above is "desktop" (existing behavior).
• R1.3 No sm: intermediate cut is introduced.

R2 — App shell (already compliant; locked in)

• R2.1 Desktop Sidebar renders null when isMobile (matchMedia("(max-width: 768px)")).
• R2.2 Mobile nav uses the existing MobileDrawer (hamburger, md:hidden, Sheet side=left) with no behavioral change.
• R2.3 TopBar keeps its existing responsive behavior (version badges hidden on small screens, hamburger visible below md).

R3 — Data tables (hybrid)

• R3.1 The four wide tables — Media (pages/Media.tsx), FileBrowser (pages/FileBrowser.impl.tsx), Users (pages/UsersPage.impl.tsx), and the three Backups tables (BackupAlertsTable.tsx, BackupJobsTable.tsx, BackupRunsTable.tsx) — render a stacked card per row below md.
• R3.2 Each card shows a primary title plus the 3–5 most important fields for that table (chosen per-table; documented in tasks). All remaining fields are omitted from the mobile card.
• R3.3 Row click / selection semantics are preserved on the card (tap target = the whole card where applicable).
• R3.4 SessionActivityPanel (narrow, 3-column) keeps the <table> shape inside a horizontal-scroll container below md.
• R3.5 The TanStack column-visibility toggle is hidden below md on every table that uses it (Media). The mobile card picks the fields; the user does not re-show hidden columns on touch.
• R3.6 At md: and above, all tables render exactly as today.

R4 — Edit forms (Sheet)

• R4.1 Below md, these edit flows open in a full-height Sheet (side=bottom or side=right, full screen) instead of a centered Dialog:
  • ServicePage connection config + secrets
  • Settings machines and SSH-key editors
  • Message compose dialog (UsersPage.impl.tsx)
  • WidgetConfigDialog
• R4.2 The Sheet form has a sticky header (title + close affordance) and a sticky footer/save bar (Cancel + Save).
• R4.3 Form fields stack to a single column inside the Sheet.
• R4.4 At md: and above, the existing Dialog-based forms are unchanged.
• R4.5 The Sheet closes on successful save and on explicit cancel; it does not close on outside-click while the form is dirty (confirm prompt).

R5 — Touch edit affordance

• R5.1 HoverEditButton gains a md: variant: hover-revealed on desktop (unchanged), always visible below md.
• R5.2 Row/card edit and delete actions surface as persistent icon buttons on the right edge below md.
• R5.3 Desktop hover-reveal aesthetic is not regressed at md: and above.

R6 — Touch targets

• R6.1 All interactive elements below md have a minimum 44×44px hit area. This includes: buttons, icon buttons, checkboxes, switches, row/card tap targets, and badges that act as buttons.
• R6.2 Visual size may remain smaller than 44px (padding-only hit areas are acceptable) as long as the tappable region meets the minimum.
• R6.3 At md: and above, sizes are unchanged.

R7 — Dashboard layout

• R7.1 The widget grid collapses to a single column below md.
• R7.2 A section anchor bar appears at the top of the dashboard below md, grouping widgets (e.g. Observability / Media / Backups / Custom) and allowing quick jump-to-section.
• R7.3 Widget order respects the user's configured sort order.
• R7.4 At md: and above, the grid renders exactly as today.

R8 — Polling (unchanged)

• R8.1 Widget refresh intervals and the message-queue poll interval are identical on mobile and desktop.
• R8.2 (Follow-up risk, not in scope: pause refetch on document.visibilityState === "hidden". Tracked in proposal §Risks.)

R9 — No PWA

• R9.1 No web manifest, service worker, or standalone display mode is added.
• R9.2 OIDC continues to work in-browser; no standalone-mode redirect handling is introduced.

R10 — Non-regression

• R10.1 No desktop layout (≥768px) is visually or functionally regressed.
• R10.2 No backend API contract change.
• R10.3 No existing test is deleted; mobile-specific tests are additive.

Acceptance criteria

• AC1 Every route listed in App.tsx navItems (Dashboard, Observability, Media, Files, Backups, Users, Actions, Services, Settings) is fully operable at 375px width in Chrome DevTools device mode (iPhone 12 Pro preset or equivalent).
• AC2 Each of the four wide tables shows a card layout at 375px and the table layout at 1280px.
• AC3 Each of the four edit forms opens in a Sheet at 375px and a Dialog at 1280px.
• AC4 HoverEditButton is always visible at 375px and hover-revealed at 1280px.
• AC5 A 44px-minimum touch-target audit passes for all interactive elements at 375px.
• AC6 The Dashboard renders a single column with an anchor bar at 375px and the existing grid at 1280px.
• AC7 cd frontend && npm run lint && npm run build && npm run test is green.
• AC8 At least one Vitest test per touched page asserts behavior at <768px and ≥768px breakpoints.

Non-goals

• Tablet/landscape/sm: intermediate layout.
• PWA, manifest, service worker, offline mode.
• Polling-interval changes.
• Backend changes.
• New data-table library.
• New product features.