docs(规范): 阶段 8.5 六处落点 + 常驻探针计数与代码对齐(12 → 13 道)

批准书 §1 的 DEFERRED 要求「先梳理组织关系、只在可复现缺陷处局部修」,§9 要求
「设计规范更新」,所以规范层落了六处,且**不新建第二份规范**(尺子仍只在 UI规范.md):

`docs/UI规范.md`(+316/−11)
· §1.1.2 全站样式组织现状 + CSS Layer 迁移的 DEFERRED 决策:分层/未分层清点口径、
  当前层叠优先级怎么成立(Tailwind layers → antd → 未分层 .nex-* 覆盖层)、
  `@layer` 声明 0 条 / `!important` 4 条全在 reduced-motion 内、唯一那条压过
  `max-md:hidden` 的未分层规则(=L-1)、以及为什么真要迁就要连 preflight 一起想清楚
· §6.2.1 导航的两个状态与「故意不同的生命周期」(折叠=偏好走 localStorage /
  抽屉=一次性动作走 useState)+ 当前页对辅助技术可见(aria-current)的暴露规则与折叠档边界
· §6.5 「窄屏不许把入口弄丢」后补三通道:Hover / Focus / Touch,只在真的截断时弹,
  触屏档按 `matchMedia('(hover: hover)')` 能力收口(不弹),并登记 N-3 待真机复测
· §13.2.1 窄屏表格两套列档位:`useNarrowTable()` 口径、九张表各自方案表、
  「换列定义不换 DOM」的辅助技术理由、数据完整性对账方法(token 级失踪计数)
· §15 标题与 §15.12/§15.13:十三道常驻探针 + 一道反向验证,新增 semanticcheck 那条判据说明
· §16 第 9 / 第 12 步:改尺子的回归清单补上 `gateprobe` 十四条判据与 semanticcheck

`docs/NEX-对照与例外.md`(+8/−3):§8 响应式那行补本项目走的第四条路(窄档换 columns,
建议 NEX 补进 04 §8.2 → N17);§2/§3/§5 新增一行「验收手段」判定 = COMPLIANT(阶段 8.5
起有机器证据),并记下 NEX 08 只列要求不给证明方式;HEAD↔工作树语义读数改成本轮实测口径。

`AGENTS.md`(+2/−2):两处「12 道常驻探针」→ 13 道。这是 semanticcheck 加进来之后
文档与代码对不上的最后一处,现已全站 grep 无残留旧计数。
main
mula.liu 2026-11-08 14:50:30 +08:00
parent 434370206c
commit 98ea70d74f
3 changed files with 326 additions and 16 deletions

View File

@ -9,7 +9,7 @@
| 层 | 文件 | 负责什么 |
|---|---|---|
| 1 | `docs/UI规范.md` | **项目级 UI/UX 权威**:20 条硬规则 R1–R20、§1–§16 全部尺子与口径、12 道常驻探针、十二步改动流程 |
| 1 | `docs/UI规范.md` | **项目级 UI/UX 权威**:20 条硬规则 R1–R20、§1–§16 全部尺子与口径、13 道常驻探针、十二步改动流程 |
| 2 | `docs/工程规范.md` | 目录职责、脚本准入、代码风格、部署、删除策略、最低验收 |
| 3 | `docs/NEX-对照与例外.md` | NEX 逐条判定(COMPLIANT / ADOPTED / ADAPTED / DEFERRED / NOT APPLICABLE)与**项目级例外登记**;NEX 与本项目冲突时按此文件执行 |
| 4 | `nex.config.yaml` | 项目现状声明(真实尺寸、真实技术栈、真实检查命令)。改了布局尺寸必须同步它 |
@ -41,7 +41,7 @@
- **Empty 三分类**:没数据 / 没匹配 / 引导下一步,文案分开,且能清除筛选恢复默认。
- **反馈四级表面**(R19):`ErrorText`/`LineHint` → `Notice` → `notify*` 吐司 → `confirmAction`。长任务唯一进度源是顶栏「平台动态」(§13.7),页面内不得再放第二个进度条。
- **专业工作区交互**:分镜卡拖拽、时间线、录音、素材灯箱、版本面板的既有操作路径。
- **质量闸门**:12 道常驻探针 + §16 十二步流程。这是 NEX 10「阶段 5 质量门禁」的现成实现,复用而非重造。
- **质量闸门**:13 道常驻探针 + §16 十二步流程。这是 NEX 10「阶段 5 质量门禁」的现成实现,复用而非重造。
- 本项目**没有**文档阅读 / PDF 预览 / AI Chat 工作区,不要为对齐 NEX 引入相应模板、布局或图表依赖。
## 3. 强制规则

View File

@ -15,7 +15,7 @@
- 反向清单:本轮实施中发现**需要 NEX 自己修订或补充**的地方(§5),以及尚未收敛的漂移(§6)。
**不是:**
- ❌ 不是第二份 UI 规范。尺子、口径、20 条硬规则、12 道探针仍然只在 `docs/UI规范.md`,本文件**不重复制定数值**,只做判定与引用。
- ❌ 不是第二份 UI 规范。尺子、口径、20 条硬规则、13 道探针仍然只在 `docs/UI规范.md`,本文件**不重复制定数值**,只做判定与引用。
- ❌ 不是改造任务清单。改造计划见 `reports/NEX设计审计与改造计划-2026-11-07.md`。
- ❌ 不是 changelog 替代品。改了尺寸/机制,先改 `theme/antd.ts` 与 `UI规范.md`,再回来更新本表受影响的那一行。
@ -92,6 +92,7 @@ NEX 与本项目差异用「项目适配」解决,**不得反向修改本项
| §7 面包屑要求 | **ADAPTED**(E5) | `UI规范.md` §0 R18 | 本项目**不用**面包屑:R18 要求「每级身份只说一遍」,门牌 + 侧栏已表达归属;kit 导出的 `Breadcrumb` 实测 0 个页面使用 |
| §8 响应式断点(576/768/992/1200) | COMPLIANT + **ADAPTED**(E9) | `styles/index.css:166-170` | 五档与 antd Grid 全等(含 1600 = antd `xxl`),主阶梯未造私档 |
| §8 「不允许私有断点」 | **ADAPTED**(E9,阶段 7 已收口) | `styles/index.css:171-175`、`UI规范.md` §4「登记断点」 | 原则接受并已收口:页面里 5 个私档(`max-[620px]`×10、`max-[720px]`×2、`max-[1080px]`、`max-[1240px]`、`max-[1400px]`)改名为 `--breakpoint-*` 命名变体,`grep -rn "max-\[" frontend/src` = 0,**px 一字未改**(归到相邻档位会让已验证的看板列数 / 检查器宽度回退,实测见 §4 表)。机制本身已被 NEX 采纳(**N16 已闭**:`04-layout-system.md` §8.1「命名断点登记出口」四条口径),并且四条全部由 `classaudit.mjs` **第 9 闸 BP** 机器对账(裸 `max-[…]`、未登记名、一名多使用者、0 使用者、`UI规范.md` §4 缺行、`visualcheck.py` 的 `BP`/`BPORDER` 失同步、`.css` 里未登记的 `@media` 像素) |
| §8.2 表格类数据的窄屏降级(三种形态之外的第四种:**换列定义**) | **ADOPTED**(阶段 8.5 · 第 3 项批准:逐表方案,不得统一处理) | `components/ui/Table.tsx::useNarrowTable()`(<992)、九张表各自的窄档 `columns`:`Dashboard.tsx:474/532`(①走已验证卡片)、`Dispatch.tsx:256+/475+`(②③)、`Review.tsx:468+`(④)、`Timeline.tsx:801+`(⑤)、`Delivery.tsx:289+/331+/455+/532+`(⑥⑦⑧⑨);口径 `UI规范.md` **§13.2.1** | NEX 04 §8.2 给的三选一(横向滚动 / 堆叠单栏 / 抽屉化)**放不下这一族**:定宽列合计 400~902 的表在 430 会把**片名 / 提示词 / 错误文本**挤成 0 宽——数据不是被滚动藏起来,是根本不渲染。本项目采用的第四条路是「宽档列定义一字不动、窄档换一套 columns,次要列并进主列第 2/3 行 + `title` 存全文」;为什么不用 CSS 显隐(表头与单元格仍在 DOM 里,辅助技术会读到看不见的列)已写在 hook 注释。建议 NEX 把这条补进 §8.2(→ §5 **N17**) |
| §8 工作区 <768 降级 | **ADOPTED**(阶段 8 · 用户批准 N7) | `app/layout/AppSider.tsx`(`AppNavMenu` / `AppSider` / `AppNavDrawer` 三导出)、`app/App.tsx:187`(`narrow`)、`app/layout/AppHeader.tsx`(同一颗按钮换语义) | <768 **不渲染侧栏**,导航只剩顶栏汉堡一个入口,点开的是 kit `Drawer placement="left"`(宽 = `SIDER_WIDTH` 224、`flushBody` 贴边、换页自动关)。改前三条已实测:图标轨 + 汉堡**同屏两个入口**语义重叠、正文白吃 64px(430 档正文 366、顶栏胶囊 `sw203>cw170` 溢出 33px)。菜单本体是**同一份组件**,不是第二套导航。NEX 侧的范式已由 **N7** 落到 `04-layout-system.md` §8.2「导航形态在同一视口内只留一个入口」;≥768 的手工折叠(64 图标轨)保留不动 |
### 2.5 `docs/05-component-system.md` — 组件系统
@ -143,6 +144,7 @@ NEX 与本项目差异用「项目适配」解决,**不得反向修改本项
|---|---|---|---|
| §1 语义化交互(不用 `div + onClick`) | **ADOPTED(原则)**;3 处热区 **本轮阶段 2 修** | `Storyboard.tsx:1915`(`<article onClick>`)、`ui/Rows.tsx:11`(`<div onClick>`)、`AppHeader.tsx:60,70`(`Avatar`/`Text` 当链接)——**行号为阶段 0 记录值**;阶段 2 之后三处已分别变为 `Storyboard.tsx:1915+`(带 `tabIndex`/`onKeyDown`)、`ui/Rows.tsx:27`(`clickable` 分支)、`AppHeader.tsx:70`(已是真 `<Link>`) | 原则完全接受;存量违规仅这 3 处(已核实:`MediaThumb.tsx:106`、`AudioPlay.tsx:68`、`MediaLightbox.tsx:186` 均已带 role/tabIndex/aria-modal,**不是**问题) |
| §2 焦点与键盘 | COMPLIANT(阶段 2 三处热区可键盘化 + **阶段 8 补排序键盘替代 N14**) | `app.css` 全站 `:focus-visible` 兜底;`ui/Table.tsx`、`MediaThumb.tsx`、`AgentConsole.tsx` 键盘处理;`lib/layers.ts::floatingLayerOpen` 分层 Esc;`Storyboard.tsx::moveByKey` + `ShotCard` 的 `aria-keyshortcuts` / `aria-describedby` | 拖拽排序的键盘替代 NEX 原本未覆盖 → **N14**,阶段 2 只做授权内的 3 处热区,**阶段 8 用户批准后落地**(`⌥↑` / `⌥↓`,实测见 `reports/ui_evidence/nex-p8/n14/`),并反向提交给 NEX `08` §2(子仓库提交) |
| §2/§3/§5 的**验收手段**(可访问名称 / 焦点可见 / 状态播报 / 空错载 是否真成立) | **COMPLIANT(阶段 8.5 起有机器证据)**;软档 20 颗/主题待 P2 | `scripts/ui/semanticcheck.py`(第 13 道常驻探针,七条判据 NAME/HOTSPOT/TAB/FOCUS/ARIA/LIVE/STATES,全部走 CDP 的 AX 树与真按键,不读源码字符串)、`UI规范.md` **§15.13**、本轮两处真缺陷修复 `pages/AssetLibrary.tsx:1217/1274/1359`(三颗裸 `Checkbox` 补 `aria-label`)、`styles/app.css:519`(`:has()` 补回被全局复位吃掉的上传按钮焦点环) | NEX 08 只列要求、没给「怎么证明」,此前本项目也只在源码里数 `aria-*` 字符串——实测这种数法**两个真缺陷一个都抓不到**(D-A 旁边有文字、D-B 病灶在 CSS)。HEAD `5a10bfb` 同尺对照:改前硬档 **58 条**(NAME 20 / HOTSPOT 16 / TAB 16 / FOCUS 6,1440 与 430 两档读数相同)→ 工作树改后硬档 0;那 40 条 NAME 软档(20 每主题)不计退出码;剩下的软档 19 类同一根因:`ui/Fields.tsx::Field` 孤立使用 antd `Form.Item`(外层无 `<Form>`)⇒ `<label for>` 为空,属 P2 批量整改,默认不进退出码(`NEX_NAMESTRICT=1` 可升硬) |
| §3 对比度 / 状态不只靠颜色 | COMPLIANT | `UI规范.md` §2.1(标签=点+文字,非仅颜色)、`Status` 文案来自 `lib/format.ts::statusLabel` | 状态一律「点 + 文字」双通道 |
| §4 响应式(明确滚动容器) | COMPLIANT;侧栏 <768 **ADOPTED(阶段 8 · N7,见上 §8 行)** | `UI规范.md` §0 R13/R15、§6 外壳表;`LogBox`/`Drawer` 滚动容器在组件内 | 导航抽屉的滚动与焦点行为走 kit `Drawer`,页面侧没有新滚动容器 |
| §5 内容与长文本(截断须给完整文案) | COMPLIANT(标签一处破口 **本轮阶段 1 修**) | `ui/Table.tsx::Clamp`、`min-w-0` 约定、`app.css:425-430`(`.nex-tag-text` 省略)| 分镜卡状态标签截断后**取不到完整文案**(缺 `title`)→ D1,阶段 1 修并补探针 |
@ -164,7 +166,7 @@ NEX 与本项目差异用「项目适配」解决,**不得反向修改本项
| 阶段 2 建立高价值共享组件 | COMPLIANT | `components/{ui,forms}` 27 文件 | NEX 阶段 2 清单里的组件本项目**已全部存在**(E7:不引入 NEX 包) |
| 阶段 3 选择模块试点 | **ADAPTED** | commit `a73ce50`(`UserAdmin` 按 §13.5 统一口径重做) | 试点已发生并有提交记录,无需另选模块重做 |
| 阶段 4 迁移专业工作区 | **NOT APPLICABLE** | — | NEX 阶段 4 的对象是 Markdown 编辑器与 PDF 预览器;本项目的工作区是画布/时间线,且已在 20 余轮修正中验证 |
| 阶段 5 质量门禁 | COMPLIANT(**超额**) | `UI规范.md` §15(12 道常驻探针 + `gateprobe.py` 反向验证)+ §16(十二步流程) | NEX 建议「将来建 Playwright 截图基线」,本项目已有;复用条款缺失 → **N15** |
| 阶段 5 质量门禁 | COMPLIANT(**超额**) | `UI规范.md` §15(13 道常驻探针 + `gateprobe.py` 反向验证)+ §16(十二步流程) | NEX 建议「将来建 Playwright 截图基线」,本项目已有;复用条款缺失 → **N15** |
| 「不推荐的落地方式」 | **ADOPTED** | `nex.config.yaml` `rules`(禁批量 CSS 重写、禁新增变量命名空间、禁为对齐引入图表库…) | 直接写成项目硬约束 |
### 2.11 `nex.config.yaml`(NEX 样例)与 `templates/`
@ -251,7 +253,7 @@ cd frontend/src && grep -roh -- '--nex-[a-z0-9-]*' . | sort | uniq -c | sort -rn
---
## 5. 反向清单:需要 NEX 修订 / 补充的条款(N1–N16)
## 5. 反向清单:需要 NEX 修订 / 补充的条款(N1–N17)
> 明细见 `reports/NEX设计审计与改造计划-2026-11-07.md` §3.3。此处只记**去向**,避免两处维护正文。
@ -272,6 +274,7 @@ cd frontend/src && grep -roh -- '--nex-[a-z0-9-]*' . | sort | uniq -c | sort -rn
| N13 | 07 无「审批/评审」模式 | `page_patterns.project_specific: [review-approval]` | 已声明 |
| N14 | 08 §1/§2 未覆盖 HTML5 拖拽的键盘替代(分镜排序) | 阶段 8 采纳:分镜卡加 `⌥/Alt + ↑↓`(`Storyboard.tsx::moveByKey`),**不动鼠标拖拽**、不新增卡脚按钮(224 档实测会劈行);快捷键写进 `aria-keyshortcuts` + 一份 `sr-only` 说明 + 使用说明页清单,结果播报走 `notify()`(吐司容器本身是常驻 `aria-live`,见 `UI规范.md` §13.3 ⑤ 第 3 条) | **✅ 已采纳**(阶段 8):NEX `08-accessibility-responsive.md` §2 新增「可排序列表的键盘替代」条款(子仓库提交);本项目侧口径同步 `UI规范.md` §13.3 ⑤ / G3 |
| N16 | 04 §8 只说「不允许私有断点」,没给主阶梯放不下时的登记出口 | 本表 **E9** + `UI规范.md` §4「登记断点」口径(一名一使用者 + 必带视口测量 + 禁止裸 `max-[...]`) | **✅ 已采纳**(阶段 8):NEX `04-layout-system.md` 新增 §8.1 命名断点登记出口 + §8.2 窄屏降级范式;本项目侧同步加 `classaudit.mjs` 第 9 闸 BP 做机器对账(`UI规范.md` §4 复核口径改为「九条判据见 §15.1」) |
| N17 | 04 §8.2 的窄屏降级只有「横向滚动 / 堆叠单栏 / 抽屉化」三选一,缺「定宽列表格换列定义」这一族 | 本表 §2.4 新增行 + `UI规范.md` §13.2.1(九张表方案表 + 992 断点依据);建议 NEX 04 §8.2 补第四种形态:「列定义按档位二套 + 次要列并入主列,禁止用 CSS 显隐制造 AT 读得到的隐形列」 | 待 NEX 侧采纳(阶段 8.5 实测提出) |
| N15 | 10 阶段 5 未承认「项目已有质量门禁」应复用 | 本表 §2.10 判定 + 建议 NEX 增补复用条款 | 已登记 |
---
@ -281,6 +284,7 @@ cd frontend/src && grep -roh -- '--nex-[a-z0-9-]*' . | sort | uniq -c | sort -rn
| # | 漂移 | 现状 | 建议 |
|---|---|---|---|
| ~~R8 文档白名单口径~~ | ✅ **阶段 6 已解决(采纳 ①)** | 文档与探针原本各说各话:`UI规范.md` R8 只放行到 `app/layout/`,第 5 闸实际放行整个 `app/`(`app/App.tsx:21` 裸用 `Button/Layout`、`app/ErrorBoundary.tsx:17` 裸用 `Result/Typography`) | R8 改写为「`theme/` · **`app/` 整个外壳层** · `components/{ui,forms}`」并与 §15.1 同一口径。理由:外壳只此一份、不往 `pages/` 扩散,包一层只会多一个名字;真正要拦的是**页面** import 组件库。② 收紧探针被否——那会把 `App.tsx` 的首屏骨架与错误边界再包一层空壳 |
| **CSS Layer 迁移(`.nex-*` 自绘表面)** | 未分层的 `.nex-*` 自绘皮肤与 `@layer` 壳并存,**形式上**不统一(同族组件有的走 utility、有的走皮肤类) | **DEFERRED(阶段 8.5 · 第 1 项决策)**:全站样式组织现状与层叠优先级设计已梳理并写进 `UI规范.md` **§1.1.2**(五层层叠 `index.css:50-57` + 未分层 `.nex-*` 皮肤 + `@theme` 令牌转发的既有次序),`app.css` 实测 839 行 / 189 条分支。**没有可复现缺陷**,只有「形式上不统一」 | 等出现第三例「utility 点不亮皮肤属性」类的真实冲突再迁;届时按 §1.1.2 记录的组织关系整族搬,不做半迁移(半迁移会让同族组件分居两层) |
| kit 里两个 0 调用但**故意保留**的名字 | `ui/Page.tsx::Breadcrumb`(antd `Breadcrumb` 的薄封装)与 `ui/Controls.tsx`→`ui/Ctlbar.tsx::RadioGroup`(antd `Radio.Group` 封装)当前 0 处调用 | 阶段 6 决策:**不删**。`Breadcrumb` 是 NEX 04 §7 详情/层级导航的唯一落点,删了下次做层级页就得重造;`RadioGroup` 是 R19/§9 里「互斥选项」的唯一名字(分段切换用 `Segmented`,二选一互斥表单用 `RadioGroup`)。复核口径:下一个用到它的页面必须同时删掉本行;若连续两轮仍未被使用,转删除 |
| ~~**D16 kit `Tag` 吞 className**~~(阶段 1 发现) | ✅ **阶段 8 已修**(`components/ui/Status.tsx::Tag` 的 `className` 并进 `cn()` 且放在最后,学同文件 `Badge` 先例) | 原缺陷:形参收了 `className` 但 `cn('nex-tag', …)` 没并进去 → 页面写 `<Tag className=…>` / `<Status className=…>` 全部空转。**修好后查实真实边界与最初推测不同**:① `styles/index.css:55` 的 `@import "./app.css"` **不带 layer**,未层声明高于任何 `@layer`,`.nex-tag.ant-tag` 独占 13 族属性,页面 utility 压不动;② `.ant-tag` 带 `transition: all .2s`,改完 `className` 立刻读 `getComputedStyle` 拿到的是过渡**起始值**——「utility 大面积失效」一半是读数假象(立即读 `ml=0px`,700ms 后 `ml=8px`)。明暗两档实测能力矩阵:`ml-*` `mt-*` `flex-none` `flex-1` `font-mono` `font-bold` `italic` `absolute`+`inset-*` `truncate` **生效**;`mr-*`/`me-*` `hidden`/`max-<bp>:hidden` `bg-*` `text-*` `rounded-*` `p-*` `leading-*` `min-h-*` `gap-*` `max-w-*` `whitespace-*` `overflow-*` **被壳吃掉** | 站点回归口径:`pages/ModelCenter.tsx:973`「默认」只留 `font-bold`(`bg-*`/`text-*`/`border-*` 属皮肤族点不亮,且 §2.1 已废止语义铺底);`pages/project/Review.tsx:363` 由 `className={MUTED_MONO}` 改走 `tone="mono"`;`pages/project/Storyboard.tsx:1983,1985` 撤掉 `<span className="flex-none">` 包装(角标此前被 `overflow-hidden` 裁掉,`vis` False→True 是本轮唯一真实视觉新增);`app/layout/PipelineConsole.tsx:158-161` 的 wrapper **保留**(`max-md:hidden` 属 display 族,壳吃掉了它)。口径 + 200ms 坑写进 `UI规范.md` **§1.1.1**;`scripts/ui/classaudit.mjs` 新增**第 8 闸 TAGSKIN**拦「给 `ui` 的 Tag/Status 传皮肤类」 |
| ~~**D17 窄屏顶栏项目名压到品牌块**~~(阶段 2 复测新发现 · **阶段 8 已修**) | 430 视口下 `.nex-console` 内容比自己的盒子还宽(改前 `scrollWidth` 214 / `clientWidth` 173 → 项目名 `<strong>` 从 x=57 起,压住品牌块 49..81;阶段 1 收口后 203/170,窄了 11px,**同一处问题改前就存在**);阶段 8 改后 `sw == cw`(430 实测 ovf=0,子元素全在盒内) | 不是阶段 1/2 引入的回归;影响 430 一档的顶栏可读性,且让 `elementFromPoint` 类探针在品牌块处拿到错的节点 | 当时不修的理由成立:修法要么缩顶栏内容、要么改窄屏品牌块形态,二者都属「Header 尺寸/移动端导航形态」(阶段 0–7 授权 §八 明确排除)。**阶段 8 用户批准 N7 后随导航形态一起修**:① <768 不再渲染侧栏,正文拿回 64px(430 档 366 → 430);② 项目名在 `<768` 恢复收缩权(`max-md:min-w-0 max-md:flex-[0_1_auto]`),溢出 33px 归零、折出来的是省略号 + tooltip 而不是残字(§15.2 第 7 条)。实测见 `reports/NEX阶段8实施-2026-11-07.md` §3 |
@ -306,6 +310,7 @@ cd frontend/src && grep -roh -- '--nex-[a-z0-9-]*' . | sort | uniq -c | sort -rn
| 2026-11-07 | 阶段 6 拆 kit 与清死代码:`ui/Panel.tsx` 拆出 `ui/State.tsx`(ProgressBar/Empty/SkeletonBlock/Spinner/Notice)与 `ui/Info.tsx`(Value/LineHint/Mono/ExtLink/Info/Count),`ui/Controls.tsx` 拆成 `ui/Ctlbar.tsx` 与 `ui/Fields.tsx` 后删除原文件,`ROW_STEPS` 移进 `grid.tsx`;`components/ui/index.ts` 出口扩到 5 个模块,业务页 0 改动;删 7 个 0 调用导出与 2 个死 hook 文件;R8 承认 `app/` 为外壳层(解本文件 §6 第一条漂移),`UI规范.md`/`工程规范.md`/`app.css`/`App.tsx`/`Status.tsx` 五处实现路径同步 |
| 2026-11-07 | 阶段 5 定反馈预算(N10):`UI规范.md` §13.3 新增 ⑤「一次操作的反馈预算」(实测三页 notify 计数 + 每操作链颗数、两条预算、判据「吐司说成了,页面说成什么样」);`pages/ModelCenter.tsx` 的 `patchRow` 补一颗结果吐司(启用/停用/设为默认此前零反馈),`save`/`remove` 的页头 `Notice` 改 `notify({title,desc})` 并删除 `notice` state(页内 `Notice` 只留 `error` 与故障注入两处持续状态);`pages/project/Library.tsx` 5 处裸 `confirm()` → `await confirmAction({title,desc,tone,confirmIcon})`,`onRecord` / `recordGenerationReference` 经新增的 `speak`/`joinLines` 合成一颗;`lib/versions.ts::keepOrRestoreCurrent` 新增第三形参 `sink`(默认 `notify`,平台资产库两个调用点未改);`scripts/ui/classaudit.mjs` 第 6 闸正则从只匹配 `window.confirm(` 放宽为 `/(?<![\w.$])(?:window\.)?(?:confirm|alert)\s*\(/` 并写入十一例自查(阶段 5 曾把可选前缀写在 lookbehind 之前,导致 `window.confirm(` 反向漏检);`pages/Dashboard.tsx` 统计卡 `steps={[{at:'lg',cols:2}]}` 只改 xs 一档 | Codex(阶段 5) |
| 2026-11-07 | 阶段 3 建立层级表:新增 `lib/layers.ts::LAYER`(header 20 / toolbar 40 / scrim 55 / sheet 60 / antd 1000 / preview 1020 / recorder 1030 / confirm 1190 / toast 1200),7 处浮层改为引用 `LAYER.*`(AppHeader 顶栏 / Page 粘性工具条 / Overlay 遮罩 / Storyboard 检查器 / MediaLightbox 灯箱 / RecordAudio 录音面板 / Confirm 确认框,`Overlay::Modal` 并新增可选 `zIndex` 形参),另有 2 条必须贴在 antd 节点上的 CSS 值(`app.css` 1100 / 1200)保持原数并加注释指回层级表;修掉两条**实测存在**的遮挡(抽屉里点开灯箱看不见、声线抽屉里录音面板点不着),并给确认框第一次显式层级以免灯箱抬升后压不住;`UI规范.md` §10 重写(层级表 + 修正过时的「挂载点」口径 + 两条「不进表」例外) | Codex(阶段 3) |
| 2026-11-08 | 阶段 8.5 响应式 UX 与质量收口(七项):**①** CSS Layer 判 DEFERRED,只写 §1.1.2 的组织现状,不动代码;**②** 顶栏项目名补键盘通道(`app/layout/PipelineConsole.tsx` 受控 `Tooltip` + `:focus-visible`,改前缺的不是省略号而是「Tab 停上去读不到全名」);**③** 窄屏表格**九张**逐表改造(`components/ui/Table.tsx::useNarrowTable` + 各页窄档 `columns`,`tableaudit` 四档 EXIT=6 → 0,宽档 1440 输出逐字节相同);**④** 新增第 13 道常驻探针 `scripts/ui/semanticcheck.py`(语义与行为,七条判据)并修掉它查出的两处真缺陷(`AssetLibrary` 三颗裸 `Checkbox`、`app.css:519` 上传按钮焦点环),`gateprobe.py` 同步加 1 缺陷 + 2 合法夹具;**⑤** 导航两态判「保持分离」,理由写进 `UI规范.md` **§6.2.1**(`nex.sider.collapsed` 持久化 / `navOpen` 不持久化,两者是宽窄与开合两根正交轴);**⑥** UI chunk 只做分析与三变体实量,**业务代码零改动**(kit 深引 +0.02kB、Dashboard 深引字节完全相同 ⇒ rolldown 对 `export *` 桶引零成本;改 lazy 才省 2.3% 但要动已验证首屏);**⑦** N14 真读屏仍 **MANUAL QA REQUIRED**(见 §6 与 `UI规范.md` §G3)。NEX 侧本轮**未**改规范正文,新增待采纳项 **N17**(窄屏表格换列定义)登记在本表 §5 | Codex(阶段 8.5) |
| 2026-11-07 | 阶段 8·N16 断点治理:`classaudit.mjs` 新增**第 9 闸 BP**——以 `styles/index.css` 的 `--breakpoint-*` 为唯一真相,向「页面用词 / `UI规范.md` §4 登记表 / `visualcheck.py` 的 `BP`·`BPORDER` / `.css` 里的 `@media` 像素」四处对账(五条判据,含「登记尺子必须只有一个使用者」「探针表缺名会静默跳过断言」两条隐性失配);闸本身按 §15.1 口径反证过 10 例(`reports/ui_evidence/nex-p8/n16/scripts/gate_bp_proof.py`:写坏→红且点名→还原复绿);NEX 侧 `04-layout-system.md` 新增 §8.1 命名断点登记出口 / §8.2 专业工作区窄屏降级范式(子仓库提交,见实施报告 §2);`UI规范.md` §4 复核口径从「grep 必须为 0」改为机器闸、§15.1 闸表 8→9;`nex.config.yaml` 补 `breakpoints_registered` 与 9 道子闸注释 | Codex(阶段 8·N16) |
| 2026-11-07 | 阶段 8·D16 修 `Tag` 吞 className:`components/ui/Status.tsx` 把 `className` 并进 `cn()` 末位(此前 10 处站点空转);顺带查实「utility 大面积失效」的两半真相——`index.css:55` 未层 `@import` 使 `.nex-tag.ant-tag` 独占 13 族属性 + `.ant-tag` 的 `transition: all .2s` 让改类后首帧读到起始值;`ModelCenter.tsx:973` 皮肤类改 `font-bold`、`Review.tsx:363` 改 `tone="mono"`、`Storyboard.tsx` 撤 flex-none wrapper、`PipelineConsole.tsx` wrapper 保留并注明只服务 display 族;`UI规范.md` 新增 §1.1.1(能力矩阵 + 200ms 坑);`classaudit.mjs` 新增第 8 闸 TAGSKIN;932 颗标签逐站点 diff,46 处差异全落在预期站点 | Codex(阶段 8·D16) |
| 2026-11-07 | 阶段 8·N14 分镜排序的键盘替代:`pages/project/Storyboard.tsx` 的 `move()` 改为回传`Promise<boolean>`(越界 `false`,三个 `void move(...)` 调用点一字未改),新增 `moveByKey()` —— 越界时报「已经在第 N 位,无法继续前移/后移」、成功时报「已后移到第 M 位」并把焦点还给同一张卡(`refocusShotCard()`:rAF 最多 8 帧找回 `[data-shot-card]`,拿不到就不抢焦点,否则第二下按键没有落点);`ShotCard` 的 `onKeyDown` 先接 `Alt+↑/↓`(`preventDefault + stopPropagation`,卡片就在 window 那条「方向键切镜」监听的冒泡路径上,不拦会一次按键既移镜又切镜),window 侧同步加 `if (ev.altKey && Arrow) return` 兜底;可达性用 `aria-keyshortcuts="Alt+ArrowUp Alt+ArrowDown"` + 全站一份 `sr-only` 说明(`aria-describedby` 指过去),**不新增卡脚按钮**(224 档实测会劈行);`pages/Help.tsx` 快捷键清单与分镜步骤同步 `⌥↑` / `⌥↓`。口径落 `UI规范.md` §13.3 ⑤ 第 3 条(键盘路径必须播报、拖拽路径不播报的不对称)与 G3(热区不是按钮时快捷键挂在哪);NEX 侧 `08-accessibility-responsive.md` §2 新增「可排序列表必须提供键盘移动方式」(子仓库提交)。专项探针 `reports/ui_evidence/nex-p8/n14/scripts/sortcheck.py`:Light/Dark 各跑「顺序变了 / 焦点没丢 / 有播报 / 边界会说话 / 不 Alt 的方向键行为不变 / Enter 仍打开检查器」,PASS 0 条;对 HEAD 反证 FAIL 14 条 | Codex(阶段 8·N14) |

View File

@ -38,13 +38,13 @@
| R9 | **不写私档数字**:`bg-[#...]`、`text-[13px]`、`rounded-[7px]`、`leading-[1.9]`、`w-[3px]`、自造断点一律禁止(视口尺子只准用 §4 那张表里的名字,`max-[1240px]` 这种裸数字算私档;确有尺子放不下时先按 §4 登记再加);颜色/字号/圆角/间距只准用转发到 `--ant-*` 的语义名,或者 Tailwind 的 4px 栅格(`gap-3` = 12 = `marginSM`)。响应式宽度 `w-[min(...)]` 与贴在内容上的尺寸 prop 例外 | 任意值是「第二把尺子」的入口,一旦允许就会长回手写规范 |
| R10 | **ref 契约**:kit 一律 `forwardRef`,ref 只交 DOM 节点,组件库句柄不外泄(折法唯一,见 `lib/ref.ts`) | `ref?:` 写在 props 里 tsc 照过、运行时只 warn,功能静默没了 |
| R11 | **图标只用 `@ant-design/icons`,且只在 `components/icons/index.ts` 一处 import**。自绘 `Icon.tsx`/`glyphs.ts` 已删,目录只剩这张语义登记表;页面写的是语义名(`IconGrid`/`IconWarn`),字形名只出现在表里。纯图标按钮必须带 `title` + `aria-label`(`<IconButton>` 把 label 同时喂给两者) | 收口前有 32 个文件散着 import 73 只图标,「同一个意思该长什么样」全站无一处可查;40 个手绘 glyph 更是同一只「会亮的方块」长出五种长相的根源 |
| R12 | **改了尺子就全量回归**:动过 `theme/antd.ts`、`styles/index.css`、`styles/app.css` 任一文件 → §15 十一道探针全量重跑,且**窄屏 430/576 也在回归宽度里** | 只在窄屏生效的规则必须有截图证据,不能靠推理 |
| R12 | **改了尺子就全量回归**:动过 `theme/antd.ts`、`styles/index.css`、`styles/app.css` 任一文件 → §15 十三道探针全量重跑,且**窄屏 430/576 也在回归宽度里** | 只在窄屏生效的规则必须有截图证据,不能靠推理 |
| R13 | **布局 utility 压在 antd 组件根节点上,依赖三处层叠声明**:`app/providers.tsx` 的 `<StyleProvider layer>`;`styles/index.css` 里拆开 import **之前**的 `@layer theme, base, components, antd, utilities;`;以及 `@import "tailwindcss/preflight.css" layer(antd)`——**preflight 必须与 antd 同层**,写回 `layer(base)` 会被 antd 的 prepend 反超、全站复位反吃组件样式。两者任一被摘掉,`max-md:hidden` 这类 utility 会**静默失效**(tsc / build 全绿,只有浏览器能看出来)(详见 §1.1) | Tailwind v4 把 utility 放进 `@layer`,而 antd 默认注入的 CSS 未分层;按 CSS 层叠规则「未分层永远赢过分层」, antd 会把我们的布局 utility 全量盖掉 |
| R14 | **按钮与浮层底部只用 antd 原生词汇**:`type` / `danger` / `size` / `icon` / `shape` / `loading`,自造 `variant` 方言已废;浮层底部一律「辅助 → 取消 → 主行动」右对齐、整条 md 档、最多一颗 `type="primary"`(详见 §5.1、§10)。裸 `<button>` 只许出现在 §5.2 的自定义表面族白名单里 | 219 处 `variant=` 是靠 codemod 迁完的:只要方言还在,下一个页面就会接着发明名字,主题与档位又收不口 |
| R15 | **按钮一律是图标按钮**:凡有动作语义的按钮都写 `icon={<IconXxx />}`,`FilePick` / `RecordAudio` 这两个自带触发元素的封装也走 `icon` 槽;一个意思全站只许一只图形(§5.1.1) | 一排纯文字按钮要逐个读完才知道哪颗是什么,图标剪影一眼分得开;用户截图原话「按钮都要使用图标按钮」 |
| R16 | **信息块三件套各有唯一写法**(§13.1):① **统计**=`Stat`/`StatGrid`,卡面就是 antd Card 的 `colorBgContainer`(**纯色、无底纹、无渐变、无水印**),识别度全部交给数字左侧那只 32px 圆角色块(底色 = 本卡语义色 `color-mix` 12%,深色档 18%;图形 = 同一条语义色),页面不再手涂 `bg-[#...]`;② **只读回显**=`Info`(antd `Descriptions`),「灰盒 + label 在上」和用 `Input disabled` 装只读值一律废止,只读 `Tag` 不许描边,统计用途的计数不许用无底纹灰胶囊;③ **语义提示**=`Notice`(自绘语义块,读 ① ② 同一把 `BLOCK_TONE` 底纹尺),页面不再自拼 `border + warning-bg` 当告警 | 白底数字块与卡片同色,扫不出「这是结论」还是「这是容器」;灰盒回显和旁边的输入框长得一样,用户去找可点的框,框里却没有可改的东西;底纹与告警底色都是 antd 自己的 fill / 语义色层,明暗两档跟主题走,不需要再养一套私有皮肤 |
| R17 | **表格行不许被子元素撑高**(§13.2):① 先做列宽预算——`Table` 默认 `minWidth={false}`,定宽列合计必须回到容器里,长文列**不写 `width`** 吃掉剩余宽度且扣掉内边距后 ≥ 200px;② 单元格里的长文案一律 `<Clamp>` 封顶(标题 1 行 / 说明与报错 2 行)并把全文挂原生 `title`,表格里的 `ErrorText` 同样必须给 `lines`;③ 动作列按「`颗数×32 + (颗数−1)×6 + 16`」算宽、图标化一行放完;④ 格子里并排的内容不许越出
自己的盒子、不许互相压叠(> 2px 立案)。一个格子的预算是**正文两行 + 次要元信息一行 ≈ 84px**,超了就是返工。**这条由 `scripts/ui/tableaudit.py` 常驻量,不靠自觉** | 「列宽」与「文案长度」两头堵,只调列宽永远调不完:审核留痕一句质检长文把行顶到 255px、生成记录一条 prompt 顶到 227px,一屏只剩三条记录,表格退化成段落。用户第 28 轮原话「表格行不要被子元素撑高(长文折 8 行 = 设计失败)」 |
自己的盒子、不许互相压叠(> 2px 立案)。一个格子的预算是**正文两行 + 次要元信息一行 ≈ 84px**,超了就是返工。**窄屏(`<992`)不许沿用 1440 那份列宽预算:用 `useNarrowTable()` 换一套精简列,次要列并进主列、数据不失踪,禁止 CSS 显隐维护两份 DOM(§13.2.1)**。**这条由 `scripts/ui/tableaudit.py` 常驻量,不靠自觉** | 「列宽」与「文案长度」两头堵,只调列宽永远调不完:审核留痕一句质检长文把行顶到 255px、生成记录一条 prompt 顶到 227px,一屏只剩三条记录,表格退化成段落。用户第 28 轮原话「表格行不要被子元素撑高(长文折 8 行 = 设计失败)」 |
| R18 | **每一级的身份与动作只在该级说一遍**(§6.5 四级层次):项目名 / 状态 / 进度 / 归档 / 删除只属于**项目层**(顶栏那颗流程控制台胶囊是唯一入口,点开右侧「项目概况」抽屉);「这是哪一站 + 这一站的主操作」只属于**环节层**(`PageHead`:一张带底纹描边的独立门牌卡);数据与筛选只属于**内容层**(`Panel`)。工作台外壳 `pages/ProjectDetail.tsx` 除兜底(载入 / 未找到 / 报错)外**不渲染任何可见块** | 用户第 11 轮原话「要进一步把各级的信息归拢并提供交互的层次清晰」:当时同一条项目身份在顶栏、外壳面包屑、概览页页头各说一遍,而**项目级**的「归档」坐在**环节级**页头上 |
| R19 | **反馈只有四级表面,各有唯一实现**(§13.3):行内报错=`ErrorText` / `LineHint`(贴在它说明的那个控件下方)、页面级说明=`Notice`(自绘语义块,与 §13.1 的 `<Block>` 同一把底纹尺,带 `action` 善后位)、操作结果=`notify*`(自绘吐司:右下角堆叠、最多 5 颗、同句去重成 `×N`、悬停 / 聚焦暂停倒计时)、破坏性确认=`confirmAction`(自绘确认框,`Promise<boolean>`)。**`window.confirm` / `window.alert` / `Modal.confirm` / antd `message` / `notification` / 裸 `<Alert>` 全站清零**,也不许再给它们打样式补丁。**这条由 `classaudit.mjs` 第 6 道闸逐行扫(§15.1)+ `feedbackcheck.py` 运行时复验(§15.9)** | 用户原话「整体修改系统中所有提示窗、完成后的反馈 tips 等。不要使用默认组件」:`window.confirm` 弹的是**操作系统**的窗口——主题、字号、按钮、语言全不由站内决定,还把脚本同步冻住;antd `message` 是全站唯一没有描边 / 色块 / 底纹的纯黑药丸,长报错读不完、悬停不暂停、连点时叠成一串一模一样的胶囊,还正好压住门牌与刚点的那颗主按钮 |
| R20 | **标题前面不挂图形**(§6.5):门牌 `PageHead` 与卡头(`PanelHead` / `Toolbar` 的标题槽)写的就是文字——`PageHead` 连 `icon` 这个 prop 都删了,`.nex-pagehead-mark` 类名一并作废;图形只许出现在**按钮里**(R15)与**信息块的色块档**(R16 统计卡 32px 色块、吐司与确认框的语义块)。图形退出之后标题左缘 = 卡内边距 = 下面每张卡正文的左缘。**这条由 `classaudit.mjs` 第 7 道闸扫**(`<PageHead … icon=>` / `.nex-pagehead-mark` 复活 / 登录页以外的 `<Mark>`) | 用户原话「不要图标」:那颗 32×32 主色方块和左栏高亮项说的是同一句话(同一信息配第二个视觉锚点,R18),还顺带把标题右推 42px——门牌与正文永远对不上同一条竖线,这件事在有图标之前做不到 |
@ -169,6 +169,58 @@ CSS 层叠规则是「未分层样式永远赢过分层样式,与选择器特
**中文按钮不插空格**:`<ConfigProvider button={{ autoInsertSpace: false }}>`;
语言包 `zh_CN` + `dayjs/locale/zh-cn` 在 providers 里配好。
#### 1.1.2 全站样式组织现状与「CSS Layer 迁移」的 DEFERRED 决策(2026-11-08 · NEX 阶段 8.5)
审计报告把「`.nex-*` 自绘表面没有进 CSS Layer」记成一条形式问题(P2)。**决策:DEFERRED**,
本节把它换来换去的账先摊平:谁在哪一层、谁赢谁、什么条件下才重开这一项。
**文件只有两个**(`grep` 可验:`frontend/src/**/*.css` 命中 `index.css` 与 `app.css`):
| 文件 | 行数 | 分层状态 | 内容 |
|---|---|---|---|
| `styles/index.css` | 220 | 声明层序 + 分层 import | `@layer theme, base, components, antd, utilities`、三条 `@import … layer(…)`、`@theme`(全部转发 `--ant-*`) |
| `styles/app.css` | 839 | **整文件未分层**(`@import "./app.css"` 不带 `layer`) | 141 条规则 / **199** 条选择器分支:132 条含 `.nex-*`(其中 4 条是 `.ant-btn:has(> .nex-…)` 这类给 antd 收口的)、40 条纯 `.ant-*` 覆写、18 条元素级复位与 utility、9 条全局伪类(`:focus-visible` 等)。**口径可复跑**:剥 `/* */` → 按花括号配对逐条取选择器 → 逗号拆分支;`.nex-` 与 `.ant-` 同时命中只计 `.nex-` 一次。全量输出与改前同口径对照见 `reports/ui_evidence/nex-p8f/01-css-layer/census.txt` |
`app.css` 里 `@layer` 出现 **0** 次;`!important` 出现 **4** 次,全部在
`@media (prefers-reduced-motion: reduce)` 那段标准动效复位里(52–55 行),不是拿来打架的;
`@keyframes` 2 组、`@media` 1 处(就是那条动效复位)。也就是说:**分层这件事在 antd / preflight / utility 三方之间已经打完并写死
(§1.1),第四方 `.nex-*` 皮肤是有意留在层外的**(§1.1.1)。
**这一层本阶段只加过一条**(阶段 8.5 · §15.13 的 D-B):`app.css:519`
`.ant-btn:has(> .nex-file-input:focus-visible) { outline: 2px solid var(--ant-color-primary) }`——
透明 `<input type=file>` 的焦点环被 46 行那条 `:where(input,…)` 复位吃掉,环改画在看得见的按钮上。
文件 828→839 行、规则 140→141、分支 198→199(新增的只有这一条 antd 收口,`.nex-*` 自绘表面一族一字未增),**未分层不是遗漏**,它留的就是这种
「token 与组件主题都管不到、但确实错了」的局部收口;这条恰好是它的用途,不是形式漂移。
**当前优先级阶梯**(低 → 高,同级内比特异性与先后):
```
layer(theme) ── Tailwind 主题变量(@theme 里全部 = --ant-*)
layer(antd) ── preflight 复位 + antd 组件运行时样式(同层,§1.1 第 3 条)
layer(utilities) ── Tailwind 布局 utility(max-md:hidden 这类)
未分层 ── app.css 的 .nex-* 皮肤与 .ant-* 收口 ← 设计上的天花板
行内 style ── 组件 props 直接写死(少数:Progress 条色、MediaThumb 尺寸)
```
**为什么 DEFERRED**:
1. 未分层不是遗漏,是 §1.1.1 那条边界的前提:`.nex-tag` 必须压得住 antd 的默认皮肤,
也要压得住页面上的 utility。**把它搬进 `@layer components`(在 `utilities` 之前),
这 132 条皮肤会同时降到 utility 之下**——页面写 `text-xs`、`bg-*`、`rounded-*`
反过来吃掉皮肤,等价于 §1.1 那次「全局层叠反转」的镜像,必须重走 R12 全量截图回归。
2. 收益只有形式:审计报告里这一项没有附带任何**可复现**的视觉缺陷,
现状的失败模式是「utility 静默不生效」,而它已经被 D16 逐属性量清、
由 `classaudit` 第 8 闸(TAGSKIN)按禁写词拦着(§1.1.1 的表)。
3. 风险不对称:迁移要么改 119 条选择器要么改层序,两者都要全站回归;
而不迁移的代价只是「新同学得先读 §1.1.1 才知道哪些 utility 点不亮」。
**重开条件**(写死,避免下次又当形式问题提):出现一条**可复现**的缺陷,
且缺陷根因是「页面 utility 与 `.nex-*` 皮肤在同一属性上互相打架」——
不是「某条 utility 没生效」(那是禁写词,按 §1.1.1 的表处理),而是「业务确实需要
在这一处改皮肤,却必须靠外层 wrapper 绕」。到那一步按**组件族局部入层**
(一次一个 `.nex-*` 家族,入层同 PR 补一条 visualcheck 断言),**不整体重写**。
---
## 2. 颜色:只有 antd 语义色,没有第二个调色板
@ -444,6 +496,14 @@ antd 三档(24/32/40)套不进去的,才是自定义表面,允许裸元
图标不写尺寸、不写颜色,继承按钮的 `font-size` / `color`。
- 这条有闸:`/tmp` 侧的 inv 探针列出「Button 无 icon」清单,
剩下的每一处都必须是**刻意**的文字链(`TextLink`)或分段开关项。
- **在册待办(阶段 8.5 真机读屏发现 · AT-1)**:图标自己会报名字。`@ant-design/icons`
每个图标渲染成 `<span role=img aria-label=字形名>`,于是 VoiceOver 读出来的是
「upload 导入脚本」「down 导出」「appstore 看板」「ordered-list 分镜表」「book 手册」——
按钮文字已经在外面,等于**同一个控件被报两遍**,前半截还是英文码。
控件已有可读名称时图标是纯装饰,正解是 `aria-hidden`(`components/icons/index.ts` 一处收口)。
这条会同时改动 14 条路由的可读名称,**必须单独一轮 + 单独 AT 复测**,
不许塞进任何视觉轮次里顺手做。取证:
`reports/ui_evidence/nex-p8f/07-screen-reader/voiceover-announcements-2026-11-08.txt`。
### 5.1.2 关键动作才有重点色
@ -528,6 +588,36 @@ items = [
`button.autoInsertSpace`、`zh_CN`)。页面不许再套第二层 `ConfigProvider`,
需要降档用 `<Dense>`。
#### 6.2.1 导航有两个状态,且**故意**两种生命周期(2026-11-08 · NEX 阶段 8.5)
审计把「侧栏折叠与移动端抽屉各存各的」记成一条状态重复。**决策:保持分离,不合并成
一个 Boolean**,因为这两个状态回答的不是同一个问题:
| 状态 | 存在哪 | 回答什么 | 为什么这样活 | 代码 |
|---|---|---|---|---|
| `collapsed` | `useLocalStorage('nex.sider.collapsed', false)` | **桌面**宽栏还是 64px 窄栏(`SIDER_COLLAPSED_WIDTH`) | 是用户的工作台偏好,跟项目、跟路由无关;刷新后应当还在 ⇒ 持久化 | `app/App.tsx:98`、`app/layout/AppSider.tsx:47/49` |
| `navOpen` | `useState(false)` | **窄屏**(`md` 以下,`narrow = Grid.useBreakpoint().md === false`)左抽屉开没开 | 是一次性的「我要跳个页面」动作;切路由就 `setNavOpen(false)`,刷新、切回桌面都不该带着它 ⇒ 不持久化 | `app/App.tsx:100/104/116/214` |
两者由同一颗汉堡按钮切换(`AppHeader` 收 `collapsed/onCollapse` 与 `navOpen/onToggleNav`
两组 props,`narrow` 决定它按哪一个),`{!narrow && <AppSider/>}` 与
`{narrow && <AppNavDrawer/>}` 互斥渲染,**同一屏只有一个导航实例**(D17/N7 定的口径)。
选中态不在这两个状态里:`selectedKeys={[pathname]}` 直接由路由算(§6.3),
所以抽屉开合、侧栏折叠都不会让「当前在哪」漂走。
**「一致」这件事还得让读屏听得见**(2026-11-08 阶段 8.5 第 5 项)。真机 VoiceOver 走位
时侧栏只报「菜单」,不报「当前页面」——选中关系原本**只写在 class 上**
(`.ant-menu-item-selected`),CDP 读选中项的属性只有 `aria-describedby`;antd Menu 在
`role=menu` 这条分支不写 `aria-selected`(`rc-menu/es/MenuItem.js:160` 那条属于
`role=option`)。补法:item 对象带 `'aria-current': 'page'`(`app/layout/AppSider.tsx`
的 `currentMark()`,判据仍是 `pathname`,与 `selectedKeys` 同一个钥匙、不引第二份状态),
rc-menu 会把它原样铺到 `<li>`。复测:三条桌面路由 + 430 抽屉,**有且只有当前项**带它,
菜单项宽度 207 未变(`reports/ui_evidence/nex-p8f/05-nav/probe-output.txt` D 段)。
**规则**:凡「选中/当前」只靠 class 表达的共享控件,都要同时给出辅助技术读得到的状态属性。
**不要合并**:合成一个布尔后,用户在手机上拉开抽屉 → 刷新 → 抽屉记成「折叠」→
切回桌面侧栏莫名变成窄栏;反过来在桌面折叠侧栏 → 手机打开 → 抽屉弹不出来。
两个正交的轴(**宽窄**、**开合**)被压成一根,两种设备互相污染对方的偏好。
### 6.3 路由 ↔ 菜单 ↔ 标题三者同一个钥匙
- `app/router.tsx` 是路由唯一表,`handle.title` 喂文档标题(`App.tsx` 的
@ -603,6 +693,16 @@ items = [
每行右端那个 `Tag` 是这一站的汇总状态(由它覆盖的那几个节点折算,`lib/pipeline.ts::moduleState`)。
- **窄屏不许把入口弄丢**:控制台在 375 也渲染(`min-w-[96px]` 保住项目名,轨道 <xl 隐、
当前节点 <lg 隐),实测 375 整块 174×32,与右侧工具簇间距 16px、不撞折叠键、Header 无横向滚动。
- **名字截断之后完整名称仍要读得到,且按输入设备分派三条通道**(`PipelineConsole.tsx`,
2026-11-08 · NEX 阶段 8.5 第 2 项):① **Hover** = 悬停名字 ⇒ antd `Tooltip`;② **Focus** = 键盘
`Tab` 到胶囊 ⇒ 同一层 `Tooltip`(只认 `:focus-visible`,`Esc` 收回,鼠标点击不弹);③ **Touch** =
没有悬停能力的那一档点胶囊 ⇒ 「项目概况」抽屉,抽屉标题就是完整名称。三条各管一类输入设备,
谁都不多余;辅助技术那条由按钮的 `title`(含完整项目名 + 进度)负责,不靠省略号文本。
两条口径定死:**只在真的截断时才弹**(`scrollWidth-clientWidth>1` 现量,整条读得完还飘一层
同样的字是噪音,与 §15.2 第 7 条同源);**弹不弹由悬停能力决定**(`matchMedia('(hover: hover)')`),
不按事件顺序打补丁——实测触屏的兼容 `mouseover` 排在 click 之后 `mouseEnterDelay=100ms` 才打开提示,
而手指永不 `mouseleave`,抽屉关掉后气泡还挂着;用 `hover:hover` 而非 `pointer:coarse`,
因为插了鼠标的混合设备该有提示。代价(触屏档读屏读不到键盘 Tooltip)登记为 N-3。
---
@ -1386,6 +1486,67 @@ antd 的 `Tag.CheckableTag` 未选中态是**完全透明**的。铺进等宽格
(实测列宽不再受 `width` 约束)。所以封顶必须包一层内层 `<div>`,也就是 `<Clamp>`。
`cellWrap` 只解决「不顶宽表格」、不解决「不撑高行」,新页面别再拿它当封顶用。
#### 13.2.1 窄屏表格:两套列档位(2026-11-08 · NEX 阶段 8.5 响应式收口)
**症状**:§13.2 那套列宽预算是按 1440 那把尺子算的(全宽表容器 **1118**)。同一份 `columns`
搬到窄屏,容器只剩 **430→356、576→502、768→462**,定宽列合计 400–902 不变,结果是两种坏法:
长文列被挤成 **0 宽**(`tableaudit` 报「横向溢出 546」,「取值」列实测只剩 **14px**),
或者整张表拖一条横向滚动条才能看完——430 的手机上去回滑一条成本记录,等于没有这条记录。
**做法:`useNarrowTable()` 换列定义,不换 DOM**(`frontend/src/components/ui/Table.tsx`)。
页面写 `const narrow = useNarrowTable()`,然后 `columns={narrow ? 精简列 : 宽档列}`——
宽档那一份**一字不动**(≥992 的渲染结果与改前逐字节相同),窄档把次要列**并进主列的第二、
三行**。关键约束是「数据换位置,不失踪」:并进去的字段仍然在表格里、仍然能被朗读和复制,
长文案用 `<Clamp lines={2}>` + 原生 `title` 收全(就是 §13.2 已经批准的「长文本完整内容提示」)。
**档位为什么是 992**:侧栏 224 + 正文左右 48 之后,992 视口的表容器实测 **670**,是全站那份
定宽预算放得下的最窄一档;992 以下实测 502 / 462 / 356,而 **768 那一档比 576 还窄**(侧栏
没折叠,正文被压到 462),所以三档窄屏共用同一套精简列,不按 576/768 再细分。
**为什么不用 CSS `max-lg:` 显隐**:要换的是列定义(少几列、格子合成几行)不是显示状态;
两套 columns 只有一份在渲染,辅助技术才不会读到藏在 DOM 里的列。
**窄档长文列下限 ≥120px**(宽档是 ≥200px):窄档容器本身只有 356,200 的下限会挤死动作列;
120 是实测「中文两行还能读出主干」的最窄值,低于它必须靠 `Clamp` + `title` 兜住完整内容。
格子行高预算仍是 **≤84px**(3 行 × 22),到边缘就去掉行间距(成片记录那条 `mt-0.5` 就是这么从
86 回到 84 的)。动作列宽度照 §13.2 第 3 条公式实测取值:成片「预览 66 + 下载 40 + gap 8 +
内边距 16 = **132**」,估的 120 会折两排。
**九张表逐个方案的落点**(430 视口实测;宽档列一律未改):
| # | 表 | 文件 | 选的方案 | 窄档列宽 | 行高 |
|---|---|---|---|---|---|
| ① | 项目列表 | `Dashboard.tsx` | 复用已验证的项目卡片,卡/表边界从 `max-sm` 推到 `max-lg`(表 `max-lg:hidden`、卡 `hidden max-lg:grid`) | 走卡片 | — |
| ② | 分镜任务清单 | `Dispatch.tsx` | 动作 Tag + 预估成本并入镜头行第 2 行,说明第 3 行 | 40 / 176 / 140 | 83 |
| ③ | 任务执行明细 | `Dispatch.tsx` | 9 列 → 3 列 | 148 / 128 / 80 | 83 |
| ④ | 审核留痕 | `Review.tsx` | 时间、类型·审核人、镜头合进首格三行 | 132 / 80 / 144 | 77 |
| ⑤ | 时间线版本 | `Timeline.tsx` | 版本号并入名称行,元信息第 2 行;宽档 `minWidth` 保留 | 144 / 84 / 128 | 59 |
| ⑥ | 成片记录 | `Delivery.tsx` | 规格/时长/大小第 3 行,耗时+校验和进 `title`;**缩略图保留**(唯一视觉凭证 + 预览入口) | 224 / 132 | 84 |
| ⑦ | 生成记录 | `Delivery.tsx` | #/类型/镜头/供应商进首列(重试次数 >1 才追加),成本/时长/时间右列 | 124 / 144 / 88 | 81 |
| ⑧ | 计费明细 | `Delivery.tsx` | 标识首列 / 数量·单价中列 / 金额·时间右列 | 124 / 136 / 96 | 59 |
| ⑨ | 成本台账 | `Delivery.tsx` | 维度 + 取值合并 / 金额 + 记录数右列 | 244 / 112 | 59 |
⑧⑨ 在开发库里没有数据、探针看不见,用 mock 路由(`page.route` 伪造 `/api/projects/*/costs`)
量出来的:改前 ⑨ 的「取值」列 **14px**、⑧ 会溢出 **456**。
**明确禁止**(这一轮的验收红线):不许对九张表用同一个方案;不许隐藏重要业务数据;不许只把
容器改宽当修复;不许放宽 `tableaudit` 规则掩盖缺陷;不许用 CSS 显隐维护两份 DOM。
**「数据没失踪」是量出来的,不是保证的**(同一轮 · 探针 `/private/tmp/nexd/p85_verify.py`,
读数 `reports/ui_evidence/nex-p8f/03-tables/DATA-INTEGRITY.txt`):同一张表在宽档与 430 各加载
一次,把宽档每格正文切成 token 集,逐条问「这个 token 在窄档还在不在」——**在**的判据是
「仍然出现在可见正文里」**或**「出现在某一格的 `[title]` 完整内容提示里」(`Clamp` 折行与
`title` 是 §13.2 已经批准的口径,格子宽度不许突破 84px 预算)。首轮 ②④⑤⑦ 四张表 100% 对上,
③⑥ 两张各缺一处,已补:
| 表 | 缺什么 | 怎么补 | 为什么这么放 |
|---|---|---|---|
| ③ 任务执行明细 | 宽档「任务」列第二行的**类型中文 + stage 码**(`配音 · voiceover` 等 5 个码 + 2 个中文名)在窄档压根不存在 | 追加到元信息行句尾,`title` 同时带上 | 那一格正文 132px、`line-clamp:1`,实测内容要 3 行(`sh=60 / ch=20`)——句首句尾同样只有开头十几个字符看得见;摆句首等于把「进度 100%」这个数换成 stage 码,而窄屏这张表要扫的是「哪条挂了 / 重试过几次」,那两个数在第二行状态标签与句首 |
| ⑥ 成片记录 | 宽档第 1 列 `#id`(65 / 78 / 79)整个没了 | 并进片名行写成 `#65 片名` | 与 ③「任务」列、⑦「生成记录」首列同一个「编号 + 名称」一行式,**不新增第二行** ⇒ 行高仍是 84 封顶;出片记录靠这个号对齐下载链接与工单 |
对账时的两个**读数陷阱**(写下来免得下轮误判成缺陷):① 正在跑的行「耗时」是活数,
两次加载之间必然不同(`954162.6s → 958402.0s`),这类差异不是数据失踪;② `line-clamp` 是**高度**
裁剪,`scrollWidth === clientWidth` 不代表没被裁——判裁剪要看 `scrollHeight > clientHeight`。
### 13.3 反馈四级表面:行内 / 页面 / 结果 / 确认(R19 落地)
症状(2026-11 第十三轮 · 用户原话「整体修改系统中所有提示窗、完成后的反馈 tips 等。
@ -1722,6 +1883,17 @@ URL 没变,effect 不再触发。
页面级快捷键清单以「使用说明」页为唯一登记处。**不许**为了这条给整块热区补 `title`——
原生 tooltip 会盖住卡内每一处,鼠标划过就是一片浮字。
**但读屏真机验收不在自动化闸里**:`semanticcheck`(§15.13)能证明「浏览器交给 AT 的那份数据里
名称、角色、状态、焦点环、live region 都在」,证明不了「NVDA / VoiceOver 在真机上确实念了这一句」。
本机没有能长驻的读屏环境(实测见阶段 8.5 报告 §7),所以 N14 这一项在真实 AT 上记的是
**MANUAL QA REQUIRED**——测试步骤与记录表在 `reports/NEX阶段8.5-响应式UX与质量收口-2026-11-08.md` §7,
那张表没填完,谁都不许把 N14 说成「读屏已验收」。
三家键位事实先记在这儿,免得下次照着网页文档重试一遍:**NVDA** 浏览模式下方向键归**审阅光标**,
`⌥↑` / `⌥↓` 要先切到焦点模式(`NVDA+空格`)才落到卡片上;**VoiceOver** 的修饰键是
`Ctrl+Option`,与 `⌥↑/↓` 不冲突,但 macOS「文本移动」快捷键族可能占用 `Option+↑/↓`,
系统更新后要复核;`aria-keyshortcuts` 只保证**可查询**,不保证播报——所以那份 `sr-only` 说明
(N14)不是重复,是播报的唯一来源,不许因为「已经声明了 keyshortcuts」就删掉它。
### G4 · 表单内的「增 / 删」:写法见 §5.1,这里只管摆位
自造 `variant` 方言已废(`mapVariant` 也删了),按钮的语义 → antd 轴映射**只在 §5.1 写一次**。
G4 剩下的只是「增 / 删放在哪一行」:
@ -1763,7 +1935,7 @@ G4 剩下的只是「增 / 删放在哪一行」:
---
## 15. 十一道常驻探针 + 一道反向验证(退出码都必须为 0)
## 15. 十三道常驻探针 + 一道反向验证(退出码都必须为 0)
### 15.1 `node scripts/ui/classaudit.mjs` —— 量源码用词
@ -2224,16 +2396,18 @@ provider 漏渲染、store 被引成第二份实例,都会让 `notify()` 静
道理和 `btnrowcheck` 的 `GROUPS 413 / TOTAL 0` 是同一条:**覆盖面是分子非零的前提,违规是判据**。
反向验证见 §15.12 的 `pb-cluster`(260 内宽三颗 120px → 2+1 必须响)/ `pg-cluster`(三颗满宽换行必须静)。
### 15.12 `.venv/bin/python scripts/ui/gateprobe.py` —— 反向验证七张闸门的十一条判据
### 15.12 `.venv/bin/python scripts/ui/gateprobe.py` —— 反向验证八张闸门的十四条判据(七张像素闸 + 语义三条)
第 30 轮立项、第 14 轮补齐到 **6/6**、第 16 轮补 `tagcheck.SPILL` 到 **7/7**、
第 17 轮补 `btnrowcheck.HEAD` 到 **8/8**、
第 17 轮(续)补 `btnrowcheck.exempt` 到 **9/9**、补 `footercheck` 到 **10/10**、
补 `btnclustercheck` 到 **11/11**:
补 `btnclustercheck` 到 **11/11**、
第 8.5 轮(2026-11-08)把语义那一族一次补到 **14/14**(`HOTSPOT` 候选 / `HOTSPOT-hard` 分档 / `TABTARGET` 走位清单):
`gridcheck` / `rhythmcheck` / `tagcheck` / `btnrowcheck` / `footercheck` / `btnclustercheck` /
`tableaudit` 判的都是像素,**它们自己也需要被体检**——豁免写宽一格,闸门就会永远安静地返回 0。
`tableaudit` 判的是像素,`semanticcheck` 判的是辅助技术读得到的语义——
**它们自己也需要被体检**:豁免写宽一格,闸门就会永远安静地返回 0。
它不碰源码、不触发 HMR,直接在 `/assets` 上种成对的 fixture:`pb-*`(坏)必须被对应闸门点名,
`pg-*`(好)必须放行。十一个闸门条目、28 条断言(每条目至少一坏一好,合法形态可以多块):
`pg-*`(好)必须放行。十四个判据条目、44 条断言(每条至少一坏一好,合法形态可以多块):
| 闸门条目 | `pb-*`:必须响 | `pg-*` / 其他必须放行 |
|---|---|---|
@ -2248,9 +2422,13 @@ provider 漏渲染、store 被引成第二份实例,都会让 `notify()` 静
| `footercheck` | 260px 内宽的 `.ant-drawer-footer` 里三颗 120px 按钮挤成 2+1(浮层底部,§15.10 管的那一族) | 同一底部 `flex-direction:column` + 两颗 `width:100%`——整组竖排等宽是合法多行 |
| `btnclustercheck` | 260 内宽的**无类名** flex 里三颗 120px 按钮折成 2+1(页面自己摆的那一族,`btnrowcheck` 没有类名可认、`footercheck` 不在浮层里) | 同样三颗各自 `width:100%` 换行——整簇满宽竖排是设计;同一父元素下「按钮 + 说明文字 + 按钮」两段各一颗,不是同一簇 |
| `tableaudit` | 300px 定宽单元格里 284px 的条 + nowrap 文本右溢 10px(`格子内容越界`) | 同样布局换成 220px 的条——摆得下就不许报 |
| `semanticcheck.HOTSPOT` | `div[role=button]` + `cursor:pointer`、**没给 `tabindex`**(`pb-sema`)与带 `data-clickable` 却没键盘路径的可点行(`pb-semb`)——正是阶段 2 修掉的那三类鼠标热区的形状 | 补了 `tabindex="0"` 的自定义控件(`pg-sema`)、原生 `<button>`(`pg-semb`)、热区里那颗 pointer 图标(`pg-semc`)、行里已有按钮的可点行(`pg-semd`)、antd v5 的图标根节点 `span.anticon.anticon-*`(`pg-simg`,**连候选都不该进**)——证明这条不是「见 `div` 就咬」,也不会把 antd 自己的 DOM 当成我们的契约 |
| `semanticcheck.HOTSPOT-hard` | 同一对 `pb-sema` / `pb-semb`:它们是「我们自己承诺过键盘可达」的那一档,必须落在**硬档**(进退出码) | 自绘的 `role=img`(`pg-semf`):HOTSPOT 的承诺只对**交互角色**成立,`img` 只是语义标注,要求它自己有 Tab 序列是判据越界(实测每主题 5 条纯噪声)——它该进候选,但不该进硬档 |
| `semanticcheck.TABTARGET` | 我们自己写的 `role=tab`(`pb-semt`)必须出现在走位清单里,否则 TAB 判据永远查不到它(判据瞎) | antd 自己的页签 `.ant-tabs-tab-btn`(`pg-semt`)必须**不在**清单里:那是 rc-tabs 的 DOM,`tabindex` 归 antd 管(实测每主题 3 条假阳性) |
任一条对不上退出码 1(“闸门瞎了或过敏,先修闸门再谈页面”),最后一行必须打出
`GATEPROBE_OK 11/11`(11 = 闸门条目数,不是断言数)。**改动这些闸的判据或豁免时必须跑它**:
`GATEPROBE_OK 14/14`(14 = 判据条目数,既不是断言数也不是 fixture 种数——同一块夹具会被几条判据分别评)。
**改动这些闸的判据或豁免时必须跑它**:
`ctl` 与 `spill` 两条就是靠 `pb-ctl` / `pb-tspill` 证明「坏了会响」之后才当退出条件用的;
反过来 `pg-ctl` / `pg-tspill` 挡的是另一种失败——判据太敏感,把合法布局也报成缺陷。
第 14 轮补 `ctl` / `spill` 时先跑的正是它:先看到两条新判据各自「坏 fixture 响、好 fixture 静」,
@ -2271,7 +2449,130 @@ provider 漏渲染、store 被引成第二份实例,都会让 `notify()` 静
第十一条 `btnclustercheck` 把第三种失败又往前推了一步:**尺子的覆盖面本身要能证伪**。
它种一对没有类名的 fixture(`pb-cluster` 三颗 120px 挤成 2+1 必须响、`pg-cluster` 三颗满宽换行必须静),
于是「选择器写窄了 / 连续段判定写漏了 / 竖排豁免误伤满宽栅格」这三种哑法都当场红。
2026-11-03 实测 **`GATEPROBE_OK 11/11`**。
语义那三条(`HOTSPOT` / `HOTSPOT-hard` / `TABTARGET`)钉的是**语义**那一族的三种失败:
① 判据读的是运行时计算样式与 `tabindex`,源码里删掉一行 `tabIndex={0}` 它才会红,
`classaudit` 那种字符串闸看不到;反过来如果它写宽了(比如「凡是 pointer 都算热区」),
`pg-semb` 那颗原生按钮当场就红。
② **软硬分档也要能被证伪**:光验候选清单看不出分档写错(`role=img` 本来就该在候选里),
所以 `HOTSPOT-hard` 用同一对夹具再评一遍——`pg-semf` 必须「在候选、不在硬档」。
③ **判据的输入清单本身要能证伪**:`TABTARGET` 两头都钉,我们的页签漏了 = 判据瞎,
antd 的页签混进来 = 每次都误报。
第 8.5 轮这一族**栽过的两次空转**就是靠这三条抓回来的(详见 §15.13 的「判据自查」段):
第一次是 antd 豁免写宽到整页,12 路由 × 3 视口 HOTSPOT/TAB 恒 0;第二次是豁免边界重定之后,
`COLLECT` 用 `data-nex-hotspot` 记「只报最外层」的章,而 `gateprobe` 按判据逐条 evaluate 同一份
`COLLECT` 三遍——第二遍每个热区都被自己上一遍盖的章吃掉,硬档清单恒为空。
**教训:反向验证的夹具会被重复评,所以采集必须是可重入的**;
现在 `COLLECT` 进来先把上一轮的 `data-nex-hotspot` 摘干净。
2026-11-03 实测 **`GATEPROBE_OK 11/11`**、2026-11-08 补语义三条之后 **`GATEPROBE_OK 14/14`**(见 §15.13)。
### 15.13 `.venv/bin/python scripts/ui/semanticcheck.py` —— 用语义与行为量「说不出口」的缺陷
**为什么还要一道**:前面十一道探针量的是像素与源码字符串,而可访问性缺陷恰好两样都不碰——
`aria-label=""`、指向不存在 id 的 `aria-labelledby`、常年挂在 JSX 上而抽屉根本没开的
`aria-expanded="true"`、给了 `role="button"` 却忘了 `tabIndex`:源码两条都齐、像素一张不差,
辅助技术读出来是空的。阶段 2 那三处非语义热区(`Storyboard` 卡、`Rows` 行、`AppHeader` 面包屑)
当初就是靠源码字符串改的,改完没人能证明「Tab 真的能停住」。
**它读的是浏览器真给 AT 的那份数据**:CDP `Accessibility.getFullAXTree`(角色 + 计算后的
可访问名称,不是 JSX 属性)、`getComputedStyle`(焦点环),加真键盘(Tab / Space / Escape)
与真鼠标(hover 唤出懒挂载的描述)。七条判据 `NAME / HOTSPOT / TAB / FOCUS / ARIA / LIVE / STATES`
口径逐条写在脚本 docstring,退出码 = offender 条数。默认 12 条路由(含 `/403` 与一条不存在的
路由)× 明暗两色 × 1440;`NEX_WIDTH=430` 再跑一遍——汉堡按钮 `aria-expanded` 随抽屉翻转、
Esc 关得掉,这条只有窄屏才走得到。
**六条实测结论,每一条都曾经是一次误报或一次空转**(写下来免得下一个人重新踩):
| 现象 | 源码 / 字符串检查为什么会误判 | 探针现在的做法 |
|---|---|---|
| `aria-describedby` 指向不存在的 id(首页 9 条悬空引用里 5 条) | antd Tooltip 的描述节点**悬停才挂载** | 给宿主打 `data-nex-sem` 句柄 → `hover()` → 再查那个 id;唤得出来就合规。`describedby/labelledby` 还要求目标有非空文字,光有节点不算 |
| `aria-controls="rc_select_0_list"` 查不到 | 下拉面板点开才挂载,而鼠标点它会被 `.ant-select-selection-item` 那层壳截走(实测) | `role=combobox` 走键盘:focus → Space 展开 → 复查目标高度 >1 → Escape 收起 |
| 「输入控件聚焦看不见焦点」 | 本项目按 `theme/antd.ts` 的既定决策**只变边框、不发蓝光**,变化落在第 3~4 层包裹(`.ant-select-selector` 边框 `#C3CCD6→#1677FF`);复选框更绝,`outline:3px solid` 画在 `input` 的**兄弟** `.ant-checkbox-inner` 上,`input` 自己纹丝不动 | 走位前先给全站可聚焦元素拍基线快照(自身 + 上 5 层包裹 + 旁边 2 个兄弟,同一把尺),到位后比描边 / 外发光 / 边框 / 底色四件套,整族纹丝不动才立案;快照前必须先 blur 并等 `FOCUS_DWELL`,否则基线就等于聚焦态(这个 bug 曾把「状态筛选」误报成缺陷)。按完每一下 Tab 停 260ms——antd 控件过渡 0.2s,立刻读数读到的是起点 |
| `role=tab` 的 `aria-controls` 面板不存在 | 非当前页签的面板懒挂载(`/models` 三条全是这么误报的) | 真点每个页签(≤6),验 `aria-selected=true` 搬过去了且面板节点出来了,再复原原页签 |
| **HOTSPOT / TAB 读数恒为 0**(12 路由 × 3 视口全绿) | 「祖先链上有 `ant-` 就豁免」在 antd v5 里等于**整页豁免**:根节点是 `.ant-app`,页面内容坐在 `.ant-card-body` / `.ant-tabs-tabpane` / `.ant-row` 里;反过来 antd v5 的图标根节点是 `class="anticon anticon-appstore"`,**不含 `ant-` 子串**,只认 `ant-` 又会把 antd 自己的图标当成我们写的标记 | 豁免边界改成「**元素自己**是 antd 的标记(`ant-*` 或 `anticon*`,且不带 `nex-`)→ 它家的;祖先是 antd 的**控件**(`.ant-btn` / `.ant-select` / `.ant-tag`)→ 它家的内部结构;祖先是**外壳与容器**(`SHELL` 名单:layout/app/card/tabs/list/row/col/space/flex/form/table/spin/empty/result/segmented/drawer/modal/popover/tooltip/dropdown/menu/…)→ 那只是我们内容住的房间,继续往上找,不豁免」。带 `nex-` 的一律算我们的:kit 用 antd 渲染的表面,行为归我们审。这条边界一旦被写宽,`gateprobe` 的 `pb-sema` 当场不响 |
| **Tab 走位从页面中间开始**(delivery 只走 10 站,独立探针 25 站) | `blur()` 只把焦点摘掉,**不会**把 Chromium 的「顺序焦点导航起点」放回文档开头——起点还留在刚刚那个元素上,于是前面几步(悬停 / Space / 点页签)把焦点留在第 16 个控件之后,Tab 从那儿继续,**文档开头到那儿之间的控件整段被跳过**:一半是「Tab 序列里找不到」假阳性,另一半更糟——**根本没被走过,FOCUS 静默漏检** | 走位前 `body` 临时 `tabindex="-1"` + `body.focus()` + `scrollTo(0,0)`,起点回到文档最前,走完再摘掉。同时每页必须打印 `Tab 走 N/M 站`:走位数少于可见可聚焦元素数还不收工的,判据自己标 `⚠ 覆盖不足` |
另有三种「只计数、不立案」的情况,每页打印,免得它们变成第二个黑洞:唤不出但宿主是 antd
自己的内部结构(`ant-` 且不带 `nex-`)且它本身有 `title` 或自己的文字可读——收起态菜单项、
`Typography` 省略号那类,文字没丢,且我们不做 antd 深层 DOM 覆盖(AGENTS.md 第 9 条);
被 `aria-hidden` / `display:none` 藏起来的宿主(Tabs 溢出用的 `#rc-tabs-0-more`),AT 根本读不到它;
Tab 走位时在基线快照之后才长出来的元素(浮层里的)记为待判,不当缺陷。
**为什么不靠源码字符串匹配**:本项目三处成熟的键盘可达实现(`Select`、`Input`、`Checkbox`)
在 `outline` 这一项上的实测值全是空的——按字符串判「焦点可见」会把它们全报成缺陷,
于是这条一定被当成噪音关掉;反过来 CSS 里一句 `outline:none` 吃环,源码里根本找不到那行。
用法与其余口径见 `scripts/ui/semanticcheck.py` docstring。反向验证在 §15.12 的
`semanticcheck.HOTSPOT` / `HOTSPOT-hard` / `TABTARGET` 三条。
**新增判据的准入条件**(本轮血的教训换来的规矩):一条判据「读数全 0」有两种可能——页面真的干净,
或者**候选集是空的**,这两种在输出里长得一模一样。所以任何一条判据要进常驻串行,必须先在
`gateprobe` 里有它自己的**缺陷夹具与合法夹具各至少一条**,并且**分档也要能证伪**
(硬档单列一条判据)。没有这对夹具的判据不许当退出条件用。
**首跑实测读数(2026-11-08 · 阶段 8.5 第 4 项 · 视口 1440 · 明暗 × 12 路由)**
| 判据 | 改前 | 改后 |
|---|---|---|
| NAME 硬档 | 60 条 | **0** |
| FOCUS | 6 条 | **0** |
| HOTSPOT / TAB / ARIA / LIVE / STATES | 0 | **0** |
| NAME 软档(只打印) | — | 19 类 / 每主题 20 实例(`timeline` 14 · `delivery` 3 · `overview` 2 · `review` 1) |
| 退出码 | 66 | **0** |
430 档补跑汉堡那条:`ARIA 430/{dark,light}/… 汉堡名称 初始「打开导航菜单」→ 展开「关闭导航菜单」
→ 收起「打开导航菜单」`,同时 `aria-expanded` false→true→false、`.ant-drawer-open` 1→0,
Esc 关得掉,两个主题 × 12 条路由全部为 0 条违规。
**这次咬出来的三处真缺陷**(都不在源码字符串里,靠这道闸才看得见):
- **D-A** `pages/AssetLibrary.tsx` 三处 `<Checkbox>`(素材墙批量选择 · 列表行 · 卡片)在 AX 树里
名字是空的。勾选类不吃「相邻文字」豁免——读屏只念「复选框,未选中」,一屏十颗用户不知道勾的
是哪一颗。补 `aria-label`,命名沿用 `pages/project/Library.tsx` 里 `PickBox` 的既有说法,
改后 `/assets` 无名节点 10 → 0。
- **D-B** 上传用的透明 `<input type=file class="nex-file-input">` 铺在按钮底下,焦点环被
`styles/app.css:46` 那句 `:where(input, …):focus-visible { outline: none }` 整条吃掉——
源码里 TSX 一切正常,CSS 里一句话让键盘用户看不见自己在哪。补一条按实际状态写的规则:
`.ant-btn:has(> .nex-file-input:focus-visible) { outline: 2px solid var(--ant-color-primary);
outline-offset: 2px }`。不用 `:focus-within`:鼠标点按钮也会命中,等于给鼠标用户凭空多画一圈。
- **D-C** 进度条写了 `role="slider"`,却没给 `tabindex`、也没有按键路径:辅助技术念得出
「滑块 42%」,键盘却一步都动不了——**是我们自己先把 ARIA 契约说出去又没兑现**,
源码里 `role` 与 `onClick` 两行都齐,字符串检查看不出任何毛病。两处,按各自的实际行为分开修:
① `components/media/AudioPlay.tsx`(全站 10 处调用点 / 6 个文件共用的那一块,可点选位置)补 `tabIndex=0` +
`aria-valuemin/max` + `aria-valuetext`(念出「00:03.20 / 00:05.08」而不是只有百分比)+
`onKeyDown`:`←/↓` `→/↑` 挪 5%(Shift 20%)、`Home`/`End` 到首尾,走的是与鼠标同一个 `seekAudio`;
`preventDefault` + `stopPropagation` 是必需的——分镜页把裸 `↑/↓` 绑成「切上一镜/下一镜」
(`pages/project/Storyboard.tsx:1131-1132`),焦点在进度条上时那两下只能找位、不能换镜。
焦点环不用另写:`app.css:41` 那条全局 `:focus-visible` 自动覆盖。
② `components/media/MediaLightbox.tsx`(统一预览器里那条进度)**本来就是只读**的——没有 `onClick`,
`←/→` 归预览器换素材、`Space` 归它播放暂停(window 捕获阶段,控件自己抢不走),
给它加 `tabindex` 等于承诺一件做了也没用的事。改成 `role="progressbar"`:语义与行为一致,
Tab 序列也不欠债。**同一个 ARIA 角色在两个组件里得出两种修法**,这正是「按行为定语义」
而不是「按字符串统一」的区别。修后 timeline 热区硬档 7 → 0、review 1 → 0。
**一条系统性欠账,记在这里不当缺陷用**:`components/ui/Fields.tsx` 的 `Field` 就是 antd
`Form.Item`,**孤立使用(外层没有 `<Form>`)时 antd 不给控件生成 id、`<label>` 的 `for` 是空的**,
于是标签文字看得见却进不了控件的辅助技术名称——软档那 20 颗/主题全部来自这里。
补法是二选一:`Field` 自己发 `id` / `htmlFor`,或逐颗补 `aria-label`;两者都属于 P2 批量整改,
本轮不碰(同一颗控件改两遍会打架)。这也解释了为什么 NAME 分两档:硬档只咬「AT 一定读不到」的,
软档记「相邻有一句话、用户靠相邻播报猜得出来」的欠账,`NEX_NAMESTRICT=1` 可整体升档。
**已知限制**:Tab 上限默认 `NEX_TABS=200`(第 8.5 轮从 140 抬到 200——旧值在素材多的 `/assets`
上撞顶)。撞上上限的那条路由,TAB 判据是「到上限为止全部可达」,不是全量遍历;
抬上限换的是覆盖,代价是跑时,再往上抬之前要先想清楚那页该不该有 200 个 Tab 停靠点。
**探针自己踩过的五个坑**(写下来,下一个人别把闸当神):① `describe()` 把类名里的 `ant-` 前缀
剥掉了,于是「宿主是 antd 内部结构就豁免」那条判断永远不成立,误报一整批;② `unnamed_context`
按句柄序号索引、主循环却按 `bid` 取,结果所有无名节点的上下文都读不到,硬档等于瞎判;
③ 汉堡那条把定位写死成 `button[aria-label="打开导航菜单"]`——`AppHeader` 按既定决策在两形态下
说两句话(窄屏「打开/关闭」、宽屏「收起/展开」),名称本来就该随状态翻转,点一下之后这颗按钮
就查不到了(430 首跑就是这么崩在 `get_attribute` 超时上的)。现在用 **角色 + 名称含「导航菜单」**
定位,并用 CDP 读回辅助技术真正拿到的名称,把「名称与面板状态同向」也写成判据:
名称会翻是要求的行为,不是要绕过的噪音;④ **豁免边界写宽到整页**,HOTSPOT/TAB 恒 0 装了
一轮假绿(修法与证据见上表第三行);⑤ **采集函数不可重入**:`COLLECT` 用 `data-nex-hotspot`
记「只报最外层」的章,`gateprobe` 按判据逐条 evaluate 同一份 `COLLECT` 三遍,第二遍起所有热区
都被自己上一遍盖的章吃掉,硬档清单恒为空——`GATEPROBE_FAIL` 抓到的,不是页面抓到的。
现在 `COLLECT` 入口先摘章,并且每页打印 `热区 hard n / soft m(候选共 k)`:
**候选为 0 而页面明显有自绘可点物的,就是闸瞎了**。
---
@ -2303,7 +2604,11 @@ provider 漏渲染、store 被引成第二份实例,都会让 `notify()` 静
改过这**八道**闸的任何一条判据或豁免(含 `tableaudit` 的 `spill`),必须跑 `scripts/ui/gateprobe.py`(§15.12)——
豁免写宽一格,闸门就永远安静地返回 0;判据太敏感,合法布局会被整片误报;
判据压根扫不到那一族 DOM,则全绿只是沉默(`pb-footer` 钉的就是这一种)。
(`gateprobe` 当前覆盖七张像素闸的十一条判据;`aligncheck` / `symmetrycheck` 那几把尺的反向验证按 §15.8 的做法各自手工做一次。)
(`gateprobe` 当前覆盖七张像素闸 + `semanticcheck` 的三条语义判据共十四条(末行 `GATEPROBE_OK 14/14` 数的就是判据条数,不是 fixture 数);`aligncheck` / `symmetrycheck` 那几把尺的反向验证按 §15.8 的做法各自手工做一次。)
**动过可点击元素的语义、焦点或 aria 声明**(补 `tabIndex`、改 `role`、写 `aria-expanded` /
`aria-describedby` / `aria-controls`、给省略号加 `title`)另跑 `scripts/ui/semanticcheck.py`(§15.13)
明暗两色 + 1440 与 430 各一遍:它量的那一层——辅助技术实际读到的名称、Tab 实际能不能停住、
焦点实际看不看得见、声明与行为是否一致——像素闸与源码字符串闸都结构上看不见。
10. **动过反馈表面就跑 `scripts/ui/feedbackcheck.py`**(§15.9):`classaudit` 第 6 道闸只能证明
源码里没写 `window.confirm` / `message.*`,证明不了「吐司真的在右下角、悬停真的会暂停、
连点真的去重成 ×N、确认框回车 Esc 真的能定返回值」——这五件事只有浏览器量得出来。
@ -2312,5 +2617,5 @@ provider 漏渲染、store 被引成第二份实例,都会让 `notify()` 静
12. **改过任何会被手册截图的界面,重拍 12 张插图**:`scripts/ui/helpshots.py`
(`→ frontend/public/help/*.png`,1600×1000、@2x 拍完 LANCZOS 缩回、锁浅色、主角固定
项目 12、五个项目子页先收起「项目概况」,口径写在脚本 docstring 里)。
插图是 `<img>` 直出的静态文件,**不参与构建**:tsc / build / 十一道探针全绿,
插图是 `<img>` 直出的静态文件,**不参与构建**:tsc / build / 十三道探针全绿,
手册里也可能还是上一个皮肤的旧截图。