# 设计规范整理 — 完整计划 & 进度时间线

> **Living document** — 每次 session wrap-up 前必须同步，补入本 session 完成的项（完成日期 + 耗时）。
> 参考入口登记在 `STATUS.md` Wrap-up 协议 + 文件关系表。
>
> **本文件是项目排期 SoT** — 任何 "v0.X 包含哪些 / 先做哪个 / 该不该上 Tier N" 决策都查这里。STATUS.md 是状态镜像，本文件是计划真源。

> **SoT 实证 (2026-05-15)** — Button family figma 真源数字 "21 sets / 8400 variants"（出现在历史 retrospect 2026-05-06 / 2026-05-07 / 历史 prompt phase-a1-generator-auto-discovery）是早期估算。v0.5.0 Sprint A baseline 通过 `jq '[.components[] | select(.figmaName | test("Button"; "i"))]' figma-data/normalized/components.manifest.json` 实证修正为：
>
> - **8 主 sets × ~400 variants**（`Button/dark|light × L|M|S|XS`）= 3,200 主 variants
> - Button/url link 特殊 set：1 set × 4 variants
> - 孤立 `IconLoadingButton*` 单节点：20 个（figma 文件未归集到主 set，建议设计师 cleanup — 已登记 [`backlog.md`](../backlog.md) BRIDGE-MOCKUP-006 候选）
> - **figma entries 总数 29 / 总 variants 3,224**
>
> 历史 retrospect / 历史 prompt 内"21 sets / 8400 variants"原文保留作为历史快照，不重写正文；本段是 ground truth 锚点。本文件 + STATUS.md + backlog.md + prop-aliases.json + 当前 sprint pickup 均已同步为实证数字。

---

## 什么是"设计规范整理"

本项目设计规范整理涵盖**三条并行轨道**：

| 轨道 | 内容 | 项目目标关系 |
|---|---|---|
| **A — Canonical 对齐**（CANONICAL / BRIDGE / EXTRACT 系列）| 组件代码 vs Figma 真源 mismatch 修复 + API 形态统一 + Figma 真源 pipeline | 能力 1（dev npm）+ 能力 2（Figma URL → code）+ 能力 5（溯源）|
| **B — 设计流程文档**（M 系列 + Agent / Skill）| mockup-conventions / design-process / domain-tvu / figma-technical-reference | AI / 设计师协作规则可机械执行 |
| **C — 自动化基础设施**（Tier 1/2/3）| translation schema 化 + mockup audit + ESLint plugin + a11y | **能力 4（multimodal → 合规 mockup）**+ 加固能力 5（溯源 schema 验证）+ 强化能力 1（consumer 自检）|

---

## 排期原则（**决策方法论 — 不可违背**）

> **背景**：plan owner 历史上倾向"按复杂度 / 耗时 / 成本最低"排，导致主线工作被小任务推后。本原则机械约束 plan owner，每次提排期前必须读一遍。
> **触发查看条件**：任何 "v0.X 包含哪些 / 先做哪个 / 该不该上 Tier N" 决策。

### 排期权重（按优先级降序）

1. **项目目标对齐** — 直接落地 [`PROJECT_GOAL.md`](../../PROJECT_GOAL.md) 5 个能力之一的工作 → **最高优先级**
2. **依赖解锁** — 后续多项工作的前置 → 高优先级（哪怕单项工作量大）
3. **自动化 / 标准化** — 把 L1 文本规则升 L3+ 工具的工作 → 高优先级（[`meta-rules.md`](../../meta-rules.md) trigger K 已强制 "客观可测规则 → L3+"）
4. **快速可交付的独立项** — 0 阻塞 + 短 cycle → 顺路填空，**不挤主线**

### 不应作为排期依据的反模式

| ❌ 反模式 | ✅ 正解 |
|---|---|
| "这项小，先做" | 看是否在主线依赖路径上 |
| "这项 20-30h，太大推后" | 看是否阻塞其它项；若是 → 优先 |
| "成本最低先做" | 项目目标对齐 > 单项成本 |
| "先做简单的看进度" | 进度感来自里程碑达成，不是任务计数 |
| "这项不阻塞，留着以后" | 若对齐项目目标核心能力 → 主线，不"留着" |

### 自检清单（每次提排期前过一遍）

- [ ] 这项跟 [`PROJECT_GOAL.md`](../../PROJECT_GOAL.md) 哪个能力对齐？（必须能答上来 1 个）
- [ ] 这项 unblock 多少其它项？
- [ ] 有没有按 "小 / 快 / 简单" 理由把主线工作推后？
- [ ] 自动化前置基础设施是否在主线前 1-2 个 sprint？
- [ ] 排期表里 patch / minor / major 命名是否符合 0.x semver（破坏性走 0.x.0，1.0 = 稳定承诺）？

> **5 条全 ✓ 才能提出排期；命中任一 ❌ → 停下重排**。

---

## Release 排期（v0.2 → v1.0）

> **核心原则**：0.x 阶段 **minor (0.x.0) 可含破坏性**；patch (0.x.y) 只 non-breaking；1.0 = 稳定承诺、API 锁定。
> **能力对齐**：每个 release 必须在"对齐能力"栏标明落地 [`PROJECT_GOAL.md`](../../PROJECT_GOAL.md) 哪个能力。

### ~~v0.2.0~~ ✅ shipped 2026-05-13

| 项 | 内容 |
|---|---|
| **对齐能力** | 能力 1（dev npm 可消费 Chart）+ 能力 2（Figma → code 完整 mapping）|
| **内容** | CANONICAL-011 Chart（6 variants + Chart.js + 12 色 palette）+ BRIDGE-MOCKUP-004 audit:published-vs-code 升 9th strict gate + Playwright 58 baseline + husky v1 + INFRA-F30 idempotent writes |
| **实际耗时** | ~2h（含 CI fail fix + re-tag + INFRA-F30 顺手扩） |
| **Evidence** | [CI run 25788351709](https://github.com/NancyZeng0210/TVU-Design-System/actions/runs/25788351709) green 1m23s; Packages 页 verified "0.2.0 Latest" |

### v0.3.0（**自动化前置 + API 增强**）

| 项 | 内容 |
|---|---|
| **对齐能力** | **能力 5（溯源）schema 化** + 能力 1/2（API 增强 + AI 从 Figma URL 完整 prop 暴露）|
| **破坏性** | 是（BRIDGE-005 改 API；Phase 6.4 non-breaking 顺路）|
| **排期理由** | Tier 1-A 已完成并 unblock 后续翻译层增改 |
| **内容** | **Phase 6.4**：加 showCount / multiple / editable props（non-breaking）<br> **BRIDGE-005**：Figma boolean / instance-swap 三层 schema 升级（generator + canonical + prop-aliases）<br><br>✅ **Tier 1-A 已于 2026-05-14 完成**：translation JSON + Schema + `audit:translation-completeness` L5 strict gate（10 维 audit 含维度 6 active vs resolved cross-check 防 SoT drift 复发）<br>✅ **Phase 6.3 实际 2026-04-28 已 resolved**（commit 897d709c；divergences-decisions.json `notification-success-deletion` + `notification-type-deletion` 标 resolved。STATUS / tracker 2026-05-11 stale active 列入是 SoT drift，2026-05-14 修正） |
| **估时** | ~1-2 天（剩 Phase 6.4 + BRIDGE-005） |

### ~~v0.4.0~~ ✅ shipped 2026-05-14（API 形态统一）

| 项 | 内容 |
|---|---|
| **对齐能力** | 能力 1（dev API 一致）+ 能力 2（AI 从 Figma URL 不撞双 API）|
| **内容** | **Phase 6.6a**：FormItem.label `#label` 命名 slot dual-form (commit 529bb366)<br> **Phase 6.6b**：Tooltip.content `#content` 命名 slot dual-form + FormItemPage Icon demo fix (commit 0db2bfd0)<br> **Phase 6.7**：Badge SoT drift reconciliation B path — canonical 自 checkpoint 9e3ca1ae 已 ship 实质内容，本版本 ack (commit 5546ae0b)<br> **Tier 2-D**：`scripts/new-backlog.mjs` 自动 ID generator (commit 50ff23d0) |
| **实际破坏性** | **否** — 4 项全 non-breaking（dual-form 加新命名 slot 不删旧 prop；Phase 6.7 0 code change；2-D 是 dev 工具）。Pickup 原 "破坏性=是" 描述基于 spec 视角；执行后实证 non-breaking |
| **实际耗时** | ~4h（4 sprints 每 sprint ~1h；远低于估 ~12-18h，沿用 v0.3.0 实跑 4-8x under-estimate 经验）|
| **Evidence** | [CI run 25856655323](https://github.com/NancyZeng0210/TVU-Design-System/actions/runs/25856655323) green 1m24s; Packages API verified — `0.4.0` created 2026-05-14T11:07:11Z; [Packages page](https://github.com/users/NancyZeng0210/packages/npm/package/tvu-design-system) |

### ~~v0.5.0~~ ✅ shipped 2026-05-18（最大组件 + tooling + pipeline Styles + mockup sync）

| 项 | 内容 |
|---|---|
| **对齐能力** | 能力 1/2（Button 是 DS 第一大组件）+ Tier 2 tooling（AI workflow 加速）+ 能力 5（pipeline Styles 抽取）|
| **实际 shipped** | **Phase 6.8** ✅ (commit 136ddc4b)：Button canonicalTheme axis；8 axis 完整覆盖 figma 8 sets。旧 API @deprecated since 0.5.0 → removed v0.6.0。**Tier 2-E** ✅ (commit 27c90388)：figma-url-to-canonical CLI。**Tier 2-F** ✅ (commit 27c90388)：lint-skills CLI，6 skills 0 broken links。**CANONICAL-007** ✅ (commit 63a9cdaf)：Pagination native button → DS Button。**EXTRACT-006** ✅ (this session)：`extractStyles()` + `getFileStyles()`；live 14 text / 4 effect / 0 fill / 0 grid；normalized-key prev merge 保留 canonicalToken/usage/_alignment_decisions/scaleTokens。**INFRA-F32** ✅ (this session)：`sync-mockup-data.mjs` + parametrized api.mjs；`.gitignore figma-data/mockup/`；live verified w/ MicroApps fileKey (~65 MB)；解锁 Tier 1-B。|
| **Tier 1-B 状态** | **unblocked → v0.6.0**：F32 已完成；audit 实现仍 ~6-10h，留 v0.6.0 |
| **破坏性** | **否** — Phase 6.8 加新 axis + 旧 API @deprecated（v0.6.0 才真删）；其余纯加法 |
| **实际耗时** | ~5.5h（Phase 6.8 ~3h + Tier 2-E/F ~1h + CANONICAL-007 ~30min + EXTRACT-006 ~30min + INFRA-F32 ~30min；vs 历史估 ~1-2 周）|
| **Evidence** | [CI run 26024995380](https://github.com/NancyZeng0210/TVU-Design-System/actions/runs/26024995380) green; Packages API verified — `0.5.0` created 2026-05-18T09:28:01Z; 2 CI hotfix commits (4f18a065 Mask blur8 双空格 alias / 4b7de2ed lint-skills globSync) |

### ~~v0.6.1~~ ✅ shipped 2026-05-19（consumer reference adoption 实测 + META-001 fix + files[] fix）

> CI 一次过（[run 26079553331](https://github.com/NancyZeng0210/TVU-Design-System/actions/runs/26079553331)）；Packages 实物 verified 0.6.1 created 2026-05-19T06:09:27Z。详见 [retrospect](./2026-05-19-consumer-verification-microapps.md)。consumer reference adoption (v1.0 trigger 3b) 第一次外部实测；MicroApps Console vue-app；同 session 发现 + 修 + ship META-001。

| 项 | 状态 | commit |
|---|---|---|
| **META-001** ESLint plugin no-inline-svg Vue SFC `<template>` 探测 | ✅ 2026-05-19 | 88c23060 |
| **files[] expansion** npm tarball 含 scripts/templates/docs | ✅ 2026-05-19 | b99fafcc (master HEAD 已修，v0.6.1 ship) |
| **consumer reference adoption 3b** MicroApps vue-app 实测 (local tarball + real npm registry 双路径) | ✅ 2026-05-19 | retrospect 2026-05-19 |

**对齐能力**：v1.0 trigger 3b reference adoption 解锁；CLI ↔ ESLint plugin 语义对齐（真源单一原则在 audit 层落实）

---

### ~~v0.6.0~~ ✅ shipped 2026-05-18（tooling + audit infra + Button breaking + ESLint plugin）

> CI 一次过（[run 26028124326](https://github.com/NancyZeng0210/TVU-Design-System/actions/runs/26028124326)）；Packages 实物 verified 0.6.0 created 2026-05-18T10:35:01Z。详见 [retrospect](./2026-05-18-v060-release.md)。F34 Node 20/22 matrix 起作用 — v0.5.0 需 2 hotfix 才过, v0.6.0 含 11 项 incl. BREAKING + 新 subpath export 仍一次过。

| 项 | 状态 | commit |
|---|---|---|
| **INFRA-F32** figma-data/mockup/ sync 机制 | ✅ 2026-05-18 | 2b54a73b |
| **Tier 2-G** STATUS.md 一致性 lint | ✅ 2026-05-18 | 935f4aab |
| **Tier 1-B** M-INTEGRITY (M27/M28/M34 = I1/I2/I3) | ✅ parallel session | 093064fa |
| **Tier 1-B** M-COLOR (M10/M25/M26 = C1/C2/C3) | ✅ parallel session | 093064fa |
| **Tier 1-B** M0/M1/M30 library-binding | ✅ 2026-05-18 | 935f4aab |
| **F34** scripts stdlib stability + Node 20/22 CI matrix | ✅ 2026-05-18 | 6314e58a |
| **F33** code-side figma name normalize | ✅ 2026-05-18 | fa500040 |
| **hook allow-list 升级** (figma-styles.json) | ✅ 2026-05-18 | 6314e58a |
| **R1/R2/R16 audit-product-code.mjs** (CLI, not ESLint plugin yet) | ✅ parallel session + 935f4aab tracking | 093064fa + 935f4aab |
| **Tier 1-C** proper `@nancyzeng0210/eslint-plugin-tvu-design-system` npm 包 | 🔲 deferred — 独立 sibling package, ~2-3 sessions | — |
| Button legacy props removal (v0.5.0 @deprecated → 真删) | 🔲 待 v0.6.0 release timing | — |

**对齐能力**：能力 4（mockup audit 多个 L3+ gate 落地）+ 能力 1（R-rule consumer code 检查 CLI 版本就位）+ Tier 2 全自动化巩固

**Release timing 决策点**：当前 master 已累积 v0.5.0 之后的 9 项工作。两条路：
- 路线 A：现在 ship v0.6.0 minor（Tier 1-C 留 v0.7.0）— Button @deprecated 真删 + 当前已累积
- 路线 B：先做 Tier 1-C（~2-3 sessions）再 ship v0.6.0 大块头 — 推迟 ~1-2 周但 release content 更厚

**估时**：路线 A ~30min release wrap；路线 B ~2-3 sessions + release

### v1.0.0（**稳定承诺**）

| 项 | 内容 |
|---|---|
| **对齐能力** | **5 个能力全交付** |
| **触发条件** | (a) PROJECT_GOAL 5 能力全部 ship；(b) 至少 3 个月无 breaking change；(c) ESLint plugin + mockup audit + translation schema 三大自动化全 L5；(d) a11y axe-core CI 跑通；(e) API 锁定 + 写迁移指南 |
| **内容** | **Tier 3-H** axe-core a11y audit；Phase 8 视觉脚本 + Code Connect（如 Figma plan 升级到 Org）；API 锁定 + 写迁移指南 + 公开 changelog |
| **估时** | wrap-up 阶段（~2-3 周） |

---

## 轨道 A — CANONICAL 系列

### 已完成

| ID | 内容摘要 | 完成日期 | 耗时估算 | 版本 |
|---|---|---|---|---|
| CANONICAL-001 | Tooltip `placement=top-*` arrow CSS 偏移修复 | 2026-05-09 | ~30min | v0.1.0 |
| CANONICAL-003 | BaseNotification iconMap 不一致 + Icon.vue inline `currentColor` override | 2026-05-09 | ~1h | v0.1.0 |
| CANONICAL-009 | audit:design-system 升 strict（scoped CSS vars false-positive + carrier 白名单 + Tab.vue token 替换）| 2026-05-11 | ~2h | v0.1.1 |
| CANONICAL-004 | Progress dark track token：`--progress-track-bg-dark` → `var(--line-deep)` (#353535) | 2026-05-13 | ~30min | patch（未单独 release）|
| CANONICAL-006 | Pagination figma alignment refactor — 7 mismatch（nav row gap / Simple nav width / Classic btn bg+border+font-weight / Small btn size 24→32px）+ .pg-main→.pg-content+.pg-nav-row hierarchy 重构 | 2026-05-13 | ~2h（prompt 写作 + Codex executor + 验收）| patch（未单独 release）|
| CANONICAL-010 | PopupBox 实现 — modal dialog + 命令式 API（PopupBox.alert/.confirm/.open）+ Teleport + docs page | 2026-05-12 | ~10-15h | v0.1.3 |
| CANONICAL-002 | PromptMessage auto-dismiss — `autoDismissMs?: number` prop + `watchEffect` timer + `onBeforeUnmount` cleanup；prop-aliases.md 登记；docs Events 表修正 | 2026-05-13 | ~30min | patch（未单独 release）|
| CANONICAL-008 | Table + InputNumber 字体 — 确认 `--font-family-en` token 含 Helvetica Neue fallback，macOS 渲染正常，非 drift，无需代码改动 | 2026-05-13 | ~5min（验证即关）| N/A（已关闭）|
| INFRA-F19 | Docs site theme toggle 完整化 — 发现已在前次 session 实现（DocsShell provide + FigmaMembersGrid inject + 18 pages :site-theme 删除 + audit gate 反转），补删 backlog 条目 | 2026-05-13 | ~10min（验证即关）| N/A |
| INFRA-F20 | Playwright 视觉基线 — playwright.config.ts + tests/visual/docs-pages.spec.ts（29 page × dark/light = 58 baseline）| 2026-05-13 | ~1.5h（prompt + Codex 执行 + 验收）| commit 5a9d4ab7 |
| vitest fixture sync | 10 fixture drift（CANONICAL-002/006/008 漏跑 test 教训）+ retrospect + F21 vitest gate spec | 2026-05-13 | ~1h | commit 5b39e886 + retrospect 2026-05-13-vitest-fixture-drift |
| INFRA-F26 | extract-figma timestamp idempotence — extract.mjs + normalize-component-tokens.mjs stripPaths + --force | 2026-05-13 | ~1.5h（prompt + Codex + 验收）| commits fa03b1ee/af61d18a/98a85bd3 |
| INFRA-F29 | normalize.mjs normalizedAt churn — inline patch 复用 F26 helper（MD5 verified idempotent）| 2026-05-13 | ~15min | commit c2c17969 |
| INFRA-F21 v1 + polish | husky pre-commit hook（vue-tsc/vitest/figma-data block）+ polish 加 sync-output 白名单（mapping.json + audit reports 允许）| 2026-05-13 | ~1.5h（prompt + Codex + polish）| commits 4f993a17/0d9332b6/716212ba/2b1283b5 |
| CANONICAL-011 | Chart 实现（6 variants · Chart.js + 12 色 palette） — D1 dep 选型 + D2 API 设计 + D3 implementation + F20 baseline cascade refresh | 2026-05-13 | ~6h（D1/D2 设计 + Codex impl + 验收 + cascade fix）| v0.2.0；commits bb32f374/96016f23/061a3e54/4f715141；retrospect 2026-05-13-canonical-011-prompt-gap |
| BRIDGE-MOCKUP-004 | tracker 收尾 — figma-to-code-mapping.json status update + publish.yml continue-on-error 移除 + RELEASING.md gate 表更新 → audit:published-vs-code 升 9th strict | 2026-05-13 | ~30min | commit 444406a2 |
| v0.2.0 release ship | changeset → CI green → Packages 页 verified `0.2.0 Latest`；含 Chart + 9 strict + Playwright + husky v1 + INFRA-F30；第二次重打 tag 修了 audit:docs-site ChartPage manifest gap (CANONICAL-011 prompt gap retrospect) | 2026-05-13 | ~1h（含 fix CI fail + re-tag）| v0.2.0；CI run 25788351709 |
| INFRA-F30 | timestamp-aware idempotent writes — icon-artifacts.mjs writePublishedManifest + audit-page-t2-sample.mjs renderReport + audit-figma-published-vs-code.mjs writeJSON/writeFileSync；strip `generatedAt` / `生成时间` / `Generated at` / `checkedAt`；消除 ~20 文件每次 commit dirty noise（同 F26/F29 pattern） | 2026-05-13 | ~1.5h（含 verify + audit-figma-published 顺手）| commit 2cf026e9 |
| 排期 SoT 重构 | tracker 加"排期原则"+ "Release 排期 v0.2 → v1.0" + 轨道 C 自动化路线；STATUS 同步重命名 v0.3/v0.4/v0.5/v0.6 (替换"v1.0 major")；PROJECT_GOAL 阶段路线同步；meta-rules 加 trigger M (排期决策反模式) | 2026-05-13 | ~2h | commit c6a70d1a |
| INFRA-F31 | 5-step onboarding gate enforcement — STATUS §起手必读链路 加 mandatory gate + tracker 显式 step 3a + 违反信号；AGENTS 顶部新增 ⛔ Onboarding Gate 段；.claude/hooks/onboarding-checklist.sh SessionStart hook 注入 5-step checklist via additionalContext；防 AI shortcut 起手必读（session 10 实证：跳 PROJECT_GOAL+AGENTS → 缺 4 项硬约束 → 用户返工） | 2026-05-13 | ~1h（设计 + 编辑 + hook + 验证） | commit 812365a8；retrospect 2026-05-13-onboarding-gate-enforcement |
| Tier 1-A Sprint 1 | axis-implementation-map.md → JSON + Schema (16 instances) + 归档原 md → _archive | 2026-05-14 | ~1h vs 估 1d | commit 40e8c777 |
| Tier 1-A Sprint 2 | prop-aliases.md split → prop-aliases.json (102 entries 13 scope) + 瘦身 md narrative (225→125 行) | 2026-05-14 | ~1h vs 估 2-3d | commit 76e99070 |
| Tier 1-A Sprint 3 | divergences.md split → divergences-decisions.json (26 decisions 8 category) + 保留 narrative | 2026-05-14 | ~1h vs 估 2-3d | commit 859c2ba5 |
| Tier 1-A Sprint 4 | audit:translation-completeness 5 维 audit + 10th strict gate + allowlist + RELEASING/STATUS/tracker/retrospect sync (Plan owner 修 3 处: shell PATH bug / 5 rg→grep verifyHint / log polish) | 2026-05-14 | ~2h vs 估 2-3d | commit 8534f01d |
| SoT drift cleanup + audit dim 6 | Phase 6.3 stale active 修正 + BreadcrumbItem showIcon↔showSeparator alias drift fix + INFRA-F30 4th source idempotent + audit dim 6 (STATUS/tracker active vs divergences-decisions resolved cross-check) 实证抓 8 个 stale finding | 2026-05-14 | ~1.5h | commit 788f1be2 |
| BRIDGE-005 | generator 加 booleanProperties 字段 (parseBooleanPropsFromTsx + lookupBooleanPropertyAlias) + DocsFigmaMembers schema 升级 + 9 components 重生成 + Plan owner fix: axis-named props 排除 (Radio.status axis 误推 boolean) | 2026-05-14 | ~1.5h vs 估 6-10h | commit 201895c4 |
| Phase 6.4 | Input.showCount + maxlength + Select.multiple + Select.editable runtime additions (non-breaking; sugar shortcut for figma axis values via OR merge) + 3 prop-aliases entries + 3 vitest tests | 2026-05-14 | ~1h vs 估 4-6h | commit 8ce29ac8 |
| v0.3.0 release ship | changeset → version bump → tag push → CI green 1m13s → Packages API verified `0.3.0` created 2026-05-14T08:25:59Z; 完整 release wrap-up: STATUS/tracker/retrospect sync | 2026-05-14 | ~30min | commit 516d14ab; CI run 25849955436; v0.3.0 tag |
| audit translation-completeness h2 boundary fix | audit-translation-completeness.mjs `auditActiveVsResolved` section.end 加 `^## ` h2 截断（避免 `### v1.0.0` section 吞掉后续 `## 轨道 A` timeline 表 → 2 个 Phase 6.3 false-positive active-stale 清除）| 2026-05-14 | ~30min | commit cca1a043 |
| Phase 6.6a FormItem.label dual-form | base + canonical FormItem.vue 加 `#label` 命名 slot（slot 优先 over prop；default slot 保持 content/control 区） + 3 vitest case + FormItemPage Custom Label Slot demo + divergences/decision/prop-aliases 同步 | 2026-05-14 | ~1h vs 估 3-4h | commit 529bb366 |
| Phase 6.6b Tooltip.content dual-form | base + canonical Tooltip.vue 加 `#content` 命名 slot（slot 优先 over prop；default slot 保持 trigger） + 3 vitest case + TooltipPage Custom Content Slot demo + FormItemPage 顺路 fix demo 用公开 Icon export 路径满足 FigmaFirstContract test + divergences/decision/prop-aliases 同步 | 2026-05-14 | ~1h vs 估 3-4h | commit 0db2bfd0 |
| Phase 6.7 SoT drift reconciliation (B path) | 发现 pickup §3.2 描述 canonical.type=颜色枚举与现状脱节——canonical Badge 自 checkpoint 9e3ca1ae 起即为 color/tag/type=Circle\|Rectangle API；plan owner 直改 divergences.md/decision JSON 措辞 ack Phase 6.7 实质已 implemented，不改代码（避免破坏 consumer + 翻译层最小化）| 2026-05-14 | ~30min | commit 5546ae0b |
| Tier 2-D backlog ID generator | `scripts/new-backlog.mjs` 单文件 ESM CLI（~89 行 zero-dep）：扫 3 SoT 文件（backlog.md + STATUS.md + tracker.md）找 `<PREFIX>-(\d+)` word-boundary regex 隔离 sub-prefix（BRIDGE vs BRIDGE-MOCKUP），输出 max+1 + entry stub。+`pnpm new-backlog` npm script。Plan owner direct-implement path B（用户 ack）| 2026-05-14 | ~20min vs 估 2h | commit 50ff23d0 |
| v0.5.0 Sprint A.1 baseline + 路线拍板 | Phase 6.8 实证 baseline：jq components.manifest.json → 8 主 sets × ~400 variants + 1 url + 20 isolated = 29 entries / 3,224 variants（修正历史估 "21 sets / 8400 variants"）；ButtonBridge 现 7 axis 已覆盖 figma 6 axis + size，**唯一缺口 = canonicalTheme axis**；path A 拍板（加新 axis + @deprecated old API，v0.6.0 才真删）；SoT 实证段写入 tracker 顶部；next-session-pickup-2026-05-15-v0-5-0.md 新建 | 2026-05-15 | ~1.5h | prep for v0.5.0 |
| v0.5.0 Sprint A.2 SoT drift cleanup | 实证数字同步 5 个文件（tracker §SoT 实证 / STATUS.md §v0.5.0 / backlog CANONICAL-007 + 历史 BRIDGE-Tier3 merged / prop-aliases entry composition-button-blocked-004 notes / divergences-decisions button-canonical-api-migration）；jq 验证 JSON 合法；commit d48cfc81 | 2026-05-15 | ~1h | commit d48cfc81 |
| Phase 6.8 Button canonical 迁移（canonicalTheme axis）| ButtonBridge.vue inject + resolvedTheme computed + `:canonical-theme` 透传；Button.vue `canonicalTheme` prop + `CanonicalContract.theme` + `data-figma-theme` attr + legacy props `@deprecated since 0.5.0`；3 vitest cases；decisions JSON `button-canonical-api-migration` → resolved；runtime-additions.md + ButtonPage.vue 更新；commit 136ddc4b | 2026-05-18 | ~3h (prompt writing ~1h + executor ~30min + review ~30min; vs 历史估 ~20-30h) | commit 136ddc4b |
| Sprint B baseline + Tier 1-B blocker 识别 | figma-data/ 目录 baseline：无 mockup/ 子目录；Tier 1-B `audit:mockup-conformance.mjs` 全部 M-rule 检查需 figma API 拉 mockup 文件数据 → BLOCKED；INFRA-F32 补入 backlog（figma-data/mockup/ sync 机制前置设计）；Sprint 路线 pivot → Tier 2-E/F 直接实现 | 2026-05-18 | ~30min | INFRA-F32 backlogged |
| Tier 2-E figma-url-to-canonical.mjs | `scripts/figma-url-to-canonical.mjs` 单文件 ESM CLI：parse Figma URL → nodeId → lookup components.manifest.json（component-level + variant-level）→ cross-ref figma-to-code-mapping.json → 输出 figmaName / codeNames / variantAxes / matched variant props。`pnpm figma-url-to-canonical` npm script | 2026-05-18 | ~30min vs 估 ~4-6h | plan owner direct (path B) |
| Tier 2-F lint-skills.mjs | `scripts/lint-skills.mjs` 单文件 ESM CLI：globSync `.claude/skills/*/SKILL.md` → 提取 markdown 链接 → 双路径 resolve（skill-relative + repo-root-relative）→ 校验文件存在；exit 1 if any missing。`pnpm lint-skills` npm script。6 skills 全 pass（0 broken links）| 2026-05-18 | ~30min vs 估 ~3-5h | plan owner direct (path B) |
| CANONICAL-007 Pagination buttons → DS Button | native `<button class="pg-btn">` 替换为 `<Button canonicalStyle/Color/Size/Radius>`；active=filling+green，inactive=filling+gray1，Small=rimless；arrow buttons=rimless+Icon slot；`.pg-nav-row :deep(.btn)` compact size override（延续 Pagination 既有 :deep 模式）；backlog entry 删除 | 2026-05-18 | ~30min vs 估 ~2h | commit 63a9cdaf |
| EXTRACT-006 extract pipeline Styles | `figma-sync/api.mjs` 加 `getFileStyles()`；`figma-sync/extract.mjs` 加 `extractStyles()`（批量 getNodes ≤100 ids；TEXT/EFFECT/FILL/GRID 四类；normalized-key 前向 merge 保留 prev canonicalToken/usage/description；`_alignment_decisions` + `scaleTokens` 原样保留）；live run 14 text (7 PingFang SC new) / 4 effect / 0 fill / 0 grid；idempotent verified | 2026-05-18 | ~30min vs 估 3-4h（pickup 内置完整 spec）| v0.5.0 release prep |
| INFRA-F32 figma-data/mockup/ sync 机制 | `figma-sync/sync-mockup-data.mjs` + `pnpm sync:mockup <fileKey>` 新 CLI；`api.mjs` 5 helpers (`getFile/getNodes/getFileStyles/getVariables/getImages`) 加 optional `fileKey` 参数（默认 env library key，向后兼容）；`figma-data/mockup/` 入 `.gitignore`（产品 mockup 文件大 + drift 频繁，不入设计系统库 repo）；live verified w/ MicroApps fileKey `DtZcMkhNy6qh6jbQQnhreQ` (~65 MB raw dump + idempotent re-run via `_meta.extractedAt` strip)；解锁 Tier 1-B audit:mockup-conformance（实现仍 v0.6.0） | 2026-05-18 | ~30min vs 估 ~2-3h | v0.5.0 release prep |

> CANONICAL-005 编号未分配（gap）。

### 待完成（按版本归类）

| ID | 内容摘要 | 版本 | 估时 | 备注 |
|---|---|---|---|---|
| ~~Phase 6.8~~ ✅ | Button canonical 完成迁移（canonicalTheme axis；commit 136ddc4b 2026-05-18）| v0.5.0 | ~3h 实跑 vs 历史估 ~20-30h | 8 主 sets / 3,200 variants |
| ~~EXTRACT-006~~ ✅ | Figma extract pipeline 抽 Text / Effect / Fill / Grid Styles | v0.5.0 | ~30min 实跑 vs 估 6-10h | infra |
| ~~CANONICAL-007~~ ✅ | Pagination buttons → DS Button | v0.5.0 | ~30min 实跑 vs 估 ~2h | commit 63a9cdaf |

---

## 轨道 B — 设计流程文档

### 已完成

| 里程碑 | 内容摘要 | 完成日期 | 耗时估算 |
|---|---|---|---|
| M1–M16 初版 mockup-conventions | 基础 mockup 规则（Phase 0-3 / token / component / 布局 / 验收）| 2026-04-28 ~ 2026-05-09 | ~3-4 sessions |
| M21 增量复用规则 | 已建立产品的增量优先复用 local（US-3 scope），补 mockup-conventions + code-conventions 决策空白 | 2026-05-11 | ~1h |
| M22 User Design Intent Acknowledgment | 新增 Pre-Phase 0 前置 Gate（M22），US-1/2/3 全触发，防止"跳过 design ask" | 2026-05-11 | ~1h |
| M14 / M21 扩展（trifecta）| M14 范围扩到任何参考输入 + "高频被误抄字段"表；M21 加 sibling visual contract 6 维度 mandatory probe | 2026-05-11 | ~2h |
| Design Process Architecture 重构（Steps 1-5）| mockup-conventions.md 拆 3 层（design-process.md / domain-tvu.md / figma-technical-reference.md）；M11-13 合并；新建 design-discovery skill / design-walkthrough / persona-simulation agent | 2026-05-12 | ~4-5h |
| Design QA Loop + Agent 优化 | F1/F2 dogfood on SaaS Dashboard；design-qa-loop agent（两阶段 QA loop + auto-fix + Dev Handoff Gate）；domain-tvu.md 加默认 persona 表（CFO/PM/SRE）| 2026-05-12 | ~3h |
| M17-M20 迁出为 figma-technical-reference | 4 条 Figma API quirk（canvas position / frame traversal / rounded numbers / strokeEndCap 限制）从 mockup-conventions 迁出独立 | 2026-05-12 | ~1h（含架构决策）|
| Design Process Rules 整理收尾（缺口 A/B/C）| mockup-conventions.md 676→191 行（thin out 完成）；AGENTS.md §Mockup 链路拆 §7-10；STATUS.md 必读链路更新 | 2026-05-13 | ~2h |
| M23 UX 交付注释格式（双语标注）| 多状态流程图 5 层结构 / 主题无关配色 / 双语布局决策树（Layout A-右/A-下/B）/ ZH 弱化 opacity 0.45 / 验证策略（probe 优先）| 2026-05-12 ~ 05-13 | ~4h |
| figma-technical-reference Q5/Q6 | Q5：GROUP vs FRAME canvas 名称标签差异；Q6：VECTOR 不支持 strokeEndCap | 2026-05-13 | ~30min |

### 待完成

| 里程碑 | 内容摘要 | 估时 | 优先级 |
|---|---|---|---|
| BRIDGE-MOCKUP-001/002/003/005 | TVU 库补 4 个 dark-mode Msg-bg token / Arrow sorting variants / Pill promotion / 12 chart-color tokens — **设计师 owner** | TBD | Medium |
| M-next（TBD）| 下一个从实战中暴露的规则缺口 | — | 按需 |

---

## 轨道 C — 自动化路线

> **触发查看条件**：任何 "为什么 / 该不该 / 何时 ship Tier X" 讨论。
> **源自** 2026-05-13 session 9 "TVU 设计规范 自动化 vs 文本规则 评估"。
>
> **核心论点**：当前 ratio 是 "code 端 9 个 L5 gate / mockup 端 0 个 L3+ gate"——直接违反 [`meta-rules.md`](../../meta-rules.md) trigger K 的 "客观可测规则必须 L3+" 自我要求。三 Tier 路线补齐此缺口。

### 已完成

| ID | 内容摘要 | 完成日期 | 耗时估算 | 版本 |
|---|---|---|---|---|
| Tier 1-A Sprint 1 | `axis-implementation-map.md` 拆为 `axis-implementation-map.json` + JSON Schema，保留 narrative MD | 2026-05-14 | ~1 sprint | v0.3.0 prep |
| Tier 1-A Sprint 2 | `prop-aliases.md` 拆为 `prop-aliases.json` + JSON Schema，保留 narrative MD | 2026-05-14 | ~1 sprint | v0.3.0 prep |
| Tier 1-A Sprint 3 | `divergences.md` 拆为 `divergences-decisions.json` + JSON Schema，保留 narrative MD | 2026-05-14 | ~1 sprint | v0.3.0 prep |
| Tier 1-A Sprint 4 | 新增 `audit:translation-completeness` L5 strict gate + allowlist + release pipeline 10th gate | 2026-05-14 | ~1 sprint | v0.3.0 prep |

### Tier 1 — 项目目标对齐的核心自动化

| ID | 内容 | 版本 | 估时 | 落地能力 | unblock |
|---|---|---|---|---|---|
| ~~Tier 1-A~~ ✅ | `translation/*` JSON + JSON Schema + `audit:translation-completeness` L5 gate | v0.3.0 prep | completed 2026-05-14 | 能力 5 溯源 | T4b AI manifest / Phase 6.6/6.7/6.8 / BRIDGE-005 / Tier 1-B / Tier 1-C |
| **Tier 1-B** | `audit:mockup-conformance.mjs`（library key 验证 / 颜色 token bound / 字体 token / M1-M5 命名）| v0.5.0 | ~6-10h | **能力 4（最大缺口）** | mockup-side 第一个 L3+ gate；design-walkthrough skill 客观项分离 |
| **Tier 1-C** | `@nancyzeng0210/eslint-plugin-tvu-design-system` consumer-side lint 包 | v0.6.0 | ~2-3 周 | 能力 1 加固 | 兄弟产品 `extends: ['plugin:tvu-design-system/recommended']` 一行接入 |

### Tier 2 — 降低 AI drift / 半机械化（**顺路做**，不占主线）

| ID | 内容 | 版本（顺路）| 估时 |
|---|---|---|---|
| ~~Tier 2-D~~ ✅ | `scripts/new-backlog.mjs` 自动 ID generator（grep + 1）| v0.4.0 (commit 50ff23d0) | ~20min vs 估 2h |
| ~~Tier 2-E~~ ✅ | `scripts/figma-url-to-canonical.mjs` lookup CLI（替代 AI 读 catalog）| v0.5.0 (2026-05-18) | ~30min vs 估 ~4-6h |
| ~~Tier 2-F~~ ✅ | `scripts/lint-skills.mjs` 验各 skill md 起手依赖文档存在 | v0.5.0 (2026-05-18) | ~30min vs 估 ~3-5h |
| **Tier 2-G** | STATUS.md 一致性 lint（版本号 / active 项数自动核）| v0.6.0 顺路 | ~2-3h |

### Tier 3 — 行业标配但 ROI 边际

| ID | 内容 | 版本 | 估时 |
|---|---|---|---|
| **Tier 3-H** | axe-core a11y audit（docs site pages 跑）| v1.0.0 | ~1 周 |
| **Tier 3-I** | Style Dictionary 迁移（defer 到多平台时）| post-1.0 | — |

### 不应自动化的（**继续保持文本规则**）

- 设计直觉判断（Tooltip vs Popover）— `persona-simulation` skill 合适
- Business persona 模拟（CFO/PM/SRE 视角）— LLM 强项
- Retrospect 触发分级判断（已 codified in STATUS.md）
- 新命名争议拍板 — `divergences.md` SoT + 用户决策
- Meta-rules trigger A/E/H/L（用户疲劳信号 / 不投射时间感 / ambiguity → ask）— AI 自我约束本质

---

## 收尾前同步协议

每次 session wrap-up 前，在本文件补入：

```
| <ID> | <内容摘要（一句话）> | <YYYY-MM-DD> | <~Xh 或 ~Xmin> | <版本（如适用）> |
```

然后 git commit 到 session wrap-up commit 里。

---

## 大图：剩余工作量估算（截至 2026-05-14）

| 版本 | 主要内容 | 估时 | 落地能力 |
|---|---|---|---|
| ~~v0.2.0~~ | Chart + audit:published-vs-code 升 strict + Playwright baseline + husky v1 + **INFRA-F30 idempotent writes** | ✅ shipped 2026-05-13 (~2h) | 能力 1/2 |
| ~~v0.3.0~~ | Tier 1-A 4 sprints + SoT drift cleanup + audit dim 6 + BRIDGE-005 + Phase 6.4 (+ Phase 6.3 resolved) | ✅ shipped 2026-05-14 (~8h 实跑 vs 估 1-2 周) | **能力 5 schema 化 + 能力 2 prop 完整暴露** |
| ~~v0.4.0~~ | Phase 6.6a/6.6b dual-form + Phase 6.7 SoT reconciliation (B path, 0 code change) + Tier 2-D (+ all non-breaking) | ✅ shipped 2026-05-14 (~4h 实跑 vs 估 12-18h) | 能力 1/2 API 统一 + AI from Figma URL 不撞同名异义 |
| ~~v0.5.0~~ ✅ | Phase 6.8 + Tier 2-E/F + CANONICAL-007 + EXTRACT-006 + INFRA-F32（Tier 1-B unblocked → v0.6.0）| shipped 2026-05-18 (~6h 实跑 incl 2 CI hotfix) | 能力 1/2 Button 完整 8-axis + 能力 5 Styles pipeline + 能力 4 unblock |
| **v0.6.0** | **Tier 1-C** ESLint plugin + Tier 1-B (post INFRA-F32)（+ Tier 2-G 顺路）| ~3-4 周 | 能力 1 consumer + 能力 4 mockup audit |
| **v1.0.0** | Tier 3-H axe-core + Phase 8（如 Figma plan 升级）+ API 锁定 | ~2-3 周 | **5 能力全交付** |
| 设计师 owner | BRIDGE-MOCKUP-001/002/003/005 + BRIDGE-DESIGN-REVIEW | 设计师推 | 加固能力 4 mockup-side |
| Deferred | T1c / T4 / Phase 8（需 Figma Org plan）| 等阻塞解 | 能力 3（code → figma）|

**总线性时长（连续做）：~3-4 个月；v0.3 剩余已由 Tier 1-A 完成后收窄到 ~2-3 天。**

**项目目标 5 能力 ship 节点**：
- v0.3.0：能力 5 溯源 schema 化落地
- v0.5.0：能力 4 第一个 L3+ gate 落地（4/5 能力可用）
- v1.0.0：5 能力全交付（能力 3 取决于 Figma plan 升级）

**结论**（截至 2026-05-13 session 9 收尾）：v0.2.0 全部 design system 改动已就位（CANONICAL-011 done + BRIDGE-MOCKUP-004 tracker close + 9 strict audit gates），ready to publish。后续 v0.3 → v1.0 路线按本文件 "Release 排期" 段执行；**任何路线偏离前必须先过本文件 "排期原则" 自检清单**。