axe-rules

Axe-Core 规则参考技能

权威来源：mgifford/ACCESSIBILITY.md 中的 examples/AXE_RULES_REFERENCE.md 和 examples/AXE_RULES_COVERAGE.md 此技能根据这些文件整理。如有疑问，以示例为准。 **注意：**权威文件围绕一个特定的测试夹具扫描器项目（带编号的测试页面）编排。本技能以通用参考的形式重新呈现相同的规则集和严重程度，不依赖任何特定的测试夹具。

编写、审查或调试 axe-core 扫描时，请遵循这些规则。

---

核心原则

Axe-core 可自动检测约 30–40% 的 WCAG 问题。它是基线，而非上限。务必将自动扫描与手动键盘测试和屏幕阅读器测试结合起来。

axe-core 的结果是证据，不是符合性判定。 完全保留规则的原始结果（violations、incomplete、passes、inapplicable），与 axe 报告的内容完全一致——将其转换为项目发现时，不要覆盖或丢弃这些结果。引用本文件、AXE_RULES_REFERENCE.md 或规则自己的 dequeuniversity.com/rules/axe/ 页面作为 WCAG 映射的依据；不要编造 axe-core 未为该规则记录的映射。对于未经审查的 violations 结果，应记录为 evidence_status: automated-indicator，并设置 handling: review——在人类确认之前，绝不能将其视为已确认的标准违规。请参阅无障碍发现跟踪：策略分类。

扫描中应包含的关键标签：

.withTags(['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa'])

Axe-core 4.11 在以下类别中包含 100 多项自动化检查：WCAG 2.0 A/AA（68 条规则）、WCAG 2.1 A/AA（26 条规则）、WCAG 2.2 A/AA（1 条规则，默认禁用）、最佳实践（30 多条规则）、WCAG AAA（3 条规则，默认禁用）、实验性（9 条规则，默认禁用）和已弃用（7 条规则，默认禁用）。

---

严重程度等级（axe-core）

axe 严重程度	含义
critical	阻碍一个或多个残障群体访问
serious	严重影响访问
moderate	造成不便，但存在变通方法
minor	最佳实践方面的不足；影响较小

---

严重规则——绝不能出现在生产环境中

规则 ID	类别	描述
image-alt	文本替代项	<img> 缺少 alt 属性
area-alt	文本替代项	图像映射 <area> 缺少替代文本
input-image-alt	文本替代项	<input type="image"> 缺少 alt
video-caption	文本替代项	<video> 没有字幕
aria-allowed-attr	ARIA	元素具有其角色不支持的 ARIA 属性
aria-hidden-body	ARIA	将 aria-hidden 应用于 <body>
aria-required-attr	ARIA	缺少必需的 ARIA 属性
aria-required-children	ARIA	缺少必需的子级 ARIA 角色
aria-required-parent	ARIA	缺少必需的父级 ARIA 角色
aria-roles	ARIA	ARIA 角色值无效
aria-valid-attr	ARIA	ARIA 属性名称无效
aria-valid-attr-value	ARIA	ARIA 属性值无效
label	表单	表单输入框没有关联的 <label>
select-name	表单	<select> 没有可访问名称
button-name	按钮/链接	按钮没有可辨识的文本
input-button-name	按钮/链接	<input type="button"> 没有文本
duplicate-id-aria	结构	被 ARIA 引用的 id 值重复
meta-refresh	元数据	<meta http-equiv="refresh"> 会导致定时重定向

---

严重规则 — 发布前修复

规则 ID	类别	描述
object-alt	文本替代	<object> 缺少可访问文本
svg-img-alt	文本替代	带有 role="img" 的 SVG 缺少可访问名称
role-img-alt	文本替代	带有 role="img" 的元素缺少替代文本
aria-braille-equivalent	ARIA	盲文标签缺少非盲文等效内容
aria-command-name	ARIA	按钮、链接或菜单项缺少可访问名称
aria-conditional-attr	ARIA	ARIA 属性的用法违反角色规范
aria-hidden-focus	ARIA	aria-hidden 元素包含可聚焦内容
aria-input-field-name	ARIA	ARIA 输入字段缺少可访问名称
aria-meter-name	ARIA	ARIA meter 元素缺少可访问名称
aria-progressbar-name	ARIA	ARIA progressbar 元素缺少可访问名称
aria-prohibited-attr	ARIA	使用了禁止的 ARIA 属性
aria-toggle-field-name	ARIA	ARIA 切换字段缺少可访问名称
aria-tooltip-name	ARIA	ARIA 工具提示缺少可访问名称
aria-dialog-name	ARIA	对话框缺少可访问名称
aria-treeitem-name	ARIA	树项目缺少可访问名称
color-contrast	颜色	文本对比度低于 4.5:1（普通文本）或 3:1（大号文本）
frame-title	框架	<iframe> 缺少可访问名称
frame-title-unique	框架	框架标题不唯一
frame-focusable-content	框架	包含可聚焦内容的框架使用了 tabindex="-1"
html-has-lang	语言	<html> 缺少 lang 属性
html-lang-valid	语言	lang 属性的值不是有效的 BCP 47 值
valid-lang	语言	内联 lang 值无效
document-title	语言	缺少 <title> 元素
list	结构	<ul>/<ol> 包含 <li> 以外的元素
listitem	结构	<li> 位于 <ul> 或 <ol> 之外
definition-list	结构	<dl> 包含 <dt>/<dd> 以外的元素
dlitem	结构	<dt>/<dd> 位于 <dl> 之外
bypass	键盘	未提供跳过导航机制
scrollable-region-focusable	键盘	滚动区域无法通过键盘访问
link-name	按钮/链接	链接缺少可辨识文本
link-in-text-block	按钮/链接	链接无法与周围文本区分
avoid-inline-spacing	内容尺寸	文本间距覆盖设置无法调整
autocomplete-valid	表单	autocomplete 属性无效或缺失
tabindex	最佳实践	使用了大于 0 的 tabindex 值
label-title-only	最佳实践	表单字段仅通过 title 属性标注
label-content-name-mismatch	最佳实践（实验性）	可见标签文本与可访问名称不匹配
td-has-header	表格（实验性）	大型表格单元格缺少关联的表头
table-fake-caption	表格（实验性）	表格标题未使用 <caption> 标记
p-as-heading	最佳实践（实验性）	段落被设置样式以呈现为标题

---

中等规则 — 纳入近期待办修复

规则 ID	类别	描述
heading-order	标题	标题级别跳跃（例如，h1 → h3）
empty-heading	标题	标题没有可辨识的文本
th-has-data-cells	表格	表头没有关联的数据单元格
td-headers-attr	表格	表格单元格引用了无效的表头 ID
meta-viewport	Meta	视口的 user-scalable=no 会禁用缩放
html-xml-lang-mismatch	语言	lang 和 xml:lang 属性不一致
form-field-multiple-labels	表单	表单字段有多个相互冲突的标签
landmark-one-main	最佳实践	页面没有 <main> 地标
landmark-banner-is-top-level	最佳实践	banner 地标不在顶层
landmark-contentinfo-is-top-level	最佳实践	contentinfo 地标不在顶层
landmark-main-is-top-level	最佳实践	main 地标不在顶层
landmark-no-duplicate-banner	最佳实践	存在多个 banner 地标
landmark-no-duplicate-contentinfo	最佳实践	存在多个 contentinfo 地标
landmark-no-duplicate-main	最佳实践	存在多个 main 地标
region	最佳实践	地标区域之外存在内容
page-has-heading-one	最佳实践	页面没有 <h1>
scope-attr-valid	最佳实践	scope 属性的值无效
accesskeys	最佳实践	accesskey 的值不唯一

---

轻微规则

规则 ID	类别	描述
table-duplicate-name	表格	<caption> 文本与 summary 属性重复
aria-deprecated-role	ARIA	使用了已弃用的 ARIA 角色
server-side-image-map	键盘	使用了服务器端图像映射
aria-text	ARIA（最佳实践）	对包含可聚焦后代元素的元素使用 role="text"

默认禁用的规则（已弃用的 marquee/blink/audio-caption）未在上方列出——如果遇到，请标记，但这些规则在默认扫描中不会启用。

axe-core 默认禁用的三条 WCAG AAA 规则，其报告针对的是项目 AA 目标不要求的级别。如果启用了这些规则，而项目尚未声明更广泛的目标，则将这些规则确认发现的问题分类为 obligation: aspirational，而不是 advisory——这仍然是真实的 AAA 级问题，只是不属于 AA 基线。不要将满足其中一条规则报告为符合 WCAG AAA。

---

在 CI 中运行 axe-core（Playwright）

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('No WCAG 2.x AA violations', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa'])
    .analyze();
  expect(results.violations).toEqual([]);
});

常见配置选项：

// Exclude a specific element (use sparingly — document the reason)
.exclude('#known-false-positive')

// Include only a specific element
.include('#component-under-test')

// Disable a specific rule (document the reason and JIRA/issue link)
.disableRules(['color-contrast'])

---

完成标准检查清单

• 每个 PR 都会运行带有 wcag2a、wcag2aa、wcag21aa、wcag22aa 标签的 axe-core 扫描
• 生产代码中不存在严重违规
• 生产代码中不存在较严重违规（或附带问题链接的明确豁免）
• 所有规则排除项均已记录原因和相关问题
• 浅色和深色配色方案均已测试
• 已测试移动端视口
• axe 结果已作为 CI 构建产物发布，供参考

---

关键 WCAG 标准（自动化覆盖范围）

• 1.1.1 非文本内容（A）
• 1.3.1 信息和关系（A）
• 1.4.3 对比度最低要求（AA）
• 2.4.2 页面标题（A）
• 3.1.1 页面语言（A）
• 4.1.2 名称、角色、值（A）
• 4.1.3 状态消息（AA）——部分覆盖

自动化可覆盖约 30–40% 的 WCAG 问题。务必结合手动测试。

---

参考资料

• 完整的 axe 规则参考
• Axe 规则覆盖范围摘要
• axe-core 规则说明
• @axe-core/playwright
• axe-core GitHub

标准展望： 这些规则针对 WCAG 2.2 AA。 请关注：https://www.w3.org/TR/wcag-3.0/