# 档 B 还原实录 — TVU Live & Studio Prototype → Figma（用真实 TVU 设计库）

> 用于分享会：记录「用现在可用的方法（Figma MCP `use_figma` 编程式装配，非 html.to.design）把 Claude Design 产物用 TVU 设计库还原到 Figma」的真实耗时与问题。

## 目标与方法

- **源**：`/Users/nancy/Documents/Claude Design/HTML/TVU Live & Studio Prototype.html`（Claude Design 导出，SaaS dashboard）
- **目标 Figma**：`MnZ5FjRjFcK503juzOFlBr`
- **库**：TVU UX Design System（fileKey `YbsPRUVmNdsbN40NNwh1Gn`，library key `lk-057f6ba0…`）
- **方法**：`search_design_system` 拿 key → `importComponentSetByKeyAsync` + `createInstance`（真实库实例）→ `setBoundVariable` 绑变量 → `textStyleId` 应用文字样式 → `binding-audit` 自查

## 时间线

| 阶段 | 时间 | 说明 |
|---|---|---|
| T0 · 任务开始 | 2026-07-01 12:21:29 | 派 subagent 解析 HTML 全貌 |
| 全貌解析完成 | ~12:34 | 确认 8 屏双产品结构 + 组件频次 + 难点预判（约 13 min） |
| T1 · 装配开始 | 2026-07-01 12:34:58 | 范围定为 Studio Overview 一屏，开始 discovery + 装配 |

## 范围

**HTML 全貌（subagent 解析）：双产品 8 screen**
- TVU Live（C 端，无 sidebar）：Discover / Room / Channel
- TVU Studio（B 端，220px sidebar）：Overview / Stream Settings / Broadcast / Monitoring / Destinations
- 组件频次：button×46、icon×85+、badge×10+、input×3 / textarea×1、SVG polyline 图表×3；**无原生 table/select/toggle（全自绘）**
- 库可 Swap：Button / Badge / Icon / Tabs / Input / Textarea / **Chart**；库无需自建：KPI 卡片、数据表格、Sidebar 布局、视频播放器、Toggle、Select、Avatar

**决策（用户拍板）：完整还原 Studio Overview 一屏**作代表——覆盖 ① 全局框架（TopBar 64px + Sidebar 220px）② 库组件 Swap（banner button/badge）③ 库无需自建（KPI 卡片×4 / quick actions）。折线图改用库 Chart 组件。

## 问题记录

**#1 · 预判偏差（好消息）** — 全貌解析时预判「折线图需自建」，实际库里有 `Chart` COMPONENT_SET（line/bar/pie/donut，颜色绑变量，key `080b12ba…`）→ 少一处自建。教训：自建前务必先 search 库，别凭预判。

**#2 · icon 命名 HTML ↔ 库不一致** — HTML 用 `#navigation/monitoring`、`#navigation/dashboard`、`#media/video-camera` 等 key；库 icon 组件却是 `icon/Menu/Monitor`、`icon/Video/go to` 等（不同分类/命名）。无法按 key 直接对应，需逐个按语义 search + 人工判断 → icon 是本次最大耗时/易错点。icon 映射表（HTML key → 库组件名）：logo→`icon/logo/TVU`、media/live→`icon/indicator/live 2`、navigation/dashboard→`icon/Menu/Dashboard`、navigation/monitoring→`icon/Menu/Monitor`、media/video-camera→`icon/Video/Camera`、action/share-to-platforms→`icon/share/share to platforms`；**仅 stream-settings 的 preferences icon 未找到精确对应**（用近似/占位）。

**#3 · 库组件覆盖远超预判（重要正面结论）** — discovery 发现库里现成 COMPONENT_SET 远比全貌预判多：`Top bar`(918b928e)、`Chart`(080b12ba，line/bar/pie)、`Table`(a9b646df)、`Pill Status`(eff51671)、`Badge`(4db5246d) 全都有。全貌预判的「需自建」清单（TopBar/图表/表格/状态 pill）大部分其实库已提供 → 档 B 实际复用率比预期高，自建主要剩 KPI 卡片 / Sidebar 布局 / quick-actions 卡片这类「组合层」。

**#4 · 库 `Top bar` 组件与原型不符（存在 ≠ 能用）** — 库有 `Top bar` COMPONENT_SET，但它是通用「登录后」布局（logo + 搜索框 + 菜单 + 用户 avatar，2 变体 After/Before Login，169 子节点），不含原型的 product-switch(Live/Studio) + demo-state + 语言切换定制。判断：不套库成品，改用库原子（icon/button/变量）自建 topbar 组合层。结论：库组件「存在 ≠ 能直接用」；高度定制布局用原子自建更合适。demo-state 演示控件省略（非产品功能）。

## 结论（供分享）

**成品**：Figma `MnZ5FjRjFcK503juzOFlBr` 内 screen `32:114`「Studio · Overview (TVU DS 还原)」，1440 宽整屏，深色主题。

**耗时（真实记录）**：
| 段 | 时间 | 用时 |
|---|---|---|
| 全貌解析（8 屏结构 + 组件频次 + 难点） | 12:21:29 → ~12:34 | ~13 min |
| Studio Overview 一屏装配（key 映射 discovery + 逐 section 建） | 12:34:58 → 12:49:44 | ~15 min |
| 验收（binding-audit + 修白底 bug） | 12:49:44 → ~12:52 | ~3 min |
| **合计** | | **约 30 min / 一个中等复杂 dashboard 页** |

**库复用**：14 个真实库实例，**全部 `remote=true`**（logo/live/dashboard/video/monitor/share icon + Button×2 + Chart×1）。颜色 / 文字全绑 TVU Variables + Roboto 文字样式；binding-audit 全屏仅 3 处未绑（透明容器默认白底 bug，已修）。

**自建组合层**（库无对应，用库 icon/Button/变量/文字样式 搭）：TopBar 布局、Sidebar、banner、KPI 卡片、Quick actions 卡片。

**问题清单汇总**：
1. **icon 命名 HTML ↔ 库不一致** → 最大耗时点，逐个语义 search 映射（#2）。
2. **库覆盖超预判**（TopBar/Chart/Table/Pill 库都有）→ 自建清单收窄，好消息（#1/#3）。
3. **库 TopBar 是通用登录布局、与原型 product-switch 定制不符** → 用库原子自建（#4）。
4. **透明容器默认白底未清** → binding-audit 揪出 3 处、已修（人审价值）。
5. **Chart 用库默认示例数据**（X 轴月份），非原型真实时序 → 示意用途，真实数据需另配。
6. 装配 API 命名空间（`figma.variables.importVariableByKeyAsync`）subagent 首个 call 踩坑即修。

**对比 html.to.design（分享金句）**：
- **html.to.design**：秒级导入，但产出无语义图层，之后手动 Swap / 绑定是纯体力活，且永远不连库。
- **档 B（本次）**：约 30 min / 屏（含解析），产出**真·库组件实例 + 绑变量**（选中即库组件、库更新联动、切 Dark/Light 自适应）。**前期慢、后期一致性强，但非一键——需 AI 判断 + 人审**（本次靠 binding-audit + 人审修了白底 bug；此前 pilot 还修过 button theme、红点漏绑）。

---

# 追加：TVU Live · Discover 还原（第 2 屏，用于和 html.to.design 对比）

**对比基准**：html.to.design 导入版 = section `14:822`（同一份 HTML 的 Discover 页，普通图层）。档 B 还原同屏做 1:1 对比。

## 时间线（Live）
| 阶段 | 时间 | 说明 |
|---|---|---|
| T-live0 · 任务开始 | 2026-07-01 12:59:34 | 定位对比基准 14:822 + discovery |

## Discovery 发现（Live 特有）
- **库无通用 `Card` / `Avatar` 组件**（仅 icon/pay/card）→ Featured banner、Live Now 卡片、Top Streamer 头像 均需自建（frame + 变量 / 圆 frame + 首字母）。本屏主要自建工作。
- search icon 找到（`icon/Search/Search`）；**分类 icon（Gaming/Sports/Music/IRL/Tech/News/Talk/eSports）库命名不匹配** → 用通用占位 icon（又一 icon 映射坑）。
- Button / Badge / Pill Status / 变量 / 文字样式 / logo / live icon 复用 Studio。

## 给 Claude Design 的上游改进反馈（用户 2026-07-01，根因在生成端）

档 B 下游丢图标的根子在 Claude Design 生成时。要求 Claude Design 遵守两条，让「Claude Design → 档 B」彻底顺滑：
1. **图标只用 TVU 设计库里真实存在的**——不要生成外部 sprite 键名（如 `media/score`，库里无 `media/` 前缀）、不要造题材图标（库是 B 端制播语义，无内容题材图标）。用不到库图标的场景应显式标注，而非引外部 sprite。
2. **嵌入的图标/背景图，导出独立 HTML 时必须栅格化内联**（base64 data-URI，而非运行时 `fetch(sprite.svg)` 外部引用）——这样下游 AI（档 B / html.to.design）能直接拿到图形还原。
→ 已请 subagent 加入 `docs/CLAUDE_DESIGN_RULES.md`（未 commit）。

## 装配 / 问题 / 结论

### 成品与耗时
- **成品**：screen `41:396`「Live · Discover (TVU DS 还原)」（x=7550），1440×1370，深色。对比基准 `14:822`（html.to.design 版，同一 HTML）。
- **耗时**：T-live0 12:59:34 → 装配完成 13:20:02，**约 20.5 min**（复用 Studio 全貌解析 + key，省去重新解析；含 Live 特有 discovery + 装配 + 验收）。**第 2 屏比第 1 屏快**——解析与 key 复用摊薄了成本。

### 库复用与 componentize
- 21 个实例：**14 库实例**（logo/live/dashboard/search icon + Button×2）+ **7 本地卡片实例**。
- **✅ 重复模块 componentize 落实**：Live 卡片建为 1 个本地主组件 `45:342`，place 7 实例（binding-audit instanceBySet 显示 7 个本地实例）——改一处即全改，符合产品设计原则。
- 颜色 / 文字全绑变量 + Roboto 文字样式；透明容器 **0 白底漏清**（吸取 Studio 教训）。

### 问题清单（Discover）
1. **库无 Card/Avatar** → Featured banner / Live 卡片 / avatar 自建（avatar = 方 frame + cornerRadius 半宽 + 首字母）；体感良好。
2. **分类 icon 命名不匹配** → 8 个 chip 用 Search icon 统一占位（真实需逐个映射专属 icon）。
3. **Featured banner 渐变 + 装饰未还原** → 用 Layer_2 纯色替代（原版是品牌绿径向渐变 + 箭头，档 B 简化）。
4. 库文字样式是 **Roboto**（非 Inter）；`FRAME.padding` 简写不存在（用四边 padding，subagent 一次修）；9 处白文字是合理白（LIVE 红标白字 / avatar 首字母）。
5. **⭐ 位图/背景装饰丢失（关键对比点，用户 2026-07-01 发现）**：Live 卡片缩略图中间的占位图标、Featured banner 的品牌绿径向渐变 + 装饰，档 B 还原版**丢失**，html.to.design 版**保留**。原因：① 装配 spec 主动把缩略图/banner 简化为纯色占位；② HTML 里图标全是**外部 sprite 引用**（`<use href="#media/score">`，运行时 fetch `assets/icons/sprite.svg`，该 sprite **未随 HTML 导出、磁盘不存在**）→ HTML 里拿不到图标 path，`createNodeFromSvg` 无源可用。渐变/头像/色块则可从 HTML CSS 值直接 `GradientPaint` 重建（banner `120deg #0b2b13→#141414` + brand 绿 radial 光晕、缩略图 `hsl(hue…)`、头像渐变）。HTML 无位图。

6. **⭐⭐ 图标映射：此前「库无题材图标」的结论是错的（2026-07-01 经 Claude Design 实证纠正，务必更正分享口径）**：这 9 个品类图标**确实在 TVU 库内**，只是**按功能命名**——体育=`icon/Video/Score`、音乐=`icon/audio/audio`、游戏=`icon/Video/Clip player`、新闻=`icon/Video/Live caption`、科技=encoder、访谈=chat、户外=location、电竞=program、美食=`icon/Video/media`；代码 sprite 里则按 `media/*` 命名——**同一批图标、两套命名**（figma-sync 抽取时重命名）。误判根因：① 用「题材词」(gaming/sports/music) search 库，撞不上**功能命名**的图标；② HTML sprite 未随导出、拿不到 path；③ 据此下了「库无题材图标/产品域不匹配」的**过重错误结论**。**正解**：用功能语义词（score/audio/clip-player/encoder/chat/location/program…）或 Claude Design 的 CAT_META 映射，库里都能找到。

   **⭐ 修正后的分享金句**：**档 B 的真正瓶颈不是「库缺图标」，而是「命名映射」**——库里有，但 sprite 键名(`media/score`)↔Figma 库名(`icon/Video/Score`)是两套命名，AI 靠语义 search 容易撞不上、误判为「缺」。这恰恰证明**需要一张权威的 键名↔库组件 映射表**（Code Connect 的本职）。**教训：别因「搜不到」就下「库里没有」的结论。**（注：因此需回头修正 `CLAUDE_DESIGN_RULES §2.1` 里「库无题材图标」的错误论据——规则「用库既有图标、别造库外 sprite 键名」方向仍对，但理由要改成命名映射问题。）

### 对比 14:822（html.to.design 版）
布局 / 内容高度一致；档 B 版 = **真库实例 + 本地组件化卡片 + 全绑变量**（选中即组件、改组件全改、切主题自适应）；html.to.design 版 = **平铺普通图层**（需手动 Swap、不连库、无组件复用）。

### 补图后（从 HTML 重建渐变 + 库近似 icon，全程不经 html.to.design）
- **Featured banner**：品牌绿线性渐变 + 右上 radial 光晕（GradientPaint 从 HTML CSS 值重建）✅ 贴近原版。
- **缩略图**：蓝渐变底 + 中心 `icon/Picture/thumbnail` 占位（改主组件、7 卡跟随）——componentize 折中：7 卡统一（原型每卡不同 hue/icon，需 property/instance-swap 才能还原差异）。
- **avatar**：渐变底（统一 hue）。
- **Browse Categories 8 icon**：换库语义最近 icon（6 精确 Sports/Music/IRL/Tech/News/Talk + 2 近似 Gaming→Monitor、eSports→星标）——库无题材图标，可接受折中。
- 小瑕疵：chip icon 上色用 SOLID 灰（instance 内部，binding-audit 不下钻未报；未绑变量，可后补 override）。
- **结论**：渐变/色块/头像能**纯从 HTML 重建**（GradientPaint）；图标此前误以为"库无题材资产"，实为命名映射问题（见 #6 纠正）。

### 最终修复（经用户走查纠正，Claude Design 提供权威映射）
- **7 卡差异化**：缩略图 icon 做成主组件 INSTANCE_SWAP property（`thumbIcon`），7 卡各 swap 对应品类**真库图标**（Video/Score、Video/Program、Video/Live caption、audio/audio、location、Video/Encoder、Video/media）+ 底色按各 hue override → 7 卡各不相同、仍是同一组件的实例。
- **Browse Categories**：竖版布局对齐 HTML（icon 顶 + 名 + count 底，150×96）+ 8 个真库图标（Clip player/Score/audio/location/Encoder/Live caption/Chat/Program，两两不同）。
- **证实**：9 个品类图标全在 TVU 库内（按功能命名），此前「库无题材图标」是误判——真瓶颈是命名映射（sprite `media/*` ↔ 库 `icon/Video/*`）。
- **图标上色（2026-07-01 新 session 核实并真正落地）**：8 chip 图标按 HTML `--chart-color-N` 映射上色（Gaming 紫#9a4ee5 / Sports 蓝 / Music 洋红#e54eb4 / IRL 青绿#2dceae / Tech 绿 / News 红 / Talk 橙 / eSports 靛蓝#4e6ee5），与 HTML 一致。
  - ⚠️ **纠错**：上一 session 记「已上色（硬编码）」实际**未落到文件**——本 session 打开时 8 图标全是灰色。现已真正上色。
  - **chart-color 真相（重要，回答"库里有没有 chart-color 变量"）**：`--chart-color-1..12` 是**代码侧 token**（`tvu-design-system/src/tokens/variables.css:78-89/356-367`），**未作为 Figma 变量发布**。其中 **1..4 是别名**（复用 brand/red/blue/orange，这 4 个在 Figma 有变量 `UX/Brand·Red·Blue·Orange`，Chart 组件也正是绑这 4 个 UX 色）；**5..12 是裸 hex**（HSL 旋转派生的图表专用色板），**Figma 库里无对应变量**。→ 故本次上色：能绑的 4 个（Tech/News/Sports/Talk）**绑 UX 库变量**；库无变量的 4 个（IRL/Gaming/Music/eSports）**按 HTML 裸 hex 硬编码 + 标注**（纪律允许的例外）。
  - **金句更新**：这是又一个 **code↔Figma token 同步缺口**——不是"库没有色"，是"12 色 chart 板只有 4 个（别名）在 Figma 有变量，另 8 个图表专用色从没 publish 成 Figma 变量"。与图标"命名映射"是同一类根因。**根治**：把 `--chart-color-5..12` 作为 Figma 变量发布进 TVU 库（owner 决策），下游即可全绑。
  - **缩略图底色**：从 HTML CSS 重建的**深蓝渐变**（GradientPaint 多停靠点），库无渐变 token，回绑单色是降级 → **保持渐变不动**（用户 2026-07-01 拍板）。

---

## 待办（context 满，转新 session 续）
1. ~~**chart-color 回绑变量**~~ **✅ 已办结（2026-07-01）**：核实结论——`--chart-color-1..12` 是代码 token，Figma 库只有 1..4 的别名变量（UX/Brand·Red·Blue·Orange），5..12 无 Figma 变量。故 8 chip 已上色：4 个绑 UX 变量、4 个硬编码 hex+标注；缩略图保持渐变。**遗留建议**：把 chart-color-5..12 publish 成 Figma 变量（owner 决策，见 #4）。
2. ~~**复盘做成 Figma Slide 页内展示**~~ **✅ 已办结（2026-07-01）**：复盘文档 `docs/track-b-retrospective-share.md`（8 页骨架）已写；Figma 文件内建 8 个横向 frame 模拟 slide（node id 67:547 / 68:546 / 70:546 / 71:546 / 73:546 / 74:546 / 75:546 / 76:546，x=9300 起、间距 80、1280×720 深色）。全绑 TVU 变量 + Roboto 样式，binding-audit 干净（唯 5 处绿底徽章白数字属刻意）。componentize：因 Figma 实例不能向 content slot append 子节点，退用统一 `buildShell()` 函数保证 8 页格式一致。
3. ~~**CLAUDE_DESIGN_RULES §2.1 论据纠正**~~ **✅ 已办结**：论据改为「命名映射问题」，并补 chart-color 同步缺口注（同类根因）。
4. ~~**3 处 TVU DS 仓库文档 commit**~~ **✅ 已办结**：commit `408b2aaa`（master），仅 M36.1 / F1.6 / CLAUDE_DESIGN_RULES 三个文档文件（用户拍板只提交这 3 个）；顺带修好卡提交的 2 个过期锚点。App.tsx / ChartPage / 验证报告 / screenshots 等 6 项其它工作区改动**未动**（疑属别的 session）。**遗留 owner 决策**：是否把 `--chart-color-5..12` publish 成 Figma 变量（根治 code↔Figma 缺口）。
5. **⭐ 图标用错了库（重要，用户 2026-07-01 纠正）**：IRL/eSports 看着有"背景色"的真因**不是实心图标**，而是 subagent 补图标时**没锁 `includeLibraryKeys`**，从**错误的库 `TVU UX Library`** 取了图标（如 IRL 的 `icon/RC/location 1`，RC 前缀=TVU UX Library），而非唯一权威库 **TVU UX Design System**（`YbsPRUVmNdsbN40NNwh1Gn`）。那个库图标风格不同 → 看着像带底色块。
   - **避免机制**（已记入 [[figma-assembly-self-check]] 第 6 条）：① 所有 search 强制传 `includeLibraryKeys=[lk-057f6ba0…]` 锁定 TVU UX Design System；② 找不到明确报「库无」，禁止 fallback 到其他库；③ 走查核每个 remote 实例来源库；④ 派 subagent 时 prompt 必写「只锁 TVU DS 库、找不到报缺不 fallback」。
   - **新 session 待办**：把 IRL/eSports（及全屏）用错库的图标**换回 TVU UX Design System** 的对应图标（或明确标注 TVU DS 无、需自绘）。
   - **这条教训必须写进复盘文档 + Figma Slide**（用户点名）。
   - **回流治本（用户 2026-07-01 追问「有没有回流到设计系统」）**：锁库纪律不能只留在助手 memory + 本项目实录（治标、只管「我」）；已派 subagent **回流到 TVU DS 仓库规范**（mockup-conventions.md 新 M 条 + 复盘，未 commit），团队共享才治本。**enforcement 升级建议**：① 派装配 subagent 的 skill/模板内置「锁 TVU DS library key」；② audit 脚本 `audit:instance-library-source` 扫产物里 remote 实例来源库，非 TVU DS 报警——光文档自觉不够，需机制强制。

## Live 任务总耗时
T-live0 12:59:34 → 补图验收完成 ~13:5x，**约 40–50 min**（含 discovery + 装配 + 库图标核实 + 从 HTML 提取 + 补图）。比 Studio 首屏（~30 min）多，因额外做了「库图标核实 + HTML 提取 + 补图」这轮探索——**这些是一次性认知成本，已沉淀为 M36.1 规范 + Claude Design §2.1/§2.2 规则 + 本实录结论**，后续同类还原不必重走。

---

## 设计走查清单（每屏还原后必查 · 规则来源：产品设计原则 + 用户 2026-07-01 强调）

1. **重复模块 componentize（硬规则）**：卡片 / 列表行 / KPI 格 / chip / streamer 行等 ≥2 个相同模块，必须是本地组件的 instance（有 mainComponent），**不得平铺独立 frame**。前期分析即规划、装配 build-once-place-instances、走查逐一核对（用 binding-audit 的 instanceBySet 佐证）。改一处即全改。
   - ⚠️ **Studio Overview 待补**：KPI×4、Quick actions×3 当前为独立 frame，未 componentize → 需补建本地组件 place 实例。
   - **Discover**：Live 卡片已要求 subagent componentize（验收确认真做了）。
2. **binding-audit**：无未绑变量的实色（meta 容器除外）。
3. **组件 theme 匹配**：深色底用 dark set；跨 set 实读变体名（light `Radius=` / dark `radius=`）。
4. **透明容器 `fills=[]`**：非卡片容器不留默认白底。
5. **文字用库文字样式 + 色绑 Text 变量**；icon 上色成功。