# TVU Design System — Status

> **Last updated**: 2026-05-19 (v0.6.1 published — consumer reference adoption 3b 解锁；META-001 同 session 发现+修+ship；MicroApps vue-app 装 v0.6.1 全闭环 verified)
> **本文档是项目状态 SoT**。任何 AI 工具新 session 起手第一份必读（早于 PROJECT_GOAL.md，因为这里直接告诉你"在哪"）。
> 任何 session wrap up 时**必须更新本文档**（见末尾"Wrap-up 协议"）。
>
> ⚠️ **排期 SoT 在 [`retrospection/design-spec-canonical-alignment-tracker.md`](./internal/retrospection/design-spec-canonical-alignment-tracker.md)**——本文件 Version Roadmap 段只是镜像。任何 "v0.X 包含哪些 / 先做哪个" 决策前先读 tracker 的 "排期原则" 自检清单。

---

## 一句话目标

把 Figma 已发布 Library 做成 **AI 与开发可消费的双向 Figma↔Code 桥**（详见 [`PROJECT_GOAL.md`](./PROJECT_GOAL.md)）。

---

## 当前版本：v0.6.1（✅ published & verified）

| 项 | 值 |
|---|---|
| 已 publish | ✅ 2026-05-19 → GitHub Packages [`@nancyzeng0210/tvu-design-system@0.6.1`](https://github.com/users/NancyZeng0210/packages/npm/package/tvu-design-system) (CI run [26079553331](https://github.com/NancyZeng0210/TVU-Design-System/actions/runs/26079553331) green 一次过；Packages API verified — `0.6.1` created 2026-05-19T06:09:27Z) |
| 包名 | `@nancyzeng0210/tvu-design-system@0.6.1` |
| 上一版本 | v0.6.0 → GitHub Packages [`0.6.0`](https://github.com/users/NancyZeng0210/packages/npm/package/tvu-design-system) (2026-05-18T10:35:01Z) |
| 安装 | `pnpm add @nancyzeng0210/tvu-design-system`（需 `@nancyzeng0210` scope npmrc 配置，详见 [`GETTING_STARTED.md`](../GETTING_STARTED.md)） |
| Release 流程 | changesets + tag-triggered CI + audit gate（**13 strict**）+ Node 20/22 matrix pre-flight |
| 主要内容 (patch) | **META-001 fix**: ESLint plugin `no-inline-svg` 加 Vue SFC `<template>` `<svg>` 探测（CLI R1 对齐）· **files[] expansion**: npm tarball 含 `scripts/` `templates/` consumer-facing docs（v0.6.0 漏） |
| 破坏性 | 无 |
| 版本详情 | [`CHANGELOG.md`](../CHANGELOG.md) |
| 解锁 | v1.0.0-rc.1 — consumer 可重跑 reference adoption (3b) 验证（这次 ESLint 应跟 CLI 对齐） |
| Release 实证 | CI 一次过；v0.6.1 也是 master HEAD F34 Node 20/22 matrix 保护下的连续 3 个 release 一次过（v0.6.0 / v0.6.1） |

---

## Version Roadmap（剩余按版本线分组）

### 已 shipped — 详情见 retrospect 复盘文件

| 版本 | shipped | retrospect |
|---|---|---|
| v0.2.0 | 2026-05-13 | [`2026-05-13-v020-release-and-infra-f30.md`](./internal/retrospection/2026-05-13-v020-release-and-infra-f30.md) |
| v0.3.0 | 2026-05-14 | [`2026-05-14-v030-release.md`](./internal/retrospection/2026-05-14-v030-release.md) |
| v0.4.0 | 2026-05-14 | [`2026-05-14-v040-release.md`](./internal/retrospection/2026-05-14-v040-release.md) |
| v0.5.0 | 2026-05-18 | [`2026-05-18-v050-release.md`](./internal/retrospection/2026-05-18-v050-release.md) |
| v0.6.0 | 2026-05-18 | [`2026-05-18-v060-release.md`](./internal/retrospection/2026-05-18-v060-release.md) |
| v0.6.1 | 2026-05-19 | [`2026-05-19-consumer-verification-microapps.md`](./internal/retrospection/2026-05-19-consumer-verification-microapps.md) (META-001 + files[] fix) |

历史 sprint 完成项详见 [`design-spec-canonical-alignment-tracker.md`](./internal/retrospection/design-spec-canonical-alignment-tracker.md) §轨道 A 已完成。

### 🟢 v0.7.0 contrast cleanup + RC prep（current sprint）

| 项 | 状态 | 备注 |
|---|---|---|
| color-contrast 1998 nodes cleanup | 🟡 **设计师 review 中** | 报告 [`a11y-contrast-report.md`](./internal/a11y-contrast-report.md)；改 Figma token → sync 回 code |
| non-text contrast 20 pairs cleanup | 🟡 **设计师 review 中** | 同上；`--line-border` vs `--bg-layer3` SAME 等 |
| reference adoption (3b) | 🟢 **first round done — bug fixed in v0.6.1，待用户重跑确认** | MicroApps vue-app 实测 + 发现 META-001 + v0.6.1 fix 全在 2026-05-19 完成；用户用 PAT 装 npm 版重跑应该 ESLint = CLI 对齐 |
| RC channel 测试 (5b) | ⏳ 等用户 | 用户决定哪些产品做 v1.0.0-rc.1 测试 |

### 🔵 v1.0.0（稳定承诺 — API 锁定）

> **触发条件**（详见 [`V1_RELEASE_CHECKLIST.md`](./V1_RELEASE_CHECKLIST.md)）：5 能力交付 (能力 3 旁路 ack) · ESLint plugin reference adoption · color-contrast clean · burn-in waived

| 项 | 估时 | 备注 |
|---|---|---|
| API lock + migration guide | ✅ 文档已 done | [`API_STABILITY.md`](./API_STABILITY.md) + [`MIGRATION_TO_V1.md`](./MIGRATION_TO_V1.md) |
| Tier 3-H a11y CI infrastructure | ✅ done | tests/a11y/ + playwright.a11y.config.ts |
| color-contrast 清零 (v0.7.0 拖) | 🟡 | 等设计师 |
| RC 测试通过 | ⏳ | 等用户 |

### ⚪ Deferred / Out of scope

| 项 | 状态 | 理由 |
|---|---|---|
| **能力 3 (AI code→Figma)** | DEFERRED bypass shipped | Figma Pro plan 限制；[`CAPABILITY_3_BYPASS.md`](./CAPABILITY_3_BYPASS.md) 提供等价方案 |
| **T1c Extract Pipeline** | PAUSED | plan owner "元层疑问"未解 |
| **Phase 8** 视觉脚本 + Code Connect | DEFERRED | 需 Figma Org plan 升级 |

---

## Active 后续工作

```
v0.7.0 / RC         (4):  contrast cleanup (设计师) · non-text contrast cleanup (设计师) · reference adoption (等用户) · RC product testing (等用户)
v1.0.0 stable       (2):  contrast 清零后即可 stamp · burn-in waived
Backlog (active)    (4):  BRIDGE-MOCKUP-002 (icon Figma owner) · BRIDGE-DESIGN-REVIEW · INFRA-F21-v2/v3/v4 · INFRA-F25-bg-contrast — 见 backlog.md（META-001 已在 v0.6.1 ship）
Code-leads divergences (3): msg-bg-tinted-dark / chart-color-palette / pill-component-family — 见 translation/divergences-decisions.json
Deferred            (3):  能力3 bypass · T1c · Phase 8
```

**真正 next 可推进的**：等设计师 review contrast report → 改 Figma → sync 回 code 跑 v0.7.0；并行等用户给新产品 repo 做 reference adoption 装。

**排期决策必读**：[`retrospection/design-spec-canonical-alignment-tracker.md`](./internal/retrospection/design-spec-canonical-alignment-tracker.md) §排期原则 — **不按耗时 / 复杂度 / 成本最低排，按项目目标对齐 + 依赖解锁 + 自动化标准化排**。

---

## 起手必读链路

> **⛔ Mandatory Gate**：任何 AI session 在第一个项目相关回答 / 推荐 / 任务前，**必须按此顺序完成 5-step onboarding**（总 ~30min）。机械执行方式：用 TodoWrite / TaskList 建 5 个 todo，逐个 Read 完才能回答。基于 partial onboarding 给推荐 = **协议违反**。
>
> **违反信号**（命中任一 → 停下重读）：
> - "我已经知道大概了 / 状态简单跳一步" → 错
> - "grep 替代完整 Read" → 错（grep 只在已 onboard 后的具体查找场景用）
> - "memory 兜底替代 SoT" → 错（memory 是 AI 缓存，项目契约真源在仓库）
>
> **历史实证**：2026-05-13 session 10 跳过 PROJECT_GOAL + AGENTS → 首轮推荐缺 4 项硬约束（canonical SoT / plan owner 边界 / working-principles / meta-rules）→ 用户返工纠偏。

| Step | 文件 | ~时长 | 作用 |
|---|---|---|---|
| 1 | **本文件 STATUS.md** | 3min | 知道在哪（状态镜像） |
| 2 | [`PROJECT_GOAL.md`](./PROJECT_GOAL.md) | 5min | 知道目标（5 个能力 + 受众 + 约束） |
| 3a | [`design-spec-canonical-alignment-tracker.md`](./internal/retrospection/design-spec-canonical-alignment-tracker.md) | 4min | 排期 SoT — 知道下一段做什么 / 按什么原则排 |
| 3b | [`_plans/next-session-pickup-*.md`](./internal/_plans/) 最新一份 | 3min | 当前 sprint 操作手册 |
| 4 | [`AGENTS.md`](../AGENTS.md) 必读链路 §1-10 | 10min | 协作规则；Mockup 任务额外读 §7-10：design-process / domain-tvu / mockup-conventions / figma-technical-reference |
| 5 | 当前 sprint task 对应的 [`backlog.md`](./internal/backlog.md) entry | 5min | 具体上下文（完整 read 该 entry，不是 grep） |

---

## Wrap-up 协议（**强制**）

### 自动度

- **半自动**：AI 在 wrap-up 时按本协议主动跑（依赖协议 enforcement，写在 `tvu-design-{code,mockup}` skill 起手协议 wrap-up 步骤里）
- **SessionEnd hook 兜底**：`~/.claude/settings.json` 配 hook 检测 "Last updated 是否为今天"，不是则警告（机械触发，逃不掉）

### STATUS.md 必改项（每 session）

- [ ] 顶部 **"Last updated" 日期改到今天**（这一条 hook 会自动核验）
- [ ] "当前版本" 段更新（如有 release）
- [ ] "Version Roadmap" 各 bucket 删除已完成项 / 加新发现项
- [ ] "Active 后续工作" 段刷新剩余项数
- [ ] **[`retrospection/design-spec-canonical-alignment-tracker.md`](./internal/retrospection/design-spec-canonical-alignment-tracker.md) 同步**：把本 session 完成的项加入 tracker（完成日期 + 耗时）

### Release wrap-up 必改项（仅 release tag pushed 时强制）

> **协议规则**（2026-05-11 落实 — v0.1.0/v0.1.1 silent fail 盲点修复点）：
>
> **Release tag pushed + CI green 不等于 publish 成功。必须 verify GitHub Packages 页实物显示包 + 版本号；CI green 只代表 step exit 0，不代表 registry 接受。**

- [ ] CI workflow run 全 green（actions 页 status PASS）
- [ ] **Packages 页 actual 显示 `@scope/package@<new-version>` 实物**（不能跳此步 — 之前 v0.1.0/v0.1.1 silent fail 根因）
- [ ] STATUS.md "当前版本" 段 "已 publish" 行加 Packages 页 URL link as evidence
- [ ] 复盘 retrospect 含 Packages 页 actual 状态（PASS / fail 都记，fail 写诊断）

### Retrospection 触发判断（分级，不是每次必写）

| 触发条件 | 是否必写 retrospect |
|---|---|
| 阶段性 release（patch / minor / major 完成） | ✅ 必写 |
| 踩了反模式（如 library-key-confusion） | ✅ 必写 |
| 学到通用工程经验 / 发现新 pattern | ✅ 必写 |
| 完成单个 backlog entry 但无新认知 | ❌ 跳过（避免噪音） |
| 纯讨论 / 调研 / 评审 | ❌ 跳过 |

复盘文件位置：`docs/internal/retrospection/<YYYY-MM-DD>-<topic>.md`

**不更新 STATUS.md / 漏复盘 → 下次 session 又要从碎片重组**（同 2-3 周状态混乱的根因）。

---

## 文件关系（防混淆）

| 文档 | 用途 | 更新节奏 |
|---|---|---|
| **STATUS.md**（本文件） | 全局状态镜像 + 版本线分组 + Active 余量 | **每 session** |
| `PROJECT_GOAL.md` | 项目目标 + 5 个能力 + 受众 + 约束 | 大方向变才改（罕见） |
| `_plans/next-session-pickup-*.md` | 当前 sprint 操作手册（prompts / 任务顺序 / dirty 协议） | **每 sprint** |
| `CHANGELOG.md` | Release-facing（外部 consumer 看）| 每 release |
| `backlog.md` | 全量 entry 详情（Active only，完成直接删） | 每发现 / 每完成 |
| `retrospection/design-spec-canonical-alignment-tracker.md` | 设计规范完整计划 + 进度时间线（living doc）| **每 session wrap-up 前同步** |
| `retrospection/*.md` | 阶段复盘（决策 / 反模式 / 教训） | 每阶段完成 |

**真源关系**：STATUS.md 是各 SoT 的**镜像/导航**，不是 SoT 本身。具体决策仍在 PROJECT_GOAL / pickup / backlog / CHANGELOG。