# Design Process — Shared Conventions

> **通用 process 原则**，path-agnostic，适用于 Path A（Figma mockup）和 Path B（代码生成）。
> 语言 voice-neutral：不说 "画"、不说 "写"，统称 "生成 deliverable" / "采用 source 组件"。
>
> **不包含**：TVU 业务规则（→ [`domain-tvu.md`](./domain-tvu.md)）/ Figma API quirks（→ [`figma-technical-reference.md`](./figma-technical-reference.md)）/ Path 专属细节（→ [`mockup-conventions.md`](./mockup-conventions.md) / [`code-conventions.md`](./code-conventions.md)）。

---

## Convention Priority Hierarchy

| 级别 | 来源 | 何时引用 |
|---|---|---|
| **P0 最高** | TVU 项目级硬规则（[`AGENTS.md`](../../AGENTS.md) 硬规则 #1-#N）| 任意 TVU 相关任务 |
| **P1** | TVU consumption conventions（本文件 + path-specific conventions）| 消费 TVU 库时 |
| **P2** | `role-ux` skill UX guidance | Pre-Phase 0 / UX 判断 |
| **P3 兜底** | 通用 UX heuristics（Nielsen / WCAG / 平台惯例）| TVU 未覆盖的判断 |

高优先级胜出。TVU 未规定 → P3 兜底，**不停下追问**。

---

## M22 — User Design Intent Acknowledgment（前置 Gate）

任何 deliverable 生成前，先检测用户 brief 是否含 design direction 类语句。

**触发信号词**：`feel like` / `should feel` / `design proposal` / `direction` / `tone` / "感觉像" / "整体方向" / "调性" / "business health" / "commercial feel"

**不触发**：纯 element 清单（"加 button" / "table 加一列"）。

### 必做（任何 Phase 0 mapping 前）

1. AI 复述 user 的 design ask 为 bullet list（原话直引 + 一句话解读）
2. 每条 ask 映射到具体 deliverable decision（color / structure / element 取舍 / information hierarchy）
3. 按 ask 数量分支：
   - **小 ask（< 3 条）**：合并进 Phase 0 mapping，作为上方 "Design intent acknowledgment" 段一起对账
   - **大 ask（≥ 3 条 或 跨全局调性）**：独立 gate — 复述发给 user 确认后才进 Phase 0

### Why

User design ask 是 deliverable 视觉合同的最高优先级输入。跳过 = 把"用户想要什么"降级成"AI 觉得用户想要什么"。

### 优先级关系

**M22 > M21 > M14**：user 显式 design ask override sibling 视觉合同（M21）；override 参考输入（M14）。

---

## Pre-Phase 0：Product Definition Gate

**触发条件**：用户给的是高层产品 / 页面 brief，element 未列出。

**进入时同步 load `role-ux` skill** — Pre-Phase 0 内的功能假设 / UX flow 提案带上 role-ux 的判断、直播行业惯例、a11y、中英双语文案 discipline。

**不触发**：用户已给完整 element 清单 / 已有 handoff 定义 scope / artifact→deliverable mirror 任务。

### Step A — Intake Gate（3 输入收集，mandatory）

任何消费产品 mockup 任务起手第一步：**先收齐 3 项输入**，再进 Step B。

| # | 项 | 必填 | 说明 |
|---|---|---|---|
| 1 | 参考链接 / 图片 / 文件 | 可选 | 竞品链接、截图、PRD 草稿、Notion / Jira 等任意组合 |
| 2 | 修改到目标 Figma 链接 | **必填** | 完整 `figma.com/design/<fileKey>/...?node-id=<id>` URL，含 node-id 最佳 |
| 3 | 功能需求 | **必填** | 一句话目标 + 关键 user story / 场景 |

**反模式**：用户只给一句"做个 X 页面"就直接进 5 步流程 → 缺 Figma 落点 + 缺验收锚 → PRD 漂浮在对话里。

### Step B — PRD 起草 + 写入目标 Figma

收齐 3 输入后：

1. **AI 整理 PRD 草稿**（中英双语 UX 说明样式）发到对话里，结构：
   ```
   ## <页面名> / <Page Name>
   ### 目标 Goal — 中文一句 / English one-liner
   ### 用户故事 User Stories — US-1..N 中英对照
   ### 关键元素 Key Elements — 元素 + TVU library 候选组件（Phase 0 待验）
   ### 非目标 Non-goals — 中英对照
   ```
2. ⏸ **Gate A**：用户确认 PRD 文本无误（可多轮迭代）
3. **AI 写入目标 Figma**（加载 `figma-use` skill）：
   - **落位约定**：在目标 frame **左侧** 创建独立 frame，命名 `PRD - <页面名>`，宽 400px，Auto Layout vertical
   - 样式沿用 TVU 既有 UX 说明 frame 范式（标题层级 / 段落 / 双语并列）
   - 写完报告 frame node 链接给用户
4. ⏸ **Gate B**：用户确认 Figma 上 PRD frame OK，才进 Step C

**Why PRD 上 Figma**：PRD 固化在设计文件而非对话里 → 跨 session 可查 / 跨人可分享 / 设计交付 + 产品 spec 同位置；中英双语保证 TVU 全球团队可读。

### Step C — 5 步流程（两个用户 gate，原有内容）

1. AI 提功能假设清单（核心 MVP + 增值，条数按产品复杂度自决）
2. ⏸ **Gate 1**：用户校功能假设，确认 MVP scope 后才进 Step 3
3. AI 提 UX flow 草稿（bullet list；复杂产品升级 ASCII / Mermaid）
4. ⏸ **Gate 2**：用户校 UX flow，确认骨架后才进 Step 5
5. AI 逐 frame/page 拆 element → 进 Phase 0

### Why

高层 brief 跳过 Pre-Phase 0 → element 都对但产品逻辑空洞。Step A/B 把"做什么 + 在哪做"显式锚定，Step C 两个 gate 把产品决策权显式还给用户，AI 做提案辅助而不是越权决定产品内容。

---

## Stage 0.5 — Pre-Design Validation（discovery 完成后、Phase 0 前）

design-discovery 产出 6 项 deliverable 后，进入两项前置验证。**两项均通过才进 Phase 0**。

### 数据可行性 Audit

**触发条件**：design 含 derived metric / chart / 数据展示 element。

见 design-discovery § 3.5——audit 在 discovery session 内完成，结论随 discovery deliverable 一并产出。已确认 feature list 经数据 audit 后才是 Stage 0.5 的合法输入。

**Why**：feature 设计前不确认数据可行性 = 反模式（实证：2026-05-11 SaaS Dashboard Driver attribution + Forecast 在 build 后才被 drop，成本远高于 discovery 阶段剔除）。

### F2-early — IA + Feature List Persona 验证

**输入**：discovery 产出的 IA 层级 + feature list + personas
**触发词**：`discovery done` / "走查 IA" → 触发 design-qa-loop Phase 1
**详见**：`~/.claude/agents/persona-simulation.md` § F2-early

F2-early 找出 IA 结构或 feature 缺口 → 补 feature / 调 IA → 再 F2-early verify → 直到无 🔴 缺口 → 进 Phase 0。

**Why**：IA 和 feature list 的错误在 Phase 0 之前修，成本远低于 post-mockup 修。

---

## Phase 0：Element-to-Source Mapping（前置硬规则）

多 element 任务（**≥ 3 个 element**）**必须**在生成 deliverable 之前产出 mapping table。trivial 单 element 调整可省。

### Lookup 序列（按序）

1. grep source index（path-specific：Figma catalog / code `src/canonical/` / `dist/icons/svg/`）
2. 每个 element 至少 2-3 个同义词 / casing 变体尝试
3. 仍 miss → path-specific 深度搜索（Figma MCP / 文件内 component_set）
4. 全 miss → 标注 ⚠️ 真 gap，发给用户拍板

### 输出格式（mandatory table）

| Element | Source reference | Path-specific detail | Status |
|---|---|---|---|
| top bar | `Top bar`（TVU library）| Figma key / code canonical / icon SVG | ✅ verified |
| status badge | `Badge`（TVU library）| ... | 🟡 skeleton → 需验 variants |
| （真缺件）| catalog + source 全 miss | n/a | ⚠️ 真 gap → 用户拍板 |

### 处理流程

1. AI 产出整张 table
2. 发给用户校验（gap 决策 / 🟡 验证路径）
3. 用户确认后才开始生成 deliverable
4. 生成中新发现 element → **回 Phase 0** 补行，**禁止**现场判断 "source 缺件"

### Why

前置 mapping 让所有 gap 一次暴露，用户一次决策。同时把 source catalog 系统性 exercise（🟡 skeleton 顺手升级 ✅ verified，反哺 catalog 质量）。

---

## Library-First + Evidence Discipline

任何 "source 没有 X" 的论断必须来自**实证搜索**，不能凭直觉。

1. 至少试 **2-3 个同义词 / 不同 casing** 搜索
2. 检查**所有可用 source**（path-specific：Figma catalog + library / code `dist/icons/` + `src/canonical/` + Figma MCP fallback）
3. **验证一个 sample instance** 看 variants / properties

只有所有路径都确认无结果，才能宣布 "source 缺件 → 自制候选"。

### 不构成充分证据

- "我搜了一下没看到" — 不够
- 仅 1 次负向搜索 — 不够
- 没验 sample instance variants — 不够

---

## M6 — Reusable Pattern Marking

识别到 reusable pattern（跨 frame/page 重复出现的 element 组合）时：

1. **不**自动提取到 design system 库
2. 标注 🟡 入库候选（候选名 + 预期 props / variants + 出现位置）
3. deliverable 收尾给用户候选清单
4. 用户拍板后再决定是否入库

⚠️ M6 不是 Library-First Discipline 的逃生口——合法自制候选 = 经过实证搜索后确认 source 缺件的 element。

---

## M11 — Self-audit Discipline

### M11.1 — Probe-based 自查（4 步法）

每次自查必须按 4 步走，**禁止靠肉眼"看起来对就过"**：

1. probe reference（原 deliverable / source component）的 N 个代表性元素拿数值
2. probe 自己实现的同一元素拿数值
3. 字段级 diff（geometry / fills / opacity / variable bindings / variant name / child count）
4. 任何 mismatch = bug 或刻意 deviation **必须解释**

跳过任何一步，自查不算自查。

### M11.2 — Visual Verification Discipline

- 所有视觉验收必走高分辨率截图或放大查看
- **缩略图禁止做 spec 判断**（小字号在缩图下无法判读）
- 关键属性（opacity / variable bindings / variant / dimensions）创建后必 probe 数值二次确认
- 验收截图发给用户时附 probe 关键字段值（不只截图）

### M11.3 — Inverse-question 视觉元素

对每个明显视觉 element 强制问："**这在折叠态 / 其它角色 / 其它断点下还成立吗？删掉它会有 visible 损失吗？**" 答"看不出损失" → 重新审视，可能是误植或冗余。

---

## M14 — Reference Input Adaptation（复刻前问适配性）

任何**非 spec 的参考输入**都是 input、不是 constraint：

- 原 deliverable（上一版本产物）
- 用户发的截图（数据样例 / 风格参考 / sibling snapshot）
- Competitor / market reference

复刻每个 element 前必须**双问**：

1. "这在当前需求所有状态 / 角色 / 断点下都成立吗？"
2. "这是 user 想要的 spec，还是 user 顺手给的参考？"

不成立 / 仅是参考 → 改造或删掉，**不照抄**。

### 高频被误抄字段（优先警觉）

| 字段 | 误抄场景 |
|---|---|
| **Color** | 截图当 data 参考时最易被当色板抄（2026-05-11 SaaS Dashboard chart 紫 vs 绿）|
| **Chart type** | 截图里的 chart 类型 ≠ 当前需求的 chart 类型 |
| **Layout 密度** | 截图里 card padding / gap ≠ 当前页面密度要求 |
| **Placeholder text / opacity** | 库组件 default 未评估直接保留 |

### Context 维度检查（generic 表）

复刻 element 前**必问该 element 在 reference 中 attach 到什么 context**：

| Context 维度 | Probe 方法 | Mismatch → |
|---|---|---|
| **IA level**（一级 / N 级 page）| top bar active menu / sub-nav 是否含父级返回 | 级别绑定 element 不 mirror |
| **Persona**（reference 服务谁 / new page 服务谁）| reference 的 user story → 实际 target persona | persona 不匹配的 element 重判 |
| **时间窗 / 业务状态**（live / draft / archived）| reference 的 state 标识 / status badge | state-bound element 重判 |
| **设备 / 断点**（desktop 1920 / 1440 / mobile）| reference 帧宽 + responsive variant | 断点不同的 element 重设计，不 scale-copy |
| **语言 / 本地化** | reference 的语言版本 | 文案长度差异元素重布局 |

Mismatch → 重判该 element，**不照抄**。任何未来出现的级别绑定 element 都被此 generic 维度自然覆盖，**不需要逐个加进规则**（举一反三）。

### 与既有规则关系

- **M22 > M14**：user 显式 design ask 是 spec，可正当 override 参考输入
- **M14 + M21 双层防线**：M14 防"参考输入当 spec"，M21 防"sibling 视觉合同没 probe"

### M14.1 — Icon 按 use-case 语义选，不按 name 字面匹配

库 icon 命名空间（如 TVU `icon/Arrow/*`）常并列**视觉相似但语义不同**的 variants。选 icon 必须按 **use-case 语义**，不是字面 name 匹配。

**典型陷阱（Arrow namespace）**：

| Variant | 视觉 | 语义 use-case |
|---|---|---|
| `icon/Arrow/Left` / `Right` | 大箭头（fat shaft + filled head）| **Back / Return / Direction action**（如 toolbar back button） |
| `icon/Arrow/Previous` / `Next` | 小 chevron `‹ ›`（细线）| **Navigation step**（如 sidebar collapse toggle / breadcrumb / pagination prev-next） |
| `icon/Arrow/Sorting` | 上下双箭头 | **Table column sort indicator** |
| `icon/Arrow/Dropdown` | 单向 chevron-down | **Dropdown / select trigger** |
| `icon/Arrow/Double up` / `Double down` | 双 chevron 叠加 | **Expand-all / Collapse-all（如 card list 折叠按钮）** |

**Mandatory check**：

1. 用 `search_design_system` 拿到全 variants 列表后，**先看 Figma file 的 swap menu** 里 variant 命名（通常 designer 在 master 里写好语义提示），不要凭"`Left` 看上去像 `‹`"机械匹配
2. 文字命名歧义时 import 1 个 sample instance 视觉 verify

**违例 history**：2026-05-14 Plan B sidebar 折叠 toggle / 4 处 breadcrumb，第一版用 `icon/Arrow/Left` 渲染出大箭头（back-arrow 视觉）— 实际应该用 `icon/Arrow/Previous`（chevron-left 视觉）。语义错配在 6 处。Search menu 里 Previous / Next / Left / Right 并列，直接对比命名即可识别。

**Why**：工程师术语（"left arrow" → 任何指左的图标）≠ 设计师术语（`Left` = directional action，`Previous` = navigational step）。两套术语不会自动对齐 — 必须靠人主动看命名 + 视觉双重 verify（参 M24 token mapping table 同源思路）。

---

## M15 — Source 未实证不得宣告"不存在"

搜索 source 须**多 casing / 多同义词 / 至少 3 词**才能下结论：

- "Radio" 0 hit ≠ source 无 radio（实际名 `radio` 小写）
- "Tooltip" 0 hit ≠ source 无 Tooltip（实际名 `Tooltips` 复数）
- "Operation List" 0 hit ≠ source 无（实际名 `Drop down List/Select Type=Operation List`）
- **"icon/Arrow/Left / Right 未发布"** 0 search 即定论 ≠ source 无（实际 TVU UX Design System 库一直有 key `503af6b...` / `a135a51...`，2025-11 更新）— 2026-05-14 实证

1 次 negative 不够。多渠道搜索 + import sample instance 验 variants 双重验证。

### M15.1 — 继承前会话 handoff doc 的"library debt"声明，必 re-verify

继续 prior session 工作时（如 increment / retrofit / refactor），若读到 handoff doc 中含 `BRIDGE-XXX` 或 "library 未发布 / 等待补单" 类 debt claim：

- **不要** 直接信任，作为前提推进
- **必须** 重跑 `search_design_system` 多 casing 验证一次
- 若 search 找到 → handoff doc 立即纠正 + ledger entry 留痕 + 修复 mockup
- 若 search 仍 0 hit → 才能继续按 debt 处理

**Why**: 库在持续更新，prior session 的 "未发布" claim 可能已过期。stale claim 在 session 间传递就会变成"接受的事实"，永远 fallback 自画。

**违例 history**: 2026-05-14 Plan B retrofit session 信 prior session 写的 `BRIDGE-MOCKUP-003: icon/Arrow/Left / Right 未发布 → 用 Unicode ‹/›`，未 re-verify。后续用户指出库实际有 → search_design_system 1 次 hit → BRIDGE-MOCKUP-003 stale 1 个 session。

---

## M16 — Deliverable Defaults Must Be Evaluated

Source component default values = 预览用占位（dropdown 默认 "Option 1/2/3"、Button 默认 text、默认 icon、多余 variant 等）。

### 采用 source component 后必做（不是必改）

评估每项 default（placeholder text / 默认 icon / variant property）：

- 默认值**符合**当前需求 → **可保留**
- 默认值**不符**需求 → **必须 override**

### 反模式（违规）

采用 source component 后**不评估**，直接交付 placeholder 当真实内容。

### Why

区分 **"未改"（可能合理）** 和 **"未评估"（始终不合理）**。一刀切"必须改"会引出本不必要的 override，component instance 失去与 source 同步的意义。

---

## M21 — Existing Product Incremental Local Reuse

### 触发场景

US-3（existing product 增 / 改 / 删 feature），product 已有 working 的 local pattern / component。

**不触发**：US-1 / US-2 greenfield、artifact→deliverable mirror、US-5 trivial、US-6 audit。

### 与 Library-First 关系（不冲突，时序差）

| 时序 | scope | 优先级 |
|---|---|---|
| 视觉基线**建立期** | US-1 / US-2 greenfield | Library-First: source > file-local > 自制 |
| 基线**已建立后**增量 | US-3 existing | **M21**: existing local > source 重建 > 自制 |

### 决策树

> ⚠️ **前置 M22 check**：若 user design ask（M22）与 sibling visual contract 显式冲突 → M22 胜出，跳过第 1 步。

1. Product 已有等价 local pattern → **优先复用**
   - data / props 可适配 → 复用 + override 内容
   - 不可适配 → mirror 视觉 / 结构 shell（圆角 / padding / 标题位 / 密度），按当前需求重建 internals
2. Product 没有但 source / library 有 → 按 Library-First Discipline
3. 都没有 → 按 Library-First 例外（自制候选）

### 起手 mandatory probe — Sibling Visual Contract

US-3 进 Phase 0 前，先 probe sibling page / module 的 visual contract，每条 probe 出**数值 / keyword**：

| 维度 | Probe 方法 |
|---|---|
| Color palette | source 取 sibling 的 fills + variable bindings（主色 / accent / status token 名）|
| Component type | sibling 使用的 component 类型（chart type / card type / etc.）|
| Typography | font family / size / weight |
| Icon style | stroke vs fill / stroke width |
| 视觉密度 | card padding / gap 数值 |
| Header structure | 顶部结构 / widget 槽位置 |

probe 输出**单起一段**放 Phase 0 mapping table 上方，命名 `Sibling visual contract`。后续每个 element decision 必须 reference 这段；偏离必须**显式解释**——**user design ask（M22）是 override 唯一合法源**。

### 例外（user 显式 override）

- local component 有已知 bug 需替换
- 跨产品级 design refresh
- user 明确说"用新版替换旧 local"

**澄清 — pre-design-system 不视为 bug**：pre-design-system 时代的违反 = 合规的历史范式，增量任务继续 mirror，不做 in-place 修正。需用户显式发起独立任务。

### Why

消除"同产品同时间窗口跨页面视觉割裂"。sibling page 视觉风格是用户对产品的认知合同，新 deliverable 背离 → 产品碎片化。

---

## Lazy Reference Loading

TVU library 体积大，**不预加载全量**——按"先索引后细节"三阶段：

| 阶段 | 加载什么 |
|---|---|
| **起手** | conventions 真源（必）+ source index headers |
| **Phase 0** | 每 element 按需 grep 具体 entry |
| **生成 deliverable** | 命中 component 才进 deep lookup / import |

### Why

eager 读全量 source catalog 浪费 reasoning space。lazy 加载使每次 grep 查询词显式可见——可审查查询是否系统性，与 ledger 异常启发式形成双重监控。