11 KiB
12. Responsive, Accessibility & Quality Evidence Governance
1. 本文目的
本文将 NEX 的响应式、可访问性和质量闸要求转化为可登记、可测试、可审计的项目规则。它不指定统一像素断点、屏幕阅读器、CSS 技术或 Bundle 阈值;项目应依据用户群、支持平台和实际实现确定具体值。
2. 响应式断点注册机制
2.1 基本原则
- 先复用项目现有断点体系。
- 仅当真实布局约束无法通过现有断点合理表达时,才新增命名断点。
- 命名断点应表达布局状态或设计意图,而不只是设备名称(例如
compact-workspace优于iphone-width)。 - 断点定义必须集中在项目认可的权威位置;组件级例外应登记,不得散落为不可追踪的媒体查询。
- 不为减少断点数量而接受内容遮挡、字段丢失、操作不可达或明显不合理的视觉回退。
2.2 登记字段
每个断点记录:
- 名称;
- CSS 条件和值(min-width/max-width/范围/容器查询);
- 解决的问题与设计理由;
- 影响的 Shell、页面和组件;
- 权威定义文件/Token/主题位置;
- 与相邻断点的布局差异;
- 断点前、断点处、断点后的测试宽度;
- 证据、批准来源和复审条件。
2.3 边界测试
若断点条件为 min-width: X,至少覆盖 X 前一个有效 CSS 像素、X 和 X 后一个有效 CSS 像素;若为区间或 max-width,也应覆盖两侧边界。还应覆盖实际用户常见宽度、浏览器缩放和长内容/长标签等压力数据。
不要只测试 390/768/1024/1440 等设备预设宽度而遗漏项目自己的临界区间。
3. 窄屏表格与数据完整性
3.1 列优先级
每张表格应先把列分为 Primary、Secondary、Tertiary 和 Actions。优先级依据用户任务和数据决策价值,不得由实现方便程度决定。
3.2 响应策略
可选择一种或组合多种策略:
- 保留关键列,次要字段进入行详情/展开区;
- 对对象摘要或键值数据使用卡片/记录视图;
- 对横向比较数据使用容器内滚动;
- 对稳定识别字段使用固定列;
- 将密集行内动作收纳为操作菜单;
- 对长文本使用换行、截断+完整内容或详情入口。
不能把“增加容器宽度”作为默认解决方案,也不能无说明地隐藏核心数据。
3.3 数据对账方法
在相同测试数据集下比较宽屏与窄屏:
- 记录总数一致;
- 关键字段值和字段归属一致;
- 排序、筛选和分页语义一致;
- 所有隐藏/折叠字段可通过明确路径查看;
- 行操作仍作用于正确记录;
- 空值、长文本、极值、状态、权限和异常数据有代表性覆盖。
对卡片化视图,核对每条记录显示的标签和值;对表格视图,核对表头关联、列顺序、滚动和操作区域。
3.4 屏幕阅读器阅读顺序
- 表格保留适当的行/列标题关联,不用纯视觉布局模拟数据表格。
- 响应式切换为卡片后,应为每个值提供清晰字段标签和逻辑阅读顺序。
- 避免对每个单元格重复朗读冗长上下文,必要时调整可访问名称或结构。
- 排序、选择、展开详情和操作菜单状态应可感知。
- 横向滚动容器应有合理名称/提示,并能通过目标输入方式访问。
4. 可访问名称和图标
4.1 装饰图标
当图标仅用于视觉装饰,或与相邻可见文本重复表达同一含义时,应从辅助技术名称计算中排除。使用项目适当的方式(如 aria-hidden="true"),并确认图标字体/glyph 内部名称不会被读屏软件当成内容。
4.2 图标按钮
图标按钮必须有清楚的可访问名称,例如“导入脚本”“导出”“关闭面板”。名称必须描述动作或对象,不能直接暴露 upload、down、trash-2 等内部图标命名。
4.3 截断与完整名称
重要文本被视觉截断时,保留完整可访问文本。Tooltip 应按设备能力提供:在支持 Hover 的精确指针设备启用 Hover;键盘用户使用 Focus;触屏用户通过点击或详情方式获得全文。若元素已经有完整可访问名称,不要造成重复朗读。
5. 导航状态模型
按生命周期管理导航状态:
- 共享状态:路由、导航配置、选中项、权限。
- 可持久用户偏好:例如桌面侧栏折叠状态。
- 临时 UI 状态:例如移动端 Drawer 开关,通常不持久化。
不要求将这些状态合并为同一个变量或存储机制。状态应按平台预期初始化、关闭和恢复。
6. CSS Cascade Layers 与样式治理
NEX 不要求所有项目使用 CSS Cascade Layers。若项目同时使用 utility classes、普通 CSS、CSS Modules、组件库样式或 @layer,先绘制实际优先级关系并识别是否存在可复现冲突。
只有在发现覆盖失效、断点规则被压制、主题回归或长期维护问题时,才按最小范围治理。大规模迁移必须有影响清单、回归矩阵和回滚方案。禁止仅为了让所有样式“形式上都在 layer 内”进行全量重写。
7. Bundle 与 CSS 性能治理
性能判断应结合项目预算和用户路径,不设跨项目通用的 chunk 字节阈值。分析至少包括:
- 初始入口和路由依赖关系;
- 大型依赖和重复打包;
- 原始、Gzip/Brotli 体积(若工具支持);
- 首屏是否加载非首屏模块;
- 路由级懒加载是否有真实收益;
- CSS 是否阻塞关键渲染或包含大量非首屏样式;
- 优化前后加载行为和缓存影响。
不得只为消除警告提高阈值,也不得没有分析就手工拆成大量 chunk。每项优化需记录数据和回归结果。
8. 语义与行为质量闸
质量探针不应只检查 DOM 标签或属性字符串。适用时至少检查:
- role / native semantics;
- accessible name;
- state(expanded、selected、checked、disabled、current 等);
- keyboard action;
- focus visibility/order/return;
- interaction result and status feedback;
- responsive visibility and access path。
静态探针可以验证源代码约束,但不能单独证明浏览器可访问树或实际读屏输出。优先采用浏览器可访问性树、自动化行为、键盘人工检查和真实 AT 记录组合验证。
9. 质量证据等级与日常默认流程
NEX 将无障碍验证分为四个证据等级,但四个等级不代表每次开发都必须逐级执行:
| 等级 | 名称 | 最低证据 | 可报告结论 |
|---|---|---|---|
| E0 | Source Reviewed | 源码、配置、HTML/ARIA 和组件实现审阅 | 实现中存在预期结构/属性;不能证明运行时表现 |
| E1 | Automated Checked | 实际运行的 Playwright、axe-core、单元/集成测试或语义探针结果 | 已覆盖规则的自动化检查通过;不能证明真实读屏体验 |
| E2 | Browser Interaction Verified | 指定浏览器中的键盘、指针/触屏实际操作记录 | 指定浏览器中的交互路径、焦点和反馈可用 |
| E3 | Assistive Technology Verified | 指定 OS + 浏览器 + 屏幕阅读器的真实操作与实际播报记录 | 仅该测试组合和测试范围中的 AT 体验通过 |
日常开发默认执行 E0–E2。 E3 是按风险和产品支持平台选择的专项测试,不要求每次代码修改、每个页面或每个项目都启动屏幕阅读器。浏览器自动化可以验证可访问树、名称/角色/状态、键盘脚本和 Live Region DOM 更新,但不能完整证明真实 AT 的播报、导航模式或快捷键处理。真实 AT 测试也不能替代 E0–E2 的常规回归。
E3 状态应明确区分:
E3_NOT_REQUIRED:完成风险评估后,当前功能/改动无需真实读屏验证,并记录理由;MANUAL_QA_REQUIRED:E3 已被判定必要,但当前环境、权限或设备不可用;E3_PASS/E3_FAIL:只在记录的真实环境中执行后填写。
不得因没有运行 E3 就将所有普通页面判为未验收;也不得对已判定 E3 必要的高风险交互,仅凭 ARIA 属性或自动化通过宣称无障碍验收完整。
10. E3 风险触发条件
优先评估以下场景是否需要 E3:
- 自定义拖拽、排序、画布、节点连接或复杂复合控件;
- 自定义 Tabs、菜单、复合导航、Tree/Grid 等键盘模型;
- 关键业务流程中使用复杂 ARIA 状态或自定义控件;
- 依赖 Live Region 完成重要异步反馈、任务进度或排序结果通知;
- 复杂数据表格、响应式表格转卡片后存在阅读顺序/关联风险;
- 已发现浏览器可访问树与实际播报可能不一致的问题;
- 项目明确声明支持特定辅助技术,或合同/法规/客户验收要求真实 AT 证据。
普通静态内容、原生 HTML 控件、低风险样式调整和没有改变可访问交互行为的常规代码修改,通常通过 E0–E2 即可。风险评估应考虑功能复杂度、用户影响、变更范围、已有缺陷和目标用户群,不能仅由 Agent 为减少工作量而跳过。
11. 跨操作系统屏幕阅读器选择
E3 应按产品真实支持范围选择操作系统、浏览器和屏幕阅读器组合,不得把 VoiceOver 当作唯一方案,也不得要求所有项目覆盖全部平台:
- macOS: VoiceOver;通常优先 VoiceOver + Safari,项目主要支持 Chrome 时按需增加 Chrome。
- Windows: NVDA;按产品支持范围选择 Firefox 或 Chrome/Edge。企业用户或合同有要求时可增加 JAWS;Narrator 可作为系统内置抽查工具。
- Linux: Orca;优先选择项目实际支持的 GNOME/AT-SPI + Firefox 组合;若 Chromium 是正式目标浏览器,再增加对应测试。
这些是测试选择建议,不表示不同 OS/浏览器/AT 组合等价。测试人员必须记录实际 OS/发行版/桌面环境、浏览器及 AT 版本。一次测试结果只对该组合有效。
如果 Agent 当前运行在 Windows 或 Linux,不应尝试启动 macOS VoiceOver;应根据目标平台选择可用的 NVDA 或 Orca。若环境没有相应 AT,完成可执行的 E0–E2,并将必要的 E3 标记为 MANUAL_QA_REQUIRED,由目标平台的测试机/人工 QA 完成。平台矩阵详见 docs/14-accessibility-platform-matrix.md。
12. 屏幕阅读器启停与用户授权
- 日常 UI 验收、Playwright 测试和页面巡检不得自动启动屏幕阅读器。
- 启动、关闭或切换 VoiceOver、NVDA、Orca 等系统辅助技术前,必须获得用户对本次 E3 测试的明确授权;一般的开发或 Computer Use 授权不自动包含这项授权。
- 测试前记录 AT 初始状态。若用户在测试前已启用屏幕阅读器,Agent 不得擅自关闭。
- 只可在用户授权范围内清理本次由 Agent 启动的 AT 状态;不得更改用户系统级偏好、自动启动设置、语音或快捷键。
- 如果无法确认当前状态或安全恢复,停止自动启停,改由用户/测试人员手动操作。
13. 报告要求
每次相关改造至少记录:
- 规则/组件/页面与风险评估理由;
- 目标平台、浏览器和视口;
- 测试数据集与数据对账结果(如适用);
- E0–E3 实际执行等级;
- 自动化命令和结果;
- E3 的 OS/发行版/桌面环境、浏览器、AT 名称及版本;
- 实际焦点路径、快捷键处理、真实播报内容和 Live Region 时序(如适用);
- 未执行项、环境限制、风险和后续复核条件。