--- marp: true theme: tvu-dark paginate: true size: 16:9 header: 'MicroApps Console · Figma Mockup 复盘 · 2026-05-09' footer: 'Nancy Zeng × Claude Opus 4.7 · 内部分享' --- # MicroApps Console · Figma Mockup ## 复盘：AI × UX 协作真实过程 **Nancy Zeng** · UX Designer **Claude Opus 4.7** · AI 协作伙伴 2026-05-09 · 单 session --- ## TL;DR - **轮次**：~8 轮 user feedback (v1 → v8) · 50+ `use_figma` calls - **交付**：MC + MS 双页 mockup + 10 条 UX 标注 + 13 条 polyline connector + 24 health wrapper swap - **规则回流**：4 条（library key filter / 颜色不假设 / connector workaround / read-only viewer） - **核心 insight**： > **前 7 轮没读 PRODUCT_CONTEXT.md spec — v8 拿到真源一次全量重写，前面 80% 细节作废** --- # 1 · Session 概览 --- ## 起点 & 落地 **起点**：MC / MS 有早期 mockup，但 UX 交付标注是中英混合的散框，连接线乱，内容陈旧。 **最终落地**： - 删 11 旧框，建 10 个 anchored 卡片（A1–A8 + A_State + A_Order） - 13 条 polyline 折线（VECTOR + vectorNetwork — design mode 没原生 Connector） - 24 个 health wrapper component swap 到 **TVU UX Design System** 库 - 3 份产品 decisions 文档落地 --- # 2 · 时间线 v1 → v8 八轮迭代 --- ## 时间线（精选 6 个转折点） | # | 版本 | 用户原话 | 性质 | |---|---|---|---| | 1 | v2 | "连接线全是直线对角穿越 UI 太乱" | AI 默认偷懒 | | 2 | v5 | "**A_State 颜色完全写反了**" | AI 凭印象写颜色 | | 3 | v6 | "**Console 是纯查看，没 New Session / 没 Clone**" | AI 架构理解错 | | 4 | v7 | "Health 颜色对齐 TVU UX **Design System**（不是 Library）" | AI 库混淆 | | 5 | v8 | "**按 PRODUCT_CONTEXT.md spec 全量重写**" | AI 前 7 轮没读 spec | --- # 3 · Top 5 Process Gap 按返工成本排序 --- ## Gap 1 · 画图前没读 spec 真源 ⚠️ **实证**：v1-v7 按"已有 mockup + 用户口头"画 — 没主动读 PRODUCT_CONTEXT.md **返工**：~6 轮标注作废（v1-v7 80% 细节在 v8 重写中被覆盖） **原因**：AI 信任「在场 UI + 口头反馈」 > 「未读 spec 文件」 **✅ 解决方案**： - **当下修复**：v8 按 PRODUCT_CONTEXT.md 全量重写 10 条标注（术语 Enterprise→Company / 4-state 平铺→3 个 type-specific 状态机 / 删伪造 default sort + XL/L/M breakpoint） - **长期防护**：`@TVU mockup` skill Phase 0 强制 read product context spec → 把"术语 / 状态机 / cardinality"清单贴 user verify 后才能调 `use_figma` - **真源落地**：⏳ 待回流 `tvu-design-mockup` skill SKILL.md（已 2 例：Video Sync + 本 session） --- ## Gap 2 · A_State 颜色凭印象写 **实证**：我默认 on-air = 绿（运行中）— **错**。页面真值：On-air=**#ea4233 红** / Preview=**#2fb54e 绿** / Analyzing=蓝 / Inactive=灰 **返工**：A_State 整段重写 + cross-context 红绿色复用警告 **原因**：UX 交付的颜色含义 = 产品规范，不允许 AI 凭直觉 **✅ 解决方案**： - **当下修复**：`getFills` 抓页面 Counter Pills / State Pill / Card badge 真色 → `setRangeFills` 让每行 ● dot 渲染真色 + 加 cross-context 红绿色复用警告 - **长期防护**：写任何产品语义颜色描述前**强制 probe**目标节点真值 → 贴出"我抓到的真值是 X"给 user verify 再写交付 - **真源落地**：✅ 已落 TVU `mockup-conventions.md` "颜色含义不假设" 规则 --- ## Gap 3 · TVU library key 混淆 **实证**：两个名字很像的独立库 — TVU UX **Library**（旧）vs TVU UX **Design System**（新），component 名几乎一样但 `libraryKey` 不同 **返工**：24 health wrapper 全 swap 一遍 + decision log + PRODUCT_CONTEXT 双向更新 **原因**：`search_design_system` 默认跨库返回，AI 不会自动校验 libraryKey **✅ 解决方案**： - **当下修复**：24 个 health wrapper swap 到 TVU UX Design System 库 + Success/warning/Error 三态绑色 variable（`UX/Brand/Brand` / `UX/Orange/Default` / `UX/Red/Default`） - **长期防护**：`search_design_system` 任何写操作前**显式传 `includeLibraryKeys`** 锁库；search 后贴"我从 `` 拿到 X" 给 user verify - **真源落地**：✅ 已落 TVU retrospection `2026-05-11-library-key-confusion.md` + `figma-technical-reference.md` --- ## Gap 4 · Master Console = 监控页 **实证**：v1-v5 当 MC 和 MS 是 1:1 镜像页面画 — 留了 8 个 + New Session 按钮 + 16 个 Clone 图标 + URL placeholder 可编辑。v6 用户纠正：「**MC 纯查看 / New Session 和 Clone 只在 MS**」 **返工**：29 个元素隐藏 + A4 标注重写按 MC vs MS 分列 **原因**：cardinality 问题 — MC/MS 是 viewer/editor 不是 1:1 镜像。和 Video Sync session 同模式 **✅ 解决方案**： - **当下修复**：隐藏 8 + New Session + 16 Clone + 5 URL → "—"；A4 重写为 MC（read-only viewer）vs MS（CRUD editor）差异表 - **长期防护**：起手必问 5 个 cardinality 问题 — (1) viewer/editor (2) 1:1/1:N/N:N (3) 状态机数+触发者 (4) 默认规则来源 (5) 多页之间关系 - **真源落地**：✅ 产品 decision 已落 [`docs/decisions/2026-05-09-master-console-readonly.md`](../decisions/2026-05-09-master-console-readonly.md)；⏳ M-CARDINALITY 5 问待累积第 3 例上 `design-process.md` --- ## Gap 5 · Connector design mode 限制 **实证**：v2 改折线 connector，v4 发现 abs 位置错位（用 v.x/y 直接设导致页级绝对坐标错） **返工**：~3 轮 connector 重绘 + 1 轮 abs 坐标 bug 修复 **原因**：Figma plugin API 在 design mode 不允许 `CONNECTOR` 节点（只 FigJam 支持）— AI 按 FigJam 经验直接试报错才转向 **✅ 解决方案**： - **当下修复**：用 `VECTOR` + `vectorNetwork` 双 vertex + 端点 `strokeCap = ARROW_LINES` 模拟 connector；abs 坐标用 `relativeTransform` 替代 v.x/y 直设；每条 connector 用 `setSharedPluginData('uxAnno','meta',JSON)` 存 anchor - **长期防护**：design mode 写 connector 类需求前先查 `figma-technical-reference.md` Connector workaround 段；半自动 routing pattern（"用户拖节点 + rebuild" → 脚本读 metadata → fetch → 重画）成为标准 - **真源落地**：✅ 已落 TVU `figma-technical-reference.md` "Connector workaround" 段 --- # 4 · 高效对话 5 条建议 按 ROI 排序 --- ## 给 UX / PM（提需求方） **(1) 第一句话就交 spec 真源路径** ❌ "给 MC / MS 加交付标注，全英化" ✅ "给 MC / MS 加交付标注，全英化，**先读 docs/MICROAPPS_PRODUCT_CONTEXT.md §3-5 的产品术语 / 状态机 / 3-type action matrix，确认理解后再画**" --- ## 给 UX / PM（续） **(2) 颜色 / 术语 / 状态机 = 产品规范，要求 AI probe** ❌ 让 AI 自己决定 on-air 是红还是绿 ✅ "State 列颜色从页面 Counter Pills `getFills` 抓真值，不要凭印象写" --- ## 给 AI 协作流程 **(3) Phase 0 强制 read product context 真源** `@TVU mockup` skill 应检查 cwd `docs/` 下是否有 product spec，有就先读。 **(4) 产品语义字段强制 probe** 颜色含义 / 状态名 / 术语都必须从现有节点抓真值，不允许"based on common UX patterns"推理。 --- ## 给 PM / Stakeholder（review 方） **(5) Cardinality checklist 上墙** Review 时先过 4 问： 1. 这页是 **viewer 还是 editor**？ 2. 对象之间 **1:1 / 1:N / N:N**？ 3. **状态机几个 state**？谁能触发？ 4. 默认排序 / 默认过滤是 **产品决策还是 AI 推理**？ --- # 5 · 规则回流 --- ## ✅ 已落回流（4 条） | 规则 | 真源 | |---|---| | Library 搜索必须 `includeLibraryKeys` | `figma-technical-reference.md` + retrospection | | 颜色含义不假设 / 必须 probe | `mockup-conventions.md` | | Design mode Connector workaround | `figma-technical-reference.md` | | MC = read-only viewer | `MicroApps/docs/decisions/2026-05-09-master-console-readonly.md` | ## ⏳ 待回流（累积触发） - Phase 0 强制 read product context（已 2 例：Video Sync + 本 session） - M-CARDINALITY 起手必问 5 问题（已 2 例，待累积第 3 例） --- # 6 · Model 选型 --- ## Opus vs Sonnet vs Haiku | 模型 | 适合 | 本 session 起作用时刻 | |---|---|---| | **Opus 4.7** | 主对话 / 跨文件回流 | v8 一次扫完 spec 同时对齐 10 条标注 | | **Sonnet 4.6** | batch 改 / probe / swap | v2 折线重绘、v7 24 health swap | | **Haiku 4.5** | 轻 probe | 不适合主对话 | **Hybrid**：Opus plan owner + Sonnet executor 本 session 全 Opus 跑 → 估算可省 ~40% token --- # 7 · 给团队的 3 个 Action Items --- ## Action Items **1. 起手交付 spec 真源** > UX / PM 在 task 第一句话里给具体路径 + 段号，不依赖 AI 找。 **2. 产品语义字段强制 probe** > AI 写颜色 / 状态 / 术语前必须 `getFills` / `getCharacters` 抓现有节点真值，写完贴出真值给 user verify。 **3. Cardinality checklist 上墙** > Review 时先过 4 问，不在 v6 / v7 才发现架构错了。 --- # Thanks **MicroApps Console · Figma Mockup 复盘** 配对 code 复盘 → [2026-05-13 MicroApps Console Code](2026-05-13-microapps-console-code-retrospect-internal-share.md) 同模式参考 → [2026-05-20 Video Sync Mockup](2026-05-20-video-sync-mockup-retrospect-internal-share.md) 复盘人：Nancy Zeng (UX) × Claude Opus 4.7 2026-05-21