无障碍回归审计 Prompt:12 个 axe-core 之外的模板

axe-core 只能自动发现约 57% 的 WCAG 问题。12 个可直接复制的 Prompt:键盘顺序、焦点管理、屏幕阅读器文案、WCAG 2.2 热区尺寸、动效偏好。

Deque 在 2024 年做的覆盖率研究(1.3 万+ 页面、约 30 万条问题)得出一个关键数字:axe-core 这类全自动工具大约只能查出 57% 的 WCAG 问题。剩下约 43% 恰恰是真正伤到用户的那部分——焦点陷阱、缺少 live region、键盘顺序乱、动效诱发癫痫,这些在 CI 里都不会变成一条红线。下面这些 Prompt 把失败模式直接交给大模型(Claude Opus 4.7、GPT-5.5 都能读懂 diff 和组件代码),并强制它给出复现步骤、file:line 定位和修复方案,而不是一句空泛的”建议改善无障碍”。

TL;DR

  • 先跑 axe-core。 它能把那约 57% 机器可验证、几乎不误报的问题清掉。别用 AI 的 token 去重复找对比度 bug。
  • 这 12 个 Prompt 留给剩下的约 43%: 键盘 Tab 顺序、路由切换焦点管理、屏幕阅读器朗读、WCAG 2.2 热区尺寸、prefers-reduced-motion
  • 以 WCAG 2.2 AA 为目标。 它是 W3C 当前的正式推荐标准(2023 年 10 月发布),新增了多数团队会漏的六条 AA 准则,包括热区最小尺寸 24×24 CSS 像素 和”焦点不被遮挡”。
  • 合规已进入强制执行期。 欧盟无障碍法案(EAA)的截止日已在 2025 年 6 月 28 日过去,其推定标准 EN 301 549 对应 WCAG 2.1 AA,罚则最高可达 10 万欧元或营收的 4%。

适合哪些场景

要满足 WCAG 2.2 AA 的消费类应用工程师、做 a11y 评审的设计师,以及投政企单子、需要一份正式审计报告的创业团队。如果你在 2025 年 6 月之后向欧盟市场销售,无障碍已经是法律要求,不再是加分项。

WCAG 2.2 新增了哪些 axe-core 难以完整检查的内容

WCAG 2.2(W3C 当前正式推荐标准)新增了九条成功准则,其中六条落在多数组织瞄准的 AA 等级。对回归审计最关键、又最难自动测的有三条:

准则等级规则工具为什么吃力
2.4.11 焦点不被遮挡(最低)AA获得焦点的元素不能被作者内容完全盖住要在运行时判断吸顶栏/Cookie 横幅是否压住焦点环
2.5.7 拖拽动作AA任何拖拽操作都要有单指点击的替代方式工具看不出拖拽把手背后的意图
2.5.8 热区最小尺寸AA热区 ≥ 24×24 CSS 像素,或留足间距padding、行内例外、间距计算都很容易算错

注意这个数字:WCAG 2.2 把下限定在 24×24 CSS 像素,而不是 44。44×44 是 Apple《人机界面指南》的推荐值,Material Design 建议 48×48 dp——这两个都是高于法定底线的良好设计目标。

12 个可直接复制的 Prompt 模板

把你的 diff 或组件代码贴在每个 Prompt 下面。每条都点名一个具体失败模式,并要求给出 file:line 和严重程度,让输出可执行而不是泛泛而谈。

1. PR 范围 a11y diff

Audit this PR for a11y regressions in the diff only. Cover: (1) New interactive elements without keyboard handlers, (2) `role="button"` on non-buttons missing key handlers, (3) Removed aria-labels, (4) Decorative imagery added without `alt=""`, (5) Heading order broken. Output file:line + severity (blocker/major/minor). Skip unchanged code.

2. 键盘顺序验证

For `[componentName]`, describe the keyboard tab order step by step (Tab / Shift+Tab / Enter / Esc / Arrow keys). Flag: (1) Focus skipping a logical element, (2) Focus moving into invisible content, (3) Tab order that doesn't match visual order, (4) Esc that doesn't close a modal, (5) Focus not returned to the trigger on close.

可替换变量: [componentName]

3. 屏幕阅读器朗读文案

Audit what a screen reader (NVDA/VoiceOver) will announce for `[componentName]`: (1) Accessible name (label / aria-label / aria-labelledby), (2) State announcements (selected / expanded / loading), (3) Live region for async results, (4) Icon-only buttons get a visible-or-aria name. Output a script-like trace of expected announcements per interaction.

可替换变量: [componentName]

4. 表单错误无障碍

Audit this form's error UX: (1) Errors associated via `aria-describedby` to the right input, (2) Submission summary at top with anchor links, (3) Live region announces error count, (4) Focus moves to first invalid field on submit, (5) Errors don't rely on colour alone. Output file:line.

5. 路由切换的焦点管理

For this SPA, audit focus management on navigation: (1) Does focus move to the new page's main heading? (2) Is the page title announced? (3) Are skip-links present and working? (4) Does focus survive modal open/close? Output failures + a fix recipe per page.

6. 焦点不被遮挡(WCAG 2.2, 2.4.11)

Audit WCAG 2.2 SC 2.4.11 Focus Not Obscured (Minimum). Identify any sticky header, cookie banner, chat widget, or toast that can fully cover a focused element when tabbing. For each: name the overlapping component, the elements it can hide, and a scroll-padding or focus-scroll fix. file:line.

7. 动效 + prefers-reduced-motion

Audit motion: (1) Any animation > 5s that loops without pause/stop? (2) Flashing > 3 times per second (seizure risk, WCAG 2.3.1)? (3) Parallax or autoplay video without controls? (4) Is `prefers-reduced-motion` honoured for every transition/animation? Output file:line + fix.

8. diff 内对比度检查

For colour changes in this diff only, compute contrast against WCAG 2.2 AA: (1) Body text ≥ 4.5:1, (2) Large text (≥ 18.66px bold or 24px) and UI components ≥ 3:1, (3) Focus indicator ≥ 3:1 against adjacent colours. Give the measured ratio per pair. Don't check unchanged elements.

9. 热区尺寸(WCAG 2.2, 2.5.8)

Audit interactive targets against WCAG 2.2 SC 2.5.8 Target Size (Minimum): each target ≥ 24×24 CSS px including padding, OR a 24px-diameter circle around it doesn't overlap another target. Note inline-link and user-agent exceptions. Also flag anything below 44×44 (Apple HIG) as a design improvement, not a failure. file:line + severity.

10. 加载 / 异步朗读

Audit async UX: (1) Loading state announced via aria-live or role="status", (2) Errors announced via aria-live="assertive" sparingly, (3) Optimistic UI matched by a reverted, announced state on failure. Output file:line.

11. 自定义控件 ARIA 模式

For `[widgetType]`, verify it implements the WAI-ARIA Authoring Practices pattern. List: (1) Required role + key behaviours, (2) Where this implementation diverges, (3) Top 3 fixes ranked by user impact. Don't propose a full rewrite if 2 patches close the gap.

可替换变量: [widgetType] —— combobox / tabs / dialog / menu / treegrid

12. 移动端屏幕阅读器走查

Walk through this screen with VoiceOver (iOS) and TalkBack (Android). Predict the announcement per swipe-right. Flag where Android and iOS diverge meaningfully (e.g. heading nav, custom roles). Output a comparison table.

附加:a11y 回归 triage

Last release had [nIssues] a11y bug reports. Triage: (1) Cluster by component, (2) Identify the top 3 by user impact (severity × reach), (3) Suggest one preventive check per cluster (axe rule, lint rule, or manual step). Output a table.

可替换变量: [nIssues]

容易踩的坑

  • 把”axe 没报警”当成通过。 自动工具只覆盖约 57% 的问题,剩下要靠键盘和屏幕阅读器手测。
  • 为了好看去掉焦点环。 键盘直接没法用,同时违反 WCAG 2.4.7。
  • <div onClick> 代替 <button> 一步丢掉键盘激活和屏幕阅读器角色。
  • 弹窗里的 Tab 陷阱——关闭时焦点没还给触发元素。
  • 到处用 aria-live="assertive" 会打断并刷屏屏幕阅读器用户,只该留给真正的警报。
  • 表单错误只用红色标注。 色盲用户看不见;颜色要配上文字和图标。
  • 漏掉 WCAG 2.2 的新增项——热区尺寸、拖拽替代、焦点不被遮挡是最常见的新缺口。

优化技巧

  • 先在 CI 里跑 axe-core(或 Axe DevTools),再用这些 Prompt 抓它抓不到的。
  • 每个新的可交互组件都手测一遍纯键盘导航。
  • 季度用一次 VoiceOver / NVDA,涉及付款或鉴权的流程每次都测。
  • 语义 HTML 优先,ARIA 只是兜底——真正的 <button> 永远好过 role="button"
  • 每个组件配一份一页的 a11y.md,写清它的键盘与屏幕阅读器契约。
  • PR 引入新的 axe-core 违规要卡;已经存在的别一起卡,保持 PR 范围聚焦。

FAQ

  • axe-core 够 WCAG AA 吗?: 不够。Deque 的数据显示自动覆盖率约为 57%。剩下的要靠手测键盘和屏幕阅读器补齐。
  • 2026 年该以哪个 WCAG 版本为目标?: WCAG 2.2 AA——它是 W3C 当前正式推荐标准(2023 年 10 月)。注意欧盟 EAA 通过 EN 301 549 仍对应 WCAG 2.1 AA,但 2.2 是其超集,瞄准 2.2 即可同时覆盖两者。
  • 44×44 是法定最小热区尺寸吗?: 不是。WCAG 2.2 SC 2.5.8 把下限定在 24×24 CSS 像素。44×44 是 Apple 的推荐值、48dp 是 Material Design 的——都是良好目标,不是法定底线。
  • 真的需要找残障用户测吗?: 任何消费级产品,最终都需要。工具加 AI 能让你做到”好”,亲身体验测试才能到”很好”。
  • 30 秒的冒烟测试怎么做?: 拔掉鼠标,只用键盘走完整个功能。你做不到,键盘用户也做不到。
  • AI 能取代 a11y 顾问吗?: 高风险或法律审计不行。常规、PR 范围的检查交给 AI,边界情况和最终签字留给顾问。源头标准见 W3C 的 WCAG 2.2 标准WAI-ARIA Authoring Practices

相关阅读

标签: #Prompt #编程 #无障碍 #无障碍