# 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 组件 / 设计 token / 图标 registry / 样式）
- AI 拿 **Figma URL** → 定位代码并 1:1 还原
- AI 拿 **代码页面** → 生成 / 还原 Figma 效果图
  > 现状（能力 3 code→Figma，按边界如实分层）：**DS 生成的代码 _可_ 还原回 Figma**——经 `figma-data/render-verification-manifest.json`（930 条 Figma nodeId ↔ code 组件 ↔ props 确定性映射）+ canonical `data-figma-*` 溯源属性，回指**有且只有一个**设计库真源（`figmaFileKey = YbsPRUVmNdsbN40NNwh1Gn`，全 manifest distinct fileKey 实测唯一）。**真正缺的不是"还原能力"，而是自动 publish 链路的三块**：① Code Connect `.figma.ts` publish（Figma Professional plan，任何 Code Connect API 调用 401，需 Org/Ent seat；已实证）② 非 DS 代码（库外自绘组件）的反查 ③ Figma MCP 本地未配置。所以标 **DEFERRED（bypass equivalent）** 指的是"全自动 code→Figma publish"，**不是**"code→Figma 不可为"。详见 `docs/CAPABILITY_3_BYPASS.md` + STATUS §Deferred。
- AI 拿 **文字 / 链接 / 截图 / 代码任一组合** → 生成符合本规范的：
  - **UX 效果图**（Figma 设计稿 / 截图）
  - **可运行代码网页**（Vue 组件 + 部署）
  > 现状：能力 4 当前实现为**合规守门（gate）+ AI 辅助合成**，非全自动生成器。
- 每个 Code 组件可追溯到 **Figma 来源**（哪个组件 / 哪个属性）

---

## 操作模型（谁用 / 怎么把关 / 质量如何保证）

> 本节是项目北极星，后续任何流程优化都须遵守。目标架构（自触发脊梁 + 四支柱 + 元层）与差距登记见 `docs/internal/full-lifecycle-assessment-2026-07-08.md`（backlog INFRA-F55），演进中、不冻结进本文件。

- **性质**：企业级设计系统，供多人使用。
- **角色**：一个 owner 把关质量；设计同事拉分支维护 + 使用；dev / PM 直接用现成系统做产品设计。
- **工具面（目标 / 现状分列）**：**目标** = Claude Code / Codex / 其它 AI / claude.ai·Design 类工具都要能产出高质量产品设计；**当前** = 仅 Claude Code（hooks + skills 全套）就位，Codex 半套、claude.ai/其它工具适配未齐——补齐是 backlog INFRA-F55 支柱③ 工作（现状诊断见 assessment §2 工具耦合）。
- **三条核心要求（目标，建设中）**：① **质量与"用哪个工具"解耦**（不绑单一工具）② 使用者**不必懂流程**，系统**自行触发**对应流程 ③ 团队成员**一看就知道如何使用**。
- **质量把关模型**：**非 owner 贡献者的改动走 PR，由 owner review**（目标：自动化 gate 做重活、人只点 merge）；**owner 本人改动直推 master**（fast-lane，见 `AGENTS.md` 硬规则 #7）。**gate 平权原则**：凡拦贡献者 PR 的 gate 同样挂 `push:master`，owner 直推路径不少过任何一关（见 backlog INFRA-F56）。
- **派生最高目标**：任何人 × 任何工具 → 被系统自动导进正确流程、产出高质量产品设计（code + mockup）。

## Token 架构（Figma 变量 = 原子级真源）

- **Figma Variable = 原子真源，sync-bound + gated**：54 个 Figma 变量含**两层**——原始色板（`--color-grey-*` / `--brand` / `--red` / …）+ **语义颜色层**（Figma `Color Type/*` → `--text-*` / `--icon-*` / `--bg-*` / `--line-*`）。全部由 `pnpm generate` 按名同步、`audit:token-contract` L5 gate 卡；**不可手改代码值，改设计改 Figma**。语义颜色 token 不是摆设，是原子依据。
- **非颜色 token = 当前值对齐、非变量绑定（保真缺口）**：间距 `--sp-*`、控件尺寸、Effect / Text Style、组件变体 token 不在 Figma Variable 里（Effect / Text 在 Figma 是 Style，间距代码手写），靠人工对齐值、无 gate。是否变量化见 backlog INFRA-F57。
- **分发形态**：当前仅 CSS 变量（`dist/style.css`）；**TS / JSON token 出口待补**（支柱① 契约工作，让非 web 工具也能消费）。

---

## 各能力的前置约束（写 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 能合成 **页面级** 输出（不只单组件）。（前瞻约束、非现状：组合契约当前仅内部 `component-affordances.json`、不随包发；随包发是支柱① 工作）
- 各方向所需的额外锚点（如 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/`）——当前 CSS 变量经 `./style.css` 分发；**TS/JSON token 出口待补**（见「Token 架构」节 + backlog 支柱① 契约工作）
   - 图标 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 视角的状态测试
       > **scope 显式化（2026-06-10 system-review P2-08）**：Status Matrix 当前只建模 **Figma 导出的变体状态**（设计真源有的轴）；**runtime 态（empty / loading / error / 0 数据 / 超长文本）不在矩阵建模范围**——数据类组件（Table / Select）的 runtime 态 demo 是已知缺口，按需求触发补，不随组件页自动复制（StatusMatrix.vue 头注释同此声明；mockup 侧超长文本由 M43 管）。三视图覆盖与 pending 债务由 `audit:docs-site` + `site-review-manifest.json` views 字段跟踪
     - "Use Cases" 段落：产品视角的业务示例
     > 现状：当前落地 = 开发 + QA 双视图；**产品 Use Cases（0/34）/ 设计 Spec 视图（1/34）为已知缺口**，按需补（进度见 `audit:docs-site` + `site-review-manifest.json` views 字段，不在此写版本 roadmap）。

4. **长期维护机制**
   - **边界翻译层**（`src/design-system/translation/`）：显式管理 Figma↔Code 的命名/结构差异
   - **Figma↔Code 锁定（防 drift）**：`figma connect publish`（Code Connect `*.figma.ts`）当前**不可达**（Figma Professional plan，任何 Code Connect API 调用返回 401，需 Org/Ent Developer seat；已实证）。**当前实际采用的等价同步机制**：硬规则 #6（AI 从 Figma URL 生成必用 `src/canonical/*` 作 SoT）+ 边界翻译层（`src/design-system/translation/`）+ `pnpm sync:figma-library` 14-step audit pipeline + `figma-data/render-verification-manifest.json`（930 entries，Figma nodeId ↔ code 组件 ↔ props 的确定性数值验证）。Code Connect 待 Figma plan 升级后纳入。
   - **视觉层确定性脚本**（`scripts/visual-audit.ts`）：不依赖 AI 的对 diff，CI 可跑

---

## 不要做

- ❌ **不修改 Figma**——Figma 是设计师的真源，代码出现差异时由翻译层登记
- ❌ **不让 AI 自由发挥**——Codex / Claude 必须读翻译层 + working-principles，不准按"行业惯例"补全
- ❌ **不让单组件深修阻塞 release 节奏**——但这 ≠「永不深修」。**Code 是否 1:1 还原 Figma 的保真度修正，是 post-launch 迭代的持续主线**：非破坏性修正（颜色 / 间距 / a11y / composition 复用）由 [`figma-vs-code-fidelity-audit-2026-05-29.md`](./internal/_reports/figma-vs-code-fidelity-audit-2026-05-29.md) 驱动、**按 tier 排期（版本归属见 [`STATUS.md`](./STATUS.md) + tracker）**；破坏性 API 改造（如**已完成**的 Button canonical 迁移）走 0.x.0 minor。要点：fidelity 修正不阻塞交付节奏，也不被无限期搁置——**是持续进行的主线，不因某版本收尾而停**
- ❌ **不混合多语义到一个 prop**——发现同名异义（如 Badge.type = 颜色 vs Figma Type = 形状）必须拆

---

## 当前进度

> ⚠️ **逐版本进度真源 = [`docs/STATUS.md`](./STATUS.md)**（当前版本 + 版本线分组 + Active 余量）**+ [`design-spec-canonical-alignment-tracker.md`](./internal/retrospection/design-spec-canonical-alignment-tracker.md)**（排期 SoT + 逐版本 retrospect）。本文件不再镜像版本路线——此处曾冻结在 v0.6.0 规划态多个版本（2026-06-10 system-review P2-07 de-mirror，同 AGENTS.md "当前阶段定位" 段范式）。<!-- de-mirror-ok: de-mirror 注解自身引用旧版本解释缘起 -->
>
> 已完成的架构里程碑（稳定史实，不随版本滚动）：0-3 架构层（边界翻译层 / working-principles / 翻译层登记）→ 4-5 模式聚类 + B1-B10 决策 → 6.x 翻译层批量登记 + token 替换 → npm 包化 + Element Plus 风格文档站 → 0.x 逐版本 release（v0.2.0 起见 tracker §Release 排期）。<!-- de-mirror-ok: 稳定史实里程碑，非 roadmap 镜像 -->

> **排期原则**（不可违背）：项目目标对齐 > 依赖解锁 > 自动化标准化 > 短 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) |