docs: add MailHub UI visual redesign design spec

Capture approved Modern SaaS direction, design tokens, shell layout,
shared presentation patterns, and page-level scope for the full UI refresh.

AI-Co-Authored-By: Grok

.gitignore

@@ -13,6 +13,7 @@ certs/*
 logs/
 tmp/
 .cache/
+.superpowers/
 docs/superpowers/
 node_modules/
 npm-debug.log*

docs/superpowers/specs/2026-07-09-mailhub-ui-redesign-design.md

@@ -0,0 +1,206 @@
+# MailHub UI Visual Redesign Design
+
+## Goal
+
+全面升级 MailHub 管理台与登录/注册页的视觉系统，使其从「默认 Ant Design 后台模板」提升为辨识度高的 Modern SaaS 控制台，同时**不改动后端 API、权限模型、业务状态机与核心信息架构**。
+
+## Confirmed Product Decisions
+
+| Decision | Choice |
+|----------|--------|
+| Scope | Full visual system redesign (theme + layout shell + component patterns + key pages) |
+| Auth pages | Included; same visual language as admin console |
+| Visual style | Modern SaaS — light canvas, indigo primary, airy product feel (Resend / Railway-like) |
+| Shell | Dark left sidebar (full text labels) + light top bar + content canvas |
+| Density | Comfortable — larger type, generous whitespace, breathable cards |
+| Implementation approach | Design system + shell upgrade on existing React + Ant Design v5 |
+| Dark mode | Out of scope for this redesign |
+
+## Non-Goals
+
+- New features, new routes, or new API endpoints
+- Replacing Ant Design / React / Vite stack
+- Full custom component library rebuild
+- Dark mode theme
+- Changing domain DNS workflow semantics, token lifecycle, or admin permissions
+- Rewriting analytics models or i18n message semantics (minor chrome strings only)
+
+## Architecture
+
+Continue the current React admin app (`src/frontend/`, `src/layouts/`, `src/pages/`, `src/components/`) built by Vite into `public/`. Visual upgrades land as:
+
+1. **Design tokens** — CSS custom properties + Ant Design `ConfigProvider` theme tokens
+2. **Shell redesign** — `AdminLayout` and auth shell (`AuthApp`)
+3. **Shared presentation components** — PageHeader, MetricCard, SectionCard, StatusPill, EmptyState, CodeBlock
+4. **Page restyles** — recompose existing page markup around the new patterns without changing data loading or handlers
+
+Business logic remains in existing model modules (`*-model.js`), `api.ts`, and page containers.
+
+```text
+ConfigProvider(theme tokens)
+  └── I18nProvider
+        ├── AuthApp (login/register/forgot/reset)  ← shared tokens
+        └── App
+              └── AdminLayout (sider + header + content)
+                    └── pages (Dashboard, Domains, …)
+                          └── shared presentation components
+```
+
+## Visual System (Tokens)
+
+### Color
+
+| Role | Value | Usage |
+|------|-------|-------|
+| Primary | `#4F46E5` | Primary buttons, links, active nav accent |
+| Primary hover | `#4338CA` | Hover / pressed primary |
+| Primary soft | `#EEF2FF` | Soft fills, selected chips |
+| Ink / Sider | `#0F172A` | Sidebar background, primary text |
+| Text secondary | `#64748B` | Labels, helper text |
+| Text muted | `#94A3B8` | Meta / placeholders |
+| Canvas | `#F4F6FB` | App background |
+| Surface | `#FFFFFF` | Cards, header, auth form card |
+| Border | `#E2E8F0` | Dividers, card borders |
+| Success | `#16A34A` (+ soft green bg) | Healthy / accepted |
+| Warning | `#D97706` (+ soft amber bg) | Pending / DNS issues |
+| Danger | `#DC2626` (+ soft red bg) | Failed / destructive |
+
+### Shape, Type, Space
+
+- **Radius:** controls `10px`, cards `14px`, pills `999px`
+- **Shadow:** light elevation — thin border + soft ambient (`0 1px 2px` + `0 8px 24px` slate-tinted)
+- **Spacing rhythm:** 8-based (`8 / 16 / 24 / 32`); content padding `24–32px`
+- **Type scale:** page title `22–24px`, metric value `28–32px`, body `14px`
+- **Font stack:** Inter, system-ui, -apple-system, Segoe UI, sans-serif
+
+### Ant Design Theme Mapping
+
+Map tokens into `ConfigProvider` at least for:
+
+- `colorPrimary`, `colorSuccess`, `colorWarning`, `colorError`
+- `colorBgLayout`, `colorBgContainer`, `colorBorderSecondary`, `colorText`, `colorTextSecondary`
+- `borderRadius`, `borderRadiusLG`
+- Component overrides for `Card`, `Table` (comfortable cell padding), `Button`, `Menu` (sider), `Tag` or custom StatusPill preference
+
+Default Ant blue `#1677ff` must not remain as brand primary.
+
+## Shell Design
+
+### AdminLayout
+
+- Sticky dark sider width **248px**, background ink `#0F172A`
+- Brand block: gradient MH mark + title `MailHub` + subtitle `Email Delivery`
+- Navigation **groups** (labels only; routes unchanged):
+  - **Overview** — Dashboard, Domains, DNS API
+  - **Delivery** — SMTP, API Tokens, Sending Logs, Webhooks
+  - **System** — Admin (admin role only), Settings
+- Active item: primary-soft indigo wash + light text (custom sider styles; avoid stock dark-menu look)
+- Header: white surface, border bottom, page title / breadcrumb, language select, refresh, primary CTA **Add domain**, user dropdown
+- Content: canvas background, comfortable padding
+- Responsive: below `lg`, collapse sider to drawer-style behavior (existing Ant Layout breakpoint pattern)
+- Optional light account summary at sider bottom is allowed; primary account actions stay in header dropdown
+
+### Auth (Login / Register / Forgot / Reset / Resend)
+
+- Same tokens as admin
+- Desktop split:
+  - **Left:** ink brand panel — logo, headline, short value prop, 2–3 capability signals
+  - **Right:** soft canvas/indigo wash + elevated white form card
+- Mobile: single column; brand panel compressed on top
+- Keep existing auth modes and API calls; restyle forms, alerts, segmented control, and spacing only
+
+## Shared Presentation Components
+
+| Component | Responsibility |
+|-----------|----------------|
+| `PageHeader` | Title, optional subtitle/description, right-side actions (one primary action per region) |
+| `MetricCard` | Label, large value, optional trend pill / soft icon tile |
+| `SectionCard` | Standard content card (14px radius, light shadow, consistent header/body padding) |
+| `StatusPill` | Semantic soft status chip (success / warning / error / info / neutral) |
+| `EmptyState` | Icon, message, optional primary CTA for empty lists/charts |
+| `CodeBlock` | Mono, wrap-safe long values (DNS/token samples) with copy affordance |
+
+Prefer placing these under `src/components/common/` (or equivalent) and reusing across pages. Existing `StatusTag` may be adapted into or replaced by `StatusPill` for visual consistency.
+
+## Key Page Treatments
+
+### Dashboard
+
+- Keep security alert (default admin password) at top when applicable
+- Condense metric strip from many flat cards to **~4 primary MetricCards** (e.g. today sent, success rate, verified domains, DNS issues). Secondary metrics fold into charts, lists, or tooltips rather than equal-weight cards
+- Chart row: trend + status distribution in SectionCards; recolor plots to token palette
+- Domain ranking / hourly charts retain structure with updated card chrome
+- Recent sends table inside SectionCard
+- No analytics model API changes
+
+### Domains list
+
+- PageHeader + toolbar (search, status filter, add domain)
+- Table inside SectionCard; domain name as emphasized link control
+- Status via StatusPill; comfortable row padding
+
+### Domain detail
+
+- Upgrade `DomainHealthCard` to a **hero block**: domain title, status pill, key stats, DNS progress, primary action stack (apply DNS / check / test / edit)
+- Tabs and two-column DNS records layout remain
+- DNS record cards use CodeBlock + StatusPill + consistent action buttons
+- No change to DNS apply/check/test flows
+
+### Other pages (SMTP, Tokens, Logs, DNS API, Settings, Admin, Webhooks placeholder)
+
+- Apply PageHeader + SectionCard + table/form spacing polish
+- Do not redesign information architecture or form field sets beyond visual hierarchy
+- Token create modal / secret-once warning keeps existing behavior with improved visual emphasis
+
+## Engineering Boundaries
+
+### In scope files (expected)
+
+- `src/frontend/App.tsx` — theme provider tokens
+- `src/frontend/styles.css` — CSS variables + shell/page styles
+- `src/frontend/auth/AuthApp.tsx` (+ auth-related styles)
+- `src/layouts/AdminLayout.tsx`
+- `src/components/common/*` (new or updated shared UI)
+- `src/components/domain/*` (visual structure only)
+- `src/pages/**` (composition / classNames / shared components; handlers stay)
+
+### Out of scope
+
+- `src/server.js`, `src/db.js`, mailer/submission/DNS provider logic
+- Model pure functions unless a pure presentation helper is needed
+- Docker / deploy scripts
+
+### i18n
+
+- Reuse existing keys for page meaning
+- May add short chrome keys (nav group labels, empty-state titles) in both locales already supported by the app
+
+### Testing & verification
+
+- Existing `npm test` suite must remain green (models, i18n, server APIs unchanged)
+- Add tests only if new pure helpers are introduced
+- Manual / build verification: `npm run build` (and UI smoke of login + dashboard + domain detail)
+
+## Delivery Order
+
+1. Design tokens (CSS vars + ConfigProvider)
+2. AdminLayout shell + nav groups
+3. Auth shell restyle
+4. Shared presentation components
+5. Dashboard
+6. Domains list + domain detail / health / DNS cards
+7. Remaining pages sweep
+8. Build + test gate
+
+## Success Criteria
+
+- Brand primary is indigo-based, not default Ant blue
+- Admin and auth feel like one product
+- Layout remains dark sidebar + comfortable density as approved
+- All existing navigation destinations and primary workflows remain reachable
+- No intentional API or auth behavior regressions
+- `npm test` and `npm run build` pass
+
+## Open Questions
+
+None blocking. Optional later (explicitly out of this spec): dark mode, illustration pack, custom icon set beyond `@ant-design/icons`.