---
name: tvu-design-mockup
description: 在 TVU 产品 Figma 文件画 mockup / 改 mockup / 改设计稿 / 加 UX 交付说明时消费 TVU UX Design System library。**任何对 TVU 产品 Figma 文件做 write 操作（含 use_figma 调用）前 MUST load 本 skill**——跳步会漏 M0/M23/M32/M35 等所有 mockup 硬规则。**触发判定**：用户语言里只要出现「Figma URL / Figma 链接 / Figma 文件 + 加 / 改 / 调 / 更新 / 同步 / 推 / 画 / 设计」任一组合，即视为 mockup write 任务必触发本 skill；不要把"setup"或"看一下"当借口跳过。常见自然表达：在 Figma 加一个按钮 / 加新页面 / 加入口 / 加 UX 交付说明 / 改 mockup / 改这个 Figma 文件 / 改效果图 / 改设计稿 / 调整 mockup / 调整设计 / 更新到这个 Figma 链接 / 同步到 Figma / 把改动放到 Figma / 把设计推到 Figma / 画 mockup / 画一张效果图 / 画一张设计稿 / 在 Figma 上设计 / @TVU mockup / 用 TVU 设计系统画 mockup / 用 TVU 库画 mockup / @TVU PRD（起草/更新 PRD → design-process Step B 6 段结构）/ @TVU UX说明（写/更新 UX 交付说明 → §M23.0 canonical 卡结构）/ 同步交付物（改完 mockup 后同步交付层 → §M-DISCIPLINE.SYNC）。真源 conventions 在 tvu-design-system repo 内。
---

# 在 TVU 设计系统消费侧画 Figma mockup

本 skill 只做 **trigger + 指路**。真源在仓库内：

- 项目入口 — `${CLAUDE_PLUGIN_ROOT}/AGENTS.md`
- 团队导览 — `${CLAUDE_PLUGIN_ROOT}/docs/internal/CONVENTIONS-OVERVIEW.md`（推荐**先读这个**了解整体）
- 硬规则 — `${CLAUDE_PLUGIN_ROOT}/docs/internal/mockup-conventions.md`（含 M0/M1 + umbrella `M-COLOR` / `M-INTEGRITY` + M23/M23.6/M24/M29/M31/M32/M33/M35 + legacy M10/M25/M26/M27/M28/M30/M34 anchor stubs；具体编号见 OVERVIEW Quick Reference）
- 已知库组件目录 — `${CLAUDE_PLUGIN_ROOT}/docs/internal/figma-component-catalog.md`
- 自动 audit 脚本（CI 候选） — `scripts/audit-mockup-integrity.mjs`（M-INTEGRITY 三件套）+ `scripts/audit-mockup-colors.mjs`（M-COLOR 三件套）

路径解析：Markdown 中的 `${CLAUDE_PLUGIN_ROOT}` 表示当前 plugin root；若环境未展开该变量，按本 skill 下方 bash block 的 `TVU` fallback 解析到 plugin 根目录。

任何细节冲突以上述真源为准；本 skill 不复述规则内容。

## 适用场景

在 TVU 产品 Figma 文件（如 `Micro-Apps-20250923` 等）画产品页面 mockup。

**不**适用：
- 写代码消费 TVU 库 → 真源 `code-conventions.md`，由 `tvu-design-code` skill 触发
- 设计系统库本体迭代 → 那是 maintainer scope，不是 consumer

## 起手协议（按序，不可省略）

⓪. **起手第一动作（先于 Step 0，不可跳）** — load 本 skill 后**立刻用 TodoWrite 把本起手协议逐条建成 checklist，逐项打勾才推进**。**任何 Figma 操作——含只读探查 / `get_metadata` / `use_figma` 勘察 / 看结构——都算"动手"，必须排在 Step 2（读真源起手段）+ Step 6.5（M48 self-check）之后**；禁止用"先探查一下 / 先照现成范本建"绕过起手 gate。**实证 2026-07-06 V4-2335**：load skill 后直接派 subagent 探查 Figma 结构 + 照抄 pre-规则 PRD 范本 `8805:2`，跳过读真源 + M48 → 字号 / opacity / 双语行距范式全错 + 建错文件（旧 Config-T 文件），多轮返工。（激活层加固，非新增内容规则；延续 M48「把核对从隐性变强制产出物」精神。）

0. **Disambiguate deliverable**（条件触发）— 若用户表达只说 "设计 / 做 X 产品" 而未指明 deliverable type → **先 ask**：
   - (a) Figma mockup / frame → 继续本 skill
   - (b) 网站代码 / HTML demo → 切到 `tvu-design-code` skill
   - (c) 先 mockup 后 code → 继续本 skill，wrap up 时提示切到 code skill
   - (d) 仅 UX 思路讨论 → 切到 `role-ux`

   用户已明确说 "@TVU mockup" / "画 mockup" / "画 frame" / "Figma" 时跳过此步。

1. **cwd 检查 + 路径策略**：
   - 若 cwd 在 `tvu-design-system/` 内 → 告警停下（污染源）
   - 若 cwd 已有项目文件（`package.json` / `src/` / `docs/` / `.git/` / `index.html` 等任一）→ 视为 **Existing product**，**在当前 cwd 工作**
   - 若 cwd 是空 / 临时 (`/tmp/*`) / 不在 `~/Documents/AICoding/VS_Code/` 下 → 视为 **Greenfield**，**强制建议** 建到 `~/Documents/AICoding/VS_Code/<product-name>/`（与 tvu-design-system sibling），问用户确认产品名后 cd 过去
   - 用户显式说 "在 X 路径下做" → 按用户说的路径，跳过上述判断
1.5. **环境健康检查** — 任一 fail 时告警停下：
   ```bash
   # Plugin root resolution: env var preferred, realpath fallback
   TVU="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../.." && pwd)}"
   ```
   - `test -d "$TVU"` → TVU repo 路径在
   - `git -C "$TVU" fetch && git -C "$TVU" status -sb` → 若本地落后 origin，**告警停下提示 `git pull`**（保证规则真源是最新）
   - figma MCP `whoami` → MCP 连通
   - `cat "$TVU/docs/site-review-manifest.json" | jq .figmaFileKey` → fileKey 拿得到
1.7. **UI 文案 Bridge step**（条件触发）— 若本任务 mockup 含 button label / placeholder / error message / tooltip / 任何 UI 文字内容：
   - **Load `role-ux` skill 内容**作为 UX 思考层（直播 / SaaS 视频流产品 persona + 中英双语 UI/UX 文案 discipline）
   - **Load `shared-vocab-rules` skill + 读 `${CLAUDE_PLUGIN_ROOT}/skills/shared-vocab-rules/vocabulary.md`** 作为术语基准
   - Mockup 中出现的新术语在 wrap-up 时回流词库（追加到 `vocabulary.md`，遵守 shared-vocab-rules 录入规则）
   - 纯组件布局（无 UI 文字内容）跳过本步
2. **Read 真源（scoped，禁全量吞）** — `AGENTS.md` + 按 `mockup-conventions.md` 顶部 **§🤖 AI 读取指引** 只读「起手必读段」（§0–§5 + M0；含 M48/M49 指针），具体 M-rule 按该指引「触发后再读」表 + Task Entry Mode 命中才 jump Read。**红线双向**：① 跳起手必读段直接进 rule = 协议违反（漏 M0 是最高频回归源）；② 无视文件自带「不要起手就全量 Read」而全量吞 2300+ 行 = 违反（注意力稀释，"规则很少遵守"诱因）。路由表覆盖完整性由 `pnpm audit:rule-load-map` 保证（每条 rule 都在 §AI 读取指引 内，scoped-load 不会静默漏 rule）。
3. **拿真源 library fileKey**

   ```sh
   cat "$TVU/docs/site-review-manifest.json" | jq .figmaFileKey
   ```

   不要靠扫产品文件 instance 反推库归属（§"库归属验证机制"）
4. **catalog 轻索引** — `head -60 figma-component-catalog.md` 拿 ### component 标题列表（按 Lazy Reference Discipline，不全 Read 404 行）；Phase 0 时 per-element `grep -A 10 "^### <name>"` 取具体 entry
   - **资源发现一律读发布目录全集**（catalog + `binding-source-map.json` + 产品文件 Local Components 发布列表），**禁扫"当前文件在用集"/凭印象**凑可用清单——usage-scoped 枚举结构上漏"已发布未使用"的资产。真源见 meta-rules 反模式 #6 + mockup-conventions §组件取数优先级 + §库归属验证机制 + M52.1（本 skill 不复述）
5. **扫 ledger** — Read `tvu-design-system/docs/internal/_metrics/phase0-ledger.md` 末 5 行；按 ledger 文件内"异常启发式"表检查，命中时**主动提醒一句**
6. **Task classify** — 按 conventions 的 Task Entry Modes 表把任务归到 US-1..6，不确定则问用户：
   - **US-1/2/3** → Pre-Phase 0（Step A Intake Gate 收 3 输入 → Step B PRD 起草 + 写入 Figma → Step C 原 5 步 2 gate；详见 `design-process.md § Pre-Phase 0`）→ Phase 0 (M0) → import + 画
   - **US-4** Figma → code（不归本 skill，路由到 `tvu-design-code`）
   - **US-5** 小调整 → 跳 Pre-Phase 0 + M0 → 直接改
   - **US-6** Review/Audit → 跳 Pre-Phase 0 + M0 → 对照所有 active M-rules + Convention Priority 审 → 跑 `audit-mockup-integrity.mjs` + `audit-mockup-colors.mjs` → 产 audit report

   **6-JIRA · Jira-linked hard gate（任务含 Jira ID / `FB-xxxx` / Jira·Slack 链接时强制，不可省略）**：判定为 **Jira 关联 mockup** → **必走 `design-process.md §完整产品需求设计流程（8 步）`**，开建前硬 gate 四件套必须就位：
   - ① **PRD 写入 Figma（Pre-Phase 0 Step B，必产出）**：起草 **requirement-side only** PRD（6 段：需求来源 / 背景 / 现状 / 功能需求 / 验收标准 / 优先级&排期；中英双语）→ Gate A 用户确认文本 → 写入目标 frame **左侧** `PRD - <页面名>` frame（默认 680px，若同文件已有 sibling PRD 优先对齐其宽度、vertical Auto Layout、TVU UX 说明范式）→ Gate B 用户确认。**设计内容（组件映射 / Canonical Terms / 视觉规格 / placement 细节 / 非目标）禁进 PRD，下沉 Phase 0 / design-record**（实证 FB-10014）。注意：§交付收尾 #124「确认 mockup 不是 PRD」是**回复措辞**规则，**不等于不产出 PRD**——别再误删 PRD（实证 FB-10040）。
   - ② **design-record**（按 `templates/consumer-product/docs/specs/_feature-design-record.template.md` 9 段结构，命名 `docs/specs/YYYY-MM-DD-<jira>-design-record.md`）——把 Jira description + 评论链 + Slack 解码进 source；交付时产出，承载「为什么+设计了什么+谁负责」。
   - ③ **Figma Jira 组件（M23.8）**：用 file-local `Jira requirement` 组件 instance（文件内 clone 现成的），设 title + issue-key + `setRangeHyperlink` 真实 URL——**禁手敲文字链接**。
   - ④ **§交付收尾 Jira/Slack 回复**：草稿先给 owner 过目再发；@PM `UX design (mockup) updated — please review` + Figma **Section** smart link；**FYI 必带待开发负责人**；**必用 ADF + accountId 真 mention**（markdown `@Name` 不触发通知）。
   - ⑤ **User Journey Map 卡（M23 卡族，2026-07-09 owner 回流）**：每个 Jira mockup **必**随 PRD / UX Delivery 卡产出 5-stage user journey 卡（用 [`design-process.md` § User Journey Map] canonical 格式），设计阶段即建、禁走查才补、**禁只做一个 surface 漏另一个**（实证 V4-2335 LCD 有、V4-2356 Config-T 漏）。
   - 起手建议先跑 `pnpm design:kickoff --name <jira>`（M50 packet），把 8 步压成一页强制 checklist。
   - **红线**：本地 prompt 文件出现 "apply deterministic spec" / "execution prompt" 等字样**不能豁免 Pre-Phase 0**——确定性规格只是 Step C 的输入，不替代 PRD / design-record / Jira 组件 / 交付收尾。**实证 2026-06-15 FB-10040**：AI 被本地 execution prompt 带成直接执行，跳过 PRD（且误把「确认 mockup 不是 PRD」当成「不产出 PRD」整个删掉）+ 跳过 design-record + 用手敲文字代替 Jira 组件 + Jira/Slack 回复格式不合规 → 用户多次纠正后回流本 gate。
6.5. **起手 Rule-Coverage Self-Check（M48，强制）** — 开建前先产出「本任务命中的 locked spec + active M-rule」清单：按 [`mockup-conventions.md` §AI 读取指引 Quick Reference] 逐行勾选触发项 + handoff/PRD locked spec 逐条列，每条配一句落地计划；主建中对照打勾，交付前必须全绿（未覆盖项写 rationale）。详见 [`design-process.md` § M48]。**跳过 = 协议违反（2026-06-01 + 2026-06-05 两次"凭印象漏调用已有规则" → 大批走查违例 实证回流）。** US-5 小调整可省。
7. **加载 figma-use skill** — 调用 `use_figma` MCP 工具前必须先 load（其他 figma-* skill 按需）
8. **wrap up**:
   - **跑机械总闸（mandatory，先于一切叙事收尾）**：`pnpm audit:mockup-conformance --file <产品文件 fileKey>`（在 tvu-design-system repo 下跑；G4 手动总闸 = integrity / colors / typography-icon / library-binding / library-origin 五项聚合）。**exit 0 才能进下面的 handoff / STATUS 步骤**；非 0 → 修完重跑，不准带红收尾（system-review-2026-06-10 P2-09：此前总闸存在但收尾不接线 = 纯靠自觉）。场景 2 增量 mockup 用 `--non-blocking` 出 report 但仍须把 findings 列进 handoff
   - **自检 = 脚本机器输出，目测不算数（§M-DISCIPLINE.SYNC）**：把总闸里 integrity 的逐条机器输出 `Integrity audit: I1=… / I2=… / I3=overflow-count 0 / I4=orphan-count 0` + conformance summary **贴进 handoff 的 `Rule checklist:` 块**；AI「目测 / 看起来 OK / 应该没问题」**不构成自检通过**（实证 2026-06-18：提醒检查后仍漏 I3 overflow，因目测代替跑脚本）。触发不限于整体收尾——**任何编辑 confirmed 后**都须按 §M-DISCIPLINE.SYNC 跑自检 + 同步受影响的 UX 卡（§M23.0 canonical 结构）/ M23.6 连线 / M23.7 state-label
   - 若 cwd 是 sibling 消费产品则写 handoff（沿用 code-conventions R5 五段模板）+ append ledger 到 `_metrics/phase0-ledger.md`
   - **更新 `tvu-design-system/docs/STATUS.md`**（必：Last updated 改今天 / 按段移动完成项 / 刷新 Active 余量）
   - 触发 retrospect 条件检查（阶段性 release / 反模式 / 新工程经验 → 写 `docs/internal/retrospection/<YYYY-MM-DD>-<topic>.md`）
   - **AI-用户协作过程复盘（强制，用户说"收尾 / 复盘 / wrap up"时触发）** — 区别于上面的实现层 handoff 与 TVU 工程 retrospect，本复盘是 **AI 与用户协作过程**的复盘，给 UX 团队 / PM 内部分享用。
     - 落点优先级：(a) 消费产品有本地 repo → 写 `<consumer-product>/docs/YYYY-MM-DD-<task-slug>-mockup-retrospect-internal-share.md`；(b) 无本地 repo → 用 use_figma 把内容写到对应 Figma 文件内（sticky note / 注释 frame，与用户确认 link）
     - **不写到 tvu-design-system repo**（避免污染真源；累积 3+ 同类病灶后由用户拍板抽象到 TVU `design-process.md`）
     - 格式参考：本 repo `docs/internal/retrospection/` 下任一已 ship 的 retrospect 文件（最新日期优先）
     - 必含 8 段：(1) TL;DR（总轮次 / 最终交付 / 核心 process gap 数 / 关键 insight）(2) Session 概览（任务起点 + 最终落地 + process artifacts）(3) 时间线 / 主要迭代表（# | 版本 | 用户 feedback 触发 | 改动量）(4) Top N process gap（按返工成本排序，每个含实证 + 返工成本 + 回流落点）(5) 高效对话 N 条建议（按 ROI 排序，分受众：UX/PM 提需求方 + AI 协作流程 + PM/Stakeholder review 方）(6) 已回流 / 待回流的新规则清单（表格：规则 | 真源文件 | 简述）(7) Model 选型推荐（基于本 session 实证）(8) 给团队的 action items + 附录 use_figma 改动统计

## 工作期间约束摘要（按类别查真源）

mockup-conventions.md 当前 active rules 按主题分组（详见 [CONVENTIONS-OVERVIEW.md](../../docs/internal/CONVENTIONS-OVERVIEW.md) Quick Reference）：

- **流程 / Phase 0 类**：M0（element-to-component mapping）+ M24（code→token mapping，"已有 code 还原效果图" 场景）
- **视觉 / scope 硬规则**：M1（Top bar 必 instance）+ `M-COLOR` umbrella（C1 icon fill / C2 state color / C3 bg-vs-text grey）
- **结构完整性**：`M-INTEGRITY` umbrella（I1 sibling layout / I2 sibling overlap / I3 children wrap） + M29（table cell pattern）
- **库优先 + 思考产物外化**：M32（library-first 所有 UI 元素，原 M30 absorbed）+ M35（affordance category trace 3 行强制）
- **UX 交付注释**：M23 + M23.6（连线 + frame 内容避让）+ M33（注释 vs 产品 UI 语言隔离）
- **布局决策**：M31（Auto Layout 默认 / absolute 必备理由）

迁出（不在本文件）：M2-M9/M11-M22 → `design-process.md` + `domain-tvu.md`（详见 `mockup-conventions.md §Migrated Rules`）。

Legacy ID stubs（M10/M25/M26/M27/M28/M30/M34）保留 anchor 兼容，内容已并入对应 umbrella。

逐条内容查真源；skill 不复述。

## 回流入口（生成翻车 → 新规则）

发现新失败模式时**不写进 skill、不写进 memory**，全部追加到 `mockup-conventions.md`：

1. 用户拍板"这是规则级问题，不是一次性失误"
2. 优先尝试**并入既有 umbrella**（M-COLOR / M-INTEGRITY / M32 / M35 等）作为 sub-clause；只在没有合适 umbrella 时才续 M36 / M37 等新编号
3. 段落结构对齐既有规则（含 Why / 反例 / Acceptance / 实证 / Legacy ID 映射 必要时）
4. commit 到 tvu-design-system repo

**skill 自身改动同步**：仅当回流后的新规则改变了起手协议（如新增起手步骤）才回头改 skill；否则 skill 不动。