From 997bbfb78f7e09e450f6c3eb0e32132543f9f4e9 Mon Sep 17 00:00:00 2001 From: pcliangx Date: Wed, 17 Jun 2026 17:49:42 +0800 Subject: [PATCH] =?UTF-8?q?feat(design):=20=E5=BC=95=E5=85=A5=20DESIGN.md?= =?UTF-8?q?=20=E8=AE=BE=E8=AE=A1=20token=20SSOT=20+=20=E7=8A=B6=E6=80=81?= =?UTF-8?q?=E8=A6=86=E7=9B=96=20+=208=20=E7=BB=B4=E4=BA=A4=E4=BB=98?= =?UTF-8?q?=E8=87=AA=E6=9F=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit P0 — 项目级设计 token 单一来源: - 新增 docs/design/DESIGN.md(YAML token + on-* 配对 + Do/Don't + 最小组件覆盖) - uiux-designer spec 引用 token、禁内联硬编码 - coding.md 增「设计 token 纪律」；code-reviewer 增「设计 token 审查项」 - CLAUDE.md / repo-layout / team-capability-map 三处同步 P1 — 状态完整性 + 设计侧前置门: - spec 新增「页面/模块状态覆盖」(loading/empty/error/permission) - 原型要求扩成组件态+产品态；新增「交付前自查(8 维)」 - testing.md「视觉达标」口径扩成全状态(保留「读图四查」术语不改) 借鉴 xianxin-design-workflow 的 DESIGN.md token 体系与 8 维验证框架。 --- .claude/agents/code-reviewer.md | 10 +++ .claude/agents/uiux-designer.md | 59 ++++++++++++++---- .claude/rules/repo-layout.md | 3 +- .claude/standards/coding.md | 9 +++ .claude/standards/testing.md | 2 +- CLAUDE.md | 2 +- docs/design/DESIGN.md | 106 ++++++++++++++++++++++++++++++++ docs/team-capability-map.md | 2 +- 8 files changed, 178 insertions(+), 15 deletions(-) create mode 100644 docs/design/DESIGN.md diff --git a/.claude/agents/code-reviewer.md b/.claude/agents/code-reviewer.md index 9a58d25..dca914d 100644 --- a/.claude/agents/code-reviewer.md +++ b/.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. **正确性** — 代码是否做了它应该做的？ diff --git a/.claude/agents/uiux-designer.md b/.claude/agents/uiux-designer.md index 5de3fb4..e8b67d4 100644 --- a/.claude/agents/uiux-designer.md +++ b/.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 或内联 `