nex_design_system/docs/08-accessibility-responsive.md

133 lines
9.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 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 等对应工具;不得因为开发机是某个系统,就假定所有用户都使用该系统,也不得要求所有项目覆盖全部读屏器组合。