# PNPL Dashboard — Complete UX Overhaul Spec

## The Core Problem

The dashboard was built feature-first: each page maps to a technical concept (Events, Pledges, Reconcile, Exports, Settings). But the **user doesn't think in features** — they think in **goals**:

- "How do I get people to pledge?"
- "Has anyone paid yet?"
- "Someone said they paid but I can't find it"
- "My treasurer needs a report"

The current UI has 3 fatal problems:

1. **Jargon everywhere** — "Reconcile", "QR Sources", "Rail", "Initiated", "Pipeline by Status", "Conversion rate". A masjid volunteer doesn't speak SaaS.
2. **Two visual identities** — Landing pages are bold, typographic, high-contrast (BRAND.md). Dashboard is generic shadcn/ui with rounded cards, muted colours, and card-heavy layouts. They feel like different products.
3. **Feature-oriented, not goal-oriented** — The user has to learn the system's mental model instead of the system matching theirs.

---

## Personas & Their Real Journeys

### Persona 1: Charity Admin (Aaisha)
**Who:** Fundraising manager at a UK Islamic charity. Not technical. Uses WhatsApp all day.
**Her actual journey:**
1. "I need to collect pledges at our gala next Saturday" → Create campaign + links
2. "The event is tonight, give each table a QR code" → Print QR codes
3. "It's Monday, who pledged? Who's paid?" → Check the money
4. "My treasurer needs numbers for the trustees meeting" → Download a report
5. "Ahmed said he paid but we can't see it" → Find & match a payment

**What confuses her today:**
- "Campaigns" (she calls them "appeals" or just "the dinner")
- "QR Sources" → she just wants "links for my volunteers"
- "Reconcile" → she'd say "check the bank"
- "Initiated" status → "what does that mean?"
- "Rail" → completely alien
- "Pipeline by Status" → ???

### Persona 2: Volunteer (Yusuf)
**Who:** Table captain at the gala. Has his own QR code. Checks his phone to see pledges.
**His actual journey:**
1. Gets a link from Aaisha → opens volunteer view
2. Shows QR code at his table → donors scan it
3. Checks "how am I doing?" on his phone
4. Wants to brag → shares leaderboard

**He never sees the dashboard** — his entire journey is `/v/[code]`. But if Aaisha asks him to "help manage", he'd see the dashboard and be completely lost.

### Persona 3: Treasurer (Fatima)
**Who:** Charity trustee responsible for financial oversight. Needs Gift Aid reports, bank reconciliation, clean data.
**Her actual journey:**
1. "Download last month's Gift Aid declarations" → Export
2. "Match bank statement to pledges" → Upload CSV, see matches
3. "Show me the money: what's collected vs outstanding" → Summary
4. "I need this for the trustees report" → Numbers she can screenshot

**What confuses her today:**
- Column mapping UI (Date Column, Description Column...) → she just wants to upload a file and it works
- Technical status names
- No clear "money in vs money out" view

### Persona Overlap
Aaisha does 80% of the work. She IS the charity admin, the event organiser, AND does the bank checking. Fatima only logs in once a month. Yusuf never logs in.

**This means: optimise everything for Aaisha. Make Fatima's tasks findable but not in the way. Yusuf is a non-factor for dashboard design.**

---

## The Redesign: Goal-Oriented Navigation

### Before (feature-oriented)
```
Overview | Campaigns | Pledges | Reconcile | Exports | Settings
```

### After (goal-oriented)
```
Home | Collect | Money | Reports | Settings
```

| Old | New | Why |
|-----|-----|-----|
| Overview | **Home** | Everyone understands "Home" |
| Campaigns | **Collect** | "I want to collect pledges" — the verb, not the noun |
| Pledges | **Money** | "Where's the money?" — that's what they're checking |
| Reconcile | (merged into Money) | "Check the bank" is part of "where's the money" |
| Exports | **Reports** | Charities think in "reports", not "exports" |
| Settings | **Settings** | Fine as-is, but with friendlier sub-labels |

### Terminology Overhaul

| Old (SaaS jargon) | New (human language) | Where used |
|---|---|---|
| Campaign | Appeal / Collection | Nav, headers |
| QR Source | Pledge link | Cards, dialogs |
| Reconcile | Match payments | Nav, page title |
| Rail | Payment method | Tables, detail |
| Initiated | Said they've paid | Status badge |
| Pipeline by Status | How pledges are doing | Dashboard card |
| Conversion rate | % who pledged | Stats |
| CRM Export Pack | Full data download | Export card |
| Webhook / API | Connect to other tools | Export card |
| GoCardless | Direct Debit | Settings |
| Reference prefix | Code prefix | Settings |
| Auto-confirmed | Automatically matched | Reconcile |

### Status Labels (the biggest confusion)

| Old | New | Color | What it actually means |
|---|---|---|---|
| new | **Waiting** | Gray | Pledge made, no payment yet |
| initiated | **Said they paid** | Amber | Donor clicked "I've paid" or replied PAID |
| paid | **Received** ✓ | Green | Payment confirmed in bank |
| overdue | **Needs a nudge** | Red | No payment after reminder cycle |
| cancelled | **Cancelled** | Gray muted | Donor or staff cancelled |

---

## Visual Identity: Bringing Brand into the Dashboard

### Current Dashboard Style
- Generic shadcn/ui (rounded-lg cards, muted-foreground, hover:shadow-md)
- No brand colors except occasional trust-blue
- Card-heavy layout (everything in a Card with CardHeader/CardContent)
- Small text, low contrast
- Emoji as visual anchors (🤲, 💷, 🏦)

### Target Dashboard Style (matching BRAND.md)
- **Sharp edges** — remove rounded-lg on cards, use squared or rounded-sm max
- **Typography as hero** — big bold numbers, not cards with icons
- **Gap-px grids** instead of card grids for stats
- **Dark sections** for key actions (1-2 per page)
- **Left-border accents** on feature items
- **No emoji in UI** — use the brand icon system
- **60-30-10 color rule** — Midnight + Paper base, Promise Blue actions, Gold/Green/Red status only
- **Signature numbered steps** (01, 02, 03) in setup flow

---

## Implementation Plan

### Phase 1: Navigation + Terminology (layout.tsx)
- Rename nav items
- Update sidebar visual to match brand
- Remove emoji from sidebar help box

### Phase 2: Dashboard Home (page.tsx)
- Rewrite with brand typography
- Gap-px stat grid instead of card grid
- Human status labels
- Remove jargon

### Phase 3: Collect page (events → collect)
- Rename to "Collect"
- Simplify campaign creation
- Better empty state

### Phase 4: Money page (pledges + reconcile merged)
- Two tabs: "People" (pledge list) and "Bank" (reconcile)
- Human column labels
- Human status badges

### Phase 5: Reports page (exports)
- Cleaner cards
- Brand style

### Phase 6: Settings page
- Friendlier labels
- Remove technical jargon