技能使用指南

accessibility-expert（无障碍专家）Skill 是什么？能解决哪些无障碍问题？

无障碍专家 Skill 覆盖 WCAG 2.1/2.2 合规、WAI-ARIA 实现、键盘导航、屏幕阅读器优化与无障碍测试自动化，能直接改代码并给渐进式修复方案。本文详解一键安装步骤、核心功能、竞品对比与真实应用场景，帮前端团队把无障碍检查左移到日常开发。

无障碍专家Skillaccessibility-expert
8 个章节 约 16 分钟阅读 AI 智能生成

无障碍专家：让 AI 帮你把 WCAG 合规、ARIA 与键盘导航一次修到位

  • 它是什么：一个聚焦 Web 无障碍的前端专家技能，覆盖 WCAG 2.1/2.2 合规、WAI-ARIA 实现、屏幕阅读器优化、键盘导航与无障碍测试自动化。
  • 它能干什么：自动检测代码中的无障碍反模式（缺 alt、缺标签、Div 按钮、焦点陷阱无退出等），给出「最小 → 更好 → 完整」的渐进式修复方案，并能直接改代码、跑命令验证。
  • 它的特别之处：不是单纯的检查工具，而是带审查清单、问题解决手册和专家分流机制的「AI 无障碍顾问」——遇到纯 CSS、React 模式、测试框架或移动端问题时，它会主动建议转交更合适的专家。
  • 它的边界：自动化工具通常只能发现约 35% 的无障碍问题，技能同样强调必须配合真实屏幕阅读器（NVDA、JAWS、VoiceOver）手动验证。
  • 适合谁：前端工程师、设计系统维护者、需要做 WCAG 合规整改的团队，以及希望把无障碍检查左移进日常开发流程的项目组。

1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能基本信息

项目 内容
中文名 无障碍专家
英文名 accessibility-expert
技能ID 11765
所属分类 前端
调用工具 读取、Grep、Glob、Bash、编辑、MultiEdit、写入

它解决的问题

Web 无障碍长期处于「知道重要、但做起来成本高」的尴尬位置。原因很现实：WCAG 2.1/2.2 的条款多、ARIA 规范细节多、屏幕阅读器行为差异大，普通开发者很难同时记住「颜色对比要 4.5:1」「模态框关闭后焦点要回到触发元素」「aria-expanded 必须随状态动态更新」这一整套规则。结果是无障碍问题往往等到上线后、被用户投诉或被合规检查时才集中爆发。

无障碍专家技能把这个领域的知识沉淀成一套可执行的流程：识别问题类别与 WCAG 级别 → 检查常见反模式 → 应用渐进式修复 → 用自动化工具和手动测试验证。

一键安装的思路与步骤

安装这类 AI 技能的核心思路是「装上即可用，不改变原有工程结构」——技能本身不改动你的构建配置，只是让 AI 助手在遇到无障碍问题时具备专家级的判断力和工具箱。

  1. 确认前提：你使用的 AI 编程助手/开发环境支持技能（Skill）机制；当前项目有可读写的本地代码目录；技能声明的读取、Grep、Glob、Bash、编辑、MultiEdit、写入等工具权限已授权。
  2. 找到入口：在技能的安装入口或技能市场中，按英文名 accessibility-expert 搜索，或直接按技能ID 11765 定位（具体入口路径与命令以官方说明为准）。
  3. 一键安装：点击安装/启用，将技能加入当前工作区或全局技能列表。具体安装命令与配置文件位置以官方说明为准。
  4. 验证是否生效：新建一次会话，直接抛出一个无障碍问题（例如「我这个表单的错误提示屏幕阅读器读不到，帮我看看」），如果 AI 开始按「WCAG 合规 → ARIA → 键盘 → 屏幕阅读器」的清单逐项排查，并给出诊断命令与修复代码，说明技能已生效。

环境自检（可选但推荐）

技能内置了一套环境检测命令，用来确认项目里是否有可用的无障碍工具链，例如：

npm list @axe-core/playwright @axe-core/react axe-core --depth=0 2>/dev/null | grep -E "(axe-core|@axe-core)" || echo "未找到axe-core"
npm list pa11y --depth=0 2>/dev/null | grep pa11y || command -v pa11y 2>/dev/null || echo "未找到Pa11y"
npm list eslint-plugin-jsx-a11y --depth=0 2>/dev/null | grep jsx-a11y || echo "未找到JSX无障碍代码检查"

在 macOS 上它还会检查 VoiceOver 是否配置，在 Windows 上检查 NVDA 与 JAWS 是否安装，在 Linux 上检查 Orca。检测出「未找到」也不是装不上，只是意味着后续验证要依赖手动测试或临时安装工具。

2. 该技能的主要功能和特点

  • WCAG 2.1/2.2 合规审查清单：覆盖图像 alt 文本、表单标签关联、标题层级（H1→H2→H3 不跳级）、颜色非唯一信息载体、文本放大 200% 无水平滚动、320px 视口重排等条目，逐项对照检查。
  • WAI-ARIA 实现与纠错：检查 ARIA 角色是否被滥用（如用 role="button" 覆盖原生语义）、aria-expanded 是否为静态值、aria-describedby/aria-labelledby 是否指向不存在的 ID、动态内容是否缺少 aria-live 实时区域。
  • 键盘导航与焦点管理：识别 <div onClick> 这类「Div 按钮综合症」、检查 tabindex 滥用、模态框焦点捕获与关闭后焦点归还、跳过链接、焦点指示器可见性与对比度（最小 3:1）。
  • 屏幕阅读器优化：按 2024 WebAIM 调查的使用率排序测试优先级——NVDA（65.6%，Windows 最流行）、JAWS（60.5%，专业环境）、VoiceOver（macOS/iOS 首选），并针对标题结构、地标（nav/main/aside）、表格 th 与 scope、描述性链接文本给出修复建议。
  • 表单无障碍专项：错误消息通过 aria-describedby 与字段关联、必填字段用 required/aria-required 编程式标识、<fieldset> + <legend> 分组、提交后的确认与错误反馈可被朗读。
  • 视觉与感官无障碍：对比度标准量化（正文 4.5:1、大文本 3:1、UI 组件 3:1）、相对单位 rem/em、prefers-reduced-motion 支持、禁止无控制的自动播放媒体。
  • 测试自动化集成：给出 axe-core（最全面）、Pa11y（CI/CD 速度快、二进制通过/失败）、Lighthouse（初始评估、性能相关）的组合策略与 CI 脚本示例。
  • 渐进式修复策略：每个问题域都拆成「最小修复 → 更好方案 → 完整方案」三档，让团队可以先止血再重构，而不是被一份上百条的审计报告卡住。
  • 反模式黑名单：明确列出 ARIA 滥用、Div 按钮、仅颜色信息、无 Esc 退出的焦点陷阱、自动播放媒体、第三方无障碍覆盖层、仅靠工具测试等七类常见错误做法。
  • 专家分流机制：当问题实际属于纯 CSS 视觉设计、React 特定模式、测试自动化框架或移动端 UI 模式时，主动建议转交对应的专家技能，避免「什么都能答、什么都答不深」。

和普通工具比强在哪：axe、Pa11y、Lighthouse 只告诉你「哪里错了」，技能告诉你怎么改、改到什么程度够用、改完怎么验证，并且能直接动手编辑文件、运行命令复核。

3. 如何使用该技能？

基本使用流程

  1. 触发技能：在对话中直接描述无障碍问题，最好带上上下文（框架、组件、现象）。例如「我的下拉菜单用 div 写的，键盘 Tab 能进去但选不中选项」。
  2. 技能自动分类：技能会先判断问题归属（WCAG 合规 / ARIA / 键盘 / 屏幕阅读器 / 视觉感官 / 表单 / 测试），并确认目标 WCAG 级别（A、AA 还是 AAA）。
  3. 静态诊断：使用 Grep、Glob 在源码中扫描反模式，输出类似下面的诊断命令结果：
# 查找无键盘支持的交互元素
grep -r 'onClick\|onPress' --include="*.jsx" --include="*.tsx" src/ | grep '<div\|<span' | grep -v 'onKeyDown\|onKeyPress' | head -10
  1. 给出渐进式修复：按最小、更好、完整三档给出代码级修改方案，并说明取舍。
  2. 验证闭环：优先调用项目已有的 axe-core / Pa11y / Lighthouse 复核，同时给出必须手动执行的检查项（Tab 键走查、屏幕阅读器朗读、200% 缩放、320px 视口）。

输入示例与输出说明

  • 输入示例一：「帮我检查 src/components/Modal.tsx 的无障碍问题。」技能输出：焦点捕获是否完整、关闭后是否归还焦点、是否有 Esc 退出、aria-modal 与 role="dialog" 是否正确、标题是否通过 aria-labelledby 关联。
  • 输入示例二：「这个表单的错误提示屏幕阅读器读不出来。」技能输出：错误容器是否带 aria-live="polite"、错误文本是否通过 aria-describedby 关联到具体字段、必填标识是否编程式可读。
  • 输入示例三：「上线前紧急过一遍无障碍。」技能输出：跳过链接、基础 aria-label、:focus { outline: 2px solid blue; }、表单标签、图片 alt、实时区域这六项紧急修复清单。

紧急修复脚本模板（技能内置建议）：

<a href="#main" class="skip-link">跳到主要内容</a>
<div aria-live="polite" id="status"></div>

4. 同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
无障碍专家（accessibility-expert） AI 无障碍顾问 + 代码修复执行者 WCAG 审查清单、ARIA 纠错、键盘/焦点、屏幕阅读器优化、测试集成建议、渐进式修复、可读写代码并跑命令 安装技能即可，无需改造工程；需要 AI 助手支持 Skill 机制 日常开发自检、合规整改、组件级修复、紧急止血 优势：给方案不止给报告，能落地改码；不足：仍依赖真实屏幕阅读器做最终确认
axe-core（+ @axe-core/playwright） 自动化无障碍检测引擎 规则化扫描、与端到端测试集成 需要在项目中安装依赖并写测试 CI 中做回归、批量页面扫描 优势：规则全面；不足：与 Pa11y 结合时约覆盖 35% 的问题，无法给出业务化修复建议
Pa11y / pa11y-ci CI/CD 无障碍门禁 快速扫描、二进制通过/失败结果、可接 sitemap 批量跑 安装 CLI 并配置脚本 流水线卡点、发布前快速反馈 优势：速度快、易集成；不足：只判定成败，缺少修复指导
Lighthouse 综合质量评估 无障碍类别审计，含对比度等内容 浏览器内置或 CLI 初次评估、性能与无障碍一起看 优势：上手最轻；不足：偏初步评估，深度规则覆盖有限
ESLint jsx-a11y 编码期静态检查 在编辑器里即时提示 JSX 无障碍问题 配置 ESLint 插件 编码时即时纠错 优势：反馈最快；不足：只覆盖静态可判定的模式

选型建议：把 ESLint jsx-a11y 放在编码期，Pa11y/axe 放在 CI 卡点，无障碍专家技能放在「问题定位、方案设计、批量修复」这一层，最后用真实屏幕阅读器人工验收。

5. 该技能的典型应用场景与实际体验情况

场景一：前端开发提交前的自检

角色是业务前端。痛点是提测后才发现无障碍问题，改动成本高。使用方式是提交前把改动的组件路径丢给技能，让它对照清单跑一遍。实际体验：上手几乎零门槛，因为不需要记规则，只需要描述现象；效果上最容易命中「缺 alt」「缺标签关联」「Div 按钮」这三类高频问题；注意点是技能给出的修复建议要结合项目现有组件库落地，不要机械照搬示例代码。

场景二：企业级 WCAG AA 合规整改

角色是项目技术负责人。痛点是收到一份无障碍审计报告，条目上百条，不知道从哪下手。使用方式是把报告条目分批交给技能，让它按「最小 → 更好 → 完整」拆解成可排期的任务。实际体验：技能的分档策略非常实用，能先解决阻断性问题再逐步完善设计系统；注意事项是必须明确目标级别（A/AA/AAA），否则容易过度修复。

场景三：复杂交互组件（模态框、下拉菜单、表格）

角色是设计系统维护者。痛点是模态框焦点乱跑、下拉菜单键盘选不中、数据表格读屏乱序。使用方式是指定组件文件，让技能检查焦点管理、键盘事件、ARIA 状态、表格 scope。实际体验：技能对「焦点陷阱无 Esc 退出」「aria-expanded 静态值」这类典型错误识别得很准；注意点是修复后一定要手动 Tab 走查一遍，自动化工具对焦点行为基本抓不到。

场景四：CI 无障碍门禁搭建

角色是测试/效能工程师。痛点是团队没有无障碍回归能力。使用方式是按技能提供的集成策略，安装 Pa11y 做快速门禁、axe-core 做综合测试，并在 package.json 中加脚本。实际体验：技能给出的脚本模板可直接参考，缩短了调研时间；注意事项是 CI 里失败即阻断可能引起大量历史问题集中爆发，建议先设为告警模式，逐步收紧。

6. 该技能能为用户带来的价值

  • 效率提升：把「查规范 → 找原因 → 写修复 → 找工具验证」四步压缩成一次对话，尤其适合不具备无障碍专精知识的普通前端。
  • 门槛降低：无需背下 WCAG 全部条款和 ARIA 规范，只要描述现象就能拿到检查项和修复代码；技能自带的中文检查清单本身就是很好的团队培训材料。
  • 质量兜底：明确提醒「自动化工具通常只覆盖约 35% 的问题」，避免团队产生「扫描通过即合规」的错觉，把真实屏幕阅读器验证纳入流程。
  • 可量化的收益方向：减少上线后返工与合规整改成本、缩短审计报告消化周期、把无障碍检查从「上线前突击」变成「提交前例行」。
  • 长期价值：沉淀出可复用的无障碍组件模式与焦点管理工具，把一次性修复转化为设计系统的能力，后续新页面默认继承。

7. 常见问题 FAQ

Q1：无障碍专家技能怎么安装？ A：在支持 Skill 机制的 AI 助手中，通过技能市场的安装入口，按英文名 accessibility-expert 或技能ID 11765 搜索并一键启用即可。具体入口位置、安装命令与权限配置方式以官方说明为准。装完后用一个具体的无障碍问题测试是否生效。

Q2：这个技能收费吗？ A：本技能页面未提供定价信息，是否需要付费取决于所在平台的技能分发规则，请以官方说明为准。技能本身依赖的 axe-core、Pa11y、Lighthouse、ESLint jsx-a11y、NVDA、VoiceOver 等工具均有各自的开源或免费方案。

Q3：它适合谁用？ A：最适合三类人：一是需要做无障碍自检的前端工程师；二是负责 WCAG 合规整改、需要把审计报告拆成任务的技术负责人；三是维护组件库/设计系统、需要沉淀无障碍模式的同学。纯视觉设计问题、React 特定模式、测试框架选型和移动端 UI 模式，技能会建议转交对应专家。

Q4：有了 axe-core、Pa11y 还需要这个技能吗？ A：需要，两者互补。自动化工具负责「发现问题」，技能负责「判断问题严重级别、给出修复方案、改代码、告诉你怎么验证」。官方说明里明确提到，自动化工具通常只能覆盖约 35% 的无障碍问题，剩下的大量问题依赖人工判断与真实辅助技术测试。

Q5：装了技能是不是就不用做屏幕阅读器测试了？ A：不行。技能把真实辅助技术测试列为必要环节，优先级为 NVDA（Windows，最流行）→ VoiceOver（macOS/iOS，移动端必需）→ JAWS（Windows，专业环境）。技能能做的是帮你把「该测什么」列清楚，把明显的代码问题先修掉，减少你在手动测试上的无效时间。