# TVU Design System 项目地图

> 给 Claude / Codex / Cursor / Cline / Copilot 等任何 AI 工具接手用。  
> 本文件只描述项目事实与协作边界；具体阶段决策以 `docs/working-principles.md`、`src/design-system/translation/` 和最新 retrospection 为准。

---

## 1. 项目目标

把 **TVU Figma 已发布 Library** 做成 **AI 与开发可消费的双向 Figma↔Code 桥**——开发通过 Element Plus 风格文档站 + npm install 即可用；AI 通过 Figma URL / 代码页面 / 多模态输入完成 Figma ↔ Code 双向生成。

详细目标 + 前置约束（T3 / T4 schema 设计要点）：[`docs/PROJECT_GOAL.md`](./PROJECT_GOAL.md)

核心结果：

- 公司项目可以 `npm install @nancyzeng0210/tvu-design-system` 使用组件、tokens、图标和样式
- AI 拿 Figma URL → 定位代码 1:1 还原；拿代码页面 → 生成 Figma 效果图
- AI 拿文字 / 链接 / 截图 / 代码任一组合 → 生成符合规范的 UX 效果图或可运行代码网页
- Code 与 Figma 的差异必须可解释、可登记、可审计（详见 `src/design-system/translation/` 真源）
- 任何 AI 工具不能凭"行业惯例"补规范；所有偏离都要进入翻译层或文档

---

## 2. 数据来源

| 来源 | 路径 / 入口 | 作用 | 是否真源 |
|---|---|---|---|
| Figma 已发布 Library | 通过 `FIGMA_TOKEN` + `figma-sync/extract.mjs` 拉取 | 组件、变量、图标、styles 的设计真源 | 是，设计侧真源 |
| Raw Figma JSON | `figma-data/raw/` | Figma API 原始快照，便于离线生成与审计 | 是，代码生成输入 |
| Normalized Figma 数据 | `figma-data/normalized/` | tokenized component、manifest、candidate、wrapper skeleton 等中间层 | 是，生成链输入 |
| Published icons | `figma-data/published/icons/` | 图标分发源，生成 registry / ESM / SVG dist | 是，图标资产输入 |
| Translation layer | `src/design-system/translation/` | Figma ↔ Code 命名、结构、语义差异登记 | 是，差异真源 |
| Working principles | `docs/working-principles.md` | 判断 API / token / 审计边界的规则 | 是，规则真源 |
| Retrospection | `docs/internal/retrospection/` | 阶段复盘、历史决策和路线变化 | 是，过程真源 |

注意：**不修改 Figma**。Figma 是设计师真源，代码只能读取、映射、生成、登记差异。

---

## 3. 项目组成

| 模块 | 路径 | 内容 |
|---|---|---|
| 组件源码 | `src/components/`、`src/canonical/` | Vue 组件、canonical wrapper、兼容 bridge |
| 设计 tokens | `src/tokens/variables.css` | CSS variables，颜色不能硬编码 |
| 图标系统 | `src/icons/` | icon registry、manifest、category loaders、generated icons |
| 翻译层 | `src/design-system/translation/` | prop alias、icon alias、token alias、accepted divergence |
| 生成脚本 | `figma-sync/` | extract / normalize / generate / audit / icon dist build |
| Figma 数据 | `figma-data/` | raw、normalized、published icon 数据 |
| 文档站 | `playground/docs/` | Element Plus 风格 docs shell、导航、组件页面 |
| playground | `playground/`、`canonical.html` | 本地预览与 canonical/legacy catalog |
| 测试 | `tests/` | Vitest 单测与构建验证 |
| 内部文档 | `docs/internal/` | prompt、audit、mapping plan、运行时补全清单 |

---

## 4. 生成与审计链路

常用脚本在 `package.json`：

```text
pnpm sync:extract                  # 从 Figma 拉 raw 数据，需要 .env / FIGMA_TOKEN
pnpm generate                      # sync.mjs 编排生成链
pnpm generate:component-tokens      # 生成 tokenized component layer
pnpm generate:manifest              # 生成 canonical manifest
pnpm generate:tokens                # 生成 CSS variables
pnpm generate:icons-catalog         # 生成图标 catalog / category files
pnpm audit:design-system            # 查 undefined token / hardcoded color / SVG 注入
pnpm audit:component-tokens          # 查组件 token linkage
pnpm audit:tokenized-diff            # 查 tokenized diff
pnpm audit:docs-site                 # 查文档站 pixel-parity 声明是否诚实
pnpm audit:figma-conformance         # 查 Figma-first 约束
pnpm test                           # Vitest
pnpm build                          # 类型检查 + Vite library build + icon dist
```

数据流：

```text
Figma Library
  → figma-data/raw/
  → figma-data/normalized/
  → src/tokens/ + src/icons/ + src/canonical/ + src/components/
  → playground/docs/ + dist/
  → audit/test/build
```

---

## 5. 核心规则

1. **Figma 不写入**：任何 Figma 写操作都是 bug。
2. **颜色硬编码是 bug**：组件 CSS 必须使用 token；缺 token 先登记/新增，不直接写 hex。
3. **差异先登记**：Figma 与 Code 不一致必须进入 `src/design-system/translation/`。
4. **设计态不映射运行时**：hover、click、enable、dark theme preview 等设计预览属性默认不成为 prop，除非已登记为运行时能力。
5. **Vue 生态命名优先**：例如 `disabled`、`closable`、`modelValue`，但必须在 alias 文档登记。
6. **视觉层靠脚本**：颜色、尺寸、token linkage 用 audit 脚本；AI 只审脚本无法判定的问题。
7. **Prompt 必须版本化**：Codex 执行型任务写入 `docs/internal/_prompts/`，末尾必须 STOP 等用户审。

---

## 6. 跨 AI 协作分工

### 标准协作闭环

1. Claude 读项目规则 + audit。
2. Claude 生成 `docs/internal/_prompts/phase-x.prompt.md`。
3. 用户把 prompt 交给 Codex。
4. Codex 只按 prompt 改代码 / 产出文件。
5. Codex STOP，列出改动和未验证项。
6. Claude 复审 Codex diff。
7. 用户决定是否进入下一阶段。

这个闭环优先级高于单个 AI 的默认行为。任何 AI 如果想跳过 STOP、跨阶段执行、或把未登记决策直接写进代码，都视为流程违例。

### Claude 优先做约束与 prompt

- 读取项目文档、translation、audit 结果，判断下一阶段边界。
- 把任务拆成可执行、可验证、带 Gate 的文件型 prompt。
- 写入 `docs/internal/_prompts/<phase>.prompt.md`。
- 对 Codex 产物做复审，确认是否符合规则。
- 默认不直接修改代码、脚本、tokens、JSON 数据或组件文件；这类改动应生成 Codex prompt 后交给 Codex 执行。
- 只有用户明确授权修改具体文件时，Claude 才能直接改对应文件，并且完成后 STOP。
- Claude 可以直接修改协作规则文档、prompt 文件、审计报告和复盘文档，但不能顺手进入代码实现阶段。

### Codex 优先做代码执行

- 只执行 prompt 中定义的范围，不自行扩阶段。
- 修改源码、tokens、测试、文档站页面等代码工件。
- 跑局部验证；需要全量验证时由主 session 统一确认。
- 完成后 STOP，并列出改动、未验证项、风险。

### 其他 AI 工具

- 先读 `AGENTS.md` → `docs/PROJECT_GOAL.md` → 本文件 → `docs/working-principles.md` → `src/design-system/translation/`。
- 不读 Claude 私有 memory 当真源；项目契约只能在仓库内。
- 不能改写决策真源，除非用户明确要求并同步文档。

---

## 7. 当前阶段（2026-04-28）

已完成：

- 0-3：架构层、边界翻译层、工作原则。
- 4-5：模式聚类与 10 项 B 类决策。
- 6.1：翻译层批量登记。

当前优先级：

1. 6.2：视觉层 token 替换。
2. 6.3：删除自创内容（如 Notification.success / type）。
3. 6.4：新增运行时能力（showCount / multiple / editable）。
4. 6.5：微结构修复。
5. npm 包化与发布说明。
6. Phase 7：Element Plus 风格文档站。

延后到 post-launch：

- 6.6：FormItem.label / Tooltip.content 双形态 API。
- 6.7：Badge prop 拆分。
- 6.8：Button canonical 完成迁移。
- Phase 8：Code Connect + 视觉层确定性脚本。

---

## 8. 清理规则

可删除 / 不应提交：

- `node_modules/`
- `dist/`
- `.DS_Store`
- `.env`
- Vite / Vitest cache

需要谨慎，不能直接删：

- `figma-data/raw/`、`figma-data/normalized/`：生成链输入，不是缓存。
- `figma-data/published/icons/`：图标分发输入。
- `_draft/`：当前仍被 retrospection 引用，删除前要确认是否已迁移到正式 audit 文档。
- `canonical.html`：当前 playground/docs 仍引用。

过时内容处理原则：

- 平台私有计划（如 `.claude/component-plan.md`）不得作为真源；应改为指向 `AGENTS.md` 和本项目地图。
- 旧审计文档如果保留，必须标明阶段和日期，避免新 AI 当成当前事实。