# TVU 设计系统 项目目标

> 本文档是项目的最高指导原则。任何 AI 工具（Claude / Codex 等）在新 session 中接手任务时，**第一份必读文档**。
> 与之配合的还有：[`docs/PROJECT_MAP.md`](./PROJECT_MAP.md)（数据来源 / 组成 / 生成链 / 跨 AI 分工）、[`docs/working-principles.md`](./working-principles.md)（实现原则）、[`src/design-system/translation/`](../src/design-system/translation/)（翻译层 SoT）、[`docs/internal/retrospection/`](./internal/retrospection/)（决策复盘）。

---

## 一句话目标

把 **Figma 已发布的 Library**（组件、Token、图标、Styles）做成 **AI 与开发可消费的双向 Figma↔Code 桥**：

- 开发通过 **Element Plus 风格文档站 + npm install** 即可用（Vue 组件 / TS Token / 图标 registry / 样式）
- AI 拿 **Figma URL** → 定位代码并 1:1 还原
- AI 拿 **代码页面** → 生成 Figma 效果图
- AI 拿 **文字 / 链接 / 截图 / 代码任一组合** → 生成符合本规范的：
  - **UX 效果图**（Figma 设计稿 / 截图）
  - **可运行代码网页**（Vue 组件 + 部署）
- 每个 Code 组件可追溯到 **Figma 来源**（哪个组件 / 哪个属性）

---

## 各能力的前置约束（写 T3 / T4 prompt 时必读）

下面这些约束是为了让"双向 + 多模态消费"能力**不在后期返工**——而不是要现在实现。T3 / T4 prompt 设计时必须前置考虑。

### T3 — EP 分类 + Figma origin 元数据

- metadata schema 必须支持**双向查询**：
  - (a) Figma node ID → code 路径（已规划）
  - (b) **code 路径 → Figma node ID**（反向）
- 多 code 实体共享 Figma origin 时（如 SelectBoxLine + SelectBoxFilled 共享 `Select.feature=date`）必须支持 **N:1 映射**

### T4a — Code Connect `.figma.ts`

- 不只声明 props 映射，要预留 `reverseGenerationHints`（或类似字段）——后期反向生成器（Code → Figma）读这个字段重建 Figma node 结构
- 所有映射查 `axis-implementation-map.json` 真源（meta-rules 反模式 #1：不在 `.figma.ts` 自创映射）

### T4b — AI manifest

manifest 顶层必须含：

- `directions: ['figma-to-code', 'code-to-figma']` — 明示支持的方向
- `compositionSupport` — 不只描述单组件，还含组件组合规则（如 FormItem 包 Input、Table 包 Pagination）+ 布局/间距规范，让 AI 能合成 **页面级** 输出（不只单组件）
- 各方向所需的额外锚点（如 code-to-figma 需要 baseline 截图引用、page-level 合成需要布局 token）

### T5 — 视觉回归 baseline

baseline 截图除了用于回归检测，还作为：

- code-to-figma 反向生成的视觉锚点（生成后跟 baseline diff 验证）
- 多模态合成（截图输入）的训练 / 校验语料

---

## 受众与他们的关注点

| 角色 | 优先级 | 关注点 |
|---|---|---|
| **开发** | P0 主要使用者 | npm 安装、import 用法、props/events/slots、可复制代码示例、TypeScript 类型 |
| **设计** | P1 查看者 | 与 Figma 对应关系、变体网格、设计 spec、版本变更 |
| **产品** | P1 查看者 | 业务场景示例、组件能做什么、什么时候用哪个 |
| **QA** | P1 查看者 | 状态矩阵（hover/disabled/error/empty 等）、可交互测试、边界条件 |

---

## 关键产出物

1. **Code 库**
   - Vue 组件（`src/components/`）
   - 设计 token（`tokens/`）
   - 图标 registry（`src/icons/` + `icons/index.ts`）
   - Styles（CSS 变量 + 主题）

2. **npm 包发布机制**
   - `package.json` 配置（entry、exports、types）
   - 版本管理（semver）
   - changelog 规范
   - 公司其他项目 `npm install @nancyzeng0210/tvu-design-system` 即可使用

3. **文档站（Element Plus 风格）**
   - 参考站：https://element-plus.org/en-US/component/overview
   - 必有结构：标题 + intro / 多段示例（preview + show source）/ API 表（Attributes / Slots / Events / Exposes）/ 右侧 TOC
   - **多角色补充**（不止开发视角）：
     - "Design Spec" tab / 段落：Figma 变体网格 + 设计稿对照
     - "Status Matrix" tab / 段落：QA 视角的状态测试
     - "Use Cases" 段落：产品视角的业务示例

4. **长期维护机制**
   - **边界翻译层**（`src/design-system/translation/`）：显式管理 Figma↔Code 的命名/结构差异
   - **Code Connect**（`*.figma.ts`）：把 Figma 节点和代码组件锁死，防止未来 drift
   - **视觉层确定性脚本**（`scripts/visual-audit.ts`）：不依赖 AI 的对 diff，CI 可跑

---

## 不要做

- ❌ **不修改 Figma**——Figma 是设计师的真源，代码出现差异时由翻译层登记
- ❌ **不让 AI 自由发挥**——Codex / Claude 必须读翻译层 + working-principles，不准按"行业惯例"补全
- ❌ **不让单组件深修阻塞交付**——破坏性 API 改造（如 Button canonical 迁移）放 post-launch 迭代
- ❌ **不混合多语义到一个 prop**——发现同名异义（如 Badge.type = 颜色 vs Figma Type = 形状）必须拆

---

## 当前进度

详见：[`docs/internal/retrospection/2026-04-28-design-system-audit.md`](./internal/retrospection/2026-04-28-design-system-audit.md)

阶段路线（截至 2026-05-13；详细排期在 [`internal/retrospection/design-spec-canonical-alignment-tracker.md`](./internal/retrospection/design-spec-canonical-alignment-tracker.md)）：

```
✅ 0-3：架构层（边界翻译层 / working-principles / 翻译层登记）
✅ 4-5：模式聚类（134 项→10 项决策）+ B1-B10 决策
✅ 6.1：翻译层批量登记
✅ 6.2：Token 替换（38 hex → token + 10 新 token）
✅ 6.5：微结构修复（合并进 CANONICAL 系列）
✅ npm 包化（v0.1.0 ~ v0.1.3 已 publish）
✅ Phase 7：Element Plus 风格文档站（19 toggle-aware pages）
✅ v0.1.x：上线公司其他项目可装（v0.1.3 verified on Packages 页）

[当前位置 ↓ — 按 0.x semver 重新分组，破坏性走 0.x.0 minor，不跳 1.0]
🟡 v0.2.0：Chart + audit:published-vs-code 升 strict（✅ ready to publish）
🟢 v0.3.0：Tier 1-A translation schema 化 + Phase 6.3 + 6.4 + BRIDGE-005
🟢 v0.4.0：Phase 6.6 双形态 API + 6.7 Badge prop 拆分
🟢 v0.5.0：Phase 6.8 Button 迁移 + Tier 1-B mockup audit（并行）
🟢 v0.6.0：Tier 1-C ESLint plugin + EXTRACT-006 + CANONICAL-007
🔵 v1.0.0：稳定承诺 — 5 能力全交付 + a11y + API 锁定 + 迁移指南
```

> **排期原则**（不可违背）：项目目标对齐 > 依赖解锁 > 自动化标准化 > 短 cycle 顺路；**不按耗时 / 复杂度 / 成本最低排**。详见 tracker.md §排期原则。

---

## AI 协作规范（Codex / Claude / 其他）

### 必读入口（按优先级）
1. **本文档**（PROJECT_GOAL.md）—— 知道在做什么
2. [`docs/PROJECT_MAP.md`](./PROJECT_MAP.md) —— 知道数据来源、项目组成、生成链和跨 AI 分工
3. [`docs/working-principles.md`](./working-principles.md) —— 知道怎么做
4. [`src/design-system/translation/`](../src/design-system/translation/) —— 知道已有决策
5. [`docs/internal/retrospection/`](./internal/retrospection/) —— 知道怎么走到这里的

### Prompt 模板（验证有效）
位置：[`docs/internal/_prompts/`](./internal/_prompts/)
- 所有 Codex prompt 都以文件形式版本化
- 用户通过 `请读取并执行 docs/internal/_prompts/<name>.prompt.md 中的指令` 触发
- 绕过 VS Code Codex 扩展的剪贴板编码 bug

### Gate 机制（防 AI 漂移）
- 每个 prompt 末尾必带 "完成后 STOP，等我决定下一步"
- 关键参数（如 variant 枚举值、token 值）必须先返回给用户确认
- 双向 diff（code 侧 + Figma 侧）后只审 ⚠️ 行
- 视觉层硬错误（hex / 未定义 token）走脚本，不走 AI

---

## Quick Reference

| 我想知道 | 看哪里 |
|---|---|
| 项目目标 | 本文档 |
| 数据来源 / 项目组成 / 生成链 / 清理规则 | [`docs/PROJECT_MAP.md`](./PROJECT_MAP.md) |
| 实现原则 | [`docs/working-principles.md`](./working-principles.md) |
| 当前进度 | [`docs/internal/retrospection/`](./internal/retrospection/)（最新日期） |
| 已做的决策 | [`src/design-system/translation/`](../src/design-system/translation/) + working-principles 末尾"决策 Log" |
| 下一步要跑的 prompt | [`docs/internal/_prompts/`](./internal/_prompts/) |
| API diff 状态 | [`docs/internal/api-diff.md`](./internal/api-diff.md) + [`api-diff-patterns.md`](./internal/api-diff-patterns.md) |
| 资产清单 | [`docs/internal/asset-inventory.md`](./internal/asset-inventory.md) |
| 组件级映射扫描 | [`docs/internal/component-mapping-scan.md`](./internal/component-mapping-scan.md) |
| 待补运行时能力 | [`docs/internal/runtime-additions.md`](./internal/runtime-additions.md) |