# 2026-05-11 — Mockup Conventions Trifecta Rule Update

> **Plan-owner 视角复盘**。SaaS Dashboard chart build 踩坑细节由 MicroApps session 自己 wrap-up 写；本文档聚焦三规则改动的设计决策与 cross-reference 互锁。
> **Commit**: `210d3ada` (master, push 2026-05-11)
> **改动文件**: `docs/internal/mockup-conventions.md` (+117 / -4)

---

## 触发

MicroApps Console session 准备 Cost per Token Trend mockup 前，pre-step SaaS Dashboard chart 暴露三规则同时盲点：

1. **AI 抄 user 发的数据参考截图主色（紫）** → 把数据样例截图当 spec 抄 → 违 M14
2. **没 probe sibling page 视觉合同**（实际 sibling chart 用绿 + area chart） → 违 M21 字面执行
3. **跳过 PRD "feel more like business health indicator rather than technical monitoring graph" design ask** → 把 user 显式视觉哲学需求降级成"AI 觉得用户想要什么" → M22 未存在，是 rule gap

单一规则不够防 trifecta；需新增 + 扩展 + 互锁。

---

## 三规则改动

### M22（新）— User Design Intent Acknowledgment

**位置**：Pre-Phase 0 段之前，作为"painting / Phase 0 mapping 前的 entry gate"。

**关键设计决策**（plan-owner review propose 调整点）：

| 议题 | executor 草案 | 最终采纳 | 理由 |
|---|---|---|---|
| 位置 | Process Rules 段（M9 之后） | Pre-Phase 0 之前独立段 | M9 不是 Hard Rules 最后一条（M10 才是）；M22 实质是 entry gate，与 Pre-Phase 0 同层；放 Process Rules 会被 US-3 触发场景漏看 |
| 命名 | "PRD design ask" | "User Design Intent" | 本仓库习惯不写 "PRD"（对话片段为主，无正式 PRD 文档） |
| 触发词 | 仅英文 | 中英双语 + 用户感受/品牌调性描述 | 用户经常中英混用；"vibe" 业务用户极少用，去掉 |
| Gate 形态 | 一律独立 gate 对账 | **小 ask（< 3 条）合并 Phase 0 Gate 1 / 大 ask（≥ 3 条 或 跨页全局调性）独立 gate** | 小 PRD 独立 gate 过重；合并进 mapping table 上方 "Design intent acknowledgment" 段更轻 |
| 作用域 | Pre-Phase 0 触发 | **US-1 / US-2 / US-3 全部触发，不限 entry mode** | US-3 增量也有 design ask，不能因 Pre-Phase 0 跳过而漏 |

### M14 — 范围扩到"任何参考输入"

**位置不动**（仍在 "反 B — Lazy mental model" 段），改 3 点：

1. 标题 `复刻原 mockup 任一元素前必问适配性` → `复刻任何参考输入前必问适配性`——范围扩到 user 截图 / competitor 截图（user 发的截图打擦边球漏网是实战盲点）
2. 加 **"高频被误抄字段"独立 lookup 表**（Color #1 / Chart type / Opacity / Layout 密度）——独立成段优于合进实证踩坑（叙事 vs 表 lookup 用途不同）
3. 实证踩坑加 2026-05-11 SaaS Dashboard chart 三连发实证

### M21 — 加"起手 mandatory probe（Sibling visual contract）"段

**位置**：M21 决策树段之后、例外段之前。

**关键设计决策**：

| 议题 | executor 草案 | 最终采纳 | 理由 |
|---|---|---|---|
| Probe 维度 | 4 维度（color / chart / 密度 / header） | **6 维度（+ typography + icon style）** | dashboard 类页面 font weight 不一致 / icon style mismatch 是高频跨页割裂源 |
| Probe 输出位置 | 写进 Phase 0 mapping 表头 | **单起一段叫 `Sibling visual contract` 放 mapping table 上方** | sibling contract（视觉合同 = constraint）≠ element mapping（implement plan），语义上分开；表头会被淹没 |
| Probe 工具术语 | `get_design_context` | 保留 | mockup-conventions 多处已绑 Figma MCP（`search_design_system` / `findAll(INSTANCE)`），术语一致 |
| 决策树 callout | 无 | **加 "前置 M22 check" callout** | M22 显式 override 时跳过第 1 步（不强制 instance/mirror sibling） |

---

## Cross-reference 互锁机制

三规则不是孤立列表，要 **互相 link** 让未来 review 能从任一条找到完整案例：

- **Convention Priority Hierarchy** 示例列表加 `M22 > M21`（line 64）
- **M22 § 与既有规则关系** 写 `M22 > M21 > M14`，cross-reference M14 踩坑段 + M21 probe 反例段
- **M21 § 起手 mandatory probe** 写 `user PRD design ask（M22）是 override 唯一合法源`
- **M14 § 与既有规则关系** 写 `M22 > M14` + `M14 + M21 双层防线`（M14 防"参考输入当 spec"，M21 防"sibling 合同没 probe"）
- **历史背景段** 加 2026-05-11 entry，写明 "**M14 / M21 / M22 三规则同时违反**"

---

## Meta lesson — Single-rule defense 不够防 build trifecta

| Lesson | 落实点 |
|---|---|
| 同一 build 错误可踩多条规则盲点，单一规则补强不够 | 三规则联动 cross-reference + Hierarchy 示例 |
| User 显式 design ask 是最高优先级输入，必须有独立 acknowledge gate；不能默认靠 M14（"截图不是 spec"）兜底——M14 防的是误抄，不是 acknowledge 缺失 | M22 新规则诞生 |
| Sibling visual contract 是"产品视觉认知合同"，M21 决策树告诉"用谁"但没强制"先 probe 出数值"，肉眼判断会漏 | M21 加 mandatory probe 6 维度 |
| 参考输入范围不限"原 mockup"——user 发的截图 / competitor 截图同样易被当 spec | M14 标题与首段范围扩展 |
| 规则之间必须 cross-reference，否则未来 review 从任一条找不到完整案例 | Hierarchy 示例 + 三规则的"与既有规则关系"段都写 link |

---

## 后续观察点

- **MicroApps session 实战检验**：Cost per Token Trend mockup 是 M22 / M21 probe / M14 ext 三规则上线后第一次 US-3 build，看是否能：
  - 起手 acknowledge user "Annual YTD" / "30-day YOY" 等设计决策的 design ask 含义
  - 起手对 sibling 1641:2213 probe 出 6 维度 visual contract（color / chart / typography / icon style / 密度 / header）
  - 不抄 user 之前给的数据参考截图当 spec
- **MicroApps session wrap-up retrospect** 应**只写 build 第一手细节**（具体抄了什么紫色 / sibling 实际什么绿 / 哪步漏 probe），不重复本文档已记录的规则设计决策。
- 若 Cost per Token Trend build 暴露**新**盲点（M22 / M21 probe / M14 ext 没 cover 的），触发第 4 条规则或第 4 块扩展。

---

## 元规则补强（可选 future improvement）

- **Plan-owner review 模式协议**: 三规则联动改动，executor 草案分块 propose + plan-owner 逐块改/留/调反馈，最终 plan-owner 直接 commit 的范式跑通——这次 plan-owner 直接 edit + commit 没回退给 executor 改，因为 executor session 已在跑别的 task（任务 2 build / 任务 1 verify）。考虑在 meta-rules.md 加一条：**规则文档更新类任务 plan-owner 可直接执行 edit + commit，无需 executor 中转**（违 single-source-of-truth 反模式 #3 风险低，因 conventions 文档就是 plan-owner 真源职责）。