无障碍 spec-test 编写系统规范¶
意图¶
使用 Astryx 组件的用户应当获得 WCAG 2.2 与 WAI-ARIA Authoring Practices 所承诺、且 Astryx 采纳的键盘、焦点、含义和状态。可复用的无障碍规范测试将这些承诺转化为可审查的契约,而不要求每个组件作者重新解释这些标准。
一条规范测试陈述一个用户可观察的需求,引用其来源,指明能够证明它的证据层,并在每个符合的绑定上原样运行。该测试套件补充 axe、浏览器检查和辅助技术审查。它并不声称一次自动化通过就证明完全无障碍。
非目标¶
- 在本规范拉取请求中实现 spec-test 包或 CI 任务。
- 定义现有组件测试如何迁移;该事项由 AST-021 负责。
- 将首个实现作为受支持的包发布。
- 重新实现 axe 规则,或替代浏览器、视觉、手动或真实辅助技术(real-AT)验证。
- 将 WAI-ARIA Authoring Practices 视为 WCAG 合规性的替代品。
- 在 WCAG 3.0 工作草案就绪之前将其用作通过/失败基线。
- 当组件无法满足页面级别的需求时,将这些需求编码进孤立的组件契约中。
要求¶
规范基础与范围¶
- FR1 — WCAG 2.2 A 和 AA 是合规基线。 每个 WCAG 合规期望 MUST 引用适用的 WCAG 2.2 A 级或 AA 级成功标准。当 APG 提供交互细节时,模式期望可以改为引用精确的 APG 要求。在这种情况下,它 MUST 标识其所支持的 WCAG 2.2 用户结果,且不得凭空捏造成功标准映射。WCAG 3.0 原则可以用来说明平实语言意图、用户需求和未来研究,但 WCAG 3.0 草案要求 MUST NOT 在没有后续且当前的 Astryx 记录的情况下创建或清除通过/失败检查。
- FR2 — APG 定义的是所采纳的构件模式,而非普适合规。 当 Astryx 采用 WAI-ARIA APG 模式时,模式契约 MUST 引用它所采用的精确 APG 角色、状态、属性或键盘交互,以及这些机制所支持的 WCAG 2.2 结果。仅当组件当前的组件、组件族或系统契约记录该选择时,组件可以使用另一种符合标准的模型;规范测试 MUST 遵循所属契约,而不是机械地套用某个 APG 示例。
- FR3 — 契约包含两层。 每次模式审查 MUST 同时考虑两者:适用于多种模式的、由组件持有的宽泛需求;以及模式特定的角色、状态、关系、键盘和焦点需求。组件的一部分可以绑定到多个模式。当组件的各个部分具有不同角色时,整个组件 MUST NOT 被强行塞入单一模式。
- FR15 — 采纳遵循组件已扮演的角色。 当组件的一部分已经扮演了某个 APG 模式的角色时,Astryx 会为它采纳该模式的必需部分:角色、无障碍名称、状态和关系属性,以及通过 Tab 加 Enter 或 Space 进行的激活。模式的可选键盘扩展——在部件之间用方向键移动、Home 和 End——仅在组件已经作为一个复合控件运作时才被采纳;一组可独立聚焦的控件不会获得这些扩展。所属组件记录需指明它采纳了哪些部分、未采纳的任何必需部分及原因,以及它在本规则之外采纳的任何额外部分,作为具名例外。
期望契约¶
- FR4 — 每条期望都可追溯。 一条期望 MUST 具有稳定的 id、简短的用户结果、精确的规范来源(WCAG 2.2 成功标准、APG 要求、当前 Astryx 契约或适用组合)、适用条件、证据层和执行类别。测试名称和失败输出 MUST 暴露期望 id 和来源引用,以便无需打开运行器实现即可理解失败。
- FR5 — 适用性是显式的。 对于每个清单维度,作者 MUST 要么编码一条适用的期望,要么记录为什么该维度不由这个模式、绑定或证据层拥有。沉默不是豁免。豁免 MUST 指明实际所有者或验证方法;它 MUST NOT 是通用的“不适用”逃生舱。
- FR6 — 证据层保持不同的证明边界。 期望被分类为单元、DOM、无障碍树、axe、真实浏览器、视觉、lint、手动或真实辅助技术检查。较低层 MUST NOT 声称只有较高层才能观察到的结果。播报措辞或时机、虚拟光标进入以及已知的辅助技术/浏览器差异遵循 AST-009;无障碍树快照不能证明语音输出。
- FR7 — 契约断言结果,而非 Astryx 内部实现。 一条可复用的期望 MUST 通过公共语义和可观察行为进行查询和操作。它 MUST NOT 依赖 Astryx 类名、私有 DOM 包装器、实现回调或源码布局,除非所属的当前记录使该结构成为契约性的。组件特定的 API 效果仍留在组件测试中。
- FR8 — 交互期望证明完整的状态转换。 键盘、指针、状态和焦点期望 MUST 演练相关的起始状态、操作、结果状态,以及模式支持时的反向或关闭路径。仅找到角色或证明开关的一个方向是不够的。
- FR9 — 执行类别与严重性和工具覆盖范围相分离。 直接适用的 WCAG 2.2 A 级或 AA 级期望是
required。仅当当前 Astryx 记录采纳了该结果时,APG 或 Astryx 特定的期望才是required。Advisory期望报告最佳实践、未定选择或尚未作为 Astryx 契约采纳的结果。Advisory期望仅作报告;required期望在能够客观验证它们的层上把关新的或更改的行为。覆盖分数、工具能力或自动化难易程度 MUST NOT 提升或降级任一类别。
WCAG 2.5.2(指针取消)可通过在抬起(lift)之前取消滑出控件的按压来满足,只有一个狭窄例外:一个即时可逆的单步开关,即第二次激活可撤销第一次激活,它可以在指针滑离后在抬起时完成,从而通过其撤销路径满足 2.5.2。该例外涵盖 Switch、Checkbox 和 CheckboxListItem。它不涵盖 Radio、SegmentedControl、DropdownMenuCheckboxItem(其菜单行在从行上抬起后不对任何内容生效)、SelectableCard 或任何执行选择而非切换的控件;其他控件只能通过后来的决策加入,而每个其他在抬起时激活的控件都保持滑出取消(DEC-5),除非 DEC-6 涵盖它。SegmentedControl 是一个单轴控件,它改为沿其轴跟踪按压(DEC-6):返回到当前选择或按 Escape,会在抬起前将按压取回。
完整性与审查¶
- FR10 — 每个模式都使用一次完整性审查。 审查从下方的源映射开始,然后添加适用的 WCAG 2.2 组件结果,例如焦点不被遮挡、状态消息、目标大小、对比度、强制颜色以及模式的 APG 交互。仅当夹具或界面拥有页面时,才考虑页面拥有的行。每一行都遵循 FR5 和 FR6,而不是被强制纳入可复用运行时契约。
| WCAG 2.2 来源 | 需考虑的结果 | 通常归属 |
|---|---|---|
| 1.1.1 非文本内容 | 信息性非文本内容具有等效替代;装饰性内容被忽略。 | 组件或内容 |
| 1.3.1 信息和关系 | 视觉结构和关系可通过编程方式获得。 | 组件或组合 |
| 1.3.2 有意义的顺序 | 程序化阅读顺序保持含义不变。 | 组件或组合 |
| 1.4.1 使用颜色 | 颜色不是传达信息或状态的唯一方式。 | 组件、主题和调用方内容 |
| 1.4.3 对比度(最低) | 文本和文本图像满足所需的对比度。 | 组件和主题 |
| 1.4.11 非文本对比度 | 控件、状态和有意义的图形满足非文本对比度。 | 组件和主题 |
| 2.1.1 键盘 | 每个组件拥有的功能都可以通过键盘操作。 | 组件 |
| 2.1.2 无键盘陷阱 | 键盘焦点可以离开任何组件,除非用户有记录的退出方式。 | 组件或组合 |
| 2.4.2 页面标题 | 页面具有描述性标题。 | 仅页面 |
| 2.4.3 焦点顺序 | 顺序焦点保持含义和操作不变。 | 组件或组合 |
| 2.4.4 链接目的(在上下文中) | 链接的目的是可确定的。 | 组件和调用方内容 |
| 2.4.6 标题和标签 | 标题和标签描述其主题或目的。 | 组件和调用方内容 |
| 2.4.7 焦点可见 | 键盘焦点具有可见指示器。 | 组件和主题 |
| 2.4.11 焦点不被遮挡(最低) | 焦点内容不会被作者创建的内容完全隐藏。 | 组件或组合 |
| 2.5.8 目标大小(最低) | 指针目标满足最小尺寸或允许的例外。 | 组件或组合 |
| 3.1.1 页面语言 | 页面语言可通过编程方式获得。 | 仅页面 |
| 3.2.4 一致的标识 | 重复的功能被一致地标识。 | 系统、组件和调用方内容 |
| 3.3.2 标签或说明 | 输入具有持续的标签或所需的说明。 | 组件和调用方内容 |
| 4.1.2 名称、角色、值 | 名称、角色、状态、值和变更可通过编程方式获得。 | 组件 |
| 4.1.3 状态消息 | 状态变更在不移动焦点的情况下被暴露。 | 组件或组合 |
- FR11 — 契约本身具有正向和反向证明。 每个期望 MUST 在最低限度合规的夹具或绑定上通过,并在其所需结果被有意移除时失败。模式级测试 MUST 区分真实违规与不支持的测试工具操作或夹具错误。
- FR12 — 完成需要独立的可访问性审查。 只有当每个清单维度都被编码或明确分配到其他地方、所有期望都可追溯、代表性绑定通过或暴露确切已知差距、变异证据证明所需期望可能失败,并且可访问性主题专家审查者未发现未说明的、可编码为契约的要求时,模式才算完成。
- FR13 — 拉取请求以可读形式描述规范测试。 新增或实质性变更的模式拉取请求 MUST 说明受影响方、采用模式和范围、包含来源和证据层的期望表、明确豁免、代表性绑定和状态、已知组件差距,以及证明契约的变异或失败。描述是测试的可读规范;可执行契约仍然是经过校验的事实来源。
- FR14 — 稳定的 ID 在重构中得以保留。 重命名文件、辅助程序或测试工具 MUST 保持期望 ID 不变。拆分、合并、收窄或更改用户结果会为每个引用受影响 ID 的绑定和已知差距记录创建明确的契约变更和迁移。
平台支持¶
- 支持的功能/引擎下限:受影响组件在 AST-013 下的当前浏览器支持契约。
- 不支持的行为:无法观察所分配证据层的测试工具会报告该限制;它不会通过、静默跳过,也不会用较低层代替。
- 浏览器证据:浏览器类期望在真实发布的引擎中运行。DOM 模拟器无法证明焦点导航、原生顶层行为、计算后的可访问性树暴露、对比度、目标几何或强制颜色绘制。
当前状态影响¶
Issue #4112 确立了可复用的模式契约(pattern-contract)方向。已关闭的 Switch 原型 演示了同一契约贯穿 jsdom 与 Chromium 绑定、源代码关联的预期 id,以及精确的已知失败。它还说明了为什么 axe 与模式契约是互补的:axe 发现大范围的标记违规,而契约验证的是让开关(switch)像开关一样运作的状态与交互。
该原型是证据,而非现行策略。除非本记录或其他现行记录采纳它们,否则其包名、评分模型、优先级名称和 harness 形态仍属实现选择。本规范保留了经过验证的契约边界,同时在大规模推广前修正两个风险:数字评分不得代替一致性(conformance),且每个预期必须指明能够实际观察其结果 的证据层级。
完整性审查纳入了反复出现的组件自有失败类型,如文本替代方案、语义关系与顺序、焦点顺序与可见性、描述性标签与链接、一致的标识、持续出现的说明,以及名称/角色/值/状态。该审查更新至 WCAG 2.2,并在边界确属如此的情况下,将页面自有、浏览器自有和真实辅助技术(AT)自有的检查排除在组件运行时契约之外。
本已接受的规范不创建测试、包、CLI 文档、组件行为或 CI 门禁。这些变更随后在受本记录约束的实现工作中跟进。
验证¶
| 契约 | 验证方式 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1–FR3 | 依据 WCAG 2.2、APG 及当前 Astryx 记录进行来源与归属审查 | 组件自有的 A/AA 标准;页面自有的标准;一个包含多个部分的组件 | 一份草稿状态的 WCAG 3.0 声明被用作 CI 门禁、APG 示例被当作普适 WCAG 规则对待,或将一个组件强行归入单一模式 |
| FR4–FR9 | 契约 schema 与 runner 自测 | required/advisory;unit/DOM/tree/axe/browser/manual/AT;toggle 往返;组件专属回调;Switch、Checkbox、CheckboxListItem、Radio 和 DropdownMenuCheckboxItem 上的滑离式抬起(slide-off lift);SegmentedControl 上的漂移(drift) | 某项检查缺少来源或层级、从不被支持的 harness 通过、依赖私有标记,或单向行为掩盖了反向路径的失败;在例外范围之外,滑离式抬起完成了由抬起激活的控件——此类情况均判定失败 |
| FR10–FR12 | 完成的检查清单、正向/负向 fixture 套件及独立审查 | 简单控件;复合组件;覆盖层;页面自有标准 | 某个维度被静默移除、某项变更仍然通过,或审查发现未记录的、可编码为契约的需求 |
| FR15 | 对照组件当前的角色声明进行采用审查 | 仅采纳必需部分的 disclosure 集合;采纳方向键的复合控件;命名异常 | 在缺少所属记录理由的情况下跳过必需部分,或在没有命名异常的情况下为可独立聚焦的控件添加方向键 |
| FR13–FR14 | 拉取请求模板检查及 id 迁移测试 | 新模式;收窄后的预期;仅涉及文件的重构 | 审查者无法从 PR 中理解测试,或 id 变更使绑定和间隙成为孤儿(orphan) |
| Platform | 真实浏览器与 AST-009 证据边界检查 | 焦点导航;无障碍树;强制颜色;公告时机 | jsdom 或树快照被认定能够观察到其无法观察的像素、浏览器行为或语音输出 |
完成标准¶
本规范只有在以下条件全部满足时,才会从 accepted 转为 shipped:
- 可复用的契约 schema 对 FR4–FR6 和 FR9 实施强制校验;
- 编写指南和拉取请求模板落实 FR10–FR13;
- 契约自测包含 FR11 下符合规范的夹具以及刻意违反规范的夹具;
- 至少有一个模式在具有代表性的 jsdom 与浏览器绑定上运行,且不依赖 Astryx 私有结构;
- 不支持的测试工具能力应如实失败,而不是通过或跳过;
- 不得将任何聚合覆盖率分数作为一致性证明;以及
- 已发布的指南链接 AST-009 用于真实辅助技术(AT)声明,并链接 AST-021 用于迁移。
决策日志¶
DEC-1 — 采用 WCAG 2.2 作为一致性依据,WCAG 3.0 仅用于前瞻性意图¶
参考: spec:AST-020/DEC-1
决策者: cixzhang,2026-09-03
WCAG 2.2 的 A 级和 AA 级提供了当前可测试的基线。WCAG 3.0 有助于界定用户需求、辅助技术体验和未来评估,但其工作草案并不决定当前的通过/失败结果。
已否决:等待 WCAG 3.0,或将草案结果视为当前的一致性要求。
DEC-2 — 为每个已采用模式编写一份可复用的结果契约¶
参考: spec:AST-020/DEC-2
决策者: cixzhang,2026-09-03
将源自标准的模式契约与组件绑定分离。这样多个组件可以共享同一种解释,同时允许某个组件的各个部分绑定到不同模式,并将组件特有的 API 行为保持在本地。
已否决:将 APG 断言复制到每个组件测试中,或强制把所有无障碍检查塞进一个全局扫描器。
DEC-3 — 让拉取请求成为可执行测试的可读规范¶
参考: spec:AST-020/DEC-3
决策者: cixzhang,2026-09-03
评审者必须能够在不需要逆向工程运行器代码的情况下,判断用户结果、标准依据、证据层、豁免项、绑定和变异证明。被检入的契约仍然是可执行的事实;拉取请求让这一事实可供无障碍专家和维护者评审。
已否决:仅审查代码,或采用一份与可执行预期没有精确映射的通用无障碍检查清单。
DEC-4 — 采纳组件已有的形态¶
参考: spec:AST-020/DEC-4
决策者: cixzhang,2026-10-13
模式的必需部分归属于任何已经在扮演该模式角色的组件部分,因为用户一旦与该角色交互,就会预期其名称、状态和激活方式。其可选的附加键盘功能只属于一个复合控件,因为方向键和 Home/End 是在同一个控件内移动;独立控件则保持页面的 Tab 顺序。一个已经带有附加功能的组件,应将其记录为具名异常,而不是丢失该功能。
已否决:只要角色出现就采用模式的所有部分(例如在独立控件上使用方向键);或者在组件完全匹配某个 APG 示例之前什么都不采用。
DEC-5 — 可反转的切换控件可在滑离之后完成¶
参考: spec:AST-020/DEC-5
决策者: cixzhang,2026-10-26
当手指滑离后,在抬起时完成切换的 Switch 或 Checkbox 可以通过再次激活来撤销,这是 WCAG 2.5.2 所接受的,并且与 UIKit 的 UISwitch 一致。该异常明确列出其类型,因此没有新的决策就不能扩大范围;像 Radio 和 SegmentedControl 这类用于选择的控件,则继续保持滑离取消,因为再次激活并不能撤销它们。
已否决:所有控件一律采用滑离取消,不设任何例外。
DEC-6 — 单轴控件在漂移后仍沿其轴继续选择¶
参考: spec:AST-020/DEC-6
决策者: cixzhang,2026-11-09;鼠标和手写笔,2026-11-10
设计评审是这样要求的:
“不过我真的希望它能更宽容一些”,以及
“比如把分段控件竖直拖出控件后,在我松开之后仍应能设置那个值”。
也就是说,沿垂直方向拖离控件的拖动,在抬起时仍会选择某个值。因此,选项沿单轴排列的控件会跟踪该轴上的按压。
偏离该轴的漂移永远不会取消选择;抬起时会根据指针沿轴的位置选择选项,并钳制在两端选项上。它通过中止和撤销来满足 WCAG 2.5.2:在抬起前回到当前选择,或按 Escape,均会让按压恢复原状;选择原来的选项即可撤销。浏览器的取消事件(pointercancel)也能将其恢复。该决策仅涵盖 SegmentedControl;其他控件需由后续决策加入。它取代了 DEC-5 中关于 SegmentedControl 的条款;DEC-5 对其余列名控件仍然有效。该规则同样适用于鼠标、手写笔和手指。
已否决:在控件外固定距离处设置取消区域;对单轴控件采用滑离取消。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx