Design Review

App 设计质量审查。关注视觉层级、色彩策略、间距节奏、整体打磨感。与 /ui-review（代码合规）互补。

触发时机

• 完成一个页面/模块的 UI 后
• 对现有页面做视觉优化前，先跑一次摸底
• 用户说"看看设计感"或"review 一下视觉"

流程

1. 确定范围

询问用户或自动识别：

• 指定文件：检查指定的 View 文件
• 指定目录：检查目录下所有 *View.swift、*Screen.swift、*Card.swift
• 无指定：检查本次变更涉及的 UI 文件

2. 加载参考

1. 读取 references/ui-design-principles.md 获取设计原则和精确数值标准
2. 读取 references/apple-ui-checklist.md 的「设计质量」章节获取代码级检查项
3. 如果目标是 macOS 项目（代码含 WindowGroup/MenuBarExtra/NSViewRepresentable/#if os(macOS)），额外读取 ui-design-principles.md section 11b（macOS 平台特定：Window 尺寸、Sidebar、Toolbar）

3. 逐文件 / 逐页面检查

---

Part A: 设计规则（代码可验证）

以下项目通过读代码即可判断。

A1. 视觉层级 — 对比度层级

原则参考：ui-design-principles.md §4 视觉层级

检查页面是否有明确的 3 级字重/字号梯度：

层级	典型用法	代码特征
一级（标题）	页面标题、卡片标题	.font(.title2) / .font(.headline) + .fontWeight(.semibold)
二级（正文）	主要内容	.font(.body)
三级（辅助）	时间、状态、说明	.font(.caption) / .font(.subheadline) + .foregroundStyle(.secondary)

检查项：

• 页面是否存在至少 2 级字重/字号区分？
• 标题与正文是否有明确的视觉差异（字重 ≥ 2 级差 或 字号 ≥ 4pt 差）？
• 辅助信息是否使用 .secondary / .tertiary 降级？
• 是否避免所有文字同一大小同一颜色（= 无层级）？
• 弱化是否通过降低颜色/字重实现，而非单纯缩小字号？（原则 §4.1）
• 数字+标签组合是否正确区分层级？（数字大且粗，标签小且弱化）

A2. 色彩策略

原则参考：ui-design-principles.md §3 颜色系统 注：颜色合规性（语义色、深色模式变体、对比度）归 /ui-review；色彩策略（比例、和谐、种类数）归本命令。

检查项：

• 页面是否有且仅有一个强调色（key color）表示可交互？
• 强调色是否与其他颜色有足够区分（不存在两个相近色同时竞争注意力）？
• 页面颜色种类是否 ≤ 5 种（含语义色）？
• 色彩比例是否符合 App 类型？（工具型：背景 ~80%，辅助 ~15%，强调 ~5%）
• 深色模式下饱和色是否降低亮度避免刺眼？
• 有色背景的 opacity 是否在深色模式下足够可见？（opacity < 0.15 在深色模式下几乎不可见）

代码检查：搜索文件中所有 Color( / .foregroundStyle( / .tint( / .accentColor 调用，统计颜色种类数。搜索 .opacity( 值 < 0.15 的有色背景，标记为深色模式风险。

A3. 间距节奏

原则参考：ui-design-principles.md §2 间距系统

检查项：

• 同级元素之间的间距是否一致？（如所有卡片间距相同）
• 内部间距 ≤ 外部间距？（卡片 padding ≤ 卡片之间的 spacing）
• 是否避免过密排布？（连续的 Spacing.xs 会让界面局促）
• 页面边距是否使用统一值？（通常 16pt）

代码检查：提取文件中所有 .padding() / .spacing() / Spacing.* 值，检查是否存在不一致的同级间距。

A4. 对齐一致性

原则参考：ui-design-principles.md §5 布局原则

检查项：

• 同一列表/容器内的元素是否统一对齐方式？（全部左对齐或全部居中，不混用）
• 多个 VStack 的 alignment 是否一致？
• 卡片/行内的元素是否有清楚的对齐关系？

A5. 卡片与容器

原则参考：ui-design-principles.md §2.3 嵌套圆角、§10.2 卡片规范

检查项：

• 同类卡片是否使用相同的圆角 / 阴影 / 内边距？
• 同类卡片是否使用相同的宽度策略？（全部 .frame(maxWidth: .infinity) 或全部内容自适应，不混用）
• 全宽意图的容器是否有 .frame(maxWidth: .infinity)？ScrollView > VStack/LazyVStack 内的卡片/区块如果有 .background() 或 .clipShape() 但无 .frame(maxWidth:)，且不在 List/Form 内 → 🔴 容器会抱住内容宽度而非撑满。
• 是否存在固定 .frame(width:) 而非 .frame(maxWidth:) 的容器？固定宽度在不同设备上会显示异常。
• 同类卡片的 .background() 颜色/材质是否一致？
• 圆角是否使用设计系统变量（CardStyle.cornerRadius 等）？
• 嵌套容器的圆角是否递减？（外层 16 → 内层 12 → 徽章 8）
• 阴影是否克制？（推荐 opacity ≤ 0.08, radius ≤ 4）
• 卡片内是否有足够 padding（≥ 12pt）不贴边？

代码检查（跨文件）：从当前检查文件的 struct 名提取类型后缀，搜索同后缀组件 Grep("struct \\w+{suffix}", glob: "*.swift")（将 {suffix} 替换为实际后缀），提取每个组件的 .frame( / .padding( / .background( / .clipShape( / .shadow( 修饰符，逐项对比。不一致项标记 🔴。

A6. 图标一致性

原则参考：ui-design-principles.md §10.3 图标规范

检查项：

• 是否统一使用 SF Symbols？（不混用 SF Symbols + 自定义图标风格）
• 同一上下文的图标是否使用相同的 rendering mode（.symbolRenderingMode()）？
• 图标大小在同级元素中是否一致？

A7. 页面构成

原则参考：ui-design-principles.md §16

检查项：

• 页面是否有明确的区域划分（摘要/主内容/操作区），还是一长串无分组的元素？
• 分组是否通过间距差异实现（组间距 > 组内距），而非依赖分隔线？
• 首屏是否在 3 秒内传达页面目的？（需要滚动才能看到核心内容 = 不通过）
• 信息密度是否与页面用途匹配？（设置页紧凑，引导/空状态宽松）
• 不同页面是否有不同的布局密度？（所有页面同一模板 = AI 千篇一律标记）

代码检查：提取文件中所有 .padding() / .spacing() 值。如果一个可滚动页面中所有 spacing 值相同 → 标记"无密度变化"。

A8. Design Token 合规性

检查项：

• 间距是否使用 Design System Token（AppSpacing.* / AppLayout.* 而非硬编码）？
• 颜色是否使用语义色（Color.appPrimary 而非 Color(hex:)）？
• 字体是否使用动态字体（.font(.body) 而非 .font(.system(size:))）？
• 圆角是否使用 Token（AppCornerRadius.medium 而非硬编码 12）？
• 阴影是否符合标准（opacity ≤ 0.08）？

代码检查：搜索硬编码 .padding(N) 或 .spacing(N)，N 不是 4pt 倍数即标记。搜索 Color(hex: / .font(.system(size: 等非 Token 用法。

💡 完成设计审查后，如需完整 Token 合规扫描，单独运行 /validate-design-tokens。

A9. Navigation Depth

检查项：

• Navigation depth ≤3 levels from root? (NavigationStack push count)
• Sheet-in-sheet or modal-on-modal patterns? (>1 level = too deep)
• Can users always navigate back without confusion?

代码检查：Search for NavigationStack/NavigationLink/sheet/fullScreenCover nesting. Count max depth.

A10. Interaction Feedback

检查项：

• Write operations (save, delete, send) have feedback? (haptic, animation, toast, state change)
• Destructive actions require confirmation?
• Loading state visible for async operations?

代码检查：Search for .sensoryFeedback, withAnimation, .alert, .confirmationDialog near save/delete/submit. Flag write operations without feedback.

A11. 弱化优先（De-emphasis over Emphasis）

原则参考：ui-design-principles.md §4.1 — 弱化不重要的信息，比放大重要信息更有效。

检查项：

• 同一 View body 内是否有 2 个以上 .font(.title) 或 .font(.title2)？（= 标题竞争）
• 是否有 2 个以上高饱和色在同一页面竞争注意力？
• 辅助信息是否通过降色/降字重弱化，而非仅靠缩小字号？

代码检查：统计同一 View body 中 .font(.title / .font(.title2 出现次数。>1 且无一个明确更大 → 🔴 标题竞争。

A12. 间距刻度合规（Spacing Scale Membership）

原则参考：ui-design-principles.md §2.1 — 所有间距值基于 4pt 倍数。

检查项：

• 所有 .padding() / spacing: 数值是否在项目 Spacing Token 列表内？
• 是否存在非 4pt 倍数的间距值？（如 13pt、15pt、22pt）
• 同一文件内是否存在 hardcoded 间距值与 Token 混用？

代码检查：提取所有数字型 padding/spacing 参数，检查是否为 4 的倍数且在 Token 范围内。非 4pt 倍数 → 🔴；hardcoded 与 Token 混用 → 🟡。

A-mac. macOS 设计检查（macOS 项目时执行）

仅当 Step 2 判定为 macOS 项目时执行。参考 ui-design-principles.md §11.7-11.9。

A-mac1. Window 尺寸

• 主窗口是否设置了合理的 .defaultSize() 和 .frame(minWidth:minHeight:)？
• 最小尺寸是否不小于 600x400pt（主窗口）/ 480x320pt（设置窗口）？

A-mac2. Sidebar 布局

• Sidebar 是否使用 .listStyle(.sidebar) 获得系统外观？
• Sidebar 默认宽度是否在 200-250pt 范围？
• 选中状态是否使用系统高亮色？

A-mac3. Toolbar 与菜单一致性

• Toolbar 中的操作是否同时在 menu commands 中可达？
• Toolbar 图标是否使用 SF Symbols 且与系统风格一致？

---

Part B: 视觉打磨（人工验证）

以下项目 Claude 无法通过代码完全验证，生成针对性检查清单供用户在设备上执行。

B1. 眯眼测试（Squint Test）

代码预检：统计目标文件使用的 .font() 种类和 .foregroundStyle() 种类数。 ≤ 1 种字号 + ≤ 1 种前景色 → "无层级，眯眼测试大概率不通过"

请在设备上执行：
半闭眼睛看页面，回答：
- [ ] 能否分辨出 3 个层级（标题 / 内容 / 辅助信息）？
- [ ] 主操作按钮是否是页面最突出的元素？
- [ ] 是否有某个区域过于密集或过于空旷？

B2. 对齐审查

请在设备上执行：
截图后用标尺/参考线工具检查：
- [ ] 所有内容块的左边缘是否对齐到同一条线？
- [ ] 卡片/列表项之间的间距是否均匀？
- [ ] 是否存在"差 1~2pt"的微妙不对齐？

B3. 色彩感知

请在设备上执行：
- [ ] 把手机调为灰度模式（辅助功能 → 色彩滤镜 → 灰度），页面层级是否仍然清晰？
- [ ] 切换深色模式，卡片/背景层级是否可辨？
- [ ] 页面整体色调是否和谐（没有某个颜色突兀跳出）？

B4. 留白与呼吸感

请在设备上执行：
- [ ] 页面是否有"喘息空间"？（内容区域不贴屏幕边缘，组之间有留白）
- [ ] 信息是否分组清晰？（相关内容靠近，不相关内容有明确间隔）
- [ ] 首屏内容是否过多导致拥挤？

B5. 动效与过渡

请在设备上执行：
- [ ] 页面切换是否流畅？有无掉帧？
- [ ] 元素出现/消失是否有过渡动画（而非闪现）？
- [ ] 动画时长是否适中？（太快 < 200ms 看不到，太慢 > 400ms 感觉卡）
- [ ] 是否尊重「减少动态效果」设置？

B6. 首屏印象

请在设备上执行（冷启动或首次进入该页面）：
- [ ] 第一眼看到的是内容还是空白/loading？
- [ ] 骨架屏或占位是否合理？
- [ ] 页面整体是否给人"精致"还是"粗糙"的感觉？

---

4. 输出报告

## Design Review Report

### 检查范围
- [文件列表]

### Part A: 设计规则（代码验证）

#### 🔴 必须修复
- [file:line] 问题描述
  现状：{当前代码}
  建议：{修复方案}

#### 🟡 建议优化
- [file:line] 问题描述
  建议：{优化方案}

#### ⚪ 通过
- {通过的检查项摘要}

### Part B: 设备验证清单

基于代码分析，建议在设备上验证以下项目：

#### 眯眼测试
- [ ] {针对该页面的具体检查点}

#### 对齐审查
- [ ] {针对该页面的具体检查点}

#### 色彩感知
- [ ] {针对该页面的具体检查点}

#### 留白与呼吸感
- [ ] {针对该页面的具体检查点}

#### 动效与过渡
- [ ] {针对该页面的具体检查点}

### 总结
- 检查文件数：N
- 设计规则问题：N（🔴 X / 🟡 Y）
- 设备验证项：N
- 💡 完成设备验证后，标记各项通过/不通过，再决定是否需要调整

---

严重度定义

级别	定义	示例
🔴 必须修复	明显破坏视觉层级或一致性	无层级区分（所有文字同大小同颜色）、卡片圆角不统一、颜色竞争（两个强调色）
🟡 建议优化	不破坏但可提升	间距不完全一致、阴影偏重、图标风格略有混用
⚪ 通过	符合设计质量标准	-

---

原则

1. 代码可验证的先验证：Part A 的结论必须基于代码证据（文件:行号）
2. 不伪装视觉判断：Part B 明确标注需要设备验证，不猜测视觉效果
3. 具体到页面：Part B 的检查项根据代码分析定制，不照搬通用模板
4. 与 /ui-review 不重复：本命令不检查状态完整性、无障碍标签、交互防护等 /ui-review 已覆盖的项目
5. 设备验证闭环：报告末尾提醒用户完成设备验证并反馈结果

5. 用户确认（必须执行）

报告输出后，禁止自行修改被审查文件。必须使用 AskUserQuestion 让用户选择：

• 选项从 Part A 的 🔴 和 🟡 发现中生成
• 用户确认后，仅修复用户选中的项目
• 用户未确认 = 不动代码

Completion Criteria

• 报告包含 Part A（设计规则，代码验证）和 Part B（视觉打磨，设备验证清单）
• Part A 每个发现附 file:line 引用
• Part B 检查项根据代码分析定制（非通用模板）
• 修复动作经过用户 AskUserQuestion 确认