beardrive/docs/mobile-quality-prd.md

Spec: Mobile layout quality for the BearDrive web app

Authoritative spec for the mobile-polish goal loop. The bar is met by independent review: a beardrive-designer subagent audits the running app and returns scores; the implementing agent never scores its own work.

Harness

Seeded hub: BDRIVE_E2E_SERVE=1 go test -count=1 -timeout 8h -run TestE2EServe ./internal/webapp → http://localhost:8993 (state resets per start). Accounts (password e2e-pass-1 for all): e2e@example.com (admin — insights, admin bar, org Manage), member@example.com (member), solo@example.com (no org — onboarding empty state).

Viewports (all must pass)

Name	Size
phone-small	360×800
phone	390×844
phone-landscape	844×390
tablet	768×1024

Surfaces to audit (per viewport)

1. Login page (/auth/login) — server-rendered, still in scope.
2. Project home: connect guide (tabs, code blocks + copy buttons) and, as admin, the embedded Insights below (treemap/scatter/hot-path/matrix SVGs must not overflow or become unreadably small).
3. Folder listing (/<pid>/notes): rows, heat dots, Recent changes feed.
4. Markdown file view (/<pid>/index.md): content, breadcrumbs, meta line, topbar actions (Share/History/Upload/Download vs the ⋯ menu — targets must stay tappable, header must not wrap or overflow).
5. History (/<pid>/history): entry rows, expandable notes.
6. Dedicated Insights (/<pid>/insights).
7. Org admin panel (Manage) and hub settings (Admin) — lists, selects, buttons, toggles.
8. Off-canvas sidebar: hamburger open/close, backdrop, tree interaction, auto-close after selecting a file.
9. ⌘K palette (on tablet; on phones verify the Search button opens it and it is usable).
10. Modals (new-project prompt, share dialog, confirms) and toasts.
11. Onboarding empty state (as solo@).

Scoring rubric (designer subagent returns 0–10 per category)

• layout — nothing overflows the viewport; no horizontal page scroll; wide content (code blocks, tables, SVGs, URLs) scrolls in its own box.
• readability — type sizes/line lengths sane; nothing truncated without recourse; contrast preserved.
• tap-targets — interactive elements ≥ ~44px effective target; no overlapping/cramped controls.
• navigation — sidebar, breadcrumbs, back/forward, deep links all usable one-handed; nothing reachable only by hover.
• polish — spacing, alignment, safe-area behavior, orientation change.

Findings carry severity (high/medium/low), the viewport+surface, and a concrete CSS/markup fix suggestion.

Exit bar

Two CONSECUTIVE designer rounds with every category ≥ 8/10 and zero high-severity mobile findings across all viewports. Desktop (1360×900) spot-checked each round — no regressions introduced by mobile fixes.

Rules

• Fix in internal/webapp/frontend (prefer src/style.css; markup only when CSS can't). Rebuild committed static (npm run build) after every change; npm run e2e (42 specs) must stay green each iteration.
• No new runtime dependencies; no desktop redesign — mobile fixes only.
• Never commit internal/webapp/manual_serve_test.go.
• Branch feat/mobile-polish, commit per iteration (feat(webapp): [mobile] ...), PR at the end; never merge or deploy.
• Disputed/won't-fix findings: record below with reasoning, count them out of the exit bar only if justified here.

Scorecard (append one row per designer round)

Round	layout	readability	tap-targets	navigation	polish	high-sev findings
1 (before fixes)	5	7	6	8	7	1 (topbar overflow at 768/844 — breakpoint gap)
2 (after round-1 fixes)	9	8	8	9	8	0 (5 low cosmetics, fixed before round 3)
3 (after low-fixes)	6	6	7	9	6	1 (REGRESSION: URL rows collapsed by the wrap fix — streak reset, fixed for round 4)
4 (after round-3 fixes)	9	9	8	9	8	0 (4 lows: chips/tabs/modal-input heights + share row at 360, fixed before round 5)
5 (confirmation)	9	9	9	9	8	0 — EXIT BAR MET (rounds 4+5 consecutive passes)

Won't-fix / disputed

• Palette footer shows keyboard hints ("↑↓ · ↵ · esc") on touch (round-5 low #1, second half): cosmetic copy noise; tap interaction fully works. Changing the hint per-viewport adds conditional copy for no functional gain. (The ⌘K badge half of the finding was a real bug — the React port dropped id="search-btn", so the existing hide rule never matched; fixed post-exit, e2e green.)
• Share dialog's Done sits alone on its last row at ≤430 (round-5 low #2): reviewer marked it "intended destructive-isolation behavior… subjective/taste — no action needed".
• Server auth pages use 44px controls via their own inline CSS (authlocal.go), the one fix outside frontend/ — the login page is a spec surface but is server-rendered, unreachable from the frontend stylesheet.

Status

GOAL COMPLETE (2026-07-14): rounds 4 and 5 both scored every category ≥8 with zero high-severity findings. Five designer rounds total; round 3 caught and reset on a regression the loop itself introduced — the independent-scoring design worked as intended.

Status / blockers

(record and stop rather than deviate)