docs: add frontend redesign spec based on prototype analysis

2026-06-03 14:58:24 +08:00
parent 2080da87aa
commit 22ab39fed2
1 changed files with 186 additions and 0 deletions
--- a/docs/superpowers/specs/2026-06-03-frontend-redesign-design.md
+++ 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 `<html>`. 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 `<mark>` 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.