跳转至

无障碍 spec-test 编写系统规范

{
  "scope": "global",
  "triggers": {
    "accessibility": ["FR1", "FR2", "FR6", "FR15"]
  }
}

意图

使用 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