accessibility-compliance

accessibility-compliance 技能概览

accessibility-compliance 技能能做什么

accessibility-compliance 技能可以帮助智能体为 Web 和移动端 UI 工作产出可直接落地的无障碍实现建议，重点覆盖 WCAG 2.2、ARIA 用法、键盘可访问性、屏幕阅读器支持以及移动端无障碍。它更适合真正要做界面实现的团队，而不只是生成一份泛泛的无障碍检查清单。

谁适合安装 accessibility-compliance

这个技能尤其适合以下人群：

• 需要 accessibility-compliance for UX Audit 的 UX 审计人员
• 负责修复组件无障碍问题的前端工程师
• 定义可访问交互模式的设计系统团队
• 正在交付表单、对话框、菜单等交互式 UI 的产品团队
• 需要兼顾 VoiceOver 和 TalkBack 的移动端或跨平台团队

如果你的核心目标是“把这个页面或组件改得更接近 WCAG 合规，并给出明确可执行的修复方案”，那这个技能会比宽泛的设计类 prompt 更有用。

为什么这个技能不同于通用 prompt

accessibility-compliance skill 的核心价值，在于它会把模型收束到实用的无障碍实现模式上，而不是停留在模糊原则层面。仓库里包含了几份聚焦的参考资料：

• references/wcag-guidelines.md
• references/aria-patterns.md
• references/mobile-accessibility.md

因此，它更适合处理这类任务：优先选择语义化 HTML 而不是 ARIA、组织可访问表单、改进键盘交互行为，或检查移动端触控目标相关指导。

用户在安装前最关心什么

大多数在评估 accessibility-compliance install 的用户，通常会先确认：

• 它给的是不是面向代码和实现的具体修复建议，而不是政策或规范口径
• 是否同时覆盖 Web 和移动端场景
• 是否既能辅助审计，也能辅助落地实现
• 对原生语义和 ARIA 的取舍是否有明确倾向
• 在评审 UI 组件时，能否减少来回沟通和返工

从这些点来看，这个技能表现比较扎实。它最大的差异化优势，是把 WCAG 概念、ARIA 模式和移动端无障碍实践整合在同一个技能包里，而且偏实战。

最适合与不适合的使用场景

最适合：

• 审计交互式组件
• 修复现有代码中的无障碍问题
• 规划对话框、手风琴、表单、导航等组件的可访问行为
• 评审焦点顺序、标签、播报以及减少动态效果支持

不适合：

• 面向特定司法辖区的法律合规解释
• 单独承担自动化测试搭建工作
• 与无障碍无关的像素级视觉设计点评
• 超出参考资料范围的深度平台原生 API 细节

如何使用 accessibility-compliance 技能

安装方式与调用方式

上游 SKILL.md 没有提供安装命令，因此目录用户通常会直接从仓库添加：

npx skills add https://github.com/wshobson/agents --skill accessibility-compliance

调用时，最好给智能体一个明确的无障碍任务，而不是只说一句“检查无障碍”。这个技能在输入中包含具体组件、用户流程或页面结构时效果最好，便于它做有依据的审查。

建议先读这些文件

如果想尽快上手，建议按下面顺序看：

1. plugins/ui-design/skills/accessibility-compliance/SKILL.md
2. plugins/ui-design/skills/accessibility-compliance/references/wcag-guidelines.md
3. plugins/ui-design/skills/accessibility-compliance/references/aria-patterns.md
4. plugins/ui-design/skills/accessibility-compliance/references/mobile-accessibility.md

这个阅读顺序基本对应多数团队的实际工作方式：先明确合规目标，再看实现模式，最后补平台边界场景。

accessibility-compliance 需要什么输入，效果才会好

accessibility-compliance usage 的输出质量，非常依赖你提供的信息是否具体。建议至少提供：

• 组件或页面类型
• 当前代码或 markup
• 使用框架（React、Next.js、Vue、plain HTML、React Native）
• 交互行为
• 目标标准，通常是 WCAG 2.2 AA
• 设备范围：desktop web、mobile web、iOS、Android
• 已知问题，来自审计工具或用户测试都可以

较弱的输入：

• “Make this accessible.”

较强的输入：

• “Review this React modal for WCAG 2.2 AA. Check keyboard trap behavior, focus return, accessible name/description, escape handling, and screen reader announcements. Suggest code changes before release.”

如何把模糊目标改成高质量 prompt

一个好的 accessibility-compliance guide prompt，通常包含五个部分：

1. 目标 UI
2. 用户交互
3. 合规目标
4. 期望交付物
5. 约束条件

例如：

• “Use the accessibility-compliance skill to audit this checkout form for WCAG 2.2 AA. Identify failures by issue, explain user impact, and provide corrected JSX for labels, error messaging, field grouping, and keyboard flow. Keep the current visual design if possible.”

这会明显优于只问“best practices”，因为它会迫使模型输出可修复、可落地的结果。

用于 UX 审计时的最佳 workflow

如果是做 accessibility-compliance for UX Audit，推荐按这个顺序推进：

1. 先让它发现问题
2. 再让它标出严重程度和用户影响
3. 然后要求给出一一对应的修复方案
4. 接着要求输出修订后的 markup 或组件代码
5. 最后要求补一份复测清单

这样可以避开一个常见问题：第一轮回答往往过于概念化。这个技能真正有价值的地方，在于把审计发现一路推进到实现细节。

不只适合页面，也很适合组件

这个技能在可复用交互模式上尤其强。适合的目标包括：

• dialogs 和 focus traps
• accordions
• menus 和 disclosures
• forms 和 validation
• tabs
• carousels
• icon buttons
• 移动端 touch targets

这些恰恰也是通用 prompt 最容易出问题的地方：要么过度使用 ARIA，要么漏掉键盘与屏幕阅读器行为。

这些参考文件在实际中意味着什么

仓库内的参考资料，实际上暗示了三条重要原则：

• 在添加 ARIA 之前，优先使用语义化 HTML
• 默认基线应视为 WCAG 2.2 AA
• 不要只考虑桌面端键盘操作，也要覆盖移动端无障碍

这在真实项目中很关键。一个像样的 prompt，应该明确要求智能体尽量减少不必要的 ARIA，并说明它为什么要添加某个 ARIA 属性。

能拿到更强输出的 prompt 模式

可以使用下面这种请求结构：

• Context: “This is a React checkout drawer.”
• Target: “Meet WCAG 2.2 AA.”
• Review scope: “Keyboard access, focus order, visible labels, error association, live region announcements.”
• Constraints: “Do not rewrite the design system API.”
• Deliverable: “Return prioritized issues, corrected JSX, and a manual test checklist.”

相比开放式的审查请求，这种结构更稳定地产出高质量的 accessibility-compliance usage 结果。

可以期待什么样的输出

一份好的 accessibility-compliance skill 输出，通常应包含：

• 与用户影响对应的问题清单
• 关联到无障碍原则或准则的说明
• 具体的 markup 或代码修改建议
• 关于键盘与焦点行为的说明
• 关于屏幕阅读器命名与播报的指导
• 在相关情况下补充移动端专项说明

如果输出只停留在原则层面，没有给到代码级修正，通常说明你的 prompt 还是太宽泛了。

accessibility-compliance 技能常见问题

accessibility-compliance 适合初学者吗？

适合，但前提是你已经了解基本的 UI 结构。如果你能提供 markup、组件代码或审计发现，这个技能的价值会更高。初学者也可以用，只是通常需要继续追问，弄清楚为什么某些语义或 ARIA 选择更合适。

它比普通的无障碍 prompt 更好吗？

通常是的，尤其在实现工作上更明显。普通 prompt 往往只会返回类似“加 alt text”或“确保支持键盘导航”这种泛泛建议。accessibility-compliance skill 更容易围绕仓库参考资料中的 WCAG 2.2、ARIA 模式和移动端无障碍问题展开，而不是飘在空泛建议上。

它能替代自动化无障碍测试吗？

不能。它更适合作为自动化工具和人工审查的补充。你可以用它来解释问题、提出修复方案，并检查一些静态工具经常漏掉的组件行为，比如焦点管理、播报时机或移动端交互细节。

什么情况下不该使用 accessibility-compliance？

如果你需要的是以下内容，就不建议用它：

• 法律意见或认证决策
• 全量代码库的自动化扫描
• 超出参考模式范围的深度原生移动平台细节
• 与无障碍无关的 UX 点评

它是一个指导型技能，不是合规保证。

它对移动端无障碍支持得好吗？

以 AI 技能来说，算是比较可靠。专门的 mobile-accessibility.md 参考文件覆盖了 iOS 和 Android 上的触控目标尺寸、间距以及屏幕阅读器相关注意点。因此，相比只关注桌面 Web 的无障碍 prompt，这个技能做移动端评审时更有说服力。

可以把它用于设计系统工作吗？

可以。它很适合为可复用组件定义统一的无障碍默认行为，特别是在语义、键盘处理、ARIA 状态和焦点管理需要在多个产品之间保持一致时。

如何提升 accessibility-compliance 技能的使用效果

给技能真实产物，不要只给摘要

想让 accessibility-compliance 更快给出高质量结果，最有效的方法是直接提供真实的 JSX、HTML、React Native 代码、带标注的截图，或者逐步展开的交互说明。仅靠模糊的产品摘要，它无法可靠推断焦点顺序、标签或播报行为。

要求它做问题映射，而不只是提建议

更强的请求方式是：

• “List each issue, affected users, violated principle or criterion, and exact fix.”

这样会逼着模型输出可审计的结果。没有这个结构时，回答很容易滑向泛泛建议。

明确告诉它你能接受多大改动

无障碍修复往往要和设计系统约束做权衡。你应该明确说明，智能体是否可以：

• 只改 markup
• 只在必要时添加 ARIA
• 重构组件层级
• 修改文案以提升理解度
• 如果当前设计本身不可访问，允许调整交互模式

这一点对结果质量的影响，通常比大多数用户预想得更大。

常见失败模式：过度使用 ARIA

无障碍工作里一个非常常见的问题，就是在原生 HTML 更合适时仍然滥加 ARIA。想提升输出质量，可以明确加上一句：

• “Prefer native semantic elements and only use ARIA when native semantics are insufficient.”

这条指令和仓库里的 ARIA 参考是一致的，也能明显减少低质量修复方案。

常见失败模式：漏掉状态变化

很多第一轮回答会注意到标签和焦点，却漏掉动态行为。建议你明确要求检查：

• focus entry and return
• expanded/collapsed state announcements
• validation error association
• async status messaging with live regions
• 在相关场景下考虑 reduced motion 和 high contrast

这些细节会实质性提升 accessibility-compliance guide 的可用性。

第一轮回答后继续迭代

完成初步审计后，可以继续追问以下任一项：

• “Rewrite the component with the fixes applied.”
• “Prioritize only release-blocking issues.”
• “Convert this into QA test steps.”
• “Explain what should be tested with screen readers.”
• “Separate WCAG AA requirements from nice-to-have AAA improvements.”

这样可以把这个技能从“评审助手”进一步变成“交付推进工具”。

有针对性地使用仓库参考文件

不要一上来就把整个仓库都读完。如果你的问题是：

• 语义结构或合规目标：先看 references/wcag-guidelines.md
• 组件行为或 roles：打开 references/aria-patterns.md
• 触控目标或移动端辅助技术：打开 references/mobile-accessibility.md

这种定向阅读路径，能让 accessibility-compliance install 和后续上手都更高效。

通过要求解释理由来提升可信度

可以要求这个技能说明：每一项修复为什么会影响键盘用户、屏幕阅读器用户、低视力用户，或对动态效果敏感的用户。这样有助于识别流于表面的修复，也方便团队在评审时为实现工作提供依据。

获取可直接投入生产的输出的最佳方式

如果你希望拿到高价值的 accessibility-compliance usage 结果，最好一次性要求它输出以下全部内容：

• 按优先级排序的问题发现
• 修正后的代码
• 修复理由
• 手动验证清单
• 剩余风险或前提假设

这正是大多数团队真正需要的交付包：把“我们应该提升无障碍”推进到“我们现在就能实现并验证”。