From 1d25c8a4f58f9da6c55ae73a80e23c7ebef5efe0 Mon Sep 17 00:00:00 2001 From: HIsheR Date: Tue, 27 Oct 2026 02:13:10 +0800 Subject: [PATCH] =?UTF-8?q?iter(g337):=20=E5=8F=AF=E8=AE=BF=E9=97=AE?= =?UTF-8?q?=E5=90=8D=E7=BA=B3=E5=85=A5=20verify=20=E9=97=A8=E7=A6=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .ua/backlog.json | 9 ++++++++ AGENTS.md | 2 +- packages/skin/ui/src/commandPalette.ts | 1 + packages/tools/cli/bin/ua.js | 29 +++++++++++++++++++++++++- 4 files changed, 39 insertions(+), 2 deletions(-) diff --git a/.ua/backlog.json b/.ua/backlog.json index 3642c6a..828f3f1 100644 --- a/.ua/backlog.json +++ b/.ua/backlog.json @@ -3419,6 +3419,15 @@ "motivation": "selectable 表格里，表头全选框与每行复选框都没有可访问名，读屏连续播报「复选框、复选框、复选框」，用户不知道选的是哪一行；选中行的反馈只有一层淡底（视觉），tr 上没有 aria-selected，读屏完全听不出「这行已被选中」——批量操作前确认选对了没有，全靠眼睛。", "acceptance": "① 表头全选框 aria-label「全选本页」，行复选框「选择第 N 行」（与展开列的行号口径一致）；② 选中行带 aria-selected（可点行按 selectable 给 true/false，不可点行只给 true），淡底仍作视觉层；③ dataTable 文档的 selectable 步骤同步说明；④ dataTable.ts 仍 ≤ 200 行（CODING.md 硬上限）；⑤ npm run check 全绿。", "notes": "" + }, + { + "id": "g337", + "domain": "tooling", + "status": "open", + "title": "可访问名门禁：combobox / slider / range 缺 aria-label 直接红", + "motivation": "本轮修输入件可访问名时发现口径靠人记：13 个组件都有 ariaLabel，commandPalette 的搜索框却只有 role=combobox + aria-controls，没有名字——读屏进命令面板只念「编辑框」，用户不知道搜什么。这类缺陷肉眼看不出来（placeholder 看着像有名字），只有读屏用户会撞上，必须让门禁兜住。", + "acceptance": "① ua verify 新增 checkAriaNames：扫描皮肤包源码里含 role: 'combobox' / role: 'slider' / type: 'range' 的创建块，块内既无 aria-label / aria-labelledby、紧随其后 3 行也没有 setAttribute('aria-label') 即报错，报出文件:行号；② 窗口只取单次 h() 调用块（回退到 h('input|textarea|select'、前进到收尾行），避免把相邻元素的 aria-label 误算成本控件的名字；③ 实跑抓到 commandPalette 一处并修好（aria-label 取 placeholder，缺省「搜索命令」）；④ AGENTS 的门禁说明与 verify 成功串同步；⑤ npm run check 全绿。", + "notes": "" } ] } diff --git a/AGENTS.md b/AGENTS.md index b3bb38b..b2d7118 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,7 +27,7 @@ - `apps/demo`（@ui-arch/demo）：交互演示，产物 apps/demo/dist/demo.html - `apps/docs`：文档站，纯产物（ua docs 生成） -**门禁一条龙**：`npm run check` = build + demo + style + typecheck + smoke + index + verify + lint-iterations + audit:visual + audit:contrast + audit:motion + audit:surface，提交前必过。其中 `smoke` 是三段断言：`@ui-arch/frame` 14 条（信号读写与同值短路、effect 注销与条件分支重追踪、computed 链式派生、多订阅者扇出）+ `@ui-arch/table-core` 37 条（排序 / 筛选 / 分页 / 选择的派生管线 + setRows 换源与失效行剔除 + 越界页码回写 + setColumns 换列与失效规则剔除）+ `@ui-arch/ui` 8 条（皮肤层纯逻辑：行级差异的剪前后缀 / LCS 对齐 / 忽略空白 / 超限退化，跑的是 dist/diffKit.js）；改内核语义或纯逻辑前先跑它，别靠组件 demo 肉眼验。`ua audit:visual` 统计皮肤包里十四类硬编码视觉字面量（字号 / 动效时长 / 阴影 / 圆角 / 焦点环 / 内距 / 控件高度 / 字重 / 行高 / 层级 / 边框色 / 混色浓度 / transform 位移 / 焦点描边）并与 `.ua/visual-baseline.json` 做棘轮：任一类超过基线即退出码 1 并指出疑似引入的提交；迁移脚本 `npm run visual:migrate` 可把字面量幂等改写成令牌。`ua audit:contrast` 走另一条线：把令牌里 24 组「前景色 × 底色」配对（正文/次级/辅助文字 × 页面底/表面/凹陷底、强调色与其反白、语义三色、正文与语义色 × 三块语义淡底、禁用态豁免档、焦点描边 × 页面底/表面）按 WCAG 公式算成对比度（支持 `color-mix` 与 `var()` 求值，半透明底先压到页面底色上），亮 / 暗 × 常规 / 高对比四套主题各算一遍，低于阈值（正文 7 / 常规 4.5 / 禁用 2.6 / 非文本 3）即退出码 1；`--json` 出逐对明细，`--list` 只列配对表。改任一颜色令牌后它会立刻告诉你「改完谁读不清了」，不必等人工目测暗色。`ua audit:motion` 守的是动效面，两类必查：① 带 `infinite` 的动画是否在 `prefers-reduced-motion: reduce` 块里被 `animation: none` 关掉——循环动画是前庭敏感用户的硬伤，漏一条整页就在抖（它抓出过转圈与不确定态进度两处漏网）；② 悬停 / 按压的位移（`translate`）是否在减少动效下归零——位移最容易诱发前庭不适，且只提供手感、不表达状态（一条 `ua-` 类通配的 `transform: none !important` 兜住全站 14 处，新增组件不用各自补）。③ 旋转 / 缩放这类第三类空间动效（折叠箭头、按压缩放）是否有「只留颜色过渡」的收窄兜底——空间变换即时到位、状态仍看得见（一条通配 `transition-property` 收窄兜住全站 35 处）。`ua audit:surface` 补的是「底色 vs 底色」这条盲区：把表面阶梯（页面底 → 表面 → 悬停底 → 按下底，外加凹陷底）逐档按亮度比验，相邻档低于 1.04（凹陷档 1.02）即退出码 1；同一条阶梯还多验两档「半透明 accent 淡底压在表面上」——选中底（`--ua-color-tint-accent`）与悬停底（`-weak`）各要 ≥ 1.04，浓度调低到看不出选中时它会红（实测暗色弱档降到 2% 只有 1.026，正是这条门禁要拦的），外加语义三色淡底（`--ua-color-tint-danger` / `-success` / `-warning`）各一档：这三块底调淡了提示条就退化成普通卡片。对比度门禁只管文字读不读得清，管不到「悬停有没有反馈」——实测过表面 → 二阶表面只有 1.008，悬停改了等于没改；`--json` 出逐档明细，`--list` 只列阶梯表。`ua verify` 校验清单 ↔ 文档 ↔ 演示一致（docs.components 的 id 必须在 api.exports 有对应条目、props 必须带 n/t/d、steps 至少 4 条（少于 4 条说明这组件还没想清楚边界）、每个文档字段名必须在组件实现源码里真实出现（改名后忘改文档会直接报错）、反向也校验 `src/types.ts` 里 `<组件>Props`（可用清单的 `propsType` 覆盖接口名，`false` 表示无入参）每个字段都在文档 props 表登记（新加字段忘了写文档会报错）、demo 锚点必须在 `apps/demo/main.ts` 中存在，且该组件必须被 demo 真实调用 `id(` / `id.`），反向也查孤儿演示（demo 里用 section() 定义的每个区块都必须被某个组件的 demo 字段认领，加了区块忘登记会直接报错），检查皮肤包样式表无硬编码颜色（`#hex` 一律禁止，必须走 `--ua-*` 令牌）与令牌引用有效（`var(--ua-*)` 必须是 tokens.css 已定义或组件自设的变量）、核对每个 `--ua-color-*` 都在 `[data-theme='dark']` 里有覆盖值且暗色块没有凭空多出的变量名（新增颜色令牌漏写暗色值直接报错）、核对 `tokens.json` 的 `color` 键与 tokens.css 的 `--ua-color-*` 同名同值（名字按 camelCase → kebab 折算，亮色值与暗色值都比，双向查漏——只改一处时文档色板会凭空多/少一个令牌，过去只能靠人眼发现）、核对 `@keyframes` 没有「帧体完全相同但名字不同」的复制粘贴（同一段动效只该有一份声明，改名复制会让方向 / 时长各写各的，翻转态就出现过「朝反方向入场」），核对 README 的 `` 区块与「分组：」行都覆盖清单组件集合（漏写/多写/重复都报错），并交叉校验 backlog 的 done 条目与 `.ua/iterations.log` 的 done 留痕一一对应（另外查 backlog id 不重复、g 编号严格递增、同一 id 只有一条 done 留痕，且留痕 ts 带 +08:00、时间线不回退、不落在未来——都是过去手工插条目/手写时间戳踩过的坑；反向也查：git 里每个 `iter()` 提交都必须有一行留痕，只查「留痕 → 提交」会放过「提交了却忘写留痕」，那种漏记最隐蔽——日志读起来完整，实际少记了一轮产出）；配方还要求编号连续、每条都有代码块与要点，且代码块里至少认出一个已注册组件 id（拼错组件名时 `ua recipes` 会把它列成空组件表）。 +**门禁一条龙**：`npm run check` = build + demo + style + typecheck + smoke + index + verify + lint-iterations + audit:visual + audit:contrast + audit:motion + audit:surface，提交前必过。其中 `smoke` 是三段断言：`@ui-arch/frame` 14 条（信号读写与同值短路、effect 注销与条件分支重追踪、computed 链式派生、多订阅者扇出）+ `@ui-arch/table-core` 37 条（排序 / 筛选 / 分页 / 选择的派生管线 + setRows 换源与失效行剔除 + 越界页码回写 + setColumns 换列与失效规则剔除）+ `@ui-arch/ui` 8 条（皮肤层纯逻辑：行级差异的剪前后缀 / LCS 对齐 / 忽略空白 / 超限退化，跑的是 dist/diffKit.js）；改内核语义或纯逻辑前先跑它，别靠组件 demo 肉眼验。`ua audit:visual` 统计皮肤包里十四类硬编码视觉字面量（字号 / 动效时长 / 阴影 / 圆角 / 焦点环 / 内距 / 控件高度 / 字重 / 行高 / 层级 / 边框色 / 混色浓度 / transform 位移 / 焦点描边）并与 `.ua/visual-baseline.json` 做棘轮：任一类超过基线即退出码 1 并指出疑似引入的提交；迁移脚本 `npm run visual:migrate` 可把字面量幂等改写成令牌。`ua audit:contrast` 走另一条线：把令牌里 24 组「前景色 × 底色」配对（正文/次级/辅助文字 × 页面底/表面/凹陷底、强调色与其反白、语义三色、正文与语义色 × 三块语义淡底、禁用态豁免档、焦点描边 × 页面底/表面）按 WCAG 公式算成对比度（支持 `color-mix` 与 `var()` 求值，半透明底先压到页面底色上），亮 / 暗 × 常规 / 高对比四套主题各算一遍，低于阈值（正文 7 / 常规 4.5 / 禁用 2.6 / 非文本 3）即退出码 1；`--json` 出逐对明细，`--list` 只列配对表。改任一颜色令牌后它会立刻告诉你「改完谁读不清了」，不必等人工目测暗色。`ua audit:motion` 守的是动效面，两类必查：① 带 `infinite` 的动画是否在 `prefers-reduced-motion: reduce` 块里被 `animation: none` 关掉——循环动画是前庭敏感用户的硬伤，漏一条整页就在抖（它抓出过转圈与不确定态进度两处漏网）；② 悬停 / 按压的位移（`translate`）是否在减少动效下归零——位移最容易诱发前庭不适，且只提供手感、不表达状态（一条 `ua-` 类通配的 `transform: none !important` 兜住全站 14 处，新增组件不用各自补）。③ 旋转 / 缩放这类第三类空间动效（折叠箭头、按压缩放）是否有「只留颜色过渡」的收窄兜底——空间变换即时到位、状态仍看得见（一条通配 `transition-property` 收窄兜住全站 35 处）。`ua audit:surface` 补的是「底色 vs 底色」这条盲区：把表面阶梯（页面底 → 表面 → 悬停底 → 按下底，外加凹陷底）逐档按亮度比验，相邻档低于 1.04（凹陷档 1.02）即退出码 1；同一条阶梯还多验两档「半透明 accent 淡底压在表面上」——选中底（`--ua-color-tint-accent`）与悬停底（`-weak`）各要 ≥ 1.04，浓度调低到看不出选中时它会红（实测暗色弱档降到 2% 只有 1.026，正是这条门禁要拦的），外加语义三色淡底（`--ua-color-tint-danger` / `-success` / `-warning`）各一档：这三块底调淡了提示条就退化成普通卡片。对比度门禁只管文字读不读得清，管不到「悬停有没有反馈」——实测过表面 → 二阶表面只有 1.008，悬停改了等于没改；`--json` 出逐档明细，`--list` 只列阶梯表。`ua verify` 校验清单 ↔ 文档 ↔ 演示一致（docs.components 的 id 必须在 api.exports 有对应条目、props 必须带 n/t/d、steps 至少 4 条（少于 4 条说明这组件还没想清楚边界）、每个文档字段名必须在组件实现源码里真实出现（改名后忘改文档会直接报错）、反向也校验 `src/types.ts` 里 `<组件>Props`（可用清单的 `propsType` 覆盖接口名，`false` 表示无入参）每个字段都在文档 props 表登记（新加字段忘了写文档会报错）、demo 锚点必须在 `apps/demo/main.ts` 中存在，且该组件必须被 demo 真实调用 `id(` / `id.`），外加可访问名扫描（combobox / slider / range 控件必须有 `aria-label` / `aria-labelledby` 或紧邻的 `setAttribute('aria-label')`，缺了读屏用户就摸不到控件），反向也查孤儿演示（demo 里用 section() 定义的每个区块都必须被某个组件的 demo 字段认领，加了区块忘登记会直接报错），检查皮肤包样式表无硬编码颜色（`#hex` 一律禁止，必须走 `--ua-*` 令牌）与令牌引用有效（`var(--ua-*)` 必须是 tokens.css 已定义或组件自设的变量）、核对每个 `--ua-color-*` 都在 `[data-theme='dark']` 里有覆盖值且暗色块没有凭空多出的变量名（新增颜色令牌漏写暗色值直接报错）、核对 `tokens.json` 的 `color` 键与 tokens.css 的 `--ua-color-*` 同名同值（名字按 camelCase → kebab 折算，亮色值与暗色值都比，双向查漏——只改一处时文档色板会凭空多/少一个令牌，过去只能靠人眼发现）、核对 `@keyframes` 没有「帧体完全相同但名字不同」的复制粘贴（同一段动效只该有一份声明，改名复制会让方向 / 时长各写各的，翻转态就出现过「朝反方向入场」），核对 README 的 `` 区块与「分组：」行都覆盖清单组件集合（漏写/多写/重复都报错），并交叉校验 backlog 的 done 条目与 `.ua/iterations.log` 的 done 留痕一一对应（另外查 backlog id 不重复、g 编号严格递增、同一 id 只有一条 done 留痕，且留痕 ts 带 +08:00、时间线不回退、不落在未来——都是过去手工插条目/手写时间戳踩过的坑；反向也查：git 里每个 `iter()` 提交都必须有一行留痕，只查「留痕 → 提交」会放过「提交了却忘写留痕」，那种漏记最隐蔽——日志读起来完整，实际少记了一轮产出）；配方还要求编号连续、每条都有代码块与要点，且代码块里至少认出一个已注册组件 id（拼错组件名时 `ua recipes` 会把它列成空组件表）。 `ua verify` 另外校验 `ITERATION.md` 的《视觉回归抽查清单》：button / textField / select / modal / dataTable / toast / layout / jsonViewer / diffView / codeBlock / signaturePad / heatmap / sparkline / commandPalette / noticeBar / progressRing / sortableList / masonry 十八段各 ≥3 条可勾选要点、每条维度标签必须落在边框 / 阴影 / 过渡 / 焦点环 / 暗色五类内、合计 ≥54 条（下限由段数 × 3 推导，加抽查位不必手改）且五维度全覆盖——视觉类条目收尾前照单过一遍，改清单时别把条目删漏。 diff --git a/packages/skin/ui/src/commandPalette.ts b/packages/skin/ui/src/commandPalette.ts index 125c361..d54e70e 100644 --- a/packages/skin/ui/src/commandPalette.ts +++ b/packages/skin/ui/src/commandPalette.ts @@ -28,6 +28,7 @@ export function commandPalette(props: CommandPaletteProps): CommandPaletteHandle class: 'ua-cmdk-input', type: 'text', placeholder: props.placeholder ?? '搜索命令…', + 'aria-label': props.placeholder ?? '搜索命令', // 占位文案只是提示，不是可访问名：读屏要靠这一条才知道搜的是什么 'aria-controls': `${uid}-list`, role: 'combobox', 'aria-expanded': 'true', diff --git a/packages/tools/cli/bin/ua.js b/packages/tools/cli/bin/ua.js index deebd09..e847e74 100644 --- a/packages/tools/cli/bin/ua.js +++ b/packages/tools/cli/bin/ua.js @@ -1630,6 +1630,32 @@ function checkVisualChecklist() { } /*** 清单一致性校验：组件文档块的 id / props 说明 / demo 锚点必须与代码和演示产物对齐 ***/ +/*** 校验输入控件的可访问名：role=combobox / slider 与原生 range 不自带名字，缺 aria-label 时读屏只念「编辑框 / 滑块」 + * 只查这三类「必须有名字」的控件，包裹式