# Product Mockup Conventions（Path A — Figma） > 任何 AI 工具在 TVU 产品 Figma 文件里画 UX mockup 时**必须遵循的硬约束**。 > 项目级真源；不要在对话或工具私有 memory 里复刻规则。 > > **作用域**：在 TVU 产品 Figma 文件（如 `Micro-Apps-20250923` 等）画产品页面 mockup。**不**作用于设计系统库本身的迭代。 --- ## 🤖 AI 读取指引（按需加载，避免全量吞） 本文件 2600+ 行，**不要起手就全量 Read**。按下表只读起手必读段，具体 M-rule jump to 时再读： | 起手必读（任务前先吃这些） | 行段 | |---|---| | 本文件顶部 intro + §作用域 + §必读链路 + §真源 / 优先级 | §0–§2 | | §Convention Priority Hierarchy + §Task Entry Modes + §Migrated Rules Pointer Index | §3–§5 | | **§M48 Startup Rule-Coverage Self-Check（起手第一产出物，所有任务）** — 先列「本任务命中的 locked spec + active M-rule」清单再开建 | [`design-process.md` §M48](./design-process.md) | | **§M49 Design Quality Contract（设计质量合同，所有产品设计任务）** — 先列 Baseline / Delta / Semantic / Feedback UI Inventory / UX / Simplicity / Content，再生成 deliverable | [`design-process.md` §M49](./design-process.md) | | §M0 Phase 0 Element-to-Component Mapping（**所有任务前置**） | §M0 | | **§M-DISCIPLINE Rule Execution（起手协议后必跑，所有任务）** — TodoWrite 把「读到的规则」物化成 checklist，防"读了不执行" | §M-DISCIPLINE | | **§M-LIFECYCLE Mockup Edit Lifecycle Gate（任何 create/update/delete 任务）** — 操作前(I5/I6 probe)·后(conformance 机检)·走查 三时点必过 | §M-LIFECYCLE | | 触发后再读（按场景 jump，不预读） | 触发条件 | |---|---| | §M1 Top bar 公共基建 | 涉及产品顶栏时 | | §M-COLOR (§C1/§C2/§C3) | 要填颜色 / icon fill / state color 时 | | §M-INTEGRITY (§I1/§I2/§I3/§I4/§I5/§I6) | **任何编辑 confirmed 后（M-DISCIPLINE.SYNC）** / mockup 完成自检 / sibling 布局 / section 重叠 / children wrap / element parent 归属 / 替换既有节点前 diff(I5) / **create·move·place 前 probe 目标位防叠加(I6)** 时 | | [`figma-technical-reference.md`](./figma-technical-reference.md) **Q15**（SECTION 子节点 x/y = section-relative 非画布绝对；`child_abs = section.x + child.x`，赋目标坐标前先减 section 原点、落点必 probe `absoluteBoundingBox` 验证，禁信 `.x/.y`）| **往 Section 内 create / move / 定位任何节点 / 设其坐标**时（高频复发坑，2026-06-04 立后已多次重踩）| | §M23 + §M23.6 + §M33 | 要画 UX 交付注释 / 流程图 / annotation 字符串时 | | §M23.10 + §M23.11 | 起草 UX 交付卡（Why / Changes / Data Contract / Interaction / Acceptance）时 | | §M23 〈canonical UX 卡结构〉（Why/Changes/Data Contract/Interaction/Acceptance + Section Header 正向模板）| **起草 / 更新 UX 交付卡结构**时（含"写/更新 UX 交付说明"措辞）—— 禁自创临时段 | | §M23.14 双语堆叠行距（组内紧 / 组间松 / 段间最松 三档差异化 lineHeight + itemSpacing）| **UX 卡 / PRD 卡正文出现 ZH 译文堆在 EN 行下方（A-下 / A-逐行 / 多语堆叠）时**——统一行距会让卡拥挤、EN/ZH 不成组 | | §M23.15 卡内模块段名层级（section heading = cyan `#33A4FD` + Medium 大号，与正文拉开）| **起草 / 更新 PRD 卡 · UX 交付卡、卡内含模块段名（Source/Background/Why/Changes…）时** | | §M23.16 规则优先于范本（防继承 pre-规则范本债务）| **开建 PRD / UX 卡前照抄最近同类范本时**——范本若 pre-规则须先用规则真源校验，勿照抄 lineHeight / itemSpacing / 层级 | | §M23.12 + §M23.13（卡 placement 紧邻 mockup + sizing 竖向 Auto Layout hug 高度 + 标准宽）| **放置 / 设定 UX·PRD 卡的位置与尺寸**时 | | §M23.7 + §M23.9（state-label = what+why+invariants + state-preview 元素放产品 frame 外、连线指回触发元素）| **写状态标注 / 把边界态预览元素放到产品 frame 外**时 | | §M23.8（Jira requirement annotation 必带 setRangeHyperlink）+ §M23.8.1（PRD 需求来源段列全 ticket + 全部可点击 + Slack 外链，create/update 都遵守）| **加 Jira annotation / FB-xxxx 编号 / 写改 PRD 需求来源段**时 | | [`design-process.md`](./design-process.md) Pre-Phase 0 **Step B**（PRD 6 段固定结构：需求来源 / 背景 / 现状 / 功能需求 / 验收 / 优先级排期）| **起草 / 更新 PRD** 时（含"按设计系统更新 PRD"这类局部更新措辞）| | §M24 | "已有 code 还原效果图"场景前置 | | §M29 | 涉及表格 cell（copyable / empty placeholder）时 | | §M31 | 决定 Auto Layout / Slot / Boolean / Absolute 时 | | §M32 (含 M30 icon 扩展) | 要 instance 任何 product UI 元素前 | | §M32.2 自建产品 UI 件起手三件套 | **自建 自定义卡 / 浮层 / 面板（非库直用 instance）起手**时 | | §M35 affordance 搜索 | 要找 chevron / sort / close 等"基本语义元素"前 | | §M43 + §M43.2 | 涉及受限容器（cell / chip / tag）+ 调列宽 / 改 cell 内容时 | | §M46 | 迭代既有 mockup（clone 上期 page 改本期）起手前必读 | | §M47 | 改任何 text 节点的 fontName 前 | | §M49.1 库样式/变量 Fidelity + §C5 语义色优先 | 建节点要绑任何视觉属性 token（颜色 / 间距 / 圆角 / 字体 / 阴影）时 | | §M49.2 + §M49.3 + §M49.4（字段级 parity 表 / 反馈控件同源 inventory / 卡片强调预算）| **重构·拆分组件 · 出现 ≥2 反馈类控件 · 评估卡片强调预算·视觉权重**时 | | §M-FONT | 设 / 改 text 节点 fontSize（须落 textStyle grid）时 | | §M-TXT-ICON-AUDIT | 放任何 icon / 文字符号（防 Unicode glyph 充数）时 | | §M-LIBRARY-HYGIENE | 新建 / 命名 component（`_` / `.` 前缀语义）时 | | §M38 | 做 selected / active row·item 指示（3-layer rail）时 | | §M41 | 做删除 / 破坏性确认弹窗时 | | §M42 + §M42.2 + §M42.3 | clone / 复制 节点或 frame 时（§M42.3：迭代既有物**优先就地改**、禁旁路克隆搭样板制造重复集）| | §M44 | 写 UI label / 字段名（防暴露后端名）时 | | §M45 | 建 / 命名 Figma page 时 | | §M36 / §M37 | 同一组合跨 frame·page 重复 ≥2（M36 promote 提案）/ 有参考图·截图输入（M37 probe）时 | | §M39 / §M40 | 抽组件 variant 文本属性（M39）/ 用 #N 序号 vs 语义命名（M40）时 | | §legacy stub M27 / M28 / M30 / M34 | 仅为外部链接兼容；优先读 umbrella | **红线**：跳过"起手必读段"直接进 M-rule = 协议违反（漏 M0 Phase 0 是历史最高频回归源）。 --- ## 必读链路（起手按顺序读） | 文件 | 内容 | 必读时机 | |---|---|---| | [`design-process.md`](./design-process.md) | 通用 process 规则（M22 / Pre-Phase 0 / Phase 0 / M11 / M14 / M15 / M16 / M21 / M6）| **所有任务** | | [`domain-tvu.md`](./domain-tvu.md) | TVU 业务规则（M3 / M4 / M5 / M7 / M8 / M9）| **所有任务** | | [`figma-technical-reference.md`](./figma-technical-reference.md) | Figma API quirks（Q1-Q4）| Path A 实现时 | | [`tools/figma-quirks.md`](./tools/figma-quirks.md) | Figma quirks 快查表 | Path A 实现时 | | 本文件 | Path A 专属：Figma 真源 / 组件优先级 / M0 / M1 / M10 / M23 | **所有 Path A 任务** | --- ## 真源 / 优先级（先读完这段再动手） ### Figma 库源文件 | 维度 | 值 | |---|---| | TVU 设计系统库源文件 fileKey | `YbsPRUVmNdsbN40NNwh1Gn` | | Published library 名 | `TVU UX Design System` | | Library key | `lk-057f6ba0f771bfa7f63a6a197502999462c2974f995488b381708ca5faadb7f9f6675e04aa442b3a5ffb31732150a7f5aa8ca3102073ab210edc684022fc6c21` | | 源文件登记位置 | [`docs/site-review-manifest.json`](../site-review-manifest.json) `figmaFileKey` 字段 | | 组件名 → code 映射 | [`figma-data/figma-to-code-mapping.json`](../../figma-data/figma-to-code-mapping.json) | **任何 mockup 任务起步必须先 `cat docs/site-review-manifest.json | jq .figmaFileKey` 拿到真源 key，再做 Figma 库探索**——不要靠扫产品文件 instance 反推库归属。 ### 组件取数优先级（默认顺序） **0. 第 0 步必查：[Figma Component Catalog](./figma-component-catalog.md)** 任何 mockup 任务起手第一件事是 grep 这个 catalog。它已 bootstrap 了库的全部 49 个 component_set + 647 icon 的骨架，**已实证过的组件还附带 Primary use / Extension scenarios / Don't use**。70% 的"library 缺件/找不到"判断在这里就有答案。 1. **catalog 没命中 → published `TVU UX Design System` library**（用 library key 过滤搜索 + import sample 看 variants，结果回填 catalog） 2. **库里也没有 → file-local 组件集**（产品文件内的 component_set，少数特殊场景用，如 `APP Icons`） 3. **最后：自画 + 标 🟡 入库候选**（必须前两条都验证后无果，且把候选写回 catalog 让下次免坑） **默认假设：library 已覆盖大多数通用组件**（Button / Input / Badge / Tooltip / Top bar / Notification / Switch / Tab / Drop down List / Form Item / Pagination / Slider 等——具体清单见 catalog）。除非实证证明无对应物，否则不允许跳到第 2 / 第 3 条。 ### 库归属验证机制 - ❌ 错误做法：扫某个既有 page 的 instance 来选 key——产品文件里可能同时存在多代库（旧 `TVU UX Library` + 新 `TVU UX Design System`），盲选会撞旧库。 - ✅ 正确做法：`search_design_system` 时通过 `includeLibraryKeys: ["lk-057f6ba0..."]` 显式过滤；返回结果中检查 `libraryName: "TVU UX Design System"`。 --- ## Convention Priority Hierarchy → [`design-process.md §Convention Priority Hierarchy`](./design-process.md#convention-priority-hierarchy)（完整优先级表 P0-P3 + 冲突解决规则） --- ## Task Entry Modes AI 接到任务后**先 classify** 再决定走哪条路径： | ID | 用户表达 | 流程 | |---|---|---| | **US-1** Greenfield 产品 | "基于 TVU 设计一个 X 产品 mockup，功能大概 ABC..." | Pre-Phase 0 → M0 → 画 frame | | **US-2** Greenfield 单 frame | "基于 TVU 给 X 产品画 dashboard frame" | Pre-Phase 0（单 frame 版）→ M0 → 画 | | **US-3** Existing product 增/改/删 | "MicroApps Console mockup 加/改/删任意 frame 或元素" | Read handoff → Pre-Phase 0（仅变化部分）→ M0 → 画（仅 update 变化部分）| | **US-4** Figma frame → code mirror | "把这个 frame 翻成代码" | **不归本 conventions**（走 [`code-conventions.md`](./code-conventions.md) US-4 路径）| | **US-5** 小调整（1-2 element）| "改下按钮位置" | 跳过 Pre-Phase 0 + M0 → 直接改 | | **US-6** Review / Audit | "帮我审 X frame 是否符合 TVU 规范" | 跳过 Pre-Phase 0 + M0 → 对照规则逐条审 → 产 audit report | | **US-7** Redesign legacy product | "给 X 老产品出 redesign 提案 / 重新设计 X" | 见下方 US-7 子流程（审 → gap → 提案 → 用户挑路径 → 才进 US-1/US-3） | Classification 不确定时 → AI **主动问用户**哪种入口。 ### US-7 子流程 — Redesign Existing Legacy Product **入口条件**：用户对**已存在的产品**（线上 / 老 Figma / 老代码）要出 **redesign 提案**——还**不知道改什么**，需先审完再决定路径。不同于 US-3（已知改什么、直接动 Figma）和 US-6（只审、不出 redesign 方向）。 **4 阶段，强制顺序，每阶段 STOP 等用户拍板：** #### Phase A — 输入收集 用户至少提供一项：截图 / 线上 URL / 源码路径。同时拿到：产品名 + 目标受众 + 重设计动机（业务驱动 / 视觉债 / DS 对齐 / 功能升级）。动机不清 → STOP 问用户，不能凭空假设。 #### Phase B — 现状审计 复用 **US-6 规则 + M30-M36 library-first lookup + M-TXT-ICON-AUDIT**，不重新发明。产出 3 层清单： | 层 | 拆解粒度 | 必标字段 | |---|---|---| | 页面 | route / view 级 | 用途、目标用户、主要交互 | | Section | 页面内功能区块 | 用途、含哪些 component | | Component | 原子元素 | 当前实现方式 + 是否已有 TVU canonical 对应（grep `src/canonical/` + `figma-component-catalog.md`）+ 用到的图标（核 `dist/icons/svg/`） | #### Phase C — Gap 分析 按 component 输出三类清单： - ✅ **可直接换 TVU canonical** — component key + variant 直接列出 - ⚠️ **TVU 已有近似但需扩 variant** — 触发 backlog entry 提议（grep 全部已用 ID 挑最大 +1），不直接改 canonical - ❌ **TVU 没有、需新增 pattern** — 走 AGENTS.md §reusable pattern 入库流程，**用户拍板**才进库；提案阶段先标记不实做 **跨产品复用扫描**（US-7 专属，US-6 不做）：如果 redesign 多个产品并行，⚠️ / ❌ 清单需跨产品比对，相同 pattern 合并为一个 backlog entry，避免重复入库。 #### Phase D — Redesign 提案 按页面产出 before/after 对照 + 改动清单 + 风险点。**硬约束：** - **不动 Figma 库文件**（[figma-write-scope](memory)） - **不写代码** - 产物落 `docs/internal/_prompts/redesign--.md` 或对话，不污染 canonical 真源 - before/after 仅文字描述 + 引用现有 Figma component key，不画新 mockup - 等用户挑路径后**才进 US-1**（greenfield 新画）**或 US-3**（增量改既有 mockup） **违例 signal（命中立即 STOP）：** - "顺手把 ⚠️ canonical 扩了" → 错，必须先入 backlog 待用户拍板 - "提案阶段已经在 Figma 起画 frame" → 错，提案阶段产物是文字 - "凭印象列 canonical 对应" → 错，必须 grep 实证（参考 [feedback_baseline-before-plan](memory) 同源教训） --- ## Migrated Rules — Pointer Index 通用 process rules → [`design-process.md`](./design-process.md)：M22 / Pre-Phase 0 / Stage 0.5 / M21 / Library-First + Evidence Discipline（M2）/ M6 / M11 / M14 / M15 / M16 / Lazy Reference Loading TVU 业务规则 → [`domain-tvu.md`](./domain-tvu.md)：M3 / M4 / M5 / M7 / M8 / M9 --- ## Hard Rules（Path A 专属） ### M0 — Phase 0：Element-to-Component Mapping（前置硬规则） 多 frame 或 **≥ 3 个 element** 的 mockup 任务**必须**在画之前先产出 mapping table。trivial 单元素调整可省。 **Scope (2026-05-14 clarification)**：以下都算"多 frame / ≥3 element"，**不算 trivial，必须做 M0 mapping**： - 主交付 frame（如 1920×1080 完整页面） - **Variant state mini-frames**（Empty / Loading / Sort-active / dropdown / popover / state group 内嵌 mini） - Annotation 内嵌的 UI（state group `_flow-state-N` 的 UI frame、condition label group 等） - 任何包含 ≥3 个 iconographic / chip / badge / button 元素的次级 frame **违例 history**: 2026-05-14 Plan B Row 4 6 个 variant minis（Empty B/C/D + Loading + Sort-active + App Picker）当成"次要快速摆"完全跳 M0 mapping → 4 个 M2 违例 (App icons placeholder rect / Sidebar Badge 手画 / Sort ↑ TEXT / chevron Unicode)。Mini-frames 不是 trivial。 #### Lookup 序列（按序） 1. **grep [`figma-component-catalog.md`](./figma-component-catalog.md)** — 第一优先；每个 element 至少 2-3 个同义词 / casing 变体试（M15 防"一次 negative 即定论"） 2. **catalog 命中 ✅ verified** → 直接采用 entry 的 Primary use / Extension 3. **catalog 命中 🟡 skeleton** → 标记需 import sample instance 验 variants 4. **catalog 全 miss** → `search_design_system` + import sample，仍**先把全部 element 的 mapping 拉完再开始画** #### 输出格式（mandatory table） | Element | Figma component_set (key) | Variants | Status | catalog 索引 | |---|---|---|---|---| | top bar | `Top bar` (`918b928e...`) | Tag=AfterLogin/BeforeLogin | ✅ verified | catalog §Verified | | status badge | `Badge` (`4db5246d...`) | Type/Color/Tag | ✅ verified | catalog §Verified | | confirmation modal | `prompt message` (待查) | pop-confirm variant | 🟡 skeleton → 需 import 验 | catalog §Skeleton | | APP icon | `APP Icons` (file-local, `fefd6aac...`) | Tag × Color | ⚠️ file-local | §已知 file-local | #### 处理流程 1. AI 产出整张 table 2. 发给用户校验（一次性决策 gap 处理 / 验证 🟡 是否进 import 流程） 3. 用户确认后才开始 import + 画 frame 4. 画的过程中若 🟡 skeleton 实证后升级为 ✅ → **回填 catalog**（不是 nice-to-have，是责任） 5. 新发现 element 没在 table 里 → **回到 Phase 0** 补一行，**禁止**现场判断"library 缺件" #### 图标与字体的源头锁定（M48 前移，2026-06-08 新增） M48 的 Glyph / 字体自查是**交付前** gate；本步把同两类决策**前移到 mapping 阶段**，从源头杜绝"边建边手搓 glyph / 默认 Inter"——建完再扫等于返工。 - **图标 affordance 必须当场定 component key**：mapping 表里凡 affordance 属"图标 / 箭头 / 状态符号 / 删除 / 增删 / chevron"等的 element，**必须当场 grep catalog / search library 填上真 component key**（配合 M35 affordance trace），**不允许留 TBD / 空 / "建时再定"**——留空 = 建时图省事敲 Unicode glyph 的温床（M48 §icons 违例的高发路径，2026-06-08 V4-2285/2286 实证）。 - **字体起手即锁**：mapping 起手声明本任务**注释层字体 = EN `Roboto` / ZH `Noto Sans SC`**（M23 §字体规范），产品本体按库 instance / file-level baseline。注释卡建卡时即 `loadFontAsync` + `setRangeFontName`，不依赖 `createText()` 的 Inter 默认。 > **三道防线同治图标/字体两类高频复发病灶**：**M0 源头列定 → 主建按表 → M48 交付前 audit gate**（[`scripts/audit-mockup-typography-icon.mjs`](../../scripts/audit-mockup-typography-icon.mjs)，接进 `pnpm audit:consumer-mockup`）。交付前综合单闸跑 `pnpm audit:mockup-conformance --file `（聚合全 5 个 mockup audit，含原 orphan 的 library-origin；场景 2 加 `--non-blocking`）。 #### Why M2 / M15 反复踩坑根因是"边画边判断 library 缺件"。Phase 0 把所有判断前置到一张 table，gap 一次暴露，决策一次到位。 --- ### M1 — TVU Top bar 是公共基建，不允许自画 任何 TVU 产品页面的 top bar **必须直接 instance** Figma library `Top bar` 组件（来自 `TVU UX Design System` library）。 - Library: `TVU UX Design System` (key `lk-057f6ba0f771bfa7f63a6a197502999462c2974f995488b381708ca5faadb7f9f6675e04aa442b3a5ffb31732150a7f5aa8ca3102073ab210edc684022fc6c21`) - Component set: `Top bar` (key `918b928e4541f1573de5c98c32b408af663d7f2f`) - Variants: `Tag=After Login`（默认, 1920×56）/ `Tag=Before Login`（1920×64） - 关键 properties：`Show Menu` / `Show Search box`（BOOLEAN）/ `Menu` `Right_content`（SLOT） ⚠️ 文件里还有同名旧版 `Top bar`（来自 `TVU UX Library`，key `2f36c51ae9fcdfd450f3151c654c9931c9069d96`），**不要用**。验证库归属：`search_design_system` 调用时通过 `includeLibraryKeys: ["lk-057f6ba0..."]` 过滤；不要用 `findAll(INSTANCE)` 扫描既有页面（那些页面可能用旧库建的）。 - **不允许**自画 top bar - **不允许**修改 top bar 结构（菜单数量 / 时区 / Tokens / Network Delay 等只能开关显示） - **不允许**把 page-level 元素塞进 top bar（计数器 / 过滤项 / 批量操作等放 top bar 下方） ⚠️ **产品标题不属于 page-level 元素**——填进 top bar 自带的 product-name slot（默认 `Product Name`，主动覆写为实际产品名）。不要在 top bar 下方再加只写 title 的 page-header strip——冗余。 **Why:** TVU 全产品视觉一致性靠 top bar 统一。AI 自画会破坏跨产品体验。 --- ### M-COLOR — Color Token Discipline（umbrella，覆盖原 M10 / M25 / M26） 凡是给 mockup 元素填色（fill / stroke / text color）时，必须按 token 规范取用。三个 sub-clauses 同源——都是"违反 token 系统语义"——所以合并为一组以便 audit 一次跑完。 **Legacy ID 映射**：M10 → §C1（icon fill），M25 → §C2（state color），M26 → §C3（bg vs text grey）。 **自动化 audit**：`scripts/audit-mockup-colors.mjs`（一次扫完 3 个 sub-clauses）。 > **US-3（existing product iteration）专用前置步骤**：在写任何颜色常量 / Color Variable 前，必须先完成 **M21.2 — Feature Iteration Color Contract**（见 [`design-process.md`](./design-process.md)）——从 sibling frame 实测提取色值，禁止默认套用 TVU DS token 值（两者可能 intentionally diverge）。M-COLOR 的 C1/C2/C3 在 Color Contract 建立后继续适用。 > > **元层 reference**：M21.2 是 [`../meta-rules.md` §触发器 O](../meta-rules.md) "Onboarding 知识 ≠ 实际产品状态（实测优先）" 的颜色专项落地。同一元规则下还有 §Sprint 收尾 Self-Audit 协议（AGENTS.md）、触发器 I/J/G 等子规则。 --- #### C1 — Brand / Token color paint 必须绑 Color Variable，不写 hex literal（原 M10；2026-05-26 扩 stroke + text + frame fill） **适用范围**（**任何** brand-color / token-driven 视觉应用，**不限 icon path**）： | 视觉应用 | 正确做法 | 错误做法 | |---|---|---| | **Icon path fill** — 单色非品牌图标 | `path.fill = Variable("Color Type/Icon/Default")` | `path.fill = "#dbdbdb"` literal | | **Icon path fill** — 单色品牌图标 | 绑 `UX/Brand/Brand` / `UX/Red/Default` etc. | hex literal | | **Icon path fill** — 状态色多色图标 | 各 path 分别绑语义 Color Variable | 全 path 一律 hex | | **Frame / shape stroke**（如 selected row 的 4px LEFT accent rail）| `frame.strokes = [{ paint绑 UX/Brand/Brand }]` | `frame.strokes = [{ color: {r,g,b} 无 boundVariables }]` | | **Frame / shape fill**（如 selected row 的 dark green bg）| `frame.fills = [{ paint绑 UX/Brand/Match,Hover }]` | hex literal | | **Text fill**（如品牌色强调文字、Syncing state pill 文字）| `text.fills = [{ paint绑 UX/Brand/Brand or Color Type/Text/* }]` | hex literal | | **第三方 logo / app icon** | hex literal 可接受（封装在 catalog SVG 内部）| 加到 design system token 里 | **核心命题：任何 brand 色 / token 色的视觉应用都不允许 raw hex paint，全部必须绑 Color Variable。** Icon 是子集，**不是全集**。 **Why**： 1. figma SVG export API 把 Color Variable 引用解析为 literal hex（pipeline 限制）。Variable 绑定语义在 figma 内部保留，未来 token 升级 / theme 切换自动同步；hex literal 不会同步。 2. **跨 paint type 的一致性**：fill 绑 var 而 stroke 漏绑（或反之）= 视觉 split brain：theme 切换时一边变一边不变。 3. **Clone 风险放大**：raw hex 在 clone 后变 N 倍 bug（详见 **M42 Clone Gate**）。 **Code 端 fallback**：`figma-sync/export-icons.mjs` 的 `transformSvgCurrentColor` 把 `#dbdbdb` 转 `currentColor`；消费组件容器设 `color: var(--icon-default)` 实现 cascade。详见 [`translation/divergences.md`](../../src/design-system/translation/divergences.md) §"Figma SVG export pipeline limitation"。 **落实方法**： 1. 编辑既有 figma library icon / element 时，所有 brand-color paint（fill / stroke / text）改用 Variable 绑定（不用 hex） 2. 画新 element / icon 时直接用 Variable 绑定 3. import / paste element 后**自检**：所有 brand-color paint 是否 hex？是 → fix 绑 Variable 4. AI 生成 figma 效果图时，instance 继承 library 设置即可——**不要**在 instance 上 override 成 literal hex 5. **Instance / clone 后 paint 绑定自检**：任何 `createInstance()` / `node.clone()` 调用后，立即 probe 所有 brand-color paint 的 `boundVariables?.color`——若为空或 raw SOLID → 二步法绑对应 token。批量场景每个均需检查，不因"library 默认已绑"而跳过。 6. **写 paint object 前先检查源**：若 paint 复用自现有 paint object（如 `const stroke = sourceNode.strokes`），先 probe `boundVariables` 是否完整——源缺失则**先修源再 clone**，不要把 bug 传播到 N 个 instance（详见 **M42 Clone Gate**）。 **实证 — 2026-05-26 Video Sync Phase B**：本规则原仅约束 icon path fill。Selected row 的 4px LEFT BRAND stroke 在 M0/M1 原版用 raw `{0.184, 0.71, 0.306}` 无 boundVariables → clone 12 variants 时全部继承 → walkthrough audit 才捕获 → 全绑 `UX/Brand/Brand` (`3010:102`)。根因：C1 原 wording "Icon path fill" 不覆盖 frame stroke，**是规则 wording 盲区不是 AI 失误**。本次扩 stroke + frame fill + text fill 覆盖即修复盲区。 --- #### C2 — State Color Discipline (hover ≠ brand)（原 M25） TVU library 为状态色提供专门 token 套件，**不可省略**： | State | Brand | Red | Blue | Orange | |---|---|---|---|---| | Default / Active | `UX/Brand/Brand` | `UX/Red/Default` | `UX/Blue/Default` | `UX/Orange/Default` | | **Hover** | `UX/Brand/Hover` | `UX/Red/Hover 1` | `UX/Blue/Hover 1` | `UX/Orange/Hover 1` | | Disabled | `UX/Brand/Disable` | — | — | — | | Icon-specific active/hover | `Color Type/Icon/Active & Hover` | （同左） | （同左） | （同左） | | Grey button hover | `Color Type/Background/Hover Grey Button` + `Color Type/Text/Hover Grey button` | — | — | — | **规则**： - **Active state** = primary token（pure brand）— 表达"现在选中的"身份 - **Hover state** = `*/Hover` variant — 比 active 略浅；提示"可点击" - **Disabled** = `*/Disable` — 灰化但保留品牌指代 - 当 interactive element 是 **brand-colored** 时，hover bg **必须**用 brand-hover，不可用 Layer_3 生灰（后者是"中性 hover"，只对非品牌色 element 用） **Why**：用 `Brand/Brand` 给 hover state 会让 hover 视觉等同 active，破坏 "click affordance vs selected state" 的区分。Layer_3 生灰则丢失品牌色暗示——用户看不到这是个 brand action。 --- #### C3 — BG vs Text Grey Discipline（原 M26） TVU library 的灰色 token 分两套： | 用途 | 命名空间 | 示例 | |---|---|---| | **Background fills**（FRAME_FILL / SHAPE_FILL）| `Color Type/Background/Layer_{1,2,3,4}` + `Top Bar` | Layer_1 canvas / Layer_2 card / Layer_3 chip / Layer_4 inactive bar | | **Text / Border foreground**（TEXT_FILL / STROKE）| `UX/Grey/grey-{2..9}` + `Color Type/Text/*` + `Color Type/Line/*` | grey-7 tip text / grey-9 disabled text / Line/Deep Divider | **禁用规则**： - ❌ 把 `UX/Grey/grey-N` 用作 frame/shape fill（grey-7/8/9 是 text color，scope 没必要给 FRAME_FILL） - ❌ 把 `Color Type/Text/*` 用作 background fill - ❌ 把 `Color Type/Background/Layer_N` 用作文字色 **正例 vs 反例**： | 元素 | ✅ 正确 | ❌ 反例 | |---|---|---| | Status bar inactive segment | `Color Type/Background/Layer_4` | `UX/Grey/grey-7` | | Card bg | `Color Type/Background/Layer_2` (or hex if not published) | `UX/Grey/grey-9` | | Tips text | `Color Type/Text/Tips` | `UX/Grey/grey-7` | | Sidebar hover bg (brand element) | `UX/Brand/Hover @ low alpha` | `Color Type/Background/Layer_3` | **Why**：Token scope 是设计意图的硬约束。`UX/Grey/grey-7` 的 scope 是 ALL_SCOPES（向后兼容），但它的 hex `#7B7B7B` 视觉上是中等灰，作为 BG 太亮、作为 text 比 tips 暗——错位使用会让浅色文字消失或深色 BG 过亮。 **Why（深层）**：Layer 系列灰是按视觉层级递增（layer_1 最暗 / layer_4 最亮 elevated），符合 BG 堆叠语义。Grey-N 系列是文本/边框灰度阶梯。混用是把"颜色"和"语义"切了。 --- #### C4 — Brand color vs M23 annotation accent 不能混用（2026-06-01 新增） TVU 视觉系统里 **brand green `#33ab4f`** 与 **M23 annotation accent cyan `#33A4FD`** 是两套独立色彩归属，严禁混用： | 色 | hex | 用途归属 | 何时用 | |---|---|---|---| | **Brand green** | `#33ab4f` (`UX/Brand/Brand`) | 产品 UI 的 active state / brand identity | Selected radio dot / 已连 SSID / brand button / 主操作 affordance | | **M23 cyan accent** | `#33A4FD` | UX 交付注释卡的 accent | M23 卡 4px 左 stroke / 状态标签标题色 / **流程线（起点圆点边框 + 主干 + 终点箭头）** / 条件标签文字 / spec card title | | **Tips gray** | **新库** `#A6ADB8` (`Color Type/Text/Tips`) / **legacy 文件** `#999999`（无 token，hex literal 但属文件 file-level convention 合法）| 次要提示文字 | `* hint`类提示行 / 注释说明次要信息 / inline 括号内 description | **反例 — 2026-06-01 V4-1865**： - F5 Mode=WiFi redirect note 用 brand green 染（`#33ab4f`）→ 用户抓"提示文字为什么用品牌色"。修法：改 tips gray 与 baseline `* Enable to connect only to this WiFi network.` 同源。 - M23 spec card title 用 brand green → 应是 cyan `#33A4FD`。修法：所有 M23 卡 section title fill 绑 cyan token / paint。 **反例 — 2026-06-02 V4-1865 v6**：F5 hint 第一次改 tips gray 用了**新库 `#A6ADB8` + fontSize 14**，但 Config-T 是 legacy file，baseline hint 实际是 **`#999999` + fontSize 12**（fontSize 也不对）。用户抓"提示文案颜色应参考项目中已有 `#999`"。修法：legacy file 起手用 `findAll` probe sibling hint text 实测色 + 字号，不套新库 token。**file-level convention precedes umbrella default** — 本表 hex 是新库默认，legacy 文件以自身 baseline 为准。 **Why**： 1. **brand color overuse 稀释品牌信号**——active state 该突出时反而被一片 brand 海淹没 2. **M23 accent ≠ 品牌色**——M23 卡是"附注层"视觉契约，与产品 UI 视觉是隔离 layer (M33 已规定)；用 brand 色破隔离 3. **hint 文字用 brand 是反 UX**——hint 应低视觉权重；brand 色高对比反喧宾夺主 **Acceptance**： - mockup product UI 区出现 cyan `#33A4FD` 任意应用 → 违例（除非 token 明文允许） - M23 card / **流程线任意部位（起点圆点边框 / 主干 / 终点箭头）** / 条件标签出现 brand green `#33ab4f` → 违例（流程线统一 cyan `#33A4FD`；唯一非蓝处是起点圆点填充 `#FFFFFF` 白衬底，非品牌色） - "提示 hint" / "次要说明" 类文字色 ≠ tips gray → 违例 --- #### C5 — Semantic-color-first（语义色优先于 grey 原语）（2026-06-12 新增） 绑颜色时**先按元素语义角色选 `Color Type/*` 语义变量；`UX/Grey/grey-N` 原语仅在没有对应语义角色时 fallback**。 | 元素角色 | ✅ 首选语义变量（Figma 实查名） | code token | ❌ 别直接绑原语 | |---|---|---|---| | 文字（标题/正文/提示/占位/禁用）| `Color Type/Text/{Heading & Button, Text_1, Text_2, Tips, Placeholder & Button, Disable}` | `--text-*` | `UX/Grey/grey-N` | | 图标 | `Color Type/Icon/{Active & Hover, Default, Placeholder, Disable}` | `--icon-*` | `UX/Grey/grey-N` | | 背景/卡/分层 | `Color Type/Background/{Layer_1..4, Top Bar}` | `--bg-*` | `UX/Grey/grey-N` | | 分隔线/边框 | `Color Type/Line/{Popup Border, Deep Divider, Light Divider}` | `--line-*` | `UX/Grey/grey-N` | **Why**：实查证实语义变量本身就 alias 到 grey 原语（`Color Type/Text/Tips` → `grey-6` #9e9e9e）——所以**绑原语像素看起来对、但丢了语义角色**：角色→灰阶映射一旦在库里调整，绑原语的节点不跟随、绑语义的自动跟随。这是 design-token 间接层的全部意义。 **实证 — 2026-06-12**：owner 发现执行器画 mockup 优先绑 `UX/Grey/grey-N` 而非自定义的 Text/Icon/Background/Line 语义色。根因：§C3 "Text/Border foreground" 把 `UX/Grey/grey-{2..9}` 列为合法 foreground 命名空间，留了绑原语口子。本 §C5 收紧为"语义角色优先、原语仅 fallback"，与 §C3 的 scope 纪律并行（C3 管"别把 bg-grey 当 text 用"，C5 管"有语义角色就别绑原语"）。 **Acceptance**：text/icon/bg/line 角色节点绑了 `UX/Grey/grey-N`、而存在对应 `Color Type/*` 语义变量 → 违例（改绑语义变量）。机检见 D16 verifier（`audit-mockup-binding-fidelity`）。 --- #### M-COLOR 共用 Acceptance - 一次 probe 跑全：`pnpm audit:mockup:colors -- --file --node `（脚本扫 §C1 / §C2 / §C3 三条；§C5 语义优先由 D16 verifier 机检） - 任一 sub-clause 违例 → handoff doc 必含 fix log（"colors fixed: [§C1 N nodes, §C2 N nodes, §C3 N nodes, §C5 N nodes]"） - Legacy ID 引用兼容：M10 / M25 / M26 anchor 在文末"Legacy ID Map"段维护重定向 --- ### M23 — UX 交付注释：多状态交互流程图格式 当一个 feature 存在多个明显不同的交互状态（如 Default / Loading / Applied），**必须**用标准化的多状态流程图格式来交付 UX 说明，而不是单一静态 frame。 #### 何时触发 - 功能有 ≥2 个用户可感知的交互状态 - 存在状态转换触发条件（用户操作 / 系统响应） - 开发需要明确的状态边界和数据变化说明 #### 结构层级（5 层） | 层 | 节点类型 | 命名规范 | 说明 | |---|---|---|---| | 1. Section header | FRAME | `"UX · [Feature] — Interaction States"` | 横跨所有 state frame，full-width | | 2. State group | GROUP | `"_flow-state-N"` | 每个状态一个 GROUP，包含 label chip + UI frame | | 3. Label chip | FRAME（GROUP 子节点）| 无固定命名 | 在 UI frame 正上方 8px，显示状态名 + 说明 | | 4. 流程箭头 + 条件标签 | VECTOR + GROUP | 箭头: `"Vector"`；条件: `"_"` | 页面级节点，不放进 state group | | 5. 规则卡 | FRAME | `"UX · [Feature] — Rules"` | 放在最后一个 state group 右侧 | #### 主题无关配色系统（硬规则） 所有注释元素必须使用**显式填充容器**——禁止文字直接浮在 canvas 上。 | 元素 | Fill | Text color | 原则 | |---|---|---|---| | Header chip / Label chip / 规则卡背景 | `#2B2D42`（深海军蓝）| `#FFFFFF` | 深底略亮可读；浅底深色 chip 突出为 annotation overlay | | 状态标签标题行 `[State Name]:` | — | `#33A4FD`（蓝色） | 与箭头颜色一致；深/浅背景对比度均达标 | | 状态说明文字（次要信息）| — | `#A6ADB8`（浅灰） | 降噪，不抢夺标题视觉权重 | | 流程连线起点圆点 | `#FFFFFF` | — | ⌀6px 圆点，**白色实心填充 + 2px 蓝色边框 `#33A4FD`**，标在主干起点 → 流程一眼定向「从哪到哪」，不靠读者猜（白填充比空心环在小尺寸下更利落不糊；2026-06-17 由空心环改白填充圆点）| | 流程箭头 stroke | — | `#33A4FD` | 2px stroke，主干从起点圆点右缘起笔；终点手动绘制箭头三角（`strokeEndCap` 在 VECTOR 不支持）| | 条件标签文字 | — | `#33A4FD` | 背景 `#2B2D42`，放在箭头正下方 | | 规则卡左边框 | 4px `#33A4FD` left stroke | — | `strokeLeftWeight=4`，其余三边 = 0，`strokeAlign='INSIDE'`（偶数 stroke 便于像素对齐，2026-05-26 由 3 改为 4）| **Why**：依赖 canvas 背景色（白字 = 假设深底 / 黑字 = 假设浅底）会在主题切换时翻车。`#2B2D42` container 在深/浅 canvas 上均有明确边界，是主题无关的最小可读单元。 #### Figma canvas 层级硬规则 **条件标签必须用 GROUP，不能用 FRAME。** FRAME 节点在 Figma canvas 上显示名称标签，会干扰流程图阅读。条件标签（arrow 下方小 chip）必须用 GROUP 实现： ```js // ✅ 正确：RECTANGLE（背景）+ TEXT，打 GROUP const rect = figma.createRectangle(); // navy fill, cornerRadius=4 const t = figma.createText(); // blue text const grp = figma.group([rect, t], page); grp.name = '_'; // 最短名，canvas 上不显眼 // ⚠️ 关键：RECTANGLE 必须在 index 0（下层），TEXT 在 index 1（上层） // figma.group([rect, t], page) 中最后一项渲染在最上方 // 若顺序错误，rect 会遮住 text → 文字消失 grp.insertChild(0, rect); // 确认 rect 在底部 ``` **State group 同理**：每个「label chip + UI frame」对打一个 GROUP（`_flow-state-N`）。GROUP 无 canvas 名称标签，8px gap 可以紧贴，不会与 Figma UI 的 frame 名称标签冲突。 → Figma FRAME vs GROUP canvas 标签行为详见 [`figma-technical-reference.md Q5`](./figma-technical-reference.md#q5--frame-vs-group：canvas-名称标签行为差异) #### 流程连线画法（起点圆点 + 终点箭头） 流程连线 = **起点实心圆点 ● + 终点箭头 ▶**（`●————▶`），让用户一眼看出从哪到哪、不靠猜方向。线身按 §M23.6 走正交折线：同行/同列即单段直线，跨行用折线（直线还是折线按拓扑需要选，见 M23.6 几何模板）： - **起点圆点**：`figma.createEllipse()`，⌀6px，`fills=[白色 #FFFFFF]` + 2px stroke `#33A4FD`（蓝色边框），垂直居中对齐主干（白填充比空心环在小尺寸下更利落、不糊） - **主干 + 终点三角**：VECTOR，从圆点右缘 +2px 起笔；`strokeEndCap` 在 VECTOR 不支持，三角手动画进 `vectorPaths.data` - **打 GROUP**：圆点 + 箭头 group 成一条连线（沿用本节注释元素 GROUP 范式），reconnect_map 存 GROUP id ```js // 主干 + 三角（局部坐标，相对 vec.x/y）；起点圆环 + GROUP 见 Q6 完整示例 const len = x2 - (x1 + 8), AH = 8; // 主干从圆点右缘（⌀6 + 2 间隙）起笔 vec.vectorPaths = [{ windingRule:'EVENODD', data: `M 0 ${AH} L ${len-AH} ${AH} M ${len-AH*2} 0 L ${len} ${AH} L ${len-AH*2} ${AH*2}` }]; ``` → 起点圆点 + 箭头 + GROUP 的完整画法详见 [`figma-technical-reference.md Q6`](./figma-technical-reference.md#q6--vector-节点不支持-strokeendcap，箭头必须手动画) #### Reconnect map（快速重连） 每次画完流程图，**必须**把 arrow 位置信息存入 sharedPluginData，下次"重新连线"时直接读取，无需重探坐标： ```js page.setSharedPluginData('ux_annotation', '[feature]_reconnect_map', JSON.stringify({ arrows: [ { id:'', label:'state-1 → state-2', // 圆点 + 箭头 GROUP 的 id x, y, w, h, // 两端都锚在语义元素 bbox（非卡边）；fromCanvas/tipCanvas 供 M23.6 (A) 两端审计 from:{ frameId:'', triggerElemId:'', edge:'right', midY }, fromCanvas:{ x, y }, to: { frameId:'', targetElemId:'', edge:'left', midY }, tipCanvas:{ x, y } }, ], stateGroups: [{ id, label:'state-N', chipId, frameId }], headerChipId, ruleCardId, })); // 读取：page.getSharedPluginData('ux_annotation', '[feature]_reconnect_map') ``` #### 反例（必须避免） | ❌ 错误做法 | 原因 | |---|---| | 条件标签用 FRAME | canvas 上显示 "Frame" 名称标签，视觉干扰 | | 文字直接浮在 canvas 上 | 颜色依赖主题背景 → 主题切换后不可读 | | `strokeEndCap = 'TRIANGLE_ARROW'` 用在 VECTOR | VECTOR 不支持此属性，silent fail | | GROUP 子节点顺序：TEXT 在前 RECTANGLE 在后 | RECTANGLE 渲染在最上层，遮住文字 | | vectorPaths data 用绝对坐标 | data 是局部坐标（相对 vec.x/y），用绝对坐标会导致路径位置翻倍偏移 | | 流程连线起点用裸线头（无起点标记）| 读者要靠箭头反推起点，方向读不出来；`●————▶` 起点实心圆点才一眼定向 | #### 双语支持（中英文必须同时提供） 所有 UX 注释文案**必须同时提供中文和英文**，排版按元素类型采用不同方式： | 元素 | 排版方式 | 说明 | |---|---|---| | **State label chip** / **Header chip** 各行 | **内联式（Layout A-右）**：英文 + ` `（2 space）+ 中文，同一文本节点（ZH 弱化样式见下方〈字体规范〉〈颜色规范〉）| 单行 label / 标题，EN 短，中文直接跟在右侧 | | **条件标签 chip** | **内联式（Layout A-下）**：英文一行 + 中文换行另起一行，同缩进（ZH 弱化样式见下方〈字体规范〉〈颜色规范〉）| 元素宽度有限，中文另起一行跟随 | | **多行 bullet 列表 / 多行公式 / 含 `\n` 的结构化正文（UX delivery 注解卡 / spec 表）** | **内联式（Layout A-逐行）**：按 EN 行 / bullet 拆分，每行末尾 + ` `（2 space）+ 对应 ZH + `\n` 进下一行（ZH 弱化样式见下方〈字体规范〉〈颜色规范〉）| EN 已按 `\n` 或 `•` 自然分行；逐行 ZH 比 Layout B 上下分节更易 1:1 对应 | | **规则卡** | **分节式（Layout B）**：英文完整段落 → 分隔线（1px `#3A3D55`） → 中文完整段落（`规则说明：`为标题） | EN 是一大块 prose（无 `\n` / 无 `•`）且 ≥ 3 行；逐行内联放不下时退到此层 | **布局选择决策树（A-右 vs A-下 vs A-逐行 vs B）**： ``` 文本行数 ≥ 3 行 或 spec 级正文？ └─ YES → EN 已按 \n / • 自然分行 且 每行 EN+ZH 能塞进容器宽度？ └─ YES → Layout A-逐行（line-by-line interleaved） └─ NO → Layout B（分节式上下分） └─ NO → 该行英文字符 ≤ 50？ 且 chip 宽度充足？ └─ YES → Layout A-右（中文直接内联到右侧，2-space 分隔） └─ NO → Layout A-下（中文另起一行，同缩进） ``` > **行距与分组**：A-下 / A-逐行 / 多语堆叠的交付卡 ZH 译文堆在 EN 下方时，必须按 **§M23.14（双语堆叠排版的行距与分组）** 做"组内紧 / 组间松 / 段间最松"三档差异化间距——否则统一行距会让卡拥挤、EN/ZH 不成组。 **技术实现（use_figma）**： - Layout A-右：`setRangeFills` / `setRangeFontName` / `setRangeFontSize` 在同一 text node 的不同字符区间分别设样式 - Layout A-下：text node 内插入 `\n` + ZH 行，同样用 range API 设中文样式 - Layout A-逐行：按 `\n` split EN 为行数组，每行配对 ZH，重建 characters，再对每个 ZH range 套样式： ```js const enLines = node.characters.split('\n'); const zhLines = [/* 对应 zh per line, 空字符串跳过 */]; const newChars = enLines.map((en, i) => zhLines[i] ? `${en} ${zhLines[i]}` : en).join('\n'); node.characters = newChars; // 然后游走 cursor 算出每个 ZH range [zhStart, zhEnd]，套 setRangeFontName/Size/Fills (opacity 0.45) // 关键：先用 setRangeFontName/Size/Fills 对 (0, newChars.length) reset 为 EN 样式（清掉前一版本残留）， // 再对每个 ZH range 套 ZH 样式，避免 setCharacters 后 trailing 残留样式污染 ``` - Layout B：追加独立 text node（`规则说明：` 标题 + 6 bullets）+ 1px 分隔 RECTANGLE - **ZH 弱化**：对所有 `Noto Sans SC` 字符区间，setRangeFills 时加 `opacity: 0.45`；EN opacity 保持 1.0（默认）。EN 用什么底色 ZH 就用相同底色 + 半透明，无需记特殊颜色值 **视觉优先级原则（最重要）**： > **英文优先，中文视觉弱化**。习惯读英文的工程师只看英文，中文不应干扰视线；习惯读中文的成员虽然中文弱化但仍可识别。双语不等于双权重——中文永远是附注，不是并列。 **逐行内联 > 上下分节（在能放下的前提下）**： > Layout B 上下分节把工程师阅读路径切两段——先读完整段 EN，再回头读整段 ZH，对照费眼睛。Layout A-逐行 让每行 EN/ZH 同视框，1:1 对照零阅读跳跃。但前提是 EN 已自然分行（`\n` 或 `•`）且每行 EN+ZH 能塞进容器宽度；EN 是一大块 prose（无 `\n` 无 `•`）或单行太长塞不下时仍走 Layout B。 **字体规范（双语 ZH 字体/字号唯一真源）**： - 英文：`Roboto`（**对齐设计系统真源**——`src/tokens/variables.css` §Text Style tokens 7 个 Text Styles + `figma-data/raw/design-tokens.tokens.json` typography.roboto 均为 Roboto family；style 用 `Regular` / `Medium` / `Bold`） - 中文：`Noto Sans SC`（Figma 可用简中字体；style 用 `Regular` / `Medium`；`PingFang SC` 在此环境不可用，故 ZH 用 Noto Sans SC 作环境替代） - 中文字号：比同层英文小 **2px**（如英文 10px → 中文 8px；宁小勿同） - **适用范围**：**所有 Figma 上的说明文字**（UX 交付卡 / PRD card / spec / state-note / 注解 / Change Summary / Interaction Spec / Baseline 等），**无特殊说明默认遵此规则**。产品 mockup 本体文案另按其库 instance / file-level baseline（见 §C4 "file-level convention precedes umbrella default"）。 - **加载机制**：设 fontName 前 `await figma.loadFontAsync({ family: 'Roboto', style })`；Roboto 在 TVU Figma 环境**已 live 实证可用**（2026-06-08 `use_figma` 实跑：`listAvailableFontsAsync` 列出 36 个 Roboto 字重，`loadFontAsync` Regular/Medium/Bold 全 OK；`Noto Sans SC` Regular 同 OK）。**若 `loadFontAsync` 真的抛错才 fallback 到 Inter，且必须显式上报用户**（不静默退回）——见 §M47。 > **Why（2026-06-08 回流）**：注解层字体此前用 `Inter`（Figma 新建文本节点默认值），与产品真源 `Roboto` 不一致 → 同一 Figma 文件里注解层和产品层两套英文字体，设计 mockup 时容易在产品节点误用 Inter / 在注解误用别的字体。统一成 **EN Roboto / ZH Noto Sans SC** 后全文件单一字体体系，消灭跨层字体误用面，且注解层字体 = 产品设计系统真源。用户 2026-06-08 指出「中文 Noto Sans SC、英文 Roboto 更合适，所有 Figma 说明文字无特殊说明默认遵此」。（注：早前 §M47 把 Roboto 与 Helvetica 一起归为「编辑环境不可用」是 2026-05-28 TPC-628 Helvetica 事故的过度归并，与 design-tokens + 实际渲染 Roboto:Bold 的硬证据冲突，本次一并校正。） **颜色规范（双语 ZH 配色唯一真源 — 其余各处只引用本节，不复述数值）**： - 英文主文：`#FFFFFF`（白）或 `#33A4FD`（accent，视层级） - 中文次级：**与对应英文同色 + opacity 0.45**（不另设独立灰 hex）— 靠透明度弱化，保持与英文的同色关联，中文不抢视觉权重 - ⚠️ 中文必须与英文**同色**，仅靠 **opacity 0.45 + 字号小 2px** 弱化；禁止与英文同 opacity 同字号 → 否则视觉上文字量翻倍，注释难以快速扫读 > **校正（2026-06-04）**：历史表述「中文用浅灰 `#A6ADB8`」与本规范「同色 + opacity 0.45」相互矛盾，已统一为后者——中文恒用对应英文**同色**、靠 **opacity 0.45 + 字号小 2px** 弱化，**不另设独立灰 hex**（`#A6ADB8` 仅作 EN 描述文字基础色，见上方主题无关配色表）。实证：2026-06-04 Graphics Insertion「1 Layer per line」用户手册流，AI 照旧表述给中文上了独立灰色，用户再次指出"中文颜色应是英文颜色的透明度"。 **反例**： - ❌ 只写英文（工程师无法判断中文产品文案） - ❌ 只写中文（国际团队协作障碍） - ❌ 多行 body 未按 `\n` / `•` 拆 line 就整块内联（EN 全段 + 2-space + ZH 全段）→ ZH 接在 EN 末尾继续 wrap，工程师看不到一一对应（用 Layout A-逐行 替代） - ❌ state label 用分节式 → chip 高度膨胀，流程图显得松散 - ❌ 直接新增 child text node 到 chip（会导致 auto-layout 撑高）→ 用 range API 改写同一节点 - ❌ 中文与英文同 opacity 同字号（看起来文字量很多，失去弱化效果）—— 弱化靠 opacity 0.45 + 小 2px，而非把中文换成另一种灰色 - ❌ 只靠字号差（1px）区分 EN/ZH —— 当 EN 本身已经是灰色时，1px 肉眼不可见；必须配合 opacity 0.45 ##### 描述性表格也必双语（区分"描述 prose"cell vs "数据中性"cell）— 2026-06-09 新增 注释层的**对比表 / 描述性表格**（如方案 A vs B 对比卡、特性对照、spec 表）每个 cell 同样落 §双语——**但按 cell 内容性质区分**，不是整列一刀切： | cell 类型 | 双语？ | 例 | |---|---|---| | **描述 prose**（解释 / 优劣 / 行为描述 / 维度名）| **必双语**（EN 主 + ZH 同色 opacity 0.45 弱化）| "统一弹窗，少跳转" / "Splits balance & seats into 2 surfaces" / 列首维度名「钱包归属」| | **数据中性**（纯数字 / 金额 / SKU / 专名 / node-id / 代码标识 / token 名）| **EN-only 可**（无语义翻译价值，翻了反噪）| `1,300 tokens/mo` / `$77` / `BM-1047` / `5399:2046` / `UX/Brand/Brand` | 判定口径：**这个 cell 翻成中文对读者有信息增量吗？** 有（描述 / 解释类）→ 双语；纯数据 / 标识符（翻了等于没翻或更乱）→ EN-only。**同一表里维度名列双语、数值列 EN-only 是正常的**——按 cell 判，不按列判。 **实证 — 2026-06-09 BM-1047 V3 Design Spec 对比卡**：V3 拆分 vs V2 统一对比表的**描述性 cell**（方案优劣 / 维度名）漏了 ZH 弱化，只剩数值 cell 是 EN——但描述 cell 恰恰最该双语。补描述 cell 双语后合规。区分"数据中性 vs 描述 prose"即本条回流。 #### 验收标准 - [ ] 深色 canvas 上：所有注释文字可读，颜色无依赖画布背景 - [ ] 浅色 canvas 上：navy chip 作为 overlay 突出可识别（无需截图验证，配色规则保证） - [ ] Figma canvas 上无多余 "Frame" 标签（条件标签是 GROUP） - [ ] Arrow ID 和坐标已存入 sharedPluginData（可通过 `getSharedPluginData` 验证） - [ ] Header chip 和规则卡有语义化名称（非默认 "Frame"） - [ ] 所有注释文案同时提供中英文，排版符合内联式（A-右 / A-下 / A-逐行）/ 分节式（B）分类规范 - [ ] 多行 body 走 A-逐行 时：每行 EN 后紧跟对应 ZH 同视框（无 ZH 整块甩末尾的反模式） - [ ] 所有 Noto Sans SC 字符区间的 fill opacity ≈ 0.45（probe 脚本可验证，无需截图） #### 验证策略（优先用 probe，截图最后手段） | 验证目标 | 推荐方式 | 截图？ | |---|---|---| | ZH opacity 是否为 0.45 | `getRangeFills` 返回 JSON，检查 `opacity` 字段 | ❌ | | EN 颜色是否正确（白/蓝/灰） | `getRangeFills` 检查 `color` | ❌ | | 节点类型（GROUP vs FRAME） | `get_metadata` 或 `node.type` | ❌ | | 位置 / 间距 / 宽高 | probe 脚本返回 x/y/w/h | ❌ | | sharedPluginData 是否写入 | `getSharedPluginData` 返回字符串验证 | ❌ | | 视觉布局（间距感、层叠、对齐感） | 截图 | ✅ 仅此类 | | 用户最终拍板前确认 | 截图 | ✅ 仅此类 | **probe 模板**（批量验证 ZH 弱化，一次 call 覆盖所有 text node）： ```js // 检查所有 annotation text 的 ZH range opacity function checkZHOpacity(node, expected = 0.45) { const len = node.characters.length; const fails = []; let i = 0; while (i < len) { const font = node.getRangeFontName(i, i + 1); if (font && font.family === 'Noto Sans SC') { let j = i + 1; while (j < len && node.getRangeFontName(j, j+1)?.family === 'Noto Sans SC') j++; const fill = node.getRangeFills(i, j)[0]; const op = fill?.opacity ?? 1.0; if (Math.abs(op - expected) > 0.05) fails.push({ range: [i,j], opacity: op }); i = j; } else { i++; } } return { pass: fails.length === 0, fails }; } ``` **Why**：截图消耗 Token 约为 probe 脚本的 10–20 倍；所有可量化属性（颜色、opacity、位置、类型）均可用 `use_figma` 返回 JSON 验证，截图只留给"眼睛才能判断"的视觉感受类问题。 **Why**：UX 交付注释本质是给工程师读的文档；如果注释本身因主题/缩放/层级问题无法清晰呈现，文档价值归零。双语确保跨语言团队无歧义对齐。 #### M23 — UX 交付卡 Canonical 结构（正向模板） > ⚠️ **起草/更新 UX 卡必照此结构，禁自创 What/Menu/Navigation 等临时段。** UX 交付卡 = 一组 **navy chip 卡**（背景 `#2B2D42`，title fill cyan `#33A4FD`），固定 ≤ 6 张、固定顺序、固定语义。**这是唯一合法卡结构**： | # | 卡 | 内容 | 必填 | |---|---|---|---| | 1 | **Section Header** | `UX · [Feature] — [States/Rules]` | 必 | | 2 | **Why** | 1-3 句驱动力：为什么做这个改动（中英）| 必 | | 3 | **Changes** | 本期改动 list（只列本次，不堆历史/roadmap）| 必 | | 4 | **Data Contract** | 字段 / 数据契约（来源、类型、空态、边界）| 数据相关时必 | | 5 | **Interaction** | 交互细节（触发、状态转移、反馈）| 有交互时必 | | 6 | **Acceptance** | 验收 checkbox（可勾选、可测）| 必 | **硬约束**： - 段名、顺序、语义照上表，**不得自创**（如 What / Menu / Navigation / Notes 等临时段 = 违例）。 - 语言纪律见 §M23.10（禁 regex/pseudocode，白话决策树）；scope 纪律见 §M23.11（只放本期、不堆 Persona/out-of-scope/roadmap）。**本段管结构，.10 管语言，.11 管取舍——三者配套。** - 卡视觉 = M23 navy chip（§配色表 + §M23.6 同色系 cyan accent）。 **实证 2026-06-18**：AI 被要求"更新 UX 交付说明"时写成 What/Menu/Navigation 临时结构——根因是 6 卡 schema 此前埋在 §M23.11 scope 纪律里、无正向模板、无关键词路由。本子段即把结构提为一等公民（修 W2）。 #### M23.12 — Spatial Proximity（UX 卡 / PRD 卡必须紧邻其描述的 mockup）— 2026-06-01 新增 UX 交付说明卡（M23 canonical 卡）和 PRD 卡的 **layout 位置必须与其描述的 mockup frame 在视觉上紧邻**。"紧邻"定义：阅读时一屏内可同看到卡 + mockup，且不需横/纵向滚动跳跃。 **Acceptance**： - per-section UX 卡 → 同 row 右侧（或同 column 下方），距对应 mockup 行最近的边 ≤ 200px - PRD 卡 → 整页顶部，width 跨所有 mockup column 或紧邻 Jira widget - 不允许把所有 spec/PRD 内容堆成"页面底部一个大卡"，与上方 mockup 视觉断开 **反例 — 2026-06-01 V4-1865 v2**：M23 卡（1600×2294）单独放 row 3（y=2810），距 row 1 mockups（y=0..1240）2570px 垂直距，工程师阅读时必须滚动 + 失去对应。修法 v4：拆为 1 个 PRD 卡 (top y=-1100 with Jira widget side-by-side) + 2 个 per-section UX 卡 (WiFi UX 卡 右 row 1 / Hotspot UX 卡 右 row 2)，每卡与其描述的 mockup 行水平同 Y。 **Why**：M23 的核心价值是给 dev/QA 提供"对 mockup 的注解"。注解距 mockup > 一屏 = 阅读时强迫上下文切换，1:1 对应失效。Layout 决策必须把"deliverable 与 mockup 的空间关系"当一等约束。 #### M23.13 — UX delivery card sizing：默认竖向 Auto Layout（hug 高度）+ 标准宽度（2026-06-05 新增） 所有 **UX 交付卡**（注释卡 / 规则卡 / state-note / Change Summary / Interaction Spec / Baseline 等）默认必须： - **竖向 Auto Layout**：`layoutMode='VERTICAL'` + `primaryAxisSizingMode='AUTO'`（**hug 高度**，随内容自适应） + `counterAxisSizingMode='FIXED'`（宽度锁定）。 - **宽度规则**（承接 [M23.12](#m2312--spatial-proximityux-卡--prd-卡必须紧邻其描述的-mockup-2026-06-01-新增) 的"注解紧贴 mockup · 1:1 对应"）：卡宽 = **其所注释的 mockup 元素/帧的宽度**，卡放在该元素正下方/旁、左对齐，1:1 贴合；注释整页/整个流程的 summary 卡 = 跨内容带的**统一宽度**。同一交付集合内卡宽一致，不逐卡手调。高度永远 hug（不设固定高度）。 - 子 TEXT：`textAutoResize='HEIGHT'` + `layoutSizingHorizontal='FILL'` + `layoutSizingVertical='HUG'`；用 padding 内缩（左 padding 让出 4/10px 品牌左 stroke）。 **Why**：固定高度 = 内容多则截断、内容少则大片空白，且后续改文案不重排。Auto Layout hug 让卡永远贴合内容；统一宽度避免同组卡参差。 **反例**：`note.resize(W, fixedH)`；或创建时按内容定高一次、后续改 `characters` 不重算 → 同一组卡截断与空白并存。 **Acceptance**： - 任一 UX 交付卡**不得**手设固定高度；必 `primaryAxisSizingMode='AUTO'` - 同一交付集合内卡宽一致（标准值） - 改卡内文案后无需手动 resize 卡高 **实证 — 2026-06-05 Graphics Insertion**：state-note 与 spec 卡用固定高度，编辑文案后有的截断有的空；宽度也逐卡手调参差 → 用户抓"高度没自适应 / 宽度也该默认"。改竖向 Auto Layout hug + 标准宽度即修。 #### M23.14 — 双语堆叠排版的行距与分组（line/paragraph spacing，M23 §双语 extension）— 2026-06-18 新增 §双语 现行只规定了字体 / 字号 / 颜色 / opacity / 布局选择（A-右 / A-下 / A-逐行 / B），**未规定行距与分组**。当 ZH 译文以统一行距堆在 EN 行下方（A-下 / A-逐行 / 多语堆叠的交付卡 / PRD 卡正文）时，`EN→其 ZH` 的间距 = `对→对` 的间距 = `段→段` 的间距 → Gestalt 邻近性失效，「一句 EN + 它的 ZH」不成组，注释读成行数翻倍的密集文字墙（用户感知 = "拥挤"）。本规则补这个洞。 **核心原则：差异化间距制造分组（不是整体放大）。** 三档间距必须**可视递增**，让「EN + 其 ZH」读成一个单元、单元之间、段落之间有递增的呼吸空间： | 层级 | 相对间距 | 默认值（按本卡 EN 字号 `S` 比例锚定，不写死任意 px）| 机制 | |---|---|---| | **同对内**：EN ↔ 其 ZH 译文（intra-pair）| **最紧** | ZH 行 lineHeight ≈ `ZH字号 × 1.15`（ZH 贴住其 EN）| range API：给 ZH range 设紧 lineHeight | | **对与对之间**：同段内 bullet ↔ bullet（inter-pair）| **中** | ≈ `S × 0.6`（EN 14px → ~8px，吸附 spacing scale）| EN 行 lineHeight 加大到 `S × 1.8` 让每个 EN 自带"与上一对之间"的间隔；或 per-bullet Auto Layout `itemSpacing` | | **段与段之间**：Source / Background / Requirements 块（inter-section）| **最大** | ≈ `S × 1.2–1.5`（~16–24px）| section 竖向 Auto Layout `itemSpacing`；或 section 标题行 paddingTop | **数值锚定**：不写死绝对 px——按卡内 EN 字号 `S` 比例 + 吸附既有 spacing scale（vertical rhythm 真源见本文件 §textStyle grid「11px off-grid 破 baseline」段 + [`binding-source-map.json`](../../figma-data/normalized/binding-source-map.json) 可绑 Number Var）。同一交付集合内三档值一致，不逐卡手调。 **机制选择（按 artifact 类型分流，与 §双语 既有约束不冲突）**： | artifact | 机制 | |---|---| | **大卡**（UX 交付卡 / PRD 卡，M23.13 默认竖向 Auto Layout）| **首选 per-section 一个 text node + range lineHeight**——复用 §双语 已有的 ZH range cursor-walk（line ~545 / probe line ~622），在走 ZH range 设 opacity 的同时给 ZH range 设紧 lineHeight、EN range 设松 lineHeight；section 之间用 Auto Layout `itemSpacing`。per-bullet「一个 bullet = 一个 text node + Auto Layout itemSpacing」是等效替代 | | **小 chip**（state label / header chip，单行）| 维持 §双语 既有约束：单节点 range API、**不新增 child node**（避免撑高 auto-layout，见 §双语 反例）。chip 单行无分组问题，本规则不适用 | **Why**：差异化三档间距是 Gestalt 邻近性的直接应用——分组靠"组内紧、组间松"，而非靠分隔线 / 加粗 / 换色（那些会增加视觉噪声，违 §双语「中文永远是附注不抢权重」）。整体放大行距只会让卡更长且仍不分组，是治标。 **Acceptance**： - [ ] `EN→其 ZH` 间距 < `对→对` 间距 < `段→段` 间距（三档**可视递增**） - [ ] 扫读时「EN + 其 ZH」一眼成组，能分清哪条 ZH 属于哪条 EN - [ ] lineHeight / itemSpacing 按 EN 字号比例或吸附 spacing scale，无任意 off-grid px - [ ] **机器闸**：`pnpm audit:mockup-bilingual-spacing --file [--node ]`（已挂进 `audit:mockup-conformance` G4）—— 多对堆叠单节点 EN 行 lineHeight ≥ ZH 行 lineHeight × 1.3（无差异 = uniform/auto = 拥挤 → FAIL）。**per-bullet + Auto Layout itemSpacing 机制不机器扫**（脚本会 log skipped 数，留本表上一档人工 自查），无需截图 - [ ] 不靠分隔线 / 换色 / 加粗 制造分组（仅靠间距） **实证 — 2026-06-18 V4-1864 + V4-1360 Per-SIM Roaming + Access-Tech PRD 卡**：每条 EN 行下加 ZH 译文后用统一行距，三档间距无差异 → 卡显拥挤、ZH 与 EN 不成组。用户："加了中文翻译在下面，所以显得比较拥挤……把这个规则制定一下"。本规则即此回流。 > **范本债务标注（2026-06-23 V4-1827）**：催生本规则的 V4-1864 PRD 卡（建于 0608，pre-M23.14）**自身从未按本规则修正**，仍是统一行距。2026-06-23 画 V4-1827 NDI PRD 卡时 AI 照抄该范本 → 继承拥挤间距 + meta 行混入 + 段名无层级，用户连续纠正。**已按本规则修正 V4-1864 PRD 卡**；并新增 §M23.16 防再次继承 pre-规则范本债务。**勿再照抄 pre-规则范本的可量化属性（lineHeight / itemSpacing / 层级），以规则值为准。** #### M23.15 — 卡内模块段名层级（section heading：cyan + 大号，与正文拉开）— 2026-06-23 新增 PRD 卡 / UX 交付卡内的**模块段名**（PRD 的 Source / Background / Current State / Requirements / Acceptance / Priority & Timeline；UX 卡的 Why / Changes / Interaction / … 等章节名）必须与正文形成**可视层级**——不得与正文同字号同色，否则段名淹没在正文里、模块入口不清，整卡读成无分段的文字流。 | 文本角色 | 样式（EN / ZH） | |---|---| | 卡大标题（card title）| Roboto Bold 18 + 白 `#FFFFFF` / ZH 16 同色 opacity 0.45 | | 卡副标题 · meta 行 | Roboto Medium 12 + cyan `#33A4FD` | | **模块段名（section heading）**| **Roboto Medium 15 + cyan `#33A4FD`** / ZH 13 同色 opacity 0.45 | | 正文（body bullet）| Roboto Regular 13 + 白 `#FFFFFF` / ZH 11 同色 opacity 0.45 | - 段名 cyan 呼应 M23 卡 title cyan（`#33A4FD`）；比正文大 **2px**（13→15）+ 换 **Medium** 字重 + 换色，三重区分。 - ZH 段名照 §双语：与 EN 段名**同色** cyan + opacity 0.45 + 字号小 2px（15→13）。 - 行距照 §M23.14：段名行 lineHeight 偏松（制造段间呼吸），其 ZH 紧贴。 **Why**：段名是模块入口，dev/QA 扫读靠它定位。段名与正文同样式 = 失去信息架构层级。 **反例 — 2026-06-23 V4-1827 NDI PRD 卡 v1**：段名（Source/Background…）照抄 V4-1864 范本用白色 Regular 13，与正文无区分，用户问"为什么模块标题没用蓝色大号"。改 cyan Medium 15 后层级清晰。 **Acceptance**： - [ ] 卡内模块段名 = cyan `#33A4FD` + Roboto Medium + 字号 > 正文（probe `getStyledTextSegments` 验 fill / size） - [ ] ZH 段名同 cyan + opacity 0.45 + 小 2px #### M23.16 — 规则优先于范本：防继承 pre-规则范本债务（meta · cross-cutting）— 2026-06-23 新增 `figma-use`「inspect the file, match what's there」要求对齐现状——但**范本 ≠ 规则真源**。当最近的同类范本建于某规则回流**之前**，照抄它的可量化属性会把违规债务一并继承。 **反模式**：开建 PRD / UX 卡前 dump 最近同类范本的 lineHeight / itemSpacing / 层级当"范式"直接照抄，**未先用规则真源（M23 系列 + §双语）校验范本**。范本若 pre-规则（如 V4-1864 pre-M23.14），即继承拥挤间距 / meta 混入 / 段名无层级等已知违规。 **正解（开建 UX / PRD 卡前必做）**： 1. **先 jump-read 规则真源**（M23 + §双语 + M23.14 + M23.15）建立"该长什么样"的标准；范本仅用于对齐**视觉 token**（颜色 / 结构 / 组件 / 命名），不照抄有规则管的可量化属性。 2. **有规则管的属性用规则值**（lineHeight / itemSpacing / 段名层级 / 双语 opacity）；范本实测值与规则冲突时**以规则为准**。 3. **建完卡立即跑机器闸** `pnpm audit:mockup-bilingual-spacing --file `（及 `audit:mockup-conformance`），不等用户指出。 **实证 — 2026-06-23 V4-1827 NDI PRD 卡**：AI 照抄 V4-1864（pre-M23.14）范本 → 继承拥挤间距 + meta 行 + 段名无层级，用户连续 3 轮纠正（间距 / 段名色 / meta + 超链接）。根因：范本驱动而非规则驱动，未在开建前用规则校验范本。 **Acceptance**： - [ ] 开建前 M48 rule-coverage self-check 含"范本 vs 规则真源校验"一项 - [ ] 建完卡跑 bilingual-spacing 机器闸通过后才进 Gate #### M23.8 — Jira requirement annotation 必带超链接（M23 extension）— 2026-05-27 新增 任何 mockup 加 `Jira requirement` component instance 时，**Issue key text node（"FB-xxxx"）必须 `setRangeHyperlink` 指向真实 Jira URL**，不能只写文字。 **触发**：mockup 含 jira annotation / FB-xxxx 编号 / 需求关联 → 强制。 ##### `Jira requirement` 组件 node 地址（per-file 登记，免每次猜测）— 2026-06-03 新增 `Jira requirement` 是 **file-local 组件（每个产品文件各有一份、不发布）**→ `importComponentByKeyAsync` 跨文件会 fail（"Component with key not found"）。**正确做法：在目标文件内 clone 一个现成 instance，改 title text + issue-key text + `setRangeHyperlink`。** 各文件已知 key / 可 clone 的 instance： | 产品文件 | fileKey | component key | 可 clone 的现成 instance | |---|---|---|---| | Config-T (Local UI) | `rJJjWWs51n2iFOlCIC7aYG` | `a6a34623f80b763077b53d7c31ecce046d498c2d` | （V4-1865 等页内同源 instance）| | Touch Screen v7.7/8.0 | `0054ib0nLmt27bC3QlGDl7` | `e8604a08a31c8c17cb8aec35d7692e88965485e7`（变体 `Priority=High`；本地 mainComponent `5315:9604`）| `5356:4431`(V4-1542) / `5315:19564`(V4-1535) / `5392:17702`(V4-1543) | > 新产品文件首次用时：用 `findAll(INSTANCE, name~/jira|requirement/)` 在已有 Jira 关联 page 上找一个 instance，clone 它；并把该文件 key + instance 追加到本表。组件结构：1 个 title text（大号）+ 1 个 issue-key text（带 hyperlink）。 **实现**： ```js issueKeyText.setRangeHyperlink(0, issueKeyText.characters.length, { type: "URL", value: "https://tvunetworks.atlassian.net/browse/FB-9398" }); ``` **Why**：mockup 是给 PM / dev / QA 跨角色共读的，"FB-9398" 纯文字 reader 还得手动复制到 Jira 搜——hyperlink 一步直达，且 Figma annotation 是单向只读不可编辑，hyperlink 一次设对永久受益。 **反例**：2026-05-27 FB-9398 mockup v1 加了 jira component 但只改 text 没设 hyperlink → 用户抓"JIRA 的链接没带上去"。 **Acceptance**：`probe → issueKeyText.getRangeHyperlink(0, len)` 返回 `{ type: 'URL', value: '' }` 非 null。 ##### M23.8.1 — 需求来源链接完整性 + 全部可点击（PRD「需求来源/Source」段 + 任意 deliverable，create/update 都遵守）— 2026-06-23 新增 M23.8 主条只管"加 `Jira requirement` 组件时其 issue-key 必带 hyperlink"。本子条把范围扩到 **PRD「需求来源 / Source」段 + 交付物内任意 ticket / 外链引用**： 1. **列全需求链**：需求来源须枚举**所有相关 ticket**——客户 / Epic（如 `SEC-*`）+ 功能请求（`FB-*`）+ 开发任务（`V4-*` / `BM-*` 等），不能只写开发任务号。一个功能常跨多个 Jira（`FB` 提需求 → `V4` 拆开发 → `SEC` 客户来源），漏任一个 = reader 看不到完整溯源。来源以 Jira issuelinks（implements / relates to / parent）为准核全。**遍历须到二度**：命名 task 的直接 issuelinks 常只有它实现的 FR；FR 上的 `relates to` bug（客户现场缺陷等）**不在命名 task 的直接 links 里**——须再对该 FR `getJiraIssue` 取其 issuelinks 捞全，否则二度关联 ticket 漏列。 2. **每个引用都可点击**：所有 ticket ID **必须 `setRangeHyperlink` 指向真实 Jira URL**（`https://tvunetworks.atlassian.net/browse/`），禁纯文本 ID。建议同时把 ID range 染 accent cyan `#33A4FD` 作"可点"视觉提示。 3. **Slack 等外链同样收录可点**：若需求从 Slack 线程 / 其它外部源解码，相关链接也须放进需求来源并 `setRangeHyperlink`。 4. **create 与 update 都遵守**：新建 PRD 时列全；后续需求**新增关联 Jira / Slack 时，update 必须回补**到需求来源——不是只在初版做一次。 **触发**：写 / 改任何含需求溯源的 PRD / 交付卡时强制。 **实现**： ```js // 对来源行每个 ticket ID： const i = textNode.characters.indexOf("FB-9586"); textNode.setRangeHyperlink(i, i + 7, { type: "URL", value: "https://tvunetworks.atlassian.net/browse/FB-9586" }); textNode.setRangeFills(i, i + 7, [{ type: "SOLID", color: { r: 0.2, g: 0.643, b: 0.992 } }]); // cyan 可点提示 ``` **Why**：PRD 是 PM / dev / QA 跨角色溯源入口。只写开发任务号（`V4-*`）会丢掉"为什么做"（`FB` 功能请求 / `SEC` 客户 Epic）；纯文本 ID 要手动复制去 Jira 搜，hyperlink 一步直达。 **反例实证**：2026-06-23 V4-2285/2286 Embedded Audio PRD —— 需求来源只写 V4-2285/V4-2286，漏 FB-9586 / FB-9587（功能请求）+ SEC-669（客户 Epic），且全是纯文本不可点击。用户抓"需求缺 FB JIRA + PRD 链接为什么不可点击"→ 回补全链 + 每个 ID setRangeHyperlink + cyan 高亮。 **第二次复发实证**：2026-06-23 V4-2259（同 file `0054ib`）—— PRD 需求来源初版只写 V4-2259（开发 task），漏 FB-8926（FR，V4-2259 implements 它）+ FB-9619（二度 bug，`relates to` FB-8926、**不在 V4-2259 直接 issuelinks 里**）+ 父 Epic V4-1676，且纯文本不可点。用户三次追问（"需求来源全了吗 / 相关 Jira 都带上了吗 / FB-9619 为什么没关联上"）才补全。**两次复发 = activation 层反复失败**——PRD 起草/重建（尤其委派 subagent 执行时）须把本条写进执行 spec 并遍历到二度关联，不能只靠"读了 Step B"。 **Acceptance**：需求来源段列全需求链上所有相关 ticket（Jira issuelinks 核对无遗漏）；`probe → getRangeHyperlink(idStart, idEnd)` 对每个 ID 返回非 null URL；交付物内无纯文本 ticket ID；外链（Slack 等）同样带 hyperlink。 --- ### M24 — Code→Token Mapping Table（仅 "已有 code 还原效果图" 场景前置硬规则） **触发条件（严格 AND）**： 1. 任务表达明确含 "根据已有 code 还原效果图" / "match the running implementation" / "把 vue-app 翻成 figma" / "参考 demo HTML" 等措辞，**或**用户主动指向 source file 作 visual truth；**且** 2. 该 source 直接定义了视觉 token / CSS variables / 颜色常量（不是只引用别人发布的 token）。**source 的形式不限**： - 多文件项目：`.vue` / `.tsx` / `.jsx` / `.svelte` + 独立 `.css` / `.scss` / `tokens.css` - **单 HTML 文件 demo**：`