From a090c5cc2be95134fcd520f833f377a59b135cbf Mon Sep 17 00:00:00 2001
From: willxue <willxue@msn.com>
Date: Wed, 22 Apr 2026 06:29:57 +0800
Subject: [PATCH 1/5] docs: add design system v1 plan

Complete landing plan for WeMail Web design system v1.0 covering:
- Token foundation (color/space/radius/shadow/font/motion/z-index/focus/chart)
- 20 primitive components (15 new + 2 extended + 3 unchanged)
- Cross-cutting infrastructure (icon wrapper, a11y contract, test utils, reduced-motion, visual regression)
- 7-sprint implementation order with acceptance checklist
- Risk register and open decisions
---
 docs/plans/2026-04-22-design-system-v1.md | 428 ++++++++++++++++++++++
 1 file changed, 428 insertions(+)
 create mode 100644 docs/plans/2026-04-22-design-system-v1.md

diff --git a/docs/plans/2026-04-22-design-system-v1.md b/docs/plans/2026-04-22-design-system-v1.md
new file mode 100644
index 0000000..fc72eae
--- /dev/null
+++ b/docs/plans/2026-04-22-design-system-v1.md
@@ -0,0 +1,428 @@
+# WeMail Web 端 UI 设计系统 v1.0 落地方案
+
+- 日期：2026-04-22
+- 分支：`feature/design-system-v1`
+- 范围：仅 Web 端（`apps/web`），不含移动端与邮件模板
+- 目标：把分散在各 feature 的视觉/交互规范收敛为一套可复用、可测试、可演进的 design token + 原语组件库，并提供一个可导航的预览页
+
+---
+
+## 1. 背景与目标
+
+- 参考图列出了 13 个模块（色彩、布局、卡片、按钮、输入、标签、导航、开关、复选框、单选、进度、提示、阴影、圆角、间距）
+- 现有仓库已有 `shared/{button,form,table,switch,chart,overlay}` 原语与一套 CSS 变量，但缺 Tag、Badge、Breadcrumb、Pagination、Tabs、Steps、Progress、Alert、Card、Typography 等常用原语
+- 新功能 / 重构页面时，团队频繁复制粘贴样式片段，偏差累积
+- **本方案目标**：一次性补齐缺口，保持对现有代码的零破坏（通过别名 / 渐进迁移），并让后续页面"只用原语、不写业务 CSS"
+
+### 非目标（本期不做）
+- 移动端适配、邮件 HTML 模板、打印样式
+- 从 lucide-react 迁移到自有图标库
+- Storybook / Ladle 预览工具（用自建 `/_design` 路由替代）
+- i18n 接入（只做"提供可覆盖 prop"，不拉 i18n 库）
+
+---
+
+## 2. 现状盘点
+
+| 参考图模块 | 现有 | 缺口 |
+|---|---|---|
+| 色彩 | `--accent`、`--success-soft`、`--warning-soft`、中性 `--text/--text-muted/--text-soft` | 缺 `--success/--warning/--danger/--info` 主色梯度；缺中性灰 9 阶；缺品牌 9 阶 |
+| 圆角 | `--radius-shell/card/pill/field` | 缺系统化的 xs/sm/md/lg/xl 命名 |
+| 阴影 | `--shadow-soft/card/border` | 缺 xs/sm/md/lg/xl 梯度 |
+| 间距 | 无 token，散在各 css | 缺 4px 网格完整 `--space-*` |
+| 字号 | 浏览器默认 + 局部 clamp | 缺 display/title/body/caption 语义 token |
+| Button | `Button / ButtonLink / ButtonAnchor`（7 变体） | 需新增 xs icon-only 变体；可选新增 subtle 变体 |
+| 输入 | `TextInput / SelectInput / TextareaInput / FormField / CheckboxField / RadioGroupField` | 缺 `SearchInput`、独立 `Checkbox`/`Radio`、`MultiSelect` |
+| 表格 | 已有 `TableContainer / Table / ...` | OK |
+| Switch | 已有 | OK |
+| 卡片 | 只有 `.panel` 全局类 + 业务 css | 需 `Card / CardHeader / CardBody / CardFooter` |
+| 标签与状态 | 各页 inline chip | 需 `Tag`（分类）+ `Badge`（状态）两原语 |
+| 导航 | 局部 `workspace-pill-nav`、面包屑散落 | 需 `Breadcrumb / Pagination / Tabs / Steps` |
+| 进度 | 无 | `Progress` |
+| 提示 | `WemailToast`（飞出）/ 无静态 | `Alert`（页内静态） |
+| Overlay | `shared/overlay` 已有 | 需核对 Modal/Drawer/Dialog 一致 |
+| 排版 | `<h1><h2><p>`+ className | 需 `Heading / Text / Label / Muted` 排版原语 |
+
+---
+
+## 3. Design Tokens（新建 `apps/web/src/shared/styles/tokens.css`）
+
+### 3.1 颜色
+
+```css
+:root,
+:root[data-theme="light"] {
+  /* 品牌 — 保留 --accent=#ff7a00 作为 --brand-500 */
+  --brand-50:  #fff2e6;
+  --brand-100: #ffe0c2;
+  --brand-200: #ffc78a;
+  --brand-300: #ffa74d;
+  --brand-400: #ff8b26;
+  --brand-500: #ff7a00;
+  --brand-600: #e66d00;
+  --brand-700: #b35400;
+
+  /* 辅助橙 */
+  --brand-soft-500: #ffb366;
+
+  /* 语义色 */
+  --success-500: #22c55e;  --success-100: #d1fadf;  --success-600: #16a34a;  --success-soft: rgba(34,197,94,.14);
+  --warning-500: #f59e0b;  --warning-100: #fef0c7;  --warning-600: #d97706;  --warning-soft: rgba(245,158,11,.14);
+  --danger-500:  #ef4444;  --danger-100:  #fee2e2;  --danger-600:  #dc2626;  --danger-soft: rgba(239,68,68,.14);
+  --info-500:    #3b82f6;  --info-100:    #dbeafe;  --info-600:    #2563eb;  --info-soft:   rgba(59,130,246,.14);
+
+  /* 中性 9 阶 */
+  --neutral-0:  #ffffff;
+  --neutral-50: #f9fafb;
+  --neutral-100:#f3f4f6;
+  --neutral-200:#e5e7eb;
+  --neutral-300:#d1d5db;
+  --neutral-400:#9ca3af;
+  --neutral-500:#6b7280;   /* 图中"中性色" */
+  --neutral-700:#374151;
+  --neutral-900:#111827;
+
+  /* 兼容别名 — 保证现有 CSS 零回归 */
+  --accent: var(--brand-500);
+  --accent-strong: var(--brand-400);
+  --accent-soft: color-mix(in srgb, var(--brand-500) 14%, transparent);
+}
+
+:root[data-theme="dark"] { /* 同名重定义，保持语义色跨主题稳定 */ }
+```
+
+### 3.2 间距（4px 网格）
+```css
+--space-1:4;  --space-2:8;  --space-3:12; --space-4:16;
+--space-5:20; --space-6:24; --space-8:32; --space-10:40;
+--space-12:48;--space-14:56;--space-16:64;--space-18:72;
+--space-20:80;--space-24:96;--space-28:112;--space-32:128;
+```
+
+### 3.3 圆角
+```css
+--radius-xs:4px; --radius-sm:8px; --radius-md:12px;
+--radius-lg:16px; --radius-xl:24px; --radius-full:9999px;
+/* 现有别名重定向 */
+--radius-field: var(--radius-lg);
+--radius-card:  var(--radius-xl);
+--radius-pill:  var(--radius-full);
+```
+
+### 3.4 阴影
+```css
+--elevation-xs: 0 1px 2px rgba(17,17,17,.04);
+--elevation-sm: 0 2px 6px rgba(17,17,17,.06), 0 1px 2px rgba(17,17,17,.04);
+--elevation-md: 0 6px 16px rgba(17,17,17,.08), 0 2px 4px rgba(17,17,17,.04);
+--elevation-lg: 0 14px 32px rgba(17,17,17,.10), 0 4px 8px rgba(17,17,17,.04);
+--elevation-xl: 0 24px 64px rgba(17,17,17,.14), 0 8px 16px rgba(17,17,17,.06);
+```
+
+### 3.5 字号 / 行高语义
+```css
+--font-display-lg: 48px/1.1;
+--font-display-md: 32px/1.2;
+--font-title-lg:   24px/1.3;
+--font-title-md:   20px/1.35;
+--font-body-lg:    16px/1.55;
+--font-body-md:    14px/1.55;
+--font-caption:    12px/1.45;
+--font-mono:       13px/1.6;
+```
+
+### 3.6 Motion tokens（新增）
+```css
+--duration-instant: 80ms;
+--duration-fast:    150ms;
+--duration-base:    200ms;
+--duration-slow:    320ms;
+--duration-slower:  480ms;
+--ease-standard: cubic-bezier(0.25, 1, 0.5, 1);
+--ease-emphasized: cubic-bezier(0.2, 1, 0.3, 1);
+--ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
+```
+
+### 3.7 Z-index 分层（新增，收敛各处散落的 z 值）
+```css
+--z-base: 0;
+--z-raised: 1;
+--z-dropdown: 10;
+--z-sticky: 20;
+--z-fixed: 30;
+--z-overlay: 40;
+--z-modal: 50;
+--z-popover: 60;
+--z-toast: 70;
+--z-tooltip: 80;
+```
+
+### 3.8 Focus ring（新增）
+```css
+--focus-ring-width: 3px;
+--focus-ring-offset: 2px;
+--focus-ring-color: color-mix(in srgb, var(--brand-500) 30%, transparent);
+--focus-ring: 0 0 0 var(--focus-ring-width) var(--focus-ring-color);
+```
+
+### 3.9 Data viz 色板（供 `shared/chart/nivoTheme` 消费）
+```css
+--chart-series-1: var(--brand-500);
+--chart-series-2: var(--info-500);
+--chart-series-3: var(--success-500);
+--chart-series-4: var(--warning-500);
+--chart-series-5: var(--danger-500);
+--chart-series-6: #8b5cf6;
+--chart-series-7: #06b6d4;
+--chart-series-8: #ec4899;
+```
+
+---
+
+## 4. 横向基础设施
+
+### 4.1 Icon 规范（`shared/icon/README.md` + lint 约定）
+- 继续用 `lucide-react`，不引入自有图标库
+- 尺寸 token：14（caption）、16（inline body）、20（button）、24（section）
+- 颜色默认 `currentColor`，stroke-width 1.5
+- 规则：所有图标必须 `aria-hidden="true"` 或带 `aria-label`
+- 在 `shared/icon/Icon.tsx` 导出 `Icon`（统一 size + aria 包装），而非到处裸用 lucide
+
+### 4.2 A11y 契约（每个原语 README 强制字段）
+- role / ARIA attrs
+- 键盘导航（Tab / Enter / Space / Arrow / Esc）
+- 对比度（≥ 4.5:1 正文 / 3:1 大字或图形）
+- `prefers-reduced-motion` 兜底
+- 关键组件（Modal/Drawer/Popover）焦点陷阱 + 归还
+
+### 4.3 i18n 接入点
+- 不引入 i18n 库；原语的 `aria-label`、`loadingLabel`、`closeLabel` 等暴露成 prop，允许页面层替换
+- 默认值用中文（WeMail 默认语言）；禁止在原语内部硬编码需要翻译的动词
+
+### 4.4 测试工具（`apps/web/src/test/utils/`）
+- `renderWithTheme(ui, { theme })` — 挂载 `data-theme` 并等待样式就绪
+- `pressKey(el, key)` — 封装 fireEvent.keyDown/Up 的组合
+- `axeRun(container)` — 可选的 a11y 自动巡检（先留挂载点，不强求本期接）
+
+### 4.5 Reduced-motion 统一开关
+- 所有新原语的 transition 必须在 `@media (prefers-reduced-motion: reduce)` 下降级为 `none`
+- `base.css` 新增一条全局兜底：`*{ transition-duration: 0 !important }` 放 reduced-motion 媒体查询里（可被个别 opt-out）
+
+### 4.6 视觉回归（补丁，放最后一个 Sprint）
+- Playwright 跑 `/_design` 路由在 light/dark 两个主题下截图
+- 存到 `apps/web/tests/visual/__snapshots__/`，PR 校对
+
+---
+
+## 5. 组件清单
+
+> 命名：目录 `shared/<name>/`；文件 `<Name>Primitives.tsx + index.ts + README.md + test`；CSS 类 `ui-<name>-...`；状态 `is-<state>` + `data-state`。
+
+### A. 已有 · 零改动
+Table、Switch、Chart、Overlay（需内部核对 Modal/Drawer 完整性）
+
+### B. 已有 · 扩展
+
+#### B1. `shared/button`
+- 新增 size `xs` + `iconOnly` 组合（32×32）
+- 新增 `variant="subtle"`（灰底 hover tint，对应图中"次要按钮·默认"浅色态）
+- README 补 xs 尺寸、subtle 变体用法
+
+#### B2. `shared/form`
+- 新增 `SearchInput`（`leadingIcon` + 清除按钮）
+- 拆出独立 `Checkbox` / `Radio` 原子（当前只有 `CheckboxField`/`RadioGroupField` 组合）
+- 新增 `MultiSelect`（headless 下拉 + 内部用 Checkbox）
+
+### C. 新增原语
+
+| 组件 | 目录 | 核心 Props | 变体 | 状态 |
+|---|---|---|---|---|
+| Card | `shared/card` | variant / padding / elevation / tone | base / data / status / accent | hover / is-interactive |
+| Tag | `shared/tag` | variant / shape / size / dot / icon | neutral / brand / info / success / warning / danger | — |
+| Badge | `shared/badge` | variant / appearance / size | soft / solid | — |
+| Breadcrumb | `shared/breadcrumb` | separator | — | is-current |
+| Pagination | `shared/pagination` | total / pageSize / page / onChange / siblings | size sm/md | is-active / is-disabled |
+| Tabs | `shared/tabs` | value / onChange / variant | segmented / underline | is-selected / is-disabled |
+| Steps | `shared/steps` | current / items | horizontal / vertical | upcoming / active / completed / error |
+| Progress | `shared/progress` | value / max / variant / size / showLabel | linear（环形延后） | indeterminate |
+| Alert | `shared/alert` | variant / appearance / title / onClose | soft / outline | dismissible |
+| Typography | `shared/typography` | as / size / tone | Heading / Text / Label / Muted / Code / Kbd | — |
+| Divider | `shared/divider` | orientation / inset / dashed | horizontal / vertical | — |
+| Avatar | `shared/avatar` | src / alt / size / fallback | circle / square | is-loading |
+| EmptyState | `shared/empty-state` | icon / title / description / actions | default / error / no-access | — |
+| Skeleton | `shared/skeleton` | shape / width / height / rounded | rect / text / circle | is-animating |
+| Spinner | `shared/spinner` | size / tone | — | — |
+| Tooltip | `shared/tooltip` | content / placement / openDelay | — | open / closed |
+| Popover | `shared/popover` | trigger / content / placement | — | open / closed |
+| Kbd | `shared/typography` 子组件 | — | — | — |
+| CopyButton | `shared/copy-button` | value / onCopy / children | — | is-copied |
+| KVList | `shared/kv-list` | items / density | — | — |
+| ScrollArea | `shared/scroll-area` | maxHeight / direction | — | has-scroll |
+| PageLayout | `shared/page-layout` | `<Page>` `<PageHeader>` `<PageToolbar>` `<PageContent>` `<PageSidebar>` | — | — |
+| FilterBar | `shared/filter-bar` | fields 数组 | — | has-active-filters |
+
+### D. 合计
+- 新增 15 类（C1–C15），扩展 2 类（B1–B2），零动 3 类，总计 20 个原语
+- 所有原语统一：forwardRef + `cx()` + `data-state` + test 文件
+
+---
+
+## 6. 页面级抽象
+
+### 6.1 `PageLayout` 脚手架
+```tsx
+<Page>
+  <PageHeader
+    breadcrumb={<Breadcrumb>...</Breadcrumb>}
+    title="账号列表"
+    description="..."
+    actions={<Button>新建</Button>}
+  />
+  <PageToolbar>
+    <SearchInput />
+    <MultiSelect />
+    <Button variant="ghost">导出</Button>
+  </PageToolbar>
+  <PageContent>
+    <Card>...</Card>
+  </PageContent>
+</Page>
+```
+- 落地在 v1.1（本期只登记，不实施），避免一次性动太多页面
+
+### 6.2 FilterBar 抽象
+- 账号列表、邮件列表、发件箱、公告都有"搜索 + 状态 + 创建人 + 时间"的组合，抽出 `FilterBar`
+- props：`fields: Array<{ type: "search" | "select" | "date" | "toggle", label, ... }>`
+- 实现放 v1.1
+
+---
+
+## 7. 文件结构
+
+```
+apps/web/src/shared/
+  styles/
+    tokens.css             ← 新建（所有 token）
+    base.css               ← 抽出 reset / 全局排版（可选，为减轻 index.css）
+    index.css              ← 顶部 @import "./tokens.css" + "./base.css"
+  button/                  ← 扩展
+  form/                    ← 扩展
+  icon/                    ← 新增
+  typography/              ← 新增
+  card/                    ← 新增
+  tag/                     ← 新增
+  badge/                   ← 新增
+  breadcrumb/              ← 新增
+  pagination/              ← 新增
+  tabs/                    ← 新增
+  steps/                   ← 新增
+  progress/                ← 新增
+  alert/                   ← 新增
+  divider/                 ← 新增
+  avatar/                  ← 新增
+  empty-state/             ← 新增
+  skeleton/                ← 新增
+  spinner/                 ← 新增
+  tooltip/                 ← 新增
+  popover/                 ← 新增
+  copy-button/             ← 新增
+  kv-list/                 ← 新增
+  scroll-area/             ← 新增
+  table/ switch/ chart/ overlay/  ← 保持
+
+apps/web/src/pages/
+  DesignSystemPage.tsx     ← 新增，路由 /_design
+
+apps/web/src/test/utils/
+  renderWithTheme.ts       ← 新增
+  pressKey.ts              ← 新增
+
+apps/web/tests/visual/
+  design-system.spec.ts    ← 新增 Playwright 快照
+  __snapshots__/           ← 基线截图
+
+docs/
+  design-system/
+    README.md              ← 设计原则 + token 清单 + 组件索引
+    CHANGELOG.md           ← token / 原语变更日志
+  plans/
+    2026-04-22-design-system-v1.md   ← 本文档
+```
+
+---
+
+## 8. 实施顺序（7 个 Sprint）
+
+每个 Sprint 结束：`pnpm test:web && pnpm lint && pnpm typecheck && pnpm build` 必须全绿，已有页面视觉零回归。
+
+| # | Sprint | 内容 | 预估 |
+|---|---|---|---|
+| S1 | Token foundation | `tokens.css` + 兼容别名 + `base.css` 抽出 + `DesignSystemPage` 骨架路由（/_design）+ 测试 utils + `CHANGELOG.md` | 1 天 |
+| S2 | 排版与原子 | `typography / divider / spinner / skeleton / icon` + 单测 + 在预览页展示 | 1 天 |
+| S3 | 卡片与状态 | `card / tag / badge / empty-state` + 单测 + 账号列表接入 Badge | 1 天 |
+| S4 | 导航四件套 | `breadcrumb / pagination / tabs / steps` + 把 `.workspace-pill-nav` 与 `.landing-code-tab-switch` 迁入 `Tabs` | 1 天 |
+| S5 | 输入扩展 + 开关类 | `SearchInput / Checkbox / Radio / MultiSelect` + `progress / alert / copy-button / kv-list / avatar` | 1 天 |
+| S6 | 浮层补齐 | `tooltip / popover / scroll-area`；核对 `overlay/` 目录的 Modal/Drawer | 1 天 |
+| S7 | 文档 + 视觉回归 | 每原语 README 完整；`/_design` 预览完整化；Playwright 快照；`docs/design-system/README.md` 索引 | 1 天 |
+
+**每 Sprint 的提交约定**：
+- 每个原语独立 commit（feat: add shared/<name>…）
+- PR 合并前跑 `pnpm --filter web test` + 预览页截图对比
+
+---
+
+## 9. 验收清单
+
+- [ ] `tokens.css` 落地，现有 `--accent/--border/...` 继续可用（via 兼容别名），历史页面零视觉回归
+- [ ] 20 个原语全部就位（第 5 节表格）
+- [ ] 每原语 3 件套齐全：`*Primitives.tsx + index.ts + README.md`
+- [ ] 每原语单测覆盖：渲染 / 受控 / disabled / 变体 class / a11y role；≥80% 行覆盖
+- [ ] `/_design` 预览页展示所有变体与状态，按图中 13 分区对齐排版
+- [ ] `docs/design-system/README.md` 索引 + `CHANGELOG.md` 记录 token 变更
+- [ ] `pnpm test:web && lint && typecheck && build` 全绿
+- [ ] Playwright `/design-system` light + dark 快照基线提交
+- [ ] 至少 2 个既有页面接入新原语（账号列表 → Badge + Pagination，Landing 开发者段 → Tabs），前后截图对比入 PR
+- [ ] Reduced-motion 媒体查询在所有动画组件生效
+- [ ] 焦点环可见，Tab 键顺序合理
+
+---
+
+## 10. 风险与降级
+
+| 风险 | 影响 | 降级 |
+|---|---|---|
+| tokens 重定向导致旧 CSS 色偏 | 高 | 只新增变量 + 别名指回，不改旧变量；S1 结束做 diff 截图对比 |
+| Tabs 原语迁移改到 `workspace-pill-nav` 破坏现有 topbar | 中 | 保留旧类名作"外观 shim"，先让 Tabs 内部渲染相同 className；两周后废弃 |
+| `focus-visible` 样式与现有按钮冲突 | 低 | 新 focus-ring 变量只给新增组件使用；Button 等已有组件保留自身 focus 样式 |
+| 一次性新增 20 目录体量大，review 吃力 | 中 | 按 Sprint 拆 commit + PR；每组件独立评审单元 |
+| 视觉回归误报（字体/浏览器抗锯齿） | 中 | 截图生成设定 deviceScaleFactor=2 + 禁用动画；阈值允许 ≤1% 像素偏差 |
+| lucide-react 图标 tree-shaking 失败 | 低 | 通过 `Icon` 组件统一导入，便于将来替换 |
+
+---
+
+## 11. 待决策开放问题
+
+1. 预览页路径：`/_design` vs `/design-system` vs 仅 dev 环境可见？
+2. Dark 主题的阴影是否要独立一套（现 dark 只改 `--shadow-soft/card`）？建议 S1 统一重算
+3. `Card variant="data"` 的数值排版要不要用 `--font-mono`？参考图是等宽
+4. `Tabs.underline` 本期是否实现？现在只用到 segmented，建议延后
+5. `Skeleton` 要不要含 shimmer 动画？建议默认无动画，prop 开启
+6. `Tooltip` 用原生 `title` 属性 fallback 还是完全 JS 实现？建议完全 JS，title 仅作 SSR 兜底
+7. 是否顺带引入 `@radix-ui/react-*` 做 headless 基座（Popover/Tabs/Tooltip）？当前无第三方 UI 依赖，引入需 ADR。建议暂不，先自写；若 S6 成本高再换
+8. Visual regression 要不要在 CI 上强制？建议先跑但仅 warn，观察一周后转 block
+
+---
+
+## 12. 与现有规范的衔接
+
+- 架构约束：原语属 `apps/web/src/shared`，不跨依赖到 `features/*` 或 `pages/*`（见 `docs/code-standard.md`）
+- 测试策略：单测 + 预览页 + 视觉回归；E2E 由现有 Playwright 关键流程兜底（见 `docs/testing-strategy.md`）
+- 提交规范：feat/refactor/docs 前缀；每原语独立 commit；PR 体记录 before/after 截图
+- 一旦本方案 merge，后续页面若重复造轮子将在 code review 被拒
+
+---
+
+## 13. 下一步行动
+
+1. 本文档合并到 main 后（或批准后直接在分支内）开始 **S1 Token foundation**
+2. 每完成 Sprint，在 PR 描述附预览页截图 + 影响页清单
+3. 全部合并后，追写 ADR：`docs/adr/0003-design-system-v1.md` 记录本期决策

From d82f8caf5f62ef5e73a73ba466185ff0e63416b4 Mon Sep 17 00:00:00 2001
From: willxue <willxue@msn.com>
Date: Wed, 22 Apr 2026 06:47:43 +0800
Subject: [PATCH 2/5] feat(design-system): tokens foundation + test utils (S1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add additive design token layer (no existing variable is changed):
- apps/web/src/shared/styles/tokens.css — brand 9-stop, semantic
  (success/warning/danger/info), neutrals 9-stop, spacing 4px grid,
  radius xs-xl + full, elevation xs-xl, font semantic sizes/leading,
  motion durations + eases, z-index layers, focus-ring, chart series
- apps/web/src/shared/styles/primitives.css — empty barrel for S2-S6
  component CSS to append via @import
- apps/web/src/shared/styles/index.css — prepend @import of tokens +
  primitives; existing :root blocks untouched, zero visual regression
- apps/web/src/test/utils/{renderWithTheme,pressKey,index}.ts — shared
  test helpers consumed by subsequent sprint tests

See docs/plans/2026-04-22-design-system-v1.md §3–§4.
---
 apps/web/src/shared/styles/index.css       |   3 +
 apps/web/src/shared/styles/primitives.css  |  20 +++
 apps/web/src/shared/styles/tokens.css      | 177 +++++++++++++++++++++
 apps/web/src/test/utils/index.ts           |   2 +
 apps/web/src/test/utils/pressKey.ts        |  25 +++
 apps/web/src/test/utils/renderWithTheme.ts |  29 ++++
 6 files changed, 256 insertions(+)
 create mode 100644 apps/web/src/shared/styles/primitives.css
 create mode 100644 apps/web/src/shared/styles/tokens.css
 create mode 100644 apps/web/src/test/utils/index.ts
 create mode 100644 apps/web/src/test/utils/pressKey.ts
 create mode 100644 apps/web/src/test/utils/renderWithTheme.ts

diff --git a/apps/web/src/shared/styles/index.css b/apps/web/src/shared/styles/index.css
index 2d1281f..d610628 100644
--- a/apps/web/src/shared/styles/index.css
+++ b/apps/web/src/shared/styles/index.css
@@ -1,3 +1,6 @@
+@import "./tokens.css";
+@import "./primitives.css";
+
 :root {
   --font-sans: "Inter", ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
   --radius-shell: 34px;
diff --git a/apps/web/src/shared/styles/primitives.css b/apps/web/src/shared/styles/primitives.css
new file mode 100644
index 0000000..498b290
--- /dev/null
+++ b/apps/web/src/shared/styles/primitives.css
@@ -0,0 +1,20 @@
+/*
+ * WeMail primitive CSS barrel.
+ *
+ * Each primitive team appends a single line:
+ *   @import "../<name>/<name>.css";
+ * below, ordered roughly by sprint.
+ *
+ * See docs/plans/2026-04-22-design-system-v1.md §7.
+ *
+ * === S2 atoms (typography / divider / icon / spinner / skeleton) ===
+ *
+ * === S3 cards & status (card / tag / badge / empty-state) ===
+ *
+ * === S4 navigation (breadcrumb / pagination / tabs / steps) ===
+ *
+ * === S5 forms & feedback (SearchInput / Checkbox / Radio / MultiSelect /
+ *                          progress / alert / copy-button / kv-list / avatar) ===
+ *
+ * === S6 overlays (tooltip / popover / scroll-area) ===
+ */
diff --git a/apps/web/src/shared/styles/tokens.css b/apps/web/src/shared/styles/tokens.css
new file mode 100644
index 0000000..ec1bd14
--- /dev/null
+++ b/apps/web/src/shared/styles/tokens.css
@@ -0,0 +1,177 @@
+/*
+ * WeMail design system tokens — v1.0 (2026-04-22)
+ *
+ * Purpose: central source of truth for color / spacing / radius / shadow /
+ * font / motion / z-index / focus / chart tokens. Additive layer — this file
+ * only introduces NEW variables. The legacy :root blocks in index.css continue
+ * to own existing variables (--accent, --border, --shadow-card, etc.) so the
+ * current UI keeps rendering with zero regression while new primitives adopt
+ * the system below.
+ *
+ * Source: docs/plans/2026-04-22-design-system-v1.md §3
+ */
+
+:root {
+  /* ===== Spacing (4px grid) ===== */
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-5: 20px;
+  --space-6: 24px;
+  --space-8: 32px;
+  --space-10: 40px;
+  --space-12: 48px;
+  --space-14: 56px;
+  --space-16: 64px;
+  --space-18: 72px;
+  --space-20: 80px;
+  --space-24: 96px;
+  --space-28: 112px;
+  --space-32: 128px;
+
+  /* ===== Radius (new scale — legacy aliases remain in index.css) ===== */
+  --radius-xs: 4px;
+  --radius-sm: 8px;
+  --radius-md: 12px;
+  --radius-lg: 16px;
+  --radius-xl: 24px;
+  --radius-full: 9999px;
+
+  /* ===== Font — semantic sizes ===== */
+  --font-display-lg: 48px;
+  --font-display-md: 32px;
+  --font-title-lg: 24px;
+  --font-title-md: 20px;
+  --font-body-lg: 16px;
+  --font-body-md: 14px;
+  --font-caption: 12px;
+  --font-mono-size: 13px;
+  --font-mono: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+
+  --line-display: 1.1;
+  --line-title: 1.3;
+  --line-body: 1.55;
+  --line-caption: 1.45;
+  --line-mono: 1.6;
+
+  /* ===== Motion ===== */
+  --duration-instant: 80ms;
+  --duration-fast: 150ms;
+  --duration-base: 200ms;
+  --duration-slow: 320ms;
+  --duration-slower: 480ms;
+  --ease-standard: cubic-bezier(0.25, 1, 0.5, 1);
+  --ease-emphasized: cubic-bezier(0.2, 1, 0.3, 1);
+  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
+
+  /* ===== Z-index layering ===== */
+  --z-base: 0;
+  --z-raised: 1;
+  --z-dropdown: 10;
+  --z-sticky: 20;
+  --z-fixed: 30;
+  --z-overlay: 40;
+  --z-modal: 50;
+  --z-popover: 60;
+  --z-toast: 70;
+  --z-tooltip: 80;
+
+  /* ===== Focus ring geometry ===== */
+  --focus-ring-width: 3px;
+  --focus-ring-offset: 2px;
+}
+
+/* ===== Theme-dependent tokens — light ===== */
+:root,
+:root[data-theme="light"] {
+  /* Brand — 9 stops, --brand-500 equals the historical --accent */
+  --brand-50: #fff2e6;
+  --brand-100: #ffe0c2;
+  --brand-200: #ffc78a;
+  --brand-300: #ffa74d;
+  --brand-400: #ff8b26;
+  --brand-500: #ff7a00;
+  --brand-600: #e66d00;
+  --brand-700: #b35400;
+  --brand-soft-500: #ffb366;
+
+  /* Semantic — 500 / 100 / 600 / soft tint */
+  --success-500: #22c55e;
+  --success-100: #d1fadf;
+  --success-600: #16a34a;
+  --success-bg: rgba(34, 197, 94, 0.14);
+
+  --warning-500: #f59e0b;
+  --warning-100: #fef0c7;
+  --warning-600: #d97706;
+  --warning-bg: rgba(245, 158, 11, 0.14);
+
+  --danger-500: #ef4444;
+  --danger-100: #fee2e2;
+  --danger-600: #dc2626;
+  --danger-bg: rgba(239, 68, 68, 0.14);
+
+  --info-500: #3b82f6;
+  --info-100: #dbeafe;
+  --info-600: #2563eb;
+  --info-bg: rgba(59, 130, 246, 0.14);
+
+  /* Neutrals — 9 stops */
+  --neutral-0: #ffffff;
+  --neutral-50: #f9fafb;
+  --neutral-100: #f3f4f6;
+  --neutral-200: #e5e7eb;
+  --neutral-300: #d1d5db;
+  --neutral-400: #9ca3af;
+  --neutral-500: #6b7280;
+  --neutral-700: #374151;
+  --neutral-900: #111827;
+
+  /* Elevation */
+  --elevation-xs: 0 1px 2px rgba(17, 17, 17, 0.04);
+  --elevation-sm: 0 2px 6px rgba(17, 17, 17, 0.06), 0 1px 2px rgba(17, 17, 17, 0.04);
+  --elevation-md: 0 6px 16px rgba(17, 17, 17, 0.08), 0 2px 4px rgba(17, 17, 17, 0.04);
+  --elevation-lg: 0 14px 32px rgba(17, 17, 17, 0.1), 0 4px 8px rgba(17, 17, 17, 0.04);
+  --elevation-xl: 0 24px 64px rgba(17, 17, 17, 0.14), 0 8px 16px rgba(17, 17, 17, 0.06);
+
+  /* Focus ring color (alpha-mixed brand) */
+  --focus-ring-color: color-mix(in srgb, var(--brand-500) 30%, transparent);
+  --focus-ring: 0 0 0 var(--focus-ring-width) var(--focus-ring-color);
+
+  /* Chart series — 8 distinct hues */
+  --chart-series-1: var(--brand-500);
+  --chart-series-2: var(--info-500);
+  --chart-series-3: var(--success-500);
+  --chart-series-4: var(--warning-500);
+  --chart-series-5: var(--danger-500);
+  --chart-series-6: #8b5cf6;
+  --chart-series-7: #06b6d4;
+  --chart-series-8: #ec4899;
+}
+
+/* ===== Theme-dependent tokens — dark ===== */
+:root[data-theme="dark"] {
+  /* Brand kept unchanged — consistent accent across themes */
+
+  /* Neutrals inverted — light values for text on dark surfaces */
+  --neutral-0: #0a0a0a;
+  --neutral-50: #111113;
+  --neutral-100: #1a1a1d;
+  --neutral-200: #222227;
+  --neutral-300: #2e2e34;
+  --neutral-400: #6b7280;
+  --neutral-500: #9ca3af;
+  --neutral-700: #d1d5db;
+  --neutral-900: #f3f4f6;
+
+  /* Deeper shadows for dark surfaces */
+  --elevation-xs: 0 1px 2px rgba(0, 0, 0, 0.32);
+  --elevation-sm: 0 2px 6px rgba(0, 0, 0, 0.4), 0 1px 2px rgba(0, 0, 0, 0.28);
+  --elevation-md: 0 6px 16px rgba(0, 0, 0, 0.48), 0 2px 4px rgba(0, 0, 0, 0.32);
+  --elevation-lg: 0 14px 32px rgba(0, 0, 0, 0.55), 0 4px 8px rgba(0, 0, 0, 0.3);
+  --elevation-xl: 0 24px 64px rgba(0, 0, 0, 0.6), 0 8px 16px rgba(0, 0, 0, 0.4);
+
+  /* Focus ring slightly brighter in dark */
+  --focus-ring-color: color-mix(in srgb, var(--brand-500) 40%, transparent);
+}
diff --git a/apps/web/src/test/utils/index.ts b/apps/web/src/test/utils/index.ts
new file mode 100644
index 0000000..66b123a
--- /dev/null
+++ b/apps/web/src/test/utils/index.ts
@@ -0,0 +1,2 @@
+export { renderWithTheme, type SupportedTheme, type RenderWithThemeResult } from "./renderWithTheme";
+export { pressKey, type PressKeyOptions } from "./pressKey";
diff --git a/apps/web/src/test/utils/pressKey.ts b/apps/web/src/test/utils/pressKey.ts
new file mode 100644
index 0000000..f809869
--- /dev/null
+++ b/apps/web/src/test/utils/pressKey.ts
@@ -0,0 +1,25 @@
+import { fireEvent } from "@testing-library/react";
+
+export type PressKeyOptions = {
+  code?: string;
+  shiftKey?: boolean;
+  ctrlKey?: boolean;
+  altKey?: boolean;
+  metaKey?: boolean;
+};
+
+export function pressKey(element: Element, key: string, options: PressKeyOptions = {}) {
+  const init: KeyboardEventInit = {
+    key,
+    code: options.code ?? key,
+    shiftKey: options.shiftKey,
+    ctrlKey: options.ctrlKey,
+    altKey: options.altKey,
+    metaKey: options.metaKey,
+    bubbles: true,
+    cancelable: true
+  };
+
+  fireEvent.keyDown(element, init);
+  fireEvent.keyUp(element, init);
+}
diff --git a/apps/web/src/test/utils/renderWithTheme.ts b/apps/web/src/test/utils/renderWithTheme.ts
new file mode 100644
index 0000000..b5bdf43
--- /dev/null
+++ b/apps/web/src/test/utils/renderWithTheme.ts
@@ -0,0 +1,29 @@
+import { type ReactElement, type ReactNode } from "react";
+import { act, render, type RenderOptions, type RenderResult } from "@testing-library/react";
+
+export type SupportedTheme = "light" | "dark";
+
+type RenderWithThemeOptions = RenderOptions & {
+  theme?: SupportedTheme;
+};
+
+export type RenderWithThemeResult = RenderResult & {
+  setTheme: (next: SupportedTheme) => void;
+};
+
+export function renderWithTheme(
+  ui: ReactElement | ReactNode,
+  { theme = "light", ...rest }: RenderWithThemeOptions = {}
+): RenderWithThemeResult {
+  document.documentElement.dataset.theme = theme;
+
+  const result = render(ui as ReactElement, rest);
+
+  function setTheme(next: SupportedTheme) {
+    act(() => {
+      document.documentElement.dataset.theme = next;
+    });
+  }
+
+  return { ...result, setTheme };
+}

From a2adaa034083b6e57130a4e94eeb9ad9585d87e8 Mon Sep 17 00:00:00 2001
From: willxue <willxue@msn.com>
Date: Wed, 22 Apr 2026 06:47:57 +0800
Subject: [PATCH 3/5] feat(design-system): /design-system preview page (S1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Register a new workspace route that renders a skeleton preview of the
token system (principles, colors, spacing, radius, shadows, typography)
and a placeholder for component primitives coming in S2-S6.

- apps/web/src/pages/DesignSystemPage.tsx — functional preview with
  design-swatch / design-spacing-row / design-radius-grid / design-
  shadow-grid / design-typography-grid sections
- apps/web/src/app/AppRoutes.tsx — register /design-system route

Follow-up sprints will plug each primitive group into this page.
---
 apps/web/src/app/AppRoutes.tsx          |   2 +
 apps/web/src/pages/DesignSystemPage.tsx | 182 ++++++++++++++++++++++++
 2 files changed, 184 insertions(+)
 create mode 100644 apps/web/src/pages/DesignSystemPage.tsx

diff --git a/apps/web/src/app/AppRoutes.tsx b/apps/web/src/app/AppRoutes.tsx
index 201b517..c1e6b28 100644
--- a/apps/web/src/app/AppRoutes.tsx
+++ b/apps/web/src/app/AppRoutes.tsx
@@ -23,6 +23,7 @@ import { TelegramSettingsPage } from "../features/settings/TelegramSettingsPage"
 import { WebhookPage } from "../features/settings/WebhookPage";
 import { AnnouncementsPage } from "../pages/AnnouncementsPage";
 import { DashboardPage } from "../pages/DashboardPage";
+import { DesignSystemPage } from "../pages/DesignSystemPage";
 import { InboxPage } from "../pages/InboxPage";
 import { SystemSettingsPage } from "../pages/SystemSettingsPage";
 import { SystemProfilePage } from "../pages/SystemProfilePage";
@@ -233,6 +234,7 @@ export function AppRoutes({ session, inbox, selectedMessage, settings, admin, ap
       <Route path="/system/settings" element={systemSettingsPage} />
       <Route path="/system/profile" element={systemProfilePage} />
       <Route path="/system/about" element={<AboutPage />} />
+      <Route path="/design-system" element={<DesignSystemPage />} />
     </Routes>
   );
 }
diff --git a/apps/web/src/pages/DesignSystemPage.tsx b/apps/web/src/pages/DesignSystemPage.tsx
new file mode 100644
index 0000000..8466425
--- /dev/null
+++ b/apps/web/src/pages/DesignSystemPage.tsx
@@ -0,0 +1,182 @@
+import type { CSSProperties, ReactNode } from "react";
+
+type SwatchProps = {
+  name: string;
+  hex: string;
+  varName?: string;
+};
+
+function Swatch({ name, hex, varName }: SwatchProps) {
+  const style: CSSProperties = { background: hex };
+  return (
+    <div className="design-swatch">
+      <span aria-hidden="true" className="design-swatch-fill" style={style} />
+      <div className="design-swatch-meta">
+        <strong>{name}</strong>
+        <code>{hex.toUpperCase()}</code>
+        {varName ? <small>{varName}</small> : null}
+      </div>
+    </div>
+  );
+}
+
+type TokenRowProps = {
+  label: string;
+  value: ReactNode;
+  hint?: string;
+};
+
+function TokenRow({ label, value, hint }: TokenRowProps) {
+  return (
+    <div className="design-token-row">
+      <div className="design-token-sample">{value}</div>
+      <div className="design-token-meta">
+        <strong>{label}</strong>
+        {hint ? <small>{hint}</small> : null}
+      </div>
+    </div>
+  );
+}
+
+export function DesignSystemPage() {
+  return (
+    <main className="workspace-grid design-system-grid">
+      <section className="panel workspace-card page-panel design-system-panel">
+        <p className="panel-kicker">WeMail UI 系统 · v1.0</p>
+        <h2>WeMail 设计系统</h2>
+        <p className="section-copy">
+          一套简洁、现代、易用的界面规范。所有组件与样式均基于此页展示的设计原则、色彩、字号、间距、圆角与阴影
+          token 构建；新功能应优先从这里取用原语与变量,避免在业务层重造样式。
+        </p>
+      </section>
+
+      <section className="panel workspace-card page-panel design-system-panel">
+        <p className="panel-kicker">设计原则</p>
+        <h2>四个不变量</h2>
+        <div className="design-principle-grid">
+          <article>
+            <strong>简洁清晰</strong>
+            <span>减少视觉干扰,一屏只解决一件事。</span>
+          </article>
+          <article>
+            <strong>一致性</strong>
+            <span>相同操作使用相同组件与状态表达。</span>
+          </article>
+          <article>
+            <strong>易用性</strong>
+            <span>优先键盘可达与屏幕阅读器语义。</span>
+          </article>
+          <article>
+            <strong>可扩展</strong>
+            <span>原语遵守 forwardRef + className + state 约定,便于组合。</span>
+          </article>
+        </div>
+      </section>
+
+      <section className="panel workspace-card page-panel design-system-panel">
+        <p className="panel-kicker">色彩系统</p>
+        <h2>品牌与语义色</h2>
+        <div className="design-swatch-grid">
+          <Swatch name="主色" hex="#ff7a00" varName="--brand-500" />
+          <Swatch name="辅助色" hex="#ffb366" varName="--brand-soft-500" />
+          <Swatch name="成功色" hex="#22c55e" varName="--success-500" />
+          <Swatch name="警告色" hex="#f59e0b" varName="--warning-500" />
+          <Swatch name="错误色" hex="#ef4444" varName="--danger-500" />
+          <Swatch name="中性色" hex="#6b7280" varName="--neutral-500" />
+        </div>
+      </section>
+
+      <section className="panel workspace-card page-panel design-system-panel">
+        <p className="panel-kicker">间距系统</p>
+        <h2>4px 网格</h2>
+        <div className="design-spacing-row">
+          {[4, 8, 12, 16, 20, 24, 32, 40, 48, 56, 64, 72, 80, 96, 112, 128].map((value) => (
+            <div className="design-spacing-item" key={value}>
+              <span aria-hidden="true" className="design-spacing-bar" style={{ width: value }} />
+              <code>{value}</code>
+            </div>
+          ))}
+        </div>
+      </section>
+
+      <section className="panel workspace-card page-panel design-system-panel">
+        <p className="panel-kicker">圆角系统</p>
+        <h2>6 档梯度</h2>
+        <div className="design-radius-grid">
+          <TokenRow
+            label="xs · 4px"
+            value={<span className="design-radius-demo" style={{ borderRadius: 4 }} />}
+            hint="--radius-xs · 内嵌边框、标签边缘"
+          />
+          <TokenRow
+            label="sm · 8px"
+            value={<span className="design-radius-demo" style={{ borderRadius: 8 }} />}
+            hint="--radius-sm · 小按钮、输入内部"
+          />
+          <TokenRow
+            label="md · 12px"
+            value={<span className="design-radius-demo" style={{ borderRadius: 12 }} />}
+            hint="--radius-md · 一般按钮、标签页头部"
+          />
+          <TokenRow
+            label="lg · 16px"
+            value={<span className="design-radius-demo" style={{ borderRadius: 16 }} />}
+            hint="--radius-lg · 输入框、卡片内嵌"
+          />
+          <TokenRow
+            label="xl · 24px"
+            value={<span className="design-radius-demo" style={{ borderRadius: 24 }} />}
+            hint="--radius-xl · 卡片外壳"
+          />
+          <TokenRow
+            label="full · 9999px"
+            value={<span className="design-radius-demo" style={{ borderRadius: 9999 }} />}
+            hint="--radius-full · 头像、pill、switch 轨道"
+          />
+        </div>
+      </section>
+
+      <section className="panel workspace-card page-panel design-system-panel">
+        <p className="panel-kicker">阴影系统</p>
+        <h2>5 档层级</h2>
+        <div className="design-shadow-grid">
+          {[
+            { name: "xs", varName: "--elevation-xs" },
+            { name: "sm", varName: "--elevation-sm" },
+            { name: "md", varName: "--elevation-md" },
+            { name: "lg", varName: "--elevation-lg" },
+            { name: "xl", varName: "--elevation-xl" }
+          ].map(({ name, varName }) => (
+            <div className="design-shadow-card" key={name} style={{ boxShadow: `var(${varName})` }}>
+              <strong>{name}</strong>
+              <code>{varName}</code>
+            </div>
+          ))}
+        </div>
+      </section>
+
+      <section className="panel workspace-card page-panel design-system-panel">
+        <p className="panel-kicker">字号系统</p>
+        <h2>7 档语义字号</h2>
+        <div className="design-typography-grid">
+          <div style={{ fontSize: 48, lineHeight: 1.1 }}>显示大号 · 48/1.1</div>
+          <div style={{ fontSize: 32, lineHeight: 1.2 }}>显示中号 · 32/1.2</div>
+          <div style={{ fontSize: 24, lineHeight: 1.3 }}>标题大号 · 24/1.3</div>
+          <div style={{ fontSize: 20, lineHeight: 1.35 }}>标题中号 · 20/1.35</div>
+          <div style={{ fontSize: 16, lineHeight: 1.55 }}>正文大号 · 16/1.55</div>
+          <div style={{ fontSize: 14, lineHeight: 1.55 }}>正文中号 · 14/1.55</div>
+          <div style={{ fontSize: 12, lineHeight: 1.45 }}>辅助说明 · 12/1.45</div>
+        </div>
+      </section>
+
+      <section className="panel workspace-card page-panel design-system-panel">
+        <p className="panel-kicker">组件库</p>
+        <h2>原语预览</h2>
+        <p className="section-copy">
+          所有原语（Button / Form / Table / Switch / Tabs 等）将在后续 Sprint 陆续接入本页。目前可以查看各自仓库目录下的
+          README：<code>apps/web/src/shared/</code>。
+        </p>
+      </section>
+    </main>
+  );
+}

From 03ff4dcc990583763eddd583bbf3a2468d801c84 Mon Sep 17 00:00:00 2001
From: willxue <willxue@msn.com>
Date: Wed, 22 Apr 2026 06:47:57 +0800
Subject: [PATCH 4/5] docs(design-system): initial README and changelog (S1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- docs/design-system/README.md — scope, token quick-index, primitive
  roster with sprint ownership, a11y contract, preview entry point
- docs/design-system/CHANGELOG.md — Keep-a-Changelog format seeded with
  the S1 additions
---
 docs/design-system/CHANGELOG.md | 55 +++++++++++++++++++++++++++++
 docs/design-system/README.md    | 61 +++++++++++++++++++++++++++++++++
 2 files changed, 116 insertions(+)
 create mode 100644 docs/design-system/CHANGELOG.md
 create mode 100644 docs/design-system/README.md

diff --git a/docs/design-system/CHANGELOG.md b/docs/design-system/CHANGELOG.md
new file mode 100644
index 0000000..b44a371
--- /dev/null
+++ b/docs/design-system/CHANGELOG.md
@@ -0,0 +1,55 @@
+# Design System Changelog
+
+约定：格式参考 [Keep a Changelog](https://keepachangelog.com/)。日期使用 ISO 8601。版本号与设计系统独立演进。
+
+## [Unreleased]
+
+### Added — Sprint 1 Foundation (2026-04-22)
+
+- `apps/web/src/shared/styles/tokens.css` — 新增 token 层
+  - 品牌色 9 阶（`--brand-50 … 700`）+ 辅助橙（`--brand-soft-500`）
+  - 语义色（success / warning / danger / info）各含 500 / 100 / 600 + `-bg` soft 变体
+  - 中性色 9 阶（`--neutral-0 … 900`），dark 主题反转
+  - 间距 `--space-1 … --space-32`（4px 网格）
+  - 圆角 `--radius-xs/sm/md/lg/xl/full`（与旧 `--radius-shell/card/pill/field` 并存）
+  - 阴影 `--elevation-xs … xl`（与旧 `--shadow-*` 并存）
+  - 字号 `--font-display-lg/md`、`--font-title-lg/md`、`--font-body-lg/md`、`--font-caption`、`--font-mono-size` + 对应行高
+  - 动效 `--duration-instant/fast/base/slow/slower` + 三条 ease 曲线
+  - 层级 `--z-base … --z-tooltip` 共 10 档
+  - 焦点环 `--focus-ring-width/offset/color/ring`
+  - 图表色板 `--chart-series-1 … 8`
+- `apps/web/src/shared/styles/primitives.css` — 空 barrel,供 S2-S6 component 追加自己的 `@import`
+- `apps/web/src/shared/styles/index.css` — 顶部新增 `@import "./tokens.css"; @import "./primitives.css";`;旧内容全部保留
+- `apps/web/src/test/utils/renderWithTheme.ts` — 基于 `@testing-library/react` 的 `render` 包装,挂 `data-theme`,支持运行时切换
+- `apps/web/src/test/utils/pressKey.ts` — 键盘按键测试辅助,封装 `keyDown + keyUp`
+- `apps/web/src/test/utils/index.ts` — 桶式导出
+- `apps/web/src/pages/DesignSystemPage.tsx` — 路由 `/design-system`,展示 token 与原语的可视预览骨架
+- `apps/web/src/app/AppRoutes.tsx` — 注册 `/design-system` 路由
+- `docs/design-system/README.md` — 索引与 token 速查表
+
+### Changed
+- (无 — S1 为 additive 落地,不破坏既有样式)
+
+### Removed
+- (无)
+
+---
+
+## 模板（后续 Sprint 填写）
+
+```md
+### Added — Sprint N Name (YYYY-MM-DD)
+- ...
+
+### Changed
+- ...
+
+### Deprecated
+- ...
+
+### Removed
+- ...
+
+### Fixed
+- ...
+```
diff --git a/docs/design-system/README.md b/docs/design-system/README.md
new file mode 100644
index 0000000..068cda7
--- /dev/null
+++ b/docs/design-system/README.md
@@ -0,0 +1,61 @@
+# WeMail 设计系统
+
+参考 [`docs/plans/2026-04-22-design-system-v1.md`](../plans/2026-04-22-design-system-v1.md) 了解整体方案、实施节奏与验收清单。
+
+## 范围
+
+- 仅 Web 端（`apps/web`），暂不覆盖移动端与邮件模板
+- 附加式（additive）落地：不改动既有 CSS 变量与选择器,新 token 与原语独立存在；业务页在各自节奏下迁移
+
+## Token 快速索引
+
+所有 token 定义在 [`apps/web/src/shared/styles/tokens.css`](../../apps/web/src/shared/styles/tokens.css)，按类别分组：
+
+| 类别 | 变量前缀 | 说明 |
+|---|---|---|
+| 品牌 | `--brand-50 … --brand-700`、`--brand-soft-500` | 主色梯度,`--brand-500` 与旧 `--accent` 等值 |
+| 语义 | `--success-*`、`--warning-*`、`--danger-*`、`--info-*` | 各自 500 / 100 / 600 + soft 变体 |
+| 中性 | `--neutral-0 … --neutral-900` | 9 阶灰度;dark 模式镜像反转 |
+| 间距 | `--space-1 … --space-32` | 4px 网格 |
+| 圆角 | `--radius-xs/sm/md/lg/xl/full` | 6 档 |
+| 阴影 | `--elevation-xs/sm/md/lg/xl` | 5 档 |
+| 字号 | `--font-display-lg/md`、`--font-title-lg/md`、`--font-body-lg/md`、`--font-caption`、`--font-mono-size` | 语义字号 |
+| 行高 | `--line-display/title/body/caption/mono` | 与字号配套 |
+| 动效 | `--duration-instant/fast/base/slow/slower`、`--ease-standard/emphasized/in-out` | 统一过渡时长与曲线 |
+| 层级 | `--z-base/raised/dropdown/sticky/fixed/overlay/modal/popover/toast/tooltip` | z-index 语义层 |
+| 焦点 | `--focus-ring-width/offset/color/ring` | 统一键盘焦点环 |
+| 图表 | `--chart-series-1 … --chart-series-8` | Nivo 主题消费 |
+
+**兼容性**：旧变量 (`--accent` / `--border` / `--surface-*` / `--shadow-*` / `--radius-shell|card|pill|field`) 仍保留原值在 `index.css`，新旧并行、零回归。
+
+## 组件清单
+
+| 名称 | 目录 | 状态 |
+|---|---|---|
+| Button / ButtonLink / ButtonAnchor | `shared/button` | ✅ 已有 |
+| TextInput / SelectInput / TextareaInput / CheckboxField / RadioGroupField / FormField | `shared/form` | ✅ 已有 |
+| Table 全家桶 | `shared/table` | ✅ 已有 |
+| Switch | `shared/switch` | ✅ 已有 |
+| Chart（Nivo 主题） | `shared/chart` | ✅ 已有 |
+| Overlay（Modal/Drawer） | `shared/overlay` | ✅ 已有（S6 复核） |
+| Typography / Divider / Icon / Spinner / Skeleton | `shared/{typography,divider,icon,spinner,skeleton}` | 🕐 S2 |
+| Card / Tag / Badge / EmptyState | `shared/{card,tag,badge,empty-state}` | 🕐 S3 |
+| Breadcrumb / Pagination / Tabs / Steps | `shared/{breadcrumb,pagination,tabs,steps}` | 🕐 S4 |
+| SearchInput / Checkbox / Radio / MultiSelect / Progress / Alert / CopyButton / KVList / Avatar | `shared/…` | 🕐 S5 |
+| Tooltip / Popover / ScrollArea | `shared/{tooltip,popover,scroll-area}` | 🕐 S6 |
+
+## A11y 契约（所有原语必须满足）
+
+- role / ARIA attrs 明确
+- 键盘可达 (Tab / Enter / Space / Arrow / Esc)
+- 对比度 ≥ 4.5:1 (正文) / 3:1 (大字或图形)
+- `prefers-reduced-motion` 下降级动画
+- Modal / Drawer / Popover 焦点陷阱 + 归还
+
+## 预览
+
+开发服务器启动后访问 `/design-system` 查看当前 token 与原语的可视预览。
+
+## 变更记录
+
+每次 token / 原语变更写入 [`CHANGELOG.md`](./CHANGELOG.md)。

From 32ebe6dabdfa15c5bb5ed17428853749925596d3 Mon Sep 17 00:00:00 2001
From: willxue <willxue@msn.com>
Date: Thu, 14 May 2026 22:38:56 +0800
Subject: [PATCH 5/5] update

---
 .gitignore                                    |    4 +-
 apps/web/e2e/README.md                        |    3 +
 apps/web/e2e/design-system.spec.ts            |   54 +
 apps/web/src/app/App.tsx                      |   11 +
 apps/web/src/app/AppLayout.tsx                |   44 +-
 apps/web/src/app/AppRoutes.tsx                |    2 -
 .../features/accounts/AccountsListPage.tsx    |  219 ++--
 .../features/landing/PublicSiteNavigation.tsx |  194 +++
 .../features/landing/WemailLandingPage.tsx    |  258 ++--
 apps/web/src/features/landing/landing.css     |  124 +-
 .../src/features/outbound/OutboundPage.tsx    |   95 +-
 .../web/src/features/settings/ApiKeysPage.tsx |   69 +-
 apps/web/src/pages/DashboardPage.tsx          |   18 +-
 apps/web/src/pages/DesignSystemPage.tsx       |  332 +++--
 apps/web/src/pages/SystemProfilePage.tsx      |   55 +-
 .../web/src/pages/UsersGlobalSettingsPage.tsx |   21 +-
 apps/web/src/pages/UsersListPage.tsx          |  250 ++--
 .../design-system/DesignSystemDocContent.tsx  |  161 +++
 .../DesignSystemPreviewContent.tsx            |  143 +++
 .../design-system/designSystemContent.ts      | 1098 +++++++++++++++++
 .../designSystemPreviewParts.tsx              |  131 ++
 .../design-system/designSystemSections.tsx    |  820 ++++++++++++
 .../pages/design-system/designSystemStyles.ts |  253 ++++
 apps/web/src/shared/README.md                 |   12 +-
 apps/web/src/shared/alert/AlertPrimitives.tsx |   70 ++
 apps/web/src/shared/alert/README.md           |   18 +
 apps/web/src/shared/alert/alert.css           |   65 +
 apps/web/src/shared/alert/index.ts            |    1 +
 .../src/shared/avatar/AvatarPrimitives.tsx    |   65 +
 apps/web/src/shared/avatar/README.md          |   18 +
 apps/web/src/shared/avatar/avatar.css         |   60 +
 apps/web/src/shared/avatar/index.ts           |    1 +
 apps/web/src/shared/badge/BadgePrimitives.tsx |   43 +
 apps/web/src/shared/badge/README.md           |   26 +
 apps/web/src/shared/badge/badge.css           |   88 ++
 apps/web/src/shared/badge/index.ts            |    1 +
 .../breadcrumb/BreadcrumbPrimitives.tsx       |   87 ++
 apps/web/src/shared/breadcrumb/README.md      |   27 +
 apps/web/src/shared/breadcrumb/breadcrumb.css |   40 +
 apps/web/src/shared/breadcrumb/index.ts       |    8 +
 .../src/shared/button/ButtonPrimitives.tsx    |    2 +-
 apps/web/src/shared/card/CardPrimitives.tsx   |   73 ++
 apps/web/src/shared/card/README.md            |   29 +
 apps/web/src/shared/card/card.css             |  163 +++
 apps/web/src/shared/card/index.ts             |    1 +
 .../copy-button/CopyButtonPrimitives.tsx      |   95 ++
 apps/web/src/shared/copy-button/README.md     |   17 +
 .../src/shared/copy-button/copy-button.css    |   33 +
 apps/web/src/shared/copy-button/index.ts      |    1 +
 .../src/shared/divider/DividerPrimitives.tsx  |   47 +
 apps/web/src/shared/divider/README.md         |   18 +
 apps/web/src/shared/divider/divider.css       |   57 +
 apps/web/src/shared/divider/index.ts          |    1 +
 .../empty-state/EmptyStatePrimitives.tsx      |   63 +
 apps/web/src/shared/empty-state/README.md     |   27 +
 .../src/shared/empty-state/empty-state.css    |   76 ++
 apps/web/src/shared/empty-state/index.ts      |    1 +
 .../shared/filter-bar/FilterBarPrimitives.tsx |   38 +
 apps/web/src/shared/filter-bar/README.md      |   20 +
 apps/web/src/shared/filter-bar/filter-bar.css |   41 +
 apps/web/src/shared/filter-bar/index.ts       |    1 +
 apps/web/src/shared/form/FormPrimitives.tsx   |  476 ++++++-
 apps/web/src/shared/form/README.md            |   16 +-
 apps/web/src/shared/form/form.css             |  161 +++
 apps/web/src/shared/form/index.ts             |    4 +
 apps/web/src/shared/icon/IconPrimitives.tsx   |   58 +
 apps/web/src/shared/icon/README.md            |   18 +
 apps/web/src/shared/icon/icon.css             |   52 +
 apps/web/src/shared/icon/index.ts             |    1 +
 .../src/shared/kv-list/KVListPrimitives.tsx   |   46 +
 apps/web/src/shared/kv-list/README.md         |   13 +
 apps/web/src/shared/kv-list/index.ts          |    1 +
 apps/web/src/shared/kv-list/kv-list.css       |   40 +
 .../metric-card/MetricCardPrimitives.tsx      |   47 +
 apps/web/src/shared/metric-card/README.md     |   18 +
 apps/web/src/shared/metric-card/index.ts      |    1 +
 .../src/shared/metric-card/metric-card.css    |   37 +
 .../src/shared/overlay/OverlayPrimitives.tsx  |  113 +-
 apps/web/src/shared/overlay/README.md         |    4 +
 apps/web/src/shared/overlay/layer-utils.ts    |  233 ++++
 .../page-layout/PageLayoutPrimitives.tsx      |   80 ++
 apps/web/src/shared/page-layout/README.md     |   23 +
 apps/web/src/shared/page-layout/index.ts      |    1 +
 .../src/shared/page-layout/page-layout.css    |   63 +
 .../pagination/PaginationPrimitives.tsx       |  226 ++++
 apps/web/src/shared/pagination/README.md      |   26 +
 apps/web/src/shared/pagination/index.ts       |    1 +
 apps/web/src/shared/pagination/pagination.css |   45 +
 .../src/shared/popover/PopoverPrimitives.tsx  |  220 ++++
 apps/web/src/shared/popover/README.md         |   21 +
 apps/web/src/shared/popover/index.ts          |    1 +
 apps/web/src/shared/popover/popover.css       |   48 +
 .../shared/progress/ProgressPrimitives.tsx    |   63 +
 apps/web/src/shared/progress/README.md        |   18 +
 apps/web/src/shared/progress/index.ts         |    1 +
 apps/web/src/shared/progress/progress.css     |   77 ++
 apps/web/src/shared/scroll-area/README.md     |   20 +
 .../scroll-area/ScrollAreaPrimitives.tsx      |   70 ++
 apps/web/src/shared/scroll-area/index.ts      |    6 +
 .../src/shared/scroll-area/scroll-area.css    |   39 +
 apps/web/src/shared/skeleton/README.md        |   19 +
 .../shared/skeleton/SkeletonPrimitives.tsx    |   70 ++
 apps/web/src/shared/skeleton/index.ts         |    1 +
 apps/web/src/shared/skeleton/skeleton.css     |   72 ++
 apps/web/src/shared/spinner/README.md         |   19 +
 .../src/shared/spinner/SpinnerPrimitives.tsx  |   45 +
 apps/web/src/shared/spinner/index.ts          |    1 +
 apps/web/src/shared/spinner/spinner.css       |   74 ++
 apps/web/src/shared/steps/README.md           |   28 +
 apps/web/src/shared/steps/StepsPrimitives.tsx |  191 +++
 apps/web/src/shared/steps/index.ts            |    1 +
 apps/web/src/shared/steps/steps.css           |   66 +
 apps/web/src/shared/styles/README.md          |    3 +
 apps/web/src/shared/styles/base.css           |   60 +
 apps/web/src/shared/styles/index.css          |   81 +-
 apps/web/src/shared/styles/primitives.css     |   51 +
 apps/web/src/shared/styles/tokens.css         |   12 +-
 apps/web/src/shared/tabs/README.md            |   30 +
 apps/web/src/shared/tabs/TabsPrimitives.tsx   |  243 ++++
 apps/web/src/shared/tabs/index.ts             |    1 +
 apps/web/src/shared/tabs/tabs.css             |   54 +
 apps/web/src/shared/tag/README.md             |   26 +
 apps/web/src/shared/tag/TagPrimitives.tsx     |   51 +
 apps/web/src/shared/tag/index.ts              |    1 +
 apps/web/src/shared/tag/tag.css               |   92 ++
 apps/web/src/shared/tooltip/README.md         |   21 +
 .../src/shared/tooltip/TooltipPrimitives.tsx  |  243 ++++
 apps/web/src/shared/tooltip/index.ts          |    1 +
 apps/web/src/shared/tooltip/tooltip.css       |   39 +
 apps/web/src/shared/typography/README.md      |   24 +
 .../typography/TypographyPrimitives.tsx       |  126 ++
 apps/web/src/shared/typography/index.ts       |    1 +
 apps/web/src/shared/typography/typography.css |  132 ++
 apps/web/src/test/app.test.tsx                |  206 +++-
 apps/web/src/test/design-system-page.test.tsx |  259 ++++
 apps/web/src/test/shared-alert.test.tsx       |   32 +
 apps/web/src/test/shared-avatar.test.tsx      |   28 +
 apps/web/src/test/shared-badge.test.tsx       |   32 +
 apps/web/src/test/shared-breadcrumb.test.tsx  |   45 +
 apps/web/src/test/shared-button.test.tsx      |    4 +
 apps/web/src/test/shared-card.test.tsx        |   46 +
 apps/web/src/test/shared-copy-button.test.tsx |   53 +
 apps/web/src/test/shared-divider.test.tsx     |   35 +
 apps/web/src/test/shared-empty-state.test.tsx |   40 +
 apps/web/src/test/shared-filter-bar.test.tsx  |   40 +
 apps/web/src/test/shared-form.test.tsx        |  159 ++-
 apps/web/src/test/shared-icon.test.tsx        |   30 +
 apps/web/src/test/shared-kv-list.test.tsx     |   24 +
 apps/web/src/test/shared-metric-card.test.tsx |   22 +
 apps/web/src/test/shared-overlay.test.tsx     |   53 +-
 apps/web/src/test/shared-page-layout.test.tsx |   47 +
 apps/web/src/test/shared-pagination.test.tsx  |   61 +
 apps/web/src/test/shared-popover.test.tsx     |   94 ++
 apps/web/src/test/shared-progress.test.tsx    |   23 +
 apps/web/src/test/shared-scroll-area.test.tsx |   37 +
 apps/web/src/test/shared-skeleton.test.tsx    |   32 +
 apps/web/src/test/shared-spinner.test.tsx     |   34 +
 apps/web/src/test/shared-steps.test.tsx       |   82 ++
 apps/web/src/test/shared-tabs.test.tsx        |   90 ++
 apps/web/src/test/shared-tag.test.tsx         |   32 +
 apps/web/src/test/shared-tooltip.test.tsx     |   69 ++
 apps/web/src/test/shared-typography.test.tsx  |   49 +
 apps/web/src/test/users-list-page.test.tsx    |    6 +-
 docs/design-system/CHANGELOG.md               |   60 +-
 docs/design-system/README.md                  |   82 +-
 ...design-system-component-docsite-sidebar.md |  434 +++++++
 ...026-04-25-design-system-docsite-upgrade.md |  402 ++++++
 167 files changed, 11914 insertions(+), 888 deletions(-)
 create mode 100644 apps/web/e2e/design-system.spec.ts
 create mode 100644 apps/web/src/features/landing/PublicSiteNavigation.tsx
 create mode 100644 apps/web/src/pages/design-system/DesignSystemDocContent.tsx
 create mode 100644 apps/web/src/pages/design-system/DesignSystemPreviewContent.tsx
 create mode 100644 apps/web/src/pages/design-system/designSystemContent.ts
 create mode 100644 apps/web/src/pages/design-system/designSystemPreviewParts.tsx
 create mode 100644 apps/web/src/pages/design-system/designSystemSections.tsx
 create mode 100644 apps/web/src/pages/design-system/designSystemStyles.ts
 create mode 100644 apps/web/src/shared/alert/AlertPrimitives.tsx
 create mode 100644 apps/web/src/shared/alert/README.md
 create mode 100644 apps/web/src/shared/alert/alert.css
 create mode 100644 apps/web/src/shared/alert/index.ts
 create mode 100644 apps/web/src/shared/avatar/AvatarPrimitives.tsx
 create mode 100644 apps/web/src/shared/avatar/README.md
 create mode 100644 apps/web/src/shared/avatar/avatar.css
 create mode 100644 apps/web/src/shared/avatar/index.ts
 create mode 100644 apps/web/src/shared/badge/BadgePrimitives.tsx
 create mode 100644 apps/web/src/shared/badge/README.md
 create mode 100644 apps/web/src/shared/badge/badge.css
 create mode 100644 apps/web/src/shared/badge/index.ts
 create mode 100644 apps/web/src/shared/breadcrumb/BreadcrumbPrimitives.tsx
 create mode 100644 apps/web/src/shared/breadcrumb/README.md
 create mode 100644 apps/web/src/shared/breadcrumb/breadcrumb.css
 create mode 100644 apps/web/src/shared/breadcrumb/index.ts
 create mode 100644 apps/web/src/shared/card/CardPrimitives.tsx
 create mode 100644 apps/web/src/shared/card/README.md
 create mode 100644 apps/web/src/shared/card/card.css
 create mode 100644 apps/web/src/shared/card/index.ts
 create mode 100644 apps/web/src/shared/copy-button/CopyButtonPrimitives.tsx
 create mode 100644 apps/web/src/shared/copy-button/README.md
 create mode 100644 apps/web/src/shared/copy-button/copy-button.css
 create mode 100644 apps/web/src/shared/copy-button/index.ts
 create mode 100644 apps/web/src/shared/divider/DividerPrimitives.tsx
 create mode 100644 apps/web/src/shared/divider/README.md
 create mode 100644 apps/web/src/shared/divider/divider.css
 create mode 100644 apps/web/src/shared/divider/index.ts
 create mode 100644 apps/web/src/shared/empty-state/EmptyStatePrimitives.tsx
 create mode 100644 apps/web/src/shared/empty-state/README.md
 create mode 100644 apps/web/src/shared/empty-state/empty-state.css
 create mode 100644 apps/web/src/shared/empty-state/index.ts
 create mode 100644 apps/web/src/shared/filter-bar/FilterBarPrimitives.tsx
 create mode 100644 apps/web/src/shared/filter-bar/README.md
 create mode 100644 apps/web/src/shared/filter-bar/filter-bar.css
 create mode 100644 apps/web/src/shared/filter-bar/index.ts
 create mode 100644 apps/web/src/shared/form/form.css
 create mode 100644 apps/web/src/shared/icon/IconPrimitives.tsx
 create mode 100644 apps/web/src/shared/icon/README.md
 create mode 100644 apps/web/src/shared/icon/icon.css
 create mode 100644 apps/web/src/shared/icon/index.ts
 create mode 100644 apps/web/src/shared/kv-list/KVListPrimitives.tsx
 create mode 100644 apps/web/src/shared/kv-list/README.md
 create mode 100644 apps/web/src/shared/kv-list/index.ts
 create mode 100644 apps/web/src/shared/kv-list/kv-list.css
 create mode 100644 apps/web/src/shared/metric-card/MetricCardPrimitives.tsx
 create mode 100644 apps/web/src/shared/metric-card/README.md
 create mode 100644 apps/web/src/shared/metric-card/index.ts
 create mode 100644 apps/web/src/shared/metric-card/metric-card.css
 create mode 100644 apps/web/src/shared/overlay/layer-utils.ts
 create mode 100644 apps/web/src/shared/page-layout/PageLayoutPrimitives.tsx
 create mode 100644 apps/web/src/shared/page-layout/README.md
 create mode 100644 apps/web/src/shared/page-layout/index.ts
 create mode 100644 apps/web/src/shared/page-layout/page-layout.css
 create mode 100644 apps/web/src/shared/pagination/PaginationPrimitives.tsx
 create mode 100644 apps/web/src/shared/pagination/README.md
 create mode 100644 apps/web/src/shared/pagination/index.ts
 create mode 100644 apps/web/src/shared/pagination/pagination.css
 create mode 100644 apps/web/src/shared/popover/PopoverPrimitives.tsx
 create mode 100644 apps/web/src/shared/popover/README.md
 create mode 100644 apps/web/src/shared/popover/index.ts
 create mode 100644 apps/web/src/shared/popover/popover.css
 create mode 100644 apps/web/src/shared/progress/ProgressPrimitives.tsx
 create mode 100644 apps/web/src/shared/progress/README.md
 create mode 100644 apps/web/src/shared/progress/index.ts
 create mode 100644 apps/web/src/shared/progress/progress.css
 create mode 100644 apps/web/src/shared/scroll-area/README.md
 create mode 100644 apps/web/src/shared/scroll-area/ScrollAreaPrimitives.tsx
 create mode 100644 apps/web/src/shared/scroll-area/index.ts
 create mode 100644 apps/web/src/shared/scroll-area/scroll-area.css
 create mode 100644 apps/web/src/shared/skeleton/README.md
 create mode 100644 apps/web/src/shared/skeleton/SkeletonPrimitives.tsx
 create mode 100644 apps/web/src/shared/skeleton/index.ts
 create mode 100644 apps/web/src/shared/skeleton/skeleton.css
 create mode 100644 apps/web/src/shared/spinner/README.md
 create mode 100644 apps/web/src/shared/spinner/SpinnerPrimitives.tsx
 create mode 100644 apps/web/src/shared/spinner/index.ts
 create mode 100644 apps/web/src/shared/spinner/spinner.css
 create mode 100644 apps/web/src/shared/steps/README.md
 create mode 100644 apps/web/src/shared/steps/StepsPrimitives.tsx
 create mode 100644 apps/web/src/shared/steps/index.ts
 create mode 100644 apps/web/src/shared/steps/steps.css
 create mode 100644 apps/web/src/shared/styles/base.css
 create mode 100644 apps/web/src/shared/tabs/README.md
 create mode 100644 apps/web/src/shared/tabs/TabsPrimitives.tsx
 create mode 100644 apps/web/src/shared/tabs/index.ts
 create mode 100644 apps/web/src/shared/tabs/tabs.css
 create mode 100644 apps/web/src/shared/tag/README.md
 create mode 100644 apps/web/src/shared/tag/TagPrimitives.tsx
 create mode 100644 apps/web/src/shared/tag/index.ts
 create mode 100644 apps/web/src/shared/tag/tag.css
 create mode 100644 apps/web/src/shared/tooltip/README.md
 create mode 100644 apps/web/src/shared/tooltip/TooltipPrimitives.tsx
 create mode 100644 apps/web/src/shared/tooltip/index.ts
 create mode 100644 apps/web/src/shared/tooltip/tooltip.css
 create mode 100644 apps/web/src/shared/typography/README.md
 create mode 100644 apps/web/src/shared/typography/TypographyPrimitives.tsx
 create mode 100644 apps/web/src/shared/typography/index.ts
 create mode 100644 apps/web/src/shared/typography/typography.css
 create mode 100644 apps/web/src/test/design-system-page.test.tsx
 create mode 100644 apps/web/src/test/shared-alert.test.tsx
 create mode 100644 apps/web/src/test/shared-avatar.test.tsx
 create mode 100644 apps/web/src/test/shared-badge.test.tsx
 create mode 100644 apps/web/src/test/shared-breadcrumb.test.tsx
 create mode 100644 apps/web/src/test/shared-card.test.tsx
 create mode 100644 apps/web/src/test/shared-copy-button.test.tsx
 create mode 100644 apps/web/src/test/shared-divider.test.tsx
 create mode 100644 apps/web/src/test/shared-empty-state.test.tsx
 create mode 100644 apps/web/src/test/shared-filter-bar.test.tsx
 create mode 100644 apps/web/src/test/shared-icon.test.tsx
 create mode 100644 apps/web/src/test/shared-kv-list.test.tsx
 create mode 100644 apps/web/src/test/shared-metric-card.test.tsx
 create mode 100644 apps/web/src/test/shared-page-layout.test.tsx
 create mode 100644 apps/web/src/test/shared-pagination.test.tsx
 create mode 100644 apps/web/src/test/shared-popover.test.tsx
 create mode 100644 apps/web/src/test/shared-progress.test.tsx
 create mode 100644 apps/web/src/test/shared-scroll-area.test.tsx
 create mode 100644 apps/web/src/test/shared-skeleton.test.tsx
 create mode 100644 apps/web/src/test/shared-spinner.test.tsx
 create mode 100644 apps/web/src/test/shared-steps.test.tsx
 create mode 100644 apps/web/src/test/shared-tabs.test.tsx
 create mode 100644 apps/web/src/test/shared-tag.test.tsx
 create mode 100644 apps/web/src/test/shared-tooltip.test.tsx
 create mode 100644 apps/web/src/test/shared-typography.test.tsx
 create mode 100644 docs/plans/2026-04-25-design-system-component-docsite-sidebar.md
 create mode 100644 docs/plans/2026-04-25-design-system-docsite-upgrade.md

diff --git a/.gitignore b/.gitignore
index 209f0b2..fc25514 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,4 +20,6 @@ apps/web/test-results/
 .spec-workflow/
 .omx/
 optimus/
-.superpowers/
\ No newline at end of file
+.superpowers/
+.claude
+.playwright-mcp/
\ No newline at end of file
diff --git a/apps/web/e2e/README.md b/apps/web/e2e/README.md
index c511af0..0b38dc7 100644
--- a/apps/web/e2e/README.md
+++ b/apps/web/e2e/README.md
@@ -17,9 +17,12 @@
 - mailbox 创建
 - inbox 读取
 - admin 基本操作
+- `/design-system` 结构与视觉回归脚手架
 
 ## 📏 约定
 
 - 端到端测试优先验证“用户路径”，不是内部实现细节
 - 当前阶段允许通过 `page.route()` 做 API mock，先保证前端壳层和交互路径稳定
 - 更接近真实后端联调的 e2e 可在后续独立 staging 环境中补充
+- `design-system.spec.ts` 默认只跑结构断言；截图基线需在预览页示例稳定后，通过 `PW_UPDATE_DESIGN_SYSTEM_SNAPSHOTS=1` 显式开启
+- `/design-system` 现在是公开页面；相关 e2e 不要求先登录或挂后台壳层
diff --git a/apps/web/e2e/design-system.spec.ts b/apps/web/e2e/design-system.spec.ts
new file mode 100644
index 0000000..a9e652d
--- /dev/null
+++ b/apps/web/e2e/design-system.spec.ts
@@ -0,0 +1,54 @@
+import { expect, test, type Page } from "@playwright/test";
+
+const snapshotUpdatesEnabled = process.env.PW_UPDATE_DESIGN_SYSTEM_SNAPSHOTS === "1";
+
+async function mockPublicSession(page: Page) {
+  await page.route("**/auth/session", async (route) => {
+    await route.fulfill({ status: 401, json: { error: "not authenticated" } });
+  });
+}
+
+async function visitDesignSystem(page: Page, theme: "light" | "dark") {
+  await mockPublicSession(page);
+  await page.addInitScript((nextTheme) => {
+    window.localStorage.setItem("wemail-workspace-theme", nextTheme);
+    document.documentElement.dataset.theme = nextTheme;
+    document.documentElement.style.colorScheme = nextTheme;
+  }, theme);
+
+  await page.goto("/design-system");
+  await expect(page.getByRole("navigation", { name: "首页导航" })).toBeVisible();
+  await expect(page.getByRole("heading", { name: "Foundations" })).toBeVisible();
+  await expect(page.getByRole("navigation", { name: /design system sidebar/i })).toBeVisible();
+  await expect(page.getByTestId("design-system-page")).toBeVisible();
+  await expect
+    .poll(async () => page.evaluate(() => document.documentElement.dataset.theme), { timeout: 10_000 })
+    .toBe(theme);
+}
+
+test("shows the design system page as a sidebar-driven public docsite", async ({ page }) => {
+  await visitDesignSystem(page, "light");
+
+  const sidebarButtons = page.getByRole("navigation", { name: /design system sidebar/i }).getByRole("button");
+  await expect(sidebarButtons).toHaveCount(14);
+  await expect(page.getByText("WeMail Design System v1")).toBeVisible();
+  await expect(page.getByRole("button", { name: "打开对话框" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "打开抽屉" })).toBeVisible();
+});
+
+test.describe("design system visual regression scaffold", () => {
+  test.skip(
+    !snapshotUpdatesEnabled,
+    "Enable PW_UPDATE_DESIGN_SYSTEM_SNAPSHOTS=1 when the preview examples and CI screenshot environment are ready."
+  );
+
+  for (const theme of ["light", "dark"] as const) {
+    test(`captures the ${theme} theme shell`, async ({ page }) => {
+      await visitDesignSystem(page, theme);
+
+      await expect(page.getByTestId("design-system-page")).toHaveScreenshot(`design-system-${theme}.png`, {
+        animations: "disabled"
+      });
+    });
+  }
+});
diff --git a/apps/web/src/app/App.tsx b/apps/web/src/app/App.tsx
index fa4f69c..b4ea28d 100644
--- a/apps/web/src/app/App.tsx
+++ b/apps/web/src/app/App.tsx
@@ -4,6 +4,7 @@ import { BrowserRouter, Navigate, useLocation } from "react-router-dom";
 import { AppLayout } from "./AppLayout";
 import { AppRoutes } from "./AppRoutes";
 import { AuthPage } from "../pages/AuthPage";
+import { DesignSystemPage } from "../pages/DesignSystemPage";
 import { WemailLoadingShell } from "../shared/WemailLoadingShell";
 import { WemailToastViewport } from "../shared/WemailToastViewport";
 import { useAppStore } from "./appStore";
@@ -59,6 +60,16 @@ function AppContent() {
   }, [location.pathname, session]);
 
   const toastViewport = <WemailToastViewport onDismissToast={dismissToast} toasts={toasts} />;
+  const isPublicDesignSystemPage = location.pathname === "/design-system";
+
+  if (isPublicDesignSystemPage) {
+    return (
+      <>
+        {toastViewport}
+        <DesignSystemPage />
+      </>
+    );
+  }
 
   if (auth.loadingSession) {
     return (
diff --git a/apps/web/src/app/AppLayout.tsx b/apps/web/src/app/AppLayout.tsx
index 67627c0..de91c01 100644
--- a/apps/web/src/app/AppLayout.tsx
+++ b/apps/web/src/app/AppLayout.tsx
@@ -1,5 +1,5 @@
 import { ReactNode, useEffect, useRef, useState } from "react";
-import { NavLink, useLocation } from "react-router-dom";
+import { NavLink, useLocation, useNavigate } from "react-router-dom";
 import {
   Bell,
   ChevronDown,
@@ -18,7 +18,8 @@ import {
 
 import type { SessionSummary } from "@wemail/shared";
 
-import { Button, ButtonLink } from "../shared/button";
+import { Button } from "../shared/button";
+import { Tabs, TabsList, TabsPanel, TabsTrigger } from "../shared/tabs";
 import { WemailBrandLockup } from "../shared/WemailBrandLockup";
 import type { WorkspaceRailIcon, WorkspaceShellState } from "./workspaceShell";
 import type { WorkspaceTheme } from "./useWorkspaceTheme";
@@ -81,6 +82,7 @@ export function AppLayout({
   children
 }: AppLayoutProps) {
   const location = useLocation();
+  const navigate = useNavigate();
   const [isUserMenuOpen, setIsUserMenuOpen] = useState(false);
   const userMenuRef = useRef<HTMLDivElement | null>(null);
   const railScrollRef = useRef<HTMLElement | null>(null);
@@ -108,6 +110,9 @@ export function AppLayout({
     };
   }, []);
 
+  const activeSecondaryRoute =
+    shell.secondaryNav.find((item) => item.to === location.pathname)?.to ?? shell.secondaryNav[0]?.to ?? "";
+
   useEffect(() => {
     const areas = [railScrollRef.current, mainScrollRef.current].filter(Boolean) as Array<HTMLElement>;
     if (areas.length === 0) return;
@@ -162,19 +167,28 @@ export function AppLayout({
 
         <div className="workspace-topbar-center">
           {shell.secondaryNav.length > 0 ? (
-            <nav className="workspace-pill-nav workspace-secondary-nav" aria-label={`${shell.activePrimaryLabel} 二级菜单`}>
-              {shell.secondaryNav.map((item) => (
-                <ButtonLink
-                  className="workspace-pill-link"
-                  isActive={location.pathname === item.to}
-                  key={item.to}
-                  size="sm"
-                  to={item.to}
-                  variant="pill"
-                >
-                  {item.label}
-                </ButtonLink>
-              ))}
+            <nav aria-label={`${shell.activePrimaryLabel} 二级菜单`} className="workspace-secondary-tabs-nav">
+              <Tabs
+                activationMode="automatic"
+                className="workspace-secondary-tabs"
+                onValueChange={(nextValue) => {
+                  if (!nextValue || nextValue === location.pathname) return;
+                  void navigate(nextValue);
+                }}
+                value={activeSecondaryRoute}
+                variant="segmented"
+              >
+                <TabsList className="workspace-pill-nav workspace-secondary-nav">
+                  {shell.secondaryNav.map((item) => (
+                    <TabsTrigger className="workspace-pill-link" key={item.to} value={item.to}>
+                      {item.label}
+                    </TabsTrigger>
+                  ))}
+                </TabsList>
+                {shell.secondaryNav.map((item) => (
+                  <TabsPanel className="sr-only" forceMount key={item.to} value={item.to} />
+                ))}
+              </Tabs>
             </nav>
           ) : (
             <div aria-label="当前左侧菜单" className="workspace-pill-nav workspace-secondary-nav workspace-secondary-nav-single">
diff --git a/apps/web/src/app/AppRoutes.tsx b/apps/web/src/app/AppRoutes.tsx
index c1e6b28..201b517 100644
--- a/apps/web/src/app/AppRoutes.tsx
+++ b/apps/web/src/app/AppRoutes.tsx
@@ -23,7 +23,6 @@ import { TelegramSettingsPage } from "../features/settings/TelegramSettingsPage"
 import { WebhookPage } from "../features/settings/WebhookPage";
 import { AnnouncementsPage } from "../pages/AnnouncementsPage";
 import { DashboardPage } from "../pages/DashboardPage";
-import { DesignSystemPage } from "../pages/DesignSystemPage";
 import { InboxPage } from "../pages/InboxPage";
 import { SystemSettingsPage } from "../pages/SystemSettingsPage";
 import { SystemProfilePage } from "../pages/SystemProfilePage";
@@ -234,7 +233,6 @@ export function AppRoutes({ session, inbox, selectedMessage, settings, admin, ap
       <Route path="/system/settings" element={systemSettingsPage} />
       <Route path="/system/profile" element={systemProfilePage} />
       <Route path="/system/about" element={<AboutPage />} />
-      <Route path="/design-system" element={<DesignSystemPage />} />
     </Routes>
   );
 }
diff --git a/apps/web/src/features/accounts/AccountsListPage.tsx b/apps/web/src/features/accounts/AccountsListPage.tsx
index f21fb94..d14d2fc 100644
--- a/apps/web/src/features/accounts/AccountsListPage.tsx
+++ b/apps/web/src/features/accounts/AccountsListPage.tsx
@@ -1,7 +1,11 @@
 import { useEffect, useMemo, useState } from "react";
+import { Badge } from "../../shared/badge";
 import { Button } from "../../shared/button";
-import { CheckboxField, FormField, SelectInput, TextInput } from "../../shared/form";
+import { FilterBar, FilterBarActions } from "../../shared/filter-bar";
+import { CheckboxField, FormField, SearchInput, SelectInput, TextInput } from "../../shared/form";
 import { OverlayDialog } from "../../shared/overlay";
+import { Pagination } from "../../shared/pagination";
+import { Page, PageHeader, PageMain, PageToolbar } from "../../shared/page-layout";
 import {
   Table,
   TableBody,
@@ -42,6 +46,21 @@ function formatLastActive(value: string) {
   return dateTimeFormatter.format(new Date(value));
 }
 
+function getStatusBadgeVariant(status: MailboxAccountStatus) {
+  switch (status) {
+    case "enabled":
+      return "success";
+    case "disabled":
+      return "warning";
+    case "archived":
+      return "neutral";
+    case "soft_deleted":
+      return "danger";
+    default:
+      return "neutral";
+  }
+}
+
 function updateSelectedAccounts(
   accounts: MailboxAccountRecord[],
   selectedIds: string[],
@@ -61,10 +80,12 @@ function updateSelectedAccounts(
 
 export function AccountsListPage() {
   const [accounts, setAccounts] = useState(mailboxAccountsMockData);
+  const [page, setPage] = useState(1);
   const [selectedIds, setSelectedIds] = useState<string[]>([]);
   const [isMoreActionsOpen, setIsMoreActionsOpen] = useState(false);
   const [isHardDeleteDialogOpen, setIsHardDeleteDialogOpen] = useState(false);
   const [confirmationPhrase, setConfirmationPhrase] = useState("");
+  const pageSize = 3;
 
   const selectedAccounts = useMemo(
     () => accounts.filter((account) => selectedIds.includes(account.id)),
@@ -72,7 +93,6 @@ export function AccountsListPage() {
   );
 
   const selectedCount = selectedAccounts.length;
-  const allVisibleSelected = accounts.length > 0 && selectedCount === accounts.length;
   const hardDeletePhrase = `DELETE ${selectedCount} ACCOUNTS`;
   const selectedAccountsWithMailHistory = selectedAccounts.filter(
     (account) => account.messageCount > 0 || account.outboundCount > 0
@@ -87,6 +107,19 @@ export function AccountsListPage() {
     }
   }, [selectedCount]);
 
+  useEffect(() => {
+    const pageCount = Math.max(1, Math.ceil(accounts.length / pageSize));
+    if (page > pageCount) {
+      setPage(pageCount);
+    }
+  }, [accounts.length, page, pageSize]);
+
+  const visibleAccounts = useMemo(() => {
+    const startIndex = (page - 1) * pageSize;
+    return accounts.slice(startIndex, startIndex + pageSize);
+  }, [accounts, page, pageSize]);
+  const allVisibleSelected = visibleAccounts.length > 0 && visibleAccounts.every((account) => selectedIds.includes(account.id));
+
   function toggleSelection(accountId: string) {
     setSelectedIds((currentIds) =>
       currentIds.includes(accountId) ? currentIds.filter((id) => id !== accountId) : [...currentIds, accountId]
@@ -94,7 +127,7 @@ export function AccountsListPage() {
   }
 
   function toggleSelectAll() {
-    setSelectedIds(allVisibleSelected ? [] : accounts.map((account) => account.id));
+    setSelectedIds(allVisibleSelected ? [] : visibleAccounts.map((account) => account.id));
   }
 
   function closeHardDeleteDialog() {
@@ -139,56 +172,58 @@ export function AccountsListPage() {
 
   return (
     <>
-      <main className="workspace-grid accounts-list-page">
+      <Page className="workspace-grid accounts-list-page">
         <section className="panel workspace-card page-panel accounts-list-toolbar-card">
-          <div className="workspace-card-header">
-            <div>
-              <p className="panel-kicker">账号中心</p>
-            </div>
-            <div className="workspace-topbar-actions">
-              <Button variant="primary">导出</Button>
-              <Button variant="secondary">刷新</Button>
-            </div>
-          </div>
+          <PageHeader
+            actions={
+              <div className="workspace-topbar-actions">
+                <Button variant="primary">导出</Button>
+                <Button variant="secondary">刷新</Button>
+              </div>
+            }
+            kicker="账号中心"
+          />
 
-          <div className="workspace-grid accounts-list-filter-grid">
-            <FormField label={<span className="sr-only">搜索账号</span>}>
-              <TextInput aria-label="搜索账号" placeholder="搜索 ID / 地址 / 创建人" type="search" />
-            </FormField>
-            <FormField label={<span className="sr-only">状态筛选</span>}>
-              <SelectInput aria-label="状态筛选" defaultValue="all">
-                <option value="all">全部状态</option>
-                <option value="enabled">启用</option>
-                <option value="disabled">停用</option>
-                <option value="archived">已归档</option>
-                <option value="soft_deleted">已软删除</option>
-              </SelectInput>
-            </FormField>
-            <FormField label={<span className="sr-only">创建人筛选</span>}>
-              <SelectInput aria-label="创建人筛选" defaultValue="all">
-                <option value="all">全部创建人</option>
-                <option value="Will">Will</option>
-                <option value="Ada">Ada</option>
-                <option value="System">System</option>
-              </SelectInput>
-            </FormField>
-            <FormField label={<span className="sr-only">最近活跃筛选</span>}>
-              <SelectInput aria-label="最近活跃筛选" defaultValue="all">
-                <option value="all">全部活跃时间</option>
-                <option value="7d">近 7 天</option>
-                <option value="30d">近 30 天</option>
-                <option value="90d">近 90 天</option>
-              </SelectInput>
-            </FormField>
-          </div>
+          <PageToolbar>
+            <FilterBar className="accounts-list-filter-grid" columns={4}>
+              <FormField label={<span className="sr-only">搜索账号</span>}>
+                <SearchInput aria-label="搜索账号" placeholder="搜索 ID / 地址 / 创建人" />
+              </FormField>
+              <FormField label={<span className="sr-only">状态筛选</span>}>
+                <SelectInput aria-label="状态筛选" defaultValue="all">
+                  <option value="all">全部状态</option>
+                  <option value="enabled">启用</option>
+                  <option value="disabled">停用</option>
+                  <option value="archived">已归档</option>
+                  <option value="soft_deleted">已软删除</option>
+                </SelectInput>
+              </FormField>
+              <FormField label={<span className="sr-only">创建人筛选</span>}>
+                <SelectInput aria-label="创建人筛选" defaultValue="all">
+                  <option value="all">全部创建人</option>
+                  <option value="Will">Will</option>
+                  <option value="Ada">Ada</option>
+                  <option value="System">System</option>
+                </SelectInput>
+              </FormField>
+              <FormField label={<span className="sr-only">最近活跃筛选</span>}>
+                <SelectInput aria-label="最近活跃筛选" defaultValue="all">
+                  <option value="all">全部活跃时间</option>
+                  <option value="7d">近 7 天</option>
+                  <option value="30d">近 30 天</option>
+                  <option value="90d">近 90 天</option>
+                </SelectInput>
+              </FormField>
+            </FilterBar>
 
-          <div className="workspace-topbar-actions accounts-list-quick-filters">
-            <Button variant="ghost">仅看异常</Button>
-            <Button variant="ghost">仅看长期不活跃</Button>
-          </div>
+            <FilterBarActions className="workspace-topbar-actions accounts-list-quick-filters">
+              <Button variant="ghost">仅看异常</Button>
+              <Button variant="ghost">仅看长期不活跃</Button>
+            </FilterBarActions>
+          </PageToolbar>
         </section>
 
-        <section className="panel workspace-card page-panel accounts-list-table-card">
+        <PageMain className="panel workspace-card page-panel accounts-list-table-card">
           <div className="workspace-card-header">
             <div>
               <p className="panel-kicker">账号列表</p>
@@ -197,43 +232,43 @@ export function AccountsListPage() {
 
           {selectedCount > 0 ? (
             <section aria-label="批量操作条" className="panel workspace-card accounts-list-bulk-bar">
-              <div className="workspace-card-header">
-                <div>
-                  <p className="panel-kicker">批量操作</p>
-                  <h4>已选择 {selectedCount} 个账号</h4>
-                </div>
-                <div className="workspace-topbar-actions">
-                  <Button onClick={() => runStatusBulkAction("enabled")} variant="primary">
-                    批量启用
-                  </Button>
-                  <Button onClick={() => runStatusBulkAction("disabled")} variant="secondary">
-                    批量停用
-                  </Button>
-                  <Button onClick={() => runStatusBulkAction("archived")} variant="secondary">
-                    批量归档
-                  </Button>
-                  <div>
-                    <Button
-                      aria-expanded={isMoreActionsOpen}
-                      onClick={() => setIsMoreActionsOpen((current) => !current)}
-                      variant="secondary"
-                    >
-                      更多操作
+              <PageHeader
+                actions={
+                  <div className="workspace-topbar-actions">
+                    <Button onClick={() => runStatusBulkAction("enabled")} variant="primary">
+                      批量启用
                     </Button>
-                    {isMoreActionsOpen ? (
-                      <div aria-label="危险批量操作" className="panel workspace-card accounts-list-more-actions" role="group">
-                        <p className="panel-kicker">危险操作</p>
-                        <Button onClick={runSoftDelete} variant="ghost">
-                          批量软删除
-                        </Button>
-                        <Button onClick={openHardDeleteDialog} variant="danger">
-                          批量彻底删除
-                        </Button>
-                      </div>
-                    ) : null}
+                    <Button onClick={() => runStatusBulkAction("disabled")} variant="secondary">
+                      批量停用
+                    </Button>
+                    <Button onClick={() => runStatusBulkAction("archived")} variant="secondary">
+                      批量归档
+                    </Button>
+                    <div>
+                      <Button
+                        aria-expanded={isMoreActionsOpen}
+                        onClick={() => setIsMoreActionsOpen((current) => !current)}
+                        variant="secondary"
+                      >
+                        更多操作
+                      </Button>
+                      {isMoreActionsOpen ? (
+                        <div aria-label="危险批量操作" className="panel workspace-card accounts-list-more-actions" role="group">
+                          <p className="panel-kicker">危险操作</p>
+                          <Button onClick={runSoftDelete} variant="ghost">
+                            批量软删除
+                          </Button>
+                          <Button onClick={openHardDeleteDialog} variant="danger">
+                            批量彻底删除
+                          </Button>
+                        </div>
+                      ) : null}
+                    </div>
                   </div>
-                </div>
-              </div>
+                }
+                kicker="批量操作"
+                title={`已选择 ${selectedCount} 个账号`}
+              />
             </section>
           ) : null}
 
@@ -264,7 +299,7 @@ export function AccountsListPage() {
                 </TableRow>
               </TableHead>
               <TableBody>
-                {accounts.map((account) => {
+                {visibleAccounts.map((account) => {
                   const isSelected = selectedIds.includes(account.id);
 
                   return (
@@ -283,7 +318,9 @@ export function AccountsListPage() {
                       <TableCell>{formatDate(account.createdAt)}</TableCell>
                       <TableCell>
                         <div className="accounts-list-status-cell">
-                          <span className={`accounts-status-pill accounts-status-pill--${account.status}`}>{statusLabelMap[account.status]}</span>
+                          <Badge appearance="soft" statusRole="status" variant={getStatusBadgeVariant(account.status)}>
+                            {statusLabelMap[account.status]}
+                          </Badge>
                           {account.deletedAt ? <div className="section-copy">软删于 {formatDate(account.deletedAt)}</div> : null}
                         </div>
                       </TableCell>
@@ -302,8 +339,16 @@ export function AccountsListPage() {
               </TableBody>
             </Table>
           </TableContainer>
-        </section>
-      </main>
+          <Pagination
+            aria-label="账号列表分页"
+            className="accounts-list-pagination"
+            onChange={setPage}
+            page={page}
+            pageSize={pageSize}
+            total={accounts.length}
+          />
+        </PageMain>
+      </Page>
 
       {isHardDeleteDialogOpen ? (
         <OverlayDialog closeLabel="关闭彻底删除确认" eyebrow="危险操作" onClose={closeHardDeleteDialog} title="确认彻底删除">
diff --git a/apps/web/src/features/landing/PublicSiteNavigation.tsx b/apps/web/src/features/landing/PublicSiteNavigation.tsx
new file mode 100644
index 0000000..59ea4dc
--- /dev/null
+++ b/apps/web/src/features/landing/PublicSiteNavigation.tsx
@@ -0,0 +1,194 @@
+import { type CSSProperties, useEffect, useState } from "react";
+import { Link, useLocation } from "react-router-dom";
+import { Menu, MoonStar, SunMedium, X } from "lucide-react";
+
+import { Button, ButtonLink } from "../../shared/button";
+import { WemailBrandLockup } from "../../shared/WemailBrandLockup";
+import { landingNavLinks } from "./landing-content";
+import "./landing.css";
+
+type PublicSiteNavigationProps = {
+  onToggleTheme: () => void;
+  theme: "dark" | "light";
+};
+
+function useReducedMotion() {
+  const [reducedMotion, setReducedMotion] = useState(false);
+
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
+    const mediaQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
+    const update = () => setReducedMotion(mediaQuery.matches);
+    update();
+    mediaQuery.addEventListener("change", update);
+    return () => mediaQuery.removeEventListener("change", update);
+  }, []);
+
+  return reducedMotion;
+}
+
+function useCompactNavigation() {
+  const [isCompactNavigation, setIsCompactNavigation] = useState(false);
+
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
+    const mediaQuery = window.matchMedia("(max-width: 980px)");
+    const update = () => setIsCompactNavigation(mediaQuery.matches);
+    update();
+    mediaQuery.addEventListener("change", update);
+    return () => mediaQuery.removeEventListener("change", update);
+  }, []);
+
+  return isCompactNavigation;
+}
+
+function ThemeIcon({ theme }: { theme: "dark" | "light" }) {
+  return theme === "dark" ? <SunMedium aria-hidden="true" /> : <MoonStar aria-hidden="true" />;
+}
+
+function resolveSectionHref(pathname: string, href: string) {
+  return pathname === "/" ? href : `/${href}`;
+}
+
+export function PublicSiteNavigation({ onToggleTheme, theme }: PublicSiteNavigationProps) {
+  const location = useLocation();
+  const [isScrolled, setIsScrolled] = useState(false);
+  const [isMobileMenuOpen, setIsMobileMenuOpen] = useState(false);
+  const reducedMotion = useReducedMotion();
+  const isCompactNavigation = useCompactNavigation();
+
+  useEffect(() => {
+    const onScroll = () => setIsScrolled(window.scrollY > 20);
+    onScroll();
+    window.addEventListener("scroll", onScroll, { passive: true });
+    return () => window.removeEventListener("scroll", onScroll);
+  }, []);
+
+  useEffect(() => {
+    const body = document.body;
+    if (isMobileMenuOpen) {
+      body.dataset.mobileMenu = "open";
+    } else {
+      delete body.dataset.mobileMenu;
+    }
+    return () => {
+      delete body.dataset.mobileMenu;
+    };
+  }, [isMobileMenuOpen]);
+
+  useEffect(() => {
+    if (!isCompactNavigation) {
+      setIsMobileMenuOpen(false);
+    }
+  }, [isCompactNavigation]);
+
+  return (
+    <header className={isScrolled ? "landing-nav-shell is-scrolled" : "landing-nav-shell"}>
+      <nav className={isScrolled || isMobileMenuOpen ? "landing-nav is-floating" : "landing-nav"} aria-label="首页导航">
+        <div className={isScrolled ? "landing-nav-bar compact" : "landing-nav-bar"}>
+          <Link aria-label="WeMail 首页" className="landing-brand" to="/">
+            <WemailBrandLockup className="landing-brand-lockup" compact label="WeMail brand lockup" />
+          </Link>
+
+          <div className="landing-nav-links" aria-label="首页分区导航">
+            {landingNavLinks.map((link) => (
+              <a key={link.href} href={resolveSectionHref(location.pathname, link.href)} className="landing-nav-link">
+                {link.label}
+              </a>
+            ))}
+            <Link className="landing-nav-link" to="/design-system">
+              设计系统
+            </Link>
+          </div>
+
+          <div className="landing-nav-actions">
+            <ButtonLink size="sm" to="/login" variant="secondary">
+              登录
+            </ButtonLink>
+            <ButtonLink size="sm" to="/register" variant="primary">
+              注册
+            </ButtonLink>
+            {!isCompactNavigation ? (
+              <Button
+                aria-label={theme === "dark" ? "切换到浅色主题" : "切换到深色主题"}
+                className="landing-nav-theme-toggle landing-nav-edge-control"
+                iconOnly
+                onClick={onToggleTheme}
+                size="sm"
+                variant="icon"
+              >
+                <ThemeIcon theme={theme} />
+              </Button>
+            ) : null}
+          </div>
+
+          {isCompactNavigation ? (
+            <Button
+              aria-controls="landing-mobile-menu"
+              aria-expanded={isMobileMenuOpen}
+              aria-label="切换菜单"
+              className="landing-nav-mobile-toggle landing-nav-mobile-toggle-tight landing-nav-edge-control"
+              iconOnly
+              onClick={() => {
+                setIsMobileMenuOpen((current) => !current);
+              }}
+              size="sm"
+              variant="icon"
+            >
+              {isMobileMenuOpen ? <X aria-hidden="true" /> : <Menu aria-hidden="true" />}
+            </Button>
+          ) : null}
+        </div>
+      </nav>
+
+      {isCompactNavigation && isMobileMenuOpen ? (
+        <div className="landing-mobile-menu-backdrop" role="dialog" aria-label="首页移动菜单" aria-modal="true" id="landing-mobile-menu">
+          <div className="landing-mobile-menu">
+            <div className="landing-mobile-links">
+              {landingNavLinks.map((link, index) => (
+                <a
+                  key={link.href}
+                  className="landing-mobile-link"
+                  href={resolveSectionHref(location.pathname, link.href)}
+                  onClick={() => setIsMobileMenuOpen(false)}
+                  style={{ ["--menu-delay" as string]: reducedMotion ? "0ms" : `${index * 70}ms` } as CSSProperties}
+                >
+                  {link.label}
+                </a>
+              ))}
+              <Link
+                className="landing-mobile-link"
+                onClick={() => setIsMobileMenuOpen(false)}
+                style={{ ["--menu-delay" as string]: reducedMotion ? "0ms" : `${landingNavLinks.length * 70}ms` } as CSSProperties}
+                to="/design-system"
+              >
+                设计系统
+              </Link>
+            </div>
+            <div className="landing-mobile-actions">
+              <ButtonLink size="sm" to="/login" variant="secondary" onClick={() => setIsMobileMenuOpen(false)}>
+                登录
+              </ButtonLink>
+              <ButtonLink size="sm" to="/register" variant="primary" onClick={() => setIsMobileMenuOpen(false)}>
+                注册
+              </ButtonLink>
+              <Button
+                fullWidth
+                className="landing-nav-theme-toggle landing-mobile-theme-toggle"
+                leadingIcon={<ThemeIcon theme={theme} />}
+                onClick={() => {
+                  onToggleTheme();
+                  setIsMobileMenuOpen(false);
+                }}
+                size="sm"
+                variant="secondary"
+              >
+                {theme === "dark" ? "切换到浅色主题" : "切换到深色主题"}
+              </Button>
+            </div>
+          </div>
+        </div>
+      ) : null}
+    </header>
+  );
+}
diff --git a/apps/web/src/features/landing/WemailLandingPage.tsx b/apps/web/src/features/landing/WemailLandingPage.tsx
index 2f6f4c5..63cb8f4 100644
--- a/apps/web/src/features/landing/WemailLandingPage.tsx
+++ b/apps/web/src/features/landing/WemailLandingPage.tsx
@@ -9,20 +9,18 @@ import {
   Eye,
   FileCheck,
   Lock,
-  Menu,
-  MoonStar,
   Send,
-  Shield,
-  SunMedium,
-  X
+  Shield
 } from "lucide-react";
 
 import { Button, ButtonLink } from "../../shared/button";
 import { Switch } from "../../shared/switch";
+import { Tabs, TabsList, TabsPanel, TabsTrigger } from "../../shared/tabs";
 import { WemailBrandLockup } from "../../shared/WemailBrandLockup";
 import { AnimatedSphere } from "./AnimatedSphere";
 import { AnimatedTetrahedron } from "./AnimatedTetrahedron";
 import { AnimatedWave } from "./AnimatedWave";
+import { PublicSiteNavigation } from "./PublicSiteNavigation";
 import {
   certifications,
   developerFeatures,
@@ -33,7 +31,6 @@ import {
   heroWords,
   infrastructureLocations,
   integrations,
-  landingNavLinks,
   metrics,
   pricingPlans,
   securityCards,
@@ -329,135 +326,6 @@ function AnimatedCounter({ value, prefix, suffix }: { value: number; prefix: str
   );
 }
 
-function DesktopNavLinks() {
-  return (
-    <div className="landing-nav-links" aria-label="首页分区导航">
-      {landingNavLinks.map((link) => (
-        <a key={link.href} href={link.href} className="landing-nav-link">
-          {link.label}
-        </a>
-      ))}
-    </div>
-  );
-}
-
-function ThemeIcon({ theme }: { theme: "dark" | "light" }) {
-  return theme === "dark" ? <SunMedium aria-hidden="true" /> : <MoonStar aria-hidden="true" />;
-}
-
-function Navigation({ onToggleTheme, theme }: { onToggleTheme: () => void; theme: "dark" | "light" }) {
-  const [isScrolled, setIsScrolled] = useState(false);
-  const [isMobileMenuOpen, setIsMobileMenuOpen] = useState(false);
-  const reducedMotion = useReducedMotion();
-  const isCompactNavigation = useCompactNavigation();
-
-  useEffect(() => {
-    const onScroll = () => setIsScrolled(window.scrollY > 20);
-    onScroll();
-    window.addEventListener("scroll", onScroll, { passive: true });
-    return () => window.removeEventListener("scroll", onScroll);
-  }, []);
-
-  useEffect(() => {
-    const body = document.body;
-    if (isMobileMenuOpen) {
-      body.dataset.mobileMenu = "open";
-    } else {
-      delete body.dataset.mobileMenu;
-    }
-    return () => {
-      delete body.dataset.mobileMenu;
-    };
-  }, [isMobileMenuOpen]);
-
-  useEffect(() => {
-    if (!isCompactNavigation) {
-      setIsMobileMenuOpen(false);
-    }
-  }, [isCompactNavigation]);
-
-  return (
-    <header className={isScrolled ? "landing-nav-shell is-scrolled" : "landing-nav-shell"}>
-      <nav className={isScrolled || isMobileMenuOpen ? "landing-nav is-floating" : "landing-nav"} aria-label="首页导航">
-        <div className={isScrolled ? "landing-nav-bar compact" : "landing-nav-bar"}>
-          <Link aria-label="WeMail 首页" className="landing-brand" to="/">
-            <WemailBrandLockup className="landing-brand-lockup" compact label="WeMail brand lockup" />
-          </Link>
-
-          <DesktopNavLinks />
-
-          <div className="landing-nav-actions">
-            <ButtonLink size="sm" to="/login" variant="secondary">
-              登录
-            </ButtonLink>
-            <ButtonLink size="sm" to="/register" variant="primary">
-              注册
-            </ButtonLink>
-          </div>
-
-          <Button
-            aria-controls={isCompactNavigation ? "landing-mobile-menu" : undefined}
-            aria-expanded={isCompactNavigation ? isMobileMenuOpen : undefined}
-            aria-label={isCompactNavigation ? "切换菜单" : theme === "dark" ? "切换到浅色主题" : "切换到深色主题"}
-            iconOnly
-            onClick={() => {
-              if (isCompactNavigation) {
-                setIsMobileMenuOpen((current) => !current);
-                return;
-              }
-              onToggleTheme();
-            }}
-            size="sm"
-            variant="icon"
-          >
-            {isCompactNavigation ? (isMobileMenuOpen ? <X aria-hidden="true" /> : <Menu aria-hidden="true" />) : <ThemeIcon theme={theme} />}
-          </Button>
-        </div>
-      </nav>
-
-      {isCompactNavigation && isMobileMenuOpen ? (
-        <div className="landing-mobile-menu-backdrop" role="dialog" aria-label="首页移动菜单" aria-modal="true" id="landing-mobile-menu">
-          <div className="landing-mobile-menu">
-            <div className="landing-mobile-links">
-              {landingNavLinks.map((link, index) => (
-                <a
-                  key={link.href}
-                  className="landing-mobile-link"
-                  href={link.href}
-                  onClick={() => setIsMobileMenuOpen(false)}
-                  style={{ ["--menu-delay" as string]: reducedMotion ? "0ms" : `${index * 70}ms` } as CSSProperties}
-                >
-                  {link.label}
-                </a>
-              ))}
-            </div>
-            <div className="landing-mobile-actions">
-              <ButtonLink size="sm" to="/login" variant="secondary" onClick={() => setIsMobileMenuOpen(false)}>
-                登录
-              </ButtonLink>
-              <ButtonLink size="sm" to="/register" variant="primary" onClick={() => setIsMobileMenuOpen(false)}>
-                注册
-              </ButtonLink>
-              <Button
-                fullWidth
-                leadingIcon={<ThemeIcon theme={theme} />}
-                onClick={() => {
-                  onToggleTheme();
-                  setIsMobileMenuOpen(false);
-                }}
-                size="sm"
-                variant="secondary"
-              >
-                {theme === "dark" ? "切换到浅色主题" : "切换到深色主题"}
-              </Button>
-            </div>
-          </div>
-        </div>
-      ) : null}
-    </header>
-  );
-}
-
 function HeroSection() {
   const reducedMotion = useReducedMotion();
   const [isVisible, setIsVisible] = useState(false);
@@ -689,6 +557,8 @@ function MetricsSection() {
 }
 
 function IntegrationsSection() {
+  const isCompactNavigation = useCompactNavigation();
+
   return (
     <RevealSection id="integrations" className="landing-section">
       <div className="landing-section-header centered">
@@ -696,30 +566,45 @@ function IntegrationsSection() {
         <h2 className="landing-display-title">和你已经在用的系统自然接上。</h2>
         <p className="landing-section-copy">把临时邮箱流程接到团队现有的通知、自动化和发布控制链路里，而不是额外再维护一套孤岛工具。</p>
       </div>
-      <div className="landing-marquee-list">
-        <div className="landing-marquee-track">
-          {Array.from({ length: 2 }).flatMap((_, loopIndex) =>
-            integrations.map((integration) => (
-              <article className="landing-integration-card" key={`${integration.name}-${loopIndex}`}>
-                <strong>{integration.name}</strong>
-                <span>{integration.category}</span>
-              </article>
-            ))
-          )}
-        </div>
-      </div>
-      <div className="landing-marquee-list reverse">
-        <div className="landing-marquee-track reverse">
-          {Array.from({ length: 2 }).flatMap((_, loopIndex) =>
-            [...integrations].reverse().map((integration) => (
-              <article className="landing-integration-card" key={`${integration.name}-reverse-${loopIndex}`}>
+      {isCompactNavigation ? (
+        <div className="landing-marquee-list landing-marquee-list-compact">
+          <div className="landing-marquee-track landing-marquee-track-compact">
+            {integrations.map((integration) => (
+              <article className="landing-integration-card" key={integration.name}>
                 <strong>{integration.name}</strong>
                 <span>{integration.category}</span>
               </article>
-            ))
-          )}
+            ))}
+          </div>
         </div>
-      </div>
+      ) : (
+        <>
+          <div className="landing-marquee-list">
+            <div className="landing-marquee-track">
+              {Array.from({ length: 2 }).flatMap((_, loopIndex) =>
+                integrations.map((integration) => (
+                  <article className="landing-integration-card" key={`${integration.name}-${loopIndex}`}>
+                    <strong>{integration.name}</strong>
+                    <span>{integration.category}</span>
+                  </article>
+                ))
+              )}
+            </div>
+          </div>
+          <div className="landing-marquee-list reverse">
+            <div className="landing-marquee-track reverse">
+              {Array.from({ length: 2 }).flatMap((_, loopIndex) =>
+                [...integrations].reverse().map((integration) => (
+                  <article className="landing-integration-card" key={`${integration.name}-reverse-${loopIndex}`}>
+                    <strong>{integration.name}</strong>
+                    <span>{integration.category}</span>
+                  </article>
+                ))
+              )}
+            </div>
+          </div>
+        </>
+      )}
     </RevealSection>
   );
 }
@@ -796,39 +681,36 @@ function DevelopersSection() {
           </div>
         </div>
         <div className="landing-developer-panel">
-          <div className="landing-code-tabs">
-            <div className="landing-code-tab-switch" role="tablist" aria-label="开发示例">
-              {developerTabs.map((tab, index) => (
-                <Button
-                  key={tab.label}
-                  aria-selected={index === activeTab}
-                  className={index === activeTab ? "active" : ""}
-                  isActive={index === activeTab}
-                  onClick={() => setActiveTab(index)}
-                  role="tab"
-                  size="sm"
-                  variant="pill"
-                >
-                  {tab.label}
-                </Button>
-              ))}
+          <Tabs onValueChange={(nextValue) => setActiveTab(Number(nextValue))} value={String(activeTab)} variant="segmented">
+            <div className="landing-code-tabs">
+              <TabsList aria-label="开发示例" className="landing-code-tab-switch">
+                {developerTabs.map((tab, index) => (
+                  <TabsTrigger className={index === activeTab ? "active" : undefined} key={tab.label} value={String(index)}>
+                    {tab.label}
+                  </TabsTrigger>
+                ))}
+              </TabsList>
+              <Button
+                className="landing-code-copy"
+                leadingIcon={copiedTab === activeTab ? <Check aria-hidden="true" /> : <Copy aria-hidden="true" />}
+                onClick={() => void copyActiveSnippet()}
+                size="sm"
+                variant="secondary"
+              >
+                {copiedTab === activeTab ? "已复制" : "复制"}
+              </Button>
             </div>
-            <Button
-              className="landing-code-copy"
-              leadingIcon={copiedTab === activeTab ? <Check aria-hidden="true" /> : <Copy aria-hidden="true" />}
-              onClick={() => void copyActiveSnippet()}
-              size="sm"
-              variant="secondary"
-            >
-              {copiedTab === activeTab ? "已复制" : "复制"}
-            </Button>
-          </div>
-          <AnimatedCodeBlock code={developerTabs[activeTab]?.code ?? ""} fileLabel="api-snippet.ts" statusLabel="可直接接入" />
-          <div className="landing-code-links">
-            <a href="#pricing">查看可用方案</a>
-            <span aria-hidden="true">|</span>
-            <a href="#features">回到能力概览</a>
-          </div>
+            {developerTabs.map((tab, index) => (
+              <TabsPanel key={tab.label} value={String(index)}>
+                <AnimatedCodeBlock code={tab.code} fileLabel="api-snippet.ts" statusLabel="可直接接入" />
+                <div className="landing-code-links">
+                  <a href="#pricing">查看可用方案</a>
+                  <span aria-hidden="true">|</span>
+                  <a href="#features">回到能力概览</a>
+                </div>
+              </TabsPanel>
+            ))}
+          </Tabs>
         </div>
       </div>
     </RevealSection>
@@ -1065,7 +947,7 @@ export function WemailLandingPage({
 }) {
   return (
     <div className="landing-page noise-overlay">
-      <Navigation onToggleTheme={onToggleTheme} theme={theme} />
+      <PublicSiteNavigation onToggleTheme={onToggleTheme} theme={theme} />
       <main className="landing-page-main">
         <HeroSection />
         <FeaturesSection />
diff --git a/apps/web/src/features/landing/landing.css b/apps/web/src/features/landing/landing.css
index 6bf51b9..b671e9b 100644
--- a/apps/web/src/features/landing/landing.css
+++ b/apps/web/src/features/landing/landing.css
@@ -169,6 +169,10 @@
   transition: width 500ms cubic-bezier(0.22, 1, 0.36, 1), transform 500ms cubic-bezier(0.22, 1, 0.36, 1), padding 500ms cubic-bezier(0.22, 1, 0.36, 1);
 }
 
+.landing-nav-edge-control {
+  justify-self: end;
+}
+
 .landing-nav.is-floating {
   width: min(1200px, 100%);
   padding-top: 16px;
@@ -176,7 +180,7 @@
 
 .landing-nav-bar {
   display: grid;
-  grid-template-columns: auto minmax(0, 1fr) auto auto;
+  grid-template-columns: auto minmax(0, 1fr) auto;
   align-items: center;
   gap: 24px;
   min-height: 80px;
@@ -247,6 +251,20 @@
 
 .landing-nav-links {
   justify-content: center;
+  gap: 32px;
+}
+
+.landing-nav-actions {
+  align-items: center;
+  justify-self: end;
+  gap: 12px;
+  margin-right: -1px;
+}
+
+.landing-nav-theme-toggle,
+.landing-nav-mobile-toggle {
+  border: 1px solid var(--border) !important;
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--surface) 30%, transparent);
 }
 
 .landing-nav-link {
@@ -296,22 +314,26 @@
 .landing-mobile-menu-backdrop {
   position: fixed;
   inset: 0;
+  z-index: 35;
   display: grid;
   place-items: stretch;
   padding: 88px 24px 24px;
   background: color-mix(in srgb, var(--bg) 90%, transparent);
   backdrop-filter: blur(18px);
+  pointer-events: auto;
 }
 
 .landing-mobile-menu {
-  display: grid;
-  align-content: space-between;
+  display: flex;
+  flex-direction: column;
   gap: 24px;
+  height: calc(100dvh - 112px);
   border-radius: 32px;
   border: 1px solid var(--border);
   background: color-mix(in srgb, var(--surface) 92%, transparent);
   padding: 32px 24px;
   box-shadow: var(--shadow-card);
+  pointer-events: auto;
 }
 
 .landing-mobile-links {
@@ -331,6 +353,13 @@
 .landing-mobile-actions {
   display: grid;
   gap: 12px;
+  margin-top: auto;
+}
+
+.landing-mobile-theme-toggle,
+.landing-mobile-theme-toggle:hover,
+.landing-mobile-theme-toggle:focus-visible {
+  transform: none;
 }
 
 .landing-hero-section {
@@ -895,6 +924,18 @@
   margin-top: 12px;
 }
 
+.landing-marquee-list-compact {
+  overflow: visible;
+}
+
+.landing-marquee-track-compact {
+  width: 100%;
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 12px;
+  animation: none;
+}
+
 .landing-integration-card {
   flex-direction: column;
   align-items: flex-start;
@@ -1735,6 +1776,18 @@
     grid-template-columns: auto 1fr auto;
   }
 
+  .landing-nav-mobile-toggle {
+    position: static;
+    justify-self: end;
+    align-self: center;
+    transform: none;
+  }
+
+  .landing-nav-mobile-toggle.ui-button:hover,
+  .landing-nav-mobile-toggle.ui-button:focus-visible {
+    transform: none;
+  }
+
   .landing-hero-section {
     min-height: auto;
     padding-top: 124px;
@@ -1777,6 +1830,10 @@
     padding-inline: 16px;
   }
 
+  .landing-nav-mobile-toggle-tight {
+    margin-right: -24px;
+  }
+
   .landing-nav.is-floating {
     padding-top: 10px;
   }
@@ -1797,13 +1854,72 @@
     min-height: calc(100dvh - 88px);
   }
 
+  .landing-hero-section {
+    padding-top: 100px;
+    padding-bottom: 24px;
+    min-height: auto;
+  }
+
+  .landing-hero-copy-shell {
+    gap: 16px;
+  }
+
   .landing-display-title,
   .landing-testimonial-grid blockquote p {
     font-size: clamp(2.2rem, 12vw, 3.8rem);
   }
 
   .landing-hero-title {
-    font-size: clamp(2.8rem, 16vw, 4.6rem);
+    gap: 2px;
+    font-size: clamp(2.45rem, 14vw, 4.1rem);
+    line-height: 0.92;
+    letter-spacing: -0.06em;
+  }
+
+  .landing-hero-description {
+    max-width: none;
+    font-size: 1rem;
+    line-height: 1.65;
+  }
+
+  .landing-hero-bottom {
+    gap: 16px;
+  }
+
+  .landing-cta-row {
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: 10px;
+  }
+
+  .landing-cta-row .ui-button {
+    width: 100%;
+    justify-content: center;
+  }
+
+  .landing-stats-marquee {
+    padding-top: 20px;
+    overflow: visible;
+  }
+
+  .landing-marquee-track,
+  .landing-marquee-track.reverse {
+    width: 100%;
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: 12px;
+    animation: none;
+  }
+
+  .landing-stat-chip {
+    width: 100%;
+    min-width: 0;
+    padding: 16px 18px;
+    gap: 12px;
+  }
+
+  .landing-stat-chip strong {
+    font-size: 2rem;
   }
 
   .landing-stat-chip,
diff --git a/apps/web/src/features/outbound/OutboundPage.tsx b/apps/web/src/features/outbound/OutboundPage.tsx
index 517940d..c7c6738 100644
--- a/apps/web/src/features/outbound/OutboundPage.tsx
+++ b/apps/web/src/features/outbound/OutboundPage.tsx
@@ -2,7 +2,9 @@ import { useEffect, useMemo, useState, type FormEvent } from "react";
 import { useSearchParams } from "react-router-dom";
 
 import { Button } from "../../shared/button";
-import { FormField, TextInput } from "../../shared/form";
+import { FilterBar, FilterBarActions } from "../../shared/filter-bar";
+import { FormField, SearchInput } from "../../shared/form";
+import { Page, PageBody, PageHeader, PageMain, PageSidebar, PageToolbar } from "../../shared/page-layout";
 import type { OutboundHistoryItem } from "../inbox/types";
 import { buildOutboundRecords, type OutboundRecord } from "./outboundMockData";
 import { OutboundComposeDrawer } from "./OutboundComposeDrawer";
@@ -115,50 +117,51 @@ export function OutboundPage({ outboundHistory, hasActiveMailbox, onSendMail }:
 
   return (
     <>
-      <main className="workspace-grid outbound-page-grid">
+      <Page as="main" className="workspace-grid outbound-page-grid">
         <section className="panel workspace-card outbound-toolbar-card">
-          <div className="workspace-card-header outbound-toolbar-header">
-            <div>
-              <p className="panel-kicker">邮件中心</p>
-              <h1>发件箱</h1>
-              <p className="section-copy">按发送结果回看历史、定位失败原因，并把异常 / 无匹配记录和正常外发放在同一套工作流里。</p>
-            </div>
-            <div className="workspace-topbar-actions outbound-toolbar-actions">
-              <Button variant="secondary">刷新</Button>
-              <Button onClick={openBlankComposeDrawer} variant="primary">
-                新建发送
-              </Button>
-            </div>
-          </div>
-
-          <div className="outbound-toolbar-row">
-            <FormField className="outbound-search-field" label={<span className="sr-only">发件箱搜索</span>}>
-              <TextInput
-                aria-label="发件箱搜索"
-                onChange={(event) => setSearchValue(event.target.value)}
-                placeholder="搜索收件人 / 主题 / 发件结果"
-                type="search"
-                value={searchValue}
-              />
-            </FormField>
-            <div aria-label="发件箱状态筛选" className="outbound-filter-row" role="toolbar">
-              {(Object.keys(FILTER_LABELS) as OutboundFilter[]).map((filterKey) => (
-                <Button
-                  aria-pressed={filter === filterKey}
-                  isActive={filter === filterKey}
-                  key={filterKey}
-                  onClick={() => setFilter(filterKey)}
-                  variant="ghost"
-                >
-                  {FILTER_LABELS[filterKey]}
+          <PageHeader
+            actions={
+              <div className="workspace-topbar-actions outbound-toolbar-actions">
+                <Button variant="secondary">刷新</Button>
+                <Button onClick={openBlankComposeDrawer} variant="primary">
+                  新建发送
                 </Button>
-              ))}
-            </div>
-          </div>
+              </div>
+            }
+            description="按发送结果回看历史、定位失败原因，并把异常 / 无匹配记录和正常外发放在同一套工作流里。"
+            kicker="邮件中心"
+            title="发件箱"
+          />
+
+          <PageToolbar>
+            <FilterBar className="outbound-toolbar-row" columns={2}>
+              <FormField className="outbound-search-field" label={<span className="sr-only">发件箱搜索</span>}>
+                <SearchInput
+                  aria-label="发件箱搜索"
+                  onChange={(event) => setSearchValue(event.target.value)}
+                  placeholder="搜索收件人 / 主题 / 发件结果"
+                  value={searchValue}
+                />
+              </FormField>
+              <FilterBarActions aria-label="发件箱状态筛选" className="outbound-filter-row" role="toolbar">
+                {(Object.keys(FILTER_LABELS) as OutboundFilter[]).map((filterKey) => (
+                  <Button
+                    aria-pressed={filter === filterKey}
+                    isActive={filter === filterKey}
+                    key={filterKey}
+                    onClick={() => setFilter(filterKey)}
+                    variant="ghost"
+                  >
+                    {FILTER_LABELS[filterKey]}
+                  </Button>
+                ))}
+              </FilterBarActions>
+            </FilterBar>
+          </PageToolbar>
         </section>
 
-        <div className="workspace-grid outbound-main-grid">
-          <section aria-label="发件记录列表" className="panel workspace-card outbound-list-panel" role="region">
+        <PageBody className="workspace-grid outbound-main-grid" hasSidebar>
+          <PageMain aria-label="发件记录列表" className="panel workspace-card outbound-list-panel" role="region">
             <div className="workspace-card-header outbound-section-header">
               <div>
                 <p className="panel-kicker">发送记录</p>
@@ -193,9 +196,9 @@ export function OutboundPage({ outboundHistory, hasActiveMailbox, onSendMail }:
                 </Button>
               ))}
             </div>
-          </section>
+          </PageMain>
 
-          <section aria-label="发件记录详情" className="panel workspace-card outbound-detail-panel" role="region">
+          <PageSidebar aria-label="发件记录详情" className="panel workspace-card outbound-detail-panel" role="region">
             {selectedRecord ? (
               <>
                 <div className="workspace-card-header outbound-section-header">
@@ -268,9 +271,9 @@ export function OutboundPage({ outboundHistory, hasActiveMailbox, onSendMail }:
             ) : (
               <p className="empty-state">当前还没有发件记录。</p>
             )}
-          </section>
-        </div>
-      </main>
+          </PageSidebar>
+        </PageBody>
+      </Page>
 
       <OutboundComposeDrawer
         draft={composeDraft}
diff --git a/apps/web/src/features/settings/ApiKeysPage.tsx b/apps/web/src/features/settings/ApiKeysPage.tsx
index 0c02969..5780120 100644
--- a/apps/web/src/features/settings/ApiKeysPage.tsx
+++ b/apps/web/src/features/settings/ApiKeysPage.tsx
@@ -3,6 +3,7 @@
 import type { ApiKeySummary } from "@wemail/shared";
 import { Button } from "../../shared/button";
 import { FormField, TextInput } from "../../shared/form";
+import { MetricCard } from "../../shared/metric-card";
 
 type CreateApiKeyResult = {
   key: {
@@ -107,45 +108,41 @@ export function ApiKeysPage({ apiKeys, onCreateApiKey, onRevokeApiKey }: ApiKeys
   return (
     <main className="workspace-grid api-keys-layout-grid">
       <section className="api-keys-top-stats" aria-label="API 密钥状态概览">
-        <article className="panel workspace-card page-panel integration-side-card api-keys-stat-card">
-          <p className="panel-kicker api-keys-stat-kicker">总密钥</p>
-          <div className="integration-stat-list">
-            <article className="integration-stat-row">
-              <strong>总数</strong>
-              <span>{summary.totalKeys}</span>
-            </article>
-          </div>
-        </article>
+        <MetricCard
+          className="panel workspace-card page-panel integration-side-card api-keys-stat-card"
+          detail="总数"
+          kicker="总密钥"
+          title="密钥总览"
+          value={summary.totalKeys}
+          valueSize="lg"
+        />
 
-        <article className="panel workspace-card page-panel integration-side-card api-keys-stat-card">
-          <p className="panel-kicker api-keys-stat-kicker">活跃密钥</p>
-          <div className="integration-stat-list">
-            <article className="integration-stat-row">
-              <strong>可用</strong>
-              <span>{summary.activeKeys}</span>
-            </article>
-          </div>
-        </article>
+        <MetricCard
+          className="panel workspace-card page-panel integration-side-card api-keys-stat-card"
+          detail="可用"
+          kicker="活跃密钥"
+          title="当前可用"
+          value={summary.activeKeys}
+          valueSize="lg"
+        />
 
-        <article className="panel workspace-card page-panel integration-side-card api-keys-stat-card">
-          <p className="panel-kicker api-keys-stat-kicker">从未使用</p>
-          <div className="integration-stat-list">
-            <article className="integration-stat-row">
-              <strong>未使用</strong>
-              <span>{summary.unusedKeys}</span>
-            </article>
-          </div>
-        </article>
+        <MetricCard
+          className="panel workspace-card page-panel integration-side-card api-keys-stat-card"
+          detail="未使用"
+          kicker="从未使用"
+          title="待接入"
+          value={summary.unusedKeys}
+          valueSize="lg"
+        />
 
-        <article className="panel workspace-card page-panel integration-side-card api-keys-stat-card">
-          <p className="panel-kicker api-keys-stat-kicker">已吊销</p>
-          <div className="integration-stat-list">
-            <article className="integration-stat-row">
-              <strong>失效</strong>
-              <span>{summary.revokedKeys}</span>
-            </article>
-          </div>
-        </article>
+        <MetricCard
+          className="panel workspace-card page-panel integration-side-card api-keys-stat-card"
+          detail="失效"
+          kicker="已吊销"
+          title="不可用"
+          value={summary.revokedKeys}
+          valueSize="lg"
+        />
       </section>
 
       <div className="api-keys-content-grid">
diff --git a/apps/web/src/pages/DashboardPage.tsx b/apps/web/src/pages/DashboardPage.tsx
index 27e167f..929c6db 100644
--- a/apps/web/src/pages/DashboardPage.tsx
+++ b/apps/web/src/pages/DashboardPage.tsx
@@ -13,6 +13,7 @@ import {
   dashboardUserRoles
 } from "../features/dashboard/dashboardMockData";
 import { nivoTheme } from "../shared/chart";
+import { MetricCard } from "../shared/metric-card";
 
 const GROWTH_KEYS = ["accounts", "mailboxes"] as const;
 const GROWTH_LABELS: Record<(typeof GROWTH_KEYS)[number], string> = {
@@ -62,13 +63,16 @@ export function DashboardPage() {
     <main className="workspace-grid dashboard-grid">
       <section className="dashboard-kpi-grid" aria-label="仪表盘核心指标">
         {dashboardKpis.map((kpi) => (
-          <article className="panel workspace-card dashboard-kpi-card" key={kpi.label}>
-            <p className="panel-kicker">KPI</p>
-            <h2>{kpi.label}</h2>
-            <strong>{kpi.value}</strong>
-            <span>{kpi.detail}</span>
-            <small>{kpi.change}</small>
-          </article>
+          <MetricCard
+            className="panel workspace-card dashboard-kpi-card"
+            caption={kpi.change}
+            detail={kpi.detail}
+            key={kpi.label}
+            kicker="KPI"
+            title={kpi.label}
+            tone="hero"
+            value={kpi.value}
+          />
         ))}
       </section>
 
diff --git a/apps/web/src/pages/DesignSystemPage.tsx b/apps/web/src/pages/DesignSystemPage.tsx
index 8466425..917466f 100644
--- a/apps/web/src/pages/DesignSystemPage.tsx
+++ b/apps/web/src/pages/DesignSystemPage.tsx
@@ -1,182 +1,174 @@
-import type { CSSProperties, ReactNode } from "react";
+import { type CSSProperties, useEffect, useState } from "react";
 
-type SwatchProps = {
-  name: string;
-  hex: string;
-  varName?: string;
-};
+import { type WorkspaceTheme } from "../app/appStore";
+import { PublicSiteNavigation } from "../features/landing/PublicSiteNavigation";
+import { Badge } from "../shared/badge";
+import { DesignSystemDocContent } from "./design-system/DesignSystemDocContent";
+import { DesignSystemPreviewOverlays, DesignSystemSectionList } from "./design-system/DesignSystemPreviewContent";
+import { designSystemGroups } from "./design-system/designSystemContent";
+import { PreviewActionButtons } from "./design-system/designSystemPreviewParts";
+import { designSystemSections, findDesignSystemSection } from "./design-system/designSystemSections";
+import { designSystemPageStyles, designSystemSharedStyles, resolveDesignSystemSidebarLayoutStyle } from "./design-system/designSystemStyles";
 
-function Swatch({ name, hex, varName }: SwatchProps) {
-  const style: CSSProperties = { background: hex };
-  return (
-    <div className="design-swatch">
-      <span aria-hidden="true" className="design-swatch-fill" style={style} />
-      <div className="design-swatch-meta">
-        <strong>{name}</strong>
-        <code>{hex.toUpperCase()}</code>
-        {varName ? <small>{varName}</small> : null}
-      </div>
-    </div>
-  );
-}
+const DESIGN_SYSTEM_THEME_STORAGE_KEY = "wemail-design-system-preview-theme";
 
-type TokenRowProps = {
-  label: string;
-  value: ReactNode;
-  hint?: string;
-};
+function resolveInitialPreviewTheme(): WorkspaceTheme {
+  if (typeof window !== "undefined") {
+    const storedTheme = window.localStorage.getItem(DESIGN_SYSTEM_THEME_STORAGE_KEY);
+    if (storedTheme === "light" || storedTheme === "dark") return storedTheme;
 
-function TokenRow({ label, value, hint }: TokenRowProps) {
-  return (
-    <div className="design-token-row">
-      <div className="design-token-sample">{value}</div>
-      <div className="design-token-meta">
-        <strong>{label}</strong>
-        {hint ? <small>{hint}</small> : null}
-      </div>
-    </div>
-  );
+    if (typeof window.matchMedia === "function") {
+      return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+    }
+  }
+
+  if (typeof document !== "undefined") {
+    const datasetTheme = document.documentElement.dataset.theme;
+    if (datasetTheme === "light" || datasetTheme === "dark") return datasetTheme;
+  }
+
+  return "light";
 }
 
+const groups = designSystemGroups;
+
 export function DesignSystemPage() {
+  const [previewTheme, setPreviewTheme] = useState<WorkspaceTheme>(resolveInitialPreviewTheme);
+  const [isDialogOpen, setIsDialogOpen] = useState(false);
+  const [isDrawerOpen, setIsDrawerOpen] = useState(false);
+  const initialGroup = groups[0];
+  const initialComponent = initialGroup?.components[0] ?? null;
+  const [activeGroupId, setActiveGroupId] = useState(initialGroup?.id ?? "foundations");
+  const [activeComponentId, setActiveComponentId] = useState<string | null>(initialComponent?.id ?? null);
+  const [sidebarLayoutStyle, setSidebarLayoutStyle] = useState<CSSProperties>(resolveDesignSystemSidebarLayoutStyle);
+
+  const activeGroup = groups.find((group) => group.id === activeGroupId) ?? groups[0];
+  const activeComponent = activeGroup?.components.find((component) => component.id === activeComponentId) ?? activeGroup?.components[0] ?? null;
+
+  function togglePreviewTheme() {
+    setPreviewTheme((current) => (current === "dark" ? "light" : "dark"));
+  }
+
+  function handleSelectComponent(groupId: string, componentId: string) {
+    setActiveGroupId(groupId);
+    setActiveComponentId(componentId);
+  }
+
+  useEffect(() => {
+    const previousTheme = document.documentElement.dataset.theme;
+    const previousColorScheme = document.documentElement.style.colorScheme;
+
+    document.documentElement.dataset.theme = previewTheme;
+    document.documentElement.style.colorScheme = previewTheme;
+    window.localStorage.setItem(DESIGN_SYSTEM_THEME_STORAGE_KEY, previewTheme);
+
+    return () => {
+      if (previousTheme === "light" || previousTheme === "dark") {
+        document.documentElement.dataset.theme = previousTheme;
+      } else {
+        delete document.documentElement.dataset.theme;
+      }
+
+      document.documentElement.style.colorScheme = previousColorScheme;
+    };
+  }, [previewTheme]);
+
+  useEffect(() => {
+    function handleResize() {
+      setSidebarLayoutStyle(resolveDesignSystemSidebarLayoutStyle());
+    }
+
+    handleResize();
+    window.addEventListener("resize", handleResize);
+
+    return () => {
+      window.removeEventListener("resize", handleResize);
+    };
+  }, []);
+
   return (
-    <main className="workspace-grid design-system-grid">
-      <section className="panel workspace-card page-panel design-system-panel">
-        <p className="panel-kicker">WeMail UI 系统 · v1.0</p>
-        <h2>WeMail 设计系统</h2>
-        <p className="section-copy">
-          一套简洁、现代、易用的界面规范。所有组件与样式均基于此页展示的设计原则、色彩、字号、间距、圆角与阴影
-          token 构建；新功能应优先从这里取用原语与变量,避免在业务层重造样式。
-        </p>
-      </section>
-
-      <section className="panel workspace-card page-panel design-system-panel">
-        <p className="panel-kicker">设计原则</p>
-        <h2>四个不变量</h2>
-        <div className="design-principle-grid">
-          <article>
-            <strong>简洁清晰</strong>
-            <span>减少视觉干扰,一屏只解决一件事。</span>
-          </article>
-          <article>
-            <strong>一致性</strong>
-            <span>相同操作使用相同组件与状态表达。</span>
-          </article>
-          <article>
-            <strong>易用性</strong>
-            <span>优先键盘可达与屏幕阅读器语义。</span>
-          </article>
-          <article>
-            <strong>可扩展</strong>
-            <span>原语遵守 forwardRef + className + state 约定,便于组合。</span>
-          </article>
-        </div>
-      </section>
-
-      <section className="panel workspace-card page-panel design-system-panel">
-        <p className="panel-kicker">色彩系统</p>
-        <h2>品牌与语义色</h2>
-        <div className="design-swatch-grid">
-          <Swatch name="主色" hex="#ff7a00" varName="--brand-500" />
-          <Swatch name="辅助色" hex="#ffb366" varName="--brand-soft-500" />
-          <Swatch name="成功色" hex="#22c55e" varName="--success-500" />
-          <Swatch name="警告色" hex="#f59e0b" varName="--warning-500" />
-          <Swatch name="错误色" hex="#ef4444" varName="--danger-500" />
-          <Swatch name="中性色" hex="#6b7280" varName="--neutral-500" />
-        </div>
-      </section>
-
-      <section className="panel workspace-card page-panel design-system-panel">
-        <p className="panel-kicker">间距系统</p>
-        <h2>4px 网格</h2>
-        <div className="design-spacing-row">
-          {[4, 8, 12, 16, 20, 24, 32, 40, 48, 56, 64, 72, 80, 96, 112, 128].map((value) => (
-            <div className="design-spacing-item" key={value}>
-              <span aria-hidden="true" className="design-spacing-bar" style={{ width: value }} />
-              <code>{value}</code>
-            </div>
-          ))}
-        </div>
-      </section>
-
-      <section className="panel workspace-card page-panel design-system-panel">
-        <p className="panel-kicker">圆角系统</p>
-        <h2>6 档梯度</h2>
-        <div className="design-radius-grid">
-          <TokenRow
-            label="xs · 4px"
-            value={<span className="design-radius-demo" style={{ borderRadius: 4 }} />}
-            hint="--radius-xs · 内嵌边框、标签边缘"
-          />
-          <TokenRow
-            label="sm · 8px"
-            value={<span className="design-radius-demo" style={{ borderRadius: 8 }} />}
-            hint="--radius-sm · 小按钮、输入内部"
-          />
-          <TokenRow
-            label="md · 12px"
-            value={<span className="design-radius-demo" style={{ borderRadius: 12 }} />}
-            hint="--radius-md · 一般按钮、标签页头部"
-          />
-          <TokenRow
-            label="lg · 16px"
-            value={<span className="design-radius-demo" style={{ borderRadius: 16 }} />}
-            hint="--radius-lg · 输入框、卡片内嵌"
-          />
-          <TokenRow
-            label="xl · 24px"
-            value={<span className="design-radius-demo" style={{ borderRadius: 24 }} />}
-            hint="--radius-xl · 卡片外壳"
-          />
-          <TokenRow
-            label="full · 9999px"
-            value={<span className="design-radius-demo" style={{ borderRadius: 9999 }} />}
-            hint="--radius-full · 头像、pill、switch 轨道"
-          />
-        </div>
-      </section>
-
-      <section className="panel workspace-card page-panel design-system-panel">
-        <p className="panel-kicker">阴影系统</p>
-        <h2>5 档层级</h2>
-        <div className="design-shadow-grid">
-          {[
-            { name: "xs", varName: "--elevation-xs" },
-            { name: "sm", varName: "--elevation-sm" },
-            { name: "md", varName: "--elevation-md" },
-            { name: "lg", varName: "--elevation-lg" },
-            { name: "xl", varName: "--elevation-xl" }
-          ].map(({ name, varName }) => (
-            <div className="design-shadow-card" key={name} style={{ boxShadow: `var(${varName})` }}>
-              <strong>{name}</strong>
-              <code>{varName}</code>
+    <div className="design-system-public-page" data-testid="design-system-page">
+      <PublicSiteNavigation onToggleTheme={togglePreviewTheme} theme={previewTheme} />
+      <main className="design-system-grid" style={{ ...designSystemPageStyles.shell, display: "grid", gap: "20px" }}>
+        <section className="panel workspace-card page-panel design-system-panel" style={designSystemPageStyles.hero}>
+          <div style={{ ...designSystemSharedStyles.stack, gap: "12px" }}>
+            <p className="panel-kicker" style={{ margin: 0, alignSelf: "start" }}>
+              WeMail Design System v1
+            </p>
+            <div style={{ ...designSystemSharedStyles.chipRow, justifyContent: "space-between", alignItems: "center" }}>
+              <div style={designSystemSharedStyles.chipRow}>
+                <span style={designSystemPageStyles.emphasisChip}>{`${groups.length} groups`}</span>
+                <span style={designSystemSharedStyles.chip}>{`${designSystemSections.length} sections`}</span>
+                <span style={designSystemSharedStyles.chip}>/design-system</span>
+              </div>
+              <div style={designSystemSharedStyles.chipRow}>
+                <Badge variant={previewTheme === "dark" ? "info" : "warning"}>{previewTheme === "dark" ? "深色模式" : "浅色模式"}</Badge>
+                <PreviewActionButtons onOpenDialog={() => setIsDialogOpen(true)} onOpenDrawer={() => setIsDrawerOpen(true)} />
+              </div>
             </div>
-          ))}
-        </div>
-      </section>
-
-      <section className="panel workspace-card page-panel design-system-panel">
-        <p className="panel-kicker">字号系统</p>
-        <h2>7 档语义字号</h2>
-        <div className="design-typography-grid">
-          <div style={{ fontSize: 48, lineHeight: 1.1 }}>显示大号 · 48/1.1</div>
-          <div style={{ fontSize: 32, lineHeight: 1.2 }}>显示中号 · 32/1.2</div>
-          <div style={{ fontSize: 24, lineHeight: 1.3 }}>标题大号 · 24/1.3</div>
-          <div style={{ fontSize: 20, lineHeight: 1.35 }}>标题中号 · 20/1.35</div>
-          <div style={{ fontSize: 16, lineHeight: 1.55 }}>正文大号 · 16/1.55</div>
-          <div style={{ fontSize: 14, lineHeight: 1.55 }}>正文中号 · 14/1.55</div>
-          <div style={{ fontSize: 12, lineHeight: 1.45 }}>辅助说明 · 12/1.45</div>
+          </div>
+        </section>
+
+        <div style={sidebarLayoutStyle}>
+          <aside className="workspace-rail-shell" aria-label="design system sidebar shell" style={designSystemPageStyles.sidebarShell}>
+            <nav className="workspace-rail workspace-scroll-area" aria-label="Design system sidebar" style={designSystemPageStyles.sidebarNav}>
+              {groups.map((group) => (
+                <section className="workspace-rail-section" key={group.id} style={designSystemPageStyles.sidebarGroup}>
+                  <p className="panel-kicker" style={designSystemPageStyles.sidebarGroupHeader}>{group.title}</p>
+                  <div className="workspace-rail-list" style={designSystemPageStyles.sidebarGroupList}>
+                    {group.components.map((component) => {
+                      const isActiveComponent = group.id === activeGroupId && component.id === activeComponentId;
+
+                      return (
+                        <button
+                          key={component.id}
+                          aria-current={isActiveComponent ? "page" : undefined}
+                          aria-label={component.title}
+                          className="workspace-rail-link"
+                          onClick={() => handleSelectComponent(group.id, component.id)}
+                          style={{
+                            ...designSystemPageStyles.sidebarButton,
+                            ...(isActiveComponent ? designSystemPageStyles.sidebarButtonActive : null)
+                          }}
+                          type="button"
+                        >
+                          <span className="workspace-rail-icon-chip" aria-hidden="true">
+                            <span style={designSystemPageStyles.sidebarDot} />
+                          </span>
+                          <div className="workspace-rail-copy">
+                            <span>{component.title}</span>
+                            <small>{component.chineseTitle}</small>
+                          </div>
+                        </button>
+                      );
+                    })}
+                  </div>
+                </section>
+              ))}
+            </nav>
+          </aside>
+
+          <div style={{ display: "grid", gap: "24px" }}>
+            {activeComponent ? (
+              <>
+                <DesignSystemDocContent
+                  componentDoc={activeComponent}
+                  groupTitle={activeGroup?.title ?? "Design system"}
+                  sectionTitles={activeComponent.sectionIds.map((sectionId) => findDesignSystemSection(sectionId).title)}
+                />
+                <DesignSystemSectionList sectionIds={activeComponent.sectionIds} />
+              </>
+            ) : null}
+          </div>
         </div>
-      </section>
-
-      <section className="panel workspace-card page-panel design-system-panel">
-        <p className="panel-kicker">组件库</p>
-        <h2>原语预览</h2>
-        <p className="section-copy">
-          所有原语（Button / Form / Table / Switch / Tabs 等）将在后续 Sprint 陆续接入本页。目前可以查看各自仓库目录下的
-          README：<code>apps/web/src/shared/</code>。
-        </p>
-      </section>
-    </main>
+
+        <DesignSystemPreviewOverlays
+          isDialogOpen={isDialogOpen}
+          isDrawerOpen={isDrawerOpen}
+          onCloseDialog={() => setIsDialogOpen(false)}
+          onCloseDrawer={() => setIsDrawerOpen(false)}
+        />
+      </main>
+    </div>
   );
 }
diff --git a/apps/web/src/pages/SystemProfilePage.tsx b/apps/web/src/pages/SystemProfilePage.tsx
index e559bb5..adbced8 100644
--- a/apps/web/src/pages/SystemProfilePage.tsx
+++ b/apps/web/src/pages/SystemProfilePage.tsx
@@ -1,5 +1,8 @@
+import { Avatar } from "../shared/avatar";
 import { Button } from "../shared/button";
 import { FormField, RadioGroupField, SelectInput, TextInput, TextareaInput } from "../shared/form";
+import { KVList } from "../shared/kv-list";
+import { Page, PageHeader } from "../shared/page-layout";
 
 type SystemProfilePageProps = {
   sessionSummary: {
@@ -11,18 +14,16 @@ type SystemProfilePageProps = {
 
 export function SystemProfilePage({ sessionSummary }: SystemProfilePageProps) {
   return (
-    <main className="workspace-grid profile-settings-grid">
+    <Page as="main" className="workspace-grid profile-settings-grid">
       <section className="panel workspace-card page-panel profile-settings-panel profile-settings-panel-identity">
-        <div className="profile-settings-copy">
-          <p className="panel-kicker">账号资料</p>
-          <h2>你的账户信息</h2>
-          <p className="section-copy">集中维护你的展示身份与基础资料，保持对外沟通时的一致性。</p>
-        </div>
+        <PageHeader
+          description="集中维护你的展示身份与基础资料，保持对外沟通时的一致性。"
+          kicker="账号资料"
+          title="你的账户信息"
+        />
 
         <div className="profile-identity-row">
-          <span className="profile-avatar" aria-hidden="true">
-            W
-          </span>
+          <Avatar aria-label="当前用户头像" fallback="W" name="WeMail Admin" size="lg" />
           <div className="profile-identity-copy">
             <strong>WeMail Admin</strong>
             <span>{sessionSummary.email}</span>
@@ -41,14 +42,12 @@ export function SystemProfilePage({ sessionSummary }: SystemProfilePageProps) {
             <TextInput aria-label="邮箱" disabled value={sessionSummary.email} />
           </FormField>
           <div className="profile-meta-grid">
-            <div className="profile-meta-card">
-              <small>角色</small>
-              <strong>{sessionSummary.role}</strong>
-            </div>
-            <div className="profile-meta-card">
-              <small>创建时间</small>
-              <strong>{sessionSummary.createdAtLabel}</strong>
-            </div>
+            <KVList
+              items={[
+                { key: "角色", value: sessionSummary.role },
+                { key: "创建时间", value: sessionSummary.createdAtLabel }
+              ]}
+            />
           </div>
         </div>
 
@@ -59,11 +58,11 @@ export function SystemProfilePage({ sessionSummary }: SystemProfilePageProps) {
       </section>
 
       <section className="panel workspace-card page-panel profile-settings-panel">
-        <div className="profile-settings-copy">
-          <p className="panel-kicker">使用偏好</p>
-          <h2>按你的工作方式来调整界面</h2>
-          <p className="section-copy">这些设置会影响你进入 WeMail 后默认看到的节奏与信息密度。</p>
-        </div>
+        <PageHeader
+          description="这些设置会影响你进入 WeMail 后默认看到的节奏与信息密度。"
+          kicker="使用偏好"
+          title="按你的工作方式来调整界面"
+        />
 
         <div className="profile-preference-list">
           <FormField
@@ -132,11 +131,11 @@ export function SystemProfilePage({ sessionSummary }: SystemProfilePageProps) {
       </section>
 
       <section className="panel workspace-card page-panel profile-settings-panel">
-        <div className="profile-settings-copy">
-          <p className="panel-kicker">安全与会话</p>
-          <h2>管理密码和当前登录状态</h2>
-          <p className="section-copy">优先显示你当前的会话信息，并把高风险操作收拢到同一个动作区。</p>
-        </div>
+        <PageHeader
+          description="优先显示你当前的会话信息，并把高风险操作收拢到同一个动作区。"
+          kicker="安全与会话"
+          title="管理密码和当前登录状态"
+        />
 
         <div className="profile-security-list">
           <div className="profile-security-row">
@@ -156,6 +155,6 @@ export function SystemProfilePage({ sessionSummary }: SystemProfilePageProps) {
           <Button variant="secondary">退出其他设备</Button>
         </div>
       </section>
-    </main>
+    </Page>
   );
 }
diff --git a/apps/web/src/pages/UsersGlobalSettingsPage.tsx b/apps/web/src/pages/UsersGlobalSettingsPage.tsx
index 57b7639..26ef214 100644
--- a/apps/web/src/pages/UsersGlobalSettingsPage.tsx
+++ b/apps/web/src/pages/UsersGlobalSettingsPage.tsx
@@ -7,6 +7,7 @@ import { InvitePanel } from "../features/admin/InvitePanel";
 import { MailboxOversightPanel } from "../features/admin/MailboxOversightPanel";
 import { QuotaPanel } from "../features/admin/QuotaPanel";
 import type { InviteSummary } from "../features/admin/types";
+import { Page, PageHeader, PageMain } from "../shared/page-layout";
 
 type UsersGlobalSettingsPageProps = {
   adminUsers: UserSummary[];
@@ -34,16 +35,16 @@ export function UsersGlobalSettingsPage({
   onToggleFeatures
 }: UsersGlobalSettingsPageProps) {
   return (
-    <main className="workspace-grid users-global-grid">
+    <Page as="main" className="workspace-grid users-global-grid">
       <section className="panel workspace-card page-panel users-page-header">
-        <div className="users-page-header-copy">
-          <p className="panel-kicker">用户设置</p>
-          <h2>全局控制</h2>
-          <p className="section-copy">集中管理邀请码、系统级配额、全局功能开关和邮箱总览。</p>
-        </div>
+        <PageHeader
+          description="集中管理邀请码、系统级配额、全局功能开关和邮箱总览。"
+          kicker="用户设置"
+          title="全局控制"
+        />
       </section>
 
-      <div className="users-global-panels">
+      <PageMain className="users-global-panels">
         <InvitePanel adminInvites={adminInvites} onCreateInvite={onCreateInvite} onDisableInvite={onDisableInvite} />
         <QuotaPanel
           adminUsers={adminUsers}
@@ -53,7 +54,7 @@ export function UsersGlobalSettingsPage({
         />
         <FeatureTogglesPanel adminFeatures={adminFeatures} onToggleFeatures={onToggleFeatures} />
         <MailboxOversightPanel adminMailboxes={adminMailboxes} />
-      </div>
-    </main>
+      </PageMain>
+    </Page>
   );
-}
\ No newline at end of file
+}
diff --git a/apps/web/src/pages/UsersListPage.tsx b/apps/web/src/pages/UsersListPage.tsx
index 07acbc3..2279586 100644
--- a/apps/web/src/pages/UsersListPage.tsx
+++ b/apps/web/src/pages/UsersListPage.tsx
@@ -3,8 +3,11 @@ import { useState, type FormEvent } from "react";
 import type { QuotaSummary, UserSummary } from "@wemail/shared";
 
 import { Button } from "../shared/button";
-import { CheckboxField, FormField, SelectInput, TextInput } from "../shared/form";
+import { Badge } from "../shared/badge";
+import { FilterBar } from "../shared/filter-bar";
+import { CheckboxField, FormField, SearchInput, SelectInput } from "../shared/form";
 import { OverlayDrawer } from "../shared/overlay";
+import { Page, PageBody, PageHeader, PageMain, PageSidebar, PageToolbar } from "../shared/page-layout";
 import {
   Table,
   TableBody,
@@ -87,126 +90,141 @@ export function UsersListPage({
   }
 
   return (
-    <main className="workspace-grid users-list-grid">
+    <Page className="workspace-grid users-list-grid">
       <section className="panel workspace-card page-panel users-page-header">
-        <div className="workspace-card-header">
-          <div>
-            <p className="panel-kicker">用户中心</p>
-          </div>
-          <div className="workspace-topbar-actions">
-            <Button variant="primary">导出</Button>
-          </div>
-        </div>
-
-        <div className="users-list-filter-grid">
-          <FormField label={<span className="sr-only">搜索用户</span>}>
-            <TextInput
-              aria-label="搜索用户"
-              onChange={(event) => onSearchChange(event.target.value)}
-              placeholder="搜索邮箱或显示名"
-              value={searchValue}
-            />
-          </FormField>
-
-          <FormField label={<span className="sr-only">角色筛选</span>}>
-            <SelectInput aria-label="角色筛选" onChange={(event) => onRoleFilterChange(event.target.value as UsersRoleFilter)} value={roleFilter}>
-              <option value="all">全部</option>
-              <option value="admin">管理员</option>
-              <option value="member">成员</option>
-            </SelectInput>
-          </FormField>
-
-          <FormField label={<span className="sr-only">状态筛选</span>}>
-            <SelectInput aria-label="状态筛选" onChange={(event) => onStatusFilterChange(event.target.value as UsersStatusFilter)} value={statusFilter}>
-              <option value="all">全部</option>
-              <option value="active">正常</option>
-            </SelectInput>
-          </FormField>
-        </div>
+        <PageHeader
+          actions={
+            <div className="workspace-topbar-actions">
+              <Button variant="primary">导出</Button>
+            </div>
+          }
+          kicker="用户中心"
+        />
+
+        <PageToolbar>
+          <FilterBar className="users-list-filter-grid" columns={3}>
+            <FormField label={<span className="sr-only">搜索用户</span>}>
+              <SearchInput
+                aria-label="搜索用户"
+                onChange={(event) => onSearchChange(event.target.value)}
+                placeholder="搜索邮箱或显示名"
+                value={searchValue}
+              />
+            </FormField>
+
+            <FormField label={<span className="sr-only">角色筛选</span>}>
+              <SelectInput aria-label="角色筛选" onChange={(event) => onRoleFilterChange(event.target.value as UsersRoleFilter)} value={roleFilter}>
+                <option value="all">全部</option>
+                <option value="admin">管理员</option>
+                <option value="member">成员</option>
+              </SelectInput>
+            </FormField>
+
+            <FormField label={<span className="sr-only">状态筛选</span>}>
+              <SelectInput aria-label="状态筛选" onChange={(event) => onStatusFilterChange(event.target.value as UsersStatusFilter)} value={statusFilter}>
+                <option value="all">全部</option>
+                <option value="active">正常</option>
+              </SelectInput>
+            </FormField>
+          </FilterBar>
+        </PageToolbar>
       </section>
 
-      <section className="panel workspace-card page-panel users-table-panel">
-        <div className="workspace-card-header">
-          <div>
-            <p className="panel-kicker">用户列表</p>
+      <PageBody hasSidebar>
+        <PageMain className="panel workspace-card page-panel users-table-panel">
+          <div className="workspace-card-header">
+            <div>
+              <p className="panel-kicker">用户列表</p>
+            </div>
           </div>
-        </div>
-
-        {selectedCount > 0 ? (
-          <section aria-label="用户批量操作条" className="panel workspace-card accounts-list-bulk-bar">
-            <div className="workspace-card-header">
-              <div>
-                <p className="panel-kicker">批量操作</p>
-                <h4>已选择 {selectedCount} 个用户</h4>
-              </div>
-              <div className="workspace-topbar-actions">
-                <Button variant="primary">批量设为管理员</Button>
-                <Button variant="secondary">批量设为成员</Button>
-                <Button variant="secondary">批量暂停外发</Button>
-              </div>
+
+          {selectedCount > 0 ? (
+            <section aria-label="用户批量操作条" className="panel workspace-card accounts-list-bulk-bar">
+              <PageHeader
+                actions={
+                  <div className="workspace-topbar-actions">
+                    <Button variant="primary">批量设为管理员</Button>
+                    <Button variant="secondary">批量设为成员</Button>
+                    <Button variant="secondary">批量暂停外发</Button>
+                  </div>
+                }
+                kicker="批量操作"
+                title={`已选择 ${selectedCount} 个用户`}
+              />
+            </section>
+          ) : null}
+
+          <TableContainer density="compact" variant="liquid">
+            <Table className="users-list-table">
+              <TableHead>
+                <TableRow>
+                  <TableHeaderCell align="center" className="ui-table-sticky-start" width={56}>
+                    <CheckboxField
+                      aria-label="选择全部用户"
+                      checked={allVisibleSelected}
+                      className="checkbox-row"
+                      label={<span className="sr-only">选择全部用户</span>}
+                      onChange={toggleSelectAll}
+                    />
+                  </TableHeaderCell>
+                  <TableHeaderCell>用户</TableHeaderCell>
+                  <TableHeaderCell>邮箱</TableHeaderCell>
+                  <TableHeaderCell>角色</TableHeaderCell>
+                  <TableHeaderCell>创建时间</TableHeaderCell>
+                  <TableHeaderCell>状态</TableHeaderCell>
+                  <TableHeaderCell className="ui-table-sticky-end" nowrap width={112}>
+                    操作
+                  </TableHeaderCell>
+                </TableRow>
+              </TableHead>
+              <TableBody>
+                {visibleUsers.map((user) => {
+                  const isSelected = selectedUserIds.includes(user.id);
+
+                  return (
+                    <TableRow isSelected={isSelected} key={user.id}>
+                      <TableCell align="center" className="ui-table-sticky-start" width={56}>
+                        <CheckboxField
+                          aria-label={`选择用户 ${user.email}`}
+                          checked={isSelected}
+                          className="checkbox-row"
+                          label={<span className="sr-only">选择用户 {user.email}</span>}
+                          onChange={() => toggleUserSelection(user.id)}
+                        />
+                      </TableCell>
+                      <TableCell>
+                        <strong>{buildDisplayName(user.email)}</strong>
+                      </TableCell>
+                      <TableCell>{user.email}</TableCell>
+                      <TableCell>{formatRole(user.role)}</TableCell>
+                      <TableCell>{user.createdAt.slice(0, 10)}</TableCell>
+                      <TableCell>
+                        <Badge variant="success">正常</Badge>
+                      </TableCell>
+                      <TableCell className="ui-table-sticky-end" nowrap width={112}>
+                        <Button onClick={() => onOpenUserSettings(user.id)} size="sm" variant="secondary">
+                          查看设置
+                        </Button>
+                      </TableCell>
+                    </TableRow>
+                  );
+                })}
+              </TableBody>
+            </Table>
+          </TableContainer>
+        </PageMain>
+
+        <PageSidebar>
+          <section className="panel workspace-card page-panel users-table-panel">
+            <p className="panel-kicker">筛选摘要</p>
+            <div className="accounts-list-status-cell">
+              <div className="section-copy">可见用户：{visibleUsers.length}</div>
+              <div className="section-copy">已选用户：{selectedCount}</div>
+              <div className="section-copy">角色筛选：{roleFilter === "all" ? "全部" : formatRole(roleFilter)}</div>
             </div>
           </section>
-        ) : null}
-
-        <TableContainer density="compact" variant="liquid">
-          <Table className="users-list-table">
-            <TableHead>
-              <TableRow>
-                <TableHeaderCell align="center" className="ui-table-sticky-start" width={56}>
-                  <CheckboxField
-                    aria-label="选择全部用户"
-                    checked={allVisibleSelected}
-                    className="checkbox-row"
-                    label={<span className="sr-only">选择全部用户</span>}
-                    onChange={toggleSelectAll}
-                  />
-                </TableHeaderCell>
-                <TableHeaderCell>用户</TableHeaderCell>
-                <TableHeaderCell>邮箱</TableHeaderCell>
-                <TableHeaderCell>角色</TableHeaderCell>
-                <TableHeaderCell>创建时间</TableHeaderCell>
-                <TableHeaderCell>状态</TableHeaderCell>
-                <TableHeaderCell className="ui-table-sticky-end" nowrap width={112}>
-                  操作
-                </TableHeaderCell>
-              </TableRow>
-            </TableHead>
-            <TableBody>
-              {visibleUsers.map((user) => {
-                const isSelected = selectedUserIds.includes(user.id);
-
-                return (
-                  <TableRow isSelected={isSelected} key={user.id}>
-                    <TableCell align="center" className="ui-table-sticky-start" width={56}>
-                      <CheckboxField
-                        aria-label={`选择用户 ${user.email}`}
-                        checked={isSelected}
-                        className="checkbox-row"
-                        label={<span className="sr-only">选择用户 {user.email}</span>}
-                        onChange={() => toggleUserSelection(user.id)}
-                      />
-                    </TableCell>
-                    <TableCell>
-                      <strong>{buildDisplayName(user.email)}</strong>
-                    </TableCell>
-                    <TableCell>{user.email}</TableCell>
-                    <TableCell>{formatRole(user.role)}</TableCell>
-                    <TableCell>{user.createdAt.slice(0, 10)}</TableCell>
-                    <TableCell>
-                      <span className="accounts-status-pill accounts-status-pill--enabled">正常</span>
-                    </TableCell>
-                    <TableCell className="ui-table-sticky-end" nowrap width={112}>
-                      <Button onClick={() => onOpenUserSettings(user.id)} size="sm" variant="secondary">
-                        查看设置
-                      </Button>
-                    </TableCell>
-                  </TableRow>
-                );
-              })}
-            </TableBody>
-          </Table>
-        </TableContainer>
-      </section>
+        </PageSidebar>
+      </PageBody>
 
       {selectedUser ? (
         <OverlayDrawer
@@ -249,6 +267,6 @@ export function UsersListPage({
           </div>
         </OverlayDrawer>
       ) : null}
-    </main>
+    </Page>
   );
 }
diff --git a/apps/web/src/pages/design-system/DesignSystemDocContent.tsx b/apps/web/src/pages/design-system/DesignSystemDocContent.tsx
new file mode 100644
index 0000000..424215f
--- /dev/null
+++ b/apps/web/src/pages/design-system/DesignSystemDocContent.tsx
@@ -0,0 +1,161 @@
+import type { DesignSystemApiField, DesignSystemCodeSample, DesignSystemComponentDoc, DesignSystemDocSection } from "./designSystemContent";
+import { designSystemDocStyles, designSystemSharedStyles } from "./designSystemStyles";
+
+interface DesignSystemDocContentProps {
+  componentDoc: DesignSystemComponentDoc;
+  groupTitle: string;
+  sectionTitles: string[];
+}
+
+const COMPONENT_SECTION_ORDER = ["真实示例", "API 接口", "使用说明", "设计规范"] as const;
+
+type ComponentSectionTitle = (typeof COMPONENT_SECTION_ORDER)[number];
+
+function renderParagraphs(paragraphs: string[]) {
+  return (
+    <div style={designSystemDocStyles.paragraphGroup}>
+      {paragraphs.map((paragraph) => (
+        <p className="section-copy" key={paragraph} style={{ margin: 0 }}>
+          {paragraph}
+        </p>
+      ))}
+    </div>
+  );
+}
+
+function getSectionBodyMap(docSections?: DesignSystemDocSection[]): Map<string, string[]> {
+  return new Map((docSections ?? []).map((section) => [section.title, section.body]));
+}
+
+function renderCodeSamples(codeSamples: DesignSystemCodeSample[]) {
+  return (
+    <div style={designSystemDocStyles.codeSampleList}>
+      {codeSamples.map((sample) => (
+        <article key={sample.title} style={designSystemDocStyles.codeSampleCard}>
+          <h3 style={designSystemDocStyles.codeSampleHeading}>{sample.title}</h3>
+          <pre style={designSystemDocStyles.codeSamplePre}>
+            <code>{sample.code}</code>
+          </pre>
+        </article>
+      ))}
+    </div>
+  );
+}
+
+function renderApiTable(apiFields: DesignSystemApiField[]) {
+  return (
+    <div style={{ overflowX: "auto" }}>
+      <table style={{ width: "100%", borderCollapse: "collapse" }}>
+        <thead>
+          <tr>
+            <th align="left" scope="col">prop</th>
+            <th align="left" scope="col">type</th>
+            <th align="left" scope="col">default</th>
+            <th align="left" scope="col">description</th>
+          </tr>
+        </thead>
+        <tbody>
+          {apiFields.map((field) => (
+            <tr key={field.prop}>
+              <td>{field.prop}</td>
+              <td>
+                <code>{field.type}</code>
+              </td>
+              <td>
+                <code>{field.defaultValue}</code>
+              </td>
+              <td>{field.description}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+function getComponentSections(componentDoc: DesignSystemComponentDoc, sectionTitles: string[]): Array<{ title: ComponentSectionTitle; body: string[] }> {
+  const sectionBodyMap = getSectionBodyMap(componentDoc.docSections);
+  const designNoteBodies = (componentDoc.docSections ?? [])
+    .filter((section) => !["适用场景", "不适用场景", "状态与变体", "设计规范"].includes(section.title))
+    .flatMap((section) => section.body);
+
+  const usageBody = [
+    componentDoc.summary,
+    ...(sectionBodyMap.get("适用场景") ?? ["当前文档内容仍在补齐中，现阶段请先结合真实示例确认适用场景。"]),
+    ...(sectionBodyMap.get("不适用场景") ?? ["当当前任务只需要文本跳转或静态信息承载时，应优先考虑更轻量的原语。"])
+  ];
+
+  const fallbackByTitle: Record<ComponentSectionTitle, string[]> = {
+    "真实示例": ["下方会继续保留该组件关联的 live preview，用来验证真实交互与文档说明是否一致。"],
+    "API 接口": [
+      "API 表结构会在后续任务中补齐；当前阶段先固定阅读顺序与占位区块。",
+      componentDoc.codeSamples?.length ? "当前可先参考下方代码示例了解已接入的调用方式。" : "当前组件的调用方式将在后续任务中补充为结构化 API 表。"
+    ],
+    "使用说明": usageBody,
+    "设计规范":
+      sectionBodyMap.get("设计规范") ??
+      sectionBodyMap.get("状态与变体") ??
+      (sectionTitles.length
+        ? [`当前页面优先覆盖 ${sectionTitles.join("、")} 相关的状态与变体预览。`]
+        : designNoteBodies.length
+          ? designNoteBodies
+          : ["设计规范会持续沉淀到统一模板中，避免组件说明散落在页面实现里。"])
+  };
+
+  return COMPONENT_SECTION_ORDER.map((title) => ({
+    title,
+    body: fallbackByTitle[title]
+  }));
+}
+
+export function DesignSystemDocContent({ componentDoc, groupTitle, sectionTitles }: DesignSystemDocContentProps) {
+  const sections = getComponentSections(componentDoc, sectionTitles);
+
+  return (
+    <section className="panel workspace-card page-panel design-system-panel" style={{ ...designSystemDocStyles.shell, ...designSystemSharedStyles.stack }}>
+      <header style={designSystemDocStyles.header}>
+        <p className="panel-kicker">{groupTitle} / Component</p>
+        <h1 style={{ margin: 0 }}>{componentDoc.title}</h1>
+        <strong style={{ color: "var(--text, #111827)" }}>{componentDoc.chineseTitle}</strong>
+        <div style={designSystemSharedStyles.chipRow}>
+          {sectionTitles.map((sectionTitle) => (
+            <span key={sectionTitle} style={designSystemSharedStyles.chip}>
+              {sectionTitle}
+            </span>
+          ))}
+        </div>
+      </header>
+      <div style={designSystemDocStyles.sectionList}>
+        {sections.map((section) => {
+          const isExampleSection = section.title === "真实示例";
+          const isGuidanceSection = section.title === "API 接口" || section.title === "设计规范";
+
+          return (
+            <section
+              aria-label={`文档章节：${section.title}`}
+              key={section.title}
+              style={{
+                ...designSystemDocStyles.section,
+                ...(isExampleSection ? designSystemDocStyles.exampleNote : null),
+                ...(isGuidanceSection ? designSystemDocStyles.guidanceNote : null)
+              }}
+            >
+              <h2 style={designSystemDocStyles.sectionHeading}>{section.title}</h2>
+              {section.title === "API 接口" && componentDoc.api?.length ? renderApiTable(componentDoc.api) : renderParagraphs(section.body)}
+            </section>
+          );
+        })}
+        {componentDoc.codeSamples?.length ? (
+          <section
+            aria-label={`代码示例：${componentDoc.title}`}
+            role="region"
+            style={{ ...designSystemDocStyles.section, ...designSystemDocStyles.guidanceNote }}
+          >
+            <h2 style={designSystemDocStyles.sectionHeading}>代码示例</h2>
+            {renderCodeSamples(componentDoc.codeSamples)}
+          </section>
+        ) : null}
+      </div>
+    </section>
+  );
+}
diff --git a/apps/web/src/pages/design-system/DesignSystemPreviewContent.tsx b/apps/web/src/pages/design-system/DesignSystemPreviewContent.tsx
new file mode 100644
index 0000000..d448125
--- /dev/null
+++ b/apps/web/src/pages/design-system/DesignSystemPreviewContent.tsx
@@ -0,0 +1,143 @@
+import { Alert } from "../../shared/alert";
+import { Button } from "../../shared/button";
+import { SearchInput } from "../../shared/form";
+import { KVList } from "../../shared/kv-list";
+import { OverlayDialog, OverlayDrawer } from "../../shared/overlay";
+import { Text } from "../../shared/typography";
+import type { DesignSystemSectionId } from "./designSystemContent";
+import { findDesignSystemSection } from "./designSystemSections";
+import { designSystemExampleStyles, designSystemPageStyles, designSystemSharedStyles } from "./designSystemStyles";
+
+interface DesignSystemSectionListProps {
+  sectionIds: DesignSystemSectionId[];
+}
+
+interface DesignSystemPreviewOverlaysProps {
+  isDialogOpen: boolean;
+  isDrawerOpen: boolean;
+  onCloseDialog: () => void;
+  onCloseDrawer: () => void;
+}
+
+export function DesignSystemSectionList({ sectionIds }: DesignSystemSectionListProps) {
+  return sectionIds.map((sectionId) => {
+    const section = findDesignSystemSection(sectionId);
+
+    return (
+      <section
+        className="panel workspace-card page-panel design-system-panel"
+        key={section.id}
+        style={{
+          ...designSystemPageStyles.sectionLayout,
+          background: "var(--surface-muted)",
+          boxShadow: "0 18px 42px rgba(15, 23, 42, 0.08)"
+        }}
+      >
+        <div style={designSystemPageStyles.metaGrid}>
+          <p className="panel-kicker">{section.sprint}</p>
+          <div style={designSystemSharedStyles.stack}>
+            <h2 style={{ margin: 0 }}>{section.title}</h2>
+            <strong style={{ color: "var(--text, #111827)" }}>{section.chineseTitle}</strong>
+            <p className="section-copy" style={{ margin: 0 }}>
+              {section.summary}
+            </p>
+          </div>
+          <div style={designSystemSharedStyles.chipRow}>
+            {section.primitives.slice(0, 4).map((item) => (
+              <span key={item} style={designSystemSharedStyles.chip}>
+                {item}
+              </span>
+            ))}
+          </div>
+          <div style={designSystemSharedStyles.stack}>
+            <div>
+              <p style={designSystemPageStyles.subheading}>Coverage</p>
+              <ul style={designSystemPageStyles.denseList}>
+                {section.coverage.map((item) => (
+                  <li key={item}>{item}</li>
+                ))}
+              </ul>
+            </div>
+            <div>
+              <p style={designSystemPageStyles.subheading}>Regression checklist</p>
+              <ul style={designSystemPageStyles.denseList}>
+                {section.checklist.map((item) => (
+                  <li key={item}>{item}</li>
+                ))}
+              </ul>
+            </div>
+          </div>
+        </div>
+        <div data-testid="design-system-preview-pane" style={designSystemExampleStyles.previewPane}>
+          {section.preview}
+        </div>
+      </section>
+    );
+  });
+}
+
+export function DesignSystemPreviewOverlays({
+  isDialogOpen,
+  isDrawerOpen,
+  onCloseDialog,
+  onCloseDrawer
+}: DesignSystemPreviewOverlaysProps) {
+  return (
+    <>
+      {isDialogOpen ? (
+        <OverlayDialog
+          closeLabel="关闭 design system 对话框示例"
+          closeOnBackdrop
+          description="这个示例用来验证 focus trap、背景 inert 和统一弹层语言。"
+          footer={
+            <div style={designSystemSharedStyles.chipRow}>
+              <Button onClick={onCloseDialog} size="sm" variant="secondary">
+                关闭
+              </Button>
+              <Button size="sm" variant="primary">
+                主操作
+              </Button>
+            </div>
+          }
+          onClose={onCloseDialog}
+          title="Dialog live preview"
+        >
+          <div style={{ display: "grid", gap: "12px" }}>
+            <Text size="md">按 `Tab` 循环焦点，按 `Esc` 或点击遮罩关闭。</Text>
+            <SearchInput aria-label="弹层内搜索" placeholder="在弹层里验证 focus trap" />
+            <Alert title="Modal shell ready" variant="info">
+              当前弹层已通过 shared layer portal 挂载到 body。
+            </Alert>
+          </div>
+        </OverlayDialog>
+      ) : null}
+
+      {isDrawerOpen ? (
+        <OverlayDrawer
+          closeLabel="关闭 design system 抽屉示例"
+          closeOnBackdrop
+          description="抽屉适合更长的补充配置和多段内容。"
+          onClose={onCloseDrawer}
+          title="Drawer live preview"
+          width="lg"
+        >
+          <div style={{ display: "grid", gap: "16px" }}>
+            <Text size="md">这里展示的是统一抽屉壳层，而不是业务页面专属样式。</Text>
+            <KVList
+              items={[
+                { key: "Portal", value: "Enabled" },
+                { key: "Focus trap", value: "Enabled" },
+                { key: "Scroll lock", value: "Enabled" }
+              ]}
+            />
+            <div style={{ alignItems: "center", display: "flex", justifyContent: "flex-end" }}>
+              <Button onClick={onCloseDrawer} size="xs" variant="primary">
+                完成预览
+              </Button>
+            </div>
+          </div>
+        </OverlayDrawer>
+      ) : null}
+    </>
+  );
+}
diff --git a/apps/web/src/pages/design-system/designSystemContent.ts b/apps/web/src/pages/design-system/designSystemContent.ts
new file mode 100644
index 0000000..ace5153
--- /dev/null
+++ b/apps/web/src/pages/design-system/designSystemContent.ts
@@ -0,0 +1,1098 @@
+export const DESIGN_SYSTEM_SECTION_IDS = [
+  "foundations",
+  "color-theme",
+  "layout-spacing",
+  "elevation-radius",
+  "typography-content",
+  "buttons-actions",
+  "form-inputs",
+  "selection-controls",
+  "navigation-wayfinding",
+  "surfaces-cards",
+  "data-display",
+  "feedback-status",
+  "overlays-utilities"
+] as const;
+
+export type DesignSystemSectionId = (typeof DESIGN_SYSTEM_SECTION_IDS)[number];
+
+export interface DesignSystemDocSection {
+  title: string;
+  body: string[];
+}
+
+export interface DesignSystemCodeSample {
+  title: string;
+  code: string;
+}
+
+export interface DesignSystemApiField {
+  prop: string;
+  type: string;
+  defaultValue: string;
+  description: string;
+}
+
+export interface DesignSystemComponentDoc {
+  id: string;
+  title: string;
+  chineseTitle: string;
+  summary: string;
+  sectionIds: DesignSystemSectionId[];
+  docSections?: DesignSystemDocSection[];
+  codeSamples?: DesignSystemCodeSample[];
+  api?: DesignSystemApiField[];
+}
+
+export interface DesignSystemGroupDoc {
+  id: string;
+  title: string;
+  chineseTitle: string;
+  summary: string;
+  overviewDescription: string;
+  sectionIds: DesignSystemSectionId[];
+  docSections?: DesignSystemDocSection[];
+  components: DesignSystemComponentDoc[];
+}
+
+export const designSystemGroups: DesignSystemGroupDoc[] = [
+  {
+    id: "foundations",
+    title: "Foundations",
+    chineseTitle: "基础层",
+    summary: "统一设计 token、主题、布局节奏和表面层级，作为所有共享原语的视觉地基。",
+    overviewDescription: "Design tokens、预览地图、文档入口与视觉回归基线都会先在这里校准，后续组件都只复用这套基础语言。",
+    sectionIds: ["foundations", "color-theme", "layout-spacing", "elevation-radius"],
+    docSections: [
+      {
+        title: "适用范围",
+        body: [
+          "Foundations 用来集中说明设计 token、主题切换、布局节奏和表面层级，作为所有共享原语的统一视觉起点。",
+          "当页面需要定义新的颜色、间距或容器层级时，应先回到这一组基础说明确认是否已经存在可复用规范。"
+        ]
+      },
+      {
+        title: "适用场景",
+        body: [
+          "用于统一解释颜色、间距、圆角、阴影和页面骨架的来源，帮助设计稿、实现代码和文档站保持同一套视觉语言。",
+          "当团队准备新增共享组件、重排页面层级或扩展主题时，应先确认这一组基础规范是否已经覆盖需求。"
+        ]
+      },
+      {
+        title: "不适用场景",
+        body: [
+          "不要把业务规则、页面专属文案或一次性视觉修饰写进 Foundations；这些内容应留在具体组件或业务页面文档中。",
+          "不要绕过 token 直接在页面里临时定义颜色、间距或阴影，否则会让设计系统失去统一约束。"
+        ]
+      },
+      {
+        title: "状态与变体",
+        body: [
+          "当前首批基础层主要覆盖 color theme、layout spacing、elevation radius 三类文档块，分别负责主题、节奏和表面层级。",
+          "light / dark 主题、页面容器密度和 surface 层级都应视为基础变体，由共享 token 控制而不是由业务组件各自分叉。"
+        ]
+      },
+      {
+        title: "交互示例",
+        body: [
+          "右侧预览会同时展示 token 清单、主题卡片和基础布局样例，作为设计评审与视觉回归的共同参考。",
+          "如果某个组件在不同主题下表现不一致，应先回到 Foundations 预览确认问题来自 token 还是具体组件实现。"
+        ]
+      },
+      {
+        title: "代码片段",
+        body: [
+          "示例片段：import \"./tokens.css\"; import \"./primitives.css\"; 页面与组件都只消费已经定义好的 CSS variables。",
+          "示例片段：const surfaceStyle = { borderRadius: \"var(--radius-lg)\", boxShadow: \"var(--shadow-sm)\" }; 用统一 token 映射视觉层级。"
+        ]
+      },
+      {
+        title: "设计规范",
+        body: [
+          "基础层文档需要和 tokens、README、CHANGELOG 保持同一套命名，避免组件页和样式变量出现双重口径。",
+          "新增组件只能复用这里已经定义的主题、间距与 elevation 语言，不在业务页单独引入新的视觉档位。"
+        ]
+      },
+      {
+        title: "维护约束",
+        body: [
+          "基础层变更需要同步检查设计系统首页、共享样式文件和对应文档，避免只更新其中一个入口。",
+          "任何新增 token 都应回答它解决了哪一类复用问题，而不是只为当前页面补一个临时值。"
+        ]
+      }
+    ],
+    components: [
+      {
+        id: "design-tokens",
+        title: "Design tokens",
+        chineseTitle: "设计令牌",
+        summary: "品牌色、语义色、间距、圆角和阴影的统一定义。",
+        sectionIds: ["foundations", "color-theme", "layout-spacing", "elevation-radius"],
+        api: [
+          {
+            prop: "scope",
+            type: '"brand" | "semantic" | "spacing" | "radius" | "elevation"',
+            defaultValue: '"brand"',
+            description: "标记当前 token 所属的设计域，帮助页面按主题、间距和表面层级组织说明。"
+          },
+          {
+            prop: "varName",
+            type: "string",
+            defaultValue: '"--brand-500"',
+            description: "对应共享样式里实际消费的 CSS custom property 名称。"
+          },
+          {
+            prop: "usage",
+            type: "string",
+            defaultValue: '"component surfaces"',
+            description: "说明这个 token 在按钮、卡片、表格或页面容器中的典型落点。"
+          }
+        ],
+        docSections: [
+          {
+            title: "适用场景",
+            body: [
+              "用于统一记录品牌色、语义色、间距、圆角和阴影等基础 token，保证页面与共享原语使用同一套视觉变量。",
+              "当团队准备新增颜色档位、页面节奏或表面层级时，应先确认是否可以直接复用现有 token。"
+            ]
+          },
+          {
+            title: "不适用场景",
+            body: [
+              "不要把业务字段、页面专属文案或一次性视觉修饰包装成 design token；这些内容应留在具体组件或页面实现中。",
+              "不要绕过共享变量在业务页面直接手写颜色、阴影或间距，否则文档与实现会很快失去同步。"
+            ]
+          },
+          {
+            title: "状态与变体",
+            body: [
+              "当前预览重点覆盖 brand、semantic、spacing、radius 和 elevation 五类 token，分别对应主题、节奏与表面层级。",
+              "light / dark 主题切换只应替换 token 值，不应要求组件层额外维护一套独立样式。"
+            ]
+          },
+          {
+            title: "交互示例",
+            body: [
+              "右侧真实示例会同时展示色板、主题卡片与 token 行项目，帮助设计评审快速确认命名与视觉映射是否一致。",
+              "如果某个组件在不同主题下观感异常，应先回到 design tokens 检查语义色和表面层级映射。"
+            ]
+          },
+          {
+            title: "设计规范",
+            body: [
+              "新增 token 需要能解释跨页面复用价值，而不是只为当前一个业务块补临时变量。",
+              "token 名称应与 shared styles、README 和文档站入口保持一致，避免出现多套别名。"
+            ]
+          }
+        ]
+      },
+      {
+        id: "page-layout",
+        title: "PageLayout",
+        chineseTitle: "页面布局",
+        summary: "页面头部、工具栏、主内容区和侧栏的组合骨架。",
+        sectionIds: ["layout-spacing"],
+        api: [
+          {
+            prop: "Page",
+            type: "layout root",
+            defaultValue: "required",
+            description: "提供页面整体容器与垂直节奏，承接 header、body 和局部分区。"
+          },
+          {
+            prop: "PageBody",
+            type: '"with-sidebar" body region',
+            defaultValue: '"main only"',
+            description: "定义主内容区与侧栏的排布关系，用于列表页、详情页和带过滤器的工作台页面。"
+          },
+          {
+            prop: "PageToolbar",
+            type: "toolbar region",
+            defaultValue: "optional",
+            description: "承接筛选条、批量操作和摘要信息，避免业务页面重复拼装工具栏骨架。"
+          }
+        ],
+        docSections: [
+          {
+            title: "适用场景",
+            body: [
+              "用于管理后台页面、设置页和列表详情页的页面骨架，统一 header、toolbar、main 与 sidebar 的关系。",
+              "当页面需要稳定的主次区域，而不是一次性自由摆放卡片时，应优先使用 PageLayout 原语。"
+            ]
+          },
+          {
+            title: "不适用场景",
+            body: [
+              "不要把单个内容卡片或弹层局部结构包装成 PageLayout；它只处理页面级骨架，不负责局部信息块样式。",
+              "如果页面只有一个简短正文区域，也不需要为了形式完整强行引入 sidebar 或 toolbar 容器。"
+            ]
+          },
+          {
+            title: "状态与变体",
+            body: [
+              "当前预览覆盖 header + toolbar + main + sidebar 的标准工作台布局，以及无侧栏时的紧凑编排节奏。",
+              "布局密度应通过 spacing token 与容器组合控制，而不是为每个页面重新手写 margin 和 max-width。"
+            ]
+          },
+          {
+            title: "交互示例",
+            body: [
+              "真实示例展示了页头操作、筛选条和双栏正文的组合，便于验证 PageLayout 与 Card、FilterBar 的拼接边界。",
+              "切换不同页面时应保持相同的 toolbar 与 sidebar 节奏，这样用户能更快建立导航预期。"
+            ]
+          },
+          {
+            title: "设计规范",
+            body: [
+              "页面级布局优先依赖 Page、PageHeader、PageBody、PageMain、PageSidebar 等原语，不在业务页面重复定义骨架。",
+              "新增区域前先确认它属于 header、toolbar、main 还是 sidebar，避免内容层与布局层混在一起。"
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  {
+    id: "content-actions",
+    title: "Content & Actions",
+    chineseTitle: "内容与动作",
+    summary: "承接排版、按钮、卡片和数据展示组件，负责页面中的主要内容编排。",
+    overviewDescription: "这组组件负责把设计系统真正落到业务页面，包括标题层级、主次动作、卡片容器和数据摘要。",
+    sectionIds: ["typography-content", "buttons-actions", "surfaces-cards", "data-display"],
+    components: [
+      {
+        id: "typography",
+        title: "Typography",
+        chineseTitle: "排版",
+        summary: "统一标题、正文、说明、代码和快捷键标签的语义层级。",
+        sectionIds: ["typography-content"],
+        api: [
+          {
+            prop: "as",
+            type: '"h1" | "h2" | "h3" | "p" | "span"',
+            defaultValue: '"p"',
+            description: "控制排版原语输出的语义标签，保证层级结构与无障碍阅读顺序一致。"
+          },
+          {
+            prop: "size",
+            type: '"hero" | "title-lg" | "title-md" | "body" | "caption"',
+            defaultValue: '"body"',
+            description: "映射共享排版 token，控制标题、正文和辅助文案的视觉层级。"
+          },
+          {
+            prop: "tone",
+            type: '"default" | "muted" | "brand"',
+            defaultValue: '"default"',
+            description: "为正文、说明文字或强调内容附加统一的文本色语义。"
+          }
+        ],
+        docSections: [
+          {
+            title: "适用场景",
+            body: [
+              "用于统一标题、正文、说明、代码与快捷键标签的层级，让页面在高密度内容下仍然保持清晰阅读节奏。",
+              "当页面需要表达主标题、区块说明或辅助提示时，应优先使用共享排版原语，而不是直接手写字号和行高。"
+            ]
+          },
+          {
+            title: "不适用场景",
+            body: [
+              "不要把 Typography 当作布局容器使用；它负责文本语义和层级，不负责卡片、栅格或页面骨架。",
+              "不要为了特殊视觉效果跳过现有排版档位单独写字体大小，否则标题与正文很难跨页面保持一致。"
+            ]
+          },
+          {
+            title: "状态与变体",
+            body: [
+              "当前示例覆盖 hero、section title、正文、caption、code、kbd 与 muted copy 等高频文本形态。",
+              "不同文本强调程度应通过 size 与 tone 组合表达，而不是额外定义不透明度或临时色值。"
+            ]
+          },
+          {
+            title: "交互示例",
+            body: [
+              "真实示例会同时展示标题层级、说明文字、代码片段和快捷键标签，帮助团队快速检查同页阅读节奏。",
+              "在表单、卡片和提示组件里复用同一套排版原语，可以减少页面之间的字体风格漂移。"
+            ]
+          },
+          {
+            title: "设计规范",
+            body: [
+              "先确定语义标签，再选择视觉档位；不要为了视觉效果牺牲正确的 heading 或 paragraph 结构。",
+              "正文、说明、代码与快捷键标签都应复用共享排版 token，避免页面各自定义字体系统。"
+            ]
+          }
+        ]
+      },
+      {
+        id: "button",
+        title: "Button",
+        chineseTitle: "按钮",
+        summary: "覆盖主要、次要、轻量、危险和 icon-only 等动作样式。",
+        sectionIds: ["buttons-actions"],
+        codeSamples: [
+          {
+            title: "主次操作组合",
+            code: `<Button variant="primary">保存变更</Button>\n<Button variant="secondary">查看历史</Button>`
+          },
+          {
+            title: "危险与加载状态",
+            code: `<Button variant="danger">停用账号</Button>\n<Button isLoading loadingLabel="保存中" variant="primary">\n  保存\n</Button>`
+          }
+        ],
+        api: [
+          {
+            prop: "variant",
+            type: '"primary" | "secondary" | "subtle" | "ghost" | "danger" | "icon"',
+            defaultValue: '"primary"',
+            description: "定义按钮的视觉层级与语义强度。"
+          },
+          {
+            prop: "size",
+            type: '"xs" | "sm" | "md" | "lg"',
+            defaultValue: '"md"',
+            description: "控制按钮的高度、内边距和文本密度。"
+          },
+          {
+            prop: "isLoading",
+            type: "boolean",
+            defaultValue: "false",
+            description: "在异步提交中显示加载态并阻止重复触发。"
+          }
+        ],
+        docSections: [
+          {
+            title: "适用场景",
+            body: [
+              "用于页面主次操作、确认提交、轻量辅助动作以及需要明确点击反馈的交互入口。",
+              "当界面需要把一个动作表达成清晰的按钮层级，而不是纯文本链接时，优先使用 Button。"
+            ]
+          },
+          {
+            title: "不适用场景",
+            body: [
+              "不要用 Button 承担纯导航文本、正文内联引用或不需要强调的次级跳转；这类场景更适合链接样式。",
+              "不要在同一个操作区并列多个 primary 按钮，也不要把危险操作伪装成普通次按钮。"
+            ]
+          },
+          {
+            title: "状态与变体",
+            body: [
+              "当前文档站优先覆盖 primary、secondary、subtle、ghost、danger、icon-only 与 loading 几类高频动作变体。",
+              "同一个动作组里应保留明确主次关系，避免在同一区块并列多个视觉上同权重的主按钮。"
+            ]
+          },
+          {
+            title: "交互示例",
+            body: [
+              "推荐同时展示一个主操作按钮、一个次操作按钮和一个危险操作按钮，帮助评审动作层级是否清晰。",
+              "需要展示加载态时，应让按钮保留原位置并明确 loading label，避免用户误以为点击没有生效。"
+            ]
+          },
+          {
+            title: "代码片段",
+            body: [
+              "静态示例：<Button variant=\"primary\">保存变更</Button> 与 <Button variant=\"secondary\">取消</Button> 组合展示主次操作。",
+              "静态示例：<Button isLoading loadingLabel=\"保存中\" variant=\"primary\">保存变更</Button> 用于异步提交中的禁用反馈。"
+            ]
+          },
+          {
+            title: "设计规范",
+            body: [
+              "按钮文案应直接表达结果或下一步动作，避免使用模糊词汇如“确认一下”“继续处理”。",
+              "icon-only 按钮必须补充 aria-label，危险操作优先使用 danger 变体并与普通动作拉开视觉距离。"
+            ]
+          }
+        ]
+      },
+      {
+        id: "card",
+        title: "Card",
+        chineseTitle: "卡片",
+        summary: "统一信息分组、数据容器和空状态承载方式。",
+        sectionIds: ["surfaces-cards"],
+        api: [
+          {
+            prop: "variant",
+            type: '"default" | "data" | "status"',
+            defaultValue: '"default"',
+            description: "定义卡片承载普通信息、数据摘要还是状态提示的视觉结构。"
+          },
+          {
+            prop: "tone",
+            type: '"default" | "brand" | "warning" | "info"',
+            defaultValue: '"default"',
+            description: "控制卡片在品牌、提醒或信息语义下的强调方式。"
+          },
+          {
+            prop: "padding",
+            type: '"sm" | "md" | "lg"',
+            defaultValue: '"md"',
+            description: "统一 header、body、footer 的内边距密度，避免页面局部手写 spacing。"
+          }
+        ],
+        docSections: [
+          {
+            title: "适用场景",
+            body: [
+              "用于承接一组相关信息、摘要数据或局部操作，让页面在高密度信息里仍然保留清晰分区。",
+              "当内容需要共享同一标题、正文和底部动作容器时，优先使用 Card，而不是在页面里手写边框盒子。"
+            ]
+          },
+          {
+            title: "不适用场景",
+            body: [
+              "不要把整页布局直接塞进单个 Card；页面级栅格、分栏和主次区域仍应由 PageLayout 或 section 容器承担。",
+              "不要为了制造层级而无节制堆叠阴影卡片，连续信息块更适合通过间距和标题分组来解决。"
+            ]
+          },
+          {
+            title: "状态与变体",
+            body: [
+              "常见卡片变体包括基础信息卡、带操作 footer 的任务卡、带空状态说明的容器卡以及数据摘要卡。",
+              "是否需要 header、body、footer 应由内容结构决定，而不是为了视觉完整强行补齐三段式。"
+            ]
+          },
+          {
+            title: "交互示例",
+            body: [
+              "适合展示一个含标题与正文的基础卡片，再补一个带底部操作区的任务卡，帮助团队校验结构边界。",
+              "如果卡片内含按钮、标签或复制工具，应验证这些动作不会把卡片误导成整块可点击容器。"
+            ]
+          },
+          {
+            title: "代码片段",
+            body: [
+              "静态示例：<Card><CardHeader>域名配额</CardHeader><CardBody>展示剩余可用量与说明</CardBody></Card>。",
+              "静态示例：<Card><CardBody>摘要信息</CardBody><CardFooter><Button variant=\"secondary\">查看详情</Button></CardFooter></Card>。"
+            ]
+          },
+          {
+            title: "设计规范",
+            body: [
+              "卡片只负责建立信息边界，不应该再承担页面级布局职责；页面编排仍由 PageLayout 和 section 容器控制。",
+              "同一视图中的卡片层级应依赖统一的 radius 与 elevation token，不为单个业务块临时定义新的阴影或圆角。"
+            ]
+          }
+        ]
+      },
+      {
+        id: "data-display",
+        title: "Data display",
+        chineseTitle: "数据展示",
+        summary: "表格、键值列表、头像和统计卡等摘要展示原语。",
+        sectionIds: ["data-display"],
+        api: [
+          {
+            prop: "TableContainer.variant",
+            type: '"default" | "liquid"',
+            defaultValue: '"default"',
+            description: "控制表格容器的表面风格，适配常规列表与更轻盈的数据面板。"
+          },
+          {
+            prop: "KVList.items",
+            type: "Array<{ key: string; value: ReactNode; hint?: string; action?: ReactNode }>",
+            defaultValue: "[]",
+            description: "定义键值列表的字段、提示与附加操作，用于环境信息和配置摘要。"
+          },
+          {
+            prop: "MetricCard.tone",
+            type: '"default" | "hero"',
+            defaultValue: '"default"',
+            description: "区分普通 KPI 卡与强调型指标卡，让关键数据有更明确的视觉层级。"
+          }
+        ],
+        docSections: [
+          {
+            title: "适用场景",
+            body: [
+              "用于承接表格、键值列表、头像身份块和指标摘要卡，帮助页面稳定展示结构化信息。",
+              "当页面需要在不依赖真实接口的情况下校验数据密度与层级时，应优先复用这组展示原语。"
+            ]
+          },
+          {
+            title: "不适用场景",
+            body: [
+              "不要把 Data display 组件当作输入控件或导航容器使用；它们负责展示结果，不负责采集或切换。",
+              "如果内容只是简短正文说明，没有结构化字段或指标层级，也不需要强行包装成数据展示原语。"
+            ]
+          },
+          {
+            title: "状态与变体",
+            body: [
+              "当前预览覆盖 Avatar、KVList、MetricCard 和 Table shell，分别对应身份摘要、键值信息、核心指标和列表结果。",
+              "数据展示组件的层级应依赖统一的 badge、caption 与 container tone，而不是在业务页额外发明新的强调样式。"
+            ]
+          },
+          {
+            title: "交互示例",
+            body: [
+              "真实示例同时摆放头像组、键值列表、指标卡和紧凑表格，方便对比不同数据密度下的节奏是否协调。",
+              "列表里的状态展示可以直接复用 Badge、Tag 等反馈原语，避免数据组件内部再重复定义语义色。"
+            ]
+          },
+          {
+            title: "设计规范",
+            body: [
+              "优先保证字段标签、指标标题和状态色在不同数据组件之间语义一致，再考虑局部强调样式。",
+              "如果一个数据块需要解释、动作和状态提示，应通过 Card、Badge、Alert 等原语组合，而不是让单一展示组件承担所有职责。"
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  {
+    id: "forms-navigation-feedback",
+    title: "Forms, Navigation & Feedback",
+    chineseTitle: "表单、导航与反馈",
+    summary: "覆盖输入、选择、路径导航、状态反馈和系统提示等高频交互组件。",
+    overviewDescription: "输入控件、路径组件和反馈组件会一起定义页面交互密度，让用户既能完成操作，也能获得明确状态回馈。",
+    sectionIds: ["form-inputs", "selection-controls", "navigation-wayfinding", "feedback-status"],
+    components: [
+      {
+        id: "search-input",
+        title: "SearchInput",
+        chineseTitle: "搜索输入框",
+        summary: "统一搜索、筛选和快速清除交互。",
+        sectionIds: ["form-inputs"],
+        api: [
+          {
+            prop: "placeholder",
+            type: "string",
+            defaultValue: '"搜索…"',
+            description: "说明搜索对象和预期输入内容，帮助用户快速理解筛选范围。"
+          },
+          {
+            prop: "aria-label",
+            type: "string",
+            defaultValue: '"搜索"',
+            description: "为仅含图标或弱化 label 的搜索场景补充明确的无障碍名称。"
+          },
+          {
+            prop: "value / defaultValue",
+            type: "string",
+            defaultValue: '""',
+            description: "支持受控与非受控输入，适配即时搜索与初始化筛选值两类场景。"
+          }
+        ],
+        docSections: [
+          {
+            title: "适用场景",
+            body: [
+              "用于列表页、筛选条和弹层内的快速搜索入口，统一前缀图标、占位文案与清除交互。",
+              "当用户需要频繁按关键字缩小结果范围时，应优先使用 SearchInput，而不是普通 TextInput。"
+            ]
+          },
+          {
+            title: "不适用场景",
+            body: [
+              "不要把 SearchInput 用作需要复杂格式校验的表单字段，例如邮箱、密码或 API Key 输入；这类场景应使用普通输入控件。",
+              "如果页面没有即时筛选或查询反馈，单独放一个搜索框会制造误导，应该先明确搜索对象和结果承载区。"
+            ]
+          },
+          {
+            title: "状态与变体",
+            body: [
+              "首批文档优先覆盖默认搜索态、已输入可清除态以及与筛选条并列时的紧凑布局态。",
+              "是否显示清除按钮、是否带前缀图标、是否放进 FilterBar，都是 SearchInput 的常见组合变体。"
+            ]
+          },
+          {
+            title: "交互示例",
+            body: [
+              "典型示例是账号列表页顶部搜索框：输入关键字后立即过滤列表，并支持一键清除恢复默认结果。",
+              "当搜索与标签、状态等筛选器联动时，应保证控件同行对齐，并让占位文案说明搜索对象。"
+            ]
+          },
+          {
+            title: "代码片段",
+            body: [
+              "静态示例：<SearchInput aria-label=\"搜索账号\" placeholder=\"搜索账号、域名或创建人\" />。",
+              "静态示例：<FilterBar><SearchInput aria-label=\"搜索 API Key\" placeholder=\"搜索名称或前缀\" /></FilterBar>。"
+            ]
+          },
+          {
+            title: "设计规范",
+            body: [
+              "搜索框应直接表达可搜索对象，例如账号、地址或创建人，避免只写泛化的“请输入关键字”。",
+              "如果搜索会和其他筛选联动，建议放进 FilterBar 组合里保持同一行节奏。"
+            ]
+          }
+        ]
+      },
+      {
+        id: "multi-select",
+        title: "MultiSelect",
+        chineseTitle: "多选器",
+        summary: "统一标签筛选、权限筛选和组合条件选择。",
+        sectionIds: ["form-inputs"],
+        api: [
+          {
+            prop: "options",
+            type: "Array<{ label: string; value: string }>",
+            defaultValue: "[]",
+            description: "定义可选标签、权限或筛选条件，是多选器渲染候选项的基础数据。"
+          },
+          {
+            prop: "defaultValue",
+            type: "string[]",
+            defaultValue: "[]",
+            description: "用于带初始筛选值的列表页，让多选器在首屏就呈现当前过滤结果。"
+          },
+          {
+            prop: "aria-label",
+            type: "string",
+            defaultValue: '"多选器"',
+            description: "为紧凑筛选条或无可视标签场景补充清晰的控件名称。"
+          }
+        ],
+        docSections: [
+          {
+            title: "适用场景",
+            body: [
+              "用于标签筛选、权限筛选和组合条件选择，让用户可以在同一控件内快速选择多个维度。",
+              "当页面需要展示已选状态并允许继续增删条件时，应优先使用 MultiSelect，而不是多个离散 checkbox。"
+            ]
+          },
+          {
+            title: "不适用场景",
+            body: [
+              "不要把只有两三个永久可见选项的场景强行做成 MultiSelect；这类场景更适合直接使用 checkbox 组。",
+              "如果筛选条件之间互斥，只能单选，也不应使用多选器，应改用 Select 或 Radio。"
+            ]
+          },
+          {
+            title: "状态与变体",
+            body: [
+              "当前预览覆盖默认空态与带默认值的已选态，重点验证标签筛选与组合条件在同一筛选条中的节奏。",
+              "多选器的展示重点是已选项反馈、候选列表滚动与紧凑布局对齐，不额外承担复杂表单校验。"
+            ]
+          },
+          {
+            title: "交互示例",
+            body: [
+              "真实示例展示了标签筛选场景：默认勾选异常账号，再结合搜索框和状态下拉形成组合过滤。",
+              "如果多选器放进 FilterBar，应确保选中项不会撑破工具栏节奏，并保留清晰的 aria-label。"
+            ]
+          },
+          {
+            title: "设计规范",
+            body: [
+              "多选器应清楚区分候选项与已选结果，避免用户在筛选面板里反复确认当前状态。",
+              "当条件较多时，优先使用统一滚动区域与标签密度，不在业务页面私自扩展弹层样式。"
+            ]
+          }
+        ]
+      },
+      {
+        id: "selection-controls",
+        title: "Selection controls",
+        chineseTitle: "选择控件",
+        summary: "Checkbox、Radio、Switch 等二元与组选项控件。",
+        sectionIds: ["selection-controls"],
+        api: [
+          {
+            prop: "checked / defaultChecked",
+            type: "boolean",
+            defaultValue: "false",
+            description: "控制二元开关和单项选择的默认状态，适配受控与非受控场景。"
+          },
+          {
+            prop: "label",
+            type: "string",
+            defaultValue: '""',
+            description: "为 Checkbox、Radio、Switch 提供统一可读标签，减少页面自行拼接文案。"
+          },
+          {
+            prop: "variant",
+            type: '"default" | "card"',
+            defaultValue: '"default"',
+            description: "让单项选择既能作为普通表单控件，也能作为卡片式筛选块出现。"
+          }
+        ],
+        docSections: [
+          {
+            title: "适用场景",
+            body: [
+              "用于承接 Checkbox、Radio、Switch 等二元与组选项控件，统一选择状态、标签和排列密度。",
+              "当页面需要让用户启用功能、勾选筛选条件或在互斥选项中做决定时，应优先复用这组控件。"
+            ]
+          },
+          {
+            title: "不适用场景",
+            body: [
+              "不要把大量标签筛选塞进 selection controls；当选项数量较多且需要折叠、搜索或多选反馈时应切到 MultiSelect。",
+              "不要让单个 Switch 承担复杂确认逻辑，涉及危险操作时仍应配合按钮、弹层或说明文案。"
+            ]
+          },
+          {
+            title: "状态与变体",
+            body: [
+              "当前示例覆盖 checked、unchecked、card-style 与 grouped controls 等高频状态，便于回归开关、单选与多选的视觉一致性。",
+              "同一组选择控件应共享标签密度、禁用态和焦点反馈，不在业务层额外定义不同交互语言。"
+            ]
+          },
+          {
+            title: "交互示例",
+            body: [
+              "真实示例展示了通知开关、异常筛选 checkbox、汇总方式 radio 和卡片式选择块四种组合方式。",
+              "如果选择控件出现在设置页和筛选条两个场景，应优先复用同一套 label 与状态说明，避免术语漂移。"
+            ]
+          },
+          {
+            title: "设计规范",
+            body: [
+              "选择控件首先表达状态切换与范围边界，不要通过颜色或阴影单独创造新的语义。",
+              "当同一视图存在多组选项时，优先按用途分组并给出清晰标签，而不是靠视觉距离让用户自行猜测。"
+            ]
+          }
+        ]
+      },
+      {
+        id: "navigation",
+        title: "Navigation",
+        chineseTitle: "导航组件",
+        summary: "Breadcrumb、Tabs、Pagination、Steps 等路径与流程组件。",
+        sectionIds: ["navigation-wayfinding"],
+        api: [
+          {
+            prop: "Breadcrumb items",
+            type: "ReactNode[]",
+            defaultValue: "[]",
+            description: "按路径层级描述当前位置与返回入口，适合详情页和多层管理后台。"
+          },
+          {
+            prop: "Tabs.defaultValue",
+            type: "string",
+            defaultValue: '"overview"',
+            description: "定义首屏展示的标签页，让局部视图切换有稳定默认态。"
+          },
+          {
+            prop: "Pagination.page / total / pageSize",
+            type: "number",
+            defaultValue: "1 / 0 / 20",
+            description: "统一分页栏的页码、总量和每页数量结构，避免列表页各自定义分页规则。"
+          }
+        ],
+        docSections: [
+          {
+            title: "适用场景",
+            body: [
+              "用于表达页面路径、内容分段、结果分页和任务流程，帮助用户理解自己当前所在的位置与下一步去向。",
+              "当页面需要在多个平级视图之间切换，或需要展示多步操作进度时，应优先复用这一组导航原语。"
+            ]
+          },
+          {
+            title: "不适用场景",
+            body: [
+              "不要把 Navigation 当成主要操作区来承载保存、删除等动作；导航负责定位与切换，不负责提交业务结果。",
+              "同一层级内容不要同时叠加 Tabs、Steps 和二级 Breadcrumb，重复路径信号会增加理解成本。"
+            ]
+          },
+          {
+            title: "状态与变体",
+            body: [
+              "当前常见变体包括 Breadcrumb 路径导航、Tabs 内容切换、Pagination 结果分页与 Steps 流程进度。",
+              "是否需要图标、数字、禁用态或完成态，应跟随组件职责，而不是为视觉丰富度额外增加状态。"
+            ]
+          },
+          {
+            title: "交互示例",
+            body: [
+              "管理后台详情页适合组合 Breadcrumb 与 Tabs：上层路径帮助返回列表，局部视图切换交由 Tabs 处理。",
+              "涉及多步配置流程时，可以用 Steps 展示进度，但每一步的主操作仍应留在正文或底部操作区。"
+            ]
+          },
+          {
+            title: "代码片段",
+            body: [
+              "静态示例：<Breadcrumb><BreadcrumbItem><BreadcrumbLink href=\"/accounts\">账号</BreadcrumbLink></BreadcrumbItem><BreadcrumbCurrent>详情</BreadcrumbCurrent></Breadcrumb>。",
+              "静态示例：<Tabs><TabsList><TabsTrigger value=\"overview\">概览</TabsTrigger><TabsTrigger value=\"activity\">活动</TabsTrigger></TabsList></Tabs>。"
+            ]
+          },
+          {
+            title: "设计规范",
+            body: [
+              "导航组件首先服务于定位和切换，不应混入主操作按钮语义；主动作仍应留在工具栏或正文操作区。",
+              "同一页面里不要同时堆叠多个相同层级的导航模式，避免用户同时处理 breadcrumb、tabs 和 steps 的重复路径信号。"
+            ]
+          }
+        ]
+      },
+      {
+        id: "feedback",
+        title: "Feedback",
+        chineseTitle: "反馈组件",
+        summary: "Tag、Badge、Alert、Progress、Skeleton 和 Spinner 等反馈状态。",
+        sectionIds: ["feedback-status"],
+        api: [
+          {
+            prop: "variant",
+            type: '"success" | "warning" | "danger" | "info" | "brand"',
+            defaultValue: '"info"',
+            description: "统一 Badge、Tag、Alert 等反馈组件的语义色映射。"
+          },
+          {
+            prop: "title",
+            type: "string",
+            defaultValue: '""',
+            description: "用于 Alert 等强提示组件的标题文案，帮助用户快速理解事件性质。"
+          },
+          {
+            prop: "value",
+            type: "number",
+            defaultValue: "0",
+            description: "用于 Progress 等进度型反馈，表达任务完成比例与当前阶段。"
+          }
+        ],
+        docSections: [
+          {
+            title: "适用场景",
+            body: [
+              "用于提示当前状态、异步进度、风险警告和加载占位，让用户及时理解系统是否成功响应了操作。",
+              "当页面需要补充状态密度但不想打断主流程时，优先使用 Badge、Tag 或 Progress；需要明确提醒时再升级到 Alert。"
+            ]
+          },
+          {
+            title: "不适用场景",
+            body: [
+              "不要用高优先级 Alert 展示每一条普通提示，否则真正的风险提醒会被淹没。",
+              "不要让 Skeleton 或 Spinner 长时间替代真实内容；如果加载超过合理时长，应补充明确说明或失败反馈。"
+            ]
+          },
+          {
+            title: "状态与变体",
+            body: [
+              "首批反馈文档覆盖 success、warning、danger、info 几类语义状态，以及 loading、empty、in-progress 等交互阶段。",
+              "Badge、Tag、Progress、Alert、Skeleton 和 Spinner 分别对应不同强度的反馈层级，选择时应先判断是否会打断用户主流程。"
+            ]
+          },
+          {
+            title: "交互示例",
+            body: [
+              "例如在 API Key 列表中，用 Badge 标识状态、用 Alert 呈现失败原因、用 Spinner 或 Skeleton 承接短暂加载。",
+              "涉及批量任务时，可以用 Progress 展示完成度，同时在任务结束后切换为明确的成功或失败文案。"
+            ]
+          },
+          {
+            title: "代码片段",
+            body: [
+              "静态示例：<Alert tone=\"warning\" title=\"域名即将过期\">请在 3 天内完成续费。</Alert>。",
+              "静态示例：<Badge variant=\"success\">运行中</Badge> 与 <Progress value={64} aria-label=\"同步进度\" /> 组合展示状态。"
+            ]
+          },
+          {
+            title: "设计规范",
+            body: [
+              "反馈组件的颜色必须复用语义色 token，让 success、warning、danger 等状态在全站保持同一套认知映射。",
+              "Skeleton 和 Spinner 只用于短暂加载反馈，不应替代真正的空状态说明。"
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  {
+    id: "overlays-utilities",
+    title: "Overlays & Utilities",
+    chineseTitle: "弹层与工具型原语",
+    summary: "提供弹层、提示层、滚动区域和复制等辅助能力。",
+    overviewDescription: "这组能力主要解决复杂交互和信息补充，不改变主页面结构，但决定整个系统的细节完成度。",
+    sectionIds: ["overlays-utilities"],
+    components: [
+      {
+        id: "overlay",
+        title: "Overlay",
+        chineseTitle: "弹层",
+        summary: "统一对话框、抽屉、聚焦管理和背景锁定。",
+        sectionIds: ["overlays-utilities"],
+        api: [
+          {
+            prop: "title",
+            type: "string",
+            defaultValue: '""',
+            description: "为对话框或抽屉提供清晰标题，帮助用户理解当前弹层任务。"
+          },
+          {
+            prop: "closeOnBackdrop",
+            type: "boolean",
+            defaultValue: "false",
+            description: "控制点击遮罩时是否允许关闭，适配轻量预览与需要强确认的两类场景。"
+          },
+          {
+            prop: "onClose",
+            type: "() => void",
+            defaultValue: "required",
+            description: "统一弹层关闭出口，承接 Esc、关闭按钮和遮罩点击等收尾动作。"
+          }
+        ],
+        docSections: [
+          {
+            title: "适用场景",
+            body: [
+              "用于承接对话框、抽屉等需要临时打断主流程的交互，同时统一 focus trap、背景锁定与 portal 挂载。",
+              "当页面需要补充配置、确认危险操作或展示分步信息时，应优先使用 Overlay 原语，而不是页面里手写 fixed panel。"
+            ]
+          },
+          {
+            title: "不适用场景",
+            body: [
+              "不要把轻量提示或只读补充说明做成 Overlay；这类场景更适合 Tooltip、Popover 或页内提示块。",
+              "不要在同一时刻堆叠多个业务弹层，除非流程明确要求，否则会让焦点与关闭语义失控。"
+            ]
+          },
+          {
+            title: "状态与变体",
+            body: [
+              "当前真实示例覆盖 dialog 与 drawer 两种壳层，重点验证 focus trap、closeOnBackdrop 与统一 footer 行为。",
+              "弹层的宽度、关闭方式和 footer 组合应作为变体处理，但背景锁定和焦点管理必须保持同一套规则。"
+            ]
+          },
+          {
+            title: "交互示例",
+            body: [
+              "设计系统首页顶部已挂出打开对话框与打开抽屉两个真实入口，用于验证共享壳层而不是业务专属样式。",
+              "在弹层内部嵌入搜索、告警和键值摘要时，应确保 Tab 顺序与关闭行为仍然稳定。"
+            ]
+          },
+          {
+            title: "设计规范",
+            body: [
+              "弹层首先解决交互收束与焦点管理，不应承担页面级布局职责。",
+              "所有对话框和抽屉都应通过统一 overlay layer 渲染，避免每个业务模块各自实现 portal 与 scroll lock。"
+            ]
+          }
+        ]
+      },
+      {
+        id: "tooltip-popover",
+        title: "Tooltip & Popover",
+        chineseTitle: "提示层与浮层",
+        summary: "承接轻量提示和补充操作面板。",
+        sectionIds: ["overlays-utilities"],
+        api: [
+          {
+            prop: "TooltipContent",
+            type: "ReactNode",
+            defaultValue: "required",
+            description: "承载 hover 或 focus 后出现的简短说明文案。"
+          },
+          {
+            prop: "PopoverContent",
+            type: "ReactNode",
+            defaultValue: "required",
+            description: "用于展示补充操作或上下文信息面板，内容可以比 tooltip 更丰富。"
+          },
+          {
+            prop: "Trigger",
+            type: "interactive element",
+            defaultValue: "required",
+            description: "定义触发提示层或浮层的入口，保证 hover、focus 与 click 行为一致。"
+          }
+        ],
+        docSections: [
+          {
+            title: "适用场景",
+            body: [
+              "Tooltip 用于承载简短解释、术语说明或图标按钮提示；Popover 用于展示补充操作面板和上下文设置。",
+              "当页面需要在不离开当前上下文的情况下补充说明或附加动作时，应优先考虑这一组轻量浮层。"
+            ]
+          },
+          {
+            title: "不适用场景",
+            body: [
+              "不要把长篇文档、表单流程或危险确认放进 Tooltip 或 Popover；这类场景应升级为 Overlay 或独立页面。",
+              "Tooltip 不应用来承载必须阅读的信息，因为用户在移动端或键盘场景下不一定稳定触发悬停。"
+            ]
+          },
+          {
+            title: "状态与变体",
+            body: [
+              "当前预览重点覆盖 hover / focus 提示与 click 打开的快捷面板两类模式，帮助区分 Tooltip 和 Popover 的职责边界。",
+              "这组组件的关键变体不是颜色，而是内容密度、触发方式与是否允许继续操作。"
+            ]
+          },
+          {
+            title: "交互示例",
+            body: [
+              "真实示例同时展示聚焦提示和快捷面板，便于验证 tooltip 文案、popover 操作区与触发器之间的距离感。",
+              "如果同一个图标既需要解释又需要动作，优先判断用户真正需要的是提示还是操作面板，避免两者叠加。"
+            ]
+          },
+          {
+            title: "设计规范",
+            body: [
+              "Tooltip 文案应短促直接，Popover 内容应围绕当前上下文，不要让用户在浮层里重新理解一套页面结构。",
+              "两类浮层都应复用统一的定位、层级和间距语言，避免每个业务入口呈现不同的悬浮体验。"
+            ]
+          }
+        ]
+      },
+      {
+        id: "copy-utility",
+        title: "Copy utility",
+        chineseTitle: "复制工具",
+        summary: "统一命令、链接和片段复制反馈。",
+        sectionIds: ["overlays-utilities"],
+        api: [
+          {
+            prop: "value",
+            type: "string",
+            defaultValue: '""',
+            description: "定义要复制到剪贴板的命令、链接或代码片段内容。"
+          },
+          {
+            prop: "children",
+            type: "ReactNode",
+            defaultValue: '"复制"',
+            description: "控制按钮展示文案，让复制动作可以适配命令、链接和字段值等不同语境。"
+          },
+          {
+            prop: "copiedLabel",
+            type: "string",
+            defaultValue: '"已复制"',
+            description: "复制成功后的即时反馈文案，帮助用户确认动作已经完成。"
+          }
+        ],
+        docSections: [
+          {
+            title: "适用场景",
+            body: [
+              "用于命令行指令、API key 前缀、访问链接和代码片段复制，让用户在高频操作中得到统一反馈。",
+              "当页面包含需要重复复制的短文本时，应优先使用 Copy utility，而不是自己实现按钮与成功提示。"
+            ]
+          },
+          {
+            title: "不适用场景",
+            body: [
+              "不要把长篇正文或整块富文本直接交给 Copy utility；这类场景更适合下载、导出或专门的代码块复制方案。",
+              "如果内容本身不可见或用户无法判断复制对象，也不应只放一个复制按钮而不补充上下文说明。"
+            ]
+          },
+          {
+            title: "状态与变体",
+            body: [
+              "当前预览覆盖测试命令复制、Playwright 命令复制和片段复制反馈，重点验证默认态与已复制态的切换。",
+              "复制工具的主要变体来自文案语境与所在容器，而不是重新设计一套独立按钮样式。"
+            ]
+          },
+          {
+            title: "交互示例",
+            body: [
+              "设计系统首页基础层与 Overlays & Utilities 区块都保留了复制命令按钮，方便验证不同容器中的反馈一致性。",
+              "如果复制动作出现在卡片、代码示例和工具栏中，应保持相同的成功提示和可聚焦行为。"
+            ]
+          },
+          {
+            title: "设计规范",
+            body: [
+              "复制按钮必须让用户知道将要复制什么内容，避免只显示抽象动词导致误操作。",
+              "复制反馈应短促、明确且不会打断主流程，优先使用同一套 success 文案和按钮状态切换。"
+            ]
+          }
+        ]
+      }
+    ]
+  }
+];
diff --git a/apps/web/src/pages/design-system/designSystemPreviewParts.tsx b/apps/web/src/pages/design-system/designSystemPreviewParts.tsx
new file mode 100644
index 0000000..0e86271
--- /dev/null
+++ b/apps/web/src/pages/design-system/designSystemPreviewParts.tsx
@@ -0,0 +1,131 @@
+import type { ReactNode } from "react";
+
+import type { WorkspaceTheme } from "../../app/appStore";
+import { Button } from "../../shared/button";
+import { CopyButton } from "../../shared/copy-button";
+import { designSystemSharedStyles } from "./designSystemStyles";
+
+interface SwatchProps {
+  name: string;
+  hex: string;
+  varName: string;
+}
+
+interface TokenRowProps {
+  label: string;
+  value: ReactNode;
+  hint: string;
+}
+
+interface ThemeShowcaseCardProps {
+  description: string;
+  theme: WorkspaceTheme;
+  title: string;
+}
+
+export function Swatch({ name, hex, varName }: SwatchProps) {
+  return (
+    <div style={designSystemSharedStyles.previewCard}>
+      <span
+        aria-hidden="true"
+        style={{
+          height: "56px",
+          borderRadius: "12px",
+          background: hex,
+          border: "1px solid rgba(15, 23, 42, 0.08)"
+        }}
+      />
+      <div style={{ display: "grid", gap: "6px" }}>
+        <strong>{name}</strong>
+        <code>{hex.toUpperCase()}</code>
+        <small>{varName}</small>
+      </div>
+    </div>
+  );
+}
+
+export function TokenRow({ label, value, hint }: TokenRowProps) {
+  return (
+    <div style={{ ...designSystemSharedStyles.previewCard, gridTemplateColumns: "88px minmax(0, 1fr)", alignItems: "center" }}>
+      <div>{value}</div>
+      <div style={{ display: "grid", gap: "6px" }}>
+        <strong>{label}</strong>
+        <small>{hint}</small>
+      </div>
+    </div>
+  );
+}
+
+export function ThemeShowcaseCard({ description, theme, title }: ThemeShowcaseCardProps) {
+  const isDark = theme === "dark";
+
+  return (
+    <div
+      style={{
+        ...designSystemSharedStyles.previewCard,
+        background: isDark ? "#0f1115" : "#ffffff",
+        borderColor: isDark ? "rgba(255,255,255,.1)" : "rgba(15,23,42,.08)",
+        color: isDark ? "#f3f4f6" : "#111827"
+      }}
+    >
+      <small>{title}</small>
+      <div style={{ display: "grid", gap: "10px" }}>
+        <div
+          style={{
+            display: "flex",
+            justifyContent: "space-between",
+            alignItems: "center",
+            gap: "12px",
+            padding: "14px 16px",
+            borderRadius: "14px",
+            background: isDark ? "rgba(255,255,255,.06)" : "rgba(15,23,42,.04)"
+          }}
+        >
+          <strong>{isDark ? "Dark surface" : "Light surface"}</strong>
+          <span
+            style={{
+              display: "inline-flex",
+              alignItems: "center",
+              padding: "6px 10px",
+              borderRadius: "999px",
+              background: isDark ? "#ff7a00" : "rgba(255,122,0,.12)",
+              color: isDark ? "#0f1115" : "#b35400",
+              fontSize: "12px",
+              fontWeight: 700
+            }}
+          >
+            Accent
+          </span>
+        </div>
+        <small style={{ color: isDark ? "rgba(243,244,246,.72)" : "rgba(17,24,39,.62)" }}>{description}</small>
+      </div>
+    </div>
+  );
+}
+
+export function DesignSystemQuickActions() {
+  return (
+    <div style={designSystemSharedStyles.previewCard}>
+      <small>Quick actions</small>
+      <div style={designSystemSharedStyles.chipRow}>
+        <CopyButton value="pnpm test:web">复制测试命令</CopyButton>
+        <CopyButton value="pnpm exec playwright test -c apps/web/playwright.config.ts apps/web/e2e/design-system.spec.ts">
+          复制 e2e 命令
+        </CopyButton>
+      </div>
+    </div>
+  );
+}
+
+export function PreviewActionButtons({ onOpenDialog, onOpenDrawer }: { onOpenDialog: () => void; onOpenDrawer: () => void }) {
+  return (
+    <div style={designSystemSharedStyles.chipRow}>
+      <Button onClick={onOpenDialog} size="sm" variant="secondary">
+        打开对话框
+      </Button>
+      <Button onClick={onOpenDrawer} size="sm" variant="secondary">
+        打开抽屉
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/web/src/pages/design-system/designSystemSections.tsx b/apps/web/src/pages/design-system/designSystemSections.tsx
new file mode 100644
index 0000000..0786ef1
--- /dev/null
+++ b/apps/web/src/pages/design-system/designSystemSections.tsx
@@ -0,0 +1,820 @@
+import { Bell, CircleAlert, Mail, ShieldCheck } from "lucide-react";
+import type { ReactNode } from "react";
+
+import { Alert } from "../../shared/alert";
+import { Avatar } from "../../shared/avatar";
+import { Badge } from "../../shared/badge";
+import { Breadcrumb, BreadcrumbCurrent, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbSeparator } from "../../shared/breadcrumb";
+import { Button } from "../../shared/button";
+import { Card, CardBody, CardFooter, CardHeader } from "../../shared/card";
+import { CopyButton } from "../../shared/copy-button";
+import { Divider } from "../../shared/divider";
+import { EmptyState } from "../../shared/empty-state";
+import { Checkbox, FormField, MultiSelect, Radio, SearchInput, SelectInput, TextareaInput } from "../../shared/form";
+import { Icon } from "../../shared/icon";
+import { KVList } from "../../shared/kv-list";
+import { MetricCard } from "../../shared/metric-card";
+import { Page, PageBody, PageHeader, PageMain, PageSidebar, PageToolbar } from "../../shared/page-layout";
+import { Pagination } from "../../shared/pagination";
+import { Popover, PopoverContent, PopoverTrigger } from "../../shared/popover";
+import { Progress } from "../../shared/progress";
+import { ScrollArea, ScrollAreaScrollbar, ScrollAreaThumb, ScrollAreaViewport } from "../../shared/scroll-area";
+import { Skeleton } from "../../shared/skeleton";
+import { Spinner } from "../../shared/spinner";
+import { StepItem, Steps, StepsList } from "../../shared/steps";
+import { Switch } from "../../shared/switch";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableContainer,
+  TableHead,
+  TableHeaderCell,
+  TableRow
+} from "../../shared/table";
+import { Tabs, TabsList, TabsPanel, TabsTrigger } from "../../shared/tabs";
+import { Tag } from "../../shared/tag";
+import { Tooltip, TooltipContent, TooltipTrigger } from "../../shared/tooltip";
+import { Code, Heading, Kbd, Label, Muted, Text } from "../../shared/typography";
+import { FilterBar, FilterBarActions, FilterBarSummary } from "../../shared/filter-bar";
+import { DesignSystemQuickActions, Swatch, ThemeShowcaseCard, TokenRow } from "./designSystemPreviewParts";
+import { designSystemExampleStyles, designSystemPageStyles, designSystemSharedStyles } from "./designSystemStyles";
+import type { DesignSystemSectionId } from "./designSystemContent";
+
+export interface DesignSystemSection {
+  id: DesignSystemSectionId;
+  title: string;
+  chineseTitle: string;
+  sprint: string;
+  summary: string;
+  primitives: string[];
+  coverage: string[];
+  checklist: string[];
+  preview: ReactNode;
+}
+
+const demoMultiSelectOptions = [
+  { label: "异常账号", value: "exceptions" },
+  { label: "近 7 天活跃", value: "7d" },
+  { label: "管理员创建", value: "admin" }
+];
+
+const demoKVListItems = [
+  { key: "环境", value: "Prod" },
+  { key: "区域", value: "APAC", hint: "默认" },
+  { key: "健康度", value: "98.6%" }
+];
+
+export const designSystemSections: DesignSystemSection[] = [
+  {
+    id: "foundations",
+    title: "Foundations",
+    chineseTitle: "基础层",
+    sprint: "基础",
+    summary: "锁定设计原则、发布节奏、预览锚点与文档入口，保证后续原语只做填充，不再重构页面结构。",
+    primitives: ["Design tokens", "Preview map", "Docs index", "Visual regression entry"],
+    coverage: ["设计原则", "Sprint 节奏", "预览分区锚点", "文档与回归约束"],
+    checklist: ["13 个 section id 固定", "README/CHANGELOG 对应同一分区地图", "light/dark 回归入口一致"],
+    preview: (
+      <div style={designSystemExampleStyles.previewGrid}>
+        <div style={designSystemExampleStyles.twoColumnGrid}>
+          {[
+            ["路由", "/design-system"],
+            ["当前目标", "Public showcase"],
+            ["系统范围", " 原语集成"],
+            ["视觉回归", "Playwright light/dark"]
+          ].map(([label, value]) => (
+            <div key={label} style={designSystemSharedStyles.previewCard}>
+              <small>{label}</small>
+              <strong>{value}</strong>
+            </div>
+          ))}
+        </div>
+        <div style={designSystemExampleStyles.twoColumnGrid}>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Usage rules</small>
+            <ul style={designSystemPageStyles.denseList}>
+              <li>原语统一走 token，不在业务层重新定义视觉变量。</li>
+              <li>新增页面先从 `/design-system` 找已有模式，再决定是否扩原语。</li>
+              <li>每个 section 都对应文档和回归锚点。</li>
+            </ul>
+          </div>
+          <DesignSystemQuickActions />
+        </div>
+      </div>
+    )
+  },
+  {
+    id: "color-theme",
+    title: "Color & Theme",
+    chineseTitle: "色彩与主题",
+    sprint: "已接入",
+    summary: "展示品牌色、语义色和 light/dark 主题入口，后续把真实组件的主题差异都收敛到这里校验。",
+    primitives: ["Brand tokens", "Semantic tokens", "Theme toggles"],
+    coverage: ["品牌色", "语义色", "主题切换", "对比度观察点"],
+    checklist: ["light/dark 均可截图", "token 名称与 docs 一致", "不依赖业务页颜色说明"],
+    preview: (
+      <div style={designSystemExampleStyles.previewGrid}>
+        <div style={designSystemExampleStyles.twoColumnGrid}>
+          <Swatch name="Brand / 500" hex="#ff7a00" varName="--brand-500" />
+          <Swatch name="Brand Soft" hex="#ffb366" varName="--brand-soft-500" />
+          <Swatch name="Success" hex="#22c55e" varName="--success-500" />
+          <Swatch name="Danger" hex="#ef4444" varName="--danger-500" />
+        </div>
+        <div style={designSystemExampleStyles.twoColumnGrid}>
+          <ThemeShowcaseCard description="浅色模式强调空间层级、边框和柔和背景。" theme="light" title="Light preview" />
+          <ThemeShowcaseCard description="深色模式保持同一套 brand/semantic 语言，只替换表面和文本密度。" theme="dark" title="Dark preview" />
+        </div>
+      </div>
+    )
+  },
+  {
+    id: "layout-spacing",
+    title: "Layout & Spacing",
+    chineseTitle: "布局与间距",
+    sprint: "基础",
+    summary: "先把页面骨架、栅格与空间尺度摆清楚，为 PageLayout、Card 和表单节奏预留稳定容器。",
+    primitives: ["PageLayout", "Section spacing", "Container rhythm", "FilterBar"],
+    coverage: ["4px 网格", "双栏 section 容器", "信息密度层级"],
+    checklist: ["移动端自动折行", "分区元信息与预览区可独立扩展", "后续示例注入不改外层布局"],
+    preview: (
+      <div style={designSystemExampleStyles.previewGrid}>
+        <div style={designSystemExampleStyles.twoColumnGrid}>
+          {[4, 8, 12, 16, 24, 32].map((value) => (
+            <div key={value} style={designSystemSharedStyles.previewCard}>
+              <small>{`--space-${value / 4}`}</small>
+              <span
+                aria-hidden="true"
+                style={{
+                  display: "block",
+                  height: "12px",
+                  width: `${value * 3}px`,
+                  maxWidth: "100%",
+                  borderRadius: "999px",
+                  background: "var(--brand-500, #ff7a00)"
+                }}
+              />
+              <strong>{`${value}px`}</strong>
+            </div>
+          ))}
+        </div>
+        <div style={designSystemSharedStyles.previewCard}>
+          <small>PageLayout preview</small>
+          <div style={designSystemExampleStyles.fullWidthCard}>
+            <Page as="div">
+              <PageHeader
+                actions={<Button size="sm" variant="secondary">导出</Button>}
+                description="统一页面头部、操作区与内容区节奏。"
+                kicker="账号中心"
+                title="账号列表"
+              />
+              <PageToolbar>
+                <FilterBar columns={3}>
+                  <FormField label={<span className="sr-only">搜索布局</span>}>
+                    <SearchInput aria-label="搜索布局" placeholder="搜索账号" />
+                  </FormField>
+                  <FormField label={<span className="sr-only">状态布局</span>}>
+                    <SelectInput aria-label="状态布局" defaultValue="all">
+                      <option value="all">全部状态</option>
+                    </SelectInput>
+                  </FormField>
+                  <FormField label={<span className="sr-only">角色布局</span>}>
+                    <SelectInput aria-label="角色布局" defaultValue="all">
+                      <option value="all">全部角色</option>
+                    </SelectInput>
+                  </FormField>
+                </FilterBar>
+                <FilterBarActions>
+                  <Button size="sm" variant="ghost">仅看异常</Button>
+                </FilterBarActions>
+              </PageToolbar>
+              <PageBody hasSidebar>
+                <PageMain>
+                  <Card padding="sm">
+                    <Text>主内容区</Text>
+                  </Card>
+                </PageMain>
+                <PageSidebar>
+                  <Card padding="sm">
+                    <Text>侧栏摘要</Text>
+                  </Card>
+                </PageSidebar>
+              </PageBody>
+            </Page>
+          </div>
+        </div>
+      </div>
+    )
+  },
+  {
+    id: "elevation-radius",
+    title: "Elevation & Radius",
+    chineseTitle: "阴影与圆角",
+    sprint: "基础",
+    summary: "卡片、表单、弹层的外观层级先在这里归档，避免每个组件各自解释阴影和圆角档位。",
+    primitives: ["Radius scale", "Elevation scale", "Surface transitions"],
+    coverage: ["6 档圆角", "5 档阴影", "卡片层级示意"],
+    checklist: ["token 名称与 preview 一致", "适用于 light/dark", "后续组件只引用 token"],
+    preview: (
+      <div style={designSystemExampleStyles.previewGrid}>
+        <div style={designSystemExampleStyles.twoColumnGrid}>
+          <TokenRow
+            label="Radius / sm"
+            hint="--radius-sm · 紧凑按钮与标签"
+            value={<span aria-hidden="true" style={{ display: "block", width: "56px", height: "56px", borderRadius: "8px", background: "var(--brand-100, #ffe0c2)" }} />}
+          />
+          <TokenRow
+            label="Radius / xl"
+            hint="--radius-xl · 主要卡片"
+            value={<span aria-hidden="true" style={{ display: "block", width: "56px", height: "56px", borderRadius: "24px", background: "var(--neutral-100, #f3f4f6)" }} />}
+          />
+          <div style={{ ...designSystemSharedStyles.previewCard, boxShadow: "var(--elevation-sm, 0 2px 6px rgba(17,17,17,.06))" }}>
+            <small>Elevation / sm</small>
+            <strong>低层级卡片</strong>
+          </div>
+          <div style={{ ...designSystemSharedStyles.previewCard, boxShadow: "var(--elevation-lg, 0 14px 32px rgba(17,17,17,.10))" }}>
+            <small>Elevation / lg</small>
+            <strong>高层级弹层</strong>
+          </div>
+        </div>
+        <div style={designSystemExampleStyles.twoColumnGrid}>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Default</small>
+            <Button variant="secondary">普通态按钮</Button>
+          </div>
+          <div style={{ ...designSystemSharedStyles.previewCard, boxShadow: "var(--focus-ring)" }}>
+            <small>Focus ring</small>
+            <Button variant="primary">键盘焦点</Button>
+          </div>
+          <div style={{ ...designSystemSharedStyles.previewCard, transform: "translateY(-2px)", boxShadow: "var(--elevation-md)" }}>
+            <small>Hover intent</small>
+            <Button variant="subtle">浮起卡片</Button>
+          </div>
+          <div style={{ ...designSystemSharedStyles.previewCard, opacity: 0.65 }}>
+            <small>Disabled</small>
+            <Button disabled variant="secondary">
+              不可用
+            </Button>
+          </div>
+        </div>
+      </div>
+    )
+  },
+  {
+    id: "typography-content",
+    title: "Typography & Content",
+    chineseTitle: "排版与内容原子",
+    sprint: "计划中",
+    summary: "承接 Typography、Divider、Icon、Spinner、Skeleton 等原子，统一文案密度和内容骨架。",
+    primitives: ["Typography", "Divider", "Icon", "Spinner", "Skeleton"],
+    coverage: ["字号层级", "语义文字", "装饰原子", "加载占位"],
+    checklist: ["中英文混排稳定", "caption/code/kbd 有固定槽位", "Skeleton/Spinner 保留回归入口"],
+    preview: (
+      <div style={designSystemExampleStyles.previewGrid}>
+        <div style={designSystemSharedStyles.previewCard}>
+          <small>Scale preview</small>
+          <div style={{ display: "grid", gap: "8px" }}>
+            <Heading as="h1" size="display-md">
+              Design token preview
+            </Heading>
+            <Heading as="h2" size="title-lg">
+              原语文案与信息层级
+            </Heading>
+            <Text size="lg">在这里统一验证 heading、body、muted、code 和快捷键标签的视觉节奏。</Text>
+            <Muted size="caption">后续页面不再自己写标题字号和辅助说明 class。</Muted>
+            <div style={designSystemSharedStyles.chipRow}>
+              <Code>--brand-500</Code>
+              <Kbd keys={["Shift", "K"]} />
+            </div>
+          </div>
+        </div>
+        <div style={designSystemSharedStyles.previewCard}>
+          <small>Atoms in use</small>
+          <div style={{ display: "grid", gap: "12px" }}>
+            <div style={designSystemSharedStyles.chipRow}>
+              <Icon icon={Mail} label="邮件" tone="accent" />
+              <Icon decorative icon={Bell} tone="muted" />
+              <Spinner showLabel size="sm" />
+            </div>
+            <Divider />
+            <Label htmlFor="design-typography-search">搜索标签</Label>
+            <SearchInput aria-label="排版预览搜索" id="design-typography-search" placeholder="搜索原语或 token" />
+            <Skeleton announce rounded shape="text" width="72%" />
+            <Skeleton animated height={44} rounded width="100%" />
+          </div>
+        </div>
+      </div>
+    )
+  },
+  {
+    id: "buttons-actions",
+    title: "Buttons & Actions",
+    chineseTitle: "按钮与动作",
+    sprint: "迭代中",
+    summary: "按钮体系已经存在一部分，这里先固定动作位布局，后续再把 subtle、xs、copy 等增强态逐步接入。",
+    primitives: ["Button", "ButtonLink", "ButtonAnchor", "CopyButton"],
+    coverage: ["主要/次要动作", "链接态", "icon-only", "复制反馈"],
+    checklist: ["动作组顺序稳定", "禁用/加载态预留", "视觉回归不依赖业务数据"],
+    preview: (
+      <div style={designSystemExampleStyles.previewGrid}>
+        <div style={designSystemExampleStyles.twoColumnGrid}>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Primary action</small>
+            <div style={designSystemSharedStyles.chipRow}>
+              <Button variant="primary">保存变更</Button>
+              <Button variant="secondary">查看历史</Button>
+            </div>
+          </div>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Lightweight action</small>
+            <div style={designSystemSharedStyles.chipRow}>
+              <Button variant="subtle">稍后处理</Button>
+              <Button variant="ghost">仅看异常</Button>
+            </div>
+          </div>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Utility action</small>
+            <div style={designSystemSharedStyles.chipRow}>
+              <Button aria-label="更多操作" iconOnly size="xs" variant="icon">
+                <Icon decorative icon={CircleAlert} size={14} />
+              </Button>
+              <CopyButton value="pnpm test:web">复制命令</CopyButton>
+            </div>
+          </div>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Danger</small>
+            <div style={designSystemSharedStyles.chipRow}>
+              <Button variant="danger">停用账号</Button>
+              <Button isLoading loadingLabel="保存中" variant="primary">
+                保存
+              </Button>
+            </div>
+          </div>
+        </div>
+        <div style={designSystemSharedStyles.previewCard}>
+          <small>Size matrix</small>
+          <div style={designSystemExampleStyles.denseGrid}>
+            <Button size="xs" variant="secondary">XS 动作</Button>
+            <Button size="sm" variant="secondary">SM 动作</Button>
+            <Button size="md" variant="primary">MD 动作</Button>
+            <Button disabled size="md" variant="secondary">不可用</Button>
+          </div>
+        </div>
+      </div>
+    )
+  },
+  {
+    id: "form-inputs",
+    title: "Form Inputs",
+    chineseTitle: "输入控件",
+    sprint: "计划中",
+    summary: "TextInput、Select、Textarea 已有基础能力，但预览页先为 SearchInput、MultiSelect 和组合表单节奏预留固定区域。",
+    primitives: ["TextInput", "SelectInput", "TextareaInput", "FormField", "SearchInput", "MultiSelect", "FilterBar"],
+    coverage: ["字段容器", "标签/帮助文案", "前后缀输入", "搜索与多选"],
+    checklist: ["单字段与组合字段分开展示", "错误/帮助/禁用态预留", "后续真实示例不改 section id"],
+    preview: (
+      <div style={designSystemExampleStyles.previewGrid}>
+        <div style={designSystemExampleStyles.twoColumnGrid}>
+          <div style={designSystemSharedStyles.previewCard}>
+            <FormField description="前缀搜索与清除动作都在原语里统一。" label="搜索账号">
+              <SearchInput aria-label="搜索账号示例" placeholder="搜索 ID / 地址 / 创建人" />
+            </FormField>
+          </div>
+          <div style={designSystemSharedStyles.previewCard}>
+            <FormField description="组合筛选、标签筛选等统一走 headless MultiSelect。" label="标签筛选">
+              <MultiSelect aria-label="标签筛选示例" defaultValue={["exceptions"]} options={demoMultiSelectOptions} />
+            </FormField>
+          </div>
+          <div style={designSystemSharedStyles.previewCard}>
+            <FormField label="状态">
+              <SelectInput aria-label="状态示例" defaultValue="enabled">
+                <option value="enabled">启用</option>
+                <option value="disabled">停用</option>
+                <option value="archived">已归档</option>
+              </SelectInput>
+            </FormField>
+          </div>
+          <div style={designSystemSharedStyles.previewCard}>
+            <FormField description="多行文案、错误说明和保存提示都从同一字段结构出去。" label="内部备注">
+              <TextareaInput aria-label="内部备注示例" defaultValue="这个账号主要给 QA 和集成环境使用。" />
+            </FormField>
+          </div>
+        </div>
+        <div style={designSystemExampleStyles.twoColumnGrid}>
+          <div style={designSystemSharedStyles.previewCard}>
+            <FormField description="禁用态保持同样高度，不改变布局节奏。" label="禁用搜索">
+              <SearchInput aria-label="禁用搜索示例" disabled placeholder="搜索暂不可用" />
+            </FormField>
+          </div>
+          <div style={designSystemSharedStyles.previewCard}>
+            <FormField description="只读字段用于展示已锁定配置。" label="只读备注">
+              <TextareaInput aria-label="只读备注示例" readOnly value="由系统策略自动生成，当前不可编辑。" />
+            </FormField>
+          </div>
+        </div>
+        <div style={designSystemSharedStyles.previewCard}>
+          <small>FilterBar composition</small>
+          <div style={designSystemExampleStyles.fullWidthCard}>
+            <PageToolbar>
+              <FilterBar columns={3}>
+                <FormField label={<span className="sr-only">搜索筛选条</span>}>
+                  <SearchInput aria-label="搜索筛选条" placeholder="搜索邮箱或显示名" />
+                </FormField>
+                <FormField label={<span className="sr-only">角色筛选条</span>}>
+                  <SelectInput aria-label="角色筛选条" defaultValue="all">
+                    <option value="all">全部角色</option>
+                    <option value="admin">管理员</option>
+                  </SelectInput>
+                </FormField>
+                <FormField label={<span className="sr-only">状态筛选条</span>}>
+                  <SelectInput aria-label="状态筛选条" defaultValue="all">
+                    <option value="all">全部状态</option>
+                    <option value="active">正常</option>
+                  </SelectInput>
+                </FormField>
+              </FilterBar>
+              <FilterBarActions>
+                <Button size="sm" variant="ghost">仅看异常</Button>
+              </FilterBarActions>
+              <FilterBarSummary>共 12 条结果</FilterBarSummary>
+            </PageToolbar>
+          </div>
+        </div>
+      </div>
+    )
+  },
+  {
+    id: "selection-controls",
+    title: "Selection Controls",
+    chineseTitle: "选择控件",
+    sprint: "计划中",
+    summary: "Switch 已有，Checkbox/Radio 还要补独立原子。这里先把单选、多选、开关拆成独立回归单元。",
+    primitives: ["Switch", "Checkbox", "Radio", "CheckboxField", "RadioGroupField"],
+    coverage: ["二元开关", "单项选择", "组选项", "状态排列"],
+    checklist: ["checked/unchecked/disabled 明确", "键盘交互后续可测", "语义标签位固定"],
+    preview: (
+      <div style={designSystemExampleStyles.previewGrid}>
+        <div style={designSystemExampleStyles.twoColumnGrid}>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Switch</small>
+            <Switch aria-label="通知开关" checked label="通知开关" />
+          </div>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Checkbox</small>
+            <Checkbox aria-label="仅看异常" defaultChecked label="仅看异常" />
+          </div>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Radio</small>
+            <Radio aria-label="按域名汇总" defaultChecked label="按域名汇总" name="selection-preview" />
+          </div>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Grouped controls</small>
+            <div style={{ display: "grid", gap: "10px" }}>
+              <Checkbox aria-label="保留归档账号" label="保留归档账号" variant="card" />
+              <Radio aria-label="仅显示生产账号" label="仅显示生产账号" name="selection-preview-card" variant="card" />
+            </div>
+          </div>
+        </div>
+      </div>
+    )
+  },
+  {
+    id: "navigation-wayfinding",
+    title: "Navigation & Wayfinding",
+    chineseTitle: "导航与路径",
+    sprint: "计划中",
+    summary: "Breadcrumb、Pagination、Tabs、Steps 会影响多个页面骨架，这里先给这四类导航各留稳定位置。",
+    primitives: ["Breadcrumb", "Pagination", "Tabs", "Steps"],
+    coverage: ["分段导航", "路径层级", "分页", "流程步骤"],
+    checklist: ["可在单独 section 做视觉回归", "active/disabled/current 预留", "后续迁移旧导航时不改锚点"],
+    preview: (
+      <div style={designSystemExampleStyles.previewGrid}>
+        <div style={designSystemExampleStyles.twoColumnGrid}>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Breadcrumb trail</small>
+            <Breadcrumb>
+              <BreadcrumbList>
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#foundations">工作台</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#surfaces-cards">设计系统</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbCurrent>导航原语</BreadcrumbCurrent>
+                </BreadcrumbItem>
+              </BreadcrumbList>
+            </Breadcrumb>
+          </div>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Segmented tabs</small>
+            <Tabs defaultValue="overview" variant="segmented">
+              <TabsList aria-label="预览标签">
+                <TabsTrigger value="overview">概览</TabsTrigger>
+                <TabsTrigger value="tokens">Token</TabsTrigger>
+                <TabsTrigger value="states">状态</TabsTrigger>
+              </TabsList>
+              <TabsPanel value="overview">同一套原语可直接承接顶栏和 landing 页的 tab 切换。</TabsPanel>
+              <TabsPanel value="tokens">Token 预览</TabsPanel>
+              <TabsPanel value="states">状态矩阵</TabsPanel>
+            </Tabs>
+          </div>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Pagination bar</small>
+            <div style={designSystemExampleStyles.fullWidthCard}>
+              <Pagination onChange={() => undefined} page={2} pageSize={20} total={120} />
+            </div>
+          </div>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Steps tracker</small>
+            <Steps currentStep={2}>
+              <StepsList>
+                <StepItem description="锁定 token 与兼容别名" step={1} title="Foundation" />
+                <StepItem description="接入共享原语与页面 shim" step={2} title="Components" />
+                <StepItem description="跑回归与截图" step={3} title="Verification" />
+              </StepsList>
+            </Steps>
+          </div>
+        </div>
+      </div>
+    )
+  },
+  {
+    id: "surfaces-cards",
+    title: "Surfaces & Cards",
+    chineseTitle: "卡片与容器",
+    sprint: "计划中",
+    summary: "用于承接 Card、EmptyState 以及页面级容器组合，明确 header/body/footer 和强调态容器的边界。",
+    primitives: ["Card", "CardHeader", "CardBody", "CardFooter", "EmptyState"],
+    coverage: ["基础卡片", "数据卡片", "状态卡片", "空状态容器"],
+    checklist: ["Card 变体与 padding 位置固定", "EmptyState 不抢其他 section 位置", "容器层级与 tokens 对齐"],
+    preview: (
+      <div style={designSystemExampleStyles.previewGrid}>
+        <div style={designSystemExampleStyles.twoColumnGrid}>
+          <Card>
+            <CardHeader>
+              <Heading as="h3" size="title-md">
+                Base card
+              </Heading>
+              <Muted size="caption">默认容器</Muted>
+            </CardHeader>
+            <CardBody>
+              <Text>用于设置页、摘要区、过滤器和普通信息分组。</Text>
+            </CardBody>
+            <CardFooter>
+              <Button size="sm" variant="secondary">
+                查看详情
+              </Button>
+            </CardFooter>
+          </Card>
+          <Card tone="brand" variant="data">
+            <CardHeader>
+              <Muted size="caption">Data card</Muted>
+              <Heading as="h3" size="title-md">
+                2,184
+              </Heading>
+            </CardHeader>
+            <CardBody>
+              <Text size="lg">最近 7 天收到的邮件</Text>
+            </CardBody>
+          </Card>
+          <Card elevation="md" isInteractive tone="warning" variant="status">
+            <CardHeader>
+              <Heading as="h3" size="title-md">
+                需要复核
+              </Heading>
+            </CardHeader>
+            <CardBody>
+              <Text>3 个账号连续 30 天无活动，建议清理或归档。</Text>
+            </CardBody>
+          </Card>
+          <EmptyState
+            actions={
+              <Button size="sm" variant="primary">
+                新建筛选
+              </Button>
+            }
+            description="当前筛选条件下还没有结果，调整状态或创建人后会在这里刷新。"
+            icon={<Icon decorative icon={Mail} tone="muted" />}
+            title="暂无账号结果"
+          />
+        </div>
+      </div>
+    )
+  },
+  {
+    id: "data-display",
+    title: "Data Display & Charts",
+    chineseTitle: "数据展示",
+    sprint: "现有 + S5 补充",
+    summary: "Table、Chart 已经有基础原语，但预览页要额外承接 KVList、Avatar 和数据密度组合的回归面。",
+    primitives: ["Table", "Chart", "KVList", "Avatar", "MetricCard"],
+    coverage: ["表格容器", "图表主题", "键值列表", "头像与身份块"],
+    checklist: ["可离线渲染", "light/dark 数据配色稳定", "后续不会依赖真实接口数据"],
+    preview: (
+      <div style={designSystemExampleStyles.previewGrid}>
+        <div style={designSystemExampleStyles.twoColumnGrid}>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Avatar stack</small>
+            <div style={designSystemSharedStyles.chipRow}>
+              <Avatar name="Will Xue" />
+              <Avatar name="Ops Team" shape="square" />
+              <Avatar fallback="QA" size="lg" />
+            </div>
+          </div>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>KV list</small>
+            <KVList density="compact" items={demoKVListItems} />
+          </div>
+        </div>
+        <div style={designSystemExampleStyles.twoColumnGrid}>
+          <MetricCard
+            className="panel workspace-card"
+            caption="+8.4%"
+            detail="较上周提升"
+            kicker="KPI"
+            title="活跃账号"
+            tone="hero"
+            value="128"
+          />
+          <MetricCard
+            className="panel workspace-card"
+            detail="可用"
+            kicker="活跃密钥"
+            title="当前可用"
+            value="6"
+            valueSize="lg"
+          />
+        </div>
+        <div style={designSystemSharedStyles.previewCard}>
+          <small>Table shell</small>
+          <div style={designSystemExampleStyles.fullWidthCard}>
+            <TableContainer density="compact" variant="liquid">
+              <Table>
+                <TableHead>
+                  <TableRow>
+                    <TableHeaderCell>ID</TableHeaderCell>
+                    <TableHeaderCell>地址</TableHeaderCell>
+                    <TableHeaderCell nowrap>状态</TableHeaderCell>
+                  </TableRow>
+                </TableHead>
+                <TableBody>
+                  <TableRow>
+                    <TableCell>acct_001</TableCell>
+                    <TableCell>ops@wemail.ai</TableCell>
+                    <TableCell>
+                      <Badge variant="success">启用</Badge>
+                    </TableCell>
+                  </TableRow>
+                  <TableRow>
+                    <TableCell>acct_002</TableCell>
+                    <TableCell>growth@wemail.ai</TableCell>
+                    <TableCell>
+                      <Badge variant="warning">停用</Badge>
+                    </TableCell>
+                  </TableRow>
+                </TableBody>
+              </Table>
+            </TableContainer>
+          </div>
+        </div>
+      </div>
+    )
+  },
+  {
+    id: "feedback-status",
+    title: "Feedback & Status",
+    chineseTitle: "反馈与状态",
+    sprint: "规划中",
+    summary: "Tag、Badge、Progress、Alert、Spinner、Skeleton 等都会在这里汇总，避免状态型原语分散到多个页面。",
+    primitives: ["Tag", "Badge", "Progress", "Alert", "Spinner", "Skeleton"],
+    coverage: ["静态状态", "进度反馈", "页内提示", "加载骨架"],
+    checklist: ["语义色与 token 对齐", "成功/警告/错误态都有入口", "快照稳定后再提交基线"],
+    preview: (
+      <div style={designSystemExampleStyles.previewGrid}>
+        <div style={designSystemExampleStyles.twoColumnGrid}>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Tag / Badge</small>
+            <div style={{ ...designSystemSharedStyles.chipRow, alignItems: "center" }}>
+              <Tag dot size="md" variant="brand">
+                新版
+              </Tag>
+              <Tag icon={<Icon decorative icon={ShieldCheck} size={14} />} size="md" variant="info">
+                合规
+              </Tag>
+              <Badge size="md" variant="success">
+                启用
+              </Badge>
+              <Badge size="md" variant="danger">
+                阻塞
+              </Badge>
+            </div>
+          </div>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Alert</small>
+            <Alert title="请先核对旧页面视觉回归" variant="warning">
+              design token 已切到共享入口后，建议优先走一轮 light / dark 截图核对。
+            </Alert>
+          </div>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Progress</small>
+            <Progress showValueLabel value={68} />
+          </div>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Loading states</small>
+            <div style={{ display: "grid", gap: "12px" }}>
+              <Spinner showLabel size="sm" />
+              <Skeleton animated rounded width="100%" />
+              <Skeleton height={12} rounded shape="text" width="62%" />
+            </div>
+          </div>
+        </div>
+      </div>
+    )
+  },
+  {
+    id: "overlays-utilities",
+    title: "Overlays & Utilities",
+    chineseTitle: "弹层与工具型原语",
+    sprint: "规划中",
+    summary: "Overlay 现有，Tooltip/Popover/ScrollArea 还未归档。这里作为所有弹层和工具型原语的统一回归面。",
+    primitives: ["Overlay", "Modal", "Drawer", "Tooltip", "Popover", "ScrollArea", "CopyButton"],
+    coverage: ["模态层", "抽屉", "悬浮提示", "滚动容器", "辅助动作"],
+    checklist: ["焦点管理后续单测/e2e 可挂载", "视觉回归截图只截稳定壳层", "工具型原语不侵入其他分区"],
+    preview: (
+      <div style={designSystemExampleStyles.previewGrid}>
+        <div style={designSystemExampleStyles.twoColumnGrid}>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Tooltip / Popover</small>
+            <div style={designSystemSharedStyles.chipRow}>
+              <Tooltip>
+                <TooltipTrigger aria-label="显示提示">聚焦提示</TooltipTrigger>
+                <TooltipContent>统一的 hover / focus 提示层。</TooltipContent>
+              </Tooltip>
+              <Popover>
+                <PopoverTrigger>打开快捷面板</PopoverTrigger>
+                <PopoverContent>
+                  <Text size="md">这里适合轻量筛选和补充配置，不适合长表单。</Text>
+                </PopoverContent>
+              </Popover>
+            </div>
+          </div>
+          <div style={designSystemSharedStyles.previewCard}>
+            <small>Scroll / Utility</small>
+            <ScrollArea aria-label="Design system scroll preview">
+              <ScrollAreaViewport style={{ maxHeight: 120, overflow: "auto", paddingRight: 8 }}>
+                <div style={{ display: "grid", gap: "8px" }}>
+                  {Array.from({ length: 6 }, (_, index) => (
+                    <Card key={index} padding="sm">
+                      <Text>滚动项 {index + 1}</Text>
+                    </Card>
+                  ))}
+                </div>
+              </ScrollAreaViewport>
+              <ScrollAreaScrollbar>
+                <ScrollAreaThumb />
+              </ScrollAreaScrollbar>
+            </ScrollArea>
+            <CopyButton value="pnpm exec playwright test -c apps/web/playwright.config.ts apps/web/e2e/design-system.spec.ts">
+              复制回归命令
+            </CopyButton>
+          </div>
+        </div>
+        <div style={designSystemExampleStyles.twoColumnGrid}>
+          <Card padding="sm" variant="status">
+            <CardHeader>
+              <Heading as="h3" size="title-md">
+                Dialog shell
+              </Heading>
+            </CardHeader>
+            <CardBody>
+              <Text size="md">预览页不直接挂打开态 modal，避免挡住整页；统一壳层由 Overlay 原语与 e2e 共同验证。</Text>
+            </CardBody>
+          </Card>
+          <Card padding="sm" tone="info" variant="status">
+            <CardHeader>
+              <Heading as="h3" size="title-md">
+                Drawer shell
+              </Heading>
+            </CardHeader>
+            <CardBody>
+              <Text size="md">抽屉、tooltip、popover 共用同一套层级 token 与交互语义，真实打开态放到单测和后续示例页。</Text>
+            </CardBody>
+          </Card>
+        </div>
+      </div>
+    )
+  }
+];
+
+export function findDesignSystemSection(sectionId: DesignSystemSectionId): DesignSystemSection {
+  const section = designSystemSections.find((item) => item.id === sectionId);
+
+  if (!section) {
+    throw new Error(`Unknown design system section: ${sectionId}`);
+  }
+
+  return section;
+}
diff --git a/apps/web/src/pages/design-system/designSystemStyles.ts b/apps/web/src/pages/design-system/designSystemStyles.ts
new file mode 100644
index 0000000..c6f938b
--- /dev/null
+++ b/apps/web/src/pages/design-system/designSystemStyles.ts
@@ -0,0 +1,253 @@
+import { type CSSProperties } from "react";
+
+export const designSystemSharedStyles = {
+  stack: {
+    display: "grid",
+    gap: "16px"
+  } satisfies CSSProperties,
+  chipRow: {
+    display: "flex",
+    flexWrap: "wrap",
+    gap: "8px"
+  } satisfies CSSProperties,
+  chip: {
+    display: "inline-flex",
+    alignItems: "center",
+    gap: "6px",
+    borderRadius: "999px",
+    padding: "6px 10px",
+    fontSize: "12px",
+    lineHeight: 1.2,
+    border: "1px solid var(--border-subtle, rgba(15, 23, 42, 0.08))",
+    background: "var(--surface-secondary, rgba(15, 23, 42, 0.04))",
+    color: "var(--text, #111827)"
+  } satisfies CSSProperties,
+  previewCard: {
+    minWidth: 0,
+    overflowWrap: "anywhere",
+    border: "1px solid var(--border-subtle, rgba(15, 23, 42, 0.08))",
+    borderRadius: "16px",
+    padding: "16px",
+    background: "var(--surface-muted)",
+    display: "grid",
+    gap: "12px"
+  } satisfies CSSProperties
+};
+
+export const designSystemPageStyles = {
+  shell: {
+    maxWidth: "1440px",
+    width: "min(1440px, calc(100vw - 24px))",
+    margin: "0 auto",
+    padding: "84px 0 32px"
+  } satisfies CSSProperties,
+  hero: {
+    display: "grid",
+    gap: "20px",
+    gridTemplateColumns: "minmax(0, 1fr)",
+    alignItems: "start",
+    background: "var(--surface-muted)",
+    boxShadow: "0 18px 42px rgba(15, 23, 42, 0.08)"
+  } satisfies CSSProperties,
+  sectionLayout: {
+    display: "grid",
+    gap: "20px",
+    gridTemplateColumns: "repeat(auto-fit, minmax(280px, 1fr))",
+    alignItems: "start"
+  } satisfies CSSProperties,
+  metaGrid: {
+    display: "grid",
+    gap: "12px"
+  } satisfies CSSProperties,
+  sidebarShell: {
+    display: "grid",
+    gap: "20px",
+    alignSelf: "start",
+    position: "sticky",
+    top: "96px",
+    padding: "8px 0",
+    borderRadius: "24px",
+    border: "1px solid var(--border-subtle, rgba(15, 23, 42, 0.08))",
+    background: "var(--surface-muted)",
+    boxShadow: "0 18px 42px rgba(15, 23, 42, 0.08)"
+  } satisfies CSSProperties,
+  sidebarNav: {
+    minHeight: 0,
+    padding: "10px 10px 22px 22px",
+    border: "none",
+    borderRadius: 0,
+    background: "transparent",
+    boxShadow: "none",
+    backdropFilter: "none"
+  } satisfies CSSProperties,
+  sidebarGroup: {
+    gap: "10px"
+  } satisfies CSSProperties,
+  sidebarGroupHeader: {
+    margin: 0,
+    padding: "0 2px"
+  } satisfies CSSProperties,
+  sidebarGroupList: {
+    gap: "10px"
+  } satisfies CSSProperties,
+  sidebarButton: {
+    cursor: "pointer"
+  } satisfies CSSProperties,
+  sidebarButtonActive: {
+    boxShadow: "0 12px 24px rgba(0, 0, 0, 0.16)"
+  } satisfies CSSProperties,
+  sidebarButtonMeta: {
+    fontSize: "12px"
+  } satisfies CSSProperties,
+  sidebarDot: {
+    width: "10px",
+    height: "10px",
+    borderRadius: "999px",
+    background: "currentColor",
+    display: "inline-block"
+  } satisfies CSSProperties,
+  emphasisChip: {
+    ...designSystemSharedStyles.chip,
+    background: "var(--brand-50, rgba(255, 122, 0, 0.12))",
+    borderColor: "var(--brand-200, rgba(255, 122, 0, 0.2))",
+    color: "var(--brand-600, #b45309)"
+  } satisfies CSSProperties,
+  denseList: {
+    margin: 0,
+    paddingLeft: "18px",
+    display: "grid",
+    gap: "8px",
+    color: "var(--text-muted, #667085)"
+  } satisfies CSSProperties,
+  subheading: {
+    margin: 0,
+    fontSize: "14px",
+    fontWeight: 700,
+    color: "var(--text, #111827)"
+  } satisfies CSSProperties
+};
+
+export const designSystemExampleStyles = {
+  previewPane: {
+    minWidth: 0,
+    display: "grid",
+    gap: "16px"
+  } satisfies CSSProperties,
+  previewGrid: {
+    minWidth: 0,
+    display: "grid",
+    gap: "16px"
+  } satisfies CSSProperties,
+  twoColumnGrid: {
+    minWidth: 0,
+    display: "grid",
+    gap: "12px",
+    gridTemplateColumns: "repeat(auto-fit, minmax(min(100%, 180px), 1fr))"
+  } satisfies CSSProperties,
+  denseGrid: {
+    minWidth: 0,
+    display: "grid",
+    gap: "10px",
+    gridTemplateColumns: "repeat(auto-fit, minmax(min(100%, 128px), 1fr))"
+  } satisfies CSSProperties,
+  fullWidthCard: {
+    minWidth: 0,
+    overflowX: "auto",
+    scrollbarGutter: "stable"
+  } satisfies CSSProperties
+};
+
+export const designSystemDocStyles = {
+  shell: {
+    display: "grid",
+    gap: "20px",
+    padding: "24px",
+    borderRadius: "24px",
+    background: "var(--surface-muted)",
+    boxShadow: "0 18px 42px rgba(15, 23, 42, 0.08)"
+  } satisfies CSSProperties,
+  header: {
+    display: "grid",
+    gap: "12px",
+    paddingBottom: "16px",
+    borderBottom: "1px solid var(--border-subtle, rgba(15, 23, 42, 0.08))"
+  } satisfies CSSProperties,
+  sectionList: {
+    display: "grid",
+    gap: "16px"
+  } satisfies CSSProperties,
+  section: {
+    display: "grid",
+    gap: "10px",
+    padding: "18px 20px",
+    borderRadius: "18px",
+    border: "1px solid var(--border-subtle, rgba(15, 23, 42, 0.08))",
+    background: "var(--surface-muted)",
+    boxShadow: "0 18px 42px rgba(15, 23, 42, 0.08)"
+  } satisfies CSSProperties,
+  sectionHeading: {
+    margin: 0,
+    fontSize: "18px"
+  } satisfies CSSProperties,
+  paragraphGroup: {
+    display: "grid",
+    gap: "8px"
+  } satisfies CSSProperties,
+  exampleNote: {
+    padding: "14px 16px",
+    borderRadius: "14px",
+    background: "var(--surface-secondary, rgba(15, 23, 42, 0.04))",
+    color: "var(--text-muted, #667085)"
+  } satisfies CSSProperties,
+  guidanceNote: {
+    padding: "14px 16px",
+    borderRadius: "14px",
+    border: "1px solid var(--border-subtle, rgba(15, 23, 42, 0.08))",
+    background: "var(--surface-primary, rgba(255,255,255,0.9))"
+  } satisfies CSSProperties,
+  codeSampleList: {
+    display: "grid",
+    gap: "12px"
+  } satisfies CSSProperties,
+  codeSampleCard: {
+    display: "grid",
+    gap: "8px"
+  } satisfies CSSProperties,
+  codeSampleHeading: {
+    margin: 0,
+    fontSize: "15px",
+    color: "var(--text, #111827)"
+  } satisfies CSSProperties,
+  codeSamplePre: {
+    margin: 0,
+    padding: "14px 16px",
+    overflowX: "auto",
+    borderRadius: "14px",
+    border: "1px solid var(--border-subtle, rgba(15, 23, 42, 0.08))",
+    background: "var(--surface-secondary, rgba(15, 23, 42, 0.04))",
+    color: "var(--text, #111827)",
+    fontSize: "13px",
+    lineHeight: 1.6,
+    whiteSpace: "pre-wrap"
+  } satisfies CSSProperties
+};
+
+export function resolveDesignSystemSidebarLayoutStyle(viewportWidth?: number): CSSProperties {
+  const width = viewportWidth ?? (typeof window !== "undefined" ? window.innerWidth : 1280);
+
+  if (width < 980) {
+    return {
+      display: "grid",
+      gap: "24px",
+      gridTemplateColumns: "minmax(0, 1fr)",
+      alignItems: "start"
+    };
+  }
+
+  return {
+    display: "grid",
+    gap: "28px",
+    gridTemplateColumns: "minmax(240px, 280px) minmax(0, 1fr)",
+    alignItems: "start"
+  };
+}
diff --git a/apps/web/src/shared/README.md b/apps/web/src/shared/README.md
index 51a0186..42e95cf 100644
--- a/apps/web/src/shared/README.md
+++ b/apps/web/src/shared/README.md
@@ -6,12 +6,12 @@
 - API client
 - 样式
 - 通用 hooks
-- 通用 UI 基础组件
-- 通用按钮原语
-- 通用表单原语
-- 通用弹层原语
-- 通用表格原语
-- 通用开关原语
+- 通用 UI 基础组件与 design token
+- 通用按钮、表单、导航、反馈、容器、数据展示原语
+- 通用页面级布局与筛选条原语
+- 通用统计卡与摘要型原语
+- 通用弹层与 shared layer 工具
+- 通用表格、开关、排版、状态与工具型原语
 - 工具函数
 
 ## 🚫 不放什么
diff --git a/apps/web/src/shared/alert/AlertPrimitives.tsx b/apps/web/src/shared/alert/AlertPrimitives.tsx
new file mode 100644
index 0000000..3dc9f41
--- /dev/null
+++ b/apps/web/src/shared/alert/AlertPrimitives.tsx
@@ -0,0 +1,70 @@
+import { CircleAlert, Info, TriangleAlert, X, type LucideIcon } from "lucide-react";
+import { forwardRef, type ButtonHTMLAttributes, type HTMLAttributes, type ReactNode } from "react";
+
+type AlertVariant = "info" | "success" | "warning" | "error";
+type AlertAppearance = "soft" | "outline";
+
+type AlertProps = HTMLAttributes<HTMLDivElement> & {
+  actions?: ReactNode;
+  appearance?: AlertAppearance;
+  dismissLabel?: string;
+  icon?: ReactNode;
+  onClose?: ButtonHTMLAttributes<HTMLButtonElement>["onClick"];
+  title?: ReactNode;
+  variant?: AlertVariant;
+};
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+const iconMap: Record<AlertVariant, LucideIcon> = {
+  error: CircleAlert,
+  info: Info,
+  success: Info,
+  warning: TriangleAlert
+};
+
+export const Alert = forwardRef<HTMLDivElement, AlertProps>(function Alert(
+  {
+    actions,
+    appearance = "soft",
+    children,
+    className,
+    dismissLabel = "关闭提示",
+    icon,
+    onClose,
+    role = "alert",
+    title,
+    variant = "info",
+    ...props
+  },
+  ref
+) {
+    const Icon = iconMap[variant];
+
+    return (
+      <div
+        {...props}
+        className={cx("ui-alert", `ui-alert-${variant}`, `ui-alert-${appearance}`, className)}
+        data-state="visible"
+        ref={ref}
+        role={role}
+      >
+        <div className="ui-alert-icon" aria-hidden="true">
+          {icon ?? <Icon size={18} strokeWidth={1.8} />}
+        </div>
+        <div className="ui-alert-copy">
+          {title ? <div className="ui-alert-title">{title}</div> : null}
+          {children ? <div className="ui-alert-body">{children}</div> : null}
+          {actions ? <div className="ui-alert-actions">{actions}</div> : null}
+        </div>
+        {onClose ? (
+          <button aria-label={dismissLabel} className="ui-alert-close" onClick={onClose} type="button">
+            <X aria-hidden="true" size={16} strokeWidth={2} />
+          </button>
+        ) : null}
+      </div>
+    );
+  }
+);
diff --git a/apps/web/src/shared/alert/README.md b/apps/web/src/shared/alert/README.md
new file mode 100644
index 0000000..f94e71d
--- /dev/null
+++ b/apps/web/src/shared/alert/README.md
@@ -0,0 +1,18 @@
+# 🚨 shared/alert
+
+共享静态提示原语层。
+
+## ✅ 放什么
+- `Alert`
+- 信息 / 成功 / 警告 / 错误提示
+- 标题、正文、可选操作区与关闭按钮
+
+## 🚫 不放什么
+- Toast 级自动消失逻辑
+- 业务错误映射与重试状态机
+- 页面级布局编排
+
+## 可访问性
+- 默认 `role="alert"`
+- 关闭按钮必须带 `dismissLabel`
+- 图标默认 `aria-hidden`
diff --git a/apps/web/src/shared/alert/alert.css b/apps/web/src/shared/alert/alert.css
new file mode 100644
index 0000000..c66c984
--- /dev/null
+++ b/apps/web/src/shared/alert/alert.css
@@ -0,0 +1,65 @@
+.ui-alert {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr) auto;
+  gap: 12px;
+  align-items: start;
+  padding: 14px 16px;
+  border: 1px solid transparent;
+  border-radius: calc(var(--radius-card) - 8px);
+}
+
+.ui-alert-soft.ui-alert-info {
+  background: color-mix(in srgb, var(--info-soft, rgba(59, 130, 246, 0.14)) 100%, transparent);
+  border-color: color-mix(in srgb, var(--info-500, #3b82f6) 18%, transparent);
+}
+
+.ui-alert-soft.ui-alert-success {
+  background: color-mix(in srgb, var(--success-soft, rgba(32, 201, 151, 0.16)) 100%, transparent);
+  border-color: color-mix(in srgb, #20c997 18%, transparent);
+}
+
+.ui-alert-soft.ui-alert-warning {
+  background: color-mix(in srgb, var(--warning-soft, rgba(255, 184, 77, 0.16)) 100%, transparent);
+  border-color: color-mix(in srgb, #ffb84d 24%, transparent);
+}
+
+.ui-alert-soft.ui-alert-error {
+  background: color-mix(in srgb, rgba(239, 68, 68, 0.14) 100%, transparent);
+  border-color: color-mix(in srgb, #ef4444 24%, transparent);
+}
+
+.ui-alert-outline {
+  background: var(--surface-strong);
+  border-color: var(--border);
+}
+
+.ui-alert-copy {
+  display: grid;
+  gap: 6px;
+}
+
+.ui-alert-title {
+  font-weight: 700;
+  color: var(--text);
+}
+
+.ui-alert-body,
+.ui-alert-actions {
+  color: var(--text-muted);
+}
+
+.ui-alert-icon,
+.ui-alert-close {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--text-muted);
+}
+
+.ui-alert-close {
+  width: 28px;
+  height: 28px;
+  border: 0;
+  border-radius: 999px;
+  background: transparent;
+}
diff --git a/apps/web/src/shared/alert/index.ts b/apps/web/src/shared/alert/index.ts
new file mode 100644
index 0000000..b734013
--- /dev/null
+++ b/apps/web/src/shared/alert/index.ts
@@ -0,0 +1 @@
+export { Alert } from "./AlertPrimitives";
diff --git a/apps/web/src/shared/avatar/AvatarPrimitives.tsx b/apps/web/src/shared/avatar/AvatarPrimitives.tsx
new file mode 100644
index 0000000..05afeee
--- /dev/null
+++ b/apps/web/src/shared/avatar/AvatarPrimitives.tsx
@@ -0,0 +1,65 @@
+import { forwardRef, useState, type HTMLAttributes, type ReactNode } from "react";
+
+type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
+type AvatarShape = "circle" | "square";
+
+type AvatarProps = HTMLAttributes<HTMLSpanElement> & {
+  alt?: string;
+  fallback?: ReactNode;
+  name?: string;
+  shape?: AvatarShape;
+  size?: AvatarSize;
+  src?: string;
+};
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+function getInitials(name?: string, alt?: string) {
+  const source = name ?? alt ?? "";
+  const parts = source
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 2);
+
+  if (parts.length === 0) return "?";
+  return parts.map((part) => part.charAt(0).toUpperCase()).join("");
+}
+
+export const Avatar = forwardRef<HTMLSpanElement, AvatarProps>(function Avatar(
+  {
+    alt,
+    className,
+    fallback,
+    name,
+    shape = "circle",
+    size = "md",
+    src,
+    ...props
+  },
+  ref
+) {
+    const [hasImageError, setHasImageError] = useState(false);
+    const initials = fallback ?? getInitials(name, alt);
+    const canRenderImage = Boolean(src && !hasImageError);
+
+    return (
+      <span
+        {...props}
+        className={cx("ui-avatar", `ui-avatar-${size}`, `ui-avatar-${shape}`, className)}
+        data-state={canRenderImage ? "image" : "fallback"}
+        ref={ref}
+      >
+        {canRenderImage ? (
+          <img alt={alt} className="ui-avatar-image" onError={() => setHasImageError(true)} src={src} />
+        ) : (
+          <span aria-hidden="true" className="ui-avatar-fallback" data-testid="avatar-fallback">
+            {initials}
+          </span>
+        )}
+      </span>
+    );
+  }
+);
diff --git a/apps/web/src/shared/avatar/README.md b/apps/web/src/shared/avatar/README.md
new file mode 100644
index 0000000..0ebb90c
--- /dev/null
+++ b/apps/web/src/shared/avatar/README.md
@@ -0,0 +1,18 @@
+# 👤 shared/avatar
+
+共享头像原语层。
+
+## ✅ 放什么
+- `Avatar`
+- 图片 / fallback initials 展示
+- 尺寸、形状和加载失败兜底
+
+## 🚫 不放什么
+- 在线状态气泡
+- 业务级头像上传流程
+- 组织 / 成员权限逻辑
+
+## 状态约定
+- `data-state="image" | "fallback"`
+- `size`: `xs` / `sm` / `md` / `lg` / `xl`
+- `shape`: `circle` / `square`
diff --git a/apps/web/src/shared/avatar/avatar.css b/apps/web/src/shared/avatar/avatar.css
new file mode 100644
index 0000000..d3b4978
--- /dev/null
+++ b/apps/web/src/shared/avatar/avatar.css
@@ -0,0 +1,60 @@
+.ui-avatar {
+  position: relative;
+  overflow: hidden;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--accent) 12%, var(--surface-muted));
+  color: var(--text);
+  font-weight: 700;
+  user-select: none;
+}
+
+.ui-avatar-square {
+  border-radius: calc(var(--radius-field) - 2px);
+}
+
+.ui-avatar-xs {
+  width: 24px;
+  height: 24px;
+  font-size: 0.72rem;
+}
+
+.ui-avatar-sm {
+  width: 32px;
+  height: 32px;
+  font-size: 0.82rem;
+}
+
+.ui-avatar-md {
+  width: 40px;
+  height: 40px;
+  font-size: 0.92rem;
+}
+
+.ui-avatar-lg {
+  width: 52px;
+  height: 52px;
+  font-size: 1.05rem;
+}
+
+.ui-avatar-xl {
+  width: 64px;
+  height: 64px;
+  font-size: 1.2rem;
+}
+
+.ui-avatar-image {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.ui-avatar-fallback {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+}
diff --git a/apps/web/src/shared/avatar/index.ts b/apps/web/src/shared/avatar/index.ts
new file mode 100644
index 0000000..7adb30c
--- /dev/null
+++ b/apps/web/src/shared/avatar/index.ts
@@ -0,0 +1 @@
+export { Avatar } from "./AvatarPrimitives";
diff --git a/apps/web/src/shared/badge/BadgePrimitives.tsx b/apps/web/src/shared/badge/BadgePrimitives.tsx
new file mode 100644
index 0000000..49807f8
--- /dev/null
+++ b/apps/web/src/shared/badge/BadgePrimitives.tsx
@@ -0,0 +1,43 @@
+import { forwardRef, type HTMLAttributes } from "react";
+
+type BadgeVariant = "neutral" | "brand" | "info" | "success" | "warning" | "danger";
+type BadgeAppearance = "soft" | "solid";
+type BadgeSize = "sm" | "md";
+type BadgeStatusRole = "none" | "status";
+
+type BadgeProps = HTMLAttributes<HTMLSpanElement> & {
+  appearance?: BadgeAppearance;
+  size?: BadgeSize;
+  statusRole?: BadgeStatusRole;
+  variant?: BadgeVariant;
+};
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+export const Badge = forwardRef<HTMLSpanElement, BadgeProps>(function Badge(
+  {
+    className,
+    appearance = "soft",
+    size = "sm",
+    statusRole = "none",
+    variant = "neutral",
+    ...props
+  },
+  ref
+) {
+  return (
+    <span
+      {...props}
+      aria-live={statusRole === "status" ? "polite" : props["aria-live"]}
+      className={cx("ui-badge", `ui-badge-${variant}`, `ui-badge-${appearance}`, `ui-badge-size-${size}`, className)}
+      data-appearance={appearance}
+      data-size={size}
+      data-usage="status"
+      data-variant={variant}
+      ref={ref}
+      role={statusRole === "status" ? "status" : props.role}
+    />
+  );
+});
diff --git a/apps/web/src/shared/badge/README.md b/apps/web/src/shared/badge/README.md
new file mode 100644
index 0000000..04ac9bf
--- /dev/null
+++ b/apps/web/src/shared/badge/README.md
@@ -0,0 +1,26 @@
+# 🎖️ shared/badge
+
+共享状态徽标原语层。
+
+## ✅ 放什么
+- `Badge`
+- 启用/停用、审核、风险、运行状态等 status 语义展示
+- `variant / appearance / size` 的统一视觉分层
+- 可选 `statusRole="status"`，用于需要被屏幕阅读器感知的即时状态
+
+## 🚫 不放什么
+- 分类归档、主题标签、来源标记
+- 可选择 chip 或筛选器按钮
+- 包含复杂图标布局的业务状态卡
+
+## 状态约定
+- `variant`: `neutral` / `brand` / `info` / `success` / `warning` / `danger`
+- `appearance`: `soft` / `solid`
+- `size`: `sm` / `md`
+- `statusRole`: `none` / `status`
+
+## 使用约定
+- `Badge` 固定输出 `data-usage="status"`，明确其状态用途
+- 默认不启用 live region，只有动态状态反馈场景才传 `statusRole="status"`
+- 如果内容表达的是分类或归属，不要用 `Badge`，改用 `shared/tag`
+- 样式文件位于 `shared/badge/badge.css`，后续统一由样式 barrel 接入
diff --git a/apps/web/src/shared/badge/badge.css b/apps/web/src/shared/badge/badge.css
new file mode 100644
index 0000000..42d9098
--- /dev/null
+++ b/apps/web/src/shared/badge/badge.css
@@ -0,0 +1,88 @@
+.ui-badge {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 0;
+  max-width: 100%;
+  border: 1px solid transparent;
+  border-radius: var(--radius-full);
+  font-size: var(--font-caption);
+  font-weight: 700;
+  line-height: var(--line-caption);
+  white-space: nowrap;
+}
+
+.ui-badge-size-sm {
+  padding: 5px 10px;
+}
+
+.ui-badge-size-md {
+  padding: 7px 12px;
+}
+
+.ui-badge-neutral {
+  --ui-badge-bg-soft: color-mix(in srgb, var(--neutral-100) 72%, transparent);
+  --ui-badge-border-soft: color-mix(in srgb, var(--neutral-300) 72%, transparent);
+  --ui-badge-fg-soft: var(--neutral-700);
+  --ui-badge-bg-solid: var(--neutral-700);
+  --ui-badge-fg-solid: var(--neutral-0);
+}
+
+.ui-badge-brand {
+  --ui-badge-bg-soft: color-mix(in srgb, var(--brand-100) 76%, transparent);
+  --ui-badge-border-soft: color-mix(in srgb, var(--brand-500) 24%, transparent);
+  --ui-badge-fg-soft: var(--brand-700);
+  --ui-badge-bg-solid: var(--brand-500);
+  --ui-badge-fg-solid: var(--neutral-0);
+}
+
+.ui-badge-info {
+  --ui-badge-bg-soft: color-mix(in srgb, var(--info-100) 76%, transparent);
+  --ui-badge-border-soft: color-mix(in srgb, var(--info-500) 22%, transparent);
+  --ui-badge-fg-soft: var(--info-600);
+  --ui-badge-bg-solid: var(--info-500);
+  --ui-badge-fg-solid: var(--neutral-0);
+}
+
+.ui-badge-success {
+  --ui-badge-bg-soft: color-mix(in srgb, var(--success-100) 76%, transparent);
+  --ui-badge-border-soft: color-mix(in srgb, var(--success-500) 22%, transparent);
+  --ui-badge-fg-soft: var(--success-600);
+  --ui-badge-bg-solid: var(--success-500);
+  --ui-badge-fg-solid: var(--neutral-0);
+}
+
+.ui-badge-warning {
+  --ui-badge-bg-soft: color-mix(in srgb, var(--warning-100) 78%, transparent);
+  --ui-badge-border-soft: color-mix(in srgb, var(--warning-500) 22%, transparent);
+  --ui-badge-fg-soft: var(--warning-600);
+  --ui-badge-bg-solid: var(--warning-500);
+  --ui-badge-fg-solid: var(--neutral-900);
+}
+
+.ui-badge-danger {
+  --ui-badge-bg-soft: color-mix(in srgb, var(--danger-100) 78%, transparent);
+  --ui-badge-border-soft: color-mix(in srgb, var(--danger-500) 22%, transparent);
+  --ui-badge-fg-soft: var(--danger-600);
+  --ui-badge-bg-solid: var(--danger-500);
+  --ui-badge-fg-solid: var(--neutral-0);
+}
+
+.ui-badge-soft {
+  background: var(--ui-badge-bg-soft);
+  border-color: var(--ui-badge-border-soft);
+  color: var(--ui-badge-fg-soft);
+}
+
+.ui-badge-solid {
+  background: var(--ui-badge-bg-solid);
+  border-color: transparent;
+  color: var(--ui-badge-fg-solid);
+  box-shadow: inset 0 -1px 0 color-mix(in srgb, var(--ui-badge-bg-solid) 78%, black);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ui-badge {
+    transition: none;
+  }
+}
diff --git a/apps/web/src/shared/badge/index.ts b/apps/web/src/shared/badge/index.ts
new file mode 100644
index 0000000..08219ec
--- /dev/null
+++ b/apps/web/src/shared/badge/index.ts
@@ -0,0 +1 @@
+export { Badge } from "./BadgePrimitives";
diff --git a/apps/web/src/shared/breadcrumb/BreadcrumbPrimitives.tsx b/apps/web/src/shared/breadcrumb/BreadcrumbPrimitives.tsx
new file mode 100644
index 0000000..5822c81
--- /dev/null
+++ b/apps/web/src/shared/breadcrumb/BreadcrumbPrimitives.tsx
@@ -0,0 +1,87 @@
+import {
+  forwardRef,
+  type AnchorHTMLAttributes,
+  type HTMLAttributes,
+  type LiHTMLAttributes,
+  type OlHTMLAttributes,
+  type ReactNode
+} from "react";
+
+type BreadcrumbSeparatorProps = LiHTMLAttributes<HTMLLIElement> & {
+  children?: ReactNode;
+};
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+export const Breadcrumb = forwardRef<HTMLElement, HTMLAttributes<HTMLElement>>(function Breadcrumb(
+  { "aria-label": ariaLabel = "面包屑导航", className, ...props },
+  ref
+) {
+  return <nav {...props} aria-label={ariaLabel} className={cx("ui-breadcrumb", className)} ref={ref} />;
+});
+
+export const BreadcrumbList = forwardRef<HTMLOListElement, OlHTMLAttributes<HTMLOListElement>>(function BreadcrumbList(
+  { className, ...props },
+  ref
+) {
+  return <ol {...props} className={cx("ui-breadcrumb-list", className)} ref={ref} />;
+});
+
+export const BreadcrumbItem = forwardRef<HTMLLIElement, LiHTMLAttributes<HTMLLIElement>>(function BreadcrumbItem(
+  { className, ...props },
+  ref
+) {
+  return <li {...props} className={cx("ui-breadcrumb-item", className)} ref={ref} />;
+});
+
+export const BreadcrumbLink = forwardRef<HTMLAnchorElement, AnchorHTMLAttributes<HTMLAnchorElement>>(function BreadcrumbLink(
+  { "aria-current": ariaCurrent, className, ...props },
+  ref
+) {
+  const dataState = ariaCurrent === "page" ? "current" : "inactive";
+
+  return (
+    <a
+      {...props}
+      aria-current={ariaCurrent}
+      className={cx("ui-breadcrumb-link", className)}
+      data-state={dataState}
+      ref={ref}
+    />
+  );
+});
+
+export const BreadcrumbCurrent = forwardRef<HTMLSpanElement, HTMLAttributes<HTMLSpanElement>>(function BreadcrumbCurrent(
+  { className, ...props },
+  ref
+) {
+  return (
+    <span
+      {...props}
+      aria-current="page"
+      className={cx("ui-breadcrumb-current", className)}
+      data-state="current"
+      ref={ref}
+    />
+  );
+});
+
+export const BreadcrumbSeparator = forwardRef<HTMLLIElement, BreadcrumbSeparatorProps>(function BreadcrumbSeparator(
+  { children = "/", className, ...props },
+  ref
+) {
+  return (
+    <li
+      {...props}
+      aria-hidden="true"
+      className={cx("ui-breadcrumb-separator", className)}
+      data-state="separator"
+      ref={ref}
+      role="presentation"
+    >
+      {children}
+    </li>
+  );
+});
diff --git a/apps/web/src/shared/breadcrumb/README.md b/apps/web/src/shared/breadcrumb/README.md
new file mode 100644
index 0000000..50a3fff
--- /dev/null
+++ b/apps/web/src/shared/breadcrumb/README.md
@@ -0,0 +1,27 @@
+# 🧭 shared/breadcrumb
+
+共享面包屑导航原语层。
+
+## ✅ 放什么
+- `Breadcrumb`
+- `BreadcrumbList`
+- `BreadcrumbItem`
+- `BreadcrumbLink`
+- `BreadcrumbCurrent`
+- `BreadcrumbSeparator`
+- 当前页 `aria-current="page"` 与 `data-state` 约定
+
+## 🚫 不放什么
+- 路由推导逻辑
+- 自动截断 / 折叠策略
+- 页面级返回按钮或业务操作
+
+## 状态约定
+- `BreadcrumbLink`: 默认 `data-state="inactive"`；传入 `aria-current="page"` 时切为 `current`
+- `BreadcrumbCurrent`: 固定输出 `aria-current="page"` 和 `data-state="current"`
+- `BreadcrumbSeparator`: 固定 `data-state="separator"`，默认内容为 `/`
+
+## 可访问性
+- 根节点渲染 `<nav aria-label>`
+- 列表使用 `<ol>`，顺序与用户路径一致
+- 当前页应使用 `BreadcrumbCurrent`，避免将当前节点误渲染为可点击链接
diff --git a/apps/web/src/shared/breadcrumb/breadcrumb.css b/apps/web/src/shared/breadcrumb/breadcrumb.css
new file mode 100644
index 0000000..e660f40
--- /dev/null
+++ b/apps/web/src/shared/breadcrumb/breadcrumb.css
@@ -0,0 +1,40 @@
+.ui-breadcrumb {
+  display: block;
+}
+
+.ui-breadcrumb-list {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.ui-breadcrumb-item {
+  min-width: 0;
+}
+
+.ui-breadcrumb-link,
+.ui-breadcrumb-current {
+  display: inline-flex;
+  align-items: center;
+  min-height: 28px;
+  color: var(--text-muted);
+  text-decoration: none;
+}
+
+.ui-breadcrumb-link[data-state="inactive"]:hover,
+.ui-breadcrumb-link[data-state="inactive"]:focus-visible {
+  color: var(--text);
+}
+
+.ui-breadcrumb-current[data-state="current"] {
+  color: var(--text);
+  font-weight: 600;
+}
+
+.ui-breadcrumb-separator {
+  color: var(--text-subtle, var(--text-muted));
+}
diff --git a/apps/web/src/shared/breadcrumb/index.ts b/apps/web/src/shared/breadcrumb/index.ts
new file mode 100644
index 0000000..c18dbe0
--- /dev/null
+++ b/apps/web/src/shared/breadcrumb/index.ts
@@ -0,0 +1,8 @@
+export {
+  Breadcrumb,
+  BreadcrumbCurrent,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbSeparator
+} from "./BreadcrumbPrimitives";
diff --git a/apps/web/src/shared/button/ButtonPrimitives.tsx b/apps/web/src/shared/button/ButtonPrimitives.tsx
index 204e912..1c940b5 100644
--- a/apps/web/src/shared/button/ButtonPrimitives.tsx
+++ b/apps/web/src/shared/button/ButtonPrimitives.tsx
@@ -7,7 +7,7 @@ import {
 } from "react";
 import { Link, type LinkProps } from "react-router-dom";
 
-type ButtonVariant = "primary" | "secondary" | "ghost" | "text" | "danger" | "icon" | "pill";
+type ButtonVariant = "primary" | "secondary" | "subtle" | "ghost" | "text" | "danger" | "icon" | "pill";
 type ButtonSize = "xs" | "sm" | "md" | "lg";
 
 type ButtonSharedProps = {
diff --git a/apps/web/src/shared/card/CardPrimitives.tsx b/apps/web/src/shared/card/CardPrimitives.tsx
new file mode 100644
index 0000000..d3bd3b0
--- /dev/null
+++ b/apps/web/src/shared/card/CardPrimitives.tsx
@@ -0,0 +1,73 @@
+import { forwardRef, type HTMLAttributes } from "react";
+
+type CardVariant = "base" | "data" | "status" | "accent";
+type CardPadding = "none" | "sm" | "md" | "lg";
+type CardElevation = "flat" | "sm" | "md" | "lg";
+type CardTone = "neutral" | "brand" | "info" | "success" | "warning" | "danger";
+
+type CardProps = HTMLAttributes<HTMLDivElement> & {
+  elevation?: CardElevation;
+  isInteractive?: boolean;
+  padding?: CardPadding;
+  tone?: CardTone;
+  variant?: CardVariant;
+};
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+export const Card = forwardRef<HTMLDivElement, CardProps>(function Card(
+  {
+    className,
+    elevation = "sm",
+    isInteractive,
+    padding = "md",
+    tone = "neutral",
+    variant = "base",
+    ...props
+  },
+  ref
+) {
+  return (
+    <div
+      {...props}
+      className={cx(
+        "ui-card",
+        `ui-card-${variant}`,
+        `ui-card-padding-${padding}`,
+        `ui-card-elevation-${elevation}`,
+        `ui-card-tone-${tone}`,
+        isInteractive && "is-interactive",
+        className
+      )}
+      data-elevation={elevation}
+      data-padding={padding}
+      data-state={isInteractive ? "interactive" : undefined}
+      data-tone={tone}
+      data-variant={variant}
+      ref={ref}
+    />
+  );
+});
+
+export const CardHeader = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function CardHeader(
+  { className, ...props },
+  ref
+) {
+  return <div {...props} className={cx("ui-card-header", className)} ref={ref} />;
+});
+
+export const CardBody = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function CardBody(
+  { className, ...props },
+  ref
+) {
+  return <div {...props} className={cx("ui-card-body", className)} ref={ref} />;
+});
+
+export const CardFooter = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function CardFooter(
+  { className, ...props },
+  ref
+) {
+  return <div {...props} className={cx("ui-card-footer", className)} ref={ref} />;
+});
diff --git a/apps/web/src/shared/card/README.md b/apps/web/src/shared/card/README.md
new file mode 100644
index 0000000..ecb3ae8
--- /dev/null
+++ b/apps/web/src/shared/card/README.md
@@ -0,0 +1,29 @@
+# 🪪 shared/card
+
+共享卡片原语层。
+
+## ✅ 放什么
+- `Card`
+- `CardHeader` / `CardBody` / `CardFooter`
+- 统一的 `variant / padding / elevation / tone` 外观约定
+- 数据看板、状态摘要、强调面板等容器壳层
+- 可选的 `isInteractive` hover / focus 样式钩子
+
+## 🚫 不放什么
+- 可折叠、拖拽、排序等复杂容器行为
+- 业务级统计排版规则
+- 卡片内部的数据请求和状态机
+
+## 状态约定
+- `variant`: `base` / `data` / `status` / `accent`
+- `padding`: `none` / `sm` / `md` / `lg`
+- `elevation`: `flat` / `sm` / `md` / `lg`
+- `tone`: `neutral` / `brand` / `info` / `success` / `warning` / `danger`
+- `isInteractive`: 输出 `data-state="interactive"` 与 `.is-interactive`
+
+## 使用约定
+- 普通信息承载用 `variant="base"`
+- 指标看板优先用 `variant="data"`
+- 状态汇总或告警容器用 `variant="status"`
+- 品牌强调或重点入口用 `variant="accent"`
+- 样式文件位于 `shared/card/card.css`，后续统一由样式 barrel 接入
diff --git a/apps/web/src/shared/card/card.css b/apps/web/src/shared/card/card.css
new file mode 100644
index 0000000..5fcb81e
--- /dev/null
+++ b/apps/web/src/shared/card/card.css
@@ -0,0 +1,163 @@
+.ui-card {
+  display: grid;
+  gap: var(--space-4);
+  min-width: 0;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  background:
+    linear-gradient(180deg, color-mix(in srgb, var(--surface) 92%, transparent), color-mix(in srgb, var(--surface-muted) 94%, transparent));
+  color: var(--text);
+  box-shadow: var(--elevation-sm);
+  transition:
+    transform var(--duration-base) var(--ease-standard),
+    box-shadow var(--duration-base) var(--ease-standard),
+    border-color var(--duration-fast) var(--ease-standard),
+    background var(--duration-fast) var(--ease-standard);
+}
+
+.ui-card-padding-none {
+  padding: 0;
+}
+
+.ui-card-padding-sm {
+  padding: var(--space-4);
+}
+
+.ui-card-padding-md {
+  padding: var(--space-5);
+}
+
+.ui-card-padding-lg {
+  padding: var(--space-6);
+}
+
+.ui-card-elevation-flat {
+  box-shadow: none;
+}
+
+.ui-card-elevation-sm {
+  box-shadow: var(--elevation-sm);
+}
+
+.ui-card-elevation-md {
+  box-shadow: var(--elevation-md);
+}
+
+.ui-card-elevation-lg {
+  box-shadow: var(--elevation-lg);
+}
+
+.ui-card-data {
+  gap: var(--space-3);
+}
+
+.ui-card-data .ui-card-body {
+  font-family: var(--font-mono);
+  font-size: calc(var(--font-title-lg) * 1.08);
+  line-height: var(--line-title);
+  letter-spacing: -0.03em;
+}
+
+.ui-card-status {
+  background:
+    linear-gradient(180deg, color-mix(in srgb, var(--surface-strong) 90%, transparent), color-mix(in srgb, var(--surface-muted) 94%, transparent));
+}
+
+.ui-card-accent {
+  border-color: color-mix(in srgb, var(--brand-500) 20%, var(--border));
+}
+
+.ui-card-tone-neutral {
+  --ui-card-tone: var(--neutral-500);
+  --ui-card-tone-soft: color-mix(in srgb, var(--neutral-100) 78%, transparent);
+}
+
+.ui-card-tone-brand {
+  --ui-card-tone: var(--brand-500);
+  --ui-card-tone-soft: color-mix(in srgb, var(--brand-100) 84%, transparent);
+}
+
+.ui-card-tone-info {
+  --ui-card-tone: var(--info-500);
+  --ui-card-tone-soft: color-mix(in srgb, var(--info-100) 84%, transparent);
+}
+
+.ui-card-tone-success {
+  --ui-card-tone: var(--success-500);
+  --ui-card-tone-soft: color-mix(in srgb, var(--success-100) 84%, transparent);
+}
+
+.ui-card-tone-warning {
+  --ui-card-tone: var(--warning-500);
+  --ui-card-tone-soft: color-mix(in srgb, var(--warning-100) 84%, transparent);
+}
+
+.ui-card-tone-danger {
+  --ui-card-tone: var(--danger-500);
+  --ui-card-tone-soft: color-mix(in srgb, var(--danger-100) 84%, transparent);
+}
+
+.ui-card-tone-brand,
+.ui-card-tone-info,
+.ui-card-tone-success,
+.ui-card-tone-warning,
+.ui-card-tone-danger {
+  border-color: color-mix(in srgb, var(--ui-card-tone) 20%, var(--border));
+}
+
+.ui-card-status.ui-card-tone-brand,
+.ui-card-status.ui-card-tone-info,
+.ui-card-status.ui-card-tone-success,
+.ui-card-status.ui-card-tone-warning,
+.ui-card-status.ui-card-tone-danger,
+.ui-card-accent.ui-card-tone-brand,
+.ui-card-accent.ui-card-tone-info,
+.ui-card-accent.ui-card-tone-success,
+.ui-card-accent.ui-card-tone-warning,
+.ui-card-accent.ui-card-tone-danger {
+  background:
+    linear-gradient(180deg, color-mix(in srgb, var(--ui-card-tone-soft) 86%, var(--surface-strong)), color-mix(in srgb, var(--surface) 94%, transparent));
+}
+
+.ui-card.is-interactive {
+  cursor: pointer;
+}
+
+.ui-card.is-interactive:hover,
+.ui-card.is-interactive:focus-within {
+  border-color: color-mix(in srgb, var(--ui-card-tone, var(--brand-500)) 26%, var(--border));
+  box-shadow: var(--elevation-md);
+  transform: translateY(-1px);
+}
+
+.ui-card-header,
+.ui-card-body,
+.ui-card-footer {
+  min-width: 0;
+}
+
+.ui-card-header {
+  display: grid;
+  gap: var(--space-2);
+}
+
+.ui-card-body {
+  display: grid;
+  gap: var(--space-3);
+}
+
+.ui-card-footer {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-3);
+  align-items: center;
+  color: var(--text-muted);
+  font-size: var(--font-body-md);
+  line-height: var(--line-body);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ui-card {
+    transition: none;
+  }
+}
diff --git a/apps/web/src/shared/card/index.ts b/apps/web/src/shared/card/index.ts
new file mode 100644
index 0000000..d96dee2
--- /dev/null
+++ b/apps/web/src/shared/card/index.ts
@@ -0,0 +1 @@
+export { Card, CardBody, CardFooter, CardHeader } from "./CardPrimitives";
diff --git a/apps/web/src/shared/copy-button/CopyButtonPrimitives.tsx b/apps/web/src/shared/copy-button/CopyButtonPrimitives.tsx
new file mode 100644
index 0000000..47f2c12
--- /dev/null
+++ b/apps/web/src/shared/copy-button/CopyButtonPrimitives.tsx
@@ -0,0 +1,95 @@
+import { Check, Copy } from "lucide-react";
+import { forwardRef, useEffect, useRef, useState, type ButtonHTMLAttributes, type MouseEvent, type ReactNode } from "react";
+
+type CopyState = "idle" | "copied" | "error";
+
+type CopyButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "onCopy"> & {
+  children?: ReactNode;
+  copiedLabel?: ReactNode;
+  onCopy?: (value: string) => void | Promise<void>;
+  onCopyError?: (error: unknown) => void;
+  resetAfterMs?: number;
+  value: string;
+};
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+export const CopyButton = forwardRef<HTMLButtonElement, CopyButtonProps>(function CopyButton(
+  {
+    children,
+    className,
+    copiedLabel = "已复制",
+    disabled,
+    onClick,
+    onCopy,
+    onCopyError,
+    resetAfterMs = 2000,
+    type = "button",
+    value,
+    ...props
+  },
+  ref
+) {
+    const [state, setState] = useState<CopyState>("idle");
+    const timeoutRef = useRef<number | null>(null);
+
+    useEffect(() => {
+      return () => {
+        if (timeoutRef.current) {
+          window.clearTimeout(timeoutRef.current);
+        }
+      };
+    }, []);
+
+    async function handleClick(event: MouseEvent<HTMLButtonElement>) {
+      onClick?.(event);
+      if (event.defaultPrevented || disabled) return;
+
+      try {
+        const clipboard = globalThis.navigator?.clipboard;
+        const writeText = clipboard && typeof clipboard.writeText === "function" ? clipboard.writeText.bind(clipboard) : null;
+
+        if (!writeText) {
+          throw new Error("Clipboard API unavailable");
+        }
+
+        await writeText(value);
+        await onCopy?.(value);
+        setState("copied");
+
+        if (timeoutRef.current) {
+          window.clearTimeout(timeoutRef.current);
+        }
+
+        timeoutRef.current = window.setTimeout(() => {
+          setState("idle");
+        }, resetAfterMs);
+      } catch (error) {
+        setState("error");
+        onCopyError?.(error);
+      }
+    }
+
+    const label = state === "copied" ? copiedLabel : children;
+
+    return (
+      <button
+        {...props}
+        aria-live="polite"
+        className={cx("ui-copy-button", state === "copied" && "is-copied", state === "error" && "is-error", className)}
+        data-state={state}
+        disabled={disabled}
+        onClick={handleClick}
+        ref={ref}
+        type={type}
+      >
+        <span aria-hidden="true" className="ui-copy-button-icon">
+          {state === "copied" ? <Check size={16} strokeWidth={2} /> : <Copy size={16} strokeWidth={1.8} />}
+        </span>
+        <span className="ui-copy-button-label">{label}</span>
+      </button>
+    );
+  }
+);
diff --git a/apps/web/src/shared/copy-button/README.md b/apps/web/src/shared/copy-button/README.md
new file mode 100644
index 0000000..a1d8d6d
--- /dev/null
+++ b/apps/web/src/shared/copy-button/README.md
@@ -0,0 +1,17 @@
+# 📋 shared/copy-button
+
+共享复制按钮原语层。
+
+## ✅ 放什么
+- `CopyButton`
+- 剪贴板复制、复制成功态和失败兜底
+- 统一图标、状态和按钮语义
+
+## 🚫 不放什么
+- 业务 toast
+- token 遮罩 / 展示逻辑
+- 页面级权限判断
+
+## 状态约定
+- `data-state="idle" | "copied" | "error"`
+- 通过 `resetAfterMs` 控制回落时间
diff --git a/apps/web/src/shared/copy-button/copy-button.css b/apps/web/src/shared/copy-button/copy-button.css
new file mode 100644
index 0000000..bd6121f
--- /dev/null
+++ b/apps/web/src/shared/copy-button/copy-button.css
@@ -0,0 +1,33 @@
+.ui-copy-button {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  min-height: 38px;
+  padding: 0 12px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-pill);
+  background: var(--surface-strong);
+  color: var(--text);
+  transition: border-color var(--transition-fast), background var(--transition-fast), color var(--transition-fast);
+}
+
+.ui-copy-button.is-copied {
+  border-color: color-mix(in srgb, #20c997 34%, transparent);
+  background: color-mix(in srgb, #20c997 12%, var(--surface-strong));
+}
+
+.ui-copy-button.is-error {
+  border-color: color-mix(in srgb, #ef4444 34%, transparent);
+}
+
+.ui-copy-button-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ui-copy-button {
+    transition: none;
+  }
+}
diff --git a/apps/web/src/shared/copy-button/index.ts b/apps/web/src/shared/copy-button/index.ts
new file mode 100644
index 0000000..1f0197a
--- /dev/null
+++ b/apps/web/src/shared/copy-button/index.ts
@@ -0,0 +1 @@
+export { CopyButton } from "./CopyButtonPrimitives";
diff --git a/apps/web/src/shared/divider/DividerPrimitives.tsx b/apps/web/src/shared/divider/DividerPrimitives.tsx
new file mode 100644
index 0000000..80a01fa
--- /dev/null
+++ b/apps/web/src/shared/divider/DividerPrimitives.tsx
@@ -0,0 +1,47 @@
+import { forwardRef, type HTMLAttributes } from "react";
+
+type DividerOrientation = "horizontal" | "vertical";
+type DividerInset = "none" | "sm" | "md" | "lg";
+
+type DividerProps = HTMLAttributes<HTMLDivElement> & {
+  dashed?: boolean;
+  decorative?: boolean;
+  inset?: DividerInset;
+  orientation?: DividerOrientation;
+};
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+export const Divider = forwardRef<HTMLDivElement, DividerProps>(function Divider(
+  {
+    className,
+    dashed = false,
+    decorative = false,
+    inset = "none",
+    orientation = "horizontal",
+    ...props
+  },
+  ref
+) {
+  const isVertical = orientation === "vertical";
+
+  return (
+    <div
+      {...props}
+      aria-hidden={decorative ? true : undefined}
+      aria-orientation={!decorative && isVertical ? "vertical" : undefined}
+      className={cx(
+        "ui-divider",
+        `ui-divider-${orientation}`,
+        inset !== "none" && `ui-divider-inset-${inset}`,
+        dashed && "ui-divider-dashed",
+        className
+      )}
+      data-orientation={orientation}
+      ref={ref}
+      role={decorative ? "presentation" : "separator"}
+    />
+  );
+});
diff --git a/apps/web/src/shared/divider/README.md b/apps/web/src/shared/divider/README.md
new file mode 100644
index 0000000..b7ebbd3
--- /dev/null
+++ b/apps/web/src/shared/divider/README.md
@@ -0,0 +1,18 @@
+# 〰️ shared/divider
+
+共享分隔线原语层。
+
+## ✅ 放什么
+- `Divider`
+- 横向 / 纵向分隔
+- inset、dashed、decorative 视觉约定
+
+## 🚫 不放什么
+- 带标题的 section header
+- 业务专属时间线或步骤线
+- 复杂布局边框系统
+
+## 使用约定
+- 结构分组默认用横向 `Divider`
+- 紧凑工具栏或双栏布局需要竖线时用 `orientation="vertical"`
+- 纯视觉装饰且不需要读屏器感知时传 `decorative`
diff --git a/apps/web/src/shared/divider/divider.css b/apps/web/src/shared/divider/divider.css
new file mode 100644
index 0000000..ebb97d4
--- /dev/null
+++ b/apps/web/src/shared/divider/divider.css
@@ -0,0 +1,57 @@
+.ui-divider {
+  --divider-color: color-mix(in srgb, var(--border) 84%, transparent);
+  flex: none;
+  background: var(--divider-color);
+}
+
+.ui-divider-horizontal {
+  width: 100%;
+  height: 1px;
+}
+
+.ui-divider-vertical {
+  width: 1px;
+  align-self: stretch;
+  min-height: 100%;
+}
+
+.ui-divider-dashed {
+  background: none;
+  border-color: var(--divider-color);
+  border-style: dashed;
+}
+
+.ui-divider-horizontal.ui-divider-dashed {
+  border-top-width: 1px;
+}
+
+.ui-divider-vertical.ui-divider-dashed {
+  border-left-width: 1px;
+}
+
+.ui-divider-inset-sm {
+  margin-inline: var(--space-2);
+}
+
+.ui-divider-inset-md {
+  margin-inline: var(--space-4);
+}
+
+.ui-divider-inset-lg {
+  margin-inline: var(--space-6);
+}
+
+.ui-divider-vertical.ui-divider-inset-sm,
+.ui-divider-vertical.ui-divider-inset-md,
+.ui-divider-vertical.ui-divider-inset-lg {
+  margin-inline: 0;
+  margin-block: var(--space-2);
+}
+
+.ui-divider-vertical.ui-divider-inset-md {
+  margin-block: var(--space-4);
+}
+
+.ui-divider-vertical.ui-divider-inset-lg {
+  margin-block: var(--space-6);
+}
diff --git a/apps/web/src/shared/divider/index.ts b/apps/web/src/shared/divider/index.ts
new file mode 100644
index 0000000..29e69eb
--- /dev/null
+++ b/apps/web/src/shared/divider/index.ts
@@ -0,0 +1 @@
+export { Divider } from "./DividerPrimitives";
diff --git a/apps/web/src/shared/empty-state/EmptyStatePrimitives.tsx b/apps/web/src/shared/empty-state/EmptyStatePrimitives.tsx
new file mode 100644
index 0000000..282555a
--- /dev/null
+++ b/apps/web/src/shared/empty-state/EmptyStatePrimitives.tsx
@@ -0,0 +1,63 @@
+import { forwardRef, type HTMLAttributes, type ReactNode, useId } from "react";
+
+type EmptyStateVariant = "default" | "error" | "no-access";
+
+type EmptyStateProps = HTMLAttributes<HTMLElement> & {
+  actions?: ReactNode;
+  description?: ReactNode;
+  icon?: ReactNode;
+  title: ReactNode;
+  variant?: EmptyStateVariant;
+};
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+export const EmptyState = forwardRef<HTMLElement, EmptyStateProps>(function EmptyState(
+  {
+    actions,
+    children,
+    className,
+    description,
+    icon,
+    title,
+    variant = "default",
+    ...props
+  },
+  ref
+) {
+    const titleId = useId();
+    const descriptionId = useId();
+
+    return (
+      <section
+        {...props}
+        aria-describedby={description ? descriptionId : undefined}
+        aria-labelledby={titleId}
+        className={cx("ui-empty-state", `ui-empty-state-${variant}`, className)}
+        data-variant={variant}
+        ref={ref}
+        role="region"
+      >
+        {icon ? (
+          <div aria-hidden="true" className="ui-empty-state-media">
+            {icon}
+          </div>
+        ) : null}
+        <div className="ui-empty-state-copy">
+          <h2 className="ui-empty-state-title" id={titleId}>
+            {title}
+          </h2>
+          {description ? (
+            <p className="ui-empty-state-description" id={descriptionId}>
+              {description}
+            </p>
+          ) : null}
+        </div>
+        {children ? <div className="ui-empty-state-content">{children}</div> : null}
+        {actions ? <div className="ui-empty-state-actions">{actions}</div> : null}
+      </section>
+    );
+  }
+);
diff --git a/apps/web/src/shared/empty-state/README.md b/apps/web/src/shared/empty-state/README.md
new file mode 100644
index 0000000..a802ddc
--- /dev/null
+++ b/apps/web/src/shared/empty-state/README.md
@@ -0,0 +1,27 @@
+# 🗂️ shared/empty-state
+
+共享空状态原语层。
+
+## ✅ 放什么
+- `EmptyState`
+- `icon / title / description / actions` 的标准组合
+- 默认、错误、无权限等占位反馈
+- 无数据页、空列表、空详情、权限拦截等场景的统一布局
+
+## 🚫 不放什么
+- 页面级导航或营销文案布局
+- 带表单输入的复杂 onboarding
+- 业务专属插图选择逻辑
+
+## 状态约定
+- `variant`: `default` / `error` / `no-access`
+- `title`: 必填，作为区域主标题并驱动 `aria-labelledby`
+- `description`: 可选，映射到 `aria-describedby`
+- `actions`: 可选，放置主次 CTA
+- `icon`: 可选，承载图标或轻量插图
+
+## 使用约定
+- `EmptyState` 默认输出 `role="region"`，便于空状态区块被辅助技术识别
+- `variant="error"` 用于失败反馈，`variant="no-access"` 用于权限不足，不要混用
+- 操作按钮由页面层传入，原语只负责布局和语义挂接
+- 样式文件位于 `shared/empty-state/empty-state.css`，后续统一由样式 barrel 接入
diff --git a/apps/web/src/shared/empty-state/empty-state.css b/apps/web/src/shared/empty-state/empty-state.css
new file mode 100644
index 0000000..f1a367f
--- /dev/null
+++ b/apps/web/src/shared/empty-state/empty-state.css
@@ -0,0 +1,76 @@
+.ui-empty-state {
+  display: grid;
+  justify-items: center;
+  gap: var(--space-4);
+  padding: var(--space-8);
+  border: 1px dashed color-mix(in srgb, var(--border-strong) 88%, transparent);
+  border-radius: var(--radius-xl);
+  background:
+    radial-gradient(circle at top, color-mix(in srgb, var(--surface-muted) 92%, transparent), transparent 68%),
+    linear-gradient(180deg, color-mix(in srgb, var(--surface) 96%, transparent), color-mix(in srgb, var(--surface-muted) 92%, transparent));
+  color: var(--text);
+  text-align: center;
+}
+
+.ui-empty-state-default {
+  --ui-empty-state-tone: var(--neutral-500);
+}
+
+.ui-empty-state-error {
+  --ui-empty-state-tone: var(--danger-500);
+  border-color: color-mix(in srgb, var(--danger-500) 28%, transparent);
+  background:
+    radial-gradient(circle at top, color-mix(in srgb, var(--danger-100) 52%, transparent), transparent 66%),
+    linear-gradient(180deg, color-mix(in srgb, var(--surface) 96%, transparent), color-mix(in srgb, var(--danger-100) 26%, transparent));
+}
+
+.ui-empty-state-no-access {
+  --ui-empty-state-tone: var(--warning-500);
+  border-color: color-mix(in srgb, var(--warning-500) 28%, transparent);
+  background:
+    radial-gradient(circle at top, color-mix(in srgb, var(--warning-100) 52%, transparent), transparent 66%),
+    linear-gradient(180deg, color-mix(in srgb, var(--surface) 96%, transparent), color-mix(in srgb, var(--warning-100) 24%, transparent));
+}
+
+.ui-empty-state-media {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 56px;
+  height: 56px;
+  border-radius: var(--radius-lg);
+  background: color-mix(in srgb, var(--ui-empty-state-tone) 14%, var(--surface-strong));
+  color: var(--ui-empty-state-tone);
+}
+
+.ui-empty-state-copy {
+  display: grid;
+  gap: var(--space-2);
+  max-width: 36rem;
+}
+
+.ui-empty-state-title {
+  font-size: var(--font-title-md);
+  line-height: var(--line-title);
+  letter-spacing: -0.03em;
+}
+
+.ui-empty-state-description,
+.ui-empty-state-content {
+  color: var(--text-muted);
+  font-size: var(--font-body-md);
+  line-height: var(--line-body);
+}
+
+.ui-empty-state-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-3);
+  justify-content: center;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ui-empty-state {
+    transition: none;
+  }
+}
diff --git a/apps/web/src/shared/empty-state/index.ts b/apps/web/src/shared/empty-state/index.ts
new file mode 100644
index 0000000..3e92ef3
--- /dev/null
+++ b/apps/web/src/shared/empty-state/index.ts
@@ -0,0 +1 @@
+export { EmptyState } from "./EmptyStatePrimitives";
diff --git a/apps/web/src/shared/filter-bar/FilterBarPrimitives.tsx b/apps/web/src/shared/filter-bar/FilterBarPrimitives.tsx
new file mode 100644
index 0000000..7e39233
--- /dev/null
+++ b/apps/web/src/shared/filter-bar/FilterBarPrimitives.tsx
@@ -0,0 +1,38 @@
+import { forwardRef, type HTMLAttributes } from "react";
+
+type FilterBarColumns = 2 | 3 | 4;
+
+type FilterBarProps = HTMLAttributes<HTMLDivElement> & {
+  columns?: FilterBarColumns;
+};
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+export const FilterBar = forwardRef<HTMLDivElement, FilterBarProps>(function FilterBar(
+  { className, columns = 4, ...props },
+  ref
+) {
+  return (
+    <div
+      {...props}
+      className={cx("ui-filter-bar", `ui-filter-bar-columns-${columns}`, className)}
+      ref={ref}
+    />
+  );
+});
+
+export const FilterBarActions = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function FilterBarActions(
+  { className, ...props },
+  ref
+) {
+  return <div {...props} className={cx("ui-filter-bar-actions", className)} ref={ref} />;
+});
+
+export const FilterBarSummary = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function FilterBarSummary(
+  { className, ...props },
+  ref
+) {
+  return <div {...props} className={cx("ui-filter-bar-summary", className)} ref={ref} />;
+});
diff --git a/apps/web/src/shared/filter-bar/README.md b/apps/web/src/shared/filter-bar/README.md
new file mode 100644
index 0000000..ab5b005
--- /dev/null
+++ b/apps/web/src/shared/filter-bar/README.md
@@ -0,0 +1,20 @@
+# 🧪 shared/filter-bar
+
+共享筛选条原语。
+
+## ✅ 放什么
+- `FilterBar`
+- `FilterBarActions`
+- `FilterBarSummary`
+- 搜索、筛选、轻量批量动作的统一排布
+
+## 🚫 不放什么
+- 某个页面专属字段 schema
+- 查询参数同步逻辑
+- 数据请求和防抖策略
+
+## 使用约定
+- `FilterBar` 只负责布局，不负责字段行为
+- `columns` 用来声明主筛选区的目标列数
+- 批量动作、快捷筛选等放到 `FilterBarActions`
+- 可选的结果摘要、已选数量提示可放到 `FilterBarSummary`
diff --git a/apps/web/src/shared/filter-bar/filter-bar.css b/apps/web/src/shared/filter-bar/filter-bar.css
new file mode 100644
index 0000000..91badbf
--- /dev/null
+++ b/apps/web/src/shared/filter-bar/filter-bar.css
@@ -0,0 +1,41 @@
+.ui-filter-bar {
+  display: grid;
+  gap: 12px;
+  align-items: end;
+}
+
+.ui-filter-bar-columns-2 {
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+
+.ui-filter-bar-columns-3 {
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+
+.ui-filter-bar-columns-4 {
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+}
+
+.ui-filter-bar-actions {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+
+.ui-filter-bar-summary {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+  color: var(--text-muted);
+  font-size: 0.92rem;
+}
+
+@media (max-width: 960px) {
+  .ui-filter-bar-columns-2,
+  .ui-filter-bar-columns-3,
+  .ui-filter-bar-columns-4 {
+    grid-template-columns: 1fr;
+  }
+}
diff --git a/apps/web/src/shared/filter-bar/index.ts b/apps/web/src/shared/filter-bar/index.ts
new file mode 100644
index 0000000..92fee37
--- /dev/null
+++ b/apps/web/src/shared/filter-bar/index.ts
@@ -0,0 +1 @@
+export { FilterBar, FilterBarActions, FilterBarSummary } from "./FilterBarPrimitives";
diff --git a/apps/web/src/shared/form/FormPrimitives.tsx b/apps/web/src/shared/form/FormPrimitives.tsx
index 65de832..bff3959 100644
--- a/apps/web/src/shared/form/FormPrimitives.tsx
+++ b/apps/web/src/shared/form/FormPrimitives.tsx
@@ -2,16 +2,24 @@ import {
   cloneElement,
   forwardRef,
   isValidElement,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type ChangeEvent,
   type ChangeEventHandler,
   type ComponentPropsWithoutRef,
   type InputHTMLAttributes,
+  type KeyboardEvent as ReactKeyboardEvent,
   type ReactNode,
+  type Ref,
   type SelectHTMLAttributes,
-  type TextareaHTMLAttributes,
-  useId
+  type TextareaHTMLAttributes
 } from "react";
+import { ChevronDown, Search, X } from "lucide-react";
 
 type FormTone = "default" | "error" | "success";
+type FormCheckVariant = "inline" | "card";
 
 type FormFieldProps = {
   children: ReactNode;
@@ -24,14 +32,18 @@ type FormFieldProps = {
   tone?: FormTone;
 };
 
-type CheckboxFieldProps = Omit<InputHTMLAttributes<HTMLInputElement>, "children" | "type"> & {
+type FormCheckProps = Omit<InputHTMLAttributes<HTMLInputElement>, "children" | "type"> & {
   className?: string;
   description?: ReactNode;
   inputClassName?: string;
   label: ReactNode;
-  variant?: "inline" | "card";
+  variant?: FormCheckVariant;
 };
 
+type CheckboxFieldProps = FormCheckProps;
+type CheckboxProps = FormCheckProps;
+type RadioProps = FormCheckProps;
+
 type RadioGroupOption = {
   description?: ReactNode;
   disabled?: boolean;
@@ -52,7 +64,31 @@ type RadioGroupFieldProps = {
   required?: boolean;
   tone?: FormTone;
   value?: string;
-  variant?: "inline" | "card";
+  variant?: FormCheckVariant;
+};
+
+type SearchInputProps = Omit<ComponentPropsWithoutRef<"input">, "type"> & {
+  clearLabel?: string;
+  onClear?: () => void;
+};
+
+export type MultiSelectOption = {
+  description?: ReactNode;
+  disabled?: boolean;
+  label: ReactNode;
+  value: string;
+};
+
+type MultiSelectProps = Omit<ComponentPropsWithoutRef<"div">, "defaultValue" | "onChange"> & {
+  clearLabel?: string;
+  defaultValue?: string[];
+  disabled?: boolean;
+  emptyText?: ReactNode;
+  name?: string;
+  onValueChange?: (nextValue: string[]) => void;
+  options: MultiSelectOption[];
+  placeholder?: ReactNode;
+  value?: string[];
 };
 
 function cx(...parts: Array<string | false | null | undefined>) {
@@ -63,6 +99,27 @@ function mergeIds(...values: Array<string | undefined>) {
   return values.filter(Boolean).join(" ") || undefined;
 }
 
+function assignRef<T>(ref: Ref<T> | undefined, value: T) {
+  if (!ref) return;
+  if (typeof ref === "function") {
+    ref(value);
+    return;
+  }
+  ref.current = value;
+}
+
+function mergeRefs<T>(...refs: Array<Ref<T> | undefined>) {
+  return (value: T) => {
+    refs.forEach((ref) => assignRef(ref, value));
+  };
+}
+
+function setNativeInputValue(input: HTMLInputElement, nextValue: string) {
+  const descriptor = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value");
+  descriptor?.set?.call(input, nextValue);
+  input.dispatchEvent(new Event("input", { bubbles: true }));
+}
+
 function renderFieldMeta(
   description?: ReactNode,
   descriptionId?: string,
@@ -99,6 +156,85 @@ function renderFieldLabel(label: ReactNode, required?: boolean) {
   );
 }
 
+function renderFormCheck(
+  type: "checkbox" | "radio",
+  inputId: string,
+  {
+    className,
+    description,
+    inputClassName,
+    label,
+    variant = "inline",
+    ...props
+  }: FormCheckProps,
+  ref: Ref<HTMLInputElement>
+) {
+  const descriptionId = description ? `${inputId}-description` : undefined;
+  const isChecked = props.checked ?? props.defaultChecked;
+
+  return (
+    <div
+      className={cx(
+        "form-check",
+        `form-check-${variant}`,
+        props.disabled && "is-disabled",
+        className
+      )}
+      data-disabled={props.disabled ? "true" : undefined}
+      data-state={isChecked ? "checked" : "unchecked"}
+    >
+      <input
+        {...props}
+        aria-describedby={mergeIds(props["aria-describedby"], descriptionId)}
+        className={cx("form-check-input", inputClassName)}
+        id={inputId}
+        ref={ref}
+        type={type}
+      />
+      <span className="form-check-copy">
+        <label className="form-check-label" htmlFor={inputId}>
+          {label}
+        </label>
+        {description ? (
+          <span className="form-check-description" id={descriptionId}>
+            {description}
+          </span>
+        ) : null}
+      </span>
+    </div>
+  );
+}
+
+function getMultiSelectSummary(selectedValues: string[], options: MultiSelectOption[], placeholder: ReactNode) {
+  if (selectedValues.length === 0) return placeholder;
+
+  const labels = selectedValues
+    .map((selectedValue) => options.find((option) => option.value === selectedValue)?.label)
+    .filter((label): label is ReactNode => label !== undefined);
+
+  return labels.map((label, index) => (
+    <span key={selectedValues[index]}>
+      {index > 0 ? ", " : null}
+      {label}
+    </span>
+  ));
+}
+
+function moveFocus(optionRefs: Array<HTMLInputElement | null>, startIndex: number, step: 1 | -1) {
+  const total = optionRefs.length;
+  let cursor = startIndex;
+
+  for (let attempts = 0; attempts < total; attempts += 1) {
+    cursor = (cursor + step + total) % total;
+    const next = optionRefs[cursor];
+
+    if (next && !next.disabled) {
+      next.focus();
+      return;
+    }
+  }
+}
+
 export function FormField({ children, className, description, htmlFor, label, message, required, tone = "default" }: FormFieldProps) {
   const generatedId = useId();
   const resolvedId = htmlFor ?? generatedId;
@@ -107,7 +243,7 @@ export function FormField({ children, className, description, htmlFor, label, me
   const control = isValidElement<{ id?: string; "aria-describedby"?: string }>(children)
     ? cloneElement(children, {
         "aria-describedby": mergeIds(children.props["aria-describedby"], descriptionId, messageId),
-        id: children.props.id ?? resolvedId
+        id: htmlFor ? children.props.id : children.props.id ?? resolvedId
       })
     : children;
 
@@ -131,6 +267,81 @@ export const TextInput = forwardRef<HTMLInputElement, ComponentPropsWithoutRef<"
   return <input {...props} className={cx("form-control", className)} ref={ref} />;
 });
 
+export const SearchInput = forwardRef<HTMLInputElement, SearchInputProps>(function SearchInput(
+  {
+    "aria-label": ariaLabel,
+    className,
+    clearLabel = "清除搜索",
+    defaultValue,
+    disabled,
+    onChange,
+    onClear,
+    readOnly,
+    value,
+    ...props
+  },
+  ref
+) {
+    const internalRef = useRef<HTMLInputElement>(null);
+    const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue?.toString() ?? "");
+    const isControlled = value !== undefined;
+    const currentValue = isControlled ? value?.toString() ?? "" : uncontrolledValue;
+
+    function handleChange(event: ChangeEvent<HTMLInputElement>) {
+      if (!isControlled) {
+        setUncontrolledValue(event.target.value);
+      }
+      onChange?.(event);
+    }
+
+    function handleClear() {
+      const nextTarget = internalRef.current;
+
+      if (!nextTarget) return;
+      setNativeInputValue(nextTarget, "");
+      if (!isControlled) {
+        setUncontrolledValue("");
+      }
+      nextTarget.focus();
+      onClear?.();
+    }
+
+    return (
+      <div
+        className={cx("ui-search-input", disabled && "is-disabled", className)}
+        data-disabled={disabled ? "true" : undefined}
+        data-state={currentValue ? "has-value" : "empty"}
+      >
+        <span aria-hidden="true" className="ui-search-input-icon">
+          <Search size={16} strokeWidth={1.8} />
+        </span>
+        <input
+          {...props}
+          aria-label={ariaLabel}
+          className="form-control ui-search-input-control"
+          defaultValue={defaultValue}
+          disabled={disabled}
+          onChange={handleChange}
+          readOnly={readOnly}
+          ref={mergeRefs(ref, internalRef)}
+          type="search"
+          value={value}
+        />
+        {currentValue && !disabled && !readOnly ? (
+          <button
+            aria-label={clearLabel}
+            className="ui-search-input-clear"
+            onClick={handleClear}
+            type="button"
+          >
+            <X aria-hidden="true" size={14} strokeWidth={2} />
+          </button>
+        ) : null}
+      </div>
+    );
+  }
+);
+
 export const SelectInput = forwardRef<HTMLSelectElement, SelectHTMLAttributes<HTMLSelectElement>>(function SelectInput(
   { className, ...props },
   ref
@@ -145,40 +356,198 @@ export const TextareaInput = forwardRef<HTMLTextAreaElement, TextareaHTMLAttribu
   return <textarea {...props} className={cx("form-control", "form-textarea", className)} ref={ref} />;
 });
 
-export function CheckboxField({
-  className,
-  description,
-  inputClassName,
-  label,
-  variant = "inline",
-  ...props
-}: CheckboxFieldProps) {
+export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>(function Checkbox(props, ref) {
   const generatedId = useId();
-  const inputId = props.id ?? generatedId;
-  const descriptionId = description ? `${inputId}-description` : undefined;
+  return renderFormCheck("checkbox", props.id ?? generatedId, props, ref);
+});
+
+export const Radio = forwardRef<HTMLInputElement, RadioProps>(function Radio(props, ref) {
+  const generatedId = useId();
+  return renderFormCheck("radio", props.id ?? generatedId, props, ref);
+});
+
+export function CheckboxField(props: CheckboxFieldProps) {
+  return <Checkbox {...props} />;
+}
+
+export const MultiSelect = forwardRef<HTMLDivElement, MultiSelectProps>(function MultiSelect(
+  {
+    "aria-label": ariaLabel,
+    className,
+    clearLabel = "清空选择",
+    defaultValue = [],
+    disabled = false,
+    emptyText = "暂无可选项",
+    name,
+    onValueChange,
+    options,
+    placeholder = "请选择",
+    value,
+    ...props
+  },
+  ref
+) {
+  const panelId = useId();
+  const rootRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const optionRefs = useRef<Array<HTMLInputElement | null>>([]);
+  const [internalValue, setInternalValue] = useState(defaultValue);
+  const [isOpen, setIsOpen] = useState(false);
+  const isControlled = value !== undefined;
+  const selectedValues = isControlled ? value : internalValue;
+
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const handlePointerDown = (event: MouseEvent) => {
+      const currentRoot = rootRef.current;
+      if (!currentRoot || currentRoot.contains(event.target as Node)) return;
+      setIsOpen(false);
+    };
+
+    document.addEventListener("mousedown", handlePointerDown);
+    return () => {
+      document.removeEventListener("mousedown", handlePointerDown);
+    };
+  }, [isOpen]);
+
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const firstSelectedIndex = options.findIndex((option) => selectedValues.includes(option.value) && !option.disabled);
+    const focusIndex = firstSelectedIndex >= 0 ? firstSelectedIndex : options.findIndex((option) => !option.disabled);
+    optionRefs.current[focusIndex]?.focus();
+  }, [isOpen, options, selectedValues]);
+
+  function commitValue(nextValue: string[]) {
+    if (!isControlled) {
+      setInternalValue(nextValue);
+    }
+    onValueChange?.(nextValue);
+  }
+
+  function toggleValue(nextOptionValue: string) {
+    const nextValue = selectedValues.includes(nextOptionValue)
+      ? selectedValues.filter((selectedValue) => selectedValue !== nextOptionValue)
+      : [...selectedValues, nextOptionValue];
+
+    commitValue(nextValue);
+  }
+
+  function closePanel() {
+    setIsOpen(false);
+    triggerRef.current?.focus();
+  }
+
+  function handleTriggerKeyDown(event: ReactKeyboardEvent<HTMLButtonElement>) {
+    if (disabled) return;
+
+    if (event.key === "ArrowDown" || event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      setIsOpen(true);
+    }
+  }
+
+  function handleOptionKeyDown(index: number) {
+    return (event: ReactKeyboardEvent<HTMLInputElement>) => {
+      if (event.key === "ArrowDown") {
+        event.preventDefault();
+        moveFocus(optionRefs.current, index, 1);
+      }
+
+      if (event.key === "ArrowUp") {
+        event.preventDefault();
+        moveFocus(optionRefs.current, index, -1);
+      }
+
+      if (event.key === "Escape") {
+        event.preventDefault();
+        closePanel();
+      }
+    };
+  }
+
+  function handleClear() {
+    commitValue([]);
+  }
+
+  const summary = getMultiSelectSummary(selectedValues, options, placeholder);
+  const hasSelection = selectedValues.length > 0;
+  const labelText = typeof ariaLabel === "string" ? ariaLabel : "多选";
 
   return (
-    <div className={cx("form-check", `form-check-${variant}`, className)}>
-      <input
-        {...props}
-        aria-describedby={mergeIds(props["aria-describedby"], descriptionId)}
-        className={cx("form-check-input", inputClassName)}
-        id={inputId}
-        type="checkbox"
-      />
-      <span className="form-check-copy">
-        <label className="form-check-label" htmlFor={inputId}>
-          {label}
-        </label>
-        {description ? (
-          <span className="form-check-description" id={descriptionId}>
-            {description}
+    <div
+      {...props}
+      className={cx("ui-multi-select", disabled && "is-disabled", className)}
+      data-state={isOpen ? "open" : "closed"}
+      ref={mergeRefs(ref, rootRef)}
+    >
+      <div className="ui-multi-select-trigger-shell">
+        <button
+          aria-controls={panelId}
+          aria-expanded={isOpen}
+          aria-haspopup="dialog"
+          aria-label={ariaLabel}
+          className="ui-multi-select-trigger"
+          disabled={disabled}
+          onClick={() => setIsOpen((current) => !current)}
+          onKeyDown={handleTriggerKeyDown}
+          ref={triggerRef}
+          type="button"
+        >
+          <span className={cx("ui-multi-select-value", !hasSelection && "is-placeholder")}>{summary}</span>
+          <span aria-hidden="true" className="ui-multi-select-actions">
+            <ChevronDown className="ui-multi-select-chevron" size={16} strokeWidth={1.8} />
           </span>
+        </button>
+        {hasSelection && !disabled ? (
+          <button
+            aria-label={clearLabel}
+            className="ui-multi-select-clear"
+            onClick={handleClear}
+            type="button"
+          >
+            <X size={14} strokeWidth={2} />
+          </button>
         ) : null}
-      </span>
+      </div>
+
+      {name
+        ? selectedValues.map((selectedValue) => <input key={selectedValue} name={name} type="hidden" value={selectedValue} />)
+        : null}
+
+      {isOpen ? (
+        <div aria-label={labelText} className="ui-multi-select-panel" id={panelId} role="dialog">
+          {options.length === 0 ? <div className="ui-multi-select-empty">{emptyText}</div> : null}
+          {options.map((option, index) => {
+            const isSelected = selectedValues.includes(option.value);
+
+            return (
+              <Checkbox
+                checked={isSelected}
+                className="ui-multi-select-option"
+                description={option.description}
+                disabled={option.disabled}
+                inputClassName="ui-multi-select-option-input"
+                key={option.value}
+                label={option.label}
+                onChange={() => {
+                  if (option.disabled) return;
+                  toggleValue(option.value);
+                }}
+                onKeyDown={handleOptionKeyDown(index)}
+                ref={(node) => {
+                  optionRefs.current[index] = node;
+                }}
+                variant="card"
+              />
+            );
+          })}
+        </div>
+      ) : null}
     </div>
   );
-}
+});
 
 export function RadioGroupField({
   className,
@@ -202,40 +571,23 @@ export function RadioGroupField({
       <legend className="form-label">{legend}</legend>
       {renderFieldMeta(description, `${groupId}-description`, message, `${groupId}-message`, tone)}
       <div className="form-radio-group-options">
-        {options.map((option, index) => {
+        {options.map((option) => {
           const isControlled = typeof value === "string";
           const checkedProps = isControlled ? { checked: value === option.value } : { defaultChecked: defaultValue === option.value };
-          const optionId = `${groupId}-${index}`;
-          const optionDescriptionId = option.description ? `${optionId}-description` : undefined;
 
           return (
-            <div
-              className={cx("form-check", `form-check-${variant}`, "form-radio-option", option.disabled || disabled ? "is-disabled" : undefined)}
+            <Radio
+              {...checkedProps}
+              description={option.description}
+              disabled={disabled || option.disabled}
               key={option.value}
-            >
-              <input
-                {...checkedProps}
-                aria-describedby={optionDescriptionId}
-                className="form-check-input"
-                disabled={disabled || option.disabled}
-                id={optionId}
-                name={name}
-                onChange={onChange}
-                required={required}
-                type="radio"
-                value={option.value}
-              />
-              <span className="form-check-copy">
-                <label className="form-check-label" htmlFor={optionId}>
-                  {option.label}
-                </label>
-                {option.description ? (
-                  <span className="form-check-description" id={optionDescriptionId}>
-                    {option.description}
-                  </span>
-                ) : null}
-              </span>
-            </div>
+              label={option.label}
+              name={name}
+              onChange={onChange}
+              required={required}
+              value={option.value}
+              variant={variant}
+            />
           );
         })}
       </div>
diff --git a/apps/web/src/shared/form/README.md b/apps/web/src/shared/form/README.md
index b760b43..1deb38f 100644
--- a/apps/web/src/shared/form/README.md
+++ b/apps/web/src/shared/form/README.md
@@ -3,11 +3,23 @@
 共享表单原语层。
 
 ## ✅ 放什么
-- 字段原语：`FormField`、`TextInput`、`SelectInput`、`TextareaInput`
-- 布尔与单选字段：`CheckboxField`、`RadioGroupField`
+- 字段原语：`FormField`、`TextInput`、`SearchInput`、`SelectInput`、`TextareaInput`
+- 独立布尔 / 单选原语：`Checkbox`、`Radio`
+- 组合字段：`CheckboxField`、`RadioGroupField`
+- 轻量 headless 选择器：`MultiSelect`
 - 与原生 DOM props 对齐的轻量封装
 
 ## 🚫 不放什么
 - 页面级表单编排
 - 业务校验逻辑
 - 表单状态管理和请求提交流程
+
+## 状态约定
+- `SearchInput`：`data-state="empty" | "has-value"`，内置搜索图标和清空按钮
+- `Checkbox` / `Radio`：复用 `form-check` 系统类，输出 `data-state="checked" | "unchecked"`
+- `MultiSelect`：按钮触发 + `role="dialog"` 面板，内部选项复用 `Checkbox`
+
+## 可访问性
+- `SearchInput` 依赖 `type="search"` 与显式 `aria-label`
+- `CheckboxField` / `RadioGroupField` 现有 API 保持不变
+- `MultiSelect` 支持 `Enter` / `Space` / `ArrowUp` / `ArrowDown` / `Escape`
diff --git a/apps/web/src/shared/form/form.css b/apps/web/src/shared/form/form.css
new file mode 100644
index 0000000..697f521
--- /dev/null
+++ b/apps/web/src/shared/form/form.css
@@ -0,0 +1,161 @@
+.ui-search-input {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 10px;
+  padding-inline: 14px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-field);
+  background: var(--surface-muted);
+  transition: border-color var(--transition-fast), background var(--transition-fast), box-shadow var(--transition-fast);
+}
+
+.ui-search-input:focus-within {
+  border-color: color-mix(in srgb, var(--accent) 48%, transparent);
+  background: var(--surface-strong);
+  box-shadow: var(--focus-ring, 0 0 0 3px rgba(255, 122, 0, 0.14));
+}
+
+.ui-search-input[data-disabled="true"] {
+  opacity: 0.62;
+}
+
+.ui-search-input-icon,
+.ui-search-input-clear,
+.ui-multi-select-actions {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--text-soft);
+}
+
+.form-control.ui-search-input-control {
+  min-width: 0;
+  border: 0;
+  border-radius: 0;
+  padding: 14px 0;
+  background: transparent;
+  appearance: none;
+  -webkit-appearance: none;
+  box-shadow: none;
+}
+
+.form-control.ui-search-input-control::-webkit-search-decoration,
+.form-control.ui-search-input-control::-webkit-search-cancel-button,
+.form-control.ui-search-input-control::-webkit-search-results-button,
+.form-control.ui-search-input-control::-webkit-search-results-decoration {
+  -webkit-appearance: none;
+  appearance: none;
+}
+
+.form-control.ui-search-input-control:focus {
+  background: transparent;
+  border-color: transparent;
+  box-shadow: none;
+}
+
+.ui-search-input-clear {
+  width: 28px;
+  height: 28px;
+  border: 0;
+  border-radius: 999px;
+  background: transparent;
+}
+
+.ui-multi-select {
+  position: relative;
+  display: grid;
+  gap: 10px;
+}
+
+.ui-multi-select-trigger-shell {
+  position: relative;
+}
+
+.ui-multi-select-trigger {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  width: 100%;
+  min-height: 52px;
+  padding: 14px 16px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-field);
+  background: var(--surface-muted);
+  color: var(--text);
+  text-align: left;
+  transition: border-color var(--transition-fast), background var(--transition-fast), box-shadow var(--transition-fast);
+}
+
+.ui-multi-select-trigger:focus-visible,
+.ui-multi-select[data-state="open"] .ui-multi-select-trigger {
+  outline: none;
+  border-color: color-mix(in srgb, var(--accent) 48%, transparent);
+  background: var(--surface-strong);
+  box-shadow: var(--focus-ring, 0 0 0 3px rgba(255, 122, 0, 0.14));
+}
+
+.ui-multi-select-value {
+  display: inline-flex;
+  flex-wrap: wrap;
+  gap: 0;
+}
+
+.ui-multi-select-value.is-placeholder {
+  color: var(--text-soft);
+}
+
+.ui-multi-select-actions {
+  gap: 10px;
+  flex-shrink: 0;
+}
+
+.ui-multi-select-clear {
+  position: absolute;
+  top: 50%;
+  right: 34px;
+  transform: translateY(-50%);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  border: 0;
+  border-radius: 999px;
+  background: transparent;
+  color: inherit;
+}
+
+.ui-multi-select-panel {
+  position: absolute;
+  top: calc(100% + 8px);
+  left: 0;
+  right: 0;
+  z-index: 20;
+  display: grid;
+  gap: 8px;
+  padding: 10px;
+  border: 1px solid var(--border);
+  border-radius: calc(var(--radius-field) + 2px);
+  background: var(--surface-strong);
+  box-shadow: var(--shadow-card);
+}
+
+.ui-multi-select-option {
+  margin: 0;
+}
+
+.ui-multi-select-empty {
+  padding: 8px 10px;
+  color: var(--text-muted);
+  font-size: 0.92rem;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ui-search-input,
+  .ui-multi-select-trigger {
+    transition: none;
+  }
+}
diff --git a/apps/web/src/shared/form/index.ts b/apps/web/src/shared/form/index.ts
index cec6267..f7a2057 100644
--- a/apps/web/src/shared/form/index.ts
+++ b/apps/web/src/shared/form/index.ts
@@ -1,7 +1,11 @@
 export {
+  Checkbox,
   CheckboxField,
   FormField,
+  MultiSelect,
+  Radio,
   RadioGroupField,
+  SearchInput,
   SelectInput,
   TextInput,
   TextareaInput
diff --git a/apps/web/src/shared/icon/IconPrimitives.tsx b/apps/web/src/shared/icon/IconPrimitives.tsx
new file mode 100644
index 0000000..f166b71
--- /dev/null
+++ b/apps/web/src/shared/icon/IconPrimitives.tsx
@@ -0,0 +1,58 @@
+import { forwardRef, type CSSProperties, type HTMLAttributes } from "react";
+import { type LucideIcon } from "lucide-react";
+
+type IconSize = "xs" | "sm" | "md" | "lg" | number;
+type IconTone = "current" | "muted" | "accent" | "success" | "warning" | "danger";
+
+type IconProps = Omit<HTMLAttributes<HTMLSpanElement>, "children"> & {
+  decorative?: boolean;
+  icon: LucideIcon;
+  label?: string;
+  size?: IconSize;
+  strokeWidth?: number;
+  tone?: IconTone;
+};
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+function resolveSizeClass(size: IconSize) {
+  return typeof size === "number" ? undefined : `ui-icon-${size}`;
+}
+
+function resolveStyle(size: IconSize, style?: CSSProperties) {
+  if (typeof size !== "number") return style;
+  return { ...style, "--icon-size": `${size}px` } as CSSProperties;
+}
+
+export const Icon = forwardRef<HTMLSpanElement, IconProps>(function Icon(
+  {
+    className,
+    decorative,
+    icon: Glyph,
+    label,
+    size = "md",
+    strokeWidth = 1.8,
+    style,
+    tone = "current",
+    ...props
+  },
+  ref
+) {
+  const isDecorative = decorative ?? !label;
+
+  return (
+    <span
+      {...props}
+      aria-hidden={isDecorative ? true : undefined}
+      aria-label={!isDecorative ? label : undefined}
+      className={cx("ui-icon", resolveSizeClass(size), tone !== "current" && `ui-tone-${tone}`, className)}
+      ref={ref}
+      role={!isDecorative ? "img" : undefined}
+      style={resolveStyle(size, style)}
+    >
+      <Glyph absoluteStrokeWidth aria-hidden="true" className="ui-icon-svg" strokeWidth={strokeWidth} />
+    </span>
+  );
+});
diff --git a/apps/web/src/shared/icon/README.md b/apps/web/src/shared/icon/README.md
new file mode 100644
index 0000000..50b00f1
--- /dev/null
+++ b/apps/web/src/shared/icon/README.md
@@ -0,0 +1,18 @@
+# 🧩 shared/icon
+
+共享图标原语层。
+
+## ✅ 放什么
+- `Icon`
+- lucide-react 的统一包装
+- 统一 size、tone、`currentColor` 与可访问性约定
+
+## 🚫 不放什么
+- 业务图标映射表
+- 多色 SVG 插画
+- 图标按钮（用 `shared/button` 组合）
+
+## 使用约定
+- 纯装饰图标默认读屏隐藏
+- 需要读屏器识别时显式传 `label`
+- size 优先用语义档位 `xs/sm/md/lg`；只有局部对齐场景才传数字像素
diff --git a/apps/web/src/shared/icon/icon.css b/apps/web/src/shared/icon/icon.css
new file mode 100644
index 0000000..2131c8d
--- /dev/null
+++ b/apps/web/src/shared/icon/icon.css
@@ -0,0 +1,52 @@
+.ui-icon {
+  --icon-size: 20px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--icon-size);
+  height: var(--icon-size);
+  color: currentColor;
+  flex: none;
+}
+
+.ui-icon-xs {
+  --icon-size: 14px;
+}
+
+.ui-icon-sm {
+  --icon-size: 16px;
+}
+
+.ui-icon-md {
+  --icon-size: 20px;
+}
+
+.ui-icon-lg {
+  --icon-size: 24px;
+}
+
+.ui-icon-svg {
+  width: 100%;
+  height: 100%;
+  display: block;
+}
+
+.ui-icon.ui-tone-muted {
+  color: var(--text-muted);
+}
+
+.ui-icon.ui-tone-accent {
+  color: var(--brand-500);
+}
+
+.ui-icon.ui-tone-success {
+  color: var(--success-600);
+}
+
+.ui-icon.ui-tone-warning {
+  color: var(--warning-600);
+}
+
+.ui-icon.ui-tone-danger {
+  color: var(--danger-600);
+}
diff --git a/apps/web/src/shared/icon/index.ts b/apps/web/src/shared/icon/index.ts
new file mode 100644
index 0000000..7b90f5b
--- /dev/null
+++ b/apps/web/src/shared/icon/index.ts
@@ -0,0 +1 @@
+export { Icon } from "./IconPrimitives";
diff --git a/apps/web/src/shared/kv-list/KVListPrimitives.tsx b/apps/web/src/shared/kv-list/KVListPrimitives.tsx
new file mode 100644
index 0000000..3b76b23
--- /dev/null
+++ b/apps/web/src/shared/kv-list/KVListPrimitives.tsx
@@ -0,0 +1,46 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from "react";
+
+type KVListDensity = "compact" | "comfortable";
+
+type KVListItem = {
+  action?: ReactNode;
+  hint?: ReactNode;
+  key: ReactNode;
+  value: ReactNode;
+};
+
+type KVListProps = HTMLAttributes<HTMLDListElement> & {
+  density?: KVListDensity;
+  items: KVListItem[];
+};
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+export const KVList = forwardRef<HTMLDListElement, KVListProps>(function KVList(
+  { className, density = "comfortable", items, ...props },
+  ref
+) {
+  return (
+    <dl
+      {...props}
+      className={cx("ui-kv-list", `ui-kv-list-${density}`, className)}
+      ref={ref}
+      role="list"
+    >
+      {items.map((item, index) => (
+        <div className="ui-kv-list-row" key={`${String(item.key)}-${index}`}>
+          <dt className="ui-kv-list-key">
+            {item.key}
+            {item.hint ? <span className="ui-kv-list-hint">{item.hint}</span> : null}
+          </dt>
+          <dd className="ui-kv-list-value">
+            <span>{item.value}</span>
+            {item.action ? <span className="ui-kv-list-action">{item.action}</span> : null}
+          </dd>
+        </div>
+      ))}
+    </dl>
+  );
+});
diff --git a/apps/web/src/shared/kv-list/README.md b/apps/web/src/shared/kv-list/README.md
new file mode 100644
index 0000000..44320e1
--- /dev/null
+++ b/apps/web/src/shared/kv-list/README.md
@@ -0,0 +1,13 @@
+# 🧾 shared/kv-list
+
+共享键值对列表原语层。
+
+## ✅ 放什么
+- `KVList`
+- 语义化 `<dl>` 键值展示
+- 紧凑 / 舒适密度和可选辅助动作槽位
+
+## 🚫 不放什么
+- 可编辑表单
+- 表格级排序和筛选
+- 业务格式化逻辑
diff --git a/apps/web/src/shared/kv-list/index.ts b/apps/web/src/shared/kv-list/index.ts
new file mode 100644
index 0000000..f6dbf8b
--- /dev/null
+++ b/apps/web/src/shared/kv-list/index.ts
@@ -0,0 +1 @@
+export { KVList } from "./KVListPrimitives";
diff --git a/apps/web/src/shared/kv-list/kv-list.css b/apps/web/src/shared/kv-list/kv-list.css
new file mode 100644
index 0000000..a256569
--- /dev/null
+++ b/apps/web/src/shared/kv-list/kv-list.css
@@ -0,0 +1,40 @@
+.ui-kv-list {
+  display: grid;
+  gap: 14px;
+  margin: 0;
+}
+
+.ui-kv-list-compact {
+  gap: 10px;
+}
+
+.ui-kv-list-row {
+  display: grid;
+  grid-template-columns: minmax(0, 180px) minmax(0, 1fr);
+  gap: 14px;
+  align-items: start;
+}
+
+.ui-kv-list-key,
+.ui-kv-list-value {
+  margin: 0;
+}
+
+.ui-kv-list-key {
+  display: grid;
+  gap: 4px;
+  color: var(--text-muted);
+  font-size: 0.88rem;
+}
+
+.ui-kv-list-value {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  color: var(--text);
+}
+
+.ui-kv-list-hint {
+  color: var(--text-soft);
+}
diff --git a/apps/web/src/shared/metric-card/MetricCardPrimitives.tsx b/apps/web/src/shared/metric-card/MetricCardPrimitives.tsx
new file mode 100644
index 0000000..7813dfd
--- /dev/null
+++ b/apps/web/src/shared/metric-card/MetricCardPrimitives.tsx
@@ -0,0 +1,47 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from "react";
+
+type MetricCardTone = "default" | "hero";
+type MetricCardValueSize = "lg" | "xl";
+
+type MetricCardProps = HTMLAttributes<HTMLElement> & {
+  caption?: ReactNode;
+  detail?: ReactNode;
+  kicker?: ReactNode;
+  title: ReactNode;
+  tone?: MetricCardTone;
+  value: ReactNode;
+  valueSize?: MetricCardValueSize;
+};
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+export const MetricCard = forwardRef<HTMLElement, MetricCardProps>(function MetricCard(
+  {
+    caption,
+    className,
+    detail,
+    kicker,
+    title,
+    tone = "default",
+    value,
+    valueSize = "xl",
+    ...props
+  },
+  ref
+) {
+  return (
+    <article
+      {...props}
+      className={cx("ui-metric-card", `ui-metric-card-${tone}`, `ui-metric-card-value-${valueSize}`, className)}
+      ref={ref as never}
+    >
+      {kicker ? <p className="panel-kicker ui-metric-card-kicker">{kicker}</p> : null}
+      <h2 className="ui-metric-card-title">{title}</h2>
+      <strong className="ui-metric-card-value">{value}</strong>
+      {detail ? <span className="ui-metric-card-detail">{detail}</span> : null}
+      {caption ? <small className="ui-metric-card-caption">{caption}</small> : null}
+    </article>
+  );
+});
diff --git a/apps/web/src/shared/metric-card/README.md b/apps/web/src/shared/metric-card/README.md
new file mode 100644
index 0000000..0cccc96
--- /dev/null
+++ b/apps/web/src/shared/metric-card/README.md
@@ -0,0 +1,18 @@
+# 📈 shared/metric-card
+
+共享统计卡片原语。
+
+## ✅ 放什么
+- `MetricCard`
+- 页面顶部 KPI、摘要统计、状态概览卡
+- kicker / title / value / detail / caption 的统一排布
+
+## 🚫 不放什么
+- 图表本身
+- 业务专属增长算法
+- 多层嵌套表格或复杂交互
+
+## 使用约定
+- `tone="hero"` 适合第一屏重点 KPI
+- `tone="default"` 适合设置页和摘要区的轻量统计卡
+- `valueSize` 用来控制数字的视觉权重
diff --git a/apps/web/src/shared/metric-card/index.ts b/apps/web/src/shared/metric-card/index.ts
new file mode 100644
index 0000000..a6e297e
--- /dev/null
+++ b/apps/web/src/shared/metric-card/index.ts
@@ -0,0 +1 @@
+export { MetricCard } from "./MetricCardPrimitives";
diff --git a/apps/web/src/shared/metric-card/metric-card.css b/apps/web/src/shared/metric-card/metric-card.css
new file mode 100644
index 0000000..161e7a1
--- /dev/null
+++ b/apps/web/src/shared/metric-card/metric-card.css
@@ -0,0 +1,37 @@
+.ui-metric-card {
+  display: grid;
+  gap: 10px;
+  align-content: start;
+}
+
+.ui-metric-card-hero {
+  background: var(--hero-gradient);
+}
+
+.ui-metric-card-title {
+  margin: 0;
+  font-size: 1rem;
+  letter-spacing: -0.03em;
+}
+
+.ui-metric-card-value {
+  line-height: 0.95;
+}
+
+.ui-metric-card-value-lg .ui-metric-card-value {
+  font-size: clamp(1.3rem, 2vw, 1.8rem);
+}
+
+.ui-metric-card-value-xl .ui-metric-card-value {
+  font-size: clamp(2rem, 3vw, 2.6rem);
+}
+
+.ui-metric-card-detail,
+.ui-metric-card-caption {
+  color: var(--text-muted);
+}
+
+.ui-metric-card-caption {
+  color: var(--accent);
+  font-weight: 600;
+}
diff --git a/apps/web/src/shared/overlay/OverlayPrimitives.tsx b/apps/web/src/shared/overlay/OverlayPrimitives.tsx
index 0e39e93..473716d 100644
--- a/apps/web/src/shared/overlay/OverlayPrimitives.tsx
+++ b/apps/web/src/shared/overlay/OverlayPrimitives.tsx
@@ -1,7 +1,9 @@
-import { type ReactNode, useId } from "react";
+import { createPortal } from "react-dom";
+import { type KeyboardEvent, type ReactNode, useId, useRef } from "react";
 import { X } from "lucide-react";
 
 import { Button } from "../button";
+import { getFocusableElements, useOverlayAccessibility, usePortalRoot } from "./layer-utils";
 
 type OverlayBaseProps = {
   ariaLabel?: string;
@@ -9,6 +11,7 @@ type OverlayBaseProps = {
   className?: string;
   closeLabel?: string;
   closeOnBackdrop?: boolean;
+  closeOnEscape?: boolean;
   description?: ReactNode;
   eyebrow?: ReactNode;
   footer?: ReactNode;
@@ -32,20 +35,64 @@ function stopPanelClick(event: React.MouseEvent) {
   event.stopPropagation();
 }
 
+function handleDialogKeyDown(event: KeyboardEvent<HTMLElement>, closeOnEscape: boolean, onClose: () => void) {
+  if (event.key === "Tab") {
+    const currentTarget = event.currentTarget;
+    const focusableElements = getFocusableElements(currentTarget);
+
+    if (focusableElements.length === 0) {
+      event.preventDefault();
+      currentTarget.focus();
+      return;
+    }
+
+    const first = focusableElements[0];
+    const last = focusableElements[focusableElements.length - 1];
+    const activeElement = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+
+    if (event.shiftKey && activeElement === first) {
+      event.preventDefault();
+      last.focus();
+      return;
+    }
+
+    if (!event.shiftKey && activeElement === last) {
+      event.preventDefault();
+      first.focus();
+      return;
+    }
+  }
+
+  if (!closeOnEscape || event.key !== "Escape") {
+    return;
+  }
+
+  event.stopPropagation();
+  onClose();
+}
+
 function OverlayHeader({
   closeLabel,
   description,
+  descriptionId,
   eyebrow,
   onClose,
   title,
   titleId
-}: Pick<OverlayBaseProps, "closeLabel" | "description" | "eyebrow" | "onClose" | "title"> & { titleId: string }) {
+}: Pick<OverlayBaseProps, "closeLabel" | "description" | "eyebrow" | "onClose" | "title"> & {
+  descriptionId?: string;
+  titleId: string;
+}) {
   return (
     <div className="ui-overlay-header">
       <div className="ui-overlay-title-block">
         {eyebrow ? <p className="ui-overlay-eyebrow">{eyebrow}</p> : null}
         <h2 id={titleId}>{title}</h2>
-        {description ? <p className="ui-overlay-description">{description}</p> : null}
+        {description ? (
+          <p className="ui-overlay-description" id={descriptionId}>
+            {description}
+          </p>
+        ) : null}
       </div>
       <Button aria-label={closeLabel ?? "关闭弹层"} iconOnly onClick={onClose} size="sm" variant="icon">
         <X absoluteStrokeWidth aria-hidden="true" className="workspace-icon" strokeWidth={1.9} />
@@ -65,11 +112,21 @@ export function OverlayDrawer({
   footer,
   onClose,
   title,
+  closeOnEscape = true,
   width = "md"
 }: OverlayDrawerProps) {
   const titleId = useId();
+  const descriptionId = useId();
+  const panelRef = useRef<HTMLElement | null>(null);
+  const portalRoot = usePortalRoot();
 
-  return (
+  useOverlayAccessibility({ active: true, panelRef, portalRoot });
+
+  if (!portalRoot) {
+    return null;
+  }
+
+  return createPortal(
     <div
       className="ui-overlay-backdrop ui-overlay-backdrop-drawer"
       data-testid="overlay-backdrop"
@@ -78,17 +135,30 @@ export function OverlayDrawer({
     >
       <section
         aria-label={ariaLabel}
+        aria-describedby={description ? descriptionId : undefined}
         aria-labelledby={ariaLabel ? undefined : titleId}
         aria-modal="true"
         className={cx("ui-overlay-panel ui-overlay-drawer panel", `ui-overlay-drawer-${width}`, className)}
         onClick={stopPanelClick}
+        onKeyDown={(event) => handleDialogKeyDown(event, closeOnEscape, onClose)}
+        ref={panelRef}
         role="dialog"
+        tabIndex={-1}
       >
-        <OverlayHeader closeLabel={closeLabel} description={description} eyebrow={eyebrow} onClose={onClose} title={title} titleId={titleId} />
+        <OverlayHeader
+          closeLabel={closeLabel}
+          description={description}
+          descriptionId={description ? descriptionId : undefined}
+          eyebrow={eyebrow}
+          onClose={onClose}
+          title={title}
+          titleId={titleId}
+        />
         <div className="ui-overlay-body">{children}</div>
         {footer ? <div className="ui-overlay-footer">{footer}</div> : null}
       </section>
-    </div>
+    </div>,
+    portalRoot
   );
 }
 
@@ -103,11 +173,21 @@ export function OverlayDialog({
   footer,
   onClose,
   size = "md",
-  title
+  title,
+  closeOnEscape = true
 }: OverlayDialogProps) {
   const titleId = useId();
+  const descriptionId = useId();
+  const panelRef = useRef<HTMLElement | null>(null);
+  const portalRoot = usePortalRoot();
 
-  return (
+  useOverlayAccessibility({ active: true, panelRef, portalRoot });
+
+  if (!portalRoot) {
+    return null;
+  }
+
+  return createPortal(
     <div
       className="ui-overlay-backdrop ui-overlay-backdrop-dialog"
       data-testid="overlay-backdrop"
@@ -116,16 +196,29 @@ export function OverlayDialog({
     >
       <section
         aria-label={ariaLabel}
+        aria-describedby={description ? descriptionId : undefined}
         aria-labelledby={ariaLabel ? undefined : titleId}
         aria-modal="true"
         className={cx("ui-overlay-panel ui-overlay-dialog panel", `ui-overlay-dialog-${size}`, className)}
         onClick={stopPanelClick}
+        onKeyDown={(event) => handleDialogKeyDown(event, closeOnEscape, onClose)}
+        ref={panelRef}
         role="dialog"
+        tabIndex={-1}
       >
-        <OverlayHeader closeLabel={closeLabel} description={description} eyebrow={eyebrow} onClose={onClose} title={title} titleId={titleId} />
+        <OverlayHeader
+          closeLabel={closeLabel}
+          description={description}
+          descriptionId={description ? descriptionId : undefined}
+          eyebrow={eyebrow}
+          onClose={onClose}
+          title={title}
+          titleId={titleId}
+        />
         <div className="ui-overlay-body">{children}</div>
         {footer ? <div className="ui-overlay-footer">{footer}</div> : null}
       </section>
-    </div>
+    </div>,
+    portalRoot
   );
 }
diff --git a/apps/web/src/shared/overlay/README.md b/apps/web/src/shared/overlay/README.md
index 8351b0b..e27b00e 100644
--- a/apps/web/src/shared/overlay/README.md
+++ b/apps/web/src/shared/overlay/README.md
@@ -17,3 +17,7 @@
 - 居中确认/创建弹窗用 `OverlayDialog`
 - 标题通过 `title` 传入，副标题通过 `description` 传入
 - 关闭行为由业务传 `onClose`，需要点击遮罩关闭时显式传 `closeOnBackdrop`
+- 默认支持 `Esc` 关闭；若场景必须阻止该行为，可传 `closeOnEscape={false}`
+- `description` 会自动接入 `aria-describedby`，用于补足弹层语义说明
+- 默认通过 shared layer portal 渲染到 `document.body`
+- 默认启用 focus trap、背景 inert、body scroll lock 和关闭后的焦点归还
diff --git a/apps/web/src/shared/overlay/layer-utils.ts b/apps/web/src/shared/overlay/layer-utils.ts
new file mode 100644
index 0000000..f8d7265
--- /dev/null
+++ b/apps/web/src/shared/overlay/layer-utils.ts
@@ -0,0 +1,233 @@
+import { type CSSProperties, type MutableRefObject, type Ref, useEffect, useLayoutEffect, useState } from "react";
+
+export const focusableSelector = [
+  "button:not([disabled])",
+  "[href]",
+  "input:not([disabled])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  "[tabindex]:not([tabindex='-1'])"
+].join(", ");
+
+type FloatingAlign = "start" | "center" | "end";
+type FloatingSide = "top" | "bottom";
+
+const PORTAL_ROOT_ID = "wemail-layer-root";
+const INERT_COUNT_ATTR = "data-wemail-inert-count";
+const PREV_ARIA_HIDDEN_ATTR = "data-wemail-prev-aria-hidden";
+
+function getPortalRoot() {
+  let root = document.getElementById(PORTAL_ROOT_ID) as HTMLDivElement | null;
+
+  if (!root) {
+    root = document.createElement("div");
+    root.id = PORTAL_ROOT_ID;
+    document.body.appendChild(root);
+  }
+
+  return root;
+}
+
+function setElementInert(element: HTMLElement, inert: boolean) {
+  const inertCapable = element as HTMLElement & { inert?: boolean };
+
+  if ("inert" in inertCapable) {
+    inertCapable.inert = inert;
+  }
+}
+
+export function assignRef<T>(ref: Ref<T> | undefined, value: T) {
+  if (typeof ref === "function") {
+    ref(value);
+    return;
+  }
+
+  if (ref) {
+    ref.current = value;
+  }
+}
+
+export function getFocusableElements(container: HTMLElement | null) {
+  if (!container) return [];
+  return Array.from(container.querySelectorAll<HTMLElement>(focusableSelector)).filter(
+    (element) => !element.hasAttribute("disabled")
+  );
+}
+
+export function usePortalRoot() {
+  const [portalRoot, setPortalRoot] = useState<HTMLElement | null>(null);
+
+  useEffect(() => {
+    if (typeof document === "undefined") return undefined;
+
+    const root = getPortalRoot();
+    setPortalRoot(root);
+
+    return () => {
+      if (root.childElementCount === 0) {
+        root.remove();
+      }
+    };
+  }, []);
+
+  return portalRoot;
+}
+
+export function useOverlayAccessibility({
+  active,
+  panelRef,
+  portalRoot
+}: {
+  active: boolean;
+  panelRef: MutableRefObject<HTMLElement | null>;
+  portalRoot: HTMLElement | null;
+}) {
+  useEffect(() => {
+    if (!active || !panelRef.current || !portalRoot) {
+      return undefined;
+    }
+
+    const previousActiveElement =
+      document.activeElement instanceof HTMLElement ? document.activeElement : null;
+
+    const panel = panelRef.current;
+    const focusableElements = getFocusableElements(panel);
+    const nextFocusTarget = focusableElements[0] ?? panel;
+    nextFocusTarget.focus();
+
+    const body = document.body;
+    const previousOverflow = body.style.overflow;
+    body.style.overflow = "hidden";
+
+    const siblings = Array.from(body.children).filter((element) => element !== portalRoot) as HTMLElement[];
+
+    siblings.forEach((element) => {
+      const currentCount = Number(element.getAttribute(INERT_COUNT_ATTR) ?? "0");
+
+      if (currentCount === 0) {
+        element.setAttribute(PREV_ARIA_HIDDEN_ATTR, element.getAttribute("aria-hidden") ?? "");
+        element.setAttribute("aria-hidden", "true");
+        setElementInert(element, true);
+      }
+
+      element.setAttribute(INERT_COUNT_ATTR, String(currentCount + 1));
+    });
+
+    return () => {
+      body.style.overflow = previousOverflow;
+
+      siblings.forEach((element) => {
+        const currentCount = Number(element.getAttribute(INERT_COUNT_ATTR) ?? "0");
+        const nextCount = Math.max(currentCount - 1, 0);
+
+        if (nextCount === 0) {
+          const previousAriaHidden = element.getAttribute(PREV_ARIA_HIDDEN_ATTR) ?? "";
+          if (previousAriaHidden === "") {
+            element.removeAttribute("aria-hidden");
+          } else {
+            element.setAttribute("aria-hidden", previousAriaHidden);
+          }
+          element.removeAttribute(INERT_COUNT_ATTR);
+          element.removeAttribute(PREV_ARIA_HIDDEN_ATTR);
+          setElementInert(element, false);
+        } else {
+          element.setAttribute(INERT_COUNT_ATTR, String(nextCount));
+        }
+      });
+
+      previousActiveElement?.focus();
+    };
+  }, [active, panelRef, portalRoot]);
+}
+
+export function useFloatingPosition({
+  align = "start",
+  anchorRef,
+  matchAnchorWidth = false,
+  offset = 10,
+  open,
+  preferredSide = "bottom",
+  contentRef
+}: {
+  align?: FloatingAlign;
+  anchorRef: MutableRefObject<HTMLElement | null>;
+  contentRef: MutableRefObject<HTMLElement | null>;
+  matchAnchorWidth?: boolean;
+  offset?: number;
+  open: boolean;
+  preferredSide?: FloatingSide;
+}) {
+  const [resolvedSide, setResolvedSide] = useState<FloatingSide>(preferredSide);
+  const [style, setStyle] = useState<CSSProperties>({
+    position: "fixed",
+    top: 0,
+    left: 0
+  });
+
+  useLayoutEffect(() => {
+    if (!open) return undefined;
+
+    function updatePosition() {
+      const anchor = anchorRef.current;
+      const content = contentRef.current;
+      if (!anchor || !content) return;
+
+      const anchorRect = anchor.getBoundingClientRect();
+      const contentRect = content.getBoundingClientRect();
+      const viewportWidth = window.innerWidth;
+      const viewportHeight = window.innerHeight;
+      const margin = 12;
+
+      let nextSide = preferredSide;
+
+      if (
+        preferredSide === "bottom" &&
+        anchorRect.bottom + offset + contentRect.height > viewportHeight - margin &&
+        anchorRect.top - offset - contentRect.height >= margin
+      ) {
+        nextSide = "top";
+      }
+
+      if (
+        preferredSide === "top" &&
+        anchorRect.top - offset - contentRect.height < margin &&
+        anchorRect.bottom + offset + contentRect.height <= viewportHeight - margin
+      ) {
+        nextSide = "bottom";
+      }
+
+      let left =
+        align === "center"
+          ? anchorRect.left + anchorRect.width / 2 - contentRect.width / 2
+          : align === "end"
+            ? anchorRect.right - contentRect.width
+            : anchorRect.left;
+
+      let top =
+        nextSide === "top" ? anchorRect.top - contentRect.height - offset : anchorRect.bottom + offset;
+
+      left = Math.min(Math.max(left, margin), viewportWidth - contentRect.width - margin);
+      top = Math.min(Math.max(top, margin), viewportHeight - contentRect.height - margin);
+
+      setResolvedSide(nextSide);
+      setStyle({
+        position: "fixed",
+        top,
+        left,
+        minWidth: matchAnchorWidth ? anchorRect.width : undefined
+      });
+    }
+
+    updatePosition();
+
+    window.addEventListener("resize", updatePosition);
+    window.addEventListener("scroll", updatePosition, true);
+
+    return () => {
+      window.removeEventListener("resize", updatePosition);
+      window.removeEventListener("scroll", updatePosition, true);
+    };
+  }, [align, anchorRef, contentRef, matchAnchorWidth, offset, open, preferredSide]);
+
+  return { resolvedSide, style };
+}
diff --git a/apps/web/src/shared/page-layout/PageLayoutPrimitives.tsx b/apps/web/src/shared/page-layout/PageLayoutPrimitives.tsx
new file mode 100644
index 0000000..8b8bb5b
--- /dev/null
+++ b/apps/web/src/shared/page-layout/PageLayoutPrimitives.tsx
@@ -0,0 +1,80 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from "react";
+
+type PageProps = HTMLAttributes<HTMLElement> & {
+  as?: "div" | "main" | "section";
+};
+
+type PageHeaderProps = HTMLAttributes<HTMLElement> & {
+  actions?: ReactNode;
+  description?: ReactNode;
+  kicker?: ReactNode;
+  title?: ReactNode;
+};
+
+type PageBodyProps = HTMLAttributes<HTMLDivElement> & {
+  hasSidebar?: boolean;
+};
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+export const Page = forwardRef<HTMLElement, PageProps>(function Page(
+  { as = "main", className, ...props },
+  ref
+) {
+  const Comp = as;
+
+  return <Comp {...props} className={cx("ui-page", className)} ref={ref as never} />;
+});
+
+export const PageHeader = forwardRef<HTMLElement, PageHeaderProps>(function PageHeader(
+  { actions, children, className, description, kicker, title, ...props },
+  ref
+) {
+  return (
+    <section {...props} className={cx("ui-page-header", className)} ref={ref}>
+      <div className="ui-page-header-main">
+        {kicker ? <p className="panel-kicker ui-page-header-kicker">{kicker}</p> : null}
+        {title ? <h1 className="ui-page-header-title">{title}</h1> : null}
+        {description ? <p className="section-copy ui-page-header-description">{description}</p> : null}
+        {children}
+      </div>
+      {actions ? <div className="ui-page-header-actions">{actions}</div> : null}
+    </section>
+  );
+});
+
+export const PageToolbar = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function PageToolbar(
+  { className, ...props },
+  ref
+) {
+  return <div {...props} className={cx("ui-page-toolbar", className)} ref={ref} />;
+});
+
+export const PageBody = forwardRef<HTMLDivElement, PageBodyProps>(function PageBody(
+  { className, hasSidebar = false, ...props },
+  ref
+) {
+  return (
+    <div
+      {...props}
+      className={cx("ui-page-body", hasSidebar && "ui-page-body-with-sidebar", className)}
+      ref={ref}
+    />
+  );
+});
+
+export const PageMain = forwardRef<HTMLElement, HTMLAttributes<HTMLElement>>(function PageMain(
+  { className, ...props },
+  ref
+) {
+  return <section {...props} className={cx("ui-page-main", className)} ref={ref} />;
+});
+
+export const PageSidebar = forwardRef<HTMLElement, HTMLAttributes<HTMLElement>>(function PageSidebar(
+  { className, ...props },
+  ref
+) {
+  return <aside {...props} className={cx("ui-page-sidebar", className)} ref={ref} />;
+});
diff --git a/apps/web/src/shared/page-layout/README.md b/apps/web/src/shared/page-layout/README.md
new file mode 100644
index 0000000..9c8e652
--- /dev/null
+++ b/apps/web/src/shared/page-layout/README.md
@@ -0,0 +1,23 @@
+# 🧭 shared/page-layout
+
+共享页面级布局原语。
+
+## ✅ 放什么
+- `Page`
+- `PageHeader`
+- `PageToolbar`
+- `PageBody`
+- `PageMain`
+- `PageSidebar`
+- 统一页面头部、操作区、主内容与侧栏排布
+
+## 🚫 不放什么
+- 具体业务页面的数据请求
+- 某一个页面专属的过滤逻辑
+- 卡片内部的业务排版
+
+## 使用约定
+- `PageHeader` 负责 kicker / title / description / actions 的基础布局
+- `PageToolbar` 用于搜索、筛选、批量动作等顶层操作排布
+- 有侧栏时用 `PageBody + PageMain + PageSidebar`
+- 无侧栏时可只用 `Page + PageHeader + PageMain`
diff --git a/apps/web/src/shared/page-layout/index.ts b/apps/web/src/shared/page-layout/index.ts
new file mode 100644
index 0000000..6a0fc3f
--- /dev/null
+++ b/apps/web/src/shared/page-layout/index.ts
@@ -0,0 +1 @@
+export { Page, PageBody, PageHeader, PageMain, PageSidebar, PageToolbar } from "./PageLayoutPrimitives";
diff --git a/apps/web/src/shared/page-layout/page-layout.css b/apps/web/src/shared/page-layout/page-layout.css
new file mode 100644
index 0000000..29ebf17
--- /dev/null
+++ b/apps/web/src/shared/page-layout/page-layout.css
@@ -0,0 +1,63 @@
+.ui-page {
+  display: grid;
+  gap: 16px;
+}
+
+.ui-page-header {
+  display: flex;
+  align-items: start;
+  justify-content: space-between;
+  gap: 16px;
+  flex-wrap: wrap;
+}
+
+.ui-page-header-main {
+  display: grid;
+  gap: 8px;
+  min-width: 0;
+}
+
+.ui-page-header-title {
+  margin: 0;
+  font-size: clamp(1.6rem, 2vw, 2rem);
+  line-height: 1.15;
+  letter-spacing: -0.04em;
+}
+
+.ui-page-header-actions {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+
+.ui-page-toolbar {
+  display: flex;
+  align-items: end;
+  justify-content: space-between;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+
+.ui-page-body {
+  display: grid;
+  gap: 16px;
+}
+
+.ui-page-body-with-sidebar {
+  grid-template-columns: minmax(0, 1.6fr) minmax(260px, 0.9fr);
+  align-items: start;
+}
+
+.ui-page-main,
+.ui-page-sidebar {
+  display: grid;
+  gap: 16px;
+  min-width: 0;
+}
+
+@media (max-width: 960px) {
+  .ui-page-body-with-sidebar {
+    grid-template-columns: 1fr;
+  }
+}
diff --git a/apps/web/src/shared/pagination/PaginationPrimitives.tsx b/apps/web/src/shared/pagination/PaginationPrimitives.tsx
new file mode 100644
index 0000000..53aa9cd
--- /dev/null
+++ b/apps/web/src/shared/pagination/PaginationPrimitives.tsx
@@ -0,0 +1,226 @@
+import {
+  forwardRef,
+  type ButtonHTMLAttributes,
+  type HTMLAttributes,
+  type KeyboardEvent,
+  type ReactNode
+} from "react";
+
+type PaginationProps = Omit<HTMLAttributes<HTMLElement>, "onChange"> & {
+  onChange?: (page: number) => void;
+  page: number;
+  pageSize: number;
+  siblings?: number;
+  total: number;
+};
+
+type PaginationButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
+  children: ReactNode;
+  isCurrent?: boolean;
+};
+
+type PaginationItem = number | "ellipsis-left" | "ellipsis-right";
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+function clamp(value: number, minimum: number, maximum: number) {
+  return Math.min(Math.max(value, minimum), maximum);
+}
+
+function getPageCount(total: number, pageSize: number) {
+  if (pageSize <= 0) return 1;
+  return Math.max(1, Math.ceil(total / pageSize));
+}
+
+function buildPaginationItems(pageCount: number, currentPage: number, siblings: number): PaginationItem[] {
+  if (pageCount <= 1) {
+    return [1];
+  }
+
+  const safeSiblings = Math.max(0, siblings);
+  const maxVisiblePages = safeSiblings * 2 + 5;
+
+  if (pageCount <= maxVisiblePages) {
+    return Array.from({ length: pageCount }, (_, index) => index + 1);
+  }
+
+  const leftBoundary = Math.max(currentPage - safeSiblings, 2);
+  const rightBoundary = Math.min(currentPage + safeSiblings, pageCount - 1);
+  const items: PaginationItem[] = [1];
+
+  if (leftBoundary > 2) {
+    items.push("ellipsis-left");
+  } else {
+    for (let page = 2; page < leftBoundary; page += 1) {
+      items.push(page);
+    }
+  }
+
+  for (let page = leftBoundary; page <= rightBoundary; page += 1) {
+    items.push(page);
+  }
+
+  if (rightBoundary < pageCount - 1) {
+    items.push("ellipsis-right");
+  } else {
+    for (let page = rightBoundary + 1; page < pageCount; page += 1) {
+      items.push(page);
+    }
+  }
+
+  items.push(pageCount);
+
+  return items;
+}
+
+function moveFocus(event: KeyboardEvent<HTMLUListElement>, focusableElements: HTMLElement[]) {
+  const activeElement =
+    event.currentTarget.ownerDocument.activeElement instanceof HTMLElement
+      ? event.currentTarget.ownerDocument.activeElement
+      : event.target instanceof HTMLElement
+        ? event.target
+        : null;
+  const currentIndex = activeElement ? focusableElements.indexOf(activeElement) : -1;
+
+  if (focusableElements.length === 0) return;
+
+  if (event.key === "Home") {
+    focusableElements[0]?.focus();
+    return;
+  }
+
+  if (event.key === "End") {
+    focusableElements[focusableElements.length - 1]?.focus();
+    return;
+  }
+
+  if (currentIndex === -1) {
+    focusableElements[0]?.focus();
+    return;
+  }
+
+  const direction = event.key === "ArrowLeft" || event.key === "ArrowUp" ? -1 : 1;
+  const nextIndex = clamp(currentIndex + direction, 0, focusableElements.length - 1);
+  focusableElements[nextIndex]?.focus();
+}
+
+const PaginationButton = forwardRef<HTMLButtonElement, PaginationButtonProps>(function PaginationButton(
+  { children, className, disabled, isCurrent, type = "button", ...props },
+  ref
+) {
+  return (
+    <button
+      {...props}
+      aria-current={isCurrent ? "page" : undefined}
+      className={cx(
+        "ui-pagination-button",
+        isCurrent && "is-current",
+        disabled && "is-disabled",
+        className
+      )}
+      data-pagination-focusable="true"
+      data-state={isCurrent ? "current" : "inactive"}
+      disabled={disabled}
+      ref={ref}
+      type={type}
+    >
+      {children}
+    </button>
+  );
+});
+
+export const Pagination = forwardRef<HTMLElement, PaginationProps>(function Pagination(
+  {
+    "aria-label": ariaLabel = "分页导航",
+    className,
+    onChange,
+    page,
+    pageSize,
+    siblings = 1,
+    total,
+    ...props
+  },
+  ref
+) {
+  const pageCount = getPageCount(total, pageSize);
+  const currentPage = clamp(page, 1, pageCount);
+  const items = buildPaginationItems(pageCount, currentPage, siblings);
+
+  function handlePageChange(nextPage: number) {
+    const resolvedPage = clamp(nextPage, 1, pageCount);
+    if (resolvedPage === currentPage) return;
+    onChange?.(resolvedPage);
+  }
+
+  function handleKeyDown(event: KeyboardEvent<HTMLUListElement>) {
+    if (!["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "Home", "End"].includes(event.key)) return;
+
+    event.preventDefault();
+
+    const focusableElements = Array.from(
+      event.currentTarget.querySelectorAll<HTMLElement>("[data-pagination-focusable=\"true\"]")
+    ).filter((element) => {
+      return !(element instanceof HTMLButtonElement && element.disabled);
+    });
+
+    moveFocus(event, focusableElements);
+  }
+
+  return (
+    <nav
+      {...props}
+      aria-label={ariaLabel}
+      className={cx("ui-pagination", className)}
+      data-state={pageCount <= 1 ? "single" : "ready"}
+      ref={ref}
+    >
+      <ul className="ui-pagination-list" onKeyDown={handleKeyDown}>
+        <li className="ui-pagination-item">
+          <PaginationButton
+            aria-label="上一页"
+            disabled={currentPage <= 1}
+            onClick={() => handlePageChange(currentPage - 1)}
+          >
+            上一页
+          </PaginationButton>
+        </li>
+
+        {items.map((item, index) => {
+          if (typeof item !== "number") {
+            return (
+              <li aria-hidden="true" className="ui-pagination-item" key={`${item}-${index}`}>
+                <span className="ui-pagination-ellipsis" data-state="ellipsis">
+                  …
+                </span>
+              </li>
+            );
+          }
+
+          return (
+            <li className="ui-pagination-item" key={item}>
+              <PaginationButton
+                aria-label={`第 ${item} 页`}
+                isCurrent={item === currentPage}
+                onClick={() => handlePageChange(item)}
+              >
+                {item}
+              </PaginationButton>
+            </li>
+          );
+        })}
+
+        <li className="ui-pagination-item">
+          <PaginationButton
+            aria-label="下一页"
+            disabled={currentPage >= pageCount}
+            onClick={() => handlePageChange(currentPage + 1)}
+          >
+            下一页
+          </PaginationButton>
+        </li>
+      </ul>
+    </nav>
+  );
+});
diff --git a/apps/web/src/shared/pagination/README.md b/apps/web/src/shared/pagination/README.md
new file mode 100644
index 0000000..51fa945
--- /dev/null
+++ b/apps/web/src/shared/pagination/README.md
@@ -0,0 +1,26 @@
+# 🔢 shared/pagination
+
+共享分页导航原语层。
+
+## ✅ 放什么
+- `Pagination`
+- `total / pageSize / page / onChange / siblings` 的受控分页语义
+- 上一页 / 下一页 / 当前页的 `aria-current`、禁用态与键盘焦点移动
+- 折叠页码的省略号输出
+
+## 🚫 不放什么
+- 数据请求和 URL 同步
+- page size selector
+- 无限滚动或游标分页协议
+
+## 状态约定
+- `page`：受控当前页，从 `1` 开始
+- `onChange(nextPage)`：仅在页码真正变化时触发
+- `siblings`：控制当前页两侧保留的页码数量
+- 当前页按钮输出 `aria-current="page"` 与 `data-state="current"`
+- 根节点在单页场景输出 `data-state="single"`，多页输出 `ready`
+
+## 可访问性
+- 根节点渲染 `<nav aria-label="分页导航">`
+- 页码与上一页 / 下一页使用原生 `<button>`
+- 支持 `ArrowLeft` / `ArrowRight` / `Home` / `End` 焦点移动
diff --git a/apps/web/src/shared/pagination/index.ts b/apps/web/src/shared/pagination/index.ts
new file mode 100644
index 0000000..5d94f67
--- /dev/null
+++ b/apps/web/src/shared/pagination/index.ts
@@ -0,0 +1 @@
+export { Pagination } from "./PaginationPrimitives";
diff --git a/apps/web/src/shared/pagination/pagination.css b/apps/web/src/shared/pagination/pagination.css
new file mode 100644
index 0000000..b538e7d
--- /dev/null
+++ b/apps/web/src/shared/pagination/pagination.css
@@ -0,0 +1,45 @@
+.ui-pagination {
+  display: block;
+}
+
+.ui-pagination-list {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.ui-pagination-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 36px;
+  min-height: 36px;
+  padding: 0 12px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-pill);
+  background: var(--surface-elevated, transparent);
+  color: var(--text-muted);
+}
+
+.ui-pagination-button[data-state="current"] {
+  color: var(--bg-elevated);
+  background: var(--surface-contrast);
+}
+
+.ui-pagination-button:disabled,
+.ui-pagination-button.is-disabled {
+  opacity: 0.56;
+  cursor: not-allowed;
+}
+
+.ui-pagination-ellipsis {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 24px;
+  color: var(--text-muted);
+}
diff --git a/apps/web/src/shared/popover/PopoverPrimitives.tsx b/apps/web/src/shared/popover/PopoverPrimitives.tsx
new file mode 100644
index 0000000..73b5b3c
--- /dev/null
+++ b/apps/web/src/shared/popover/PopoverPrimitives.tsx
@@ -0,0 +1,220 @@
+import {
+  createContext,
+  forwardRef,
+  type ButtonHTMLAttributes,
+  type HTMLAttributes,
+  type MutableRefObject,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useId,
+  useRef,
+  useState
+} from "react";
+import { createPortal } from "react-dom";
+
+import { assignRef, focusableSelector, useFloatingPosition, usePortalRoot } from "../overlay/layer-utils";
+
+type PopoverProps = {
+  children: ReactNode;
+  defaultOpen?: boolean;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+};
+
+type PopoverTriggerProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type">;
+
+type PopoverContentProps = HTMLAttributes<HTMLDivElement> & {
+  align?: "start" | "center" | "end";
+  side?: "top" | "bottom";
+};
+
+type PopoverContextValue = {
+  contentId: string;
+  contentRef: MutableRefObject<HTMLDivElement | null>;
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  triggerRef: MutableRefObject<HTMLButtonElement | null>;
+};
+
+const PopoverContext = createContext<PopoverContextValue | null>(null);
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+function usePopoverContext() {
+  const context = useContext(PopoverContext);
+
+  if (!context) {
+    throw new Error("Popover primitives must be used within <Popover>.");
+  }
+
+  return context;
+}
+
+function useControllableOpenState({
+  defaultOpen = false,
+  onOpenChange,
+  open
+}: Pick<PopoverProps, "defaultOpen" | "onOpenChange" | "open">) {
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const isControlled = open !== undefined;
+  const currentOpen = isControlled ? open : internalOpen;
+
+  function setOpen(nextOpen: boolean) {
+    if (!isControlled) {
+      setInternalOpen(nextOpen);
+    }
+
+    onOpenChange?.(nextOpen);
+  }
+
+  return [currentOpen, setOpen] as const;
+}
+
+export function Popover({ children, defaultOpen, onOpenChange, open }: PopoverProps) {
+  const contentId = useId();
+  const contentRef = useRef<HTMLDivElement | null>(null);
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const [isOpen, setOpen] = useControllableOpenState({ defaultOpen, onOpenChange, open });
+
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+
+    function handlePointerDown(event: MouseEvent) {
+      const target = event.target;
+      if (!(target instanceof Node)) {
+        return;
+      }
+
+      if (triggerRef.current?.contains(target) || contentRef.current?.contains(target)) {
+        return;
+      }
+
+      setOpen(false);
+      triggerRef.current?.focus();
+    }
+
+    document.addEventListener("mousedown", handlePointerDown);
+
+    return () => {
+      document.removeEventListener("mousedown", handlePointerDown);
+    };
+  }, [isOpen, setOpen]);
+
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+
+    const content = contentRef.current;
+    if (!content) {
+      return;
+    }
+
+    const firstFocusable = content.querySelector<HTMLElement>(focusableSelector);
+    (firstFocusable ?? content).focus();
+  }, [isOpen]);
+
+  return (
+    <PopoverContext.Provider
+      value={{
+        contentId,
+        contentRef,
+        open: isOpen,
+        setOpen,
+        triggerRef
+      }}
+    >
+      <div className="ui-popover-root" data-state={isOpen ? "open" : "closed"}>
+        {children}
+      </div>
+    </PopoverContext.Provider>
+  );
+}
+
+export const PopoverTrigger = forwardRef<HTMLButtonElement, PopoverTriggerProps>(function PopoverTrigger(
+  { className, onClick, ...props },
+  ref
+) {
+  const { contentId, open, setOpen, triggerRef } = usePopoverContext();
+
+  return (
+    <button
+      {...props}
+      aria-controls={contentId}
+      aria-expanded={open}
+      aria-haspopup="dialog"
+      className={cx("ui-popover-trigger", className)}
+      data-state={open ? "open" : "closed"}
+      onClick={(event) => {
+        onClick?.(event);
+        if (event.defaultPrevented) return;
+        setOpen(!open);
+      }}
+      ref={(node) => {
+        triggerRef.current = node;
+        assignRef(ref, node);
+      }}
+      type="button"
+    />
+  );
+});
+
+export const PopoverContent = forwardRef<HTMLDivElement, PopoverContentProps>(function PopoverContent(
+  { align = "start", children, className, onKeyDown, side = "bottom", ...props },
+  ref
+) {
+  const { contentId, contentRef, open, setOpen, triggerRef } = usePopoverContext();
+  const portalRoot = usePortalRoot();
+  const { resolvedSide, style } = useFloatingPosition({
+    align,
+    anchorRef: triggerRef as MutableRefObject<HTMLElement | null>,
+    contentRef: contentRef as MutableRefObject<HTMLElement | null>,
+    matchAnchorWidth: true,
+    open,
+    preferredSide: side
+  });
+
+  if (!open || !portalRoot) {
+    return null;
+  }
+
+  return createPortal(
+    <div
+      {...props}
+      aria-modal="false"
+      className={cx(
+        "ui-popover-content",
+        `ui-popover-side-${resolvedSide}`,
+        `ui-popover-align-${align}`,
+        className
+      )}
+      data-align={align}
+      data-side={resolvedSide}
+      data-state="open"
+      id={contentId}
+      onKeyDown={(event) => {
+        onKeyDown?.(event);
+        if (event.defaultPrevented) return;
+        if (event.key === "Escape") {
+          setOpen(false);
+          triggerRef.current?.focus();
+        }
+      }}
+      ref={(node) => {
+        contentRef.current = node;
+        assignRef(ref, node);
+      }}
+      role="dialog"
+      style={style}
+      tabIndex={-1}
+    >
+      {children}
+    </div>,
+    portalRoot
+  );
+});
diff --git a/apps/web/src/shared/popover/README.md b/apps/web/src/shared/popover/README.md
new file mode 100644
index 0000000..8c0f9b2
--- /dev/null
+++ b/apps/web/src/shared/popover/README.md
@@ -0,0 +1,21 @@
+# 🗂 shared/popover
+
+共享 Popover 原语层。
+
+## ✅ 放什么
+- `Popover`
+- `PopoverTrigger`
+- `PopoverContent`
+- trigger 切换、outside click dismiss、`Esc` dismiss
+- `aria-expanded`、`aria-controls`、`role="dialog"` 等基础弹层语义
+
+## 🚫 不放什么
+- 命令面板、下拉菜单、选择器
+- 全局层级管理和复杂定位引擎
+- 业务专属表单状态
+
+## 使用约定
+- 适合承载轻量筛选、快捷动作、补充配置
+- 内容应保持短流程；长表单或强打断场景改用 `OverlayDialog` / `OverlayDrawer`
+- 关闭后默认把焦点还给 trigger，保证键盘回退路径稳定
+- 内容通过 shared layer portal 渲染，并带基础 side 回退与视口边界约束
diff --git a/apps/web/src/shared/popover/index.ts b/apps/web/src/shared/popover/index.ts
new file mode 100644
index 0000000..0df1394
--- /dev/null
+++ b/apps/web/src/shared/popover/index.ts
@@ -0,0 +1 @@
+export { Popover, PopoverContent, PopoverTrigger } from "./PopoverPrimitives";
diff --git a/apps/web/src/shared/popover/popover.css b/apps/web/src/shared/popover/popover.css
new file mode 100644
index 0000000..5d083c8
--- /dev/null
+++ b/apps/web/src/shared/popover/popover.css
@@ -0,0 +1,48 @@
+.ui-popover-root {
+  position: relative;
+  display: inline-flex;
+}
+
+.ui-popover-trigger {
+  appearance: none;
+  border: 0;
+  background: transparent;
+  padding: 0;
+  margin: 0;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
+
+.ui-popover-content {
+  position: absolute;
+  z-index: 35;
+  min-width: 14rem;
+  border: 1px solid var(--border-subtle, rgba(15, 23, 42, 0.12));
+  border-radius: var(--radius-lg, 16px);
+  background: var(--surface-panel, #ffffff);
+  color: var(--text-primary, #0f172a);
+  box-shadow: var(--shadow-lg, 0 20px 48px rgba(15, 23, 42, 0.18));
+  padding: 0.75rem;
+}
+
+.ui-popover-side-bottom {
+  top: calc(100% + 0.5rem);
+}
+
+.ui-popover-side-top {
+  bottom: calc(100% + 0.5rem);
+}
+
+.ui-popover-align-start {
+  left: 0;
+}
+
+.ui-popover-align-center {
+  left: 50%;
+  transform: translateX(-50%);
+}
+
+.ui-popover-align-end {
+  right: 0;
+}
diff --git a/apps/web/src/shared/progress/ProgressPrimitives.tsx b/apps/web/src/shared/progress/ProgressPrimitives.tsx
new file mode 100644
index 0000000..0d77cb7
--- /dev/null
+++ b/apps/web/src/shared/progress/ProgressPrimitives.tsx
@@ -0,0 +1,63 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from "react";
+
+type ProgressSize = "sm" | "md" | "lg";
+type ProgressVariant = "neutral" | "brand" | "success" | "warning" | "danger";
+
+type ProgressProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+  formatValue?: (percentage: number, value: number, max: number) => ReactNode;
+  indeterminate?: boolean;
+  max?: number;
+  showValueLabel?: boolean;
+  size?: ProgressSize;
+  value?: number;
+  variant?: ProgressVariant;
+};
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+function clamp(value: number, min: number, max: number) {
+  return Math.min(max, Math.max(min, value));
+}
+
+export const Progress = forwardRef<HTMLDivElement, ProgressProps>(function Progress(
+  {
+    className,
+    formatValue,
+    indeterminate = false,
+    max = 100,
+    showValueLabel = false,
+    size = "md",
+    value = 0,
+    variant = "brand",
+    ...props
+  },
+  ref
+) {
+  const boundedMax = Math.max(max, 1);
+  const boundedValue = clamp(value, 0, boundedMax);
+  const percentage = Math.round((boundedValue / boundedMax) * 100);
+  const valueLabel = formatValue?.(percentage, boundedValue, boundedMax) ?? `${percentage}%`;
+
+  return (
+    <div
+      {...props}
+      aria-valuemax={indeterminate ? undefined : boundedMax}
+      aria-valuemin={indeterminate ? undefined : 0}
+      aria-valuenow={indeterminate ? undefined : boundedValue}
+      className={cx("ui-progress", `ui-progress-${variant}`, `ui-progress-${size}`, className)}
+      data-state={indeterminate ? "indeterminate" : "determinate"}
+      ref={ref}
+      role="progressbar"
+    >
+      <span className="ui-progress-track">
+        <span
+          className="ui-progress-indicator"
+          style={indeterminate ? undefined : { width: `${percentage}%` }}
+        />
+      </span>
+      {showValueLabel ? <span className="ui-progress-label">{valueLabel}</span> : null}
+    </div>
+  );
+});
diff --git a/apps/web/src/shared/progress/README.md b/apps/web/src/shared/progress/README.md
new file mode 100644
index 0000000..8616fe1
--- /dev/null
+++ b/apps/web/src/shared/progress/README.md
@@ -0,0 +1,18 @@
+# 📈 shared/progress
+
+共享进度原语层。
+
+## ✅ 放什么
+- `Progress`
+- 线性进度条尺寸、语义色和确定 / 不确定状态
+- `aria-valuenow` / `aria-valuemax` / `role="progressbar"` 的统一语义
+
+## 🚫 不放什么
+- 任务编排逻辑
+- 上传 / 同步业务文案拼接
+- 环形进度或图表级动画
+
+## 状态约定
+- `data-state="determinate" | "indeterminate"`
+- `variant`: `neutral` / `brand` / `success` / `warning` / `danger`
+- `size`: `sm` / `md` / `lg`
diff --git a/apps/web/src/shared/progress/index.ts b/apps/web/src/shared/progress/index.ts
new file mode 100644
index 0000000..7bd001d
--- /dev/null
+++ b/apps/web/src/shared/progress/index.ts
@@ -0,0 +1 @@
+export { Progress } from "./ProgressPrimitives";
diff --git a/apps/web/src/shared/progress/progress.css b/apps/web/src/shared/progress/progress.css
new file mode 100644
index 0000000..59bf719
--- /dev/null
+++ b/apps/web/src/shared/progress/progress.css
@@ -0,0 +1,77 @@
+.ui-progress {
+  display: grid;
+  gap: 8px;
+}
+
+.ui-progress-track {
+  position: relative;
+  overflow: hidden;
+  display: block;
+  width: 100%;
+  height: 10px;
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--text-soft) 18%, transparent);
+}
+
+.ui-progress-sm .ui-progress-track {
+  height: 6px;
+}
+
+.ui-progress-lg .ui-progress-track {
+  height: 12px;
+}
+
+.ui-progress-indicator {
+  display: block;
+  height: 100%;
+  border-radius: inherit;
+  background: var(--accent);
+  transition: width var(--transition-fast);
+}
+
+.ui-progress[data-state="indeterminate"] .ui-progress-indicator {
+  width: 38%;
+  animation: ui-progress-indeterminate 1s ease-in-out infinite;
+}
+
+.ui-progress-neutral .ui-progress-indicator {
+  background: var(--text-muted);
+}
+
+.ui-progress-brand .ui-progress-indicator {
+  background: var(--accent);
+}
+
+.ui-progress-success .ui-progress-indicator {
+  background: #20c997;
+}
+
+.ui-progress-warning .ui-progress-indicator {
+  background: #ffb84d;
+}
+
+.ui-progress-danger .ui-progress-indicator {
+  background: #ef4444;
+}
+
+.ui-progress-label {
+  font-size: 0.82rem;
+  color: var(--text-muted);
+}
+
+@keyframes ui-progress-indeterminate {
+  0% {
+    transform: translateX(-110%);
+  }
+
+  100% {
+    transform: translateX(300%);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ui-progress-indicator {
+    transition: none;
+    animation: none;
+  }
+}
diff --git a/apps/web/src/shared/scroll-area/README.md b/apps/web/src/shared/scroll-area/README.md
new file mode 100644
index 0000000..2eb0044
--- /dev/null
+++ b/apps/web/src/shared/scroll-area/README.md
@@ -0,0 +1,20 @@
+# ↕️ shared/scroll-area
+
+共享 Scroll Area 原语层。
+
+## ✅ 放什么
+- `ScrollArea`
+- `ScrollAreaViewport`
+- `ScrollAreaScrollbar`
+- `ScrollAreaThumb`
+- 统一滚动容器、viewport、滚动条槽位与方向状态
+
+## 🚫 不放什么
+- 虚拟列表
+- 惰性加载或无限滚动状态机
+- 业务专属列表项布局
+
+## 使用约定
+- `ScrollArea` 负责区域语义和方向
+- `ScrollAreaViewport` 承载真实内容
+- `ScrollAreaScrollbar` / `ScrollAreaThumb` 负责样式槽位，不内置复杂拖拽逻辑
diff --git a/apps/web/src/shared/scroll-area/ScrollAreaPrimitives.tsx b/apps/web/src/shared/scroll-area/ScrollAreaPrimitives.tsx
new file mode 100644
index 0000000..bb12cf9
--- /dev/null
+++ b/apps/web/src/shared/scroll-area/ScrollAreaPrimitives.tsx
@@ -0,0 +1,70 @@
+import {
+  forwardRef,
+  type HTMLAttributes,
+  type ReactNode
+} from "react";
+
+type ScrollAreaOrientation = "horizontal" | "vertical";
+
+type ScrollAreaProps = HTMLAttributes<HTMLDivElement> & {
+  children: ReactNode;
+  orientation?: ScrollAreaOrientation;
+};
+
+type ScrollAreaViewportProps = HTMLAttributes<HTMLDivElement>;
+
+type ScrollAreaScrollbarProps = HTMLAttributes<HTMLDivElement> & {
+  orientation?: ScrollAreaOrientation;
+};
+
+type ScrollAreaThumbProps = HTMLAttributes<HTMLDivElement>;
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+export const ScrollArea = forwardRef<HTMLDivElement, ScrollAreaProps>(function ScrollArea(
+  { children, className, orientation = "vertical", role = "region", ...props },
+  ref
+) {
+  return (
+    <div
+      {...props}
+      className={cx("ui-scroll-area", className)}
+      data-orientation={orientation}
+      ref={ref}
+      role={role}
+    >
+      {children}
+    </div>
+  );
+});
+
+export const ScrollAreaViewport = forwardRef<HTMLDivElement, ScrollAreaViewportProps>(function ScrollAreaViewport(
+  { className, ...props },
+  ref
+) {
+  return <div {...props} className={cx("ui-scroll-area-viewport", className)} ref={ref} />;
+});
+
+export const ScrollAreaScrollbar = forwardRef<HTMLDivElement, ScrollAreaScrollbarProps>(function ScrollAreaScrollbar(
+  { className, orientation = "vertical", ...props },
+  ref
+) {
+  return (
+    <div
+      {...props}
+      className={cx("ui-scroll-area-scrollbar", `ui-scroll-area-scrollbar-${orientation}`, className)}
+      data-orientation={orientation}
+      data-state="visible"
+      ref={ref}
+    />
+  );
+});
+
+export const ScrollAreaThumb = forwardRef<HTMLDivElement, ScrollAreaThumbProps>(function ScrollAreaThumb(
+  { className, ...props },
+  ref
+) {
+  return <div {...props} className={cx("ui-scroll-area-thumb", className)} data-state="visible" ref={ref} />;
+});
diff --git a/apps/web/src/shared/scroll-area/index.ts b/apps/web/src/shared/scroll-area/index.ts
new file mode 100644
index 0000000..9c3c000
--- /dev/null
+++ b/apps/web/src/shared/scroll-area/index.ts
@@ -0,0 +1,6 @@
+export {
+  ScrollArea,
+  ScrollAreaScrollbar,
+  ScrollAreaThumb,
+  ScrollAreaViewport
+} from "./ScrollAreaPrimitives";
diff --git a/apps/web/src/shared/scroll-area/scroll-area.css b/apps/web/src/shared/scroll-area/scroll-area.css
new file mode 100644
index 0000000..a84b11b
--- /dev/null
+++ b/apps/web/src/shared/scroll-area/scroll-area.css
@@ -0,0 +1,39 @@
+.ui-scroll-area {
+  position: relative;
+  overflow: hidden;
+}
+
+.ui-scroll-area-viewport {
+  width: 100%;
+  height: 100%;
+  overflow: auto;
+  scrollbar-width: none;
+}
+
+.ui-scroll-area-viewport::-webkit-scrollbar {
+  display: none;
+}
+
+.ui-scroll-area-scrollbar {
+  position: absolute;
+  inset-block: 0;
+  inset-inline-end: 0;
+  width: 0.5rem;
+  padding: 0.125rem;
+}
+
+.ui-scroll-area-scrollbar-horizontal {
+  inset-block-start: auto;
+  inset-inline: 0;
+  inset-block-end: 0;
+  width: auto;
+  height: 0.5rem;
+}
+
+.ui-scroll-area-thumb {
+  width: 100%;
+  height: 100%;
+  min-height: 2rem;
+  border-radius: 999px;
+  background: var(--border-strong, rgba(100, 116, 139, 0.42));
+}
diff --git a/apps/web/src/shared/skeleton/README.md b/apps/web/src/shared/skeleton/README.md
new file mode 100644
index 0000000..6fab43e
--- /dev/null
+++ b/apps/web/src/shared/skeleton/README.md
@@ -0,0 +1,19 @@
+# 🦴 shared/skeleton
+
+共享骨架屏原语层。
+
+## ✅ 放什么
+- `Skeleton`
+- `rect / text / circle` 形状
+- 自定义尺寸、圆角和可选 shimmer 动画
+- 默认装饰语义，必要时可宣布“内容加载中”
+
+## 🚫 不放什么
+- 页面级骨架布局编排
+- 实际数据加载策略
+- 业务专属占位内容文案
+
+## 使用约定
+- 默认静态，占位块只负责稳定布局
+- 需要动效时显式传 `animated`
+- 需要读屏器播报时传 `announce`
diff --git a/apps/web/src/shared/skeleton/SkeletonPrimitives.tsx b/apps/web/src/shared/skeleton/SkeletonPrimitives.tsx
new file mode 100644
index 0000000..782cd44
--- /dev/null
+++ b/apps/web/src/shared/skeleton/SkeletonPrimitives.tsx
@@ -0,0 +1,70 @@
+import { forwardRef, type CSSProperties, type HTMLAttributes } from "react";
+
+type SkeletonShape = "rect" | "text" | "circle";
+type SkeletonRounded = boolean | "sm" | "md" | "lg" | "full";
+
+type SkeletonProps = HTMLAttributes<HTMLDivElement> & {
+  animated?: boolean;
+  announce?: boolean;
+  height?: CSSProperties["height"];
+  label?: string;
+  rounded?: SkeletonRounded;
+  shape?: SkeletonShape;
+  width?: CSSProperties["width"];
+};
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+function roundedClassName(rounded: SkeletonRounded | undefined) {
+  if (!rounded) return undefined;
+  if (rounded === true) return "ui-skeleton-rounded-md";
+  return `ui-skeleton-rounded-${rounded}`;
+}
+
+function mergeStyle(width: SkeletonProps["width"], height: SkeletonProps["height"], style?: CSSProperties) {
+  const nextStyle: CSSProperties = {};
+
+  if (width !== undefined) nextStyle.width = width;
+  if (height !== undefined) nextStyle.height = height;
+
+  return Object.keys(nextStyle).length ? { ...style, ...nextStyle } : style;
+}
+
+export const Skeleton = forwardRef<HTMLDivElement, SkeletonProps>(function Skeleton(
+  {
+    animated = false,
+    announce = false,
+    className,
+    height,
+    label = "内容加载中",
+    rounded,
+    shape = "rect",
+    style,
+    width,
+    ...props
+  },
+  ref
+) {
+  return (
+    <div
+      {...props}
+      aria-hidden={!announce ? true : undefined}
+      aria-label={announce ? label : undefined}
+      aria-live={announce ? "polite" : undefined}
+      className={cx(
+        "ui-skeleton",
+        `ui-skeleton-${shape}`,
+        animated && "ui-skeleton-animated",
+        roundedClassName(rounded),
+        className
+      )}
+      data-shape={shape}
+      data-state={animated ? "loading" : "idle"}
+      ref={ref}
+      role={announce ? "status" : undefined}
+      style={mergeStyle(width, height, style)}
+    />
+  );
+});
diff --git a/apps/web/src/shared/skeleton/index.ts b/apps/web/src/shared/skeleton/index.ts
new file mode 100644
index 0000000..358493f
--- /dev/null
+++ b/apps/web/src/shared/skeleton/index.ts
@@ -0,0 +1 @@
+export { Skeleton } from "./SkeletonPrimitives";
diff --git a/apps/web/src/shared/skeleton/skeleton.css b/apps/web/src/shared/skeleton/skeleton.css
new file mode 100644
index 0000000..865d220
--- /dev/null
+++ b/apps/web/src/shared/skeleton/skeleton.css
@@ -0,0 +1,72 @@
+.ui-skeleton {
+  position: relative;
+  overflow: hidden;
+  display: block;
+  width: 100%;
+  min-height: 1rem;
+  border-radius: var(--radius-sm);
+  background:
+    linear-gradient(
+      135deg,
+      color-mix(in srgb, var(--surface-muted) 92%, transparent),
+      color-mix(in srgb, var(--surface-strong) 68%, transparent)
+    );
+}
+
+.ui-skeleton-rect {
+  min-height: 2.75rem;
+}
+
+.ui-skeleton-text {
+  min-height: 0.9rem;
+  border-radius: var(--radius-full);
+}
+
+.ui-skeleton-circle {
+  aspect-ratio: 1;
+  width: 2.5rem;
+  min-height: auto;
+  border-radius: 999px;
+}
+
+.ui-skeleton-rounded-sm {
+  border-radius: var(--radius-sm);
+}
+
+.ui-skeleton-rounded-md {
+  border-radius: var(--radius-md);
+}
+
+.ui-skeleton-rounded-lg {
+  border-radius: var(--radius-lg);
+}
+
+.ui-skeleton-rounded-full {
+  border-radius: 999px;
+}
+
+.ui-skeleton-animated::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(
+    90deg,
+    transparent,
+    color-mix(in srgb, white 38%, transparent),
+    transparent
+  );
+  transform: translateX(-100%);
+  animation: ui-skeleton-shimmer 1.4s var(--ease-standard) infinite;
+}
+
+@keyframes ui-skeleton-shimmer {
+  to {
+    transform: translateX(100%);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ui-skeleton-animated::after {
+    animation: none;
+  }
+}
diff --git a/apps/web/src/shared/spinner/README.md b/apps/web/src/shared/spinner/README.md
new file mode 100644
index 0000000..b19e63a
--- /dev/null
+++ b/apps/web/src/shared/spinner/README.md
@@ -0,0 +1,19 @@
+# 🌀 shared/spinner
+
+共享加载指示器原语层。
+
+## ✅ 放什么
+- `Spinner`
+- 统一尺寸、tone、默认中文加载文案
+- decorative / status 两种语义模式
+- reduced-motion 下的动画降级
+
+## 🚫 不放什么
+- 页面级 loading shell
+- 复杂骨架屏布局
+- 业务专属的“重试中 / 同步中 / 部署中”状态机
+
+## 使用约定
+- 默认 `Spinner` 带 `role="status"`，适合单点加载操作
+- 仅作为按钮/图标内视觉反馈时传 `decorative`
+- 需要显式展示文案时传 `showLabel`
diff --git a/apps/web/src/shared/spinner/SpinnerPrimitives.tsx b/apps/web/src/shared/spinner/SpinnerPrimitives.tsx
new file mode 100644
index 0000000..d76c19f
--- /dev/null
+++ b/apps/web/src/shared/spinner/SpinnerPrimitives.tsx
@@ -0,0 +1,45 @@
+import { forwardRef, type HTMLAttributes } from "react";
+
+type SpinnerSize = "xs" | "sm" | "md" | "lg";
+type SpinnerTone = "default" | "muted" | "accent" | "success" | "warning" | "danger";
+
+type SpinnerProps = HTMLAttributes<HTMLSpanElement> & {
+  decorative?: boolean;
+  label?: string;
+  showLabel?: boolean;
+  size?: SpinnerSize;
+  tone?: SpinnerTone;
+};
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+export const Spinner = forwardRef<HTMLSpanElement, SpinnerProps>(function Spinner(
+  {
+    className,
+    decorative = false,
+    label = "加载中",
+    showLabel = false,
+    size = "md",
+    tone = "default",
+    ...props
+  },
+  ref
+) {
+  return (
+    <span
+      {...props}
+      aria-hidden={decorative ? true : undefined}
+      aria-label={!decorative ? label : undefined}
+      aria-live={!decorative ? "polite" : undefined}
+      className={cx("ui-spinner", `ui-spinner-${size}`, `ui-tone-${tone}`, showLabel && "ui-spinner-with-label", className)}
+      data-state="indeterminate"
+      ref={ref}
+      role={!decorative ? "status" : undefined}
+    >
+      <span aria-hidden="true" className="ui-spinner-indicator" />
+      {showLabel ? <span className="ui-spinner-label">{label}</span> : null}
+    </span>
+  );
+});
diff --git a/apps/web/src/shared/spinner/index.ts b/apps/web/src/shared/spinner/index.ts
new file mode 100644
index 0000000..f80e080
--- /dev/null
+++ b/apps/web/src/shared/spinner/index.ts
@@ -0,0 +1 @@
+export { Spinner } from "./SpinnerPrimitives";
diff --git a/apps/web/src/shared/spinner/spinner.css b/apps/web/src/shared/spinner/spinner.css
new file mode 100644
index 0000000..cc08c6c
--- /dev/null
+++ b/apps/web/src/shared/spinner/spinner.css
@@ -0,0 +1,74 @@
+.ui-spinner {
+  --spinner-size: 16px;
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  color: var(--text);
+}
+
+.ui-spinner-xs {
+  --spinner-size: 12px;
+}
+
+.ui-spinner-sm {
+  --spinner-size: 14px;
+}
+
+.ui-spinner-md {
+  --spinner-size: 16px;
+}
+
+.ui-spinner-lg {
+  --spinner-size: 20px;
+}
+
+.ui-spinner-indicator {
+  width: var(--spinner-size);
+  height: var(--spinner-size);
+  border-radius: 999px;
+  border: 2px solid currentColor;
+  border-right-color: transparent;
+  opacity: 0.9;
+  animation: ui-spinner-rotate 720ms linear infinite;
+}
+
+.ui-spinner-label {
+  font-size: var(--font-body-md);
+  line-height: var(--line-body);
+}
+
+.ui-spinner.ui-tone-default {
+  color: var(--text);
+}
+
+.ui-spinner.ui-tone-muted {
+  color: var(--text-muted);
+}
+
+.ui-spinner.ui-tone-accent {
+  color: var(--brand-500);
+}
+
+.ui-spinner.ui-tone-success {
+  color: var(--success-600);
+}
+
+.ui-spinner.ui-tone-warning {
+  color: var(--warning-600);
+}
+
+.ui-spinner.ui-tone-danger {
+  color: var(--danger-600);
+}
+
+@keyframes ui-spinner-rotate {
+  to {
+    transform: rotate(1turn);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ui-spinner-indicator {
+    animation: none;
+  }
+}
diff --git a/apps/web/src/shared/steps/README.md b/apps/web/src/shared/steps/README.md
new file mode 100644
index 0000000..5dc70a7
--- /dev/null
+++ b/apps/web/src/shared/steps/README.md
@@ -0,0 +1,28 @@
+# 🪜 shared/steps
+
+共享步骤导航原语层。
+
+## ✅ 放什么
+- `Steps`
+- `StepsList`
+- `StepItem`
+- 当前步、已完成、未开始三态映射
+- 可选的 `onStepChange(step)` 受控切换语义
+- 水平 / 垂直方向与键盘焦点移动
+
+## 🚫 不放什么
+- 表单校验结果聚合
+- 业务流程编排
+- 页面级进度存储或路由同步
+
+## 状态约定
+- `currentStep`: 受控当前步骤，从 `1` 开始
+- `onStepChange(step)`: 点击步骤时回调，用于外层受控切换
+- `StepItem` 根据 `step` 与 `currentStep` 自动计算 `complete / current / upcoming`
+- 当前步按钮输出 `aria-current="step"` 与 `data-state="current"`
+- 根节点根据是否可切换输出 `data-state="interactive" | "static"`
+
+## 可访问性
+- 根节点渲染 `<nav aria-label>`
+- 列表使用 `<ol>` 保持流程顺序
+- 步骤按钮支持 `Arrow*`、`Home`、`End` 焦点移动
diff --git a/apps/web/src/shared/steps/StepsPrimitives.tsx b/apps/web/src/shared/steps/StepsPrimitives.tsx
new file mode 100644
index 0000000..57f10be
--- /dev/null
+++ b/apps/web/src/shared/steps/StepsPrimitives.tsx
@@ -0,0 +1,191 @@
+import {
+  createContext,
+  forwardRef,
+  type ButtonHTMLAttributes,
+  type HTMLAttributes,
+  type KeyboardEvent,
+  type ReactNode,
+  useContext,
+  useId
+} from "react";
+
+type StepsOrientation = "horizontal" | "vertical";
+
+type StepsProps = HTMLAttributes<HTMLElement> & {
+  currentStep: number;
+  onStepChange?: (step: number) => void;
+  orientation?: StepsOrientation;
+};
+
+type StepsContextValue = {
+  baseId: string;
+  currentStep: number;
+  onStepChange?: (step: number) => void;
+  orientation: StepsOrientation;
+};
+
+type StepItemProps = Omit<HTMLAttributes<HTMLLIElement>, "title"> & {
+  description?: ReactNode;
+  disabled?: boolean;
+  onSelect?: (step: number) => void;
+  step: number;
+  title: ReactNode;
+  triggerProps?: Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "type">;
+};
+
+const StepsContext = createContext<StepsContextValue | null>(null);
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+function clamp(value: number, minimum: number) {
+  return Math.max(value, minimum);
+}
+
+function useStepsContext(componentName: string) {
+  const context = useContext(StepsContext);
+
+  if (!context) {
+    throw new Error(`${componentName} must be used within Steps.`);
+  }
+
+  return context;
+}
+
+function resolveStepState(step: number, currentStep: number) {
+  if (step < currentStep) return "complete";
+  if (step === currentStep) return "current";
+  return "upcoming";
+}
+
+export const Steps = forwardRef<HTMLElement, StepsProps>(function Steps(
+  { className, currentStep, onStepChange, orientation = "horizontal", ...props },
+  ref
+) {
+  const generatedId = useId();
+
+  return (
+    <StepsContext.Provider
+      value={{
+        baseId: generatedId,
+        currentStep: clamp(currentStep, 1),
+        onStepChange,
+        orientation
+      }}
+    >
+      <nav
+        {...props}
+        className={cx("ui-steps", className)}
+        data-orientation={orientation}
+        data-state={onStepChange ? "interactive" : "static"}
+        ref={ref}
+      />
+    </StepsContext.Provider>
+  );
+});
+
+export const StepsList = forwardRef<HTMLOListElement, HTMLAttributes<HTMLOListElement>>(function StepsList(
+  { className, onKeyDown, ...props },
+  ref
+) {
+  const context = useStepsContext("StepsList");
+
+  function handleKeyDown(event: KeyboardEvent<HTMLOListElement>) {
+    onKeyDown?.(event);
+    if (event.defaultPrevented) return;
+
+    if (!["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "Home", "End"].includes(event.key)) return;
+
+    event.preventDefault();
+
+    const buttons = Array.from(
+      event.currentTarget.querySelectorAll<HTMLButtonElement>("[data-step-trigger=\"true\"]")
+    ).filter((button) => !button.disabled);
+    const activeElement = event.target instanceof HTMLElement ? event.target : null;
+    const currentIndex = activeElement ? buttons.indexOf(activeElement as HTMLButtonElement) : -1;
+
+    if (buttons.length === 0) return;
+
+    if (event.key === "Home") {
+      buttons[0]?.focus();
+      return;
+    }
+
+    if (event.key === "End") {
+      buttons[buttons.length - 1]?.focus();
+      return;
+    }
+
+    const isHorizontal = context.orientation === "horizontal";
+    const isHorizontalKey = event.key === "ArrowLeft" || event.key === "ArrowRight";
+    const isVerticalKey = event.key === "ArrowUp" || event.key === "ArrowDown";
+
+    if ((isHorizontal && isVerticalKey) || (!isHorizontal && isHorizontalKey)) {
+      return;
+    }
+
+    const direction = event.key === "ArrowLeft" || event.key === "ArrowUp" ? -1 : 1;
+    const nextIndex = currentIndex === -1 ? 0 : (currentIndex + direction + buttons.length) % buttons.length;
+    buttons[nextIndex]?.focus();
+  }
+
+  return (
+    <ol
+      {...props}
+      className={cx("ui-steps-list", className)}
+      data-orientation={context.orientation}
+      onKeyDown={handleKeyDown}
+      ref={ref}
+    />
+  );
+});
+
+export const StepItem = forwardRef<HTMLLIElement, StepItemProps>(function StepItem(
+  { className, description, disabled, onSelect, step, title, triggerProps, ...props },
+  ref
+) {
+  const context = useStepsContext("StepItem");
+  const stepState = resolveStepState(step, context.currentStep);
+  const triggerId = `${context.baseId}-step-${step}`;
+
+  return (
+    <li
+      {...props}
+      className={cx("ui-step-item", className)}
+      data-state={stepState}
+      ref={ref}
+    >
+      <button
+        {...triggerProps}
+        aria-current={stepState === "current" ? "step" : undefined}
+        className={cx(
+          "ui-step-trigger",
+          stepState === "current" && "is-current",
+          disabled && "is-disabled",
+          triggerProps?.className
+        )}
+        data-state={stepState}
+        data-step-trigger="true"
+        disabled={disabled}
+        id={triggerId}
+        onClick={(event) => {
+          triggerProps?.onClick?.(event);
+          if (event.defaultPrevented || disabled) return;
+          onSelect?.(step);
+          context.onStepChange?.(step);
+        }}
+        tabIndex={stepState === "current" ? 0 : -1}
+        type="button"
+      >
+        <span aria-hidden="true" className="ui-step-indicator">
+          {step}
+        </span>
+        <span className="ui-step-copy">
+          <span className="ui-step-title">{title}</span>
+          {description ? <span className="ui-step-description">{description}</span> : null}
+        </span>
+      </button>
+    </li>
+  );
+});
diff --git a/apps/web/src/shared/steps/index.ts b/apps/web/src/shared/steps/index.ts
new file mode 100644
index 0000000..e586d52
--- /dev/null
+++ b/apps/web/src/shared/steps/index.ts
@@ -0,0 +1 @@
+export { StepItem, Steps, StepsList } from "./StepsPrimitives";
diff --git a/apps/web/src/shared/steps/steps.css b/apps/web/src/shared/steps/steps.css
new file mode 100644
index 0000000..104787b
--- /dev/null
+++ b/apps/web/src/shared/steps/steps.css
@@ -0,0 +1,66 @@
+.ui-steps {
+  display: block;
+}
+
+.ui-steps-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.ui-steps-list[data-orientation="vertical"] {
+  flex-direction: column;
+}
+
+.ui-step-item {
+  min-width: 0;
+}
+
+.ui-step-trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  min-height: 44px;
+  padding: 10px 14px;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  background: transparent;
+  color: var(--text-muted);
+}
+
+.ui-step-trigger[data-state="current"] {
+  color: var(--text);
+  border-color: color-mix(in srgb, var(--accent) 36%, var(--border));
+  background: color-mix(in srgb, var(--accent) 10%, transparent);
+}
+
+.ui-step-item[data-state="complete"] .ui-step-trigger {
+  color: var(--text);
+}
+
+.ui-step-indicator {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.08);
+}
+
+.ui-step-copy {
+  display: grid;
+  text-align: left;
+}
+
+.ui-step-title {
+  font-weight: 600;
+}
+
+.ui-step-description {
+  color: var(--text-subtle, var(--text-muted));
+  font-size: 0.875rem;
+}
diff --git a/apps/web/src/shared/styles/README.md b/apps/web/src/shared/styles/README.md
index 9e5ade9..4a8acd4 100644
--- a/apps/web/src/shared/styles/README.md
+++ b/apps/web/src/shared/styles/README.md
@@ -6,6 +6,9 @@
 - 全局样式入口
 - 主题变量
 - 通用布局 / 排版基线
+- `tokens.css` 里的 design token
+- `base.css` 里的 reset / 根布局 / 裸元素基线
+- `primitives.css` 里的原语样式导入汇总
 
 ## 🚫 不放什么
 - 页面专属大段内联样式说明
diff --git a/apps/web/src/shared/styles/base.css b/apps/web/src/shared/styles/base.css
new file mode 100644
index 0000000..fdadd3e
--- /dev/null
+++ b/apps/web/src/shared/styles/base.css
@@ -0,0 +1,60 @@
+/*
+ * Shared base layer.
+ *
+ * This file is intentionally limited to reset / root layout / bare element
+ * defaults so component-specific styling can stay in index.css or each
+ * primitive's own stylesheet.
+ */
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body,
+#root {
+  min-height: 100%;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  font-family: var(--font-sans);
+  background: var(--page-gradient);
+  color: var(--text);
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+button,
+input,
+select,
+textarea {
+  font: inherit;
+}
+
+button {
+  cursor: pointer;
+}
+
+h1,
+h2,
+h3,
+p {
+  margin: 0;
+}
+
+h1,
+h2,
+h3,
+strong {
+  letter-spacing: -0.04em;
+}
+
+label {
+  display: grid;
+  gap: 10px;
+}
diff --git a/apps/web/src/shared/styles/index.css b/apps/web/src/shared/styles/index.css
index d610628..ea306bb 100644
--- a/apps/web/src/shared/styles/index.css
+++ b/apps/web/src/shared/styles/index.css
@@ -1,4 +1,5 @@
 @import "./tokens.css";
+@import "./base.css";
 @import "./primitives.css";
 
 :root {
@@ -81,10 +82,6 @@
   --shadow-card: 0 18px 50px rgba(0, 0, 0, 0.42);
 }
 
-* {
-  box-sizing: border-box;
-}
-
 .workspace-scroll-area,
 .workspace-stack-compact,
 .message-body {
@@ -142,36 +139,6 @@
   );
 }
 
-html,
-body,
-#root {
-  min-height: 100%;
-}
-
-body {
-  margin: 0;
-  min-height: 100vh;
-  font-family: var(--font-sans);
-  background: var(--page-gradient);
-  color: var(--text);
-}
-
-a {
-  color: inherit;
-  text-decoration: none;
-}
-
-button,
-input,
-select,
-textarea {
-  font: inherit;
-}
-
-button {
-  cursor: pointer;
-}
-
 input,
 textarea {
   width: 100%;
@@ -190,25 +157,6 @@ textarea:focus {
   background: var(--surface-strong);
 }
 
-h1,
-h2,
-h3,
-p {
-  margin: 0;
-}
-
-h1,
-h2,
-h3,
-strong {
-  letter-spacing: -0.04em;
-}
-
-label {
-  display: grid;
-  gap: 10px;
-}
-
 .form-field {
   display: grid;
   gap: 10px;
@@ -622,7 +570,15 @@ label {
   border-color: var(--border);
 }
 
+.ui-button-subtle {
+  background: color-mix(in srgb, var(--surface-muted) 82%, var(--neutral-100) 18%);
+  color: var(--text-muted);
+  border-color: color-mix(in srgb, var(--border) 84%, transparent);
+  box-shadow: none;
+}
+
 .ui-button-secondary:hover,
+.ui-button-subtle:hover,
 .ui-button-icon:hover {
   border-color: color-mix(in srgb, var(--accent) 32%, var(--border));
   background: color-mix(in srgb, var(--surface-muted) 76%, var(--accent) 8%);
@@ -641,6 +597,10 @@ label {
   background: color-mix(in srgb, var(--accent) 8%, transparent);
 }
 
+.ui-button-subtle:hover {
+  color: var(--text);
+}
+
 .ui-button-text {
   padding-inline: 6px;
   background: transparent;
@@ -1112,7 +1072,7 @@ button:disabled {
 .ui-overlay-dialog {
   width: min(520px, 100%);
   max-height: min(720px, 100%);
-  border-radius: 8px;
+  border-radius: 32px;
   animation: ui-overlay-dialog-in 220ms cubic-bezier(0.25, 1, 0.5, 1) both;
 }
 
@@ -1723,6 +1683,7 @@ button:disabled {
 
 .workspace-brand strong,
 .workspace-user-trigger span,
+.workspace-pill-link,
 .workspace-pill-link span,
 .workspace-rail-link span,
 .workspace-rail-stat strong {
@@ -1756,6 +1717,18 @@ button:disabled {
   justify-self: stretch;
 }
 
+.workspace-secondary-tabs {
+  display: flex;
+  justify-content: center;
+  width: 100%;
+}
+
+.workspace-secondary-tabs-nav {
+  display: flex;
+  justify-content: center;
+  width: 100%;
+}
+
 .workspace-secondary-nav {
   justify-self: center;
   margin-inline: auto;
diff --git a/apps/web/src/shared/styles/primitives.css b/apps/web/src/shared/styles/primitives.css
index 498b290..df49faa 100644
--- a/apps/web/src/shared/styles/primitives.css
+++ b/apps/web/src/shared/styles/primitives.css
@@ -8,13 +8,64 @@
  * See docs/plans/2026-04-22-design-system-v1.md §7.
  *
  * === S2 atoms (typography / divider / icon / spinner / skeleton) ===
+ * @import "../typography/typography.css";
+ * @import "../divider/divider.css";
+ * @import "../icon/icon.css";
+ * @import "../spinner/spinner.css";
+ * @import "../skeleton/skeleton.css";
  *
  * === S3 cards & status (card / tag / badge / empty-state) ===
+ * @import "../card/card.css";
+ * @import "../tag/tag.css";
+ * @import "../badge/badge.css";
+ * @import "../empty-state/empty-state.css";
  *
  * === S4 navigation (breadcrumb / pagination / tabs / steps) ===
+ * @import "../breadcrumb/breadcrumb.css";
+ * @import "../pagination/pagination.css";
+ * @import "../tabs/tabs.css";
+ * @import "../steps/steps.css";
  *
  * === S5 forms & feedback (SearchInput / Checkbox / Radio / MultiSelect /
  *                          progress / alert / copy-button / kv-list / avatar) ===
+ * @import "../form/form.css";
+ * @import "../progress/progress.css";
+ * @import "../alert/alert.css";
+ * @import "../copy-button/copy-button.css";
+ * @import "../kv-list/kv-list.css";
+ * @import "../avatar/avatar.css";
  *
  * === S6 overlays (tooltip / popover / scroll-area) ===
+ * @import "../tooltip/tooltip.css";
+ * @import "../popover/popover.css";
+ * @import "../scroll-area/scroll-area.css";
  */
+@import "../typography/typography.css";
+@import "../divider/divider.css";
+@import "../icon/icon.css";
+@import "../spinner/spinner.css";
+@import "../skeleton/skeleton.css";
+@import "../page-layout/page-layout.css";
+@import "../filter-bar/filter-bar.css";
+@import "../metric-card/metric-card.css";
+
+@import "../card/card.css";
+@import "../tag/tag.css";
+@import "../badge/badge.css";
+@import "../empty-state/empty-state.css";
+
+@import "../breadcrumb/breadcrumb.css";
+@import "../pagination/pagination.css";
+@import "../tabs/tabs.css";
+@import "../steps/steps.css";
+
+@import "../form/form.css";
+@import "../progress/progress.css";
+@import "../alert/alert.css";
+@import "../copy-button/copy-button.css";
+@import "../kv-list/kv-list.css";
+@import "../avatar/avatar.css";
+
+@import "../tooltip/tooltip.css";
+@import "../popover/popover.css";
+@import "../scroll-area/scroll-area.css";
diff --git a/apps/web/src/shared/styles/tokens.css b/apps/web/src/shared/styles/tokens.css
index ec1bd14..c72a7fb 100644
--- a/apps/web/src/shared/styles/tokens.css
+++ b/apps/web/src/shared/styles/tokens.css
@@ -100,22 +100,26 @@
   --success-500: #22c55e;
   --success-100: #d1fadf;
   --success-600: #16a34a;
-  --success-bg: rgba(34, 197, 94, 0.14);
+  --success-soft: rgba(34, 197, 94, 0.14);
+  --success-bg: var(--success-soft);
 
   --warning-500: #f59e0b;
   --warning-100: #fef0c7;
   --warning-600: #d97706;
-  --warning-bg: rgba(245, 158, 11, 0.14);
+  --warning-soft: rgba(245, 158, 11, 0.14);
+  --warning-bg: var(--warning-soft);
 
   --danger-500: #ef4444;
   --danger-100: #fee2e2;
   --danger-600: #dc2626;
-  --danger-bg: rgba(239, 68, 68, 0.14);
+  --danger-soft: rgba(239, 68, 68, 0.14);
+  --danger-bg: var(--danger-soft);
 
   --info-500: #3b82f6;
   --info-100: #dbeafe;
   --info-600: #2563eb;
-  --info-bg: rgba(59, 130, 246, 0.14);
+  --info-soft: rgba(59, 130, 246, 0.14);
+  --info-bg: var(--info-soft);
 
   /* Neutrals — 9 stops */
   --neutral-0: #ffffff;
diff --git a/apps/web/src/shared/tabs/README.md b/apps/web/src/shared/tabs/README.md
new file mode 100644
index 0000000..3fb3d45
--- /dev/null
+++ b/apps/web/src/shared/tabs/README.md
@@ -0,0 +1,30 @@
+# 🪟 shared/tabs
+
+共享 tabs / segmented 原语层。
+
+## ✅ 放什么
+- `Tabs`
+- `TabsList`
+- `TabsTrigger`
+- `TabsPanel`
+- segmented 优先的 tablist / tab / tabpanel 语义与 roving keyboard
+- `variant="segmented"` 与预留的 `variant="underline"` API
+
+## 🚫 不放什么
+- 页面路由同步
+- 业务专属 tab 文案或布局
+- 复杂动画与溢出滚动策略
+
+## 状态约定
+- `value` / `onValueChange`：受控模式
+- `defaultValue`：非受控初始值
+- `variant`: 默认 `segmented`，保留 `underline` 以避免后续 API 锁死
+- `activationMode`: `automatic` / `manual`，默认 `automatic`
+- trigger 输出 `data-state="active" | "inactive"`
+- panel 输出 `hidden` 与 `data-state`
+
+## 可访问性
+- `TabsList` 渲染 `role="tablist"`
+- `TabsTrigger` 渲染 `role="tab"`，自动关联 `aria-controls`
+- `TabsPanel` 渲染 `role="tabpanel"`，自动关联 `aria-labelledby`
+- 支持 `Arrow*`、`Home`、`End` 键盘导航
diff --git a/apps/web/src/shared/tabs/TabsPrimitives.tsx b/apps/web/src/shared/tabs/TabsPrimitives.tsx
new file mode 100644
index 0000000..7044519
--- /dev/null
+++ b/apps/web/src/shared/tabs/TabsPrimitives.tsx
@@ -0,0 +1,243 @@
+import {
+  createContext,
+  forwardRef,
+  type ButtonHTMLAttributes,
+  type HTMLAttributes,
+  type KeyboardEvent,
+  useContext,
+  useId,
+  useState
+} from "react";
+
+type TabsVariant = "segmented" | "underline";
+type TabsOrientation = "horizontal" | "vertical";
+type TabsActivationMode = "automatic" | "manual";
+
+type TabsProps = HTMLAttributes<HTMLDivElement> & {
+  activationMode?: TabsActivationMode;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  orientation?: TabsOrientation;
+  value?: string;
+  variant?: TabsVariant;
+};
+
+type TabsContextValue = {
+  activationMode: TabsActivationMode;
+  baseId: string;
+  orientation: TabsOrientation;
+  setValue: (value: string) => void;
+  value: string;
+  variant: TabsVariant;
+};
+
+type TabsTriggerProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "value"> & {
+  value: string;
+};
+
+type TabsPanelProps = HTMLAttributes<HTMLDivElement> & {
+  forceMount?: boolean;
+  value: string;
+};
+
+const TabsContext = createContext<TabsContextValue | null>(null);
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+function sanitizeValue(value: string) {
+  const normalized = value.trim().replace(/[^a-zA-Z0-9_-]+/g, "-");
+  return normalized || "tab";
+}
+
+function getElementId(baseId: string, value: string, suffix: "panel" | "tab") {
+  return `${baseId}-${sanitizeValue(value)}-${suffix}`;
+}
+
+function useTabsContext(componentName: string) {
+  const context = useContext(TabsContext);
+
+  if (!context) {
+    throw new Error(`${componentName} must be used within Tabs.`);
+  }
+
+  return context;
+}
+
+export const Tabs = forwardRef<HTMLDivElement, TabsProps>(function Tabs(
+  {
+    activationMode = "automatic",
+    className,
+    defaultValue,
+    onValueChange,
+    orientation = "horizontal",
+    value,
+    variant = "segmented",
+    ...props
+  },
+  ref
+) {
+  const generatedId = useId();
+  const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue ?? "");
+  const resolvedValue = value ?? uncontrolledValue;
+
+  function handleValueChange(nextValue: string) {
+    if (nextValue === resolvedValue) return;
+    if (value === undefined) {
+      setUncontrolledValue(nextValue);
+    }
+    onValueChange?.(nextValue);
+  }
+
+  return (
+    <TabsContext.Provider
+      value={{
+        activationMode,
+        baseId: generatedId,
+        orientation,
+        setValue: handleValueChange,
+        value: resolvedValue,
+        variant
+      }}
+    >
+      <div
+        {...props}
+        className={cx("ui-tabs", className)}
+        data-orientation={orientation}
+        data-state={resolvedValue ? "ready" : "empty"}
+        data-variant={variant}
+        ref={ref}
+      />
+    </TabsContext.Provider>
+  );
+});
+
+export const TabsList = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(function TabsList(
+  { className, onKeyDown, ...props },
+  ref
+) {
+  const context = useTabsContext("TabsList");
+
+  function handleKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+    onKeyDown?.(event);
+    if (event.defaultPrevented) return;
+
+    if (!["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "Home", "End"].includes(event.key)) return;
+
+    const isHorizontal = context.orientation === "horizontal";
+    const isHorizontalKey = event.key === "ArrowLeft" || event.key === "ArrowRight";
+    const isVerticalKey = event.key === "ArrowUp" || event.key === "ArrowDown";
+
+    if ((isHorizontal && isVerticalKey) || (!isHorizontal && isHorizontalKey)) {
+      return;
+    }
+
+    event.preventDefault();
+
+    const tabs = Array.from(event.currentTarget.querySelectorAll<HTMLButtonElement>("[role=\"tab\"]")).filter(
+      (tab) => !tab.disabled
+    );
+    const activeElement = event.target instanceof HTMLElement ? event.target : null;
+    const currentIndex = activeElement ? tabs.indexOf(activeElement as HTMLButtonElement) : -1;
+
+    if (tabs.length === 0) return;
+
+    let nextIndex = currentIndex === -1 ? 0 : currentIndex;
+
+    if (event.key === "Home") {
+      nextIndex = 0;
+    } else if (event.key === "End") {
+      nextIndex = tabs.length - 1;
+    } else {
+      const direction = event.key === "ArrowLeft" || event.key === "ArrowUp" ? -1 : 1;
+      nextIndex = (currentIndex + direction + tabs.length) % tabs.length;
+    }
+
+    const nextTab = tabs[nextIndex];
+    if (!nextTab) return;
+
+    nextTab.focus();
+
+    if (context.activationMode === "automatic") {
+      context.setValue(nextTab.dataset.value ?? "");
+    }
+  }
+
+  return (
+    <div
+      {...props}
+      aria-orientation={context.orientation}
+      className={cx("ui-tabs-list", className)}
+      data-orientation={context.orientation}
+      data-variant={context.variant}
+      onKeyDown={handleKeyDown}
+      ref={ref}
+      role="tablist"
+    />
+  );
+});
+
+export const TabsTrigger = forwardRef<HTMLButtonElement, TabsTriggerProps>(function TabsTrigger(
+  { className, disabled, onClick, type = "button", value, ...props },
+  ref
+) {
+  const context = useTabsContext("TabsTrigger");
+  const isActive = context.value === value;
+  const triggerId = getElementId(context.baseId, value, "tab");
+  const panelId = getElementId(context.baseId, value, "panel");
+
+  return (
+    <button
+      {...props}
+      aria-controls={panelId}
+      aria-selected={isActive}
+      className={cx("ui-tabs-trigger", isActive && "is-active", disabled && "is-disabled", className)}
+      data-orientation={context.orientation}
+      data-state={isActive ? "active" : "inactive"}
+      data-value={value}
+      data-variant={context.variant}
+      disabled={disabled}
+      id={triggerId}
+      onClick={(event) => {
+        onClick?.(event);
+        if (event.defaultPrevented || disabled) return;
+        context.setValue(value);
+      }}
+      ref={ref}
+      role="tab"
+      tabIndex={isActive ? 0 : -1}
+      type={type}
+    />
+  );
+});
+
+export const TabsPanel = forwardRef<HTMLDivElement, TabsPanelProps>(function TabsPanel(
+  { className, forceMount = true, value, ...props },
+  ref
+) {
+  const context = useTabsContext("TabsPanel");
+  const isActive = context.value === value;
+  const panelId = getElementId(context.baseId, value, "panel");
+  const triggerId = getElementId(context.baseId, value, "tab");
+
+  if (!forceMount && !isActive) {
+    return null;
+  }
+
+  return (
+    <div
+      {...props}
+      aria-labelledby={triggerId}
+      className={cx("ui-tabs-panel", className)}
+      data-orientation={context.orientation}
+      data-state={isActive ? "active" : "inactive"}
+      data-variant={context.variant}
+      hidden={!isActive}
+      id={panelId}
+      ref={ref}
+      role="tabpanel"
+      tabIndex={isActive ? 0 : -1}
+    />
+  );
+});
diff --git a/apps/web/src/shared/tabs/index.ts b/apps/web/src/shared/tabs/index.ts
new file mode 100644
index 0000000..851a232
--- /dev/null
+++ b/apps/web/src/shared/tabs/index.ts
@@ -0,0 +1 @@
+export { Tabs, TabsList, TabsPanel, TabsTrigger } from "./TabsPrimitives";
diff --git a/apps/web/src/shared/tabs/tabs.css b/apps/web/src/shared/tabs/tabs.css
new file mode 100644
index 0000000..d3ddc1a
--- /dev/null
+++ b/apps/web/src/shared/tabs/tabs.css
@@ -0,0 +1,54 @@
+.ui-tabs {
+  display: grid;
+  gap: 12px;
+}
+
+.ui-tabs-list {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  width: fit-content;
+}
+
+.ui-tabs-list[data-variant="segmented"] {
+  padding: 4px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-pill);
+  background: rgba(255, 255, 255, 0.48);
+}
+
+.ui-tabs-list[data-variant="underline"] {
+  border-bottom: 1px solid var(--border);
+}
+
+.ui-tabs-trigger {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 36px;
+  padding: 0 14px;
+  border: 1px solid transparent;
+  border-radius: var(--radius-pill);
+  background: transparent;
+  color: var(--text-muted);
+}
+
+.ui-tabs-trigger[data-state="active"][data-variant="segmented"] {
+  color: var(--bg-elevated);
+  background: var(--surface-contrast);
+  box-shadow: 0 10px 24px rgba(0, 0, 0, 0.12);
+}
+
+.ui-tabs-trigger[data-variant="underline"] {
+  border-radius: 0;
+  border-bottom-color: transparent;
+}
+
+.ui-tabs-trigger[data-state="active"][data-variant="underline"] {
+  color: var(--text);
+  border-bottom-color: currentColor;
+}
+
+.ui-tabs-panel {
+  min-width: 0;
+}
diff --git a/apps/web/src/shared/tag/README.md b/apps/web/src/shared/tag/README.md
new file mode 100644
index 0000000..689cea7
--- /dev/null
+++ b/apps/web/src/shared/tag/README.md
@@ -0,0 +1,26 @@
+# 🏷️ shared/tag
+
+共享分类标签原语层。
+
+## ✅ 放什么
+- `Tag`
+- 分类、来源、主题、能力维度等 category 语义标签
+- `variant / shape / size / dot / icon` 的统一视觉约定
+- 适合列表筛选说明、邮件类型、资源归类等弱状态信息
+
+## 🚫 不放什么
+- 实时运行状态或告警状态展示
+- 需要 live region 的异步反馈
+- 可关闭 / 可编辑 tag 输入器
+
+## 状态约定
+- `variant`: `neutral` / `brand` / `info` / `success` / `warning` / `danger`
+- `shape`: `rounded` / `pill`
+- `size`: `sm` / `md`
+- `dot`: 渲染前导色点
+- `icon`: 渲染前导图标槽位
+
+## 使用约定
+- `Tag` 固定输出 `data-usage="category"`，用于强调“分类而非状态”
+- 如果内容表达的是系统状态、审核状态、启用状态，优先使用 `shared/badge`
+- 样式文件位于 `shared/tag/tag.css`，后续统一由样式 barrel 接入
diff --git a/apps/web/src/shared/tag/TagPrimitives.tsx b/apps/web/src/shared/tag/TagPrimitives.tsx
new file mode 100644
index 0000000..ba8023e
--- /dev/null
+++ b/apps/web/src/shared/tag/TagPrimitives.tsx
@@ -0,0 +1,51 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from "react";
+
+type TagVariant = "neutral" | "brand" | "info" | "success" | "warning" | "danger";
+type TagShape = "rounded" | "pill";
+type TagSize = "sm" | "md";
+
+type TagProps = HTMLAttributes<HTMLSpanElement> & {
+  dot?: boolean;
+  icon?: ReactNode;
+  shape?: TagShape;
+  size?: TagSize;
+  variant?: TagVariant;
+};
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+export const Tag = forwardRef<HTMLSpanElement, TagProps>(function Tag(
+  {
+    children,
+    className,
+    dot,
+    icon,
+    shape = "pill",
+    size = "sm",
+    variant = "neutral",
+    ...props
+  },
+  ref
+) {
+  return (
+    <span
+      {...props}
+      className={cx("ui-tag", `ui-tag-${variant}`, `ui-tag-size-${size}`, `ui-tag-shape-${shape}`, className)}
+      data-shape={shape}
+      data-size={size}
+      data-usage="category"
+      data-variant={variant}
+      ref={ref}
+    >
+      {dot ? <span aria-hidden="true" className="ui-tag-dot" /> : null}
+      {icon ? (
+        <span aria-hidden="true" className="ui-tag-icon">
+          {icon}
+        </span>
+      ) : null}
+      {children ? <span className="ui-tag-label">{children}</span> : null}
+    </span>
+  );
+});
diff --git a/apps/web/src/shared/tag/index.ts b/apps/web/src/shared/tag/index.ts
new file mode 100644
index 0000000..cbde104
--- /dev/null
+++ b/apps/web/src/shared/tag/index.ts
@@ -0,0 +1 @@
+export { Tag } from "./TagPrimitives";
diff --git a/apps/web/src/shared/tag/tag.css b/apps/web/src/shared/tag/tag.css
new file mode 100644
index 0000000..137170e
--- /dev/null
+++ b/apps/web/src/shared/tag/tag.css
@@ -0,0 +1,92 @@
+.ui-tag {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-width: 0;
+  max-width: 100%;
+  border: 1px solid transparent;
+  color: var(--text);
+  font-size: var(--font-caption);
+  font-weight: 600;
+  line-height: var(--line-caption);
+  white-space: nowrap;
+}
+
+.ui-tag-shape-rounded {
+  border-radius: var(--radius-sm);
+}
+
+.ui-tag-shape-pill {
+  border-radius: var(--radius-full);
+}
+
+.ui-tag-size-sm {
+  padding: 5px 10px;
+}
+
+.ui-tag-size-md {
+  padding: 7px 12px;
+}
+
+.ui-tag-dot {
+  width: 7px;
+  height: 7px;
+  border-radius: var(--radius-full);
+  background: currentColor;
+  flex-shrink: 0;
+}
+
+.ui-tag-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+
+.ui-tag-label {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.ui-tag-neutral {
+  background: color-mix(in srgb, var(--neutral-100) 70%, transparent);
+  border-color: color-mix(in srgb, var(--neutral-300) 72%, transparent);
+  color: var(--neutral-700);
+}
+
+.ui-tag-brand {
+  background: color-mix(in srgb, var(--brand-100) 72%, transparent);
+  border-color: color-mix(in srgb, var(--brand-300) 42%, transparent);
+  color: var(--brand-700);
+}
+
+.ui-tag-info {
+  background: color-mix(in srgb, var(--info-100) 74%, transparent);
+  border-color: color-mix(in srgb, var(--info-500) 24%, transparent);
+  color: var(--info-600);
+}
+
+.ui-tag-success {
+  background: color-mix(in srgb, var(--success-100) 72%, transparent);
+  border-color: color-mix(in srgb, var(--success-500) 22%, transparent);
+  color: var(--success-600);
+}
+
+.ui-tag-warning {
+  background: color-mix(in srgb, var(--warning-100) 74%, transparent);
+  border-color: color-mix(in srgb, var(--warning-500) 24%, transparent);
+  color: var(--warning-600);
+}
+
+.ui-tag-danger {
+  background: color-mix(in srgb, var(--danger-100) 74%, transparent);
+  border-color: color-mix(in srgb, var(--danger-500) 22%, transparent);
+  color: var(--danger-600);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ui-tag {
+    transition: none;
+  }
+}
diff --git a/apps/web/src/shared/tooltip/README.md b/apps/web/src/shared/tooltip/README.md
new file mode 100644
index 0000000..f57eabe
--- /dev/null
+++ b/apps/web/src/shared/tooltip/README.md
@@ -0,0 +1,21 @@
+# 💬 shared/tooltip
+
+共享 Tooltip 原语层。
+
+## ✅ 放什么
+- `Tooltip`
+- `TooltipTrigger`
+- `TooltipContent`
+- hover / focus 打开，blur / `Esc` 关闭
+- `aria-describedby` 与 `role="tooltip"` 语义联动
+
+## 🚫 不放什么
+- 全局 tooltip manager
+- 复杂碰撞检测或智能翻转
+- 业务专属富文本提示卡
+
+## 使用约定
+- 触发器默认是按钮语义，适合图标按钮、帮助入口、字段说明
+- Tooltip 仅承载短说明，不承载表单、菜单或可交互流程
+- 长内容或带操作的浮层应改用 `Popover`
+- 内容通过 shared layer portal 渲染，并带基础 top/bottom 回退定位
diff --git a/apps/web/src/shared/tooltip/TooltipPrimitives.tsx b/apps/web/src/shared/tooltip/TooltipPrimitives.tsx
new file mode 100644
index 0000000..7c55272
--- /dev/null
+++ b/apps/web/src/shared/tooltip/TooltipPrimitives.tsx
@@ -0,0 +1,243 @@
+import {
+  createContext,
+  forwardRef,
+  type ButtonHTMLAttributes,
+  type HTMLAttributes,
+  type MutableRefObject,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useId,
+  useRef,
+  useState
+} from "react";
+import { createPortal } from "react-dom";
+
+import { assignRef, useFloatingPosition, usePortalRoot } from "../overlay/layer-utils";
+
+type TooltipProps = {
+  children: ReactNode;
+  defaultOpen?: boolean;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  openDelay?: number;
+};
+
+type TooltipTriggerProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type">;
+
+type TooltipContentProps = HTMLAttributes<HTMLDivElement> & {
+  side?: "top" | "bottom";
+};
+
+type TooltipContextValue = {
+  contentRef: MutableRefObject<HTMLDivElement | null>;
+  contentId: string;
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  startOpenTimer: () => void;
+  stopOpenTimer: () => void;
+  triggerRef: MutableRefObject<HTMLButtonElement | null>;
+};
+
+const TooltipContext = createContext<TooltipContextValue | null>(null);
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+function useTooltipContext() {
+  const context = useContext(TooltipContext);
+
+  if (!context) {
+    throw new Error("Tooltip primitives must be used within <Tooltip>.");
+  }
+
+  return context;
+}
+
+function useControllableOpenState({
+  defaultOpen = false,
+  onOpenChange,
+  open
+}: Pick<TooltipProps, "defaultOpen" | "onOpenChange" | "open">) {
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const isControlled = open !== undefined;
+  const currentOpen = isControlled ? open : internalOpen;
+
+  function setOpen(nextOpen: boolean) {
+    if (!isControlled) {
+      setInternalOpen(nextOpen);
+    }
+
+    onOpenChange?.(nextOpen);
+  }
+
+  return [currentOpen, setOpen] as const;
+}
+
+export function Tooltip({ children, defaultOpen, onOpenChange, open, openDelay = 120 }: TooltipProps) {
+  const contentRef = useRef<HTMLDivElement | null>(null);
+  const contentId = useId();
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const openTimerRef = useRef<number | null>(null);
+  const [isOpen, setOpen] = useControllableOpenState({ defaultOpen, onOpenChange, open });
+
+  function stopOpenTimer() {
+    if (openTimerRef.current) {
+      window.clearTimeout(openTimerRef.current);
+      openTimerRef.current = null;
+    }
+  }
+
+  function startOpenTimer() {
+    stopOpenTimer();
+
+    if (openDelay <= 0) {
+      setOpen(true);
+      return;
+    }
+
+    openTimerRef.current = window.setTimeout(() => {
+      setOpen(true);
+      openTimerRef.current = null;
+    }, openDelay);
+  }
+
+  useEffect(() => stopOpenTimer, []);
+
+  return (
+    <TooltipContext.Provider
+      value={{
+        contentRef,
+        contentId,
+        open: isOpen,
+        setOpen,
+        startOpenTimer,
+        stopOpenTimer,
+        triggerRef
+      }}
+    >
+      <span className="ui-tooltip-root" data-state={isOpen ? "open" : "closed"}>
+        {children}
+      </span>
+    </TooltipContext.Provider>
+  );
+}
+
+export const TooltipTrigger = forwardRef<HTMLButtonElement, TooltipTriggerProps>(function TooltipTrigger(
+  { className, onBlur, onFocus, onKeyDown, onMouseEnter, onMouseLeave, ...props },
+  ref
+) {
+  const { contentId, contentRef, open, setOpen, startOpenTimer, stopOpenTimer, triggerRef } = useTooltipContext();
+
+  return (
+    <button
+      {...props}
+      aria-describedby={open ? contentId : undefined}
+      className={cx("ui-tooltip-trigger", className)}
+      data-state={open ? "open" : "closed"}
+      onBlur={(event) => {
+        onBlur?.(event);
+        if (event.defaultPrevented) return;
+        stopOpenTimer();
+        setOpen(false);
+      }}
+      onFocus={(event) => {
+        onFocus?.(event);
+        if (event.defaultPrevented) return;
+        stopOpenTimer();
+        setOpen(true);
+      }}
+      onKeyDown={(event) => {
+        onKeyDown?.(event);
+        if (event.defaultPrevented) return;
+        if (event.key === "Escape") {
+          stopOpenTimer();
+          setOpen(false);
+        }
+      }}
+      onMouseEnter={(event) => {
+        onMouseEnter?.(event);
+        if (event.defaultPrevented) return;
+        startOpenTimer();
+      }}
+      onMouseLeave={(event) => {
+        onMouseLeave?.(event);
+        if (event.defaultPrevented) return;
+        if (event.relatedTarget instanceof Node && contentRef.current?.contains(event.relatedTarget)) {
+          return;
+        }
+        stopOpenTimer();
+        setOpen(false);
+      }}
+      ref={(node) => {
+        triggerRef.current = node;
+        assignRef(ref, node);
+      }}
+      type="button"
+    />
+  );
+});
+
+export const TooltipContent = forwardRef<HTMLDivElement, TooltipContentProps>(function TooltipContent(
+  { children, className, onKeyDown, onMouseEnter, onMouseLeave, side = "top", ...props },
+  ref
+) {
+    const { contentId, contentRef, open, setOpen, startOpenTimer, stopOpenTimer, triggerRef } = useTooltipContext();
+    const portalRoot = usePortalRoot();
+    const { resolvedSide, style } = useFloatingPosition({
+      align: "center",
+      anchorRef: triggerRef as MutableRefObject<HTMLElement | null>,
+      contentRef: contentRef as MutableRefObject<HTMLElement | null>,
+      matchAnchorWidth: false,
+      offset: 8,
+      open,
+      preferredSide: side
+    });
+
+    if (!open || !portalRoot) {
+      return null;
+    }
+
+    return createPortal(
+      <div
+        {...props}
+        className={cx("ui-tooltip-content", `ui-tooltip-side-${resolvedSide}`, className)}
+        data-side={resolvedSide}
+        data-state="open"
+        id={contentId}
+        onKeyDown={(event) => {
+          onKeyDown?.(event);
+          if (event.defaultPrevented) return;
+          if (event.key === "Escape") {
+            setOpen(false);
+            triggerRef.current?.focus();
+          }
+        }}
+        onMouseEnter={(event) => {
+          onMouseEnter?.(event);
+          if (event.defaultPrevented) return;
+          startOpenTimer();
+        }}
+        onMouseLeave={(event) => {
+          onMouseLeave?.(event);
+          if (event.defaultPrevented) return;
+          if (event.relatedTarget instanceof Node && triggerRef.current?.contains(event.relatedTarget)) {
+            return;
+          }
+          stopOpenTimer();
+          setOpen(false);
+        }}
+        ref={(node) => {
+          contentRef.current = node;
+          assignRef(ref, node);
+        }}
+        role="tooltip"
+        style={style}
+      >
+        {children}
+      </div>,
+      portalRoot
+    );
+  }
+);
diff --git a/apps/web/src/shared/tooltip/index.ts b/apps/web/src/shared/tooltip/index.ts
new file mode 100644
index 0000000..ba9cebf
--- /dev/null
+++ b/apps/web/src/shared/tooltip/index.ts
@@ -0,0 +1 @@
+export { Tooltip, TooltipContent, TooltipTrigger } from "./TooltipPrimitives";
diff --git a/apps/web/src/shared/tooltip/tooltip.css b/apps/web/src/shared/tooltip/tooltip.css
new file mode 100644
index 0000000..550efd3
--- /dev/null
+++ b/apps/web/src/shared/tooltip/tooltip.css
@@ -0,0 +1,39 @@
+.ui-tooltip-root {
+  position: relative;
+  display: inline-flex;
+}
+
+.ui-tooltip-trigger {
+  appearance: none;
+  border: 0;
+  background: transparent;
+  padding: 0;
+  margin: 0;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
+
+.ui-tooltip-content {
+  position: absolute;
+  left: 50%;
+  z-index: 40;
+  max-width: 18rem;
+  transform: translateX(-50%);
+  border: 1px solid var(--border-subtle, rgba(255, 255, 255, 0.12));
+  border-radius: var(--radius-md, 12px);
+  background: var(--surface-elevated, rgba(13, 17, 23, 0.96));
+  color: var(--text-primary, #f8fafc);
+  box-shadow: var(--shadow-lg, 0 20px 48px rgba(15, 23, 42, 0.24));
+  padding: 0.5rem 0.75rem;
+  font-size: 0.8125rem;
+  line-height: 1.4;
+}
+
+.ui-tooltip-side-top {
+  bottom: calc(100% + 0.5rem);
+}
+
+.ui-tooltip-side-bottom {
+  top: calc(100% + 0.5rem);
+}
diff --git a/apps/web/src/shared/typography/README.md b/apps/web/src/shared/typography/README.md
new file mode 100644
index 0000000..118839b
--- /dev/null
+++ b/apps/web/src/shared/typography/README.md
@@ -0,0 +1,24 @@
+# ✍️ shared/typography
+
+共享排版原语层。
+
+## ✅ 放什么
+- `Heading`
+- `Text`
+- `Label`
+- `Muted`
+- `Code`
+- `Kbd`
+- 基于语义字号、tone 和原生标签的轻量排版封装
+
+## 🚫 不放什么
+- 页面级富文本排版系统
+- Markdown 渲染器
+- 业务专属文案拼装逻辑
+
+## 使用约定
+- 标题优先用 `Heading`，正文优先用 `Text`
+- 弱化说明、时间戳、辅助信息用 `Muted`
+- 字段标题或可点击表单标签用 `Label`
+- 内联标识符、环境变量、命令片段用 `Code`
+- 快捷键提示统一用 `Kbd`
diff --git a/apps/web/src/shared/typography/TypographyPrimitives.tsx b/apps/web/src/shared/typography/TypographyPrimitives.tsx
new file mode 100644
index 0000000..41662fb
--- /dev/null
+++ b/apps/web/src/shared/typography/TypographyPrimitives.tsx
@@ -0,0 +1,126 @@
+import {
+  Fragment,
+  forwardRef,
+  type CSSProperties,
+  type HTMLAttributes,
+  type LabelHTMLAttributes,
+  type ReactNode
+} from "react";
+
+type TypographyTone = "default" | "muted" | "accent" | "success" | "warning" | "danger";
+type HeadingSize = "display-lg" | "display-md" | "title-lg" | "title-md";
+type TextSize = "lg" | "md" | "caption";
+type HeadingTag = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+type TextTag = "p" | "span" | "div";
+type CodeTag = "code" | "pre" | "span";
+
+type HeadingProps = HTMLAttributes<HTMLHeadingElement> & {
+  as?: HeadingTag;
+  size?: HeadingSize;
+  tone?: TypographyTone;
+};
+
+type TextProps = HTMLAttributes<HTMLElement> & {
+  as?: TextTag;
+  size?: TextSize;
+  tone?: TypographyTone;
+};
+
+type LabelProps = LabelHTMLAttributes<HTMLLabelElement> & {
+  size?: Extract<TextSize, "md" | "caption">;
+  tone?: TypographyTone;
+};
+
+type CodeProps = HTMLAttributes<HTMLElement> & {
+  as?: CodeTag;
+  block?: boolean;
+  tone?: TypographyTone;
+};
+
+type KbdProps = HTMLAttributes<HTMLElement> & {
+  keys?: ReactNode[];
+  separator?: ReactNode;
+};
+
+function cx(...parts: Array<string | false | null | undefined>) {
+  return parts.filter(Boolean).join(" ");
+}
+
+function toneClassName(tone: TypographyTone) {
+  return tone === "default" ? undefined : `ui-tone-${tone}`;
+}
+
+function mergeStyle(style?: CSSProperties, nextStyle?: CSSProperties) {
+  if (!style) return nextStyle;
+  if (!nextStyle) return style;
+  return { ...nextStyle, ...style };
+}
+
+export const Heading = forwardRef<HTMLHeadingElement, HeadingProps>(function Heading(
+  { as = "h2", className, size = "title-lg", tone = "default", ...props },
+  ref
+) {
+  const Comp = as;
+
+  return <Comp {...props} className={cx("ui-heading", `ui-heading-${size}`, toneClassName(tone), className)} ref={ref} />;
+});
+
+export const Text = forwardRef<HTMLElement, TextProps>(function Text(
+  { as = "p", className, size = "md", tone = "default", ...props },
+  ref
+) {
+  const Comp = as;
+
+  return <Comp {...props} className={cx("ui-text", `ui-text-${size}`, toneClassName(tone), className)} ref={ref as never} />;
+});
+
+export const Muted = forwardRef<HTMLElement, Omit<TextProps, "tone">>(function Muted(
+  { className, size = "md", ...props },
+  ref
+) {
+  return <Text {...props} className={cx("ui-text-muted", className)} ref={ref as never} size={size} tone="muted" />;
+});
+
+export const Label = forwardRef<HTMLLabelElement, LabelProps>(function Label(
+  { className, size = "md", tone = "default", ...props },
+  ref
+) {
+  return <label {...props} className={cx("ui-label", `ui-label-${size}`, toneClassName(tone), className)} ref={ref} />;
+});
+
+export const Code = forwardRef<HTMLElement, CodeProps>(function Code(
+  { as = "code", block = false, className, style, tone = "default", ...props },
+  ref
+) {
+  const Comp = as;
+  const nextStyle = mergeStyle(style, block || as === "pre" ? { display: "block" } : undefined);
+
+  return (
+    <Comp
+      {...props}
+      className={cx("ui-code", (block || as === "pre") && "ui-code-block", toneClassName(tone), className)}
+      ref={ref as never}
+      style={nextStyle}
+    />
+  );
+});
+
+export const Kbd = forwardRef<HTMLElement, KbdProps>(function Kbd(
+  { children, className, keys, separator = "+", ...props },
+  ref
+) {
+  const segments = keys?.length ? keys : undefined;
+
+  return (
+    <kbd {...props} className={cx("ui-kbd", className)} ref={ref}>
+      {segments
+        ? segments.map((segment, index) => (
+            <Fragment key={`${String(segment)}-${index}`}>
+              {index > 0 ? <span className="ui-kbd-separator">{separator}</span> : null}
+              <span className="ui-kbd-key">{segment}</span>
+            </Fragment>
+          ))
+        : children}
+    </kbd>
+  );
+});
diff --git a/apps/web/src/shared/typography/index.ts b/apps/web/src/shared/typography/index.ts
new file mode 100644
index 0000000..4163c16
--- /dev/null
+++ b/apps/web/src/shared/typography/index.ts
@@ -0,0 +1 @@
+export { Code, Heading, Kbd, Label, Muted, Text } from "./TypographyPrimitives";
diff --git a/apps/web/src/shared/typography/typography.css b/apps/web/src/shared/typography/typography.css
new file mode 100644
index 0000000..ea46e43
--- /dev/null
+++ b/apps/web/src/shared/typography/typography.css
@@ -0,0 +1,132 @@
+.ui-heading,
+.ui-text,
+.ui-label,
+.ui-code,
+.ui-kbd {
+  margin: 0;
+  color: var(--text);
+}
+
+.ui-heading {
+  font-weight: 700;
+  letter-spacing: -0.02em;
+}
+
+.ui-heading-display-lg {
+  font-size: var(--font-display-lg);
+  line-height: var(--line-display);
+}
+
+.ui-heading-display-md {
+  font-size: var(--font-display-md);
+  line-height: var(--line-display);
+}
+
+.ui-heading-title-lg {
+  font-size: var(--font-title-lg);
+  line-height: var(--line-title);
+}
+
+.ui-heading-title-md {
+  font-size: var(--font-title-md);
+  line-height: var(--line-title);
+}
+
+.ui-text-lg {
+  font-size: var(--font-body-lg);
+  line-height: var(--line-body);
+}
+
+.ui-text-md,
+.ui-label-md {
+  font-size: var(--font-body-md);
+  line-height: var(--line-body);
+}
+
+.ui-text-caption,
+.ui-label-caption {
+  font-size: var(--font-caption);
+  line-height: var(--line-caption);
+}
+
+.ui-label {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  font-weight: 600;
+}
+
+.ui-text-muted,
+.ui-text.ui-tone-muted,
+.ui-label.ui-tone-muted {
+  color: var(--text-muted);
+}
+
+.ui-heading.ui-tone-accent,
+.ui-text.ui-tone-accent,
+.ui-label.ui-tone-accent,
+.ui-code.ui-tone-accent {
+  color: var(--brand-500);
+}
+
+.ui-heading.ui-tone-success,
+.ui-text.ui-tone-success,
+.ui-label.ui-tone-success,
+.ui-code.ui-tone-success {
+  color: var(--success-600);
+}
+
+.ui-heading.ui-tone-warning,
+.ui-text.ui-tone-warning,
+.ui-label.ui-tone-warning,
+.ui-code.ui-tone-warning {
+  color: var(--warning-600);
+}
+
+.ui-heading.ui-tone-danger,
+.ui-text.ui-tone-danger,
+.ui-label.ui-tone-danger,
+.ui-code.ui-tone-danger {
+  color: var(--danger-600);
+}
+
+.ui-code,
+.ui-kbd {
+  font-family: var(--font-mono);
+  font-size: var(--font-mono-size);
+  line-height: var(--line-mono);
+}
+
+.ui-code {
+  display: inline-flex;
+  align-items: center;
+  padding: 0.14rem 0.42rem;
+  border: 1px solid color-mix(in srgb, var(--border) 86%, transparent);
+  border-radius: var(--radius-sm);
+  background: color-mix(in srgb, var(--surface-muted) 84%, transparent);
+}
+
+.ui-code-block {
+  padding: var(--space-3) var(--space-4);
+  overflow: auto;
+}
+
+.ui-kbd {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-1);
+  padding: 0.2rem 0.45rem;
+  border: 1px solid color-mix(in srgb, var(--border) 82%, transparent);
+  border-radius: var(--radius-sm);
+  background: color-mix(in srgb, var(--surface-strong) 84%, transparent);
+  box-shadow: var(--elevation-xs);
+}
+
+.ui-kbd-key {
+  min-width: 1.2rem;
+  text-align: center;
+}
+
+.ui-kbd-separator {
+  color: var(--text-soft);
+}
diff --git a/apps/web/src/test/app.test.tsx b/apps/web/src/test/app.test.tsx
index fd15788..12f2e3e 100644
--- a/apps/web/src/test/app.test.tsx
+++ b/apps/web/src/test/app.test.tsx
@@ -5,6 +5,8 @@ import { App } from "../app/App";
 import { WORKSPACE_THEME_STORAGE_KEY } from "../app/appStore";
 import { jsonResponse } from "./helpers/mock-api";
 
+const DESIGN_SYSTEM_THEME_STORAGE_KEY = "wemail-design-system-preview-theme";
+
 const originalMatchMedia = window.matchMedia;
 
 function installMatchMedia({
@@ -83,9 +85,171 @@ describe("App", () => {
       expect(within(navigation).getByLabelText(/WeMail brand lockup/i)).toBeInTheDocument();
       expect(within(navigation).getByRole("link", { name: /^产品能力$/i })).toHaveAttribute("href", "#features");
       expect(within(navigation).getByRole("link", { name: /^使用流程$/i })).toHaveAttribute("href", "#how-it-works");
-      expect(screen.getByRole("heading", { name: /把临时邮箱/i })).toBeInTheDocument();
+      expect(within(navigation).getByRole("link", { name: /^开发接入$/i })).toHaveAttribute("href", "#developers");
+      expect(within(navigation).getByRole("link", { name: /^方案价格$/i })).toHaveAttribute("href", "#pricing");
+      expect(within(navigation).getByRole("link", { name: /设计系统/i })).toHaveAttribute("href", "/design-system");
+      expect(screen.getByRole("heading", { level: 1, name: /把临时邮箱/i })).toBeInTheDocument();
       expect(within(navigation).getByRole("link", { name: /登录/i })).toHaveClass("ui-button", "ui-button-secondary");
       expect(within(navigation).getByRole("link", { name: /注册/i })).toHaveClass("ui-button", "ui-button-primary");
+      expect(within(navigation).getByRole("button", { name: /切换到浅色主题|切换到深色主题/i })).toHaveClass(
+        "landing-nav-theme-toggle",
+        "landing-nav-edge-control"
+      );
+      expect(screen.getAllByRole("link", { name: /立即开始/i }).length).toBeGreaterThan(0);
+      expect(screen.getAllByRole("link", { name: /进入登录/i }).length).toBeGreaterThan(0);
+    },
+    10000
+  );
+
+  it(
+    "renders the design system as a public route with sidebar navigation and the first component detail by default",
+    async () => {
+      window.history.pushState({}, "", "/design-system");
+      vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("not authenticated"));
+      render(<App />);
+
+      expect(await screen.findByTestId("design-system-page")).toBeInTheDocument();
+      const sidebar = screen.getByRole("navigation", { name: "Design system sidebar" });
+      expect(sidebar).toBeInTheDocument();
+      expect(within(sidebar).queryByRole("button", { name: /概览/i })).not.toBeInTheDocument();
+      expect(within(sidebar).getByRole("button", { name: "Design tokens" })).toHaveAttribute("aria-current", "page");
+      expect(screen.getByRole("heading", { level: 1, name: "Design tokens" })).toBeInTheDocument();
+      expect(screen.getByText(/品牌色、语义色、间距、圆角和阴影的统一定义/i)).toBeInTheDocument();
+      expect(screen.queryByText("Current mode")).not.toBeInTheDocument();
+      expect(screen.queryByText(/这个页面现在改成左侧导航和右侧内容面板/i)).not.toBeInTheDocument();
+      expect(screen.queryByRole("button", { name: "切换主题" })).not.toBeInTheDocument();
+      expect(screen.queryByRole("button", { name: "复制预览链接" })).not.toBeInTheDocument();
+      expect(screen.getByText("WeMail Design System v1")).toBeInTheDocument();
+      expect(screen.getByRole("button", { name: "打开对话框" })).toBeInTheDocument();
+      expect(screen.queryByText(/Design system preview workspace/i)).not.toBeInTheDocument();
+      expect(screen.queryByText(/S1-S7/i)).not.toBeInTheDocument();
+      expect(screen.queryByRole("tablist", { name: /认证方式切换/i })).not.toBeInTheDocument();
+    },
+    10000
+  );
+
+  it(
+    "switches the right panel to component detail when a sidebar component is selected",
+    async () => {
+      window.history.pushState({}, "", "/design-system");
+      vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("not authenticated"));
+      render(<App />);
+
+      const sidebar = await screen.findByRole("navigation", { name: "Design system sidebar" });
+      fireEvent.click(within(sidebar).getByRole("button", { name: "Button" }));
+
+      expect(screen.getByRole("heading", { level: 1, name: "Button" })).toBeInTheDocument();
+      expect(screen.getByText(/覆盖主要、次要、轻量、危险和 icon-only 等动作样式/i)).toBeInTheDocument();
+      expect(screen.getByRole("heading", { level: 2, name: "Buttons & Actions" })).toBeInTheDocument();
+      expect(screen.queryByText(/Design tokens、预览地图、文档入口与视觉回归基线/i)).not.toBeInTheDocument();
+    },
+    10000
+  );
+
+  it(
+    "renders structured documentation sections for the initial component-docsite targets",
+    async () => {
+      window.history.pushState({}, "", "/design-system");
+      vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("not authenticated"));
+      render(<App />);
+
+      const sidebar = await screen.findByRole("navigation", { name: "Design system sidebar" });
+
+      expect(screen.getByRole("heading", { level: 2, name: "使用说明" })).toBeInTheDocument();
+      expect(screen.getByText(/品牌色、语义色、间距、圆角和阴影的统一定义/i)).toBeInTheDocument();
+
+      fireEvent.click(within(sidebar).getByRole("button", { name: "Button" }));
+      expect(screen.getByRole("heading", { level: 2, name: "API 接口" })).toBeInTheDocument();
+      const apiSection = screen.getByRole("region", { name: "文档章节：API 接口" });
+      expect(within(apiSection).getByText("variant")).toBeInTheDocument();
+      expect(within(apiSection).getAllByText(/primary/i).length).toBeGreaterThan(0);
+
+      fireEvent.click(within(sidebar).getByRole("button", { name: "Card" }));
+      expect(screen.getByRole("heading", { level: 2, name: "设计规范" })).toBeInTheDocument();
+      expect(screen.getByText(/卡片只负责建立信息边界，不应该再承担页面级布局职责/i)).toBeInTheDocument();
+
+      fireEvent.click(within(sidebar).getByRole("button", { name: "SearchInput" }));
+      expect(screen.getByText(/搜索框应直接表达可搜索对象，例如账号、地址或创建人/i)).toBeInTheDocument();
+
+      fireEvent.click(within(sidebar).getByRole("button", { name: "Navigation" }));
+      expect(screen.getByText(/导航组件首先服务于定位和切换，不应混入主操作按钮语义/i)).toBeInTheDocument();
+
+      fireEvent.click(within(sidebar).getByRole("button", { name: "Feedback" }));
+      expect(screen.getByText(/Skeleton 和 Spinner 只用于短暂加载反馈，不应替代真正的空状态说明/i)).toBeInTheDocument();
+    },
+    10000
+  );
+
+  it(
+    "renders component docs with examples first, then API, then usage guidance",
+    async () => {
+      window.history.pushState({}, "", "/design-system");
+      vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("not authenticated"));
+      render(<App />);
+
+      const sidebar = await screen.findByRole("navigation", { name: "Design system sidebar" });
+      fireEvent.click(within(sidebar).getByRole("button", { name: "Button" }));
+
+      const headings = screen.getAllByRole("heading").map((node) => node.textContent);
+      const requiredHeadings = ["真实示例", "API 接口", "使用说明"];
+      const headingIndexes = requiredHeadings.map((heading) => headings.indexOf(heading));
+
+      expect(headingIndexes.every((index) => index >= 0)).toBe(true);
+      expect(headingIndexes).toEqual([...headingIndexes].sort((left, right) => left - right));
+    },
+    10000
+  );
+
+  it(
+    "renders separate doc sections and code sample regions for a component",
+    async () => {
+      window.history.pushState({}, "", "/design-system");
+      vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("not authenticated"));
+      render(<App />);
+
+      const sidebar = await screen.findByRole("navigation", { name: "Design system sidebar" });
+      fireEvent.click(within(sidebar).getByRole("button", { name: "Button" }));
+
+      expect(screen.getByRole("region", { name: "文档章节：API 接口" })).toBeInTheDocument();
+      expect(screen.getByRole("region", { name: "文档章节：设计规范" })).toBeInTheDocument();
+      expect(screen.getByRole("region", { name: "代码示例：Button" })).toBeInTheDocument();
+    },
+    10000
+  );
+
+  it(
+    "documents button with examples, API, usage, and design guidance",
+    async () => {
+      window.history.pushState({}, "", "/design-system");
+      vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("not authenticated"));
+      render(<App />);
+
+      const sidebar = await screen.findByRole("navigation", { name: "Design system sidebar" });
+      fireEvent.click(within(sidebar).getByRole("button", { name: "Button" }));
+
+      expect(screen.getByRole("heading", { level: 2, name: "真实示例" })).toBeInTheDocument();
+      expect(screen.getByRole("heading", { level: 2, name: "API 接口" })).toBeInTheDocument();
+      expect(screen.getByRole("heading", { level: 2, name: "使用说明" })).toBeInTheDocument();
+      expect(screen.getByRole("heading", { level: 2, name: "设计规范" })).toBeInTheDocument();
+      expect(screen.getByRole("region", { name: "代码示例：Button" })).toBeInTheDocument();
+    },
+    10000
+  );
+
+  it(
+    "keeps the design system preview theme separate from the workspace theme storage",
+    async () => {
+      window.history.pushState({}, "", "/design-system");
+      vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("not authenticated"));
+      render(<App />);
+
+      expect(await screen.findByTestId("design-system-page")).toBeInTheDocument();
+      const workspaceThemeBeforeToggle = window.localStorage.getItem(WORKSPACE_THEME_STORAGE_KEY) ?? "__missing__";
+      const designSystemThemeBeforeToggle = window.localStorage.getItem(DESIGN_SYSTEM_THEME_STORAGE_KEY);
+      fireEvent.click(screen.getByRole("button", { name: /切换到浅色主题|切换到深色主题/i }));
+
+      expect(window.localStorage.getItem(WORKSPACE_THEME_STORAGE_KEY) ?? "__missing__").toBe(workspaceThemeBeforeToggle);
+      expect(window.localStorage.getItem(DESIGN_SYSTEM_THEME_STORAGE_KEY)).not.toBe(designSystemThemeBeforeToggle);
     },
     10000
   );
@@ -128,8 +292,8 @@ describe("App", () => {
       expect(screen.queryAllByRole("heading", { name: /登录到 WeMail/i })).toHaveLength(0);
       expect(screen.queryByText(/在同一个认证入口里切换登录与注册/i)).not.toBeInTheDocument();
       expect(screen.queryByText(/^账号登录$/i)).not.toBeInTheDocument();
-      const emailInput = screen.getByLabelText(/邮箱/i);
-      const passwordInput = screen.getByLabelText(/密码/i);
+      const emailInput = screen.getByLabelText(/邮箱/i, { selector: "input" });
+      const passwordInput = screen.getByLabelText(/密码/i, { selector: "input" });
       expect(emailInput).toBeInTheDocument();
       expect(emailInput.closest(".form-control-shell")?.querySelector(".form-control-icon")).not.toBeNull();
       expect(passwordInput).toHaveAttribute("type", "password");
@@ -138,7 +302,7 @@ describe("App", () => {
       expect(toggle).toBeInTheDocument();
 
       fireEvent.click(toggle);
-      expect(screen.getByLabelText(/密码/i)).toHaveAttribute("type", "text");
+      expect(screen.getByLabelText(/密码/i, { selector: "input" })).toHaveAttribute("type", "text");
       expect(screen.getByRole("button", { name: "隐藏密码" })).toBeInTheDocument();
       expect(container.querySelectorAll(".form-control-shell").length).toBeGreaterThanOrEqual(2);
     },
@@ -175,8 +339,40 @@ describe("App", () => {
 
       const dialog = screen.getByRole("dialog", { name: /首页移动菜单/i });
       expect(dialog).toBeInTheDocument();
+      expect(screen.getByRole("button", { name: /切换菜单/i })).toHaveClass(
+        "landing-nav-mobile-toggle",
+        "landing-nav-mobile-toggle-tight"
+      );
+      expect(screen.getByRole("button", { name: /切换菜单/i })).not.toHaveStyle({ transform: "translateY(-1px)" });
       expect(within(dialog).getByRole("link", { name: /^方案价格$/i })).toHaveAttribute("href", "#pricing");
       expect(within(dialog).getByRole("link", { name: /登录/i })).toBeInTheDocument();
+      expect(within(dialog).queryByRole("link", { name: /设计系统/i })).toBeInTheDocument();
+      expect(within(dialog).queryByRole("button", { name: /切换到浅色主题|切换到深色主题/i })).toHaveClass("landing-nav-theme-toggle");
+
+      fireEvent.click(within(dialog).getByRole("link", { name: /设计系统/i }));
+
+      await waitFor(() => {
+        expect(window.location.pathname).toBe("/design-system");
+      });
+    },
+    10000
+  );
+
+  it(
+    "renders each integration card only once on compact navigation",
+    async () => {
+      vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("not authenticated"));
+      installMatchMedia({ compactNavigation: true, dark: true });
+      const { container } = render(<App />);
+
+      await screen.findByRole("heading", { level: 2, name: /和你已经在用的系统自然接上/i });
+
+      const integrationsSection = container.querySelector("#integrations");
+      expect(integrationsSection).not.toBeNull();
+      expect(integrationsSection?.querySelectorAll(".landing-integration-card")).toHaveLength(12);
+      expect(within(integrationsSection as HTMLElement).getAllByText(/^Cloudflare$/i)).toHaveLength(1);
+      expect(within(integrationsSection as HTMLElement).getAllByText(/^Telegram$/i)).toHaveLength(1);
+      expect(within(integrationsSection as HTMLElement).getAllByText(/^Feature Flags$/i)).toHaveLength(1);
     },
     10000
   );
@@ -363,7 +559,7 @@ describe("App", () => {
 
       expect(await screen.findByRole("columnheader", { name: "地址" })).toBeInTheDocument();
       expect(screen.queryByText("账号列表先以占位页承接")).not.toBeInTheDocument();
-      expect(container.querySelectorAll(".accounts-status-pill")).toHaveLength(3);
+      expect(container.querySelectorAll(".ui-badge")).toHaveLength(3);
       expect(container.querySelector(".accounts-list-bulk-bar")).toBeNull();
     },
     10000
diff --git a/apps/web/src/test/design-system-page.test.tsx b/apps/web/src/test/design-system-page.test.tsx
new file mode 100644
index 0000000..8c5b2aa
--- /dev/null
+++ b/apps/web/src/test/design-system-page.test.tsx
@@ -0,0 +1,259 @@
+import { cleanup, fireEvent, render, screen, within } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { MemoryRouter } from "react-router-dom";
+
+import { DesignSystemPage } from "../pages/DesignSystemPage";
+import { designSystemGroups } from "../pages/design-system/designSystemContent";
+
+describe("DesignSystemPage", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders a sidebar-driven public design system docsite", () => {
+    render(
+      <MemoryRouter>
+        <DesignSystemPage />
+      </MemoryRouter>
+    );
+
+    const sidebar = screen.getByRole("navigation", { name: "Design system sidebar" });
+
+    expect(sidebar).toBeInTheDocument();
+    expect(within(sidebar).getAllByRole("button").length).toBeGreaterThan(10);
+    expect(screen.getByRole("navigation", { name: "首页导航" })).toBeInTheDocument();
+    expect(screen.getAllByRole("heading", { name: "Foundations" }).length).toBeGreaterThan(0);
+    expect(screen.getByRole("link", { name: "WeMail 首页" })).toBeInTheDocument();
+  });
+
+  it("renders sidebar groups with component items only and no overview entries", () => {
+    render(
+      <MemoryRouter>
+        <DesignSystemPage />
+      </MemoryRouter>
+    );
+
+    const sidebar = screen.getByRole("navigation", { name: "Design system sidebar" });
+
+    expect(within(sidebar).queryByRole("button", { name: /概览/i })).not.toBeInTheDocument();
+    expect(within(sidebar).getByRole("button", { name: "Button" })).toBeInTheDocument();
+    expect(within(sidebar).getByRole("button", { name: "Card" })).toBeInTheDocument();
+    expect(within(sidebar).getByRole("button", { name: "SearchInput" })).toBeInTheDocument();
+  });
+
+  it("keeps the left sidebar as a single visual shell", () => {
+    render(
+      <MemoryRouter>
+        <DesignSystemPage />
+      </MemoryRouter>
+    );
+
+    const sidebar = screen.getByRole("navigation", { name: "Design system sidebar" });
+    const sidebarParentSection = sidebar.closest("section");
+    const sidebarAside = sidebar.closest("aside");
+
+    expect(sidebarParentSection).toBeNull();
+    expect(sidebarAside).toHaveClass("workspace-rail-shell");
+    expect(sidebarAside).not.toHaveClass("panel");
+    expect(sidebar).toHaveClass("workspace-rail", "workspace-scroll-area");
+    expect(sidebar).toHaveStyle({
+      border: "none",
+      borderRadius: "0",
+      background: "transparent",
+      boxShadow: "none"
+    });
+  });
+
+  it("keeps a single elevated sidebar base card and leaves non-active sidebar items unshadowed", () => {
+    render(
+      <MemoryRouter>
+        <DesignSystemPage />
+      </MemoryRouter>
+    );
+
+    const sidebarShell = screen.getByRole("navigation", { name: "Design system sidebar" }).closest("aside");
+    const activeSidebarItem = screen.getByRole("button", { name: "Design tokens" });
+    const inactiveSidebarItem = screen.getByRole("button", { name: "PageLayout" });
+    const docCard = screen.getByRole("heading", { name: "Design tokens" }).closest("section");
+
+    expect(sidebarShell).not.toBeNull();
+    expect(activeSidebarItem.closest("aside")).toBe(sidebarShell);
+    expect(inactiveSidebarItem).not.toHaveStyle({ boxShadow: "0 16px 32px rgba(0, 0, 0, 0.18)" });
+    expect(docCard).not.toBeNull();
+  });
+
+  it("removes the empty top gutter inside the sidebar base card", () => {
+    render(
+      <MemoryRouter>
+        <DesignSystemPage />
+      </MemoryRouter>
+    );
+
+    const sidebar = screen.getByRole("navigation", { name: "Design system sidebar" });
+    const firstGroupHeading = within(sidebar).getByText("Foundations");
+
+    expect(firstGroupHeading).toBeInTheDocument();
+  });
+
+  it("renders a public showcase with live overlay controls", () => {
+    render(
+      <MemoryRouter>
+        <DesignSystemPage />
+      </MemoryRouter>
+    );
+
+    expect(screen.getByText("WeMail Design System v1")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "打开对话框" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "打开抽屉" })).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("button", { name: "打开对话框" }));
+    expect(screen.getByRole("dialog", { name: "Dialog live preview" })).toBeInTheDocument();
+  });
+
+  it("keeps the drawer preview action compact", () => {
+    render(
+      <MemoryRouter>
+        <DesignSystemPage />
+      </MemoryRouter>
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "打开抽屉" }));
+
+    const drawer = screen.getByRole("dialog", { name: "Drawer live preview" });
+    expect(within(drawer).getByRole("button", { name: "完成预览" })).toHaveClass("ui-button-size-xs");
+  });
+
+  it("uses the same card surface tone for hero and right-side docs, and keeps sidebar cards elevated", () => {
+    render(
+      <MemoryRouter>
+        <DesignSystemPage />
+      </MemoryRouter>
+    );
+
+    const heroCard = screen.getByText("WeMail Design System v1").closest("section");
+    const docCard = screen.getByRole("heading", { name: "Design tokens" }).closest("section");
+    const activeSidebarItem = screen.getByRole("button", { name: "Design tokens" });
+
+    expect(heroCard).not.toBeNull();
+    expect(docCard).not.toBeNull();
+    expect(activeSidebarItem).not.toBeNull();
+  });
+
+  it("keeps live preview panes shrinkable inside the design system layout", () => {
+    render(
+      <MemoryRouter>
+        <DesignSystemPage />
+      </MemoryRouter>
+    );
+
+    const previewPanes = screen.getAllByTestId("design-system-preview-pane");
+
+    expect(previewPanes.length).toBeGreaterThan(0);
+    for (const previewPane of previewPanes) {
+      expect(previewPane).toHaveStyle({ minWidth: "0" });
+    }
+  });
+
+  it("shows button code samples alongside the live button preview", () => {
+    render(
+      <MemoryRouter>
+        <DesignSystemPage />
+      </MemoryRouter>
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Button" }));
+
+    const codeSamplesRegion = screen.getByRole("region", { name: "代码示例：Button" });
+    expect(within(codeSamplesRegion).getAllByRole("heading", { level: 3 }).length).toBeGreaterThan(0);
+    expect(within(codeSamplesRegion).getAllByText(/<Button/).length).toBeGreaterThan(0);
+
+    const livePreviewSection = screen.getByRole("heading", { name: "Buttons & Actions" }).closest("section");
+    expect(livePreviewSection).not.toBeNull();
+    expect(within(livePreviewSection as HTMLElement).getByRole("button", { name: "保存变更" })).toBeInTheDocument();
+    expect(within(livePreviewSection as HTMLElement).getByRole("button", { name: "停用账号" })).toBeInTheDocument();
+  });
+
+  it("renders component docs with examples first, then API, then usage guidance", () => {
+    render(
+      <MemoryRouter>
+        <DesignSystemPage />
+      </MemoryRouter>
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Button" }));
+
+    const headings = screen.getAllByRole("heading").map((node) => node.textContent);
+    const expected = ["真实示例", "API 接口", "使用说明"];
+    const indexes = expected.map((heading) => headings.indexOf(heading));
+
+    expect(indexes.every((index) => index >= 0)).toBe(true);
+    expect(indexes).toEqual([...indexes].sort((a, b) => a - b));
+  });
+
+  it("renders a structured API table for a component", () => {
+    render(
+      <MemoryRouter>
+        <DesignSystemPage />
+      </MemoryRouter>
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Button" }));
+
+    expect(screen.getByText("prop")).toBeInTheDocument();
+    expect(screen.getByText("type")).toBeInTheDocument();
+    expect(screen.getByText("default")).toBeInTheDocument();
+    expect(screen.getByText("description")).toBeInTheDocument();
+  });
+
+  it("renders every sidebar-listed component with complete examples, api, and usage docs", () => {
+    render(
+      <MemoryRouter>
+        <DesignSystemPage />
+      </MemoryRouter>
+    );
+
+    for (const group of designSystemGroups) {
+      for (const component of group.components) {
+        fireEvent.click(screen.getByRole("button", { name: component.title }));
+
+        expect(screen.getByRole("heading", { name: component.title })).toBeInTheDocument();
+        expect(screen.getByRole("region", { name: "文档章节：真实示例" })).toBeInTheDocument();
+        expect(screen.getByRole("region", { name: "文档章节：使用说明" })).toBeInTheDocument();
+
+        const apiSection = screen.getByRole("region", { name: "文档章节：API 接口" });
+        expect(within(apiSection).getByText("prop")).toBeInTheDocument();
+        expect(within(apiSection).getByText("type")).toBeInTheDocument();
+        expect(within(apiSection).getByText("default")).toBeInTheDocument();
+        expect(within(apiSection).getByText("description")).toBeInTheDocument();
+
+        expect(component.api?.length ?? 0).toBeGreaterThan(0);
+        expect(component.docSections?.length ?? 0).toBeGreaterThan(0);
+      }
+    }
+  });
+
+  it("keeps Tag and Badge samples on the same display size", () => {
+    render(
+      <MemoryRouter>
+        <DesignSystemPage />
+      </MemoryRouter>
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Feedback" }));
+
+    for (const label of ["新版", "合规", "启用", "阻塞"]) {
+      expect(screen.getByText(label).closest("[data-size]")).toHaveAttribute("data-size", "md");
+    }
+  });
+
+  it("defaults to the first component detail instead of a group overview", () => {
+    render(
+      <MemoryRouter>
+        <DesignSystemPage />
+      </MemoryRouter>
+    );
+
+    expect(screen.getByRole("heading", { name: "Design tokens" })).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: /概览/i })).not.toBeInTheDocument();
+  });
+});
diff --git a/apps/web/src/test/shared-alert.test.tsx b/apps/web/src/test/shared-alert.test.tsx
new file mode 100644
index 0000000..eb946e1
--- /dev/null
+++ b/apps/web/src/test/shared-alert.test.tsx
@@ -0,0 +1,32 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { Alert } from "../shared/alert";
+
+describe("shared alert primitive", () => {
+  it("renders semantic tone, title, and body content", () => {
+    render(
+      <Alert title="邮件路由异常" variant="warning">
+        请检查上游 MX 记录是否仍然指向当前 worker。
+      </Alert>
+    );
+
+    const alert = screen.getByRole("alert");
+    expect(alert).toHaveClass("ui-alert", "ui-alert-warning");
+    expect(screen.getByText("邮件路由异常")).toBeInTheDocument();
+    expect(screen.getByText(/请检查上游 MX/i)).toBeInTheDocument();
+  });
+
+  it("supports dismiss actions without changing content semantics", () => {
+    const handleClose = vi.fn();
+
+    render(
+      <Alert dismissLabel="关闭提示" onClose={handleClose} title="已复制">
+        现在可以把 token 保存到密码管理器里。
+      </Alert>
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "关闭提示" }));
+    expect(handleClose).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/apps/web/src/test/shared-avatar.test.tsx b/apps/web/src/test/shared-avatar.test.tsx
new file mode 100644
index 0000000..acd11df
--- /dev/null
+++ b/apps/web/src/test/shared-avatar.test.tsx
@@ -0,0 +1,28 @@
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Avatar } from "../shared/avatar";
+
+describe("shared avatar primitive", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders an image avatar when src is available", () => {
+    render(<Avatar alt="Will Xue" size="lg" src="https://example.com/avatar.png" />);
+
+    const image = screen.getByRole("img", { name: "Will Xue" });
+    expect(image).toHaveAttribute("src", "https://example.com/avatar.png");
+    expect(image.closest(".ui-avatar")).toHaveClass("ui-avatar", "ui-avatar-lg");
+  });
+
+  it("falls back to initials when the image is missing or fails to load", () => {
+    render(<Avatar alt="Will Xue" name="Will Xue" src="https://example.com/avatar.png" />);
+
+    const image = screen.getByRole("img", { name: "Will Xue" });
+    fireEvent.error(image);
+
+    expect(screen.getByText("WX")).toBeInTheDocument();
+    expect(screen.getByTestId("avatar-fallback")).toHaveAttribute("aria-hidden", "true");
+  });
+});
diff --git a/apps/web/src/test/shared-badge.test.tsx b/apps/web/src/test/shared-badge.test.tsx
new file mode 100644
index 0000000..0b8033e
--- /dev/null
+++ b/apps/web/src/test/shared-badge.test.tsx
@@ -0,0 +1,32 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Badge } from "../shared/badge";
+
+describe("shared badge primitives", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders status badges with variant, appearance, and size hooks", () => {
+    render(
+      <>
+        <Badge data-testid="success-badge" appearance="soft" size="md" variant="success">
+          运行中
+        </Badge>
+        <Badge data-testid="warning-badge" appearance="solid" size="sm" statusRole="status" variant="warning">
+          待审核
+        </Badge>
+      </>
+    );
+
+    const successBadge = screen.getByTestId("success-badge");
+    expect(successBadge).toHaveClass("ui-badge", "ui-badge-success", "ui-badge-soft", "ui-badge-size-md");
+    expect(successBadge).toHaveAttribute("data-usage", "status");
+
+    const warningBadge = screen.getByTestId("warning-badge");
+    expect(warningBadge).toHaveClass("ui-badge", "ui-badge-warning", "ui-badge-solid", "ui-badge-size-sm");
+    expect(warningBadge).toHaveAttribute("role", "status");
+    expect(warningBadge).toHaveAttribute("aria-live", "polite");
+  });
+});
diff --git a/apps/web/src/test/shared-breadcrumb.test.tsx b/apps/web/src/test/shared-breadcrumb.test.tsx
new file mode 100644
index 0000000..5b8b81d
--- /dev/null
+++ b/apps/web/src/test/shared-breadcrumb.test.tsx
@@ -0,0 +1,45 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+  Breadcrumb,
+  BreadcrumbCurrent,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbSeparator
+} from "../shared/breadcrumb";
+
+describe("shared breadcrumb primitives", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders breadcrumb navigation with list semantics and current page state", () => {
+    render(
+      <Breadcrumb aria-label="当前路径">
+        <BreadcrumbList>
+          <BreadcrumbItem>
+            <BreadcrumbLink href="/workspace">工作台</BreadcrumbLink>
+          </BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbItem>
+            <BreadcrumbLink href="/workspace/inbox">收件箱</BreadcrumbLink>
+          </BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbItem>
+            <BreadcrumbCurrent>邮件详情</BreadcrumbCurrent>
+          </BreadcrumbItem>
+        </BreadcrumbList>
+      </Breadcrumb>
+    );
+
+    expect(screen.getByRole("navigation", { name: "当前路径" })).toHaveClass("ui-breadcrumb");
+    expect(screen.getByRole("list")).toHaveClass("ui-breadcrumb-list");
+    expect(screen.getByRole("link", { name: "工作台" })).toHaveAttribute("data-state", "inactive");
+    expect(screen.getByRole("link", { name: "收件箱" })).toHaveAttribute("data-state", "inactive");
+    expect(screen.getByText("邮件详情")).toHaveAttribute("aria-current", "page");
+    expect(screen.getByText("邮件详情")).toHaveAttribute("data-state", "current");
+    expect(screen.getAllByText("/")).toHaveLength(2);
+  });
+});
diff --git a/apps/web/src/test/shared-button.test.tsx b/apps/web/src/test/shared-button.test.tsx
index 4e7d5e3..67bfc0e 100644
--- a/apps/web/src/test/shared-button.test.tsx
+++ b/apps/web/src/test/shared-button.test.tsx
@@ -15,6 +15,9 @@ describe("shared button primitives", () => {
         <Button size="md" variant="primary">
           保存资料
         </Button>
+        <Button size="sm" variant="subtle">
+          稍后处理
+        </Button>
         <Button isActive size="xs" variant="ghost">
           仅看异常
         </Button>
@@ -25,6 +28,7 @@ describe("shared button primitives", () => {
     );
 
     expect(screen.getByRole("button", { name: "保存资料" })).toHaveClass("ui-button", "ui-button-primary", "ui-button-size-md");
+    expect(screen.getByRole("button", { name: "稍后处理" })).toHaveClass("ui-button", "ui-button-subtle", "ui-button-size-sm");
     expect(screen.getByRole("button", { name: "仅看异常" })).toHaveClass("ui-button", "ui-button-ghost", "is-active", "ui-button-size-xs");
     expect(screen.getByRole("button", { name: "关闭对话框" })).toHaveClass("ui-button", "ui-button-icon", "ui-button-icon-only", "ui-button-size-sm");
   });
diff --git a/apps/web/src/test/shared-card.test.tsx b/apps/web/src/test/shared-card.test.tsx
new file mode 100644
index 0000000..1d3e329
--- /dev/null
+++ b/apps/web/src/test/shared-card.test.tsx
@@ -0,0 +1,46 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Card, CardBody, CardFooter, CardHeader } from "../shared/card";
+
+describe("shared card primitives", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders card sections with shared variant, padding, elevation, and tone attributes", () => {
+    render(
+      <Card data-testid="card" elevation="md" padding="lg" tone="brand" variant="data">
+        <CardHeader>
+          <h2>今日收件</h2>
+        </CardHeader>
+        <CardBody>
+          <strong>1,284</strong>
+        </CardBody>
+        <CardFooter>较昨日 +12%</CardFooter>
+      </Card>
+    );
+
+    const card = screen.getByTestId("card");
+    expect(card).toHaveClass("ui-card", "ui-card-data", "ui-card-padding-lg", "ui-card-elevation-md", "ui-card-tone-brand");
+    expect(card).toHaveAttribute("data-variant", "data");
+    expect(card).toHaveAttribute("data-padding", "lg");
+    expect(card).toHaveAttribute("data-elevation", "md");
+    expect(card).toHaveAttribute("data-tone", "brand");
+    expect(screen.getByText("今日收件").closest(".ui-card-header")).toBeInTheDocument();
+    expect(screen.getByText("1,284").closest(".ui-card-body")).toBeInTheDocument();
+    expect(screen.getByText("较昨日 +12%").closest(".ui-card-footer")).toBeInTheDocument();
+  });
+
+  it("marks interactive cards with a dedicated state hook", () => {
+    render(
+      <Card data-testid="interactive-card" isInteractive variant="status">
+        账号状态
+      </Card>
+    );
+
+    const card = screen.getByTestId("interactive-card");
+    expect(card).toHaveClass("ui-card", "ui-card-status", "is-interactive");
+    expect(card).toHaveAttribute("data-state", "interactive");
+  });
+});
diff --git a/apps/web/src/test/shared-copy-button.test.tsx b/apps/web/src/test/shared-copy-button.test.tsx
new file mode 100644
index 0000000..a529e7e
--- /dev/null
+++ b/apps/web/src/test/shared-copy-button.test.tsx
@@ -0,0 +1,53 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { CopyButton } from "../shared/copy-button";
+
+describe("shared copy button primitive", () => {
+  const writeText = vi.fn();
+
+  beforeEach(() => {
+    vi.stubGlobal("navigator", {
+      ...window.navigator,
+      clipboard: { writeText }
+    });
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.unstubAllGlobals();
+    writeText.mockReset();
+  });
+
+  it("copies the provided value and announces copied state", async () => {
+    const user = userEvent.setup();
+    const handleCopy = vi.fn();
+    writeText.mockResolvedValue(undefined);
+
+    render(
+      <CopyButton copiedLabel="已复制" onCopy={handleCopy} value="wemail_live_secret">
+        复制密钥
+      </CopyButton>
+    );
+
+    const button = screen.getByRole("button", { name: "复制密钥" });
+    await user.click(button);
+
+    expect(handleCopy).toHaveBeenCalledWith("wemail_live_secret");
+    expect(screen.getByRole("button", { name: "已复制" })).toHaveAttribute("data-state", "copied");
+  });
+
+  it("honors the disabled state and does not attempt clipboard writes", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <CopyButton disabled value="wemail_live_secret">
+        复制密钥
+      </CopyButton>
+    );
+
+    await user.click(screen.getByRole("button", { name: "复制密钥" }));
+    expect(writeText).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/web/src/test/shared-divider.test.tsx b/apps/web/src/test/shared-divider.test.tsx
new file mode 100644
index 0000000..6f4e699
--- /dev/null
+++ b/apps/web/src/test/shared-divider.test.tsx
@@ -0,0 +1,35 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Divider } from "../shared/divider";
+
+describe("shared divider primitive", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders a horizontal separator by default", () => {
+    render(<Divider data-testid="divider" />);
+
+    const divider = screen.getByRole("separator");
+    expect(divider).toHaveClass("ui-divider", "ui-divider-horizontal");
+    expect(divider).toHaveAttribute("data-orientation", "horizontal");
+    expect(screen.getByTestId("divider")).toBe(divider);
+  });
+
+  it("renders vertical, inset, and dashed variants with the right semantics", () => {
+    render(<Divider dashed inset="lg" orientation="vertical" />);
+
+    const divider = screen.getByRole("separator");
+    expect(divider).toHaveClass("ui-divider-vertical", "ui-divider-dashed", "ui-divider-inset-lg");
+    expect(divider).toHaveAttribute("aria-orientation", "vertical");
+    expect(divider).toHaveAttribute("data-orientation", "vertical");
+  });
+
+  it("supports decorative separators without exposing an accessibility role", () => {
+    render(<Divider decorative data-testid="decorative-divider" />);
+
+    expect(screen.queryByRole("separator")).not.toBeInTheDocument();
+    expect(screen.getByTestId("decorative-divider")).toHaveAttribute("aria-hidden", "true");
+  });
+});
diff --git a/apps/web/src/test/shared-empty-state.test.tsx b/apps/web/src/test/shared-empty-state.test.tsx
new file mode 100644
index 0000000..1e98cad
--- /dev/null
+++ b/apps/web/src/test/shared-empty-state.test.tsx
@@ -0,0 +1,40 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { EmptyState } from "../shared/empty-state";
+
+describe("shared empty-state primitives", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders empty-state title, description, icon, and actions with labeled section semantics", () => {
+    render(
+      <EmptyState
+        actions={<button type="button">去创建邮箱</button>}
+        description="新建一个收件箱后，这里会展示最近的消息。"
+        icon={<span data-testid="empty-icon">0</span>}
+        title="暂无收件记录"
+      />
+    );
+
+    const section = screen.getByRole("region", { name: "暂无收件记录" });
+    expect(section).toHaveClass("ui-empty-state", "ui-empty-state-default");
+    expect(section).toHaveAttribute("data-variant", "default");
+    expect(section).toContainElement(screen.getByTestId("empty-icon"));
+    expect(screen.getByText("新建一个收件箱后，这里会展示最近的消息。")).toHaveClass("ui-empty-state-description");
+    expect(screen.getByRole("button", { name: "去创建邮箱" }).parentElement).toHaveClass("ui-empty-state-actions");
+  });
+
+  it("supports semantic variants for error and no-access cases", () => {
+    render(
+      <>
+        <EmptyState data-testid="error-state" title="加载失败" variant="error" />
+        <EmptyState data-testid="no-access-state" title="暂无权限" variant="no-access" />
+      </>
+    );
+
+    expect(screen.getByTestId("error-state")).toHaveClass("ui-empty-state", "ui-empty-state-error");
+    expect(screen.getByTestId("no-access-state")).toHaveClass("ui-empty-state", "ui-empty-state-no-access");
+  });
+});
diff --git a/apps/web/src/test/shared-filter-bar.test.tsx b/apps/web/src/test/shared-filter-bar.test.tsx
new file mode 100644
index 0000000..049381c
--- /dev/null
+++ b/apps/web/src/test/shared-filter-bar.test.tsx
@@ -0,0 +1,40 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { FilterBar, FilterBarActions, FilterBarSummary } from "../shared/filter-bar";
+
+describe("shared filter bar primitives", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders the grid with the requested column count", () => {
+    render(
+      <FilterBar columns={3}>
+        <label>
+          <span>搜索</span>
+          <input aria-label="搜索" />
+        </label>
+      </FilterBar>
+    );
+
+    expect(screen.getByLabelText("搜索").parentElement?.parentElement).toHaveClass(
+      "ui-filter-bar",
+      "ui-filter-bar-columns-3"
+    );
+  });
+
+  it("renders actions and summary wrappers", () => {
+    render(
+      <>
+        <FilterBarActions>
+          <button type="button">仅看异常</button>
+        </FilterBarActions>
+        <FilterBarSummary>共 12 条结果</FilterBarSummary>
+      </>
+    );
+
+    expect(screen.getByRole("button", { name: "仅看异常" }).parentElement).toHaveClass("ui-filter-bar-actions");
+    expect(screen.getByText("共 12 条结果")).toHaveClass("ui-filter-bar-summary");
+  });
+});
diff --git a/apps/web/src/test/shared-form.test.tsx b/apps/web/src/test/shared-form.test.tsx
index f3d4f8c..bbec817 100644
--- a/apps/web/src/test/shared-form.test.tsx
+++ b/apps/web/src/test/shared-form.test.tsx
@@ -1,8 +1,20 @@
-import { createRef } from "react";
+import { createRef, useState } from "react";
 import { fireEvent, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
 import { describe, expect, it, vi } from "vitest";
 
-import { CheckboxField, FormField, RadioGroupField, SelectInput, TextInput, TextareaInput } from "../shared/form";
+import {
+  Checkbox,
+  CheckboxField,
+  FormField,
+  MultiSelect,
+  Radio,
+  RadioGroupField,
+  SearchInput,
+  SelectInput,
+  TextInput,
+  TextareaInput
+} from "../shared/form";
 
 describe("shared form primitives", () => {
   it("associates FormField labels with wrapped controls", () => {
@@ -111,4 +123,147 @@ describe("shared form primitives", () => {
 
     expect(compact).toBeChecked();
   });
+
+  it("renders SearchInput with clear affordance in controlled mode", async () => {
+    const user = userEvent.setup();
+
+    function Host() {
+      const [value, setValue] = useState("ops");
+
+      return (
+        <SearchInput
+          aria-label="搜索邮箱"
+          onChange={(event) => setValue(event.target.value)}
+          value={value}
+        />
+      );
+    }
+
+    render(<Host />);
+
+    const input = screen.getByRole("searchbox", { name: "搜索邮箱" });
+    expect(input).toHaveValue("ops");
+    expect(input.closest(".ui-search-input")).toHaveAttribute("data-state", "has-value");
+
+    await user.click(screen.getByRole("button", { name: "清除搜索" }));
+
+    expect(input).toHaveValue("");
+    expect(screen.queryByRole("button", { name: "清除搜索" })).not.toBeInTheDocument();
+  });
+
+  it("supports standalone checkbox and radio primitives without changing field APIs", async () => {
+    const user = userEvent.setup();
+
+    function RadioHost() {
+      const [value, setValue] = useState("deliver");
+
+      return (
+        <>
+          <Checkbox defaultChecked description="把抄送地址一并搜索" label="包含抄送" />
+          <Radio
+            checked={value === "deliver"}
+            description="仅显示成功投递的记录"
+            label="仅投递成功"
+            name="delivery-state"
+            onChange={() => setValue("deliver")}
+            value="deliver"
+            variant="card"
+          />
+          <Radio
+            checked={value === "failed"}
+            label="仅投递失败"
+            name="delivery-state"
+            onChange={() => setValue("failed")}
+            value="failed"
+            variant="card"
+          />
+        </>
+      );
+    }
+
+    render(<RadioHost />);
+
+    const checkbox = screen.getByRole("checkbox", { name: "包含抄送" });
+    const failed = screen.getByRole("radio", { name: "仅投递失败" });
+
+    expect(checkbox).toBeChecked();
+    expect(screen.getByText("把抄送地址一并搜索")).toBeInTheDocument();
+    expect(failed.closest(".form-check")).toHaveAttribute("data-state", "unchecked");
+
+    await user.click(failed);
+
+    expect(failed).toBeChecked();
+    expect(failed.closest(".form-check")).toHaveAttribute("data-state", "checked");
+  });
+
+  it("supports uncontrolled multi-select interaction and keyboard toggling", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <MultiSelect
+        aria-label="选择通知渠道"
+        defaultValue={["email"]}
+        options={[
+          { label: "邮件", value: "email" },
+          { label: "Telegram", value: "telegram" },
+          { disabled: true, label: "Webhook", value: "webhook" }
+        ]}
+        placeholder="选择渠道"
+      />
+    );
+
+    const trigger = screen.getByRole("button", { name: /选择通知渠道/i });
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+    expect(trigger).toHaveTextContent("邮件");
+
+    await user.click(trigger);
+
+    const dialog = screen.getByRole("dialog", { name: "选择通知渠道" });
+    expect(dialog).toBeInTheDocument();
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+
+    const telegram = screen.getByRole("checkbox", { name: "Telegram" });
+    telegram.focus();
+    await user.keyboard(" ");
+
+    expect(telegram).toBeChecked();
+    expect(trigger).toHaveTextContent("邮件, Telegram");
+
+    const webhook = screen.getByRole("checkbox", { name: "Webhook" });
+    expect(webhook).toBeDisabled();
+
+    await user.keyboard("{Escape}");
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("supports controlled multi-select value updates", async () => {
+    const user = userEvent.setup();
+
+    function Host() {
+      const [value, setValue] = useState<string[]>(["read"]);
+
+      return (
+        <MultiSelect
+          aria-label="选择权限"
+          onValueChange={setValue}
+          options={[
+            { label: "读取", value: "read" },
+            { label: "写入", value: "write" },
+            { label: "删除", value: "delete" }
+          ]}
+          value={value}
+        />
+      );
+    }
+
+    render(<Host />);
+
+    const trigger = screen.getByRole("button", { name: /选择权限/i });
+    expect(trigger).toHaveTextContent("读取");
+
+    await user.click(trigger);
+    await user.click(screen.getByRole("checkbox", { name: "写入" }));
+
+    expect(trigger).toHaveTextContent("读取, 写入");
+  });
 });
diff --git a/apps/web/src/test/shared-icon.test.tsx b/apps/web/src/test/shared-icon.test.tsx
new file mode 100644
index 0000000..73b4f8f
--- /dev/null
+++ b/apps/web/src/test/shared-icon.test.tsx
@@ -0,0 +1,30 @@
+import { Mail, ShieldCheck } from "lucide-react";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { Icon } from "../shared/icon";
+
+describe("shared icon primitive", () => {
+  it("renders decorative icons hidden from assistive technology by default", () => {
+    render(<Icon data-testid="mail-icon" icon={Mail} size="sm" />);
+
+    const icon = screen.getByTestId("mail-icon");
+    expect(icon).toHaveClass("ui-icon", "ui-icon-sm");
+    expect(icon).toHaveAttribute("aria-hidden", "true");
+    expect(icon.querySelector("svg")).toBeInTheDocument();
+  });
+
+  it("renders accessible icons with a label and tone variant", () => {
+    render(<Icon icon={ShieldCheck} label="安全校验通过" size="lg" tone="success" />);
+
+    const icon = screen.getByRole("img", { name: "安全校验通过" });
+    expect(icon).toHaveClass("ui-icon", "ui-icon-lg", "ui-tone-success");
+    expect(icon).not.toHaveAttribute("aria-hidden");
+  });
+
+  it("supports numeric sizing while preserving the wrapper contract", () => {
+    render(<Icon data-testid="custom-size-icon" icon={Mail} size={18} />);
+
+    expect(screen.getByTestId("custom-size-icon")).toHaveStyle({ "--icon-size": "18px" });
+  });
+});
diff --git a/apps/web/src/test/shared-kv-list.test.tsx b/apps/web/src/test/shared-kv-list.test.tsx
new file mode 100644
index 0000000..397db94
--- /dev/null
+++ b/apps/web/src/test/shared-kv-list.test.tsx
@@ -0,0 +1,24 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { KVList } from "../shared/kv-list";
+
+describe("shared kv-list primitive", () => {
+  it("renders semantic description list content with density classes", () => {
+    render(
+      <KVList
+        density="compact"
+        items={[
+          { key: "区域", value: "Asia/Shanghai" },
+          { key: "保留时长", value: "24 小时" }
+        ]}
+      />
+    );
+
+    const list = screen.getByRole("list", { hidden: true });
+    expect(list.tagName).toBe("DL");
+    expect(list).toHaveClass("ui-kv-list", "ui-kv-list-compact");
+    expect(screen.getByText("区域")).toBeInTheDocument();
+    expect(screen.getByText("Asia/Shanghai")).toBeInTheDocument();
+  });
+});
diff --git a/apps/web/src/test/shared-metric-card.test.tsx b/apps/web/src/test/shared-metric-card.test.tsx
new file mode 100644
index 0000000..6f8bd2e
--- /dev/null
+++ b/apps/web/src/test/shared-metric-card.test.tsx
@@ -0,0 +1,22 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { MetricCard } from "../shared/metric-card";
+
+describe("shared metric card primitive", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders kicker, title, value, detail, and caption in a unified card", () => {
+    render(
+      <MetricCard caption="+12%" detail="较上周提升" kicker="KPI" title="活跃账号" tone="hero" value="128" />
+    );
+
+    expect(screen.getByText("KPI")).toHaveClass("panel-kicker");
+    expect(screen.getByRole("heading", { name: "活跃账号" })).toHaveClass("ui-metric-card-title");
+    expect(screen.getByText("128")).toHaveClass("ui-metric-card-value");
+    expect(screen.getByText("较上周提升")).toHaveClass("ui-metric-card-detail");
+    expect(screen.getByText("+12%")).toHaveClass("ui-metric-card-caption");
+  });
+});
diff --git a/apps/web/src/test/shared-overlay.test.tsx b/apps/web/src/test/shared-overlay.test.tsx
index 8c57ec7..b5871b8 100644
--- a/apps/web/src/test/shared-overlay.test.tsx
+++ b/apps/web/src/test/shared-overlay.test.tsx
@@ -1,9 +1,17 @@
-import { fireEvent, render, screen } from "@testing-library/react";
-import { describe, expect, it, vi } from "vitest";
+import { readFileSync } from "node:fs";
+
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { OverlayDialog, OverlayDrawer } from "../shared/overlay";
 
+const sharedStyles = readFileSync("src/shared/styles/index.css", "utf8");
+
 describe("shared overlay primitives", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
   it("renders a right drawer with unified shell classes and backdrop close behavior", () => {
     const onClose = vi.fn();
 
@@ -25,6 +33,7 @@ describe("shared overlay primitives", () => {
     expect(drawer).toHaveAttribute("aria-modal", "true");
     expect(screen.getByText("用户设置")).toHaveClass("ui-overlay-eyebrow");
     expect(screen.getByText("willxue@msn.com")).toHaveClass("ui-overlay-description");
+    expect(drawer).toHaveAttribute("aria-describedby", screen.getByText("willxue@msn.com").id);
 
     fireEvent.click(screen.getByTestId("overlay-backdrop"));
     expect(onClose).toHaveBeenCalledTimes(1);
@@ -44,7 +53,47 @@ describe("shared overlay primitives", () => {
 
     const dialog = screen.getByRole("dialog", { name: "确认彻底删除" });
     expect(dialog).toHaveClass("ui-overlay-panel", "ui-overlay-dialog", "panel");
+    expect(sharedStyles).toMatch(/\.ui-overlay-dialog\s*\{[^}]*border-radius:\s*32px;/);
     expect(screen.getByText("确认")).toBeInTheDocument();
     expect(screen.getByLabelText("关闭确认弹窗")).toHaveClass("ui-button-icon");
   });
+
+  it("closes on escape for keyboard users", () => {
+    const onClose = vi.fn();
+
+    render(
+      <OverlayDialog description="此操作不可恢复。" onClose={onClose} title="确认删除">
+        <p>确认后立即生效。</p>
+      </OverlayDialog>
+    );
+
+    fireEvent.keyDown(screen.getByRole("dialog", { name: "确认删除" }), { key: "Escape" });
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("traps focus inside the dialog and marks the background inert", () => {
+    render(
+      <div data-testid="page-shell">
+        <button type="button">外部操作</button>
+        <OverlayDialog footer={<button type="button">确认</button>} onClose={() => undefined} title="聚焦测试">
+          <button type="button">更多信息</button>
+        </OverlayDialog>
+      </div>
+    );
+
+    const dialog = screen.getByRole("dialog", { name: "聚焦测试" });
+    const pageShellContainer = screen.getByTestId("page-shell").parentElement;
+    const closeButton = screen.getByLabelText("关闭弹层");
+    const confirmButton = screen.getByRole("button", { name: "确认" });
+
+    expect(closeButton).toHaveFocus();
+    expect(pageShellContainer).toHaveAttribute("aria-hidden", "true");
+
+    fireEvent.keyDown(dialog, { key: "Tab", shiftKey: true });
+    expect(confirmButton).toHaveFocus();
+
+    fireEvent.keyDown(dialog, { key: "Tab" });
+    expect(closeButton).toHaveFocus();
+  });
 });
diff --git a/apps/web/src/test/shared-page-layout.test.tsx b/apps/web/src/test/shared-page-layout.test.tsx
new file mode 100644
index 0000000..b9eb3e4
--- /dev/null
+++ b/apps/web/src/test/shared-page-layout.test.tsx
@@ -0,0 +1,47 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Page, PageBody, PageHeader, PageMain, PageSidebar, PageToolbar } from "../shared/page-layout";
+
+describe("shared page layout primitives", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders page header content and actions", () => {
+    render(
+      <Page>
+        <PageHeader actions={<button type="button">新建</button>} description="统一页面头部" kicker="用户中心" title="用户目录" />
+      </Page>
+    );
+
+    expect(screen.getByText("用户中心")).toHaveClass("panel-kicker");
+    expect(screen.getByRole("heading", { name: "用户目录" })).toHaveClass("ui-page-header-title");
+    expect(screen.getByText("统一页面头部")).toHaveClass("ui-page-header-description");
+    expect(screen.getByRole("button", { name: "新建" })).toBeInTheDocument();
+  });
+
+  it("supports body layouts with main and sidebar regions", () => {
+    render(
+      <Page>
+        <PageBody hasSidebar>
+          <PageMain>主区域</PageMain>
+          <PageSidebar>侧栏</PageSidebar>
+        </PageBody>
+      </Page>
+    );
+
+    expect(screen.getByText("主区域")).toHaveClass("ui-page-main");
+    expect(screen.getByText("侧栏")).toHaveClass("ui-page-sidebar");
+  });
+
+  it("renders a toolbar wrapper for page-level actions", () => {
+    render(
+      <PageToolbar>
+        <button type="button">刷新</button>
+      </PageToolbar>
+    );
+
+    expect(screen.getByRole("button", { name: "刷新" }).parentElement).toHaveClass("ui-page-toolbar");
+  });
+});
diff --git a/apps/web/src/test/shared-pagination.test.tsx b/apps/web/src/test/shared-pagination.test.tsx
new file mode 100644
index 0000000..b043755
--- /dev/null
+++ b/apps/web/src/test/shared-pagination.test.tsx
@@ -0,0 +1,61 @@
+import userEvent from "@testing-library/user-event";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { useState } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { Pagination } from "../shared/pagination";
+
+describe("shared pagination primitive", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders pagination landmarks, current page state, and collapsed ranges", () => {
+    render(<Pagination page={10} pageSize={10} total={200} />);
+
+    expect(screen.getByRole("navigation", { name: "分页导航" })).toHaveClass("ui-pagination");
+    expect(screen.getByRole("button", { name: "第 10 页" })).toHaveAttribute("aria-current", "page");
+    expect(screen.getByRole("button", { name: "第 10 页" })).toHaveAttribute("data-state", "current");
+    expect(screen.getAllByText("…")).toHaveLength(2);
+    expect(screen.getByRole("button", { name: "上一页" })).toBeEnabled();
+    expect(screen.getByRole("button", { name: "下一页" })).toBeEnabled();
+  });
+
+  it("updates controlled page state and calls onChange with the next page", async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+
+    function Host() {
+      const [page, setPage] = useState(2);
+
+      return (
+        <Pagination
+          onChange={(nextPage) => {
+            handleChange(nextPage);
+            setPage(nextPage);
+          }}
+          page={page}
+          pageSize={20}
+          total={240}
+        />
+      );
+    }
+
+    render(<Host />);
+    await user.click(screen.getByRole("button", { name: "第 3 页" }));
+
+    expect(handleChange).toHaveBeenCalledWith(3);
+    expect(screen.getByRole("button", { name: "第 3 页" })).toHaveAttribute("aria-current", "page");
+    expect(screen.getByRole("button", { name: "第 2 页" })).toHaveAttribute("data-state", "inactive");
+  });
+
+  it("supports arrow key focus movement across pagination controls", () => {
+    render(<Pagination page={3} pageSize={10} total={120} />);
+
+    const currentPage = screen.getByRole("button", { name: "第 3 页" });
+    currentPage.focus();
+    fireEvent.keyDown(screen.getByRole("list"), { key: "ArrowRight" });
+
+    expect(screen.getByRole("button", { name: "第 4 页" })).toHaveFocus();
+  });
+});
diff --git a/apps/web/src/test/shared-popover.test.tsx b/apps/web/src/test/shared-popover.test.tsx
new file mode 100644
index 0000000..859cc9d
--- /dev/null
+++ b/apps/web/src/test/shared-popover.test.tsx
@@ -0,0 +1,94 @@
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Popover, PopoverContent, PopoverTrigger } from "../shared/popover";
+
+describe("shared popover primitives", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("opens from the trigger and wires expanded/controls semantics", () => {
+    render(
+      <Popover>
+        <PopoverTrigger>打开筛选器</PopoverTrigger>
+        <PopoverContent aria-label="筛选器">
+          <button type="button">保存筛选</button>
+        </PopoverContent>
+      </Popover>
+    );
+
+    const trigger = screen.getByRole("button", { name: "打开筛选器" });
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+
+    fireEvent.click(trigger);
+
+    const popover = screen.getByRole("dialog", { name: "筛选器" });
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+    expect(trigger).toHaveAttribute("aria-controls", popover.id);
+    expect(trigger).toHaveAttribute("data-state", "open");
+    expect(popover).toHaveAttribute("data-state", "open");
+    expect(screen.getByRole("button", { name: "保存筛选" })).toHaveFocus();
+  });
+
+  it("dismisses on escape and restores focus to the trigger", () => {
+    render(
+      <Popover>
+        <PopoverTrigger>打开快捷操作</PopoverTrigger>
+        <PopoverContent aria-label="快捷操作">
+          <button type="button">归档邮件</button>
+        </PopoverContent>
+      </Popover>
+    );
+
+    const trigger = screen.getByRole("button", { name: "打开快捷操作" });
+    fireEvent.click(trigger);
+
+    fireEvent.keyDown(screen.getByRole("dialog", { name: "快捷操作" }), { key: "Escape" });
+
+    expect(screen.queryByRole("dialog", { name: "快捷操作" })).not.toBeInTheDocument();
+    expect(trigger).toHaveFocus();
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("dismisses when clicking outside the content", () => {
+    render(
+      <div>
+        <button type="button">外部元素</button>
+        <Popover>
+          <PopoverTrigger>打开邮箱动作</PopoverTrigger>
+          <PopoverContent aria-label="邮箱动作">
+            <button type="button">复制地址</button>
+          </PopoverContent>
+        </Popover>
+      </div>
+    );
+
+    const trigger = screen.getByRole("button", { name: "打开邮箱动作" });
+    fireEvent.click(trigger);
+    expect(screen.getByRole("dialog", { name: "邮箱动作" })).toBeInTheDocument();
+
+    fireEvent.mouseDown(screen.getByRole("button", { name: "外部元素" }));
+    fireEvent.click(screen.getByRole("button", { name: "外部元素" }));
+
+    expect(screen.queryByRole("dialog", { name: "邮箱动作" })).not.toBeInTheDocument();
+    expect(trigger).toHaveFocus();
+  });
+
+  it("renders the popover content inside the shared layer portal", () => {
+    render(
+      <Popover defaultOpen>
+        <PopoverTrigger>打开筛选器</PopoverTrigger>
+        <PopoverContent aria-label="筛选器">
+          <button type="button">保存筛选</button>
+        </PopoverContent>
+      </Popover>
+    );
+
+    const portalRoot = document.getElementById("wemail-layer-root");
+    const popover = screen.getByRole("dialog", { name: "筛选器" });
+
+    expect(portalRoot).not.toBeNull();
+    expect(portalRoot?.contains(popover)).toBe(true);
+  });
+});
diff --git a/apps/web/src/test/shared-progress.test.tsx b/apps/web/src/test/shared-progress.test.tsx
new file mode 100644
index 0000000..8e6055d
--- /dev/null
+++ b/apps/web/src/test/shared-progress.test.tsx
@@ -0,0 +1,23 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { Progress } from "../shared/progress";
+
+describe("shared progress primitive", () => {
+  it("renders determinate progress with aria values and unified classes", () => {
+    render(<Progress aria-label="上传进度" showValueLabel value={32} variant="success" />);
+
+    const progress = screen.getByRole("progressbar", { name: "上传进度" });
+    expect(progress).toHaveClass("ui-progress", "ui-progress-success");
+    expect(progress).toHaveAttribute("aria-valuenow", "32");
+    expect(progress).toHaveTextContent("32%");
+  });
+
+  it("renders indeterminate progress without aria-valuenow", () => {
+    render(<Progress aria-label="同步中" indeterminate size="sm" />);
+
+    const progress = screen.getByRole("progressbar", { name: "同步中" });
+    expect(progress).toHaveAttribute("data-state", "indeterminate");
+    expect(progress).not.toHaveAttribute("aria-valuenow");
+  });
+});
diff --git a/apps/web/src/test/shared-scroll-area.test.tsx b/apps/web/src/test/shared-scroll-area.test.tsx
new file mode 100644
index 0000000..41caa2a
--- /dev/null
+++ b/apps/web/src/test/shared-scroll-area.test.tsx
@@ -0,0 +1,37 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+  ScrollArea,
+  ScrollAreaScrollbar,
+  ScrollAreaThumb,
+  ScrollAreaViewport
+} from "../shared/scroll-area";
+
+describe("shared scroll area primitives", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders a labeled scroll region with viewport and scrollbar parts", () => {
+    render(
+      <ScrollArea aria-label="邮件列表">
+        <ScrollAreaViewport>
+          <div style={{ height: 400 }}>很多邮件</div>
+        </ScrollAreaViewport>
+        <ScrollAreaScrollbar orientation="vertical">
+          <ScrollAreaThumb />
+        </ScrollAreaScrollbar>
+      </ScrollArea>
+    );
+
+    const region = screen.getByRole("region", { name: "邮件列表" });
+    expect(region).toHaveClass("ui-scroll-area");
+    expect(region).toHaveAttribute("data-orientation", "vertical");
+    expect(region.querySelector(".ui-scroll-area-viewport")).toBeInTheDocument();
+
+    const scrollbar = region.querySelector(".ui-scroll-area-scrollbar");
+    expect(scrollbar).toHaveAttribute("data-orientation", "vertical");
+    expect(scrollbar?.querySelector(".ui-scroll-area-thumb")).toBeInTheDocument();
+  });
+});
diff --git a/apps/web/src/test/shared-skeleton.test.tsx b/apps/web/src/test/shared-skeleton.test.tsx
new file mode 100644
index 0000000..83e5f4f
--- /dev/null
+++ b/apps/web/src/test/shared-skeleton.test.tsx
@@ -0,0 +1,32 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { Skeleton } from "../shared/skeleton";
+
+describe("shared skeleton primitive", () => {
+  it("renders a decorative rectangular skeleton by default", () => {
+    render(<Skeleton data-testid="skeleton" />);
+
+    const skeleton = screen.getByTestId("skeleton");
+    expect(skeleton).toHaveClass("ui-skeleton", "ui-skeleton-rect");
+    expect(skeleton).toHaveAttribute("aria-hidden", "true");
+    expect(skeleton).toHaveAttribute("data-state", "idle");
+  });
+
+  it("supports animated text skeletons with custom sizing", () => {
+    render(<Skeleton animated data-testid="text-skeleton" height={12} shape="text" width="72%" />);
+
+    const skeleton = screen.getByTestId("text-skeleton");
+    expect(skeleton).toHaveClass("ui-skeleton-text", "ui-skeleton-animated");
+    expect(skeleton).toHaveAttribute("data-state", "loading");
+    expect(skeleton).toHaveStyle({ height: "12px", width: "72%" });
+  });
+
+  it("can expose loading status semantics with Chinese default copy", () => {
+    render(<Skeleton announce shape="circle" />);
+
+    const skeleton = screen.getByRole("status", { name: "内容加载中" });
+    expect(skeleton).toHaveClass("ui-skeleton", "ui-skeleton-circle");
+    expect(skeleton).toHaveAttribute("data-shape", "circle");
+  });
+});
diff --git a/apps/web/src/test/shared-spinner.test.tsx b/apps/web/src/test/shared-spinner.test.tsx
new file mode 100644
index 0000000..8306b80
--- /dev/null
+++ b/apps/web/src/test/shared-spinner.test.tsx
@@ -0,0 +1,34 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Spinner } from "../shared/spinner";
+
+describe("shared spinner primitive", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders an indeterminate status spinner with Chinese default copy", () => {
+    render(<Spinner />);
+
+    const spinner = screen.getByRole("status", { name: "加载中" });
+    expect(spinner).toHaveClass("ui-spinner", "ui-spinner-md", "ui-tone-default");
+    expect(spinner).toHaveAttribute("data-state", "indeterminate");
+  });
+
+  it("supports decorative spinners that stay hidden from assistive technology", () => {
+    render(<Spinner data-testid="decorative-spinner" decorative size="sm" tone="accent" />);
+
+    expect(screen.queryByRole("status")).not.toBeInTheDocument();
+    expect(screen.getByTestId("decorative-spinner")).toHaveAttribute("aria-hidden", "true");
+    expect(screen.getByTestId("decorative-spinner")).toHaveClass("ui-spinner-sm", "ui-tone-accent");
+  });
+
+  it("can show visible loading copy with an overridable label", () => {
+    render(<Spinner label="同步中" showLabel size="lg" tone="muted" />);
+
+    const spinner = screen.getByRole("status", { name: "同步中" });
+    expect(spinner).toHaveClass("ui-spinner-lg", "ui-tone-muted");
+    expect(screen.getByText("同步中")).toHaveClass("ui-spinner-label");
+  });
+});
diff --git a/apps/web/src/test/shared-steps.test.tsx b/apps/web/src/test/shared-steps.test.tsx
new file mode 100644
index 0000000..23ee82e
--- /dev/null
+++ b/apps/web/src/test/shared-steps.test.tsx
@@ -0,0 +1,82 @@
+import userEvent from "@testing-library/user-event";
+import { cleanup, render, screen } from "@testing-library/react";
+import { useState } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { StepItem, Steps, StepsList } from "../shared/steps";
+
+describe("shared steps primitives", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders current, complete, and upcoming step states with accessible navigation semantics", () => {
+    render(
+      <Steps aria-label="集成流程" currentStep={2}>
+        <StepsList>
+          <StepItem step={1} title="绑定域名" />
+          <StepItem step={2} title="验证 DNS" />
+          <StepItem step={3} title="接收邮件" />
+        </StepsList>
+      </Steps>
+    );
+
+    expect(screen.getByRole("navigation", { name: "集成流程" })).toHaveClass("ui-steps");
+    expect(screen.getByRole("list")).toHaveClass("ui-steps-list");
+    expect(screen.getByText("绑定域名").closest("li")).toHaveAttribute("data-state", "complete");
+    expect(screen.getByRole("button", { name: "验证 DNS" })).toHaveAttribute("aria-current", "step");
+    expect(screen.getByRole("button", { name: "验证 DNS" })).toHaveAttribute("data-state", "current");
+    expect(screen.getByText("接收邮件").closest("li")).toHaveAttribute("data-state", "upcoming");
+  });
+
+  it("updates controlled currentStep when a new step is activated", async () => {
+    const user = userEvent.setup();
+
+    function Host() {
+      const [currentStep, setCurrentStep] = useState(1);
+
+      return (
+        <Steps aria-label="注册流程" currentStep={currentStep} onStepChange={setCurrentStep}>
+          <StepsList>
+            <StepItem step={1} title="填写账号" />
+            <StepItem step={2} title="验证邮箱" />
+            <StepItem step={3} title="完成注册" />
+          </StepsList>
+        </Steps>
+      );
+    }
+
+    render(<Host />);
+    await user.click(screen.getByRole("button", { name: "验证邮箱" }));
+
+    expect(screen.getByRole("button", { name: "验证邮箱" })).toHaveAttribute("aria-current", "step");
+    expect(screen.getByRole("button", { name: "填写账号" })).toHaveAttribute("data-state", "complete");
+  });
+
+  it("supports keyboard focus movement and activation across interactive steps", async () => {
+    const user = userEvent.setup();
+
+    function Host() {
+      const [currentStep, setCurrentStep] = useState(1);
+
+      return (
+        <Steps aria-label="发布流程" currentStep={currentStep} onStepChange={setCurrentStep}>
+          <StepsList>
+            <StepItem step={1} title="编写内容" />
+            <StepItem step={2} title="审核" />
+            <StepItem step={3} title="发布" />
+          </StepsList>
+        </Steps>
+      );
+    }
+
+    render(<Host />);
+    screen.getByRole("button", { name: "编写内容" }).focus();
+
+    await user.keyboard("{ArrowRight}");
+    expect(screen.getByRole("button", { name: "审核" })).toHaveFocus();
+
+    await user.keyboard("{Enter}");
+    expect(screen.getByRole("button", { name: "审核" })).toHaveAttribute("aria-current", "step");
+  });
+});
diff --git a/apps/web/src/test/shared-tabs.test.tsx b/apps/web/src/test/shared-tabs.test.tsx
new file mode 100644
index 0000000..760bb4e
--- /dev/null
+++ b/apps/web/src/test/shared-tabs.test.tsx
@@ -0,0 +1,90 @@
+import userEvent from "@testing-library/user-event";
+import { cleanup, render, screen } from "@testing-library/react";
+import { useState } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Tabs, TabsList, TabsPanel, TabsTrigger } from "../shared/tabs";
+
+describe("shared tabs primitives", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders segmented tabs with correct tab and tabpanel relationships", () => {
+    render(
+      <Tabs defaultValue="overview">
+        <TabsList aria-label="邮箱详情">
+          <TabsTrigger value="overview">概览</TabsTrigger>
+          <TabsTrigger value="activity">活动</TabsTrigger>
+        </TabsList>
+        <TabsPanel value="overview">概览内容</TabsPanel>
+        <TabsPanel value="activity">活动内容</TabsPanel>
+      </Tabs>
+    );
+
+    const overviewTab = screen.getByRole("tab", { name: "概览" });
+    const activityTab = screen.getByRole("tab", { name: "活动" });
+    const overviewPanel = screen.getByRole("tabpanel", { name: "概览" });
+
+    expect(screen.getByRole("tablist", { name: "邮箱详情" })).toHaveAttribute("data-variant", "segmented");
+    expect(overviewTab).toHaveAttribute("aria-selected", "true");
+    expect(overviewTab).toHaveAttribute("data-state", "active");
+    expect(activityTab).toHaveAttribute("aria-selected", "false");
+    expect(activityTab).toHaveAttribute("tabindex", "-1");
+    expect(overviewPanel).toBeVisible();
+    expect(screen.getByText("活动内容")).toHaveAttribute("hidden");
+  });
+
+  it("updates controlled state when a trigger is activated", async () => {
+    const user = userEvent.setup();
+
+    function Host() {
+      const [value, setValue] = useState("overview");
+
+      return (
+        <Tabs onValueChange={setValue} value={value}>
+          <TabsList aria-label="消息分组">
+            <TabsTrigger value="overview">概览</TabsTrigger>
+            <TabsTrigger value="activity">活动</TabsTrigger>
+          </TabsList>
+          <TabsPanel value="overview">概览内容</TabsPanel>
+          <TabsPanel value="activity">活动内容</TabsPanel>
+        </Tabs>
+      );
+    }
+
+    render(<Host />);
+    await user.click(screen.getByRole("tab", { name: "活动" }));
+
+    expect(screen.getByRole("tab", { name: "活动" })).toHaveAttribute("aria-selected", "true");
+    expect(screen.getByRole("tabpanel", { name: "活动" })).toBeVisible();
+  });
+
+  it("supports roving keyboard navigation in automatic activation mode", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Tabs defaultValue="overview">
+        <TabsList aria-label="消息分组">
+          <TabsTrigger value="overview">概览</TabsTrigger>
+          <TabsTrigger value="activity">活动</TabsTrigger>
+          <TabsTrigger value="settings">设置</TabsTrigger>
+        </TabsList>
+        <TabsPanel value="overview">概览内容</TabsPanel>
+        <TabsPanel value="activity">活动内容</TabsPanel>
+        <TabsPanel value="settings">设置内容</TabsPanel>
+      </Tabs>
+    );
+
+    screen.getByRole("tab", { name: "概览" }).focus();
+    await user.keyboard("{ArrowRight}");
+
+    expect(screen.getByRole("tab", { name: "活动" })).toHaveFocus();
+    expect(screen.getByRole("tab", { name: "活动" })).toHaveAttribute("aria-selected", "true");
+
+    await user.keyboard("{End}");
+
+    expect(screen.getByRole("tab", { name: "设置" })).toHaveFocus();
+    expect(screen.getByRole("tabpanel", { name: "设置" })).toBeVisible();
+  });
+});
diff --git a/apps/web/src/test/shared-tag.test.tsx b/apps/web/src/test/shared-tag.test.tsx
new file mode 100644
index 0000000..5aef163
--- /dev/null
+++ b/apps/web/src/test/shared-tag.test.tsx
@@ -0,0 +1,32 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Tag } from "../shared/tag";
+
+describe("shared tag primitives", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders category tags with tone, size, shape, and optional dot/icon affordances", () => {
+    render(
+      <>
+        <Tag data-testid="brand-tag" dot shape="pill" size="md" variant="brand">
+          品牌模板
+        </Tag>
+        <Tag data-testid="info-tag" icon={<span data-testid="tag-icon">#</span>} shape="rounded" size="sm" variant="info">
+          API
+        </Tag>
+      </>
+    );
+
+    const brandTag = screen.getByTestId("brand-tag");
+    expect(brandTag).toHaveClass("ui-tag", "ui-tag-brand", "ui-tag-size-md", "ui-tag-shape-pill");
+    expect(brandTag).toHaveAttribute("data-usage", "category");
+    expect(brandTag.querySelector(".ui-tag-dot")).toBeInTheDocument();
+
+    const infoTag = screen.getByTestId("info-tag");
+    expect(infoTag).toHaveClass("ui-tag", "ui-tag-info", "ui-tag-size-sm", "ui-tag-shape-rounded");
+    expect(screen.getByTestId("tag-icon")).toBeInTheDocument();
+  });
+});
diff --git a/apps/web/src/test/shared-tooltip.test.tsx b/apps/web/src/test/shared-tooltip.test.tsx
new file mode 100644
index 0000000..9fbf391
--- /dev/null
+++ b/apps/web/src/test/shared-tooltip.test.tsx
@@ -0,0 +1,69 @@
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Tooltip, TooltipContent, TooltipTrigger } from "../shared/tooltip";
+
+describe("shared tooltip primitives", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("opens on focus and links the trigger to the tooltip content", () => {
+    render(
+      <Tooltip>
+        <TooltipTrigger>邮箱地址</TooltipTrigger>
+        <TooltipContent>复制后可分享给同事</TooltipContent>
+      </Tooltip>
+    );
+
+    const trigger = screen.getByRole("button", { name: "邮箱地址" });
+    expect(screen.queryByRole("tooltip")).not.toBeInTheDocument();
+
+    fireEvent.focus(trigger);
+
+    const tooltip = screen.getByRole("tooltip");
+    expect(trigger).toHaveAttribute("aria-describedby", tooltip.id);
+    expect(trigger).toHaveAttribute("data-state", "open");
+    expect(tooltip).toHaveAttribute("data-state", "open");
+  });
+
+  it("closes on escape and blur", () => {
+    render(
+      <Tooltip>
+        <TooltipTrigger>查看说明</TooltipTrigger>
+        <TooltipContent>最多保留 7 天</TooltipContent>
+      </Tooltip>
+    );
+
+    const trigger = screen.getByRole("button", { name: "查看说明" });
+
+    fireEvent.focus(trigger);
+    expect(screen.getByRole("tooltip")).toBeInTheDocument();
+
+    fireEvent.keyDown(trigger, { key: "Escape" });
+    expect(screen.queryByRole("tooltip")).not.toBeInTheDocument();
+    expect(trigger).toHaveAttribute("data-state", "closed");
+
+    fireEvent.focus(trigger);
+    expect(screen.getByRole("tooltip")).toBeInTheDocument();
+
+    fireEvent.blur(trigger);
+    expect(screen.queryByRole("tooltip")).not.toBeInTheDocument();
+    expect(trigger).not.toHaveAttribute("aria-describedby");
+  });
+
+  it("renders tooltip content inside the shared layer portal", () => {
+    render(
+      <Tooltip defaultOpen>
+        <TooltipTrigger>查看说明</TooltipTrigger>
+        <TooltipContent>最多保留 7 天</TooltipContent>
+      </Tooltip>
+    );
+
+    const portalRoot = document.getElementById("wemail-layer-root");
+    const tooltip = screen.getByRole("tooltip");
+
+    expect(portalRoot).not.toBeNull();
+    expect(portalRoot?.contains(tooltip)).toBe(true);
+  });
+});
diff --git a/apps/web/src/test/shared-typography.test.tsx b/apps/web/src/test/shared-typography.test.tsx
new file mode 100644
index 0000000..068d840
--- /dev/null
+++ b/apps/web/src/test/shared-typography.test.tsx
@@ -0,0 +1,49 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { Code, Heading, Kbd, Label, Muted, Text } from "../shared/typography";
+
+describe("shared typography primitives", () => {
+  it("renders semantic heading tags with size and tone variants", () => {
+    render(
+      <Heading as="h1" size="display-md" tone="accent">
+        收件箱总览
+      </Heading>
+    );
+
+    const heading = screen.getByRole("heading", { level: 1, name: "收件箱总览" });
+    expect(heading.tagName).toBe("H1");
+    expect(heading).toHaveClass("ui-heading", "ui-heading-display-md", "ui-tone-accent");
+  });
+
+  it("renders text and muted copy with shared typography classes", () => {
+    render(
+      <>
+        <Text as="span" size="lg">
+          共 12 封邮件
+        </Text>
+        <Muted>最近 24 小时自动刷新</Muted>
+      </>
+    );
+
+    expect(screen.getByText("共 12 封邮件")).toHaveClass("ui-text", "ui-text-lg");
+    expect(screen.getByText("最近 24 小时自动刷新")).toHaveClass("ui-text", "ui-text-muted");
+  });
+
+  it("renders label, code, and kbd with their native semantics", () => {
+    render(
+      <div>
+        <Label htmlFor="mailbox-search">搜索邮箱</Label>
+        <input id="mailbox-search" />
+        <Code tone="success">mailbox_id</Code>
+        <Kbd keys={["Cmd", "K"]} />
+      </div>
+    );
+
+    expect(screen.getByText("搜索邮箱").tagName).toBe("LABEL");
+    expect(screen.getByLabelText("搜索邮箱")).toHaveAttribute("id", "mailbox-search");
+    expect(screen.getByText("mailbox_id")).toHaveClass("ui-code", "ui-tone-success");
+    expect(screen.getByText("Cmd")).toHaveClass("ui-kbd-key");
+    expect(screen.getByText("K")).toHaveClass("ui-kbd-key");
+  });
+});
diff --git a/apps/web/src/test/users-list-page.test.tsx b/apps/web/src/test/users-list-page.test.tsx
index 9e2cac4..b71f550 100644
--- a/apps/web/src/test/users-list-page.test.tsx
+++ b/apps/web/src/test/users-list-page.test.tsx
@@ -50,9 +50,9 @@ describe("UsersListPage", () => {
     expect(screen.getByRole("columnheader", { name: "角色" })).toBeInTheDocument();
     expect(screen.getByRole("columnheader", { name: "操作" })).toHaveClass("ui-table-sticky-end");
     expect(screen.getByRole("checkbox", { name: "选择全部用户" }).closest("th")).toHaveClass("ui-table-sticky-start");
-    expect(screen.getAllByText("正常").find((element) => element.classList.contains("accounts-status-pill"))).toHaveClass(
-      "accounts-status-pill",
-      "accounts-status-pill--enabled"
+    expect(screen.getAllByText("正常").find((element) => element.classList.contains("ui-badge"))).toHaveClass(
+      "ui-badge",
+      "ui-badge-success"
     );
     expect(screen.getByLabelText("搜索用户")).toBeInTheDocument();
     expect(screen.getByLabelText("角色筛选")).toBeInTheDocument();
diff --git a/docs/design-system/CHANGELOG.md b/docs/design-system/CHANGELOG.md
index b44a371..ce4fb1b 100644
--- a/docs/design-system/CHANGELOG.md
+++ b/docs/design-system/CHANGELOG.md
@@ -4,6 +4,50 @@
 
 ## [Unreleased]
 
+### Added — Public Preview & Layer Hardening (2026-04-23)
+
+- `apps/web/src/shared/overlay/layer-utils.ts` — 抽出 shared layer 能力：portal root、focusable 查询、overlay inert 管理、基础 floating 定位
+- `apps/web/src/test/shared-overlay.test.tsx` — 新增 focus trap / 背景 inert 回归
+- `apps/web/src/test/shared-popover.test.tsx` — 新增 portal 渲染回归
+- `apps/web/src/test/shared-tooltip.test.tsx` — 新增 portal 渲染回归
+- `apps/web/src/test/app.test.tsx` — 新增公开 `/design-system` 路由与首页入口回归
+
+### Changed
+
+- `apps/web/src/app/App.tsx` — `/design-system` 提前从应用壳层分流，变为公开独立页面
+- `apps/web/src/app/AppRoutes.tsx` — 移除后台工作台中的 `/design-system` 路由注册
+- `apps/web/src/features/landing/WemailLandingPage.tsx` — 首页顶部与移动菜单新增 `设计系统` 链接
+- `apps/web/src/pages/DesignSystemPage.tsx` — 补齐公开页头、主题切换、真实预览卡片与 live overlay demo，逐步替换 placeholder 区块
+- `apps/web/src/features/accounts/AccountsListPage.tsx`、`apps/web/src/pages/UsersListPage.tsx` — 接入 `PageLayout` 与 `FilterBar`，开始把重复页面结构收敛进 shared 原语
+- `apps/web/src/shared/overlay/OverlayPrimitives.tsx` — Overlay 改为 portal 渲染，支持 focus trap、背景 inert、body scroll lock、焦点归还
+- `apps/web/src/shared/popover/PopoverPrimitives.tsx` — Popover 改为 shared layer portal，并加入基础定位与碰撞回退
+- `apps/web/src/shared/tooltip/TooltipPrimitives.tsx` — Tooltip 改为 shared layer portal，并加入基础定位与 side 回退
+
+### Added — Page Layout & Filter Bar (2026-04-23)
+
+- `apps/web/src/shared/page-layout/*` — 新增页面级布局原语：`Page`、`PageHeader`、`PageToolbar`、`PageBody`、`PageMain`、`PageSidebar`
+- `apps/web/src/shared/filter-bar/*` — 新增筛选条原语：`FilterBar`、`FilterBarActions`、`FilterBarSummary`
+- `apps/web/src/shared/metric-card/*` — 新增统计卡原语：`MetricCard`
+- `apps/web/src/test/shared-page-layout.test.tsx` — 锁定页面级布局结构
+- `apps/web/src/test/shared-filter-bar.test.tsx` — 锁定筛选条布局与摘要区域
+- `apps/web/src/test/shared-metric-card.test.tsx` — 锁定统计卡结构
+
+### Added — Sprint 7 Preview & Docs (2026-04-23)
+
+- `apps/web/src/pages/DesignSystemPage.tsx` — 重构为 13 分区预览工作面，固定 section id、页内导航、回归检查点与“等待注入真实示例”槽位
+- `apps/web/src/test/design-system-page.test.tsx` — 锁定 13 分区结构、导航锚点和占位契约
+- `apps/web/e2e/design-system.spec.ts` — 新增 `/design-system` 专用 Playwright 用例，覆盖结构断言与 light/dark 视觉回归脚手架
+- `docs/design-system/README.md` — 新增 13 类分区映射、后续注入约定与视觉回归说明
+
+### Changed
+
+- `docs/design-system/CHANGELOG.md` — 开始记录 S7 预览与文档工作面变更
+- `apps/web/e2e/README.md` — 补充 design-system 专用 e2e/视觉回归说明
+
+### Fixed
+
+- 统一 `/design-system` 作为 design system 预览页路径，不再为后续文档和回归流程保留 `/_design` 旧命名
+
 ### Added — Sprint 1 Foundation (2026-04-22)
 
 - `apps/web/src/shared/styles/tokens.css` — 新增 token 层
@@ -18,19 +62,21 @@
   - 层级 `--z-base … --z-tooltip` 共 10 档
   - 焦点环 `--focus-ring-width/offset/color/ring`
   - 图表色板 `--chart-series-1 … 8`
-- `apps/web/src/shared/styles/primitives.css` — 空 barrel,供 S2-S6 component 追加自己的 `@import`
-- `apps/web/src/shared/styles/index.css` — 顶部新增 `@import "./tokens.css"; @import "./primitives.css";`;旧内容全部保留
-- `apps/web/src/test/utils/renderWithTheme.ts` — 基于 `@testing-library/react` 的 `render` 包装,挂 `data-theme`,支持运行时切换
-- `apps/web/src/test/utils/pressKey.ts` — 键盘按键测试辅助,封装 `keyDown + keyUp`
+- `apps/web/src/shared/styles/primitives.css` — 空 barrel，供 S2-S6 component 追加自己的 `@import`
+- `apps/web/src/shared/styles/index.css` — 顶部新增 `@import "./tokens.css"; @import "./primitives.css";`；旧内容全部保留
+- `apps/web/src/test/utils/renderWithTheme.ts` — 基于 `@testing-library/react` 的 `render` 包装，挂 `data-theme`，支持运行时切换
+- `apps/web/src/test/utils/pressKey.ts` — 键盘按键测试辅助，封装 `keyDown + keyUp`
 - `apps/web/src/test/utils/index.ts` — 桶式导出
-- `apps/web/src/pages/DesignSystemPage.tsx` — 路由 `/design-system`,展示 token 与原语的可视预览骨架
-- `apps/web/src/app/AppRoutes.tsx` — 注册 `/design-system` 路由
+- `apps/web/src/pages/DesignSystemPage.tsx` — 路由 `/design-system`，展示 token 与原语的可视预览骨架
+- `apps/web/src/app/AppRoutes.tsx` — 注册 `/design-system` 路由（后续已提升为公开独立页面）
 - `docs/design-system/README.md` — 索引与 token 速查表
 
 ### Changed
-- (无 — S1 为 additive 落地,不破坏既有样式)
+
+- (无 — S1 为 additive 落地，不破坏既有样式)
 
 ### Removed
+
 - (无)
 
 ---
diff --git a/docs/design-system/README.md b/docs/design-system/README.md
index 068cda7..c083cbe 100644
--- a/docs/design-system/README.md
+++ b/docs/design-system/README.md
@@ -2,10 +2,48 @@
 
 参考 [`docs/plans/2026-04-22-design-system-v1.md`](../plans/2026-04-22-design-system-v1.md) 了解整体方案、实施节奏与验收清单。
 
+## 当前状态
+
+- 预览路由固定为 `/design-system`，不再使用 `/_design`
+- `/design-system` 为公开独立页面，不依赖登录，也不挂在后台工作台壳层里
+- 未登录首页顶部提供 `设计系统` 入口，方便直接预览与对照
+- 13 个分区已具备真实原语示例、公共页头、主题切换和 live overlay demo
+- Playwright 已锁定公开 `/design-system` 的结构性回归，light/dark 截图仍按环境变量开关保护
+
 ## 范围
 
 - 仅 Web 端（`apps/web`），暂不覆盖移动端与邮件模板
-- 附加式（additive）落地：不改动既有 CSS 变量与选择器,新 token 与原语独立存在；业务页在各自节奏下迁移
+- 附加式（additive）落地：保留既有 CSS 变量兼容层，并把新增 token、原语和 page-level showcase 统一收敛到 shared 层
+- 现阶段重点是把 Web 端原语、公共预览和基础交互能力补齐；移动端、邮件模板和更高级的浮层定位仍在后续演进范围
+
+## 13 类预览分区
+
+`apps/web/src/pages/DesignSystemPage.tsx` 现在以稳定英文 section id 组织公开预览页。后续新增真实示例时，优先在现有分区内扩展示例，不要重排结构或另起平行入口。
+
+| Section id | 页面标题 | 承接内容 | 主要来源 Sprint |
+|---|---|---|---|
+| `foundations` | `Foundations` | 设计原则、发布节奏、锚点契约、回归入口 | S1 / S7 |
+| `color-theme` | `Color & Theme` | 品牌色、语义色、主题差异 | S1 |
+| `layout-spacing` | `Layout & Spacing` | 页面布局、容器节奏、间距尺度 | S1 |
+| `elevation-radius` | `Elevation & Radius` | 阴影、圆角、表面层级 | S1 |
+| `typography-content` | `Typography & Content` | Typography、Divider、Icon、Spinner、Skeleton | S2 |
+| `buttons-actions` | `Buttons & Actions` | Button 体系、动作矩阵、CopyButton | S2 / S5 |
+| `form-inputs` | `Form Inputs` | TextInput、Select、Textarea、SearchInput、MultiSelect | S5 |
+| `selection-controls` | `Selection Controls` | Switch、Checkbox、Radio、字段组选项 | S5 |
+| `navigation-wayfinding` | `Navigation & Wayfinding` | Breadcrumb、Pagination、Tabs、Steps | S4 |
+| `surfaces-cards` | `Surfaces & Cards` | Card、容器组合、EmptyState | S3 |
+| `data-display` | `Data Display & Charts` | Table、Chart、KVList、Avatar | S1 / S5 |
+| `feedback-status` | `Feedback & Status` | Tag、Badge、Progress、Alert、Spinner、Skeleton | S3 / S5 / S6 |
+| `overlays-utilities` | `Overlays & Utilities` | Overlay、Tooltip、Popover、ScrollArea、工具型原语 | S6 |
+
+## 预览页维护约定
+
+后续继续扩 `/design-system` 时遵守下面几条：
+
+1. 保持 13 个 section id 不变，Playwright 和文档都会引用这些锚点。
+2. 优先在现有 section 的 preview 区内扩真实示例，不要新增一整套平行布局。
+3. 每个分区都至少保留三类信息：覆盖范围、回归检查点、真实示例或占位。
+4. 新增原语示例后，同步更新本 README 的对应分区说明和 [`CHANGELOG.md`](./CHANGELOG.md)。
 
 ## Token 快速索引
 
@@ -13,9 +51,9 @@
 
 | 类别 | 变量前缀 | 说明 |
 |---|---|---|
-| 品牌 | `--brand-50 … --brand-700`、`--brand-soft-500` | 主色梯度,`--brand-500` 与旧 `--accent` 等值 |
+| 品牌 | `--brand-50 … --brand-700`、`--brand-soft-500` | 主色梯度，`--brand-500` 与旧 `--accent` 等值 |
 | 语义 | `--success-*`、`--warning-*`、`--danger-*`、`--info-*` | 各自 500 / 100 / 600 + soft 变体 |
-| 中性 | `--neutral-0 … --neutral-900` | 9 阶灰度;dark 模式镜像反转 |
+| 中性 | `--neutral-0 … --neutral-900` | 9 阶灰度；dark 模式镜像反转 |
 | 间距 | `--space-1 … --space-32` | 4px 网格 |
 | 圆角 | `--radius-xs/sm/md/lg/xl/full` | 6 档 |
 | 阴影 | `--elevation-xs/sm/md/lg/xl` | 5 档 |
@@ -26,36 +64,40 @@
 | 焦点 | `--focus-ring-width/offset/color/ring` | 统一键盘焦点环 |
 | 图表 | `--chart-series-1 … --chart-series-8` | Nivo 主题消费 |
 
-**兼容性**：旧变量 (`--accent` / `--border` / `--surface-*` / `--shadow-*` / `--radius-shell|card|pill|field`) 仍保留原值在 `index.css`，新旧并行、零回归。
-
 ## 组件清单
 
 | 名称 | 目录 | 状态 |
 |---|---|---|
-| Button / ButtonLink / ButtonAnchor | `shared/button` | ✅ 已有 |
-| TextInput / SelectInput / TextareaInput / CheckboxField / RadioGroupField / FormField | `shared/form` | ✅ 已有 |
+| Button / ButtonLink / ButtonAnchor | `shared/button` | ✅ 已补齐；含 `subtle`、`xs`、icon-only 等变体 |
+| TextInput / SelectInput / TextareaInput / CheckboxField / RadioGroupField / FormField / SearchInput / MultiSelect / Checkbox / Radio | `shared/form` | ✅ 已补齐 |
 | Table 全家桶 | `shared/table` | ✅ 已有 |
 | Switch | `shared/switch` | ✅ 已有 |
 | Chart（Nivo 主题） | `shared/chart` | ✅ 已有 |
-| Overlay（Modal/Drawer） | `shared/overlay` | ✅ 已有（S6 复核） |
-| Typography / Divider / Icon / Spinner / Skeleton | `shared/{typography,divider,icon,spinner,skeleton}` | 🕐 S2 |
-| Card / Tag / Badge / EmptyState | `shared/{card,tag,badge,empty-state}` | 🕐 S3 |
-| Breadcrumb / Pagination / Tabs / Steps | `shared/{breadcrumb,pagination,tabs,steps}` | 🕐 S4 |
-| SearchInput / Checkbox / Radio / MultiSelect / Progress / Alert / CopyButton / KVList / Avatar | `shared/…` | 🕐 S5 |
-| Tooltip / Popover / ScrollArea | `shared/{tooltip,popover,scroll-area}` | 🕐 S6 |
+| Overlay（Modal/Drawer） | `shared/overlay` | ✅ 已有；现支持 portal、focus trap、背景 inert 和焦点归还 |
+| Typography / Divider / Icon / Spinner / Skeleton | `shared/{typography,divider,icon,spinner,skeleton}` | ✅ 已补齐 |
+| Card / Tag / Badge / EmptyState | `shared/{card,tag,badge,empty-state}` | ✅ 已补齐 |
+| Breadcrumb / Pagination / Tabs / Steps | `shared/{breadcrumb,pagination,tabs,steps}` | ✅ 已补齐 |
+| Progress / Alert / CopyButton / KVList / Avatar | `shared/...` | ✅ 已补齐 |
+| Tooltip / Popover / ScrollArea | `shared/{tooltip,popover,scroll-area}` | ✅ 已补齐；Tooltip / Popover 使用 shared layer portal 和基础碰撞处理 |
+| Page / PageHeader / PageToolbar / PageBody / PageMain / PageSidebar | `shared/page-layout` | ✅ 已补齐；用于统一页面级结构 |
+| FilterBar / FilterBarActions / FilterBarSummary | `shared/filter-bar` | ✅ 已补齐；用于搜索、筛选与结果摘要排布 |
+| MetricCard | `shared/metric-card` | ✅ 已补齐；用于 KPI / 摘要统计卡 |
+
+## 视觉回归脚手架
+
+- 专用 spec：[`apps/web/e2e/design-system.spec.ts`](../../apps/web/e2e/design-system.spec.ts)
+- 默认会跑结构性断言，确认 `/design-system` 能作为公开页面展示 13 个 section
+- light/dark 截图测试先以环境变量开关保护：`PW_UPDATE_DESIGN_SYSTEM_SNAPSHOTS=1`
+- 未来在示例稳定后使用 `pnpm test:e2e -- --update-snapshots apps/web/e2e/design-system.spec.ts` 生成或更新基线
 
 ## A11y 契约（所有原语必须满足）
 
 - role / ARIA attrs 明确
-- 键盘可达 (Tab / Enter / Space / Arrow / Esc)
-- 对比度 ≥ 4.5:1 (正文) / 3:1 (大字或图形)
+- 键盘可达（Tab / Enter / Space / Arrow / Esc）
+- 对比度 ≥ 4.5:1（正文）/ 3:1（大字或图形）
 - `prefers-reduced-motion` 下降级动画
 - Modal / Drawer / Popover 焦点陷阱 + 归还
 
-## 预览
-
-开发服务器启动后访问 `/design-system` 查看当前 token 与原语的可视预览。
-
 ## 变更记录
 
-每次 token / 原语变更写入 [`CHANGELOG.md`](./CHANGELOG.md)。
+每次 token / 原语 / 预览工作面变更都写入 [`CHANGELOG.md`](./CHANGELOG.md)。
diff --git a/docs/plans/2026-04-25-design-system-component-docsite-sidebar.md b/docs/plans/2026-04-25-design-system-component-docsite-sidebar.md
new file mode 100644
index 0000000..7843dbe
--- /dev/null
+++ b/docs/plans/2026-04-25-design-system-component-docsite-sidebar.md
@@ -0,0 +1,434 @@
+# Design System Component Docsite Sidebar Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 把 `/design-system` 改造成后台风格左侧组件目录 + 右侧组件详情文档站，去掉所有分组概览入口，并为当前目录中的所有组件补齐“真实示例 + API 表 + 使用说明”。
+
+**Architecture:** 左侧仅保留分组标题和组件项，视觉风格对齐管理后台左侧栏，但不复用业务导航语义。右侧统一使用组件文档模板，按“标题区 → 真实示例 → API 表 → 使用说明 → 规范说明”渲染；所有组件内容从独立 schema 文件读取，页面层只负责目录状态与路由编排。
+
+**Tech Stack:** React 19, TypeScript, Vitest, Testing Library, Playwright, 现有 shared primitives（Button / Card / Form / Tabs / Tooltip / Overlay 等）
+
+---
+
+### Task 1: 重构左侧目录为后台风格组件目录
+
+**Files:**
+- Modify: `apps/web/src/pages/DesignSystemPage.tsx`
+- Modify: `apps/web/src/pages/design-system/designSystemStyles.ts`
+- Test: `apps/web/src/test/design-system-page.test.tsx`
+
+**Step 1: Write the failing test**
+
+在 `apps/web/src/test/design-system-page.test.tsx` 增加断言：
+- 左侧仍按分组展示
+- 但不存在任何“概览”按钮
+- 左侧每组下直接显示组件项，例如 `Button`、`Card`、`SearchInput`
+
+```tsx
+it("renders sidebar groups with component items only and no overview entries", () => {
+  render(
+    <MemoryRouter>
+      <DesignSystemPage />
+    </MemoryRouter>
+  );
+
+  const sidebar = screen.getByRole("navigation", { name: "Design system sidebar" });
+  expect(within(sidebar).queryByRole("button", { name: /概览/i })).not.toBeInTheDocument();
+  expect(within(sidebar).getByRole("button", { name: "Button" })).toBeInTheDocument();
+  expect(within(sidebar).getByRole("button", { name: "Card" })).toBeInTheDocument();
+  expect(within(sidebar).getByRole("button", { name: "SearchInput" })).toBeInTheDocument();
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/design-system-page.test.tsx -t "renders sidebar groups with component items only and no overview entries"
+```
+Expected: FAIL，因为当前侧栏仍有 overview 入口。
+
+**Step 3: Write minimal implementation**
+
+- `DesignSystemPage.tsx`
+  - 去掉 group overview 入口
+  - 左侧改成“分组标题 + 组件项”目录
+  - 默认选中第一个组件而不是分组概览
+- `designSystemStyles.ts`
+  - 调整左侧样式，使其更接近后台左栏：
+    - 分组标题
+    - 当前项高亮
+    - 紧凑目录节奏
+    - sticky 行为保留
+
+**Step 4: Run test to verify it passes**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/design-system-page.test.tsx -t "renders sidebar groups with component items only and no overview entries"
+```
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add apps/web/src/pages/DesignSystemPage.tsx apps/web/src/pages/design-system/designSystemStyles.ts apps/web/src/test/design-system-page.test.tsx
+git commit -m "feat: switch design system sidebar to component-only navigation"
+```
+
+---
+
+### Task 2: 统一组件详情模板为“示例优先”阅读流
+
+**Files:**
+- Modify: `apps/web/src/pages/design-system/DesignSystemDocContent.tsx`
+- Modify: `apps/web/src/pages/design-system/designSystemStyles.ts`
+- Test: `apps/web/src/test/design-system-page.test.tsx`
+
+**Step 1: Write the failing test**
+
+增加断言：点击 `Button` 后，右侧文档必须先出现“真实示例”，再出现 “API 接口”，再出现“使用说明”。
+
+```tsx
+it("renders component docs with examples first, then API, then usage guidance", () => {
+  render(
+    <MemoryRouter>
+      <DesignSystemPage />
+    </MemoryRouter>
+  );
+
+  fireEvent.click(screen.getByRole("button", { name: "Button" }));
+
+  const headings = screen.getAllByRole("heading").map((node) => node.textContent);
+  const expected = ["真实示例", "API 接口", "使用说明"];
+  const indexes = expected.map((heading) => headings.indexOf(heading));
+
+  expect(indexes.every((index) => index >= 0)).toBe(true);
+  expect(indexes).toEqual([...indexes].sort((a, b) => a - b));
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/design-system-page.test.tsx -t "renders component docs with examples first, then API, then usage guidance"
+```
+Expected: FAIL
+
+**Step 3: Write minimal implementation**
+
+- `DesignSystemDocContent.tsx`
+  - 去掉 group overview 模式
+  - 统一所有组件页的顺序：
+    1. 标题区
+    2. 真实示例
+    3. API 接口
+    4. 使用说明
+    5. 设计规范 / 补充说明
+- `designSystemStyles.ts`
+  - 强化文档段落和 API 表块的层级
+
+**Step 4: Run test to verify it passes**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/design-system-page.test.tsx -t "renders component docs with examples first, then API, then usage guidance"
+```
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add apps/web/src/pages/design-system/DesignSystemDocContent.tsx apps/web/src/pages/design-system/designSystemStyles.ts apps/web/src/test/design-system-page.test.tsx
+git commit -m "feat: align component docs to example-first reading flow"
+```
+
+---
+
+### Task 3: 扩展文档 schema 支持 API 表
+
+**Files:**
+- Modify: `apps/web/src/pages/design-system/designSystemContent.tsx`
+- Modify: `apps/web/src/pages/design-system/DesignSystemDocContent.tsx`
+- Test: `apps/web/src/test/design-system-page.test.tsx`
+
+**Step 1: Write the failing test**
+
+增加断言：选中 `Button` 后，页面出现 API 表头 `prop / type / default / description`。
+
+```tsx
+it("renders a structured API table for a component", () => {
+  render(
+    <MemoryRouter>
+      <DesignSystemPage />
+    </MemoryRouter>
+  );
+
+  fireEvent.click(screen.getByRole("button", { name: "Button" }));
+
+  expect(screen.getByText("prop")).toBeInTheDocument();
+  expect(screen.getByText("type")).toBeInTheDocument();
+  expect(screen.getByText("default")).toBeInTheDocument();
+  expect(screen.getByText("description")).toBeInTheDocument();
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/design-system-page.test.tsx -t "renders a structured API table for a component"
+```
+Expected: FAIL
+
+**Step 3: Write minimal implementation**
+
+在 `designSystemContent.tsx` 扩展 schema：
+- `DesignSystemApiField`
+- `api` 字段
+
+```ts
+interface DesignSystemApiField {
+  prop: string;
+  type: string;
+  defaultValue: string;
+  description: string;
+}
+```
+
+然后在 `DesignSystemDocContent.tsx` 中渲染 API 表。
+
+**Step 4: Run test to verify it passes**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/design-system-page.test.tsx -t "renders a structured API table for a component"
+```
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add apps/web/src/pages/design-system/designSystemContent.tsx apps/web/src/pages/design-system/DesignSystemDocContent.tsx apps/web/src/test/design-system-page.test.tsx
+git commit -m "feat: add API tables to design system docs"
+```
+
+---
+
+### Task 4: 为当前目录中的所有组件补齐完整页内容
+
+**Files:**
+- Modify: `apps/web/src/pages/design-system/designSystemContent.tsx`
+- Test: `apps/web/src/test/app.test.tsx`
+- Test: `apps/web/src/test/design-system-page.test.tsx`
+
+**Step 1: Write the failing test**
+
+增加断言：当前目录中的所有组件都必须能进入详情页，并显示至少 3 个块：
+- 真实示例
+- API 接口
+- 使用说明
+
+```tsx
+it("renders complete docs for every component listed in the sidebar", () => {
+  render(
+    <MemoryRouter>
+      <DesignSystemPage />
+    </MemoryRouter>
+  );
+
+  const componentNames = [
+    "Design tokens",
+    "PageLayout",
+    "Typography",
+    "Button",
+    "Card",
+    "Data display",
+    "SearchInput",
+    "MultiSelect",
+    "Selection controls",
+    "Navigation",
+    "Feedback",
+    "Overlay",
+    "Tooltip & Popover",
+    "Copy utility"
+  ];
+
+  for (const name of componentNames) {
+    fireEvent.click(screen.getByRole("button", { name }));
+    expect(screen.getByRole("heading", { name: "真实示例" })).toBeInTheDocument();
+    expect(screen.getByRole("heading", { name: "API 接口" })).toBeInTheDocument();
+    expect(screen.getByRole("heading", { name: "使用说明" })).toBeInTheDocument();
+  }
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/design-system-page.test.tsx -t "renders complete docs for every component listed in the sidebar"
+```
+Expected: FAIL
+
+**Step 3: Write minimal implementation**
+
+把当前目录里的所有组件文档补到同一标准：
+- Design tokens
+- PageLayout
+- Typography
+- Button
+- Card
+- Data display
+- SearchInput
+- MultiSelect
+- Selection controls
+- Navigation
+- Feedback
+- Overlay
+- Tooltip & Popover
+- Copy utility
+
+每个都至少补齐：
+- `summary`
+- `examples`
+- `api`
+- `usage`
+- `notes`
+
+优先复用当前已有 preview 与文案，避免重写 demo。
+
+**Step 4: Run test to verify it passes**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/design-system-page.test.tsx -t "renders complete docs for every component listed in the sidebar"
+```
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add apps/web/src/pages/design-system/designSystemContent.tsx apps/web/src/test/design-system-page.test.tsx apps/web/src/test/app.test.tsx
+git commit -m "feat: complete doc pages for all design system components"
+```
+
+---
+
+### Task 5: 调整桌面与移动端的目录/详情体验
+
+**Files:**
+- Modify: `apps/web/src/pages/DesignSystemPage.tsx`
+- Modify: `apps/web/src/pages/design-system/designSystemStyles.ts`
+- Test: `apps/web/src/test/design-system-page.test.tsx`
+
+**Step 1: Write the failing test**
+
+增加断言：
+- 默认进入第一个组件详情，而不是 overview
+- 移动端仍保持单列，不溢出
+
+```tsx
+it("defaults to the first component detail instead of a group overview", () => {
+  render(
+    <MemoryRouter>
+      <DesignSystemPage />
+    </MemoryRouter>
+  );
+
+  expect(screen.getByRole("heading", { name: "Design tokens" })).toBeInTheDocument();
+  expect(screen.queryByRole("button", { name: /概览/i })).not.toBeInTheDocument();
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/design-system-page.test.tsx -t "defaults to the first component detail instead of a group overview"
+```
+Expected: FAIL
+
+**Step 3: Write minimal implementation**
+
+- 默认选中第一个组件详情
+- 左侧保持后台风格目录
+- 桌面端目录宽度、sticky 行为、当前项高亮稳定
+- 移动端继续保持单列 layout
+
+**Step 4: Run test to verify it passes**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/design-system-page.test.tsx -t "defaults to the first component detail instead of a group overview"
+```
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add apps/web/src/pages/DesignSystemPage.tsx apps/web/src/pages/design-system/designSystemStyles.ts apps/web/src/test/design-system-page.test.tsx
+git commit -m "feat: polish component-doc navigation experience"
+```
+
+---
+
+### Task 6: 最终验证与代码审查
+
+**Files:**
+- Review only: `apps/web/src/pages/DesignSystemPage.tsx`
+- Review only: `apps/web/src/pages/design-system/designSystemContent.tsx`
+- Review only: `apps/web/src/pages/design-system/DesignSystemDocContent.tsx`
+- Review only: `apps/web/src/pages/design-system/designSystemStyles.ts`
+- Test: `apps/web/src/test/app.test.tsx`
+- Test: `apps/web/src/test/design-system-page.test.tsx`
+- Test: `apps/web/e2e/design-system.spec.ts`
+
+**Step 1: Run targeted unit tests**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/app.test.tsx src/test/design-system-page.test.tsx src/test/shared-form.test.tsx src/test/shared-overlay.test.tsx
+```
+Expected: PASS
+
+**Step 2: Run E2E smoke**
+
+Run:
+```bash
+pnpm exec playwright test -c apps/web/playwright.config.ts apps/web/e2e/design-system.spec.ts
+```
+Expected: PASS
+
+**Step 3: Preview verification**
+
+手动确认：
+- 首页进入设计系统
+- 左侧为后台风格组件目录
+- 没有 overview
+- 默认进入组件详情
+- Button 页能看到真实示例 + API 表 + 使用说明
+- Overlay live demo 正常
+- 移动端单列正常
+
+**Step 4: Final code review**
+
+Use:
+- `code-reviewer`
+- 必要时补 `typescript-reviewer`
+
+Expected: 无 CRITICAL/HIGH 问题
+
+**Step 5: Commit**
+
+```bash
+git add apps/web/src/pages/DesignSystemPage.tsx \
+  apps/web/src/pages/design-system/designSystemContent.tsx \
+  apps/web/src/pages/design-system/DesignSystemDocContent.tsx \
+  apps/web/src/pages/design-system/designSystemStyles.ts \
+  apps/web/src/test/app.test.tsx \
+  apps/web/src/test/design-system-page.test.tsx \
+  apps/web/e2e/design-system.spec.ts
+git commit -m "feat: turn design system into component-first docsite"
+```
diff --git a/docs/plans/2026-04-25-design-system-docsite-upgrade.md b/docs/plans/2026-04-25-design-system-docsite-upgrade.md
new file mode 100644
index 0000000..68b5b94
--- /dev/null
+++ b/docs/plans/2026-04-25-design-system-docsite-upgrade.md
@@ -0,0 +1,402 @@
+# Design System Docsite Upgrade Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 把 `/design-system` 从组件预览页升级为真正可读、可维护的组件文档站，支持完整组件详情与更正式的文档化阅读体验。
+
+**Architecture:** 保留现有左侧混合导航（分组概览 + 组件项），但把右侧内容区统一收敛为文档模板。页面层只负责导航状态与模板编排，组件文档内容从独立配置对象读取；overview 与 component detail 共享同一阅读节奏，但字段不同。
+
+**Tech Stack:** React 19, TypeScript, Vitest, Testing Library, 现有 shared primitives（Button / Card / Typography / Tabs / Code-style blocks）
+
+---
+
+### Task 1: 抽离设计系统文档数据模型
+
+**Files:**
+- Create: `apps/web/src/pages/design-system/designSystemContent.ts`
+- Modify: `apps/web/src/pages/DesignSystemPage.tsx`
+- Test: `apps/web/src/test/app.test.tsx`
+
+**Step 1: Write the failing test**
+
+在 `apps/web/src/test/app.test.tsx` 增加一个最小断言：点击某个组件后，右侧详情区必须出现统一文档段落标题，例如“适用场景”或“设计规范”。
+
+```tsx
+it("renders structured documentation sections for a selected component", async () => {
+  window.history.pushState({}, "", "/design-system");
+  vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("not authenticated"));
+  render(<App />);
+
+  const sidebar = await screen.findByRole("navigation", { name: "Design system sidebar" });
+  fireEvent.click(within(sidebar).getByRole("button", { name: "Button" }));
+
+  expect(screen.getByText("适用场景")).toBeInTheDocument();
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/app.test.tsx -t "renders structured documentation sections for a selected component"
+```
+Expected: FAIL，因为当前组件详情没有统一文档段落。
+
+**Step 3: Write minimal implementation**
+
+在 `apps/web/src/pages/design-system/designSystemContent.ts` 定义：
+- `DesignSystemDocSection`
+- `DesignSystemComponentDoc`
+- `DesignSystemGroupDoc`
+- Button / Card / SearchInput / Navigation / Feedback 等首批完整文档数据
+
+`DesignSystemPage.tsx` 改成从这些对象读取内容，而不是把所有说明散在页面 JSX 里。
+
+**Step 4: Run test to verify it passes**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/app.test.tsx -t "renders structured documentation sections for a selected component"
+```
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add apps/web/src/pages/design-system/designSystemContent.ts apps/web/src/pages/DesignSystemPage.tsx apps/web/src/test/app.test.tsx
+git commit -m "feat: structure design system doc content"
+```
+
+---
+
+### Task 2: 统一右侧组件详情模板
+
+**Files:**
+- Create: `apps/web/src/pages/design-system/DesignSystemDocContent.tsx`
+- Modify: `apps/web/src/pages/DesignSystemPage.tsx`
+- Test: `apps/web/src/test/app.test.tsx`
+
+**Step 1: Write the failing test**
+
+增加断言，要求组件详情按固定顺序出现这些标题：
+- 组件介绍
+- 适用场景
+- 状态与变体
+- 交互示例
+- 代码片段
+- 设计规范
+
+```tsx
+it("renders component docs in the expected reading order", async () => {
+  window.history.pushState({}, "", "/design-system");
+  vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("not authenticated"));
+  render(<App />);
+
+  const sidebar = await screen.findByRole("navigation", { name: "Design system sidebar" });
+  fireEvent.click(within(sidebar).getByRole("button", { name: "Button" }));
+
+  const headings = screen.getAllByRole("heading").map((node) => node.textContent);
+  expect(headings).toContain("适用场景");
+  expect(headings).toContain("状态与变体");
+  expect(headings).toContain("交互示例");
+  expect(headings).toContain("代码片段");
+  expect(headings).toContain("设计规范");
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/app.test.tsx -t "renders component docs in the expected reading order"
+```
+Expected: FAIL
+
+**Step 3: Write minimal implementation**
+
+创建 `DesignSystemDocContent.tsx`：
+- 接收一个 `componentDoc`
+- 用固定 section 顺序渲染文档
+- overview 模式与 component mode 共用节奏，但允许字段不同
+
+在 `DesignSystemPage.tsx` 中右侧区域只做：
+- 选中 overview → 传 groupDoc
+- 选中 component → 传 componentDoc
+
+**Step 4: Run test to verify it passes**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/app.test.tsx -t "renders component docs in the expected reading order"
+```
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add apps/web/src/pages/design-system/DesignSystemDocContent.tsx apps/web/src/pages/DesignSystemPage.tsx apps/web/src/test/app.test.tsx
+git commit -m "feat: add structured doc template for components"
+```
+
+---
+
+### Task 3: 升级视觉层级，让右侧更像文档站
+
+**Files:**
+- Create: `apps/web/src/pages/design-system/designSystemStyles.ts`
+- Modify: `apps/web/src/pages/DesignSystemPage.tsx`
+- Test: `apps/web/src/test/app.test.tsx`
+
+**Step 1: Write the failing test**
+
+补一个结构性测试，要求右侧详情区存在独立的文档块，而不是全部混在一个大说明里。可用文本断言验证存在“代码片段”和“设计规范”区域。
+
+```tsx
+it("renders separate doc sections instead of a single summary block", async () => {
+  window.history.pushState({}, "", "/design-system");
+  vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("not authenticated"));
+  render(<App />);
+
+  const sidebar = await screen.findByRole("navigation", { name: "Design system sidebar" });
+  fireEvent.click(within(sidebar).getByRole("button", { name: "Button" }));
+
+  expect(screen.getByText("代码片段")).toBeInTheDocument();
+  expect(screen.getByText("设计规范")).toBeInTheDocument();
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/app.test.tsx -t "renders separate doc sections instead of a single summary block"
+```
+Expected: FAIL
+
+**Step 3: Write minimal implementation**
+
+把目前散在 `DesignSystemPage.tsx` 的样式常量收敛一部分到 `designSystemStyles.ts`，至少拆出：
+- 页面级布局 style
+- 文档 section style
+- 示例区 style
+- 代码区 style
+- 规范信息块 style
+
+同时让右侧详情区减少 dashboard 感，强化文档阅读感：
+- 标题更明确
+- 分段更稳定
+- 卡片数量更少但层级更清晰
+
+**Step 4: Run test to verify it passes**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/app.test.tsx -t "renders separate doc sections instead of a single summary block"
+```
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add apps/web/src/pages/design-system/designSystemStyles.ts apps/web/src/pages/DesignSystemPage.tsx apps/web/src/test/app.test.tsx
+git commit -m "feat: refine design system docsite layout"
+```
+
+---
+
+### Task 4: 首批组件详情补全到“可用文档”级别
+
+**Files:**
+- Modify: `apps/web/src/pages/design-system/designSystemContent.ts`
+- Modify: `apps/web/src/pages/DesignSystemPage.tsx`
+- Test: `apps/web/src/test/app.test.tsx`
+
+**Step 1: Write the failing test**
+
+至少为 Button 增加完整文档内容断言：
+- 有适用场景
+- 有至少一个不要使用场景
+- 有状态与变体项
+- 有代码片段标题
+- 有设计规范标题
+
+```tsx
+it("documents button with usage, variants, code, and design guidance", async () => {
+  window.history.pushState({}, "", "/design-system");
+  vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("not authenticated"));
+  render(<App />);
+
+  const sidebar = await screen.findByRole("navigation", { name: "Design system sidebar" });
+  fireEvent.click(within(sidebar).getByRole("button", { name: "Button" }));
+
+  expect(screen.getByText("适用场景")).toBeInTheDocument();
+  expect(screen.getByText("不适用场景")).toBeInTheDocument();
+  expect(screen.getByText("状态与变体")).toBeInTheDocument();
+  expect(screen.getByText("代码片段")).toBeInTheDocument();
+  expect(screen.getByText("设计规范")).toBeInTheDocument();
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/app.test.tsx -t "documents button with usage, variants, code, and design guidance"
+```
+Expected: FAIL
+
+**Step 3: Write minimal implementation**
+
+先补齐以下组件或分组：
+- `Foundations` overview
+- `Button`
+- `Card`
+- `SearchInput`
+- `Navigation`
+- `Feedback`
+
+每个组件至少包含：
+- summary
+- use cases
+- donts
+- variants
+- examples
+- one static code sample
+- design notes
+
+**Step 4: Run test to verify it passes**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/app.test.tsx -t "documents button with usage, variants, code, and design guidance"
+```
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add apps/web/src/pages/design-system/designSystemContent.ts apps/web/src/pages/DesignSystemPage.tsx apps/web/src/test/app.test.tsx
+git commit -m "feat: fill first design system component docs"
+```
+
+---
+
+### Task 5: 增加代码片段与示例区的稳定回归
+
+**Files:**
+- Modify: `apps/web/src/pages/design-system/DesignSystemDocContent.tsx`
+- Modify: `apps/web/src/test/app.test.tsx`
+- Optional Test: `apps/web/e2e/design-system.spec.ts`
+
+**Step 1: Write the failing test**
+
+增加断言，要求选中 Button 后：
+- 有一段代码片段文本
+- 示例区里的真实按钮仍然可见
+
+```tsx
+it("shows both live examples and static code snippets for a component", async () => {
+  window.history.pushState({}, "", "/design-system");
+  vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("not authenticated"));
+  render(<App />);
+
+  const sidebar = await screen.findByRole("navigation", { name: "Design system sidebar" });
+  fireEvent.click(within(sidebar).getByRole("button", { name: "Button" }));
+
+  expect(screen.getByText(/<Button variant=/i)).toBeInTheDocument();
+  expect(screen.getByRole("button", { name: "保存变更" })).toBeInTheDocument();
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/app.test.tsx -t "shows both live examples and static code snippets for a component"
+```
+Expected: FAIL
+
+**Step 3: Write minimal implementation**
+
+- 在文档 schema 中加入 `codeSamples`
+- 在 `DesignSystemDocContent.tsx` 渲染 `<pre><code>` 或现有 typography/code 原语
+- 代码片段先静态维护，不做自动生成
+- 如果已有 `apps/web/e2e/design-system.spec.ts`，补一条轻量 smoke：默认 overview、切 Button、看到代码片段和示例按钮
+
+**Step 4: Run test to verify it passes**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/app.test.tsx -t "shows both live examples and static code snippets for a component"
+```
+Expected: PASS
+
+Optional:
+```bash
+pnpm test:e2e -- --grep "design system"
+```
+Expected: PASS 或至少 smoke path 通过
+
+**Step 5: Commit**
+
+```bash
+git add apps/web/src/pages/design-system/DesignSystemDocContent.tsx apps/web/src/test/app.test.tsx apps/web/e2e/design-system.spec.ts
+git commit -m "test: cover design system docs and examples"
+```
+
+---
+
+### Task 6: 最终验证与整理
+
+**Files:**
+- Review only: `apps/web/src/pages/DesignSystemPage.tsx`
+- Review only: `apps/web/src/pages/design-system/designSystemContent.ts`
+- Review only: `apps/web/src/pages/design-system/DesignSystemDocContent.tsx`
+- Review only: `apps/web/src/pages/design-system/designSystemStyles.ts`
+- Test: `apps/web/src/test/app.test.tsx`
+
+**Step 1: Run targeted unit tests**
+
+Run:
+```bash
+pnpm --dir apps/web exec vitest run src/test/app.test.tsx
+```
+Expected: PASS
+
+**Step 2: Run preview verification**
+
+Use preview tools to verify:
+- 默认进入 group overview
+- 点击 Button 进入完整长文档详情
+- 页面有“介绍 → 场景 → 变体 → 示例 → 代码 → 规范”的阅读流
+- 桌面/移动端布局不塌
+
+Expected: 页面结构稳定，无 console / server error
+
+**Step 3: Run code review**
+
+Use required review flow:
+- `code-reviewer`
+- 必要时补 `typescript-reviewer`
+
+Expected: 无 CRITICAL/HIGH 问题
+
+**Step 4: Final cleanup**
+
+确认：
+- 无重复文案块
+- 无多余按钮
+- 无旧的“预览集合页”残留逻辑
+- 新文件命名与分层符合项目约定
+
+**Step 5: Commit**
+
+```bash
+git add apps/web/src/pages/DesignSystemPage.tsx \
+  apps/web/src/pages/design-system/designSystemContent.ts \
+  apps/web/src/pages/design-system/DesignSystemDocContent.tsx \
+  apps/web/src/pages/design-system/designSystemStyles.ts \
+  apps/web/src/test/app.test.tsx \
+  apps/web/e2e/design-system.spec.ts
+git commit -m "feat: turn design system preview into component docsite"
+```