---
name: design-walkthrough
description: F1 Design Walkthrough — structured 6-section audit of a mockup or code deliverable against PRD, sibling visual contract, rule compliance, anti-patterns, and data feasibility. Triggered by "design walkthrough", "走查这个设计", or "audit this design".
---

# Design Walkthrough Agent (F1)

> **触发词**：`design walkthrough` / `走查这个设计` / `audit this design`
> **Inputs**：design deliverable（mockup node-id / code path）+ PRD + discovery output（若有）+ 适用规则集
> **Tools**：Figma MCP（Path A）/ Read / Bash
> **Output**：结构化 walkthrough report（见下方格式）

---

## 使用方法

```
design walkthrough <node-id or file path>
PRD: <link or inline>
Rules: <mockup / code / both>
```

---

## Step 0: Page Type 分类（必做，决定 rule set + section 触发）

| Page Type | 判断条件 | 额外规则 | Data Audit |
|---|---|---|---|
| **Business Dashboard** | 含 chart / KPI metric / financial / derived value | — | 默认触发 |
| **Monitoring / Operator Console** | 含 session status / real-time control / alert | M3 / M4 / M7 | 含 derived value 时触发 |
| **Settings / Form** | 含 input / form / config panel | — | 跳过 |
| **Navigation / Landing** | 顶层导航 / 空态 / 入口页 | — | 跳过 |
| **Design System / Component Spec** | variant matrix / component set / 多态规格页（非单一产品页面） | M-VARIANT-CONSISTENCY / M-IA-ONE-HOME | 跳过 |

> Component Spec 场景：Section 1 的 "sibling contract" 改读作「内部跨变体契约」——参照系是同组件集内的其它变体，而非外部 sibling 页面。

---

## Walkthrough Report 格式

```markdown
# Design Walkthrough Report — <Deliverable Name>

**Date**: YYYY-MM-DD
**Deliverable**: <node-id / file path>
**Page type**: <Business Dashboard / Monitoring / Settings / Navigation>
**PRD reference**: <link>
**Rules applied**: design-process.md + domain-tvu.md + <path-specific conventions>

---

## 0. Axis Execution Ledger（必填 — invariant：声明即消费，轴级不可静默省）

> 三轴每一轴必须有 FIRED / SKIPPED 判定 + 理由。SKIPPED 仅允许两类理由：① Step 0 page-type gate 明确排除；② 该轴维度对本交付物不适用（须具体写明）。**漏填任一轴 = 协议违反**（report body 里 N/A 的细分子表可省，本 ledger 不可省）。

| 轴 | 覆盖 section | FIRED / SKIPPED | 理由 / 触发依据 |
|---|---|---|---|
| **轴① 系统一致性** | §3 D1/D2 + §5.7 D6/D9/D13 + D16 绑定保真 | ✅ / ⏭️ | <例：多变体→§3 fired；D16 见下方机检> |
| **轴② 既有 6-section** | §1–§6 本体 | ✅ / ⏭️ | <主循环无条件 fired；§5 Data Audit 按 Step 0 触发> |
| **轴③ 视觉质量** | §5.5 + §5.6 + §5.8 | ✅ / ⏭️ | <例：≥2 反馈元素→§5.5 fired> |

### Report Completeness Gate（必填 — 防"只机检不判断"，mirror keystone 落地）

> 报告交付前自检：判断轴**每条必须有 ≥1 实质 finding**（具体 assessment + evidence，非裸 `✅`/`N/A`）。任一行 NO = 走查不完整、协议违反、重做该轴。**整份报告实质内容只有机械维度（机检 pass/fail）而本 gate 任一判断轴空 → 直接判不合格。**

| 判断轴 | 有实质 finding？（非裸 ✅/N/A）| 证据指针（section + 一句话 finding 摘要）|
|---|---|---|
| §2 PRD/User Story 覆盖率 | YES / NO | <例：US-3 "查看角色" partial——缺 Finance 视图> |
| §4 Anti-pattern Scan | YES / NO | <例：未发现 / 发现"参考图当 spec"> |
| §5.6 强调预算 + 视觉权重 | YES / NO | <例：卡 #3 超预算 2 语义色行> |
| §5.7 a11y / 运行态 / 主题对等 | YES / NO | <例：D9 缺 empty/error 态设计> |
| §5.8 视觉质量（B1/B2/B5/B6/B7）| YES / NO | <例：B5 留白组内>组间，节奏乱> |

> SKIPPED 仅当对应轴在上方 Axis Execution Ledger 已判 SKIPPED（page-type gate 排除 / 维度不适用）且写明理由；否则 NO = 必须补做。

> **D16 专项**：token 绑定保真不靠走查目测——在"理由"列记机检结果（`pnpm audit:mockup-binding-fidelity --file <key>` / conformance gate 的 pass/fail），或显式记 `deferred-to-conformance-gate`。不允许因"走查不目测"就当 D16 不存在（declared≠consumed 反例）。
>
> **机械维度证据化（keystone，2026-06-17 新增）**：D16 的"不靠目测、贴机检结果"模式**泛化到全部机械可判维度**——M32 库归属(`audit-mockup-library-origin`)、M-COLOR(`audit-mockup-colors`)、M52 binding(`audit-mockup-binding-fidelity`)、**M-INTEGRITY block 叠加(`audit-mockup-overlap`)**、**M23.14 双语堆叠行距(`audit-mockup-bilingual-spacing`)**、M-VARIANT 像素一致。一次 `pnpm audit:mockup-conformance --file <key> --node <id>` 跑齐上述机检（连线正交另跑 `use_figma` M23.6 probe，REST 不可机检）。**这些维度的判定列必须贴对应机检 gate 的 pass/fail（含审计原文片段），禁止靠目测 / 记忆打 `✅` 或 `N/A`**；无 gate 输出的机械维度**视为未走查（协议违反）**。机检 gate 的 `--node` 必须覆盖**本 session 触碰的所有节点**，不止新建物。**走查是 §M-LIFECYCLE 第三时点（兜底全扫）——前两时点（操作前 probe / 操作后即时机检）见 mockup-conventions §M-LIFECYCLE。****实证 2026-06-17 BM-1047 V3**：走查只目测审了新建弹窗、把 M32/M-VARIANT 打 `✅`/`N/A`，漏了改过的下拉按钮非组件 + 跨态不一致 + 角色标记不一致——`library-origin`/`binding-fidelity` 早能抓到，但没在走查时跑，最后靠用户手工逐条指出。
>
> **判断轴不可被机检替代（mirror keystone，2026-06-18 新增 — 与上条镜像对称）**：机检证据是**必要不充分**。走查的实质是**设计判断**——§2 PRD/US 覆盖、§4 anti-pattern、§5.6 强调预算/视觉权重、§5.7 a11y/运行态/主题对等、§5.8 视觉质量（层级/密度/留白/可扫描/渐进披露）。**这些判断轴必须各有实质 finding（带具体 assessment / evidence，非裸 `✅` 或 `N/A`）**。一份报告若实质内容**只剩机械维度**（库归属 / binding / overlap / 像素一致 / reparent 坐标等），而判断轴**缺席 / 全空 / 全 `✅` 无 evidence** → **走查不完整 = 协议违反**。上条防"跳机检靠目测"，本条防"只跑机检、跳设计判断"——**机检既不能跳、也不能拿来顶替设计判断**。**反例 2026-06-18**：被要求"按 TVU 流程走查并给报告"，产出却是**工程实现层验收**（reaction 参数 / reparent 坐标 / 库归属机检）——把一轴的机械底料当成整份走查，§2 PRD 覆盖 / §5.6 / §5.8 判断轴全缺。走查读者是评判"设计对不对"的 PM/QA/dev，不是验"实现接对没接对"。

---

## 1. Sibling Visual Contract 一致性（M21 check）

- Sibling probed: <page node-id>
- Contract: Color <token>, Chart <type>, Typography <spec>, Icon <style>, Density <values>, Header <structure>
- Findings:
  - ✅ / ❌ <element>: <assessment>

## 2. PRD + User Story 覆盖率

> 多 US 场景：分两个 sub-table；单 US 场景：合并为一张表。

| 需求 / User Story | Deliverable 对应 | 覆盖状态 |
|---|---|---|
| <PRD requirement / "As X I want Y"> | <element> | ✅ covered / ⚠️ partial / ❌ missing |

Coverage: X / Y items (Z%)

## 3. Rule Compliance

> 只显示 page type 适用的 rule rows。

| Rule | Check | Status | Evidence |
|---|---|---|---|
| M14 Reference adaptation | Probe 参考输入 context 维度 | ✅ / ❌ | <detail> |
| M16 Default evaluation | 所有 source component defaults 被评估 | ✅ / ❌ | <detail> |
| M21 Sibling contract | probe 数值已做 | ✅ / ❌ | <detail> |
| M22 Design intent | user ask 被 acknowledged | ✅ / ❌ | <detail> |
| M11 Self-audit | probe 数值 vs reference | ✅ / ❌ | <detail> |
| M-LIFECYCLE-CRUD | first-class entity 的 Create / Read / Update / Delete 4 项是否都有显式答案（任一项"故意没有"必须写明 rationale） | ✅ / ❌ | <detail> |
| M6 Reusable pattern | 是否发现新 reusable pattern | ✅ none / 🟡 found: <name> | <detail> |
| M-VARIANT-CONSISTENCY | 多变体交付物逐变体**像素级**核对：对齐基线、内边距/间距、前导图标垂直锚点、close 键基线——内容行数变化（2 行 vs 3 行）时锚点规则须跨变体统一，不允许某一态独自居中而其余顶对齐 | ✅ / ❌ | <detail：列出离群变体 node-id> |
| M-IA-ONE-HOME | 同一语义角色（如"通知/消息"）的所有形态归属一致：若拆在多个组件集，须交叉引用且消解命名重叠（组件名 ≠ 内部某一 status 标签） | ✅ / ❌ | <detail> |
| Section 结构（design-process ①）| 交付物收进具名 Section（不散落 page）；**BEFORE 与 AFTER 分属不同 Section**（PRD/Jira/UX 卡可同 Section，但 BEFORE≠AFTER）。**N/A = 本交付无 before/after 对比（如全新页 US-1/2），只判"是否收进具名 Section"** | ✅ / N/A / ❌ | <detail：列出 BEFORE/AFTER 各自 Section id；N/A 时写明无对照态> |
| M3 Status colors（Monitoring only）| 红=Live / 绿=Active 遵守 | ✅ / N/A | <detail> |
| M4 Dark theme（Monitoring only）| monitoring 页面 dark only | ✅ / N/A | <detail> |
| M7 Control surface（Monitoring only）| actions > identifiers > status | ✅ / N/A | <detail> |

## 4. Anti-pattern Scan（meta-rules.md）

| Anti-pattern | Found? | Location |
|---|---|---|
| 规则正文枚举特例 | ❌ / ✅ found | <detail> |
| 参考输入当 spec | ❌ / ✅ found | <detail> |
| 未评估 default 直接交付 | ❌ / ✅ found | <detail> |
| 只查语义不查像素（颜色/图标对了就放行，未核对对齐/间距）| ❌ / ✅ found | <detail> |
| 同一角色拆多组件集却无统一分类/交叉引用 | ❌ / ✅ found | <detail> |
| BEFORE 与 AFTER 塞进同一 Section（对比方难并排 review/导航）| ❌ / ✅ found | <detail> |

## 5. 数据可行性 Audit

> Business Dashboard：默认触发。Monitoring / Operator Console：含 derived value 时触发。Settings / Navigation：跳过。

| Metric / Value | 数据来源 | 可行性 | Notes |
|---|---|---|---|
| <metric name> | <source> | ✅ real / ⚠️ estimated / ❌ undefined | |

## 5.5 Feedback UI Inventory（固定层，M52.3）

> 把全部反馈类 UI 按语义类拉清单，同类必同源。任何 mockup 含 ≥2 个反馈元素即触发。

| 类（toast / inline alert / modal notification / popover hint）| 成员 | component 源 | 宽/padding | close | action | icon/title 规则 | 判定 |
|---|---|---|---|---|---|---|---|
| <class> | <members> | ✅ 库 set+variant / ❌ 自画 | <values> | — | — | — | ✅ 同源 / ❌ 断层 |

## 5.6 强调预算 + 视觉权重横向对比（固定层，M52.4）

> 每卡 ≤1 语义色状态行 + ≤2 灰 hint + 1 主 CTA；横向对比数行数/彩色元素 vs 同 lane 中位数。

| 卡 | 信息行 | 语义色行 | 灰 hint | 彩色元素合计 | vs lane 中位数 | 判定 |
|---|---|---|---|---|---|---|
| <card> | N | N | N | N | ± | ✅ / ❌ 超预算 |

## 5.7 系统一致性补充轴（固定层，D6 a11y / D9 运行态 / D13 主题对等）

> 第一轴系统一致性的 mockup-reviewable 维度（取自 [`consistency-dimensions-audit-2026-06-12`](../../docs/internal/retrospection/consistency-dimensions-audit-2026-06-12.md)）。**D1 跨变体 / D2 跨组件**已在 §3 Rule Compliance（M-VARIANT-CONSISTENCY / M-IA-ONE-HOME）；**D16 token 绑定保真**由 conformance gate `audit-mockup-binding-fidelity` 机检。本层补 D6/D9/D13。

| 维度 | check | 判定 |
|---|---|---|
| **D6** a11y 范式 | 同类组件 focus/键盘可达、对比、th scope、tooltip 键盘做法是否一致 | ✅ / ❌ / N/A |
| **D9** 运行态 | empty / loading / error / 0-data / 无权限 / 超长文本 各态是否设计（"故意无"须写 rationale） | ✅ / ❌ / N/A |
| **D13** 主题对等 | dark + light 都验、无破一主题的 token | ✅ / ❌ / N/A |

## 5.8 视觉设计质量轴（固定层，B1/B2/B5/B6/B7）

> 第三轴 visual-quality（senior 设计师走查），尺子见 [`visual-quality-dimensions-2026-06-12`](../../docs/internal/visual-quality-dimensions-2026-06-12.md)。**B3 强调预算 + B4 视觉权重**已在 §5.6（M52.4）；本层补其余 5 维。

| 维度 | check（可测） | 判定 |
|---|---|---|
| **B1** 视觉层级 | 字号聚 ≤3 档、相邻 ≥1.25× | ✅ 分明 / ❌ 糊 |
| **B2** 信息密度 | 无 chartjunk、密度档单屏统一 | ✅ / ❌ |
| **B5** 留白节奏 | 组内 < 组间、同级间距取 token 倍数 | ✅ / ❌ |
| **B6** 可扫描性 | 主 CTA / 关键状态在 F/Z 扫描起点 | ✅ / ❌ |
| **B7** 渐进披露 | 低频 / 高级收二级、破坏性操作不裸露同级 | ✅ / ❌ |

## 6. Recommended Next Actions

| Priority | Action | Owner |
|---|---|---|
| 🔴 High | <action>（auto-fix candidate） | AI |
| 🟡 Medium | <action>（需用户决策） | User → AI |
| 🟢 Low | <action>（defer 候选） | User |

---

**Walkthrough complete.** Issues found: <N> high / <N> medium / <N> low.
```

---

## Agent 执行协议

1. **Step 0**: 判断 page type → 确定 rule set + Data Audit 触发条件
2. **Read design deliverable**: 用 `get_design_context`（Path A）或 `Read`（Path B）
3. **Probe sibling**（US-3 场景）: 取 sibling visual contract M21 probe 6 维度
4. **PRD + US coverage**: 对照 PRD 逐条检查；单 US 合并进同一张表
5. **Rule compliance**: 按 page type 子集逐条 check，加 M6 新 pattern 扫描
   - **多变体/组件集交付物**：必须逐变体抓代表态细图（不同 type × 不同内容行数各取样），做 M-VARIANT-CONSISTENCY 像素级对齐核对——语义（颜色/图标/按钮）查完后**不要止步**，对齐/间距/锚点是独立一轮。
6. **Anti-pattern scan**: 对照 meta-rules.md § 3
7. **Data audit**（按 Step 0 触发条件决定是否执行）: 验证 derived metric 数据来源
8. **三轴固定层全跑（§5.5–§5.8，invariant：声明即消费，不只列在 report 格式里）**：
   - 轴① 系统一致性：§3 的 D1/D2（变体/组件）+ §5.7 的 D6/D9/D13 + D16 绑定保真（跑 `audit-mockup-binding-fidelity` 或 conformance gate）
   - 轴② 既有 6-section（§1–§6 本体）
   - 轴③ 视觉质量：§5.5 反馈 inventory（M52.3）+ §5.6 强调预算/权重（M52.4 = B3/B4）+ §5.8 的 B1/B2/B5/B6/B7
   - page type 仍 gate 子集（§Step 0）：外科手术档只触发命中维度，整张 mockup 才全跑
   - **完成后必填 §0 Axis Execution Ledger**：逐轴记 FIRED/SKIPPED + 理由。整张 mockup 默认三轴全 FIRED；因 page-type gate / 外科手术档而 SKIPPED 的轴必在 ledger 写明理由——**不允许默默不跑某轴**（"声明即消费"的可验证落点）
9. **Output report**: 按上方格式输出。**§0 Axis Execution Ledger 必填、不可省**——report body 里 N/A 的细分子表可省，但每轴的 FIRED/SKIPPED 判定必须在 ledger 留痕（静默漏轴 = 协议违反）

**不做**：不修改 deliverable，不生成新 deliverable，不产新规则——只输出 report。