# TVU Design System — 平台级分析 + 优化（设计系统即产品主轴）

> **日期**：2026-07-16 · **基线**：磁盘实际状态 @ HEAD `f5a3e6c6`（master）· **方法**：18 个并行分析前沿（工程交付底座 10 + 产品/UX/设计质量 8）+ 每条 P0/P1 对抗验证，105 findings，主线亲验 load-bearing 项。
> **框架修正**：owner 中途纠偏——本平台首先是**产品 UX 设计系统**（供设计/产品/QA/开发四类受众消费、并产出高质量产品设计），工程交付（npm/CI/构建）是**支撑底座**而非 headline。本报告按设计系统即产品主轴组织，工程项按"阻塞哪个受众用这个设计系统"定位。
> **对抗验证有效性**：18 前沿共捕获 6 个证伪/纠正（Tab 无 CE bug、死脚本是有意保留、consumer lint 其实存在、dashboard 非"完全非 consumer"、DG-2 composition thick route 是 owner-gated 非缺陷、DG-3 code-side quality gate 其实存在），说明验证未橡皮图章。

---

## 0. 平台是什么（定位，已验证）

- **本质 = Figma→数据自动同步器 + code 确定性验证器,不是代码生成器**：37 个 `src/canonical/*.vue` 全手写（0 codegen marker），"1:1"靠 930 条 render-verification manifest + 56 个 audit gate 验证，非从 Figma 生成组件代码。唯一 codegen 是 React/CE binding wrapper（从手写 Vue 经 defineCustomElement 派生）。
- **能力成熟度**（STATUS 表已验证不夸大）：① dev npm 🟡 partial（Vue 全通，token TS/JSON 已发，**React 无 npm 路径**）② Figma→code 1:1 ✅（930 manifest）③ code→Figma ⚠️ deferred-bypass ④ 产品设计生成 🟡 gate+AI 辅助 ⑤ 溯源 ✅。
- **核心承诺守住**：库覆盖零遗漏——40 个已发布 Figma 非图标组件集全部有 canonical wrapper，双向 parity（audit:figma-library-vs-canonical exit 0）。

---

## 1. 优化清单（设计系统即产品主轴，按 tracker §排期原则排序）

> 排期权重：项目目标对齐 > 依赖解锁 > 自动化 > 快速独立项；**不按耗时**。每项标注：证据 / 影响受众 / 改动面 / 风险 / 可逆 / 破坏性。
> 执行分类：**[LAND]** 本 session 落地+验证 · **[BACKLOG]** 入 backlog 排期 · **[NEXT]** 下迭代 · **[OWNER]** 需 owner 拍板（破坏性/Figma-first/release）。

### 支柱 A — 组件保真与视觉质量（capability 2/5；设计+QA）

| ID | 发现 | 严重度 | 分类 |
|---|---|---|---|
| FID-01 | render-verification report 8 天 stale（checkedAt 2026-07-08 vs HEAD 07-16 有 5+ 组件 commit）；"A-drift=0" headline 早于最新保真修复 | P1✓ | [BACKLOG]（regen 需 Playwright，随 v0.11.0 release 跑；可先加 staleness guard） |
| FID-03 | 279 条真实 rendered-vs-Figma 值差被降级进非 gating 的 B_RESIDUAL_SCHEMA_GAP；"A-drift=0" 只覆盖 harness 可渲染面，B 桶无 baseline 可无声增长 | P1✓ | [BACKLOG]（给 B 桶加 non-increasing baseline like A） |
| FID-02 | 交互态保真只 6/28 组件有 hover/focus/disabled/error verifier entry（纠正：部分是 stateFromCommonAxes 只认 input 族轴的 taxonomy artifact，但覆盖缺口真实） | P1✓ | [BACKLOG]（manifest generator 扩 stateful 组件态） |
| FID-04 | 深层子节点保真 99.2% 未验（3018 期望节点只比对 25=0.83%）；组合组件内部 chip/dropdown row/table cell/step connector 基本未对 Figma node hex | P1✓ | [BACKLOG]（data-figma-node 标注 + gap 趋势入 STATUS） |
| FID-06 | audit:no-hardcoded-design-tokens 恒 exit 0（report-only），即使在 prepublishOnly 也拦不住；14 个 exact-match 可 tokenize 的 spacing/radius 硬编码残留 | P2 | **[LAND]**（gate on exactMatch>0 + 转 14 处） |
| FID-05 | disabled `opacity:0.4` 在 Switch/Slider/Rating/InputNumber 复现（SelectBox 已修的同款 fabrication），且 4 者无 disabled verifier entry | P2 | [BACKLOG]（**需 live Figma 核 disabled 真值**再修，FIGMA_AS_SOURCE_OF_TRUTH） |

### 支柱 B — 设计 token 系统（capability 1；设计+开发）

| ID | 发现 | 严重度 | 分类 |
|---|---|---|---|
| TOK-01 | **无 motion/animation token 类**；13-14 组件硬编码不一致过渡时长（0.12/0.15/0.2/0.3/0.8s+120ms 混用），成熟设计系统原语完全缺失、无 gate | P1✓ | [BACKLOG]（加 --motion-*/--ease-* + Motion foundation 页；值优先源自 Figma motion） |
| TOK-02/DOCS-6 | **无 Spacing/Layout foundation 文档页**（Foundation 有 color/type/border/effect/icon）；8 步 --sp- scale 无设计师可查参考 | P1✓ | **[LAND]**（加 SpacingPage.vue mirror BorderPage） |
| TOK-04 | 无通用语义 hover/active surface token（只 per-brand-color + 1 个 button surface）；组件 hover 面 ad hoc | P2 | [NEXT] |
| TOK-03 | INFRA-F57 残余：spacing/size 非 Figma-Variable-bound，抽象 scale 层无 live source/gate | P2 | [OWNER]（已知，owner 决策） |
| TOK-05 | token 分发已解决（dist/tokens TS/JSON 已发+exports），但 PROJECT_GOAL L39/L91 仍写"待补" | info | **[LAND]**（doc 修） |

### 支柱 C — 文档站作为多角色产品（4 受众；capability 1/2/4）— 最大产品/UX 缺口

| ID | 发现 | 严重度 | 分类 |
|---|---|---|---|
| DOCS-1/IS-02 | **audit:docs-site RED on master HEAD**：INFRA-F67 commit 8312b03b 删 StepsPage StatusMatrix marker 未更 manifest（仍 present）→ gate exit 1；STATUS wrap-up 声称全绿漏此 | P1✓ | **[LAND · Tier 0 必修]** |
| DOCS-5 | 文档站**无 Getting Started/Installation 页**（P0 开发 onboarding）；Overview landing 是内部 review-methodology 页 | P1✓ | **[LAND]**（加 Getting Started 页） |
| DOCS-2 | **产品受众全无服务**：Use Cases view 0/25 组件页 | P1✓ | [BACKLOG/NEXT]（定义 pattern + populate 高频，大工作量） |
| DOCS-3 | 设计受众薄服务：Design Spec view 1/25（仅 form-item） | P1✓ | [BACKLOG/NEXT]（推广 form-item pattern） |
| DOCS-4/IS-01 | QA 半服务：Status Matrix 8/25（Button/Input/Select/Table/Tabs 全 pending） | P1✓ | [BACKLOG/NEXT]（复用 StatusMatrixGrid） |
| DOCS-7 | topbar 搜索按钮死按钮（无 handler，34 页无搜索） | P2 | **[LAND]**（wire Cmd/K 或 honesty-disable） |
| DOCS-8 | 部分 Element-Plus 结构：per-example preview+copyable-source 仅 3/25 页 | P2 | [NEXT] |

### 支柱 D — 库覆盖 + 图标/affordance（capability 2/5；全受众）

| ID | 发现 | 严重度 | 分类 |
|---|---|---|---|
| ICON-1 | affordance SoT 推荐 `navigation/observe` 解析为**空图标**（registry 无、catalog 无 navigation 分类）→ 按 SoT 契约生成产品代码得 blank icon | P1✓ | **[LAND]**（修 SoT registry_name + 加 resolvability audit） |
| ICON-2 | 两套图标命名并存无互 alias（affordance-style generated 643 vs folder-style catalog 644），DS 自身组件混用 → `<Icon name>` 无确定答案 | P1✓ | [BACKLOG]（选一 canonical + alias 另一，migration） |
| COV-02 | 系统级缺组件（Figma+code 都无）：Drawer/DatePicker/Calendar/Skeleton/Accordion/Card/Avatar/Divider/Tree/Upload/Empty-state/removable Tag | P2 | [OWNER]（Figma-first + 设计 + owner 拍板） |
| COV-01 | 4 个 code-first 组件（Logo/MenuList/UserMenu/PillCounter）无 Figma source、render-gate 未验 | P2 | [BACKLOG]（等设计师发布 Figma） |
| COV-03 | 图标 registry 643 vs 644 published；无 registry↔catalog 对账 audit、registry 无 Figma nodeId | P2 | [NEXT] |
| COV-04 | figma-component-catalog.md header count stale（49+647 vs 40+644）；AI mockup 第一查文档 | P2 | **[LAND]**（重跑 header + doc-sync） |
| ICON-3 | 2 个 chevron affordance（left/right）synonyms+when_to_use 空（644 中唯二） | P2 | **[LAND]**（backfill） |
| ICON-4 | docs Icon 页 count 虚高 ~2x（把 alias 当 icon 数：643+643=1286 vs 真 644） | P2 | **[LAND]**（一个表达式改） |

### 支柱 E — 交互与状态设计 + a11y（QA+设计；capability 1/2/5）

| ID | 发现 | 严重度 | 分类 |
|---|---|---|---|
| a11y-03 | **canonical Select 键盘不可操作**：焦点从不转入 teleported listbox → 整个 ArrowUp/Down/Enter/Escape handler 不可达（WCAG 2.1.1 Level A，非 accepted contrast 债）；真实未接受缺陷 | P1✓ | **[LAND]**（接 focus-transfer；a11y foundation 已有 focus-visible/ARIA/trap，修法 localized） |
| a11y-02 | **无 a11y 回归天花板**：token-contrast report-only（exit 0），ci.yml+publish.yml a11y job 均 continue-on-error → 新回归无声上线；render 有 ratchet，a11y 无 | P1✓ | **[LAND]**（给 token-contrast 加 baseline ratchet + 落 accepted N） |
| IS-03 | 数据组件 runtime 态（empty/loading/error/0-data）未建模未 demo（P2-08 确认开）；Table 只 align/type/columns/data/striped | P1✓ | [BACKLOG/NEXT]（Table/Select 加 runtime prop + demo 段） |
| IS-04 | Status Matrix state-axis vocab 漏 'ux' 轴（Input/Select 的 error/hover/click/focus 所在） | P2 | [NEXT] |
| IS-05 | InputBox feature-icon active 色仅 prop-driven，无 live hover/focus（仅边框响应） | P2 | [NEXT] |

### 支柱 F — 产品设计生成能力（capability 4；产品设计系统心脏）

| ID | 发现 | 严重度 | 分类 |
|---|---|---|---|
| DG-1 | **无 layout 原语**：无 grid/breakpoint/container token，组件 0 @media，无 Layout/Grid/Container/Row/Col/Page 组件 → page-level 设计生成无可组合物 | P1✓ | [BACKLOG/OWNER]（加 layout 原语，Figma-source + owner；capability 4 关键） |
| DG-4 | quality bar 只经手动导出 zip 到 claude.ai，不随 npm 包发 → package-only consumer 无设计质量指引 | P2 | [NEXT]（distilled 规则随包发） |
| DG-2 | composition contract 只编码 containment 不含 layout/spacing 规范 | P1**✗证伪** | 非缺陷（厚路线 owner-gated deferred，INFRA-F60） |
| DG-3 | 生成代码无质量 gate | P1**✗证伪** | 非缺陷（audit:consumer-code/audit-product-code.mjs + eslint-plugin 已存在覆盖 color/spacing/binding） |

### 支柱 G — 治理与执法平权（PROJECT_GOAL 工具解耦支柱；Q1 显式优化范围）

| ID | 发现 | 严重度 | 分类 |
|---|---|---|---|
| gov-mockup-tool-coupled | headline#1：mockup conformance（9 子审）执法绑 Claude Code；CI/publish/pr-checks/prepublishOnly 0 mockup gate；conformance 是 REST/token-based 不能 git-staged 触发；唯一 git 级 teeth=pre-commit handoff-evidence gate（只在 commit 带标记 .md 时） | P1✓ | **[LAND 部分]**（AGENTS 措辞诚实化：trigger 层是 Claude-only + git-teeth 是 handoff-evidence；强化 handoff-evidence 校 touched-node）+ [NEXT] 元层解耦(INFRA-F63) |
| render-drift-window | 像素 render gate 只 publish.yml 跑；master-push ci.yml/pre-push/Gitea PR 都不跑 → 发版间 canonical .vue 几何手改无拦截（窗口=整个发版间隔）；GH runner 已能装 chromium（framework-parity/docs-overflow 已用） | P1✓ | **[LAND]**（ci.yml 加 render-drift-gate job，src/**/*.vue 触发） |
| gov-dual-ci-split-brain | headline#2：阻塞门 GitHub master-push(framework-parity/docs-overflow) vs Gitea PR(typecheck/vitest/prepublishOnly/upstream-gate) 分叉；contributor PR 反而门更少 | P1✓ | **[LAND 部分]**（gate-parity audit + AGENTS 文档说明有意分工）+ [NEXT] mirror render job |
| gov-component-attributes | headline#3 **证伪为缺陷**：audit:component-attributes 是有意保留的手动基线工具（已注释）；**别删** | info✗ | 无需动 |
| ci-gitea-no-visual-gate | Gitea runner unprivileged 跑不了 chromium render gate（capability 2 核心）→ 靠 GitHub mirror job | P2 | [NEXT] |

### 支柱 H — 交付底座：开发消费（capability 1；P0 开发受众）

| ID | 发现 | 严重度 | 分类 |
|---|---|---|---|
| react-npm-blocked | React 无 npm 消费路径：无 ./react export、无 dist/react、**CE register runtime 从不进 published tarball**（build:wc 不在 build、dist-wc 不在 files、无 ./web-components export）；React 只活在内部 react-pilot（private） | P1✓ | [BACKLOG]（Option A additive：build:wc 进 build + dist-wc 进 files + ./web-components export + docs；non-breaking，unblock React 受众） |
| ds-index-barrel | src/index.ts barrel + 顶层 `import './tokens/variables.css'` 副作用 + install() 全注册 → 任何 named import 拉整包，逼 consumer 反抄 src/（MicroApps 实证） | P1✓ **breaking** | [OWNER]（side-effect-free 子入口；changeset + owner 拍板） |
| adx-ce-bridge-one-off | INFRA-F67 CE context bridge 内联 Steps.vue 硬编码 `:scope > tvu-step-item`，非复用 composable；Tab 若需同类修则重复（但 Tab **无**此 bug，已证伪） | P2 | [NEXT]（抽 useCeContextBridge，防未来重复） |
| reexp-orphan-wc-dts | dist/web-components/ 3 个孤儿 .d.ts 无 .js runtime（发类型不发 runtime，误导 TS 用户） | P2 | **[LAND]**（Option A 顺带 或 从 files 排除；本 session 走排除/文档，runtime ship 归 React backlog） |
| adx-changesets-unpublished | 9 pending changesets(5 minor+4 patch,2 BREAKING)→ v0.11.0 owner-gated；pillar① token 出口已 built 未 delivered | P1✓ breaking | [OWNER]（release 决策） |

### 采用策略（块4；分析覆盖,consumer 仓改动不在 Q1 范围）

- tvu-saas-dashboard = 零代码消费（design-only workspace，README 声明）；6 个 DS skill 软链自 2026-05-22 plugin 迁移后 dangling。→ [NEXT] consumer 迁移 tracker。
- MicroApps = 源码耦合非 npm dep；vue-app 钉 ^0.6.1（卡 v0.8.0 breaking 前，落后 4 个 minor）；graphics-app 无 DS dep 靠 symlink 才 build；vue-app/.npmrc 明文 gho_ token（未提交，建议轮换）。根因指回 DS-side `ds-index-barrel`。→ [NEXT] consumer 迁移 tracker + drift radar（配 INFRA-F61）。
- 新产品有 scaffold（setup-tvu-consumer + templates/consumer-product A/B），老产品无 per-product 迁移 tracker。

### 方向（块6，直落 PROJECT_GOAL）
1. **解耦 authoring-time 执法脱离 Claude Code**（INFRA-F63 元层）——最高杠杆，把单工具护栏变组织级。
2. **发 React 消费路径**（./web-components/react export，substrate 已存在）。
3. **老产品迁移 tracker + consumer drift radar**。
4. **render/visual gate 上 Gitea PR 路径**（GitHub mirror job）。
5. **composition 厚路线 + layout 原语**（capability 4 page-level，owner-gated 待 consumer 需求）。

---

## 2. 本 session 执行日志（LAND 项，verification-before-completion）

> 每项：改动 → 实跑 gate 拿真实 stdout 才算完。commit `59dfa521`（master，push 双 remote + git ls-remote 核实 Gitea+GitHub 均 = 59dfa521）。

| # | 项 | 改动 | 验证（真实 stdout） |
|---|---|---|---|
| 1 | **DOCS-1 RED gate 修复** | `figma-sync/audit-docs-site-readiness.mjs`：statusMatrix marker 加"Status Matrix"标题文本识别（与 useCases/designSpec 兄弟约定一致）——修 INFRA-F67 `8312b03b` 删 `<StatusMatrix>` 后 manifest 未更留下的破门。不碰 .vue（无视觉改动，data-view 方案先试后弃）。 | `pnpm audit:docs-site` **EXIT=0，0 errors**（之前 EXIT=1）；已验证不误报（含 "Status Matrix" 文本 7 页全 declared present，无 pending 页含该文本）。 |
| 2 | **render-drift-gate → ci.yml**（关闭漂移窗口） | `.github/workflows/ci.yml`：加 render-gate job（test:render-verification + audit:render-drift-gate）到 master-push，`continue-on-error: true` 非阻塞落地（沿用 framework-parity/docs-overflow 先非阻塞证明 GH-runner 管道再 promote 约定）。 | `pnpm audit:render-drift-gate` **EXIT=0**（A=0≤baseline）；ci.yml 结构解析 6 jobs 含 render-gate，continue-on-error=2。未跑：完整 CI job（需 chromium，push 后验；故非阻塞）。 |
| 3 | **TOK-05** PROJECT_GOAL token 分发 stale 纠正 | `docs/PROJECT_GOAL.md` L39+L91：`TS/JSON token 出口待补`→已发（./tokens DTCG + ./tokens/js resolved TS，2026-07-10 INFRA-F55），并显式标出真实残余（非色 token 未 Figma-Variable-绑定 + DTCG 无 source 标记）。 | `pnpm prepublishOnly` **EXIT=0**（27 gates，含 doc-de-mirror/doc-sync/status-consistency）。 |
| 4 | **COV-04** figma-component-catalog header 计数纠正 | `docs/internal/figma-component-catalog.md` L11+L562：49+647→40+644（同步 components.manifest.json；AI mockup 第一查文档）。 | 同上 prepublishOnly EXIT=0。 |
| 5 | **trans-affordance-path** stale 路径修 | `src/design-system/translation/affordance-layer.md` L29：已删单文件 `affordance-categories.json`→sharded 目录。 | 同上 prepublishOnly EXIT=0。 |

**证伪/未采纳（对抗验证 + 主线判断）**：Tab CE bug（不存在，base TabList 内部 v-for）· 死脚本 audit:component-attributes（有意保留，别删）· DG-2/DG-3（composition thick route owner-gated / code-side gate 已存在）· FID-06 gate-flip（14 转换清单已备，未落地——避免赶工 + 预算留给交付物）· ICON-1（方案歧义 = ICON-2 未决，触发器 L 不自作主张）· a11y-03（盲改违 verification-before-completion，需浏览器键盘验证）。全部带精确修法入 backlog INFRA-F68 / 报告 §1。

**副带发现（收尾告知 owner）**：pre-push 提醒 open PR #9（docs/M21.2）也改过 figma-component-catalog.md → 该 PR 合并时该文件可能冲突（非阻塞，owner 合 PR 时处理）。