wulf-pulse/docs/superpowers/specs/2026-05-03-mobile-shell-design.md

# Mobile Shell Redesign — Design Spec

**Date:** 2026-05-03
**Scope:** `/mobile/*` shell, navigation, and per-page layouts on Pulse.

## 1. Goal & audience

Pulse's mobile shell exists for **managers on the go** — quick status checks,
triage decisions, and read-only awareness. It is not a full replacement for the
desktop app; pages where mobile editing isn't justified should link out to the
desktop equivalent.

Success means a manager can:

- See the state of the business at a glance (Dashboard).
- Triage and inspect tickets (Tickets).
- Read AR / invoice / payment status (Finance).
- Skim recent AI ticket analyses (Analyzer).
- Reach Engagement and sign-out without clutter on the primary nav.

## 2. Approach

**Rebuild `/mobile` in place.** Keep all existing `/mobile/*` route paths
(`/mobile/dashboard`, `/mobile/tickets`, `/mobile/tickets/[id]`,
`/mobile/finance`). Replace `/mobile/layout.tsx`, the four page files, and
delete `/mobile/nav` (its content moves into a Sheet drawer — see §3).

No new top-level routes. No parallel `/mobile-v2` directory. The existing pages
stay their canonical URLs throughout the redesign.

## 3. Navigation

### 3.1 Bottom tab bar (primary)

Four tabs, equal-width, fixed to the bottom of the viewport:

| Tab        | Icon (lucide)     | Route               |
|------------|-------------------|---------------------|
| Dashboard  | `LayoutDashboard` | `/mobile/dashboard` |
| Tickets    | `Ticket`          | `/mobile/tickets`   |
| Finance    | `DollarSign`      | `/mobile/finance`   |
| Analyzer   | `Sparkles`        | `/mobile/analyzer`  |

Active state: `text-primary`; inactive: `text-muted-foreground`. Active
detection via `pathname.startsWith(href)`.

### 3.2 "More" Sheet drawer (secondary)

A fifth control on the bottom bar — `Menu` icon labelled **More** — opens a
shadcn `Sheet` (side="right", or "bottom" on phones; pick one and stay
consistent). The drawer **replaces the standalone `/mobile/nav` page entirely**.

Drawer contents, top to bottom:

1. **Mobile sections** — Engagement (`/mobile/engagement`, see §6.5).
2. **Full site** — link list to desktop pages that have no mobile view yet
   (Quotes, Configuration Items, Backup Status, Ticket Digest, Admin / Sync).
   Each link uses the `ExternalLink` icon hint to signal "leaves mobile shell".
3. **Account** — current user (avatar + email, read-only), then **Sign out**
   (calls `signOut()` then `router.push('/auth/sign-in')`).

Delete `app/mobile/nav/page.tsx` after the drawer is in place.

## 4. PWA setup

- `public/manifest.json` — name "Pulse", short_name "Pulse", `display: "standalone"`,
  `start_url: "/mobile"`, theme/background colors matching the dark and light
  shells. Reference it from `app/layout.tsx` via `<link rel="manifest">`.
- `viewport` meta in `app/layout.tsx` (or root metadata): include
  `viewport-fit=cover` so the shell can paint behind the home indicator.
- **Safe-area insets** — both the sticky header and the bottom tab bar add
  `env(safe-area-inset-top)` / `env(safe-area-inset-bottom)` padding. Use
  Tailwind arbitrary values (`pt-[env(safe-area-inset-top)]`,
  `pb-[env(safe-area-inset-bottom)]`) or a small utility class.
- **No service worker, no offline mode** in this iteration. Don't ship
  `next-pwa` or a custom SW — deferred until a clear offline use-case lands.
- **Tablet** — `md:max-w-2xl mx-auto` wrapper is noted as a follow-up but is
  **not** part of this spec's deliverable. Keep the current `max-w-lg`.

## 5. Shell (`app/mobile/layout.tsx`)

### 5.1 Header

Sticky top, `bg-background/95 backdrop-blur`, bottom border. Three slots:

- **Left:** Wulf mark (existing logo asset) + "Pulse" wordmark, linked to
  `/mobile/dashboard`. Use the actual brand mark, not the text-only fallback.
- **Right (in order):**
  - `Bell` icon button — **placeholder only**, no menu, no badge logic. Wire
    to `aria-label="Notifications"` and an empty `onClick` so it's
    keyboard-accessible. A future phase will turn this into a real list.
  - Compact user avatar (`Avatar` from shadcn, size `h-7 w-7`). On tap,
    opens the More drawer (so the avatar is the entry point alongside the
    bottom-bar More button).

No page title in the header — pages render their own H1 in the content area.

### 5.2 Content area

`<main>` between header and bottom nav, scrollable. Add bottom padding equal to
the bottom-nav height + safe-area inset so content doesn't hide under the bar.

### 5.3 Bottom nav

Fixed, full-width, `border-t bg-background`. Wraps in `max-w-lg mx-auto` so
content and nav share the same gutter. Five cells: 4 tabs (§3.1) + More (§3.2).

## 6. Pages

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

Sections, top to bottom:

1. **2×2 KPI grid** — four primary metric cards. KPIs to choose from the
   desktop dashboard's hero stats; final selection during build, but the layout
   is fixed at 2×2 on phone widths.
2. **"Needs Attention" strip** — horizontal scroll of compact cards
   surfacing items that require manager action (overdue tickets, failed
   backups, stalled workflows). Each card opens its detail view directly.
3. **Backup / worker status** — compact status row showing the analyzer
   worker, RMM worker, and backup-success-rate at a glance. Read-only; tap
   opens the desktop admin page.

No charts on the mobile Dashboard in this iteration — recharts on small widths
isn't earning its weight.

### 6.2 Tickets (`/mobile/tickets`)

- **Collapsible filter strip** at top (`Collapsible` from shadcn, default
  collapsed). When expanded: status, priority, queue, assigned-to-me toggle.
  Filter state syncs to the URL query string so deep-linking works.
- **Priority-bar rows** — list rows have a left-edge color stripe by priority
  (Critical/High/Medium/Low → red/orange/amber/slate). Body shows ticket #,
  title, company, age, assignee. Single-tap opens detail.
- **Infinite scroll** — replace the current pagination with cursor-based
  infinite scroll. Fetch in pages of ~25; trigger next page when the last row
  enters the viewport (IntersectionObserver). Keep a "Load more" fallback button
  for accessibility.
- **Detail page** — keep `/mobile/tickets/[id]/page.tsx` largely as-is; only
  reskin the header to match the new shell (Wulf mark, breadcrumb back).

### 6.3 Finance (`/mobile/finance`)

Restyle of the existing page only. No new data, no new sections. Adopt the new
Card and typography scale, fix any spacing that breaks on small phones. If a
section currently relies on a wide table, swap it for a stacked list on mobile.

### 6.4 Analyzer (`/mobile/analyzer`) — NEW

**Read-only feed of recent AI ticket analyses.**

- List view: most-recent-first stream of analyses. Each row shows ticket #,
  title, the analyzer's one-line summary, confidence badge, and a stage
  indicator (Triage → Analyze → Deep Review). Tap opens a mobile summary view.
- Mobile summary view: renders **Summary**, **Next Step**, **Next Step
  Rationale** (all already produced by the analyzer pipeline). Includes a "View
  full analysis" link out to the desktop analyzer page.
- No editing, no re-run, no prompt tuning on mobile.
- Source data: existing `analyzer_analyses` rows via a new
  `/api/mobile/analyzer/feed` endpoint (or reuse an existing list endpoint if
  one already returns the right shape).

### 6.5 Engagement (`/mobile/engagement`) — NEW, accessed via More drawer

Engagement gets a **real mobile refactor**, not a thin adaptation. The desktop
page (`app/engagement/page.tsx`, ~1300 lines) and profile page
(`app/engagement/profile/page.tsx`, ~650 lines) both rely on wide tables, dense
charts, and modal patterns that don't translate to phone widths. Build the
mobile views from the same data sources but with phone-first layouts.

**Overview (`/mobile/engagement`):**

- Period selector chip row (today / 7d / 30d) — sticky just below the page H1.
- Summary cards stacked single-column (active users, total Graph hours, total
  Autotask hours, hours-per-active-user). No 4-up grid; reading numbers across
  a 4-up row on a phone is a non-starter.
- Per-employee list as stacked rows (avatar / initials, name, role, hours
  bar). Sortable via a small control above the list (sort by hours, name,
  utilization). Search input above the list.
- Charts: replace the desktop's wide bar/line charts with one compact "hours
  trend" sparkline at the top of the list, period-scoped. No multi-series
  chart on mobile in this iteration.

**User profile (`/mobile/engagement/profile?userId=...` or
`/mobile/engagement/[userId]`):**

- Reuses the existing profile data endpoints. Layout is single-column:
  identity header → period selector → key metrics (compact) → activity
  breakdown list → recent items.
- This **replaces** the desktop user-detail modal pattern on mobile —
  tapping a row navigates to a real page, not a modal, so the shell's back
  gesture works correctly.
- Pick exactly one of the two route shapes above during build (prefer the
  `[userId]` segment form for shareable URLs); don't ship both.

Engagement is **not** on the bottom bar — it lives in the More drawer because
managers don't check it as often as the four primary surfaces.

## 7. Out of scope (explicit non-goals)

- Service worker, offline cache, push notifications.
- Tablet breakpoint (md:max-w-2xl) — noted, deferred.
- Real notification list behind the bell.
- Mobile editing on Engagement (user detail) or Analyzer (re-run, prompt edits).
- Charts / recharts on mobile Dashboard.
- Replacing or restyling the desktop pages reachable from the More drawer.

## 8. Build order

1. PWA scaffolding — `manifest.json`, viewport meta, safe-area utility.
2. New `app/mobile/layout.tsx` — header, More drawer (Sheet), 5-cell bottom nav.
   Delete `app/mobile/nav/page.tsx` in the same change.
3. Dashboard restyle (2×2 grid, Needs Attention, status row).
4. Tickets restyle (filter Collapsible, priority-bar rows, infinite scroll).
   Detail page header reskin only.
5. Finance restyle.
6. Analyzer page + `/api/mobile/analyzer/feed` endpoint.
7. Engagement Overview (`/mobile/engagement`) — phone-first layout from existing data sources.
8. Engagement user profile (`/mobile/engagement/[userId]`) — replaces the desktop modal pattern with a real mobile page.

Each step ships independently — no big-bang merge.