nick-doc/PRD - UI UX Overhaul (Amaneh Design System).md

# PRD — UI/UX Overhaul: Adopting the Amaneh Design System

**Status:** Planning  
**Author:** Claude / Design System by ClaudeDesign  
**Date:** 2026-05-29  
**Scope:** Full frontend UI/UX replacement — web app + Telegram Mini App

---

## 1. The Problem

The current frontend was built on top of MUI v7 with a standard Material Design theme (teal primary `#00A76F`, flat white backgrounds, MUI's default elevation model). It works, but it reads as generic SaaS. The escrow context — trust, money, legal finality — demands a different visual language. Specific pain points:

| Pain Point | Current State | Why It Matters |
|---|---|---|
| **Color feels cold and institutional** | Teal-green primary, grey surfaces | Escrow is about trust, not tech dashboards |
| **Typography is indistinct** | Almarai/Vazirmatn (UI only) | No hierarchy between headings, data, and UI chrome |
| **Status vocabulary is loose** | MUI semantic colors (`warning`, `info`, `success`) mapped inconsistently to states | Users can't reliably decode what "blue chip" vs "green chip" means |
| **Telegram UI ≈ Web UI** | TelegramMiniAppShell re-uses full MUI dashboard chrome | Telegram has native back button, bottom sheet patterns, safe area insets — these aren't used |
| **No brand identity** | Logo is text-only; no mark, no seal | Escrow platforms need institutional credibility signals |
| **Dark/Light toggle is cosmetic** | Both modes use the same palette logic | Cream paper + warm ink in light mode is more appropriate than flat white |

---

## 2. The Proposed System (ClaudeDesign Brief)

The `escrowPlatform.zip` design brief introduces **"Amaneh"** — a named, coherent design system with the following pillars:

### 2.1 Color System

Replace the current 6-preset MUI palette with a **5-ramp warm earth system**:

| Ramp | Token | Hex (primary) | Semantic Role |
|---|---|---|---|
| **Cream / Ink** | `--cream-50` / `--ink-900` | `#FBF6EB` / `#1C1410` | Surface + text — warm not white/black |
| **Saffron** | `--saffron-600` | `#C2410C` | Single action color: buttons, links, focus rings |
| **Pistachio** | `--pistachio-700` | `#3D6B4F` | Good / Released / Success states |
| **Persian Blue** | `--persian-700` | `#1F4A8A` | Active / In-transit states |
| **Honey** | `--honey-700` | `#8A6314` | Pending / Warning states |
| **Pomegranate** | `--pomegranate-700` | `#8E2424` | Disputed / Error states |

**What to drop:** The current 5 color presets (blue, purple, orange, red, green themes) and the settings drawer preset switcher. Single authoritative palette.

### 2.2 Typography System

Three-font stack replacing the current single Almarai/Vazirmatn stack:

| Role | Font | Use |
|---|---|---|
| **Display / Headings** | Source Serif 4 (italic 500–600) | Page titles, section headers, pull quotes |
| **UI / Body** | IBM Plex Sans | All UI chrome, body text, labels |
| **Data / Mono** | IBM Plex Mono | Amounts, hashes, addresses, status codes, table data |
| **Persian headings** | Vazirmatn 700 | RTL headings |
| **Persian body** | Vazirmatn 400 | RTL body text |
| **Persian mono** | IBM Plex Mono | Numbers (works in both scripts) |

### 2.3 State Vocabulary (Chip System)

Fixed 1:1 mapping — no more loose MUI semantic color usage:

| State EN | وضعیت FA | Chip Class | Color |
|---|---|---|---|
| Held | نگهداری شده | `chip--saffron` | Saffron |
| Shipping | در حال ارسال | `chip--active` | Persian Blue |
| Inspection | بازرسی | `chip--active` | Persian Blue |
| Released | آزاد شد | `chip--good` | Pistachio |
| Pending | در انتظار | `chip--warn` | Honey |
| Disputed | اختلاف | `chip--bad` | Pomegranate |
| Cancelled | لغو شد | *(neutral)* | Ink muted |

### 2.4 Brand Mark

Three logo options proposed (Seal, Bridge, Knot marks) + serif italic wordmark "amaneh·". Recommendation: **SealMark** (compact, works at 16px favicon and 64px logo) with wordmark for desktop nav.

### 2.5 Surface Treatment

- **Background:** `#E7DFCB` (warm parchment) instead of MUI's `#F4F6F8` grey
- **Paper:** `#FBF6EB` (cream) instead of `#FFFFFF`
- **Cards:** 1px `--border-hairline` border, `--shadow-1` (near-hairline) instead of MUI elevation shadows
- **Corner ticks:** optional `.doc-chrome` motif on key document cards (escrow agreements, receipts)
- **Paper grain:** subtle noise texture on dark panels

---

## 3. Telegram UI vs. Web UI — The Differentiation Problem

### Current State

The Telegram Mini App (`/telegram` route, `TelegramMiniAppShell`) renders a list of action cards using MUI `Card`, `Button`, `Typography` — identical to the web dashboard. The only Telegram-specific code is safe area insets and theme color attachment.

### What Telegram Mini Apps Actually Need

Telegram has its own UX contract:
- **Back button** (hardware/header back) — not a browser back arrow
- **MainButton** — a full-width bottom CTA managed by `Telegram.WebApp.MainButton`
- **Bottom sheets** instead of dialogs
- **Haptic feedback** (`Telegram.WebApp.HapticFeedback`)
- **Native color tokens** (`--tg-theme-bg-color`, `--tg-theme-text-color`, etc.)
- **Touch targets ≥ 48px**, thumb-reachable primary actions
- **No sidebar navigation** — replace with bottom tab bar or header-only nav
- **Compressed information density** — single-column, card-per-item

### Proposed Telegram-Specific Design Rules

1. **Layout:** Full-width single column. No sidebar. Header = `←` back + title + optional right action.
2. **Navigation:** Bottom tab bar (4 items max): Dashboard · Requests · Chat · Account
3. **Primary actions:** Use `Telegram.WebApp.MainButton` for the primary CTA on each screen (pay, confirm, release)
4. **Modals → Bottom sheets:** Replace `Dialog` with a swipeable bottom sheet component
5. **Theme tokens:** Consume `--tg-theme-*` CSS vars as overrides on top of the Amaneh palette — so the app looks "at home" in both Telegram light and dark contexts
6. **Haptics:** Add feedback on state-changing taps (confirm, release, dispute)
7. **Font size:** Minimum 16px body (no 12px UI text in Telegram — pinch zoom is disabled)
8. **Status chips:** Same vocabulary as web, but rendered as full-width banners when the status is primary on a screen

The goal is: the Telegram app should feel like a **Telegram app** that happens to be an escrow tool — not a dashboard stuffed into a WebView.

---

## 4. What Is and Isn't Implemented in the Design Brief

The ClaudeDesign zip contains:

| File | What's Implemented | What's Missing |
|---|---|---|
| `styles.css` | Full CSS token layer, all color ramps, typography scale, buttons, chips, inputs, nav items, metric tiles | No responsive breakpoints, no dark mode tokens |
| `foundations.jsx` | Color palette artboard, type specimen, chip vocabulary table | No React component library — just reference renders |
| `dashboard.jsx` | Buyer dashboard mockup (sidebar + topbar + stat tiles + escrow card list) | Not wired to real data; not a component — a single monolith render |
| `auth.jsx` | Sign-in split-screen (form + dark side panel with pull quote) | Sign-up, reset password, verify pages not designed |
| `brand.jsx` | Logo variants (Seal, Bridge, Knot, Stamp), wordmark variants, bilingual lockups | No SVG exports, no favicon spec |
| `app.jsx` | Comparison artboard (before/after) | Not a deliverable component |
| `design-canvas.jsx` | Full design canvas with all artboards stitched together | Not a component — design review surface only |
| `uploads/escrow-design-ui/` | Partial Next.js structure (layouts, sections, nav configs) | Incomplete — missing most section components |

**Bottom line:** The design system spec is complete and implementable. The React components are scaffolding only. We are building from scratch using the spec as the source of truth.

---

## 5. Implementation Plan

### Phase 0 — Foundation (Do First, Blocks Everything)

**Goal:** Replace the token layer without touching any existing component logic.

1. **Add Google Fonts** — Source Serif 4 + IBM Plex Sans + IBM Plex Mono to `layout.tsx`
2. **Create `src/theme/amaneh-tokens.css`** — Direct port of `styles.css` token layer (CSS vars only, no utility classes)
3. **Update `src/theme/theme-config.ts`** — Wire new color ramps into MUI palette:
   - `primary.main` → `#C2410C` (saffron-600)
   - `background.default` → `#E7DFCB`
   - `background.paper` → `#FBF6EB`
   - `text.primary` → `#1C1410`
   - Success/Warning/Error/Info → pistachio/honey/pomegranate/persian ramps
4. **Update `typography.ts`** — Set font families to the three-font stack
5. **Remove 5 color presets from settings** — Delete preset switcher; remove from `SettingsDrawer`
6. **Update `components/theme/core/`** — Card, Button, Chip, Input MUI overrides to match Amaneh spec

**Estimated effort:** 2–3 days. No page-level changes. Immediately visible everywhere.

---

### Phase 1 — Core Components (High Impact, Low Risk)

**Goal:** Replace the atomic UI elements that appear on every screen.

| Component | Change |
|---|---|
| `Label` / status chips | Rewrite using Amaneh chip vocabulary (7 states, fixed color mapping) |
| `Logo` | Replace with `SealMark` + serif wordmark |
| Navigation items (sidebar) | Update active state to saffron-50 bg + saffron-700 text |
| Buttons | Saffron primary, ghost/outline variants |
| Card surfaces | Remove MUI elevation, add hairline border + shadow-1 |
| `EmptyContent` | Redesign with Amaneh illustration language |
| `LoadingScreen` / `SplashScreen` | Update to Amaneh brand colors + mark |

**Estimated effort:** 3–4 days.

---

### Phase 2 — Auth Pages

**Goal:** Match the ClaudeDesign auth split-screen spec exactly.

Pages to update:
- `sign-in` — Split screen: dark side panel (ink-900 bg, saffron mark, serif headline, pull-quote) + form panel
- `sign-up` — Same split-screen structure, different side copy
- `reset-password` — Centered form, simplified
- `update-password` — Centered form
- `verify` — Centered with code input

**Key changes:**
- Dark side panel with paper-grain texture + saffron logo mark
- IBM Plex Mono for auth eyebrow text
- Saffron focus rings on inputs
- Telegram auth button styled distinctly (not identical to Google OAuth)

**Estimated effort:** 3 days.

---

### Phase 3 — Dashboard & Request Flow

**Goal:** The most-used screens — buyer/seller dashboard, request list, request detail, payment flow.

#### Dashboard Overview
- Metric tiles using `.metric` pattern (serif number, mono label)
- Escrow card list using new chip vocabulary
- Sidebar nav with Amaneh active states
- Topbar with IBM Plex Sans, compact search

#### Request List + Detail
- Table rows with new chip states
- `doc-chrome` corner-tick treatment on the escrow agreement card
- Timeline/activity feed using mono for timestamps, serif for headings
- Action buttons (Release, Dispute, Hold) using saffron primary / pomegranate destructive

#### Payment Flow
- Step indicators redesigned (saffron active step)
- Amount displays in IBM Plex Mono (tabular nums)
- Chain/network badges using Amaneh chip system

**Estimated effort:** 5–7 days.

---

### Phase 4 — Telegram Mini App Redesign

**Goal:** Make the Telegram experience feel native, not a shrunken dashboard.

#### New Telegram Layout System (`src/layouts/telegram/`)

```
TelegramLayout
├── TelegramHeader (title + ← back via WebApp.BackButton)
├── TelegramContent (full-width, scrollable, single-column)
├── TelegramBottomTabBar (4 tabs: Dashboard · Requests · Chat · Account)
└── TelegramMainButton (wrapper for WebApp.MainButton)
```

#### Component changes

| Current | Telegram Replacement |
|---|---|
| `Dialog` | `TelegramBottomSheet` (swipe-down to close) |
| Sidebar nav | `TelegramBottomTabBar` |
| MUI `Card` with padding | Full-bleed touch card (48px+ tap target) |
| Small status chips | Full-width status banner at top of screen when active |
| MUI `Button` primary | `Telegram.WebApp.MainButton` (native Telegram CTA) |
| 14px UI text | 16px minimum everywhere |

#### Theme token wiring

```css
/* Telegram theme bridge */
.telegram-context {
  --cream-50: var(--tg-theme-bg-color, #FBF6EB);
  --ink-900:  var(--tg-theme-text-color, #1C1410);
  --saffron-600: var(--tg-theme-button-color, #C2410C);
}
```

#### Pages to redesign in Telegram context
1. **Home** — 4-stat summary + active requests list (bottom tab: Dashboard)
2. **Requests** — Swipeable list with status chips (bottom tab: Requests)  
3. **Request Detail** — Document-style layout + MainButton for primary action
4. **Chat** — Near-native feel (bottom sheet for attachments)
5. **Account** — Settings list (bottom tab: Account)

**Estimated effort:** 5–6 days.

---

### Phase 5 — Remaining Pages

**Goal:** Apply the system uniformly to all remaining pages.

- Shop pages (public + seller) — warmer e-commerce surface
- Admin pages (networks, trezor, confirmations) — keep dense table layout, apply chip system
- Error pages (403, 404, 500) — Amaneh brand language
- Post/blog — serif display typography prominent
- Checkout (Request Network) — high-trust surface treatment

**Estimated effort:** 4–5 days.

---

## 6. Scope Boundaries

### In scope
- Full visual redesign of all pages
- New token layer (`amaneh-tokens.css`)
- MUI theme override updates
- New logo mark + wordmark
- Telegram Mini App layout system rebuild
- Status chip vocabulary standardization

### Out of scope
- No changes to API contracts or data models
- No changes to auth logic, payment logic, or blockchain interactions
- No component library extraction to separate package (future)
- No Storybook / design token docs tooling (future)

---

## 7. Risk Register

| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Font loading causes FOUT/CLS | Medium | High | `font-display: swap` + preconnect hints in `layout.tsx` |
| Saffron CTA conflicts with existing disabled state logic | Low | Medium | Audit all button disabled states in Phase 0 |
| `--tg-theme-*` vars unavailable outside Telegram | Low | Low | CSS var fallbacks already cover this |
| Persian serif (Gulzar) is heavy (3MB+) | High | Medium | Only load for display headings; fallback to Vazirmatn in body |
| Removing 5 color presets breaks user preferences in localStorage | Low | Low | Add migration: wipe `themeColorPreset` from settings on load |
| MUI DataGrid resists custom chip styling | Medium | Low | Use `renderCell` overrides for status columns |

---

## 8. Order of Execution Summary

```
Week 1  │ Phase 0: Token layer + theme config + fonts
        │ Phase 1: Core components (Logo, Chips, Buttons, Cards)
        │
Week 2  │ Phase 2: Auth pages
        │ Phase 3: Dashboard + Request + Payment (start)
        │
Week 3  │ Phase 3: (finish)
        │ Phase 4: Telegram Mini App rebuild
        │
Week 4  │ Phase 5: Remaining pages
        │ QA pass: RTL, dark mode, Telegram dark theme, mobile responsive
```

---

## 9. Definition of Done

- [ ] All 78 routes render with Amaneh palette (no teal `#00A76F` remaining)
- [ ] Status chips use the 7-state fixed vocabulary everywhere
- [ ] IBM Plex Mono is used for all monetary amounts and blockchain addresses
- [ ] Telegram Mini App has bottom tab bar, no sidebar, no MUI dialogs
- [ ] Telegram MainButton is wired for the primary action on each flow screen
- [ ] RTL (Persian) renders correctly with Vazirmatn for body and IBM Plex Mono for numbers
- [ ] No Google Fonts 5-preset switcher in Settings drawer
- [ ] Logo mark (SealMark) appears in nav, auth, and favicon
- [ ] Lighthouse CLS < 0.1 after font additions
- [ ] No accessibility regressions (color contrast AA minimum for all text/background pairs)