# 让 Claude Design 预览能用上更多组件 — 设计

> **日期**：2026-06-24
> **状态**：设计已批准，待写实现 plan
> **范围**：仅「轨一 = 预览级」。轨二（生产级可交付 React）明确 out of scope（见 §7）。

---

## 1. 问题

Claude Design 平台（claude.ai/design）当前从 TVU 上传的 bundle 里只能在预览中生成/使用 **4 个组件**：Badge / Button / Icon / TopBar。Notification / Tooltip / Message / Table / Select 等复杂组件用不了，用户在平台里做 mockup 时只能临时手搓。

owner 希望让平台能用上更多组件。

---

## 2. 机制前提

Claude Design **不消费任何组件实现代码**，机制是「读设计信息 → 自己推断生成」，每轮从项目文件重新编译（证据：[`docs/CLAUDE_DESIGN_SETUP.md:94`](../../CLAUDE_DESIGN_SETUP.md) + `:120`）。

由此推论（决定 §5「不塞代码」与 §7「范围外」）：在 bundle 里塞 React/Vue 实现、Figma 导 .jsx、Vue 转 React —— 平台都不会用，且产出是脱离 token 真源的静态/影子副本。唯一能影响平台输出的杠杆 = 喂给它更完整的**设计信息**。

---

## 3. 唯一真正的杠杆

平台只吃「设计信息」。它现在只生成 4 个简单组件，**假设**是：现有 bundle 给复杂组件的信息是「何时用 / 别用 / props 语义」（给 mockup 操作 + Vue import 看的），**缺一份「生成友好」的视觉规格**——组件长什么样、各部位绑什么 token、各 variant 差在哪。

补上这份规格 → 平台推断能覆盖复杂组件、生成得更准。

⚠️ 这是**假设**。平台是黑盒，补信息不保证它就能生成。所以方案是**先小规模验证假设**，不是直接全量实现。

---

## 4. 规格的来源与形态（零漂移）

- **不手写视觉值。** 从已有 Figma 提取数据**脚本派生**：
  - [`figma-data/normalized/components-tokenized/<组件>.json`](../../../figma-data/normalized/components-tokenized/) — 已 token 化（`--bg-layer4` / `--text-body` / `--brand`…），含 `fills` + `layoutMode` + 逐节点结构（Notification 那份 182KB）。
  - [`figma-data/normalized/docs-figma-members/<组件>.ts`](../../../figma-data/normalized/docs-figma-members/) — axes + variant 矩阵（Notification = `theme×form×type` = 48 variant）。
- **形态** = 给生成器读的「组件解剖」markdown：DOM 层级结构 + 每部位绑的 token + 各 variant 差异 + 状态说明。
- 源自 Figma 提取数据 → Figma 改了，重跑 `sync:figma-library --with-extract` + `export` 自动更新，**永不漂移**，不碰 token 真源。这正是它优于「Figma 导 jsx / Vue 转 React」之处。

---

## 5. 工程改动（最小）

- 在 [`scripts/export-claude-design-bundle.mjs`](../../../scripts/export-claude-design-bundle.mjs) 新增派生步骤，生成 `reference/components-spec/<组件>.md`。
- **验证期只为 Notification + Tooltip 两个生成**（两者 tokenized JSON + members 数据均齐备）。
- 不动现有 13 个 reference 文档、不动 token / sprite 逻辑。

---

## 6. ROI 验证协议（对齐 BRIDGE-MOCKUP-007「扩量前真文件验证」纪律）

⚠️ **现实约束**：验证核心步骤在 Claude Design 平台上，AI 无法直接操作该平台。**协作式验证**：

| 步骤 | 谁做 |
|---|---|
| 派生 2 个组件规格 → 重新 `pnpm build && pnpm export:claude-design-bundle` | AI |
| 上传 bundle 到 Claude Design | owner |
| 在 Claude Design 里让它生成/用 Notification + Tooltip，截图反馈 | owner |
| 对照真实组件打分、判通过与否 | 一起 |

- **时间盒**：0.5–1 小时。
- **成功标准（预览级，不要求 1:1）**：
  1. 平台不再跳过、能生成出来；
  2. 布局结构对（标题 / 描述 / 按钮 / 图标的相对位置）；
  3. 颜色 / 字号来自 TVU token 而非瞎编；
  4. 关键 variant 能区分（至少 `type` 的色差 + `form` 的形态差）。
- **不要求**：交互、全 48 variant、a11y。

### 决策门

- **通过** → 扩量：派生步骤开给其余约 28 个非图标组件（`components-tokenized` 全集去 `icon_*`），一次性纳入 bundle。
- **不通过**（补信息后平台仍生成不出 / 质量不可用）→ 降级保底（**本次不做，留作 fallback**）：为复杂组件提供静态 HTML/CSS snippet（用 token，1:1 视觉），让平台直接嵌而非靠它生成。

---

## 7. 范围外（明确不做）

- **轨二：生产级可交付 React**。正路不经过 Claude Design：Vue 消费端已有 npm 包；若真有 React 消费端，则在 npm 包正式增加 React 构建产物（单一真源派生 + 测试守护）= 把 TVU 升级为多框架库，独立立项，且需先确定真有 React 消费项目。当前消费端框架未定 → YAGNI。
- 不在 bundle 里塞组件实现代码（平台机制不消费）。
- 不碰 token 拆分 / 改名。

---

## 8. 未决 / 验证期决定

- 派生规格 markdown 的**具体字段格式**（DOM 解剖怎么表达最「生成友好」）—— 在写 plan / 实现时定，验证结果可能反过来调整格式。
- 成功标准第 2-4 条的**量化阈值** —— 验证时和 owner 一起按截图判定，不预设死线。