From 22ab39fed29d8fc6fb22d129f25cee3f680dce3e Mon Sep 17 00:00:00 2001 From: wangwei Date: Wed, 3 Jun 2026 14:58:24 +0800 Subject: [PATCH] docs: add frontend redesign spec based on prototype analysis --- .../2026-06-03-frontend-redesign-design.md | 186 ++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 docs/superpowers/specs/2026-06-03-frontend-redesign-design.md diff --git a/docs/superpowers/specs/2026-06-03-frontend-redesign-design.md b/docs/superpowers/specs/2026-06-03-frontend-redesign-design.md new file mode 100644 index 0000000..3f708be --- /dev/null +++ b/docs/superpowers/specs/2026-06-03-frontend-redesign-design.md @@ -0,0 +1,186 @@ +# Frontend Redesign — Design Spec +**Date:** 2026-06-03 +**Status:** Approved + +## Overview + +Complete replacement of the existing frontend UI layer, strictly following the HTML prototype designs in the `Prototype/` folder. The API layer (`api/`), mock data (`data/`), and TypeScript types (`types/`) are preserved unchanged. Only the UI layer is rewritten. + +## Design System + +### CSS Variables (Design Tokens) + +Defined in `frontend/src/styles/globals.css`, extracted directly from prototypes: + +```css +/* Sidebar (light rail) */ +--rail-bg: #ffffff +--rail-surface: #f7f8fa +--rail-fg: #111827 +--rail-muted: #8b929e +--rail-border: #e8eaed +--rail-hover: rgba(0,0,0,.04) +--rail-active: rgba(226,0,116,.07) + +/* Canvas */ +--bg: #f2f4f7 +--surface: #ffffff +--fg: #111827 +--muted: #6b7280 +--border: #e5e7eb + +/* Brand */ +--accent: #e20074 +--accent-dim: rgba(226,0,116,.10) +--accent-hover: #c8006a +--success: #16a34a +--warn: #d97706 +--danger: #dc2626 + +/* Typography */ +--font-display: "TeleNeoWeb-Bold", "Inter", -apple-system, sans-serif +--font-body: "TeleNeoWeb-Regular", "Inter", -apple-system, sans-serif +--font-mono: ui-monospace, "JetBrains Mono", Menlo, monospace + +/* Layout */ +--sidebar-w: 232px +--radius-sm: 6px +--radius-md: 10px +--radius-pill: 9999px +--shadow-card: 0 1px 4px rgba(0,0,0,.06), 0 0 0 1px rgba(0,0,0,.04) + +/* Dark mode: data-theme="dark" overrides all above */ +``` + +### Dark Mode +Toggle via `data-theme="dark"` on ``. Persisted to `localStorage`. Sidebar footer button triggers toggle. + +## Architecture + +### File Structure (UI layer only — rewrite) + +``` +frontend/src/ +├── styles/ +│ └── globals.css ← Rewrite: design tokens + base reset +├── components/ +│ └── layout/ +│ ├── AppShell.tsx ← Rewrite: CSS grid sidebar(232px) + content-area +│ ├── Sidebar.tsx ← New: brand + nav groups + user footer + theme toggle +│ └── Topbar.tsx ← New: sticky topbar (per-page title + actions) +├── pages/ +│ ├── Overview/ +│ │ └── OverviewPage.tsx ← New: launcher index +│ ├── Status/ +│ │ └── StatusPage.tsx ← Rewrite: system status dashboard +│ ├── Perception/ +│ │ ├── PerceptionPage.tsx ← Rewrite: regulatory signals +│ │ └── EventFeed.tsx ← Rewrite: feed pane +│ ├── Docs/ +│ │ └── DocsPage.tsx ← Rewrite: document management +│ ├── Compliance/ +│ │ └── CompliancePage.tsx ← Rewrite: compliance analysis workspace +│ └── RagChat/ +│ └── RagChatPage.tsx ← Rewrite: regulation Q&A chat +├── router/ +│ └── AppRouter.tsx ← Rewrite: 6 routes with sidebar layout +├── api/ ← PRESERVE unchanged +├── data/ ← PRESERVE unchanged +└── types/ ← PRESERVE unchanged +``` + +### Navigation (Sidebar) + +Permanent left sidebar, 232px wide. Groups: + +**Main** +- Overview (grid icon) +- Regulatory Signals (eye/radar icon) — badge: high-impact count +- System Status (list icon) — badge: active issues count + +**Workbench** +- Documents (file icon) +- Compliance Analysis (shield icon) + +**Chat** +- Regulation Q&A (chat bubble icon) + +Footer: user avatar (TS) + name/role + theme toggle button. + +Active item: accent-colored left border bar (3px) + accent background tint. + +## Pages + +### 1. Overview +- Hero section: title + subtitle + CTA buttons (Open dashboard, Jump to regulation chat) +- Summary card (scope: 6 screens / Backend-aware flows / Review posture) +- Workflow steps (6-column grid): 01 Dashboard → 06 Chat +- Screen grid (2×3): clickable cards with mini mockup previews + +### 2. System Status (`dashboard-sidebar.html`) +- **Topbar**: "System Status" title + search + "Export status" btn + "New upload" btn (primary) +- **Stats grid (4-col)**: Documents total / Vector chunks / High-impact signals / Last 90 days — values fetched from `/api/v1/perception/stats` +- **Panel grid (1.4fr + 0.9fr)**: + - Left: Workflow queue (task rows: name/status/progress/CTA) + Active compliance programs (program rows + KPI strip: Retrieval hit rate / Evidence coverage / Reviewer SLA with meter bars) + - Right: System health (service rows: name/status) + Regulatory watch (event rows: date/title/summary clamp-2) +- **Footer**: brand name + live green dot + "Online" + +### 3. Regulatory Signals (`perception.html`) +- **Topbar**: title + subtitle monospace + search + Refresh btn +- **Stats bar (4-col, flush, no card borders)**: Total / High impact (danger color) / Medium impact (warn color) / Last 90 days (accent color) — fetched from `/api/v1/perception/stats` +- **Filter bar**: Source chips (All/MIIT/UN-ECE/ISO/GB Comm./EUR-Lex/IATF) + separator + Impact chips (All/High/Medium/Low) +- **Two-pane split (360px + 1fr)**: + - Left feed pane: scrollable event cards (source tag colored, standard code, status pill, title, summary clamp-2, date, tags, impact dot). Selected card gets accent border + glow ring. + - Right analysis pane: empty state with ring icon. On select: detail card (source/code/status/title/summary/meta) + action row (Run impact analysis btn, Stop btn, Source link) + Affected documents card (doc rows: score%/name/clause/snippet) + AI output card (SSE streaming with blink cursor, markdown rendering) +- **Footer**: live dot + "Live feed" + brand + +### 4. Documents (`document-management.html`) +- **Topbar**: title + search + filter controls + "Upload document" primary btn +- **Filter bar**: status chips (All/Ready/Embedding/Failed/Pending) + regulation type filter +- **Document table**: rows with doc name, status pill (ok/warn/risk), upload time, chunk count, action CTAs (Inspect/Analyze/Resolve) +- Rows link to document detail view + +### 5. Compliance Analysis (`compliance-analysis.html`) +- **Topbar**: title + search + "New analysis" primary btn +- **Hero**: eyebrow + h1 + description + nav buttons +- **Three-column workspace (0.95fr + 1.25fr + 0.9fr)**: + - Col 1 — Retrieved regulations: source items (standard name, helper text, score pills, status pill) + - Col 2 — Document paragraph under review: source text block with `` highlights + Analysis stages (4 progress bars: Clause retrieval / Requirement extraction / Gap analysis / Recommendation synthesis) + - Col 3 — Findings and conclusion: finding items (title/description/status pill) + conclusion box (recommended replacement text) + action items (Next action / Escalation) + +### 6. Regulation Q&A (`regulation-chat.html`) +- **Two-column layout**: main chat area + right citation rail +- **Topbar**: chat title + export btn +- **Chat area**: message bubbles (user right/assistant left), streaming cursor blink, citation superscripts +- **Citation rail**: source doc rows (score/name/clause/snippet) +- **Input area**: textarea + quick-prompt chips + send button (primary) + +## Component Patterns + +### Status Pills +``` +.status.ok → green dot + green bg tint +.status.warn → amber dot + amber bg tint +.status.risk → red dot + red bg tint +.status.info → blue dot + blue bg tint +``` + +### Buttons +- Default: border + surface bg, 32px height +- Primary: accent bg, white text +- Small: 28px height + +### Cards +- `border-radius: 10px`, `box-shadow: var(--shadow-card)`, `padding: 16px 18px` + +### Nav badges +- Accent-tinted pill, monospace font, 10px + +## Preserved (No Changes) +- `frontend/src/api/` — all API client files +- `frontend/src/data/` — all mock data files +- `frontend/src/types/` — TypeScript definitions +- `frontend/src/contexts/ThemeContext.tsx` — theme state (adapt to use data-theme on html element) + +## Tech Stack +React 19 + TypeScript + Vite + TailwindCSS 4 + React Router 7. Lucide React for icons.