跳转到使用指南
accessibility作者 Addy Osmani

Accessibility Skill.

Claude Code 和 Codex 的设计审查 skill:遵循 WCAG 2.2 审核和改进 Web 无障碍访问性。

  • Design Review & Accessibility
  • 审查报告
addyosmani/web-quality-skills · skills/accessibility/SKILL.mdSKILL.md
--- name: accessibility description: Audit and improve web accessibility following WCAG 2.2 guidelines. Use when asked to "improve accessibility", "a11y audit", "WCAG compliance", "screen reader support", "keyboard navigation", or "make accessible". --- ## Evidence-led audit workflow ## WCAG Principles: POUR ## Conformance levels ## Perceivable ## Operable ## Understandable
2026-09-14 从上游文件读取的前言和章节标题 · 完整 14,265 字符

01 功能说明

无障碍 skill 在 Claude Code 和 Codex 中的作用

摘要、工作流与产物,均读自该 skill 的 SKILL.md。

来自 SKILL.md读取于 2026-09-14 · 非实际运行记录

以 skill 自身的术语

此 skill 依据 WCAG 2.2 审计并修复 Web 无障碍问题,围绕 POUR ——可感知、可操作、可理解、健壮——以及 A、AA、AAA 合规级别组织。它运行一条以证据为导向的工作流:当有已渲染的页面可用时,先运行实时 Lighthouse 无障碍审计(lighthouse_audit,配合 Chrome DevTools MCP),用失败节点定位到具体组件,再用 take_snapshot 检查无障碍树,然后修复源码并重新运行。

如果缺少实时工具,Lighthouse CLI 或 axe 可以覆盖自动化那一半,同样的手动检查依旧适用。它内置代码级规则,涵盖替代文本、对比度、焦点可见性、目标尺寸、减少动效、表单错误和可访问的身份验证,另附一份按 critical、serious、moderate 分级的问题清单。

它产出什么

  • 一份按优先级排列的问题清单,分为 Critical(立即修复)、Serious(发布前修复)和 Moderate(尽快修复)三个层级,并配有具名示例。
  • 修正后的标记与可直接粘贴的代码片段,包括一个用于向辅助技术暴露图标按钮标签的视觉隐藏工具类。
  • references/A11Y-PATTERNS.md 中的完整参考实现,涵盖表单标签、模态框焦点陷阱、跳转链接、ARIA 选项卡、实时区域、错误处理和屏幕阅读器命令。
查看示例提示词 ↗

工作方式

  1. 01
    运行实时无障碍审计

    从已渲染的页面开始,运行实时 Lighthouse 无障碍审计:面向公众的通用页面使用移动导航模式,重新加载会丢失已认证状态时则使用快照模式。

  2. 02
    定位出错的组件

    用失败的审计节点直接指向具体的组件或模板,而不是在整个仓库里检索通用模式。

  3. 03
    检查无障碍树

    读取已渲染的无障碍树快照,检查名称、角色、状态、地标和标题层级,然后用键盘走一遍受影响的流程。

  4. 04
    修复源码并重新验证

    改源码,而不是改已渲染的输出,然后重复同一项审计和同一项手动交互,确认修复生效。

  5. 05
    回退到 CLI 工具

    没有可用的实时浏览器工具时,把 Lighthouse CLI 或 axe 的输出与同样的手动检查搭配使用,因为仅靠自动化只能覆盖一部分障碍。

02 找到适合场景

何时使用 accessibility Skill

当工作是此类设计审查时,在 Claude Code 或 Codex 中使用 accessibility skill。下方的适用范围和限制取自该 skill 自己的文件。

适合场景

  • 以 a11y 审计、WCAG 合规、屏幕阅读器支持、键盘导航或「让页面可访问」等措辞提出的请求。
  • 以 AA 级别为目标的团队——该文件将其视为标准目标,在许多司法管辖区也是法律要求。
  • 粘性页眉或页脚吞掉键盘焦点环的页面——这是 WCAG 2.2 新增的一条标准。
  • 必须完全无需鼠标即可操作的界面,包括由非交互元素构建的自定义组件。

了解边界

  • 行内文本链接、由浏览器控制尺寸的元素,以及 24px 圆形区域不与其他目标重叠的目标,均可豁免最小目标尺寸规则。
  • AAA 级别被视为可选项,而非硬性要求。
  • 文件特别指出的反模式:为原生 button 手动添加键盘激活,会因 Enter 和 Space 本就会触发 click 而产生双重触发。

需要提供的信息

  • 一个已渲染的页面实时工作流在页面渲染完成后才开始,因为审计、节点列表和无障碍树都来自它。
  • 页面的导航模式告诉 Agent 这是普通公开页面,还是重新加载就会丢失已认证状态或用户创建状态的流程,因为这决定了采用移动端导航还是快照模式。
  • 需要演练的键盘流程准备好审计期间用键盘走一遍受影响的交互,同时进行无障碍树检查。

03 Skill 内部

无障碍 skill 为 Claude Code 和 Codex 定下的规则

SKILL.md 为 Agent 设定的 7 条具体指令、默认值与限制——正是文件中真正改变结果的部分。

  1. 优先使用原生元素

    原生 button、a 和表单控件本身就处理 Enter/Space 激活、焦点和辅助技术语义,因此手动键盘处理只是无法替换元素时的最后手段。

  2. 保持焦点样式可见

    永远不要移除 outline。

  3. 守住 24 × 24 的最小目标尺寸

    AA 级别下,交互目标至少需为 24 × 24 CSS 像素;按钮、复选框和单选项标签则建议采用 44 × 44 的舒适触控尺寸。

  4. 按需消除动画

    在 prefers-reduced-motion 下,文件把动画和过渡时长压缩到 0.01ms,将循环次数上限设为 1,并把 scroll-behavior 重置为 auto。

  5. 绝不单靠颜色传递信息

    错误状态将颜色与图标、文字结合;标记中把 aria-invalid="true" 与指向错误信息元素的 aria-describedby 配对使用。

  6. 播报错误并聚焦错误

    通过 role="alert" 或 aria-live 把错误推送给屏幕阅读器,标记出有问题的字段,并在提交时把焦点移到第一个错误处。

  7. 让身份验证保持低认知负担

    登录流程不得依赖记忆密码或解谜,除非复制粘贴或自动填充可用、存在通行密钥或邮件链接等替代方式,或测试使用物体识别或个人信息。

04 投入使用

在 Claude Code 或 Codex 中安装 accessibility

一条 npx skills add 命令,然后在你的 Agent 中执行第一个任务和对结果的清单检查。

将 accessibility 添加到 Claude Code、Codex 或你的 Agent

在你的项目中运行;安装程序会询问要把它添加到哪个 Agent。

Terminal
npx skills add https://github.com/addyosmani/web-quality-skills --skill accessibility

通用的 skills CLI 形式,对应 skills/accessibility/SKILL.md;仓库可能记录了自己的路径。

为 Skill 提供第一个设计审查任务

按 skill 自身的术语撰写;把括号中的部分换成你的内容。

Starter prompt
Audit [page URL or route] with Lighthouse and then fix the accessibility problems in the source. The form inputs in [component path] have no programmatically associated labels, the icon buttons have no accessible names, and focus outlines are being removed on [element]. Re-run the same audit afterwards and check keyboard navigation and target sizes.

来源:依据 SKILL.md,按 skill 自身的术语撰写。

检查首次结果

SKILL.md 本身如何描述正确的结果:

  • 用 Tab 键遍历整个页面,并用 Enter 和 Space 激活控件。

在 OpenDesign 中可通过其 SKILL.md 链接导入 accessibility:Plugins → Add → Skill → Import from link,然后在顶栏中选择它。

05 开源、可追溯

来源、许可与验证

本页面事实的来源,以及最后检查时间。

Skill 文件
skills/accessibility/SKILL.md 内容校验和已在验证时记录;commit afa8da9
License
MIT 来自 LICENSE;SKILL.md 标注 "MIT"。
仓库星标数
2,786 GitHub 快照摄于 2026-09-14,针对整个 addyosmani/web-quality-skills 仓库。不是 accessibility 的评级或使用计数。
已由 OpenDesign 验证
2026-09-14 已检查源文件、路径、许可文本和 star 数量。未内置在 OpenDesign 主程序(检查日期 2026-08-28);本页面未记录实际运行。
Skill 自身的描述
"遵循 WCAG 2.2 指南审查并改进 Web 可访问性。当被要求「改进可访问性」、「a11y 审查」、「WCAG 合规」、「屏幕阅读器支持」、「键盘导航」或「使其无障碍」时使用。"

来自 SKILL.md 的 front-matter 描述。完整文件约 14,265 个字符。在 GitHub 上阅读完整文件。

Accessibility

在真实的设计审查任务上运行 accessibility。

下载 OpenDesign,从其 SKILL.md 链接导入 accessibility,粘贴上面的提示词,在查看结果之前先阅读计划。

终端
npx skills add https://github.com/addyosmani/web-quality-skills --skill accessibility

OpenDesign 桌面客户端

一套设计系统,让每一次创作都保持品牌一致

在完整的 Vibe Design Workspace 中,用同一套品牌规则生成网页、PPT、可交互原型、数据看板、图像与 HTML 视频。连接本地 Codex、Claude Code、Cursor 等编程助手,即可免费创作。

  • 覆盖网页、PPT、原型、数据看板、图像与视频
  • 140+ 设计系统,以及完整模板与技能库
  • 连接本地 Codex 与 21+ 款编程助手 · 免费使用
免费下载

支持 macOS 与 Windows