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

/* 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)