nex_design_system/docs/08-accessibility-responsive.md

9.6 KiB
Raw Blame History

08. Accessibility & Responsive Quality

0. 无障碍基线与适用范围

NEX 将 WCAG 2.2 Level AA 作为 Web 产品默认的工程设计目标。项目如受法律、合同、采购规范或行业标准约束,应采用其中更严格或更具体的要求。此目标是工程基线,不代表仅凭自动化扫描即可宣称整站符合 WCAG,也不替代正式合规评估。

无障碍是产品质量要求,不是某一种屏幕阅读器或操作系统的专属功能。所有项目都应按适用性处理可感知、可操作、可理解和健壮性要求;具体实现可以使用原生 HTML、ARIA、组件库或项目既有机制。

日常开发和每轮变更的默认验收方式是:

  1. E0 源码/语义审阅;
  2. E1 自动化可访问性与行为测试;
  3. E2 浏览器键盘/指针交互验证。

E3 真实屏幕阅读器测试是按风险和目标平台选择的专项验证,不是每次代码修改、每个页面或每个项目都必须启动的常规步骤。E3 的操作系统与读屏器组合见 docs/14-accessibility-platform-matrix.md。Agent 未获明确授权,不得自行启动、关闭或更改用户的屏幕阅读器设置。

1. 语义优先与可访问名称

  • 触发动作使用原生按钮语义;页面跳转使用链接语义。避免用可点击 div / span 模拟按钮或链接,除非有充分理由且完整实现相应 ARIA、键盘和焦点行为。
  • 表单控件必须有准确、稳定的可访问名称;错误信息应与对应控件建立程序化关联。
  • 图标按钮必须有描述动作的可访问名称,名称应使用用户熟悉的业务语言。
  • 纯装饰图标必须从辅助技术名称计算中排除。 对 SVG/图标组件/图标字体等,使用项目适当的机制(例如 aria-hidden="true"),并防止图标内部字形名或组件名泄漏到可访问名称。
  • 图标与可见文本并列时,通常由可见文本提供名称,装饰图标不应重复朗读。只有图标本身承载唯一语义时,才为控件提供明确的可访问名称。
  • 不要把 upload、down、chevron-right 等图标库内部名称、字体字形名或代码标识直接拼进用户可读名称。

2. 截断文本和完整名称的多通道可用性

重要项目名称、状态、错误文本和关键字段即使视觉上截断,也必须保留完整内容,并按交互形态提供适当渠道:

  1. 辅助技术名称/文本: 完整内容应存在于可访问树或可展开内容中,不得只保留省略后的短文本。
  2. 键盘通道: 对可聚焦控件,Focus 时应能获取完整内容;非交互文本可按需提供可聚焦详情或相邻说明,不要无意义地让所有文本进入 Tab 顺序。
  3. 指针 Hover 通道: 仅在设备确实支持悬停时启用 Hover Tooltip。可用 @media (hover: hover) and (pointer: fine) 或项目等效能力检测,不能把 Hover 当作触屏能力。
  4. 触屏通道: 触屏用户应能通过点击、详情面板或其他明确方式获取完整内容,不能要求 Hover。

避免重复播报:如果可访问名称已经包含完整文本,不要再把 Tooltip 内容机械追加成第二份重复名称。title、Tooltip、aria-label 应根据元素语义选择,不应互相堆叠。

3. 键盘和焦点

  • 所有核心功能应可通过键盘访问。
  • Tab 顺序应与视觉和任务顺序一致;焦点必须清晰可见。
  • Enter / Space 的行为应符合控件语义。
  • 不得通过 CSS 全局移除焦点轮廓而不提供替代样式。
  • Modal、Drawer、Popover 等浮层应正确管理焦点进入、焦点返回和关闭行为。
  • 自定义快捷键应避开常见浏览器和辅助技术冲突;不能仅通过声明 aria-keyshortcuts 就认为用户已获得操作能力或读屏软件一定会播报。

4. 拖拽和复杂指针交互

任何依赖拖拽完成的核心操作都必须提供非拖拽替代路径,例如:

  • 通过按钮/菜单选择“上移/下移”或目标位置;
  • 通过键盘命令完成移动、排序或节点连接;
  • 提供可聚焦的操作控件和明确的状态反馈。

不能假设 HTML5 Drag and Drop API 自身就提供完整键盘体验。替代路径必须在功能上等价,不能只增加一个没有实际行为的快捷键说明。

对复杂排序、画布、流程编辑器和其他自定义复合控件,先通过 E0–E2 验证语义、键盘路径和操作结果;只有符合风险触发条件时,再安排 E3 真实屏幕阅读器验证。无法执行已判定必要的 E3 时,标记 MANUAL_QA_REQUIRED,不得宣称该 AT 组合已通过。

5. 响应式断点治理

  • 优先复用项目既有断点和组件库响应式规则。
  • 新增断点必须有真实布局需求,不得只为绕过单页 CSS 问题而临时散落媒体查询。
  • 允许项目定义超出基础断点阶梯的命名断点。每个断点必须在项目断点登记表中记录名称、数值/范围、用途、权威来源、受影响页面/组件和边界测试。
  • 必须测试断点前、断点处和断点后;具体视口由实际断点决定,不强制所有项目使用同一组设备宽度。
  • 不应简单缩小桌面布局来冒充移动端体验。导航、标题、工具栏、表格、表单和多栏工作区应按任务设计变形。
  • 避免无意的整页横向滚动;只有宽数据集、时间线或画布确有需要时,才在明确容器内横向滚动。

6. 窄屏数据表格治理

窄屏下表格不得仅靠扩大外层容器或隐藏任意列来“通过”检查。应先按数据任务识别列的重要性:

  • Primary: 识别记录和完成核心任务所必需的字段;不得无说明地隐藏。
  • Secondary: 影响判断但非首屏必须的字段;可移入展开详情、次级面板或按需查看区域。
  • Tertiary: 辅助、低频或装饰性字段;可在窄屏降级展示,但必须保留合理获取方式。
  • Actions: 行级操作;评估是否收纳为操作菜单,避免动作簇挤占数据列。

可按表格特点选择:

  1. 保留核心列并将次要信息移入行详情/展开区;
  2. 对键值型或对象摘要型数据改为卡片/记录列表;
  3. 对需要横向比较的密集数据保留局部横向滚动,并提供明确的滚动线索;
  4. 对重要标识列使用固定列,但必须检查窄屏剩余可视宽度;
  5. 将多个行内动作合并为菜单或次级操作区;
  6. 对长文本使用合理换行、截断加完整内容通道或详情查看。

每个表格必须单独选择策略。保留语义化表格时,应检查表头关联、行列阅读顺序、排序/选择状态和滚动容器;卡片化时,应保证每条记录的字段标签、值和操作关系仍然清楚。

6.1 数据对账(必须)

响应式改造后必须进行数据对账,不能只看截图或 tableaudit 是否通过:

  • 使用同一组代表性数据对比宽屏和窄屏视图;
  • 核对记录数量、关键字段值、字段与记录对应关系、排序/筛选结果;
  • 对隐藏或折叠字段确认存在可达的完整查看路径;
  • 核对每行操作是否仍可访问且操作对象正确;
  • 检查长文本、空值、极值、状态标签和权限差异;
  • 对屏幕阅读器检查表头/标签、单元格或卡片阅读顺序,避免重复或丢失信息。该项进入 E3 的条件由风险和平台支持范围决定,不要求每次表格样式调整都启动读屏器。

检查脚本可以辅助发现宽度、溢出和结构问题,但不得因测试规则不适配就放宽规则掩盖数据缺失。

7. 导航状态生命周期

桌面折叠偏好与移动端 Drawer 打开状态通常属于不同状态:前者可持久化,后者是临时交互状态。可以共享路由、导航定义和当前选中项,但不要求共用一个状态变量或持久化策略。刷新页面后移动端抽屉通常应关闭。

8. CSS 层叠与性能优化的边界

  • NEX 不强制项目使用 CSS Cascade Layers,也不要求将所有自绘样式迁入某个 @layer。
  • 对未分层样式、utility class 和媒体查询之间的优先级,应先记录实际层叠模型。只有存在可复现的冲突、回归或维护成本时,才做针对性治理;不得为形式统一进行全量迁移。
  • Bundle 或 CSS Chunk 体积应结合初始加载路径、路由、压缩后大小、缓存和实际性能预算评估。
  • 不得仅为消除构建警告而提高阈值;也不得在没有依赖分析和加载证据时盲目配置分包。
  • 优先识别可延迟加载的路由/模块,并比较优化前后的初始资源和实际行为。

9. 动效和偏好

  • 尊重 prefers-reduced-motion 或目标平台等效设置。
  • 避免闪烁、持续运动和不必要的空间位移。
  • 动效不应造成焦点丢失、滚动位置跳变或操作延迟。

10. 建议验收

日常 UI/UX 变更按适用性优先执行 E0、E1、E2:

  • 交互语义、可访问名称和装饰图标是否被正确隐藏;
  • Playwright/axe 等自动化可检测问题(若项目工具链支持);
  • 键盘路径、可见焦点、焦点进入/返回;
  • 截断内容的辅助技术文本、键盘、Hover 能力检测和触屏渠道;
  • 拖拽替代路径;
  • 自定义断点登记及边界测试;
  • 窄屏表格数据对账;
  • 导航状态持久化行为;
  • CSS Layer/Bundle 优化的实际证据;
  • 减少动态效果设置。

E3 仅在 docs/12-responsive-accessibility-quality.md 定义的风险条件满足时安排。按项目实际支持的操作系统选择 VoiceOver、NVDA、Orca 等对应工具;不得因为开发机是某个系统,就假定所有用户都使用该系统,也不得要求所有项目覆盖全部读屏器组合。