nex_design_system/docs/12-responsive-accessibility...

11 KiB
Raw Blame History

12. Responsive, Accessibility & Quality Evidence Governance

1. 本文目的

本文将 NEX 的响应式、可访问性和质量闸要求转化为可登记、可测试、可审计的项目规则。它不指定统一像素断点、屏幕阅读器、CSS 技术或 Bundle 阈值;项目应依据用户群、支持平台和实际实现确定具体值。

2. 响应式断点注册机制

2.1 基本原则

  • 先复用项目现有断点体系。
  • 仅当真实布局约束无法通过现有断点合理表达时,才新增命名断点。
  • 命名断点应表达布局状态或设计意图,而不只是设备名称(例如 compact-workspace 优于 iphone-width)。
  • 断点定义必须集中在项目认可的权威位置;组件级例外应登记,不得散落为不可追踪的媒体查询。
  • 不为减少断点数量而接受内容遮挡、字段丢失、操作不可达或明显不合理的视觉回退。

2.2 登记字段

每个断点记录:

  1. 名称;
  2. CSS 条件和值(min-width/max-width/范围/容器查询);
  3. 解决的问题与设计理由;
  4. 影响的 Shell、页面和组件;
  5. 权威定义文件/Token/主题位置;
  6. 与相邻断点的布局差异;
  7. 断点前、断点处、断点后的测试宽度;
  8. 证据、批准来源和复审条件。

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 时序(如适用);
  • 未执行项、环境限制、风险和后续复核条件。