前言¶

前端页面做完功能联调之后，无障碍（a11y）往往还卡在人工走查：图标按钮有没有可读名称、表单有没有关联 label、Tab 顺序是否合理、对比度够不够。这类问题肉眼扫一遍容易漏，专门开一轮 axe / Lighthouse 又偏重。若你已经在用 Cursor Agent，其实可以用内置浏览器直接抓取与屏幕阅读器同源的无障碍树，按清单把问题找出来并改源码。

accessibility-auditing 就是为此准备的 Agent Skill：不依赖额外扫描器，按固定工作流打开页面、捕获 ARIA 树、检查键盘可达性，再输出分级报告并落地修复。

这是什么¶

accessibility-auditing 收录在 spencerpauly 维护的开源清单 awesome-cursor-skills 中，归类为 Cursor-Native（依赖 Cursor Agent 内置浏览器能力）。仓库以 Creative Commons Zero（CC0）授权，目录下仅有一份 SKILL.md。

官方一句话定位是：使用 Cursor 浏览器的 ARIA / accessibility snapshot，审计页面上的缺失标签、错误 Tab 顺序、对比度问题以及 ARIA 误用。frontmatter 中 user-invocable: true，可在对话里主动唤起。

它解决的是「开发过程中的轻量 a11y 走查」：Agent 对着真实渲染页面的无障碍树做结构化检查，而不是只读静态 HTML 猜测。

核心功能与亮点¶

根据官方 SKILL.md，工作流分成六步，检查项也写得很具体。

1. 打开目标页

使用 browser_navigate 打开待测 URL（本地开发地址或预览环境均可）。

2. 捕获无障碍树

调用 browser_snapshot，拿到页面的 aria / accessibility tree。Skill 明确说明：这就是屏幕阅读器所依赖的那棵树。

3. 对照清单审计

官方要求逐项检查五类问题：

• 缺失可访问名称：无文本且无 aria-label 的 button、无 alt 的 img、无关联 label / aria-label 的 input、无文本的链接、仅图标的按钮。
• 语义 HTML：用可点击的 div / span 代替 button / a；缺少 nav / main / header / footer 地标；标题层级跳跃（如 h1 直接到 h3）；列表未用 ul / ol / li。
• 键盘导航：可交互元素不在 Tab 序中；自定义控件缺 role 与键盘处理；弹层焦点陷阱与 Escape 关闭；缺少 skip-to-content。
• ARIA 误用：可聚焦元素上写了 aria-hidden="true"；非法 role；aria-expanded 无对应折叠内容；aria-controls 指向不存在的 id。
• 对比度（结合截图目视）：浅灰字配白底、过淡的 placeholder、禁用态与正常态难以区分。

4. 实测键盘行为

用 browser_press 模拟 Tab，验证每个可交互元素能否获焦、焦点顺序是否自上而下 / 自左而右、焦点环是否可见、Escape 能否关闭弹层与下拉。

5. 输出分级报告

官方给出了报告模板，分为 Critical、Warnings、Passed，便于评审和排期。

6. 直接改代码

对每条问题在源码中修复，并列出常见改法：给图标按钮加 aria-label、用 label / htmlFor 关联输入框、把可点击 div 换成真正的按钮、补 alt、理顺标题层级等。

和 Cursor 官方 Browser 文档是对齐的：文档里同样把「无障碍改进」列为内置浏览器用例，示例提示包括检查对比度、语义 HTML、ARIA 标签、键盘导航与缺失 alt。该 Skill 把这些动作收成可复用的检查清单与报告格式。

安装与启用¶

Skill 本体就是一份标准 SKILL.md，符合 Agent Skills / agentskills.io 约定。Cursor 会从项目级或用户级目录自动发现技能。

方式一：手动拷贝（与 awesome-cursor-skills README 一致）

把官方文件放到项目技能目录：

mkdir -p .cursor/skills/accessibility-auditing
curl -fsSL \
  https://raw.githubusercontent.com/spencerpauly/awesome-cursor-skills/main/resources/accessibility-auditing/SKILL.md \
  -o .cursor/skills/accessibility-auditing/SKILL.md

个人全局可用时，可放到 ~/.cursor/skills/accessibility-auditing/SKILL.md。Cursor 还兼容 .agents/skills/，以及 Claude Code / Codex 的 .claude/skills/、.codex/skills/ 等路径。

方式二：用 skills CLI 安装

vercel-labs/skills 支持从 GitHub 按名称安装单个 Skill。针对 Cursor 可类似执行：

npx skills add spencerpauly/awesome-cursor-skills \
  --skill accessibility-auditing \
  -a cursor

若主要给 Claude Code 用，把 -a cursor 换成 -a claude-code 即可（会装到对应的 skills 目录）。加 -g 则装到用户全局目录。

安装后，在 Cursor Agent 对话里输入 /accessibility-auditing，或直接描述「对当前页面做无障碍审计」；Agent 会根据 description 自动匹配该 Skill。

需要注意：工作流依赖 browser_navigate / browser_snapshot / browser_press 这类浏览器工具。在 Cursor 里一般直接走内置 Browser；在其他 Agent 中，只有挂载了能力对等的浏览器 MCP / 工具时，同一份清单才能完整跑通。

典型用法示例¶

本地服务起来后，可以这样唤起（URL 换成你的页面）：

/accessibility-auditing
请审计 http://localhost:3000/login
按 Critical / Warnings / Passed 输出报告，并对 Critical 项直接改源码。

也可以不显式写斜杠命令，用自然语言触发：

用浏览器打开首页，抓取 aria 树，检查缺失标签、Tab 顺序、ARIA 误用和对比度，
给出无障碍审计报告后再逐项修复。

官方报告格式示例如下（结构来自 SKILL.md）：

Accessibility Audit:
  Critical:
    - 3 buttons with no accessible name (header icons)
    - Login form inputs missing labels
  Warnings:
    - Heading levels skip from h1 to h3
    - No skip-to-content link
    - 2 clickable divs should be buttons
  Passed:
    - All images have alt text
    - Landmarks present (nav, main, footer)
    - Focus order is logical

修复阶段可按官方常见改法对照源码，例如：

<!-- 图标按钮补可访问名称 -->
<button type="button" aria-label="Close">×</button>

<!-- 输入框关联 label -->
<label for="email">Email</label>
<input id="email" name="email" type="email" />

<!-- 可点击区域用语义元素 -->
<button type="button">提交</button>

适用场景与注意事项¶

适合这些场景：

• 功能开发中途，想快速扫一遍表单、导航、弹层的基础 a11y。
• Code Review 前，让 Agent 先出一份 Critical / Warnings 清单。
• 面向需要满足 WCAG / 无障碍合规要求的产品，作为迭代期的辅助手段。

使用时注意几点：

1. 对比度检查是「截图目视」，不是精确的对比度比值计算；正式合规仍建议再用 axe、Lighthouse 或专业对比度工具复核。
2. 依赖浏览器 snapshot 是否返回完整无障碍树。若工具结果只有元数据、没有 aria 树与元素引用，审计与键盘操作都会受阻，需先确认 Cursor Browser / 所用 MCP 工作正常。
3. Skill 不会替你声明「已通过 WCAG」；它提供的是可操作的检查流程与修复指引，验收结论仍要由团队标准与专项工具兜底。
4. 仓库将该 Skill 标为 Cursor-Native，核心能力绑定 Cursor 内置浏览器；拷到其他 Agent 时，请确认具备等价的导航、快照与按键能力。

小结¶

accessibility-auditing 把「打开页面 → 抓 ARIA 树 → 按清单审计 → Tab 实测 → 分级报告 → 改源码」固化成一份可复用的 Agent Skill，适合把无障碍检查嵌进日常 AI 辅助开发，而不是等上线前才突击。

官方地址：

https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/accessibility-auditing

SKILL.md 原文：

https://github.com/spencerpauly/awesome-cursor-skills/blob/main/resources/accessibility-auditing/SKILL.md