feat(design): 引入 DESIGN.md 设计 token SSOT + 状态覆盖 + 8 维交付自查

.claude/agents/code-reviewer.md

@@ -90,6 +90,16 @@ SendMessage({to: "product-lead", message: "审查未通过: [功能名]\n报告:
 
 判级：上述任一缺失 → 至少 warning；契约手写绕过生成产物（破坏编译期校验）/ 交互控件无 handler（点击无反应）→ critical。
 
+## 设计 token 审查项（含前端样式改动的 PR）
+
+针对"设计漂移 / 硬编码色值 / 对比不达标"，含前端样式改动的 PR 逐条核（纪律 SSOT [`coding.md` 设计 token 纪律](../standards/coding.md) + token 源 `docs/design/DESIGN.md`）：
+
+1. **无硬编码视觉值**：样式里**无**裸 `#RRGGBB` / 字面 `px` 间距字号 / 一次性圆角——`grep` 业务 / 样式代码命中即 finding；视觉值必引用 DESIGN.md token（Tailwind / CSS 变量）。
+2. **on-* 配对**：背景色都配了 DESIGN.md 里的 `on-*` 文本色，无"主色背景配未声明文本色"；可疑低对比组合标注。
+3. **token 在册**：引用的 token 都存在于 DESIGN.md（避免引用未定义 token）；新增视觉值应先进 DESIGN.md。
+
+判级：硬编码绕过 token 体系 / 主色未配 on-color（潜在对比缺陷）→ 至少 warning；大面积硬编码或对比明显不达标（可访问性缺陷）→ critical。
+
 ## 审查优先级顺序
 
 1. **正确性** — 代码是否做了它应该做的？

.claude/agents/uiux-designer.md

@@ -34,8 +34,8 @@ SendMessage({to: "frontend-dev", message: "设计完成: [页面/功能名]\n设
 
 1. **单一来源原则** — 遵循 `.claude/standards/document-rules.md`，完整内容只在权威文档描述，SendMessage 只传路径和摘要
 2. **用户中心** — 从用户目标和任务出发，不从技术实现出发
-3. **一致性** — 遵循项目设计系统，保持视觉和交互一致
-4. **可访问性** — 考虑色盲、视障、键盘操作等无障碍需求
+3. **一致性** — 遵循项目设计系统 `docs/design/DESIGN.md`（设计 token SSOT），视觉值一律**引用 token**，禁内联硬编码颜色 / 字号 / 间距 / 圆角
+4. **可访问性** — 考虑色盲、视障、键盘操作等无障碍需求；颜色按 DESIGN.md `on-*` 配对取色（对比度满足 WCAG AA）
 5. **简洁** — 减少不必要的元素，聚焦核心操作
 6. **反馈明确** — 每个操作都有及时、清晰的反馈
 
@@ -44,14 +44,16 @@ SendMessage({to: "frontend-dev", message: "设计完成: [页面/功能名]\n设
 1. **理解需求** — 阅读任务描述、用户故事、验收标准
 2. **信息架构** — 确定内容优先级、导航结构
 3. **线框图** — 低保真布局，不含样式
-4. **视觉设计** — 应用颜色、字体、图标
+4. **视觉设计** — 先确认 `docs/design/DESIGN.md` 存在（无则本步建立项目级 token 系统）；应用颜色、字体、图标**一律引用 DESIGN.md token**，新增视觉值先回填 DESIGN.md 再用
 5. **交互设计** — 定义状态、动画过度、异常处理
 6. **静态 HTML 原型** — 输出 `docs/design/[feature]/index.html`（要求见"静态 HTML 原型要求"节）
 7. **设计标注** — 输出可交接的设计规范给 frontend-dev
 
 ## 输出格式
 
-设计完成后**必须同时产出两份文件**，再通过 SendMessage 告知 frontend-dev 路径：
+所有视觉值的单一来源是项目级 `docs/design/DESIGN.md`（设计 token SSOT；首个 feature 时建立、后续按需更新）。下列每份 feature 产物只**引用** token，不重声明色板 / 间距。
+
+设计完成后**必须同时产出两份 feature 文件**，再通过 SendMessage 告知 frontend-dev 路径：
 
 | 文件 | 路径 | 用途 |
 |---|---|---|
@@ -73,16 +75,32 @@ SendMessage({to: "frontend-dev", message: "设计完成: [页面/功能名]\n设
 |---|---|---|---|---|---|
 | 按钮 | ... | ... | ... | ... | ... |
 
+## 页面/模块状态覆盖
+
+> 产品级状态，缺任一即真实缺陷（区别于上表组件视觉态）。每个数据驱动的页面/模块逐态定义「触发条件 + 呈现」。
+
+| 状态 | 触发 | 呈现 |
+|---|---|---|
+| default | 有数据正常态 | 正常内容 |
+| loading | 请求未返回 | 骨架屏 / spinner（含超时兜底文案）|
+| empty | 数据为空 | 空态插画 + 引导操作（**非白屏**）|
+| error | 请求失败 / 异常 | 分类错误文案 + 重试入口 |
+| permission | 无访问权限 | 无权限提示 + 申请 / 返回路径 |
+| disabled | 功能不可用 | 灰置 + 原因提示 |
+
 ## 交互流程
 1. 用户操作 → 系统响应
 2. ...
 
 ## 设计标注
-- 字体: ...
-- 颜色: primary #... / error #...
-- 间距: 基准 16px
-- 圆角: 8px
-- 按钮高度: 48px
+
+> 视觉值**引用 `docs/design/DESIGN.md` token**，本段只列本页用到哪些 token + 本页特有覆盖（如有），禁内联重声明全局色板 / 间距。
+
+- 字体: `{typography.title}` 标题 / `{typography.body}` 正文
+- 颜色: `{color.primary}` 主操作 / `{color.error}` 错误（均按 `on-*` 配对取文本色）
+- 间距: 基准 `{spacing.md}`
+- 圆角: `{radius.md}`
+- 按钮: component token `button-primary`（本页若有覆盖在此注明）
 
 ## AC 覆盖
 
@@ -102,12 +120,30 @@ SendMessage({to: "frontend-dev", message: "设计完成: [页面/功能名]\n设
 
 - **自包含**：单文件 `index.html` 优先，用 Tailwind CDN 或内联 `<style>`，避免外部构建步骤
 - **可直接打开**：`open docs/design/[feature]/index.html` 即应渲染完整页面
-- **覆盖关键状态**：用 `data-state` 或并排展示 default/hover/active/disabled/error 等关键态
+- **覆盖关键状态**：组件视觉态（default/hover/active/disabled）+ **产品状态（loading/empty/error/permission，见 spec「页面/模块状态覆盖」）** 用 `data-state` 或并排展示，空态 / 加载态不得留白屏
 - **响应式**：至少覆盖移动（375px）与桌面（≥1024px）两个断点
 - **真实文案与数据**：用接近生产的占位内容，避免 "Lorem ipsum"，便于评审者理解信息密度
 - **无后端依赖**：不调用真实 API，所有数据写在页面内或 `<script>` 常量
+- **对齐设计 token**：样式取值对齐 `docs/design/DESIGN.md` token（CDN 原型可在 `<style>` 顶部用 CSS 变量镜像 token：`--color-primary` 等），不写与 DESIGN.md 冲突的硬编码色值；颜色按 `on-*` 配对
 - **可访问性基线**：保留语义化标签、`alt`、`label`、可见焦点态，对照 `frontend-design:frontend-design` 的检查清单
 
+## 交付前自查（8 维）
+
+SendMessage 通知 frontend-dev 前，对照本表逐维自检 spec + 原型（任一不达标先改再交；**这 8 维也是后续 qa-engineer UAT 界面核查的同一组轴**，自检即对齐验收标准）：
+
+| 维度 | 自检要点 |
+|---|---|
+| 1 布局 | 模块顺序 / 对齐 / 间距 / 视觉层次，密度均衡 |
+| 2 字体 | 字号 / 字重 / 行高 / 层级取自 `{typography.*}` token |
+| 3 颜色 | 全部引用 token + `on-*` 配对达 WCAG AA，无硬编码 |
+| 4 组件 | 复用 `component` token，无一次性样式 |
+| 5 状态 | default/loading/empty/error/permission/disabled 全覆盖（见「页面/模块状态覆盖」）|
+| 6 交互 | 每个可交互控件有明确反馈 / 校验 / 确认逻辑 |
+| 7 响应式 | 移动 375 + 桌面 ≥1024 两断点均无裁切 / 溢出 |
+| 8 性能 | 长列表（≥100 项）标注虚拟滚动 / 懒加载意图 |
+
+> 设计意图：8 维是**设计侧前置门**，与 UAT 的「读图四查」（qa 在 testing.md 的验证机制）互补不重叠——本表防"带病交付"，四查防"接口对了界面坏了"。
+
 ## MiniApp Mode（微信小程序设计）
 
 当 `product-lead` 任务明确为微信小程序（"小程序" / "miniapp" / "微信端"）时，本角色附加规则集中在 [`.claude/standards/miniapp.md` §9 Designer Mode 行为](../standards/miniapp.md)。
@@ -128,7 +164,8 @@ SendMessage({to: "frontend-dev", message: "设计完成: [页面/功能名]\n设
 
 | Kind | Path | Template | Must |
 |---|---|---|---|
-| 设计规范 | `docs/design/[feature]/spec.md` | free（本文件"设计规范结构"段） | 含布局 / 状态表 / 交互流程 / 标注 / **AC 覆盖表（逐条引用 PRD §4 AC ID + 承载方式或 N/A 理由）** |
+| 设计系统 token | `docs/design/DESIGN.md` | 已落地模板（YAML token + 理据） | **项目级 SSOT**·首个 feature 建立、后续按需更新；含 `on-*` 配对 + 最小组件覆盖 + Do/Don't；各 feature spec 只引用其 token |
+| 设计规范 | `docs/design/[feature]/spec.md` | free（本文件"设计规范结构"段） | 含布局 / 状态表 / 交互流程 / 标注（**引用 DESIGN.md token，禁内联重声明色板**）/ **AC 覆盖表（逐条引用 PRD §4 AC ID + 承载方式或 N/A 理由）** |
 | 静态 HTML 原型 | `docs/design/[feature]/index.html` | free（Tailwind CDN 或内联 `<style>`） | 自包含 / 可直接 `open` / 覆盖关键状态 + 移动 + 桌面响应式 |
 | 资源 | `docs/design/[feature]/assets/` | free | 图片 / 图标 / 视频引用 |
 | 设计标注通告 | SendMessage to frontend-dev / miniapp-dev | free | 含 spec.md + index.html 路径 + 关键标注摘要 |

.claude/rules/repo-layout.md

@@ -38,7 +38,8 @@ paths:
 | `docs/team-capability-map.md` | §1 端到端全景图（角色 + 阶段门 + hook + skill 叠加）+ 全角色协作 Mermaid + 能力对照表，改 agent 时必须同步 |
 | `docs/product-workflow.md` | 产品交付工作流 + 全量术语词典；写 PRD / 拆 Task / 用术语前先查这里 |
 | `docs/prd/*.md` | product-lead 产出（命名 `[feature]-[YYYY-MM-DD].md`，写时用 skill `agf-writing-prd`） |
-| `docs/design/[feature]/` | uiux-designer 产出（`spec.md` + `index.html`，资源放 `assets/`） |
+| `docs/design/DESIGN.md` | **项目级设计系统 SSOT**（设计 token：color/typography/spacing/radius/component + `on-*` 配对 + Do/Don't），uiux-designer 维护；各 feature spec 与前端样式引用其 token，禁内联重声明（纪律见 `coding.md` 设计 token 纪律） |
+| `docs/design/[feature]/` | uiux-designer 产出（`spec.md` + `index.html`，资源放 `assets/`；视觉值引用 `docs/design/DESIGN.md` token） |
 | `docs/reviews/*.md` | code-reviewer 产出 + release retro（`retro-vX.Y.Z-YYYY-MM-DD.md`）+ 季度 eval 漂移记录 |
 | `docs/qa/*.md` | qa-engineer 产出（E2E / UAT 报告，写时用 skill `agf-writing-qa-report`；SIT 不再独立成 `docs/qa/*-sit-*.md`，证据写入 `progress/<role>.md` 由 code-reviewer 在 review 时 audit）+ `<feature>-process-log.md`（progress/ 归档，UAT 签字后由 product-lead 写入） |
 | `docs/deploy/*.md` | deploy-engineer 产出（UAT 部署报告 `<feature>-uat-<YYYY-MM-DD>.md`，写时用 skill `agf-deploying-uat`；含 UAT 栈各服务 URL + 冒烟证据 + 迁移结果 + 部署 commit SHA + 二元 gate；qa-engineer 读它拿 E2E/UAT 测试目标地址）+ apple-release-engineer 产出（Apple 发布报告 `<feature>-apple-<YYYY-MM-DD>.md`，写时用 skill `agf-releasing-apple`；含分发包定位 + 冒烟证据 + 构建 commit SHA + 二元 gate；apple-qa-engineer 读它拿测试目标） |

.claude/standards/coding.md

@@ -48,6 +48,15 @@ git log --oneline --grep="<feature>" | head # commit 历史
 - **契约变更闭环**：后端重新导出 `openapi.json` 进库 → apple 侧下次构建自动重生成；CI 对 `openapi.json` 跑「重导出 + `git diff --exit-code`」。
 - 执行细则见 [`apple-native.md`](apple-native.md)；后端 schema 规范责任与 Web 轨同一条（上节），不重复。
 
+### 设计 token 纪律（含前端样式的 feature 必读）
+
+项目视觉系统的单一来源是 [`docs/design/DESIGN.md`](../../docs/design/DESIGN.md)（设计 token SSOT，维护者 uiux-designer）。前端样式与各 feature spec 只引用 token，杜绝"散点硬编码 + 设计漂移"：
+
+- **禁硬编码视觉值**：颜色 hex、字号、间距、圆角一律引用 DESIGN.md token（落到 Tailwind / CSS 变量，如 `var(--color-primary)`）；业务 / 样式代码里裸 `#RRGGBB`、`padding: 13px` 之类即 finding。
+- **on-* 配对取色**：背景色与文本色成对取 `(color.x, color.on-x)`，对比度满足 WCAG AA（正文 ≥ 4.5:1）；新增主色先在 DESIGN.md 补 `on-*` 再用。
+- **token 变更闭环**：需要新 token → 先改 DESIGN.md 再在 spec / 代码引用；不在 feature 局部另立一套色板 / 间距。
+- 审查侧由 code-reviewer「设计 token 审查项」逐条核（见 [`code-reviewer.md`](../agents/code-reviewer.md)）。
+
 ## AI Development Guidelines
 
 - 接入 LLM SDK 时优先启用 prompt caching（若厂商 SDK 支持）

.claude/standards/testing.md

@@ -50,7 +50,7 @@ feature 含任何用户可见界面（页面 / 弹窗 / 抽屉 / 浮层）即触
    - **导航**：该界面应有的全局导航 / 入口 / 返回路径可见且指向正确；
    - **裁切**：无文本截断、元素溢出、相互遮挡；
    - **控件可点**：该界面关键可交互控件真实点击 / 输入并产生可观测后果（断言标准复用下文强制覆盖项 ③）；
-   - **视觉达标**：对照 `docs/design/[feature]/spec.md` + `index.html` 原型核还原度——对齐 / 间距 / 配色 / 字体层级 / 文案完整 / 空态与加载态观感；判准 = **这张截图敢不敢直接交付给用户**。
+   - **视觉达标**：对照 `docs/design/[feature]/spec.md` + `index.html` 原型核还原度——对齐 / 间距 / 配色 / 字体层级 / 文案完整 / 全状态观感（default/loading/empty/error/permission/disabled，对照 spec「页面/模块状态覆盖」）；判准 = **这张截图敢不敢直接交付给用户**。
 
 ### 证据效力（不可绕过）
 

CLAUDE.md

@@ -20,7 +20,7 @@ AI 应用开发项目，前端 Web、后端服务、AI Agent、Apple 原生（ma
 
 - 本文件只放项目特有规则，团队通用规则统一放在 `.claude/standards/`，结构性指引在 `.claude/rules/`。
 - 项目涉及外部合规、部署约束、第三方集成限制时，在此处追加。
-- 设计交付物路径约定：`docs/design/[feature]/spec.md`（设计规范）+ `docs/design/[feature]/index.html`（自包含静态原型，Tailwind CDN 或内联样式，可直接 `open` 打开），资源放 `assets/`。
+- 设计交付物路径约定：项目级 `docs/design/DESIGN.md`（**设计 token SSOT**，维护者 uiux-designer，各 feature 只引用其 token，禁内联重声明色板/间距）+ 每 feature `docs/design/[feature]/spec.md`（设计规范）+ `docs/design/[feature]/index.html`（自包含静态原型，Tailwind CDN 或内联样式，可直接 `open` 打开），资源放 `assets/`。设计 token 纪律见 `.claude/standards/coding.md` 设计 token 纪律，reviewer 审查项见 `.claude/agents/code-reviewer.md` 设计 token 审查项。
 - 修改 `.claude/agents/*.md` 的职责或产出时，必须同步检查 `docs/team-capability-map.md`（"主要输出"列）与 `.claude/standards/team-roles.md`（仅当工具/skill/推荐 mode 变更时）。
 - 前后端对接（前端调后端 API；防"按钮没事件 / 契约对不上"两类下游高频缺陷）→ 契约纪律见 `.claude/standards/coding.md` 前后端契约纪律 + [ADR-006](docs/adr/006-frontend-backend-contract-sync.md)（OpenAPI=SSOT，前端走 orval 生成，禁手写 fetch/类型/mock）；测试侧强制覆盖（含交互完整性 + E2E 控件遍历）见 `.claude/standards/testing.md` 前后端对接强制覆盖项。
 - 涉及多 LLM SDK 接入（DeepSeek/Doubao/Qwen/MiniMax 切换、fallback、env 变量）→ 必须先看 skill `.claude/skills/agf-wiring-multi-llm-sdk/`。

docs/design/DESIGN.md

@@ -0,0 +1,106 @@
+---
+# docs/design/DESIGN.md —— 项目级设计系统 SSOT（design tokens）
+# 这是整个项目设计 token 的唯一来源；各 feature 的 docs/design/[feature]/spec.md 与前端实现
+# 只「引用」本文件 token，禁内联重声明颜色 / 字号 / 间距 / 圆角。改 token 改这里一处，全项目生效。
+# 维护者：uiux-designer。技术栈对齐 ADR-000（React + Tailwind）。
+status: Template          # Template = 待首个 feature 落地后由 uiux-designer 把示例值替换为项目实际值；落地后改 Active
+version: 0.1.0
+tokens:
+  color:
+    # 每个可作背景的「主色」必须配一个 on-* 文本色（对比安全，正文 ≥ 4.5:1 / 大字 ≥ 3:1）
+    primary:           "#3B82F6"
+    on-primary:        "#FFFFFF"
+    surface:           "#FFFFFF"
+    on-surface:        "#0F172A"
+    surface-muted:     "#F1F5F9"
+    on-surface-muted:  "#475569"
+    border:            "#E2E8F0"
+    success:           "#16A34A"
+    on-success:        "#FFFFFF"
+    warning:           "#D97706"
+    on-warning:        "#FFFFFF"
+    error:             "#DC2626"
+    on-error:          "#FFFFFF"
+  typography:
+    # 命名按语义层级，不按像素；size / line(行高) / weight
+    display:   { size: 32, line: 40, weight: 700 }
+    headline:  { size: 24, line: 32, weight: 600 }
+    title:     { size: 18, line: 28, weight: 600 }
+    body:      { size: 14, line: 22, weight: 400 }
+    label:     { size: 13, line: 18, weight: 500 }
+    caption:   { size: 12, line: 16, weight: 400 }
+  spacing:
+    # 8pt 基准栅格（md=16 为基准间距）
+    xs: 4
+    sm: 8
+    md: 16
+    lg: 24
+    xl: 32
+    "2xl": 48
+  radius:
+    none: 0
+    sm: 4
+    md: 8
+    lg: 12
+    full: 9999
+  component:
+    # 每个组件显式绑定 bg / text / typography / radius / padding(或 height)，值引用上面的 token
+    button-primary:
+      bg: "{color.primary}"
+      text: "{color.on-primary}"
+      typography: label
+      radius: md
+      height: 48
+    button-secondary:
+      bg: "{color.surface}"
+      text: "{color.on-surface}"
+      border: "{color.border}"
+      typography: label
+      radius: md
+      height: 48
+    input-field:
+      bg: "{color.surface}"
+      text: "{color.on-surface}"
+      border: "{color.border}"
+      radius: md
+      height: 44
+    card:
+      bg: "{color.surface}"
+      border: "{color.border}"
+      radius: lg
+      padding: md
+---
+
+# 设计系统（DESIGN.md）
+
+> 本文件是**项目级设计 token 的单一来源（SSOT）**。各 feature 的 `docs/design/[feature]/spec.md` 与前端实现**只引用本文件 token**，不得内联重声明颜色 / 字号 / 间距 / 圆角。改 token 改这里一处，全项目生效——这是 AGF「单一来源原则」在视觉层的落地（参见 `.claude/standards/document-rules.md`）。
+
+## 1. 对比安全配对（on-* 规则）
+
+每个可作背景的「主色」都必须配一个 `on-<color>` 文本色，且配对满足 WCAG AA：
+
+- 正文 / 小字：对比度 ≥ **4.5:1**
+- 大字（≥ 18px 粗体 或 ≥ 24px）：≥ **3:1**
+
+实现端永远成对取色 `(bg, on-bg)`，从源头杜绝「蓝底蓝字 / 浅灰按钮看不清」。**新增主色时先补 `on-*` 配对再用**。
+
+## 2. Do / Don't（成对，每条禁止都配纠正）
+
+| ❌ Don't | ✅ Do |
+|---|---|
+| 硬编码 `#3B82F6` / `padding: 15px` | 引用 token `{color.primary}` / `{spacing.md}` |
+| 给单个元素写一次性样式 | 引用 / 扩展 `component` token |
+| 主色不配 on-color 直接用 | 先在本文件补 `on-*` 配对再用 |
+| 空数据 / 加载直接白屏 | empty / loading 用空态组件或骨架屏 |
+| 用一堆零散灰阶 | 收敛到 `surface / surface-muted / border` 三档 |
+
+## 3. 最小组件覆盖
+
+任一 feature 落地前，`component` token 至少含：`button-primary`、`button-secondary`、`input-field`、`card`，每个显式绑定 bg / text / typography / radius / padding(或 height)。**新组件先在此登记 token 再用。**
+
+## 4. 维护与引用
+
+- **维护者**：`uiux-designer`。新 feature 若需新 token，先更新本文件，再在 spec / 实现引用。
+- **引用语法**：spec.md 与实现里用 `{color.primary}` / `{spacing.md}` 占位；前端落到 Tailwind / CSS 变量（如 `var(--color-primary)`），不写裸 hex / px。
+- **token → 实现纪律**：见 [`coding.md` 设计 token 纪律](../../.claude/standards/coding.md)；reviewer 按 [`code-reviewer.md` 设计 token 审查项](../../.claude/agents/code-reviewer.md) 审硬编码与 on-* 配对。
+- 字段口径 / 页面级状态语义沿用各 feature 的 `spec.md`；本文件只管全局视觉 token，不放页面结构。