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

193 lines
11 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.

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