# 把 TVU 设计系统接入 Claude Design > **面向**：想用 [Claude Design](https://claude.ai/design/)（Anthropic Labs 出的 AI 设计工具）做符合 TVU 规范的设计稿 / 原型的同事。 > **这是 TVU 设计系统的第三条 AI 分发轨道**：① npm 包（开发 import）· ② Claude Code plugin（[`PLUGIN.md`](./PLUGIN.md)，AI workflow）· ③ **本文（Claude Design，prompt→设计稿/原型）**。 > **维护**：本文是 SOP 真源；步骤里引用的命令 / 路径变了就改这里。 --- ## 0. 先理解 Claude Design 怎么"学"你的设计系统 Claude Design 配置团队 design system 的方式是 **onboarding 时分析你给的 source assets → 自动推断出 palette / typography / components / spacing / grid → 你 review → 发布给团队**。 ⚠️ **关键**：它是**推断（inference）**你的系统，**不是检索你上传的显式规则文档**。官方与评测都点了同一个软肋： > "The extracted system is only as good as the source assets you upload." · "still an inference — edge cases, rare variants, and contextual tokens may require manual correction through re-prompting." **对我们的意义**： - 代码里**能看见**的东西（组件结构 / token / 类型）它推断得很好 → 喂 codebase 就够。 - 代码里**看不见**的隐性规则（M23 交付规范、TVU 业务领域规则、"何时用哪个组件 / 不要手搓"、图标 registry 纪律）它推断不出来 → 需要**显式**补，这就是 bundle 的作用。 --- ## 1. 接入步骤（按 Claude Design onboarding 四步） > 下面步骤基于公开资料整理；**带 ⚠️ 的点请在产品 onboarding 界面里实际确认**（产品在 research preview，UI/能力可能与本文写作时不同）。 ### Step 1 — 创建 / 进入团队组织 用公司账号（Pro / Max / Team / Enterprise）进 https://claude.ai/design/ ，建立或进入 TVU 的组织。 （机密项目用 Team / Enterprise plan — 数据不用于训练。） ### Step 2 — 喂 source assets（按优先级） | 优先级 | source | 怎么给 | 说明 | |---|---|---|---| | **P0 主源** | **TVU 设计系统 codebase** | 连 GitHub repo（授权后浏览+导入），或导入本地 clone 文件夹 | Claude Design 最想要的——读 `src/canonical` 组件、tokens、`dist` 类型，生成结构匹配的设计 | | **P0 并列** | **Claude Design 包**（本仓库导出，见 [§2](#2-claude-design-包重造可编译底座)） | 上传整个包目录（`.md` / `.css` / `.json` 都吃，已实测） | 它每轮**从文件重新编译**这套系统——这个策展过、带 `SKILL.md` 规则的目录就是底座 | | **P1** | **TVU Figma 库** | **导出 `.fig` 文件**附进来（不是贴链接） | ⚠️ 实测：Claude Design **不能登录 / 抓任意 Figma URL**；裸链接无效。`.fig` 导出能拆读，但只当补素材/核对，不当主通道——主视觉真源走 codebase + 包 | **codebase 怎么给**（实测确认）： - 内网 Gitea（`product-demo.tvustream.com:3001`）Claude Design **访问不到**（内网地址）。 - 用 **GitHub 镜像**：`https://github.com/NancyZeng0210/TVU-Design-System`（授权后可浏览+导入），或 - **本地 clone 一份文件夹**，用产品的"导入本地文件夹"流程上传。 ### Step 3 — Review 生成的 design system Claude Design 会给出推断的 palette / typography / components / 布局。**重点核**它在隐性规则上的盲区： - 组件取数是否优先用了 TVU 库组件（而不是自画）？ - 颜色 / 间距是否走 token（不是硬编码 hex）？ - 图标是否来自 registry（不是自画 SVG）？ 盲区用 re-prompt 纠（把 bundle 里对应文档段落贴给它）。 ### Step 4 — Publish 给团队 确认无误后翻 **Published** 开关——团队里新项目默认继承这套 TVU design system。 --- ## 2. Claude Design 包（重造可编译底座） ### 生成 / 刷新（一条命令，含 build + 打 zip） > **触发词「更新 Claude Design 文件包」= 跑下面这条**。脚本在 git 里，任何设备 clone 仓库后都可执行（不绑设备）。 ```bash pnpm build && pnpm export:claude-design-bundle ``` - `pnpm build` 先刷新 `dist/`（`styles.css` 编译样式 + 图标 sprite 的源），**保证 token / 图标改动反映进包**——跳过它则这两样滞后于源码。 - `pnpm export:claude-design-bundle` 生成包目录 **+ 自动打 zip**（`~/Documents/AICoding/tvu-design-system-bundle-.zip`，旧的同名 zip 会先清掉）→ **直接拖给 Claude Design**。 - 产物目录 `~/Documents/AICoding/claude-design-bundle/`（repo 外，**不被 Claude Code 规则链路读到**，零交集）。`--out=` 改目录；`--no-zip` 只出目录不打包。 - **数据来源 = 本地工作区当前文件**（直接读磁盘，含未提交改动）；脚本**不** checkout 任何 git 版本。文件名/MANIFEST 里的 `` 只是 `git HEAD` 取来贴的**版本标签**，方便追溯，非数据源。最佳实践：**commit 后再生成**，让标签与内容一致（未提交就生成 → 内容仍是最新，但标签会比内容旧）。 ### 结构（目录树贴合 Claude Design 导入规格） ``` styles.css 编译入口：@import "./tokens/variables.css" tokens/ variables.css 全部 token（dark 默认 + [data-theme="light"]）— 整份，不拆不改名 figma-variables.json Figma 端 Variable 原始定义 assets/icons/sprite.svg 644 个真实图标矢量合并（1:1）— Claude Design 确认可用，见下 reference/ 01 组件目录 · 02 组件语义/props · 03 mockup 交付规范 · 04 设计流程 05 TVU 业务规则 · 07 实现原则 · 08 npm 安装用法 icon-keys-index.md + icon-keys-<类>.md（644 图标 / 18 类，按 canonical 名分类） SKILL.md ★ 先读：隐性规则浓缩（真源 docs/CLAUDE_DESIGN_RULES.md） README.md · MANIFEST.json ``` **与 Claude Design 导入规格的有意偏离**（README 里也写给编译器看）——照规格做会破坏真源，故**不做**： - ❌ token 拆成 colors/typography/spacing + 改名 `--color-*`/`--spacing-*` → 破坏 Figma 同步 + `audit:token-contract` gate，制造第二真源。给整份 `variables.css`，归类不全让编译器自己修。 - ❌ React 组件（`.jsx`/`.d.ts`）→ TVU 是 Vue 库，翻译 = 不可维护的漂移副本。 - ❌ Vue 实现源码也不进包：Claude Design 生成设计稿/HTML 原型、**不复用 TVU Vue 运行时**，要的是组件**设计信息**而非实现代码。组件设计信息已全在包内：`01` 目录 + `02` props/语义 + `08` 安装用法 + **Code 设计** `10` 代码约定/`11` 组件审查/`12` 生成避坑。**codebase 连接是 optional 增强（拿完整 Vue 源码），连不上不影响设计用途**——关键信息不依赖连接。 - ❌ **产品功能设计实例**（各产品 mockup/迭代）不进包：那是「用设计系统做出来的案例」，分散在消费产品 repo + Figma 产品文件，与「可复用规范」分属两层；混进来会让 Claude Design 分不清规则与案例（owner 2026-06-11 拍板范围锁定在设计系统规范）。 - ❌ 预览卡 / dashboard 模板 → 交给 Claude Design 编译时自己生成（owner 拍板不手做）。 - ⚠️ 旧包的 7 散 CSS / `--font-cn` 无 @font-face / 孤立 `--transition-*` 是早期脱节产物，重造版不含（系统字体 stack，无需打包字体）。 **上传上限 + 图标方案（实测 2026-06-11）**：Claude Design 单次上传**最多 500 entries**（含目录）。644 个独立图标 SVG 会撑爆（实测 658 → 报错 `501+ entries`）。 **图标方案 = sprite（Claude Design 2026-06-11 确认采用）**：644 矢量合并成单个 `assets/icons/sprite.svg`（1 entry，1:1，绕开 500 上限）。Claude Design 不解析 sprite 本身，而是**两文件配合**：从 `reference/icon-keys-<类>.md`（图标名 + 描述表格，先查 `icon-keys-index.md`）查名 → 生成 UI 时 `` 渲染真实矢量。 **correctness 关键 — 命名一致**：sprite 的 `` 用 canonical registry 名（如 `navigation/arrow-dropdown`），经 `manifest.nodeId ↔ affordance.figma_node_id` join 生成，**与 icon-keys 列的名、代码 ``、`audit:icon-canonical-names` 严格一致**（导出时校验 644/644 零缺失）。Claude Design 从目录读到的名，sprite 里一定有同名 symbol。 其它两条路（已不采用，留档）：独立 SVG 分批（`--with-icon-svg`，644>500 需分批且受总量限制风险）；markdown only（拿不到真实矢量）。 **格式**：`.md` / `.css` / `.json` Claude Design 都吃（已实测）。整包打 zip 上传，它做最终检测+修正；若已连 codebase，`tokens/` / `reference/08` 偏冗余，核心价值在 `SKILL.md` + `reference/01-05` + `icon-keys-*`。 ### 刷新节奏 仓库规则演化（组件增减 / conventions 改 / 图标变 / token 调）后重跑 `pnpm export:claude-design-bundle`，重新提供。用 `MANIFEST.json` 的 `gitCommit` 核快照新旧（应等于当时仓库 HEAD）。 --- ## 3. 实测已确认（Claude Design 自述，2026-06-11） - ✅ **Figma**：不能登录 / 抓任意 URL，裸链接无效；`.fig` 导出文件能拆读，但只当补素材。 - ✅ **codebase**：GitHub repo（授权后浏览+导入）或本地文件夹，二选一；Gitea 内网不行。 - ✅ **文档格式**：`.md` / 纯文本原生吃，不用转 DOCX。 - ✅ **工作模式**：不是 onboarding 读一次就推断完事，而是**每轮从项目文件重新编译**——所以策展过的带规则目录（本包）是底座，越完整越好。 ### 仍待验证 - **handoff to Claude Code**：Claude Design 设计完能打包 handoff bundle 交给 Claude Code（"探索→原型→生产代码"闭环）——与本仓库 npm 包 + plugin 轨道天然衔接，值得后续打通。 - **SKILL.md §5 通用质量规则**（avoid slop 等）**非 TVU 仓库真源**，是通用补充——按团队偏好确认保留 / 删改。 --- ## 4. 相关 - [`PLUGIN.md`](./PLUGIN.md) — Claude Code plugin 分发轨道 - [`GETTING_STARTED.md`](./GETTING_STARTED.md) — npm 包安装 / import（开发侧） - [`FIGMA_AS_SOURCE_OF_TRUTH.md`](./FIGMA_AS_SOURCE_OF_TRUTH.md) — Figma 真源原则（铁律之一的出处） - [`CLAUDE_DESIGN_RULES.md`](./CLAUDE_DESIGN_RULES.md) — 包内 `SKILL.md` 的真源（隐性规则浓缩） - 导出脚本：[`scripts/export-claude-design-bundle.mjs`](../scripts/export-claude-design-bundle.mjs)