# 档 B 还原复盘 — Claude Design → Figma（用真实 TVU 设计库）

> 团队内部分享稿。**示例产物 = TVU Live & Studio Prototype（SaaS dashboard）**，双产品 8 屏中还原 Live·Discover + Studio·Overview。
> 本文件是「一份文件」的单一源，对应 Figma 横向 slide 页。详细实录见 `track-b-restore-log.md`。
> 分享：Nancy · 受众：产品 & UX 设计师 · 2026-07-01

---

## 一、背景 · 两条通路

下游要「把 Claude Design 产物搬进 Figma 并连上设计系统」，有两条路：

- **html.to.design（旧路）**：DOM 像素级导入。秒级、视觉保真，但产出**无语义普通图层**，之后手动 Swap/绑定是纯体力活，**永远不连团队库**。功能不存在，非付费墙。
- **档 B（本次）**：Figma MCP `use_figma` 编程式装配**真实库实例**。前期慢、非一键，但产出**真组件 + 绑变量 + componentize**——选中即库组件、库更新联动、切 Dark/Light 自适应。

## 二、方法 · 档 B 通路（5 步）

1. `search_design_system` 拿组件/变量 **key**（必带 `includeLibraryKeys` 锁唯一权威库）
2. `importComponentSetByKeyAsync` + `createInstance` → 真实库实例（`remote=true`）
3. `setBoundVariableForPaint` 绑色 / `setBoundVariable` 绑间距
4. `node.textStyleId` 应用库文字样式（Roboto）
5. `binding-audit` 只读自查：揪未绑实色、选错 theme、来源库

## 三、成果（2 屏）

- **Studio · Overview**（screen 32:114）：TopBar+Sidebar 框架、库组件 Swap、KPI/Quick 自建组合层、库 Chart。~30 min（含 8 屏全貌解析 ~13 min）。
- **Live · Discover**（screen 41:396）：Featured banner、Live 卡 componentize（1 主组件 place 7 实例）、8 分类 chip。对比 html.to.design 导入版 14:822。~20–50 min（第 2 屏更快，解析/key 复用摊薄）。
- 库复用：Studio 14 + Live 14 库实例 + 7 本地卡片实例，颜色/文字全绑 TVU 变量 + Roboto 样式。

---

## 四、⭐ 还原过程的问题 → 如何解决 → 后续如何预防

> 这是本次分享的核心。档 B ＝ **AI 装配 + 人审**：下面几乎每个问题都靠走查 / binding-audit / 用户实证揪出，并已**沉淀成规则回流到 TVU 设计系统仓库**（团队共享才治本，不只留助手 memory）。

| # | 遇到的问题 | 如何解决（本次） | 后续如何预防（已沉淀） |
|---|---|---|---|
| 1 | **图标命名映射**：sprite 键名 `media/*` ↔ 库 canonical 名 `icon/Video/*` 两套命名，用题材词 search 撞不上，一度误判「库无题材图标」 | 改用**功能语义词** search（score/audio/clip-player/encoder…）；用户拿 Claude Design CAT_META 实证纠正 | `CLAUDE_DESIGN_RULES §2.1` 论据改为「命名映射问题」；根治＝权威「键名↔canonical」映射表（Code Connect 本职，见第五节）|
| 2 | **图标取错库**：IRL 用了旧库 `TVU UX Library` 的 `icon/RC/location 1`（装配没锁库、fallback 到别的库）| 排查 remote 实例来源库，换回权威库 `TVU UX Design System`（收尾项）| `mockup-conventions §M32.3`：全程只锁唯一权威库、search 带 `includeLibraryKeys`、miss 报缺不 fallback；+ 机制强制（subagent 模板内置 + audit 脚本）|
| 3 | **重复模块漏 componentize**：Studio KPI×4 / Quick×3 平铺成独立 frame | 走查发现、补建本地组件 place 实例 | `mockup-conventions §M36.1` componentize 三阶段硬规则 + `design-process F1.6` 走查维度 |
| 4 | **AI 选错组件 theme**：深色底误用了浅色（light）Button set | 走查发现、换 dark set | `figma-assembly-self-check`：跨 set **实读变体名**（light `Radius=` / dark `radius=`）、深色底用 dark set |
| 5 | **漏绑变量被硬编码**：状态红点直接写死颜色 | binding-audit 揪出、补绑变量 | 搭完**必跑 binding-audit**（报未绑实色 + 每实例 theme/remote/来源库）|
| 6 | **透明容器露白底**：非卡片容器默认白 fill 在深色屏露白块 | binding-audit 揪出 3 处、清 `fills=[]` | binding-audit + 透明容器 `fills=[]` 纪律 |
| 7 | **位图/背景装饰丢失**：HTML 图标是外部 sprite（`<use href>`，sprite 未随导出）、`use_figma` 搬不了外部图 | 渐变/色块/头像从 HTML CSS 值用 `GradientPaint` 重建；位图无源 → 占位 | `CLAUDE_DESIGN_RULES §2.2`：导出 standalone HTML 时图标/背景须**栅格化或内联**，禁运行时外部 sprite fetch |
| 8 | **chart-color 无 Figma 变量可绑**：`--chart-color-5..12` 代码有、Figma 无（一度误判「库缺变量」）| 查明是 **code↔Figma 真源方向**问题：1..4 是 brand/red/blue/orange 别名（Figma 有变量、可绑）；5..12 是图表专用裸 hex。能绑的绑 UX 变量、库无的按 HTML hex 上色 | `meta-rules §2` 立「真源方向划分」：**图表/数据可视化色板 = 代码 SoT、Figma 不建变量**；其余 = Figma SoT |
| 9 | **预判偏差（好消息）**：以为折线图/TopBar/表格需自建 | discovery 先 search 库，发现库已有 Chart/TopBar/Table/Pill | 自建前先 search **库发布 catalog 全集**，别凭预判、别按「使用中」枚举 |

### 共通根因（元教训）

- **真瓶颈是「命名 / 同步映射」+「锁库纪律」，不是「库缺资产」**。别因「搜不到」就下「库里没有」结论——换功能语义词再搜。
- **档 B = AI 装配 + 人审**：几乎每个问题都靠人审 / binding-audit / 用户实证揪出，非一键生成。
- **治本靠回流规则到设计系统仓库**（团队共享），不只留助手 memory（那只治「我」这一个 AI）。

---

## 五、后续怎么落地 · 推荐工作流（半自动 + 人审）

1. Claude Design 网页端生成效果图 → 2. 导出自包含 HTML（结构/文案/TVU token 名完整）→ 3. AI 用 `use_figma` 按 TVU 库逐 section 装配（真实实例 + 绑 Variables + 文字样式）→ 4. Figma 微调审校 + 跑 binding-audit 兜底。

### 🔑 想更接近「自动匹配」？关键前提 = Code Connect

- **理论上最大杠杆是 Code Connect**（代码 ↔ Figma 的权威组件/属性映射表）——它正是第四节 #1「命名映射」问题的根治：有了它，AI 不必靠语义 search 猜组件，直接查表。
- **但实测受限**：TVU 当前 Figma 是 **Professional plan**，`figma connect publish` 返回 **401**（需升级 Organization / Enterprise），且项目已决定 v1.0 不走 Code Connect、改用自研旁路。
- **当前可用的杠杆**：让 AI 装配时查 figma-sync 已产出的映射表（`components.manifest` / `binding-source-map`），把「猜组件」变「查表」——不需升级 plan。
- **现实预期**：目前没有「提交链接→自动出带库组件的 Figma」的全自动方案；**半自动装配 + 人审是当前最优**。

---

## 六、选型与落地（讨论）

### A · 途径选型（什么场景用哪种）
| 途径 | 何时用 | 关键特性 |
|---|---|---|
| **Claude.ai/Design 生成** | 从 0 出稿 · 只需看效果/评审 | 需求描述直接生成体系化设计 + 可导出 HTML（是下面两条的**上游源**）|
| **html.to.design**（HTML→Figma）| 已有 HTML · 静态单页 · 要快 · 不连库 | 秒级像素快照 · 扁平图层 · **仅导入默认渲染页** · 不连库 |
| **档 B · use_figma**（HTML/描述→Figma）| 已有 HTML/描述 · 需连库/可维护 · 多页 SaaS | AI 语义重建 · 真库实例+绑变量+componentize · **识别 HTML 内多页、一次全画** · 连库 |
| **档 B · use_figma**（原型 / UX 流程）| 复杂 · 多页原型 · UX 交付流程说明 | 一次生成多页 · **自动识别多页（插件只识别单页）** · 连库 |

> ②③ 基于**已有高保真 HTML**；④ 可从描述 / 流程直接画（复杂 / 多页原型、UX 交付流程），无需 HTML；① Claude Design 是产生该源（或直接出稿）的上游。use_figma 读 HTML 源（含多屏）能**识别并一次装配多个页面**；html.to.design 只导入渲染出的默认页。

### B · 版本如何维护
- **设计源（HTML）**：存哪 · 谁维护 · 版本怎么走（建议纳入 repo、按 命名+日期 版本）。
- **库更新联动**：档 B 实例随库自动更新（选中即库组件）；html.to.design 不联动 → 源改需重导 + 重新整理。
- **改动回流**：产品/设计改动 → 改 HTML 源 → 重跑装配；规则类改动 → 回流 TVU DS 仓库（团队共享）。

### C · 待决讨论
- 是否评估 html.to.design 付费版（去水印 · 批量 · 更高保真）？
- 是否升级 Figma plan 启用 **Code Connect**（根治命名映射）？

> ✓ **已定原则（非讨论项）**：库组件一律用——库无对应才建本地组件（componentize）+ 提库扩展候选，绝不 free-form 自画。（档 B 实测缺口：Card/Avatar/chart-color 等即按此处理。）

---

## 附：本次回流到 TVU 设计系统仓库的规则（团队共享）

- `mockup-conventions.md` §M36.1（componentize 三阶段）、§M32.3（锁唯一权威库）
- `design-process.md` §F1.6（componentization 走查维度）
- `CLAUDE_DESIGN_RULES.md` §2.1（图标命名映射论据）、§2.2（导出栅格化/内联）
- `meta-rules.md` §2（真源方向划分：图表色板=代码 SoT）、触发器 B 子规则（回流边界 + 回流即提交）