# TVU Design System — UX 成熟度评估（Phase 1 · UX 主轴）

> **日期**：2026-07-17 · **性质**：只读诊断（Phase 1，未改任何代码 / Figma / 未 commit，等 owner 逐 Batch ack）
> **权重**：UX 设计系统质量 70% · 设计/开发/AI 消费体验 20% · 工程治理 10%
> **方法**：6 个并行只读 subagent 取 direct 证据（Foundations / Components / Coverage+Patterns / Interaction+Content+A11y / Docs+AI / 6 任务驱动走查）+ 主线交叉核验既有 105（`_reports/2026-07-16-platform-design-system-analysis.md`）+ 62（backlog INFRA-F68）findings。历史结论只作线索，P0/P1 全部本 session 重新 direct 验证。
> **定位**：既有两份评估（07-08 全生命周期、07-16 平台分析）偏工程/治理底座；本评估按 owner 要求回到 **UX 实质**，用 0-5 成熟度 + 任务驱动走查重新组织。findings 与 INFRA-F68 register 交叉引用，不另起竞争 SoT。

---

## 0. 一句话结论

**TVU DS 是一个成熟的「组件保真镜像系统」，但还不是「产品构建系统」。** 用 Atomic Design 的话说：**atom / molecule 层（token、单组件视觉保真）做到 4 分水准，organism / template / page 层（数据网格行为、表单系统、运行态、布局原语、页面 pattern）大面积缺失或仅视觉外壳。** 6 个真实 TVU 产品任务走查结果：**0 个能用 DS 直接建成、3 个部分可建（需大量手工）、3 个基本靠手搓**。

单一系统性根因见 §2。

---

## 1. 成熟度评分表（0-5）

评分口径：0=不存在 · 1=零散靠个人经验 · 2=有基础资产但覆盖/一致性不足 · 3=可用于主要场景有明确缺口 · 4=完整可验证多角色可消费 · 5=可规模化可演进跨工具稳定。

| 维度 | 分数 | 直接证据（file:line） | 主要缺口 | 影响角色 |
|---|---:|---|---|---|
| **Foundations** | **3** | 语义色层 Figma-sourced+gated（`variables.css:1-14,57-90`）；明暗主题全量映射（`:340-453`）；7 Text Style + 8 阶 spacing + 6 阶 radius + 3 层 shadow 齐全；DTCG token 已发（`dist/tokens`） | 无 layout/grid/breakpoint 原语（`src/` 0 @media）；无 motion token（13 文件 6 种硬编码时长）；无 z-index 标度（1000/1100 硬编码）；无 density 标度；i18n 部分/RTL 零 | 设计/开发/AI |
| **Components** | **2.5** | 36 canonical SFC 全 1:1 Figma + `data-figma-*` 溯源；SelectBase/DropDown/PopupBox 有真运行能力 | Table/Form 是纯视觉壳（见 P0）；跨组件 API 不自洽（disabled 5 种写法 / `type` 6 义 / size 大小写分裂）；无全库 empty/loading/error 模型 | 开发/AI/QA |
| **Coverage** | **2** | 原子/分子层覆盖好（input/select/button/tab/step/pagination/modal/toast/badge/pill/progress） | 数据工作流与运行态全缺（Table 静态；无 Form 引擎；缺 Drawer/DatePicker/Skeleton/Empty/Alert/Statistic/Descriptions/Card/Avatar/Upload/Tree） | 全角色 |
| **Patterns** | **1** | 仅 1 处先例：form-item design-spec（1/25） | 无任何页面/流程 pattern 层（列表/详情/表单/搜索筛选/批量/空态/多步/仪表盘）；composition.json 只含 containment 无 layout | 设计/AI/开发 |
| **Interaction** | **3** | 单组件 hover/focus/active/disabled/error 建模一致；PopupBox 是 focus-trap 范例 | 浮层焦点行为四套不统一；motion 不成体系；无 undo；toast 无队列服务 | 全角色 |
| **Content** | **2** | 真实 i18n 层（`src/locale/index.ts` TvuLocale 契约 + provide/inject 合并） | 5 个已建 key 未 wiring（`Pagination:163/228`、`SelectBoxBase.vue:238`、`PopupBox:32-33` 仍硬编码）；无 voice/tone/大小写/标点规范；FormItem 兜底文案 `'Error message'`；无复数/长度/语序处理 | 设计/开发/产品 |
| **Accessibility** | **3** | 强基础：PopupBox trap+return+Escape；Tooltip role+describedby；DropDown 完整键盘+roving+activedescendant；contrast owner-accepted | **3 个 verified WCAG 缺陷**（Select 键盘不可达 2.1.1-A / toast 无 aria-live 4.1.3-AA / FormItem label-error 未关联 1.3.1·3.3.1-A）；无 reduced-motion；无 RTL；a11y 无回归 ratchet | 全角色（尤其 AT 用户） |
| **Documentation** | **2** | 页架构 + manifest 追踪好；开发受众 markdown 齐（`GETTING_STARTED.md`）；QA 半服务（Status Matrix 9/25） | 站内无 Getting Started 页；死搜索按钮；示例不可复制（source 仅 3/25）；产品受众 Use Cases 0/25；设计 Design Spec 1/25；零 Figma 链接 | 产品(几乎零)/设计/QA/开发 |
| **AI Consumption** | **3** | 最强维度：真机读入口 `llms.txt`（随包发）+ composition 契约（`do_not_hand_compose`）+ 930 manifest + DTCG + eslint-plugin + tool-agnostic bundle | 无页面级 recipe/layout 层（只能拼组件不能生成整页）；Button 裸色非语义；llms.txt 反向溯源指针 + composition `_meta.source_refs` **在已发布 npm/bundle 里悬空**（manifest 不在 files[]）；do_not_hand_compose 未 lint | AI/开发 |
| **Governance** | **3** | code 保真侧确定性 gate 近乎完美（930 manifest + render-drift + 56 audit + changesets + Gitea PR CI） | 极不对称：mockup/设计侧 prose:gate≈73:1；执法绑 Claude Code；a11y/token-contrast report-only（continue-on-error 无 ratchet）；SoT drift（DUP-*） | owner/贡献者/跨工具 |

**加权**：UX 层（Foundations/Components/Coverage/Patterns/Interaction/Content/A11y 七维，70%）均值 ≈ **2.4**；消费层（Docs/AI，20%）≈ **2.5**；治理（10%）= 3。**综合 ≈ 2.5 / 5** —— "有扎实基础资产，但产品构建能力与多角色消费存在系统性缺口"。

---

## 2. 单一系统性根因

所有 UX 缺口收敛到一条：

> **DS 的建设契约是"1:1 还原 Figma 已发布 Library"（能力 2），而不是"构建产品页面"（能力 4）。Figma 只建模设计态视觉变体（variant），不建模运行态行为——于是一切运行时能力（数据网格行为、表单校验、empty/loading/error 态、toast 服务、焦点交接、布局、页面 pattern）系统性地落在了 Figma-first scope 之外。**

- 这与 07-08 报告从治理角度得出的"双模态可靠性 / 机制不对称"是同一病根的两面：**有确定性 gate 的轴（code 保真）近乎完美；只有 prose/AI-skill 的轴（设计/产品构建）掉到低分**。
- 引申：**当前"扩增冻结到 v1.0 发布"的策略，与本评估最高 UX 杠杆项（Table/Form/layout/pattern）正面冲突**——在一个还建不出数据表格和表单的系统上锁 v1.0 稳定 API，是需要 owner 显式裁决的战略问题（见 §5 owner 决策 3）。这是本评估最需要 owner 拍板的一条，不替 owner 决定。

---

## 3. Finding 清单

> severity：P0=阻塞核心产品任务 · P1=系统性缺口显著损害体验 · P2=明确缺口非阻塞 · P3=打磨。evidence_level 全部 direct（除 F-AI-4 heuristic）。⚑=本 session 新发现（超出既有 105/62 register）。

### P0（阻塞核心产品任务，2 条）

**UX-P0-1 — Table 是静态视觉壳，无数据网格能力**（Coverage/Components；映射 APID-01）
- evidence: `src/canonical/Table.vue:9-21`（5 props）+ `src/components/Table/Table.vue:15-19`（columns/data/striped，0 emit，data=[] 渲染空表头无 no-data）；composition.json Table 条目 = `"none"`
- ux_impact: 设备列表/成员表/计费行/信号日志——每个 SaaS 表格任务都要各自手搓 sort/filter/select/bulk/pagination/empty/loading → 跨产品跨 AI-run 全发散。走查阻塞 Task 1/5/6。
- systemic_root_cause: Table 按 Figma "cell" 视觉集翻译，从未按运行时 data-grid 建模。
- existing_capability: 条纹表皮 + 列 icon 槽 + 分离的 Pagination。
- gap: sort/filter/行选/展开/固定列/loading/empty/no-results/虚拟滚 + Pagination 集成。
- recommended_direction: Figma-first 定义数据网格交互态 → 分阶段扩 API（sortable/filterable 列、`@sort-change`/`@selection-change`、`row-key`、`loading`/`empty` 槽）；同时发"列表页"pattern。
- figma_first:Y · code:Y · doc:Y · owner:Y · confidence:high

**UX-P0-2 — 无 Form 容器 / 校验引擎**（Coverage/Components；映射 APID-02/FORM-01）
- evidence: 仅 `src/canonical/FormItem.vue:17-36`（label/error/hint/layout，`error` 是静态字符串 prop）；全仓无 `Form.vue`
- ux_impact: 源配置/成员邀请/计费/设备设置全是表单密集——无 rules/validator/联动/提交编排/滚到首错，每产品各自手搓校验 → 错误 UX 不一致。走查阻塞 Task 2/4。
- systemic_root_cause: 同上——校验是行为不是视觉，FormItem 只提取了视觉壳。
- existing_capability: 字段级 `status:Error` + error 文案；字段控件 emit `update:modelValue`。
- gap: Form 容器（`:model`/`:rules`/`validate()`）、校验时机、条件/动态字段、滚到首错、校验方法论文档。
- recommended_direction: 定义校验契约 + Form 容器（逻辑可 code-led，新视觉 Figma-first）+ FORM-01 方法论页。
- figma_first:partial · code:Y · doc:Y · owner:Y · confidence:high

### P1（系统性显著缺口，13 条）

**UX-P1-1 — 无页面组合层：既无 layout 原语也无页面 pattern**（Patterns/Components；DG-1/PAT-01/AIC-01）
- evidence: `src/components` 无 Grid/Container/Row/Col/Page（29 families）；canonical 0 @media；`docs/templates/` 仅 CI yaml；Use Cases 0/25
- ux_impact: 走查 6 任务里 5 个在页面层被阻塞（仪表盘网格/表单布局/列表页壳/向导脚手架全靠各自发明）。
- recommended: (1) Figma-source layout 原语 + breakpoint/grid/container token；(2) 从列表页+表单页起写页面 pattern recipe（机读 + 站内 Use Cases）。figma_first:Y·code:Y·doc:Y·owner:Y·confidence:high

**UX-P1-2 ⚑ — Select 打开后键盘不可操作（WCAG 2.1.1 Level A verified 缺陷）**（Accessibility/Interaction；a11y-03）
- evidence: `SelectBoxBase.vue:166-175`（isOpen watcher 仅定位+监听，无 `.focus()`）；`:259-276`（Teleport 未绑 `@close`，`DropDownListSelect.vue:96` 的 `emit('close')` 是死代码，无焦点返回）；trigger 无 `@keydown`；`DropDownListSelect.vue:113` 是 `role=listbox tabindex=0` 但 teleport 到 body、焦点从不进入 → `:67-99` 的 Arrow/Enter/Escape handler 永不触发；listbox 无 `defineExpose` 故父组件无法调 focus
- ux_impact: 键盘/AT 用户能打开列表但到不了、读不了、选不了任何选项，Escape 也关不掉；核心表单控件无鼠标即不可用。
- existing_capability: DropDown 键盘机器 + PopupBox 现成 focus-in/return 范式可照抄。
- gap: listbox `defineExpose({focus})` + isOpen watcher nextTick focus + 绑 `@close` + 关闭返回 trigger。
- recommended: 移植 PopupBox 焦点模式 + 加浏览器键盘 e2e 作 ratchet。figma_first:N·code:Y(触.vue,行为非视觉)·doc:N·owner:N(已 LAND 批)·confidence:high

**UX-P1-3 ⚑ — Notification / Message toast 对屏幕阅读器完全静默（WCAG 4.1.3 AA verified 缺陷）**（Accessibility）
- evidence: base `Notification.vue`/`Message.vue` 无 `aria-live`/`role=status|alert`（grep 仅 close 按钮的 aria-label）
- ux_impact: 成功/错误/警告反馈（含错误 toast）从不被 AT 播报，非 happy-path 结果对盲用户不可见。
- gap: info/success/warning → `role=status`(polite)；error/dialog → `role=alert`(assertive)。figma_first:N·code:Y·doc:N·owner:N·confidence:high

**UX-P1-4 ⚑ — FormItem label 与 error 未程序化关联（WCAG 1.3.1/3.3.1/4.1.2 Level A verified 缺陷）**（Accessibility）
- evidence: `src/components/FormItem/FormItem.vue:87` `<label>` 无 `for`；slot 控件无 `id`；error `<p>`(`:99-110`) 无 id、无 `aria-describedby`/`aria-errormessage`；控件无 `aria-invalid`（`:194-195` 注释确认 error 只靠红框红字）
- ux_impact: SR 播报控件不带 label，error 未绑字段；字段级 error 是纯色（红框）传达。
- gap: 生成 field id → 接 `label[for]`/`aria-describedby`/`aria-invalid`；字段加 error 图标补非色冗余。figma_first:N·code:Y·doc:N·owner:N(图标或需设计点头)·confidence:high

**UX-P1-5 — 全库运行态（empty/loading/error/no-results/live）未建模**（States/Coverage；IS-03）
- evidence: Table 无 loading/empty prop；Chart 无 loading/empty/error（`Chart.vue:6-20`）；无 Skeleton/Spin/Empty；grep loading 仅 Button+Switch
- ux_impact: 实时监控/信号面板/表格/select 都需 loading+empty，每 consumer 各自发明。走查阻塞 Task 1/3/5/6。
- gap: Table/Chart/Select 加运行态 props+demo；加 Skeleton/Empty/Result；写 STATE-01 页面态指南。figma_first:Y·code:Y·doc:Y·owner:Y·confidence:high

**UX-P1-6 ⚑ — Message 无法渲染业务内容（硬编码 demo 文案，无 text prop/slot）；canonical 还丢了 autoDismissMs**（Components 缺陷）
- evidence: `src/components/Message/Message.vue:52-72`（fallbackMessages 硬编码）+ `:99`（`<p>{{copy}}</p>` 无默认槽）；canonical `Message.vue:8-16` 仅暴露 status/size/closable，未转发 base 的 `autoDismissMs`
- ux_impact: "Encoder-3 信号丢失"这类真实内联提示经公开 API 无法实现 → 逼出 affordance SoT 明令禁止的手搓 icon+text div。走查 Task 3 内容路径实质阻塞。
- gap: base 加 `#default` 槽(+可选 text prop)；canonical 转发槽 + autoDismissMs。figma_first:N·code:Y·doc:Y·owner:N·confidence:high

**UX-P1-7 — 无瞬时反馈服务（toast/notification 队列）+ 无常驻 Alert 横幅**（Components/Patterns；COMP-02）
- evidence: 命令式服务只有 PopupBox（`popupbox-service.ts`）；Message/Notification 无等价 service；`Notification form=slide` 是被动组件无堆叠/定位/自动消失管理；无 Alert 族
- ux_impact: Task 3/5 无法在不手搓队列/定位层的情况下显示 toast 或常驻"设备离线"横幅。
- gap: 把 PopupBox service 范式推广到 message/notify；加 Alert 横幅（Figma-first）。figma_first:partial·code:Y·doc:Y·owner:Y·confidence:high

**UX-P1-8 — 跨组件 API 不自洽（disabled 5 写法 / `type` 6 义 / size 大小写分裂 / 外观 prop 名不一）**（Components；AIC-02 部分 + 07-08 §支柱①）
- evidence: disabled = `enable:yes/no`(CheckBox/Radio/Switch) vs `enable:on/off`(Input/Select) vs `status:disable`(Button 且拼错) vs `state:disabled`(Breadcrumb) vs `disabled:bool`(Slider/Tooltip/InputNumber/Tab)；`type` 承载 severity/表格段/布局变体/字段组合/行为模式/形状 6 种无关义；size 大小写规整了但范围不一(Button `L|M|S|XS` / Input `M|L|XL` / Select `M|L`)且 Badge canonical 完全不暴露 size；外观轴 = Button `fill` 小写 / Badge `fill` 首字母大写 / Input `variant` / Tab `fill` 大小写并收
- ux_impact: consumer/AI 无法预测同类 prop 语义；禁用一个表单行要记 5 种拼法；AI 页面生成无法请求 `primary`/`danger`。
- systemic_root_cause: 每 canonical 忠实镜像各自 Figma variant 属性名，缺一层运行时归一。
- recommended: 加语义 role 别名（primary/danger→color，保留 color 逃生舱）+ 归一 disabled/size 为统一契约（**破坏性 → changeset + owner**）。figma_first:N(纯 code 别名)·code:Y·doc:Y·owner:Y·confidence:high

**UX-P1-9 ⚑ — llms.txt 反向溯源指针 + composition `_meta.source_refs` 在已发布 npm/bundle 里悬空**（AI Consumption；部分超 AIC-03）
- evidence: `llms.txt` "反向溯源"指向 `figma-data/render-verification-manifest.json`（930），但 `package.json` files[] 无 figma-data/，`find dist -name '*render-verification*'` 空，bundle 脚本(`export-claude-design-bundle.mjs:66`)只发 `normalized/variables.json` 且不发 llms.txt；`dist/composition/composition.json` `_meta.source_refs` 全指 repo 路径、均不在 files[]
- ux_impact: 消费**已发布包/bundle** 的 AI 按 llms.txt 的头号能力（反向溯源）与 composition provenance 去找的文件根本不存在——差异化最卖点的能力对外不可交付。
- gap: 要么发瘦身 manifest 进 dist+files[]+bundle，要么改写 llms.txt/_meta 诚实描述 repo-only 并给 npm consumer 替代；加 audit 拦"引用了非 files[] 路径"。figma_first:N·code:Y·doc:Y·owner:Y(发 vs 改写)·confidence:high

**UX-P1-10 — 无页面级 recipe/layout 层：AI 只能拼组件不能生成合规整页**（AI Consumption；AIC-01/06）
- evidence: composition.json 只编码 containment（11/37 有 contains）；无 layout/grid/spacing/page-recipe 字段；佐证 DG-1
- ux_impact: AI 能选对组件、按 contains 嵌套，但无机读 recipe 排整页（仪表盘/表单屏）→ 页面组合不受约束、易幻觉。
- recommended: layout 原语就位后扩 composition schema + 加页面 pattern recipe（owner-gated，依赖 UX-P1-1）。figma_first:Y·code:Y·doc:Y·owner:Y·confidence:high

**UX-P1-11 — AI 赋能割裂：消费 context 工具无关，执法绑 Claude Code**（AI Consumption/Governance；gov-mockup-tool-coupled）
- evidence: 工具无关 = llms.txt + npm subpath exports + claude-design-bundle；但执法 = 13 个 Claude skills + 3 个 `.claude/hooks/*.sh`；CI 无工具无关 mockup gate
- ux_impact: 非 Claude AI 拿到知识契约但拿不到任何护栏/gate → "任何工具可消费"对 context 成立、对合规不成立。
- recommended: 把 authoring-time 执法下沉到 git/CI（INFRA-F63）；llms.txt 也发进 bundle。figma_first:N·code:Y·doc:Y·owner:Y·confidence:high

**UX-P1-12 — 无 motion/ease token 类 + 无 reduced-motion**（Foundations/Interaction/A11y；TOK-01）
- evidence: variables.css 0 motion/ease/duration；13 文件硬编码 6 种时长（0.15×21/120ms/0.8s/0.2s/0.3s/0.12s）；grep prefers-reduced-motion=0
- ux_impact: 交互时序可感知地不一致；前庭敏感用户无降级钩子（含 0.8s 动画）。
- gap: 加 `--motion-*`/`--ease-*`（值优先源自 Figma motion）+ `@media(prefers-reduced-motion)` 归零；重构 13 文件。figma_first:Y·code:Y·doc:Y(MotionPage)·owner:N·confidence:high

**UX-P1-13 — 无 z-index/elevation 标度（浮层碰撞风险）**（Foundations；TKN-02）
- evidence: 硬编码 `SelectBoxBase.vue:521 z:1100` / `Tooltip.vue:81 z:1000` / `PopupBox.vue:272 z:1000` / `UserMenu.vue:193 z:1000`；无 `--z-*`
- ux_impact: TVU 仪表盘同屏叠视频块/侧栏/tooltip/下拉/模态；tooltip 与 modal 同 1000 且无分层契约 → dropdown-in-modal/tooltip-over-popup 碰撞几乎必然且不可调。
- gap: 有序 `--z-dropdown/sticky/modal/tooltip` 标度 + 迁 5 个浮层组件。figma_first:N·code:Y·doc:Y·owner:N·confidence:high

### P2（明确缺口，非阻塞，7 条）

- **UX-P2-1 — 产品受众站内零服务**：Use Cases 0/25、Design Spec 1/25、Status Matrix 9/25（`site-review-manifest.json`）。可用 composition.json 的 `when_to_use` 播种。doc:Y·owner:Y
- **UX-P2-2 — 站内无 Getting Started 页 + 死搜索按钮 + 示例不可复制**：`navigation.ts` 无 install id；landing 是 review-methodology 页；`DocsShell.vue:596-599` 死搜索；source 仅 3/25 且无 copy 按钮（"Ready to copy" 标签虚标）。`docs/GETTING_STARTED.md` 已完整、只是站内没镜像。code:Y·owner:N
- **UX-P2-3 — 无内容设计规范**：无 voice/tone/大小写/标点/microcopy 方法论文档；design-review-queue #4（Notification 问句标点不一致）无治理规则。doc:Y·owner:Y
- **UX-P2-4 — 缺展示型组件**：Card/Statistic/Descriptions/Avatar/DatePicker/removable Tag（走查 Task 5/6/2 手搓）。figma_first:Y·owner:Y
- **UX-P2-5 — Input/Select ~半 API**：无 clearable/loading/maxlength/prefix-suffix；Select 无 filter/remote search/optgroup（`SelectBoxBase.vue:76` editable 仅切边框类）。code:Y·owner:Y
- **UX-P2-6 — 高频组件无 QA 行为参照**：Table/Input/Select/Tabs 的 Status Matrix pending；缺 'ux' 态轴（IS-04）。可复用 StatusMatrixGrid 回填。code:Y·owner:N
- **UX-P2-7 — i18n 深度 + RTL**：数字部分 toLocaleString 但无 locale date/time；RTL 全零（~40 物理 L/R 跨 11 文件）。RTL 优先级取决于是否真有 RTL 市场（无仓库证据）→ owner 定 scope。

### P3（打磨，2 条）

- **UX-P3-1 — 状态色无 intent 命名语义层**：值一致（非 bug）但 meaning 骑在 hue 名上（brand-green 兼 success/preview）；PromptMessage 另有 `--prompt-*` 平行集（第二真源）。可选加 `--status-*` 别名，无强需求不做。
- **UX-P3-2 — composition 契约无 per-entry evidenceLevel**：只有 file-level SoT flag，AI 无法按字段区分 SoT/推断/示例。

### 已复核并驳回的"伪 finding"（对抗验证有效性证据）

| 伪 finding | 驳回理由（direct 核实） |
|---|---|
| Modal 缺失 | `PopupBox.vue:8-34` 是完整语义 Modal（visible/title/width/closable/backdrop/escape/footer + 命令式 service），backlog COMP-02 已改判 |
| 状态色跨组件不一致 | Badge/PillStatus/Message 值一致，非 divergence bug（降为 P3 语义层缺失） |
| Select 完全无键盘 | DropDown 键盘机器完整；真缺陷是 trigger→listbox 焦点交接（精准定位避免误导修法） |
| composition 契约不存在/未发布 | `dist/composition/composition.json`(81KB,37 组件) 真实且 npm-exported，是真差异化 |
| Tooltip 无 a11y | base `Tooltip.vue:41-50` 有 role+describedby+可聚焦锚点 |
| DG-2/DG-3（composition 无 layout / 生成无质量 gate）| 07-16 报告已自证伪（厚路线 owner-gated / audit-product-code + eslint-plugin 已存在），不再重提 |
| 非色 token 未 Figma-Variable-绑定 = Foundations 缺口 | 值已人工对齐 + eslint 强制，属 provenance/治理，非 Foundations 可用性缺口（owner 已知 INFRA-F57） |
| Breadcrumb/Steps/Input/Select 拓扑无 Figma source | `divergences-decisions.json` 已显式登记为合法 code-side 组合层 |

---

## 4. 优化 Batch 路线（按 tracker §排期原则：项目目标对齐 > 依赖解锁 > 自动化 > 快速独立项；**不按耗时**）

> ⚠️ **与当前"扩增冻结到 v1.0 发布"策略的关系已逐 Batch 标注**。Batch A/B/C 多在冻结内或仅需视觉门；Batch D 是冻结的扩增主体，需 owner 显式裁决（见 §5）。每 Batch：对应已验证问题 + UX 目标 + 验收标准 + 受控范围 + 设计/代码/文档验证 + 完成 STOP 等 review。

> **⚑ owner 重定向（Nancy 2026-07-17）**：优化按两步走，**a11y 正确性 bug（Select 不可达等）移出本次评估范围**。
> - **第一步 = 保真**：深化 code↔Figma 确定性验证（DS 的核心强项，但深层节点/交互态大面积未验）→ 见新增 **Batch F**（本次 Priority 1）。
> - **第二步 = 利用现有组件 + 规则做 UX 产品设计**（能力 4）：pattern/recipe 层 + composition 加 layout 元数据 + layout 原语 + populate Use Cases → 见 **Batch D3 + 新增 Batch G**（Priority 2）。
> - 下面 Batch A/B/C/E 降级为"顺路 / 待议"；Batch B（a11y）**本次不做**；Batch D 里只有 D3（layout+pattern）进 Priority 2，D1/D2/D4（Table 运行时/Form 引擎/新组件）是 code 消费层扩增、非本次两步重点（对 mockup/设计生成，忠实静态组件 + 规则已够）。

### Batch F — 保真深化（Priority 1 · 本次第一步 · 深化 DS 核心强项）
- **对应**（re-verify 自 07-16 FID-*）：深层节点仅 0.83% 验证（3018 期望节点只比对 25 个 hex）→ 组合组件内部（chip/dropdown row/table cell/step connector）基本未对 Figma；交互态保真只 6/28 组件有 hover/focus/disabled/error verifier；render-verification report 曾 stale + B_RESIDUAL 285 差值无 baseline 可无声增长；FID-05 disabled `opacity:0.4`（Switch/Slider/Rating/InputNumber）疑为 fabrication（SelectBox 同款已修）**需 live Figma 核**。
- **UX 目标**：把"1:1 还原 Figma"从"顶层可信、内部未验"提升到"组合组件内部逐节点可信"——保真承诺名副其实。
- **验收**：(1) manifest generator 扩 `data-figma-node` 深层 hex 标注+比对，deep-node 覆盖率从 0.83% 阶梯式抬升（入 STATUS 趋势）；(2) 剩余 22 组件补 hover/focus/disabled/error verifier entry；(3) B_RESIDUAL 加 non-increasing baseline ratchet + regen 掉 stale manifest；(4) live Figma 核 4 组件 disabled 真值，按结果修 opacity fabrication。
- **验证**：`pnpm test:render-verification` + `audit:render-drift-gate` 真实 stdout；live Figma extract 对比。
- **范围**：manifest/generator + verifier entries + 视觉门（若触 .vue 修 opacity）。**这是 DS 最该先做、也最擅长的确定性工作。**

### Batch G — 组件 + 规则驱动的 UX 产品设计层（Priority 2 · 本次第二步 · 能力 4）
- **对应**：无页面 pattern 层（UX-P1-1，仅 form-item 1/25）；composition.json 只含 containment 无 layout（UX-P1-10 / F-PAT-2）；无 layout 原语（DG-1）；Use Cases 0/25（UX-P2-1）。
- **UX 目标**：AI/设计师能**用现有组件 + 规则**拼出真实 TVU 产品页/mockup，不必每次从零组合、不必等大批新运行时组件。
- **验收**：(1) 从真实 TVU 产品屏（非 Ant/Material）萃取页面 pattern recipe——列表页/详情页/表单页/仪表盘/设置页，每个编码"用哪些组件 + 布局 + 间距 + 态 + 内容规则"，同时机读（扩 composition schema 加 layout/arrangement 元数据）+ 站内 Use Cases 页；(2) 补 layout 原语（breakpoint/grid/container token + Row/Col/Page，Figma-source）作 pattern 的可组合底座——这是第二步唯一需要的"新积木"。
- **验证**：6 任务走查重跑 verdict 从"0 fully"抬升；AI 拿 pattern 生成整页 mockup 的对照测试。
- **范围**：pattern recipe（doc + JSON）+ layout 原语（Figma-first + owner）+ Use Cases 页。**扩增性质，与当前冻结冲突 → 需 owner 定何时解冻做第二步。**

---

### 以下降级为"顺路 / 待议"（非本次两步重点）

### Batch A — 消费诚实化 + AI 交付闭合（冻结内 · 无 .vue 视觉改动 · 低风险 · 最高性价比）
- **对应**：UX-P1-9（悬空指针）、UX-P2-2（Getting Started 页/死搜索/copy）、UX-P2-6（Status Matrix 回填）
- **UX 目标**：开发落地即能安装/复制/搜索；AI 消费已发布包时溯源指针真能命中；QA 有行为参照。
- **验收**：站内有 Getting Started 页；搜索按钮可用或诚实禁用；≥高频组件有 copy 按钮；`pnpm audit:docs-site` exit 0；新增 audit 拦截"llms.txt/composition 引用非 files[] 路径"→ 现状先转红后修绿；Status Matrix 回填 Table/Input/Select/Tabs。
- **验证**：docs 站截图 + audit stdout + `npm pack` 内容核实指针可达。
- **范围**：docs SFC + package.json files[] / bundle 脚本 + 1 个新 audit。**不碰组件 .vue 视觉。**

### Batch B — a11y 正确性修复（触 .vue，需视觉门 + 浏览器 e2e · 建议不受冻结约束）
- **对应**：UX-P1-2（Select 键盘）、UX-P1-3（toast aria-live）、UX-P1-4（FormItem label-error）、UX-P1-6（Message 内容缺陷）、UX-P1-12 的 reduced-motion 部分
- **UX 目标**：3 个 verified WCAG 缺陷（2×Level A + 1×AA）清零；Message 能显示业务内容；AT 用户可完成键盘/表单/反馈流。
- **理由 / owner 决策点**：这些是**正确性 bug 不是扩增**——一个锁定稳定 API 的 v1.0 不应带 Level-A 键盘失败。建议从冻结豁免。
- **验收**：浏览器键盘 e2e 覆盖 Select open→navigate→select→escape 全程绿；axe 对 3 缺陷 0 violation；Message 传入真实文案渲染；每项走 VISUAL_COMMIT_APPROVED 视觉门。
- **验证**：Playwright 键盘 e2e stdout + axe 报告 + 视觉门截图 + render-verification 不回归。
- **范围**：SelectBoxBase/DropDownListSelect/Notification/Message/FormItem 5 个 .vue（行为为主，视觉最小）。

### Batch C — Foundations 补齐 + 内容/i18n 收口（部分触 .vue CSS，需视觉门）
- **对应**：UX-P1-12（motion token）、UX-P1-13（z-index 标度）、Content UX-P1（5 key wiring）、UX-P2-3（内容规范）
- **UX 目标**：交互时序/浮层分层成体系可查；可本地化字符串真能本地化；有 voice/tone/标点规范。
- **验收**：`--motion-*`/`--ease-*`/`--z-*` token 落 variables.css + MotionPage/SpacingPage 文档页；13 文件迁移 + reduced-motion；5 个 locale key wiring（视觉门）；内容设计页发布并接 `~/.claude/vocabulary.md`。
- **验证**：token gate + 视觉门截图 + i18n 切换 demo。
- **范围**：variables.css + ~13 组件 CSS + docs 页 + 1 内容文档。

### Batch D — 产品构建层（**扩增主体 · 当前冻结 · Figma-first · owner 逐子项拍板**）
> 这是最高 UX 杠杆但与冻结冲突的核心；建议拆子 Batch，每个先 Figma-first 出设计再 code。
- **D1 Table 数据网格**（UX-P0-1）：Figma-first 定义交互态 → 分阶段 sortable/filterable/selection/loading/empty + 列表页 pattern。
- **D2 Form 系统**（UX-P0-2）：校验契约 + Form 容器 + FORM-01 方法论页。
- **D3 layout 原语 + 页面 pattern 层**（UX-P1-1/P1-10）：breakpoint/grid/container token + Row/Col/Page + 列表页/表单页/仪表盘 recipe（机读 + 站内 Use Cases）。
- **D4 运行态组件 + 缺失展示组件**（UX-P1-5/P1-7/P2-4）：Skeleton/Empty/Result/Alert 横幅 + toast 服务 + Card/Statistic/Descriptions/Avatar/DatePicker。
- **UX 目标**：6 任务走查从"0 fully"提升到核心任务可用 DS 直接建成。
- **验收（每子项）**：对应任务走查重跑 verdict ≥ "部分可建无手搓核心行为"；Figma-first 出设计 + render-verification manifest 新增条目 + Status Matrix + Use Case 页。
- **范围**：逐子项受控，每个完成 STOP。

### Batch E — API 归一（破坏性 · changeset + owner · 与 v1.0 稳定承诺强相关）
- **对应**：UX-P1-8（disabled/size/type/variant + 语义 Button role）
- **UX 目标**：跨组件同类 prop 语义可预测；AI 能按语义角色（primary/danger）生成。
- **理由 / owner 决策点**：这是"锁 v1.0 API 之前必须先归一"的破坏性改造——**顺序上应先于 v1.0 稳定承诺**，否则锁进不自洽的 API。
- **验收**：统一 disabled 契约 + 语义 role 别名（保留 color 逃生舱）+ migration guide；changeset BREAKING。
- **范围**：跨组件，破坏性，owner 拍板 + 迁移文档。

### 治理层（10% 权重 · 随上述 Batch 顺带，不单独主线）
- a11y/token-contrast 加 baseline ratchet（去 continue-on-error，同 render-drift 范式）——随 Batch B。
- 执法工具无关化下沉 git/CI（INFRA-F63）——随 Batch A/UX-P1-11。
- SoT drift gate（DUP-*）——已在 INFRA-F68 REWORK-01 推进中，不重复。

---

## 5. 待 owner 拍板的战略决策（本评估最需要 owner 的 3 条）

1. **v1.0 里程碑定义**：当前 v1.0 = "API 锁定 + contrast accept + burn-in waived"，但系统还建不出数据表格/表单/整页。**"稳定 API 承诺"应不应该在缺 Batch D/E 的状态下打？** 或者 v1.0 的语义改为"当前 scope（组件保真镜像）的稳定"、把产品构建层显式列为 v1.x/v2 路线？——这决定 Batch D/E 与 v1.0 的先后。
2. **扩增冻结豁免边界**：Batch B（a11y 正确性 bug）是否从"扩增冻结"豁免？（建议豁免——是 bug 不是 feature。）Batch A/C（诚实化 + Foundations token）是否算冻结内？
3. **Batch D 是否解冻 + 何时起**：产品构建层是最高 UX 杠杆也是最大工作量 + Figma-first 依赖设计师。是否现在解冻 D（至少 D1 Table + D2 Form），还是维持冻结到 v1.0 发布后？

---

## 附录：证据来源与方法边界
- 6 subagent 报告 direct 证据全部 file:line 锚定，主线交叉核验既有 105/62 findings，未发现既有 P0/P1 被夸大或已 stale（除 Status Matrix 8→9/25 已订正）。
- **Figma 侧未 live 核验**：本评估基于 code + 930-manifest（确定性 Figma↔code 映射）+ 既有 accepted-exception 记录。凡标 `figma_first_required:Y` 的修法在实施前需 live Figma 取真值（FIGMA_AS_SOURCE_OF_TRUTH 第 0 步），本 Phase 1 未动 Figma。
- 未跑 build/dev server（避并发 vite 缓存污染）；a11y 用既有 report + 静态 + 逻辑推断，浏览器键盘 e2e 列为 Batch B 验收手段而非本评估已执行项。