descrybe/docs/mobile-audit.md

# Mobile / tablet audit — descrybe-v2 web

**Date:** 2026-08-04  
**App:** `apps/web` (SvelteKit) at `http://127.0.0.1:5174`  
**Auth:** demo user `demo@descrybe.local` (see [demo-user.md](demo-user.md))  
**Tooling:** codehelper `browser` with `device=mobile` (390×844) and `device=tablet` (768×1024), `format=png`  
**Gate:** `npm run check` → **0 errors, 0 warnings**

---

## Summary

Document-level horizontal overflow on dashboard table pages is fixed (products/feeds document width now matches the viewport ≈390px on mobile). Tables scroll horizontally inside shells. Modals use a bottom-sheet layout on small screens. Tutorial popover clamps and scrolls on narrow viewports. Remaining polish: denser header cluster, mapping/table column density, and tutorial popover vs open drawer.

| Area | Before (mobile) | After |
|------|-----------------|--------|
| Products page width | ~823px (page scroll) | **390px** (table scrolls inside) |
| Feeds page width | ~989px | **390px** |
| Campaigns / Woo | 627–708px | Contained via layout `overflow-x-clip` + table shells |
| Billing / Dashboard / Pricing / Login | Already ~390 | OK |
| `npm run check` | — | **Pass** |

---

## Pages audited

### Login (`/login`) — mobile + tablet

- **Screenshot notes:** Centered sign-in card, brand header, footer legal links. No horizontal overflow. Form fields and Sign in CTA are comfortable tap sizes.
- **Findings:** Secondary text links (Create company / Accept invite / View pricing) are smaller than 44px but usable. OK for auth.
- **Fixes:** None required.

### Pricing (`/pricing`) — mobile

- **Screenshot notes:** Marketing shell with hamburger + theme toggle; plan cards stack vertically; Monthly/Yearly toggle fits.
- **Findings:** Header icon pair is close; FAQ rows are full-width (good). Hero CTA pair sits side-by-side — acceptable.
- **Fixes:** None required this pass.

### Dashboard (`/dashboard`) — mobile

- **Screenshot notes:** Hamburger + company switcher + short “Resume” tour control + avatar. Action grid (tutorial / processing / store / campaign) wraps. Stat cards stack full width.
- **Findings:** Header cluster is dense on 390px. Tutorial opens drawer for nav steps and shows popover over sidebar (step “Standard fields” observed).
- **Fixes:** Shorter header tour labels on xs; larger tap height (~36–40px); layout padding `p-4 sm:p-6`.

### Products (`/products`) — mobile + tablet

- **Screenshot notes (mobile):** Status tabs + search/filters; product flex-table with Quality / Category / Status columns. Viewport no longer widens the document.
- **Screenshot notes (tablet):** Sidebar drawer pattern still uses hamburger at 768; table columns readable; “Resume tutorial” full label visible.
- **Findings:** Table still needs **in-card horizontal swipe** to see Actions; that is intended. Filter row can feel cramped on mobile.
- **Fixes:** `ProductTable` `min-w-[40rem]` + `overflow-x-auto`; page shell `min-w-0`.

### Feeds (`/feeds`) — mobile

- **Screenshot notes:** Stats cards stack; search card; wide feeds table with Name / Source / Type / Interval / Status / Last Synced / Actions. Map + ⋮ actions visible after horizontal scroll.
- **Findings:** Source header truncates in the first viewport until the user scrolls the table — expected with sticky Actions. Map/⋮ remain tight tap targets.
- **Fixes:** Card `min-w-0 overflow-hidden`; shared `Table` `min-w-[36rem]` + overflow shell.

### Mapping (`/feeds/[id]/mapping`) — mobile

- **Screenshot notes:** Title + Auto-map / Extract / Back actions wrap; step tabs and field mapping table; footer Save / Sync sample.
- **Findings:** Step tabs previously clipped horizontally (“Select Product Element” / “Map Fields” side-by-side).
- **Fixes:** Step tabs stack on xs (`flex-col` → `sm:flex-row`).

### Billing (`/billing`) — mobile

- **Screenshot notes:** Plan/credits cards stack; usage chart; Compare / Manage / Add credits actions.
- **Findings:** Header density same as other app pages. No page overflow.
- **Fixes:** Inherited layout/header fixes.

### Campaigns (`/campaigns`) — mobile

- **Screenshot notes:** Search + campaign table (Name / Season / Status / Updated / Actions).
- **Findings:** Table uses horizontal scroll inside card after shell fix.
- **Fixes:** Campaigns table Card `min-w-0 overflow-hidden`.

### Woo / Stores (`/woocommerce`) — mobile

- **Screenshot notes:** Setup steps card; Connection / Categories / … tabs (2-col grid on mobile); credential form; Save / Queue buttons.
- **Findings:** Setup step copy previously appeared clipped when the page itself overflowed; `break-words` added on the steps list.
- **Fixes:** `break-words` on setup `<ol>`; layout containment.

### Sidebar / nav

- **Screenshot notes:** Off-canvas drawer (`#app-sidebar`), overlay, primary links + More. Opens for tutorial nav targets.
- **Findings:** Drawer + tutorial popover compete for space on 390px (popover can cover the highlighted link). Skip/Pause/Back remain reachable.
- **Fixes:** Tutorial popover max-height + edge clamp + full-bleed width under 480px; header hamburger ≥40×40.

### Tutorial overlay

- **Screenshot notes:** Shade panels + highlight ring + popover (“STEP N OF 16”, Skip tour, Pause). Observed on dashboard with More → Standard Fields highlighted.
- **Findings:** Works on mobile; popover should stay smaller / lower when the drawer is open (follow-up).
- **Fixes:** `max-height: min(70dvh, 28rem)`, overflow scroll, safe-area padding, tighter edge inset on small screens.

### Modals (`Dialog`)

- **Intent:** Add Feed and similar dialogs.
- **Fixes:** Mobile bottom-sheet alignment (`items-end`), `max-h-[min(92dvh,900px)]`, scrollable body, removed `sm:min-w-[500px]` that fought small widths.

---

## Code changes (this pass)

| File | Intent |
|------|--------|
| `src/routes/+layout.svelte` | `max-w-[100vw] overflow-x-clip`, `min-w-0` main, compact tour header labels |
| `src/lib/components/DashboardHeader.svelte` | Larger hamburger/logout targets, tighter header gaps |
| `src/lib/components/CompanySwitcher.svelte` | Narrower max-width on xs |
| `src/lib/components/PageShell.svelte` | `min-w-0 max-w-full` |
| `src/lib/components/ui/Table.svelte` | `min-w-[36rem]` + overscroll containment |
| `src/lib/components/ui/TableShell.svelte` | Outer overflow + min-w-0 |
| `src/lib/components/ui/Dialog.svelte` | Mobile bottom sheet + max-height |
| `src/lib/components/ui/TabsList.svelte` | Horizontal scroll when needed |
| `src/lib/components/products/ProductTable.svelte` | Explicit min-width rows for in-shell scroll |
| `src/lib/components/tutorial/TutorialOverlay.svelte` | Small-screen popover sizing/clamp |
| `src/routes/feeds/+page.svelte` | Table card overflow containment |
| `src/routes/campaigns/+page.svelte` | Table card overflow containment |
| `src/routes/woocommerce/+page.svelte` | Setup steps `break-words` |
| `src/routes/feeds/[feedId]/mapping/+page.svelte` | Step tabs stack on mobile |

---

## Follow-ups (not blocking)

1. **Tutorial + drawer:** Prefer bottom-anchored popover when `navUi.mobileOpen`, or auto-scroll the highlighted nav item above the popover.
2. **Feeds/products actions:** Increase Map / ⋮ hit areas to ≥44px on touch.
3. **Products filters:** Stack category/feed/sort full-width on xs.
4. **Tablet (≥768):** Consider showing persistent sidebar earlier (`md:` vs `lg:`) so tablet does not rely only on the drawer.
5. **Add Feed modal e2e:** Browser click was flaky with overlapping outline targets; re-verify after drawer closed.

---

## How to re-run

```bash
# from apps/web
npm run check
```

Browser (codehelper MCP / CLI), with demo session:

- Base URL: `http://127.0.0.1:5174`
- `device=mobile` and `device=tablet`
- Prefer `format=png` if WebP encoding is unavailable in the agent host
- Authenticated pages: login then `session=<name>` reuse

Key routes: `/login`, `/pricing`, `/dashboard`, `/products`, `/feeds`, `/feeds/<id>/mapping`, `/billing`, `/campaigns`, `/woocommerce`.