audit: 2026-05-30 full-codebase audit — report, issues, docs, runbooks
Full-codebase-audit 2026-05-30 outputs: - Audit report: 09 - Audits/Full Codebase Audit - 2026-05-30.md - 81 issue files ISSUE-055..135 (decisions + 1 skipped no-brainer). - Scanner docs from scratch (was zero): architecture, data model, API ref, payment flow, operations runbook + repo README. - Doc-sync updates across API reference, data models, flows, design system. - Secret Rotation Runbook (08 - Operations) for the exposed credentials. - Reusable workflow guide (07 - Development) + .claude/workflows/full-codebase-audit.js. Issues remain status:open intentionally — the code fixes are uncommitted-then-committed working-tree changes per repo and aren't "resolved" until merged/deployed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Siavash Sameni
344
PRD - UI UX Overhaul (Amaneh Design System).md
Normal file
344
PRD - UI UX Overhaul (Amaneh Design System).md
Normal file
@@ -0,0 +1,344 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user