mcpField
A
accessibility

accessibility

github.com/oakoss设计与 UI20148 次安装11 周前更新
代码仓库

关于 accessibility

accessibility 技能提供 Web 无障碍设计与测试指南，围绕 WCAG 2.2 AA、键盘操作、ARIA 和语义化 HTML。它面向设计与开发人员，涵盖检查清单、常见误区及辅助技术测试方法。

主要功能

  1. 01WCAG 2.2 AA 检查要点
  2. 02键盘导航与焦点管理
  3. 03ARIA 属性使用指导
  4. 04语义化 HTML 与表单建议
  5. 05屏幕阅读器及自动化测试

适用场景

  1. 01审查页面的 WCAG AA 合规性
  2. 02检查键盘与屏幕阅读器操作
  3. 03改进表单标签和错误提示
  4. 04补充自动化无障碍测试

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/oakoss/agent-skills --skill accessibility

安装后在 Claude Code 中输入/accessibility确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
aria-patterns.md
color-and-media.md
focus-management.md
forms-validation.md
semantic-html.md
testing.md

详细介绍

Web 无障碍（WCAG 2.2 AA）

为所有人打造——无障碍是基本要求，而非附加功能。

对比度（WCAG AA）

元素最低比例
正文文本（< 18pt）4.5:1
大号文本（>= 18pt 或 14pt 粗体）3:1
UI 组件和焦点指示器3:1

WCAG 2.2 新增 AA 标准

标准要求
目标尺寸最小值（2.5.8）交互目标至少为 24x24 CSS 像素
焦点不被遮挡最小值（2.4.11）焦点元素至少部分可见，不被粘性页眉或覆盖层遮挡
焦点外观（2.4.13）焦点指示器的最小面积（2px 周长），且对比度变化达到 3:1
拖动操作（2.5.7）为任何拖动交互提供单指针替代方式
冗余输入（3.3.7）不得要求重新输入此前已提供的信息
帮助一致性（3.2.6）帮助机制（聊天、电话、常见问题）在各页面中的相对顺序保持一致
无障碍身份验证（3.3.8）登录时不得进行认知功能测试（允许粘贴、自动填充或其他替代方式）

基本键盘操作模式

按键操作
Tab / Shift+Tab在可聚焦元素之间导航
Enter / Space激活按钮和链接
方向键在小组件内导航（选项卡、菜单）
Escape关闭对话框和菜单
Home / End跳转到小组件中的第一项/最后一项

元素选择

需求元素
导航到页面<a href="...">
提交表单<button type="submit">
打开对话框<button aria-haspopup="dialog">
其他操作<button type="button">
独立完整的文章<article>
导航链接<nav>
补充信息<aside>

常见 ARIA 属性

属性用途
aria-label没有可见标签时提供名称
aria-labelledby引用现有文本作为标签
aria-describedby提供额外说明（提示、错误）
aria-live播报动态更新（polite 或 assertive）
aria-expanded表示可折叠/可展开状态
aria-hidden="true"对屏幕阅读器隐藏装饰性元素
aria-invalid标记有错误的表单字段
aria-required="true"标记必填字段
aria-busy表示加载状态

WCAG 2.2 AA 检查清单摘要

原则关键要求
可感知图片需提供替代文本，对比度 >= 4.5:1，不能仅用颜色传达信息，文本可放大至 200%，视频需提供字幕，支持 prefers-reduced-motion
可操作支持键盘操作，焦点清晰可见且不被遮挡，焦点外观符合最低要求，目标尺寸 >= 24px，提供跳转链接，提供拖动操作的替代方式
易理解<html lang="en">，导航一致，帮助信息位置一致，表单标签，错误识别，避免重复输入，认证流程易于访问
稳健HTML 有效，所有 UI 组件均具有名称、角色和值，状态消息使用 aria-live（SC 4.1.1 解析已不适用于 WCAG 2.2）

反模式

反模式修复方式
使用 <div onClick> 而非 <button>使用语义化 HTML 元素
使用 outline: none 且不提供替代样式使用 :focus-visible 并提供清晰可见的轮廓
将占位符用作标签使用 <label> 元素
tabindex > 0使用 DOM 顺序或 tabindex="0" / tabindex="-1"
仅用颜色指示状态添加图标和文本标签
跳过标题级别按顺序使用 h1-h6，并通过 CSS 设置样式
在 <button> 上使用 role="button"移除冗余的 ARIA
在交互元素上使用 aria-hidden绝不隐藏交互内容
固定字体大小（px）使用 rem 单位
模态对话框中没有焦点陷阱限制焦点范围，并支持按 Escape 关闭

常见错误

错误正确做法
为已有可见文本的元素添加 aria-label使用 aria-labelledby 引用现有可见文本
对非紧急更新使用 aria-live="assertive"大多数动态内容使用 aria-live="polite"；仅将 assertive 用于错误和警报
对信息性图片设置 alt=""提供描述性替代文本；仅对纯装饰图片使用空 alt
为不可聚焦元素添加键盘处理程序使用原生交互元素，或添加 tabindex="0"、role 和按键处理程序
仅使用 axe 等自动化工具测试自动扫描只能发现约 30% 的问题；务必补充仅用键盘和屏幕阅读器进行的测试

屏幕阅读器和浏览器组合

屏幕阅读器浏览器平台
JAWSChromeWindows
NVDAChromeWindows（免费）
NVDAFirefoxWindows（免费）
VoiceOverSafarimacOS / iOS
TalkBackChromeAndroid
NarratorEdgeWindows（内置）

测试快速指南

方法工具耗时
仅用键盘操作隐藏鼠标，按 Tab 键浏览页面5 分钟
屏幕阅读器JAWS + Chrome 或 NVDA + Chrome/Firefox10 分钟
屏幕阅读器VoiceOver + Safari（macOS）10 分钟
自动扫描axe DevTools 浏览器扩展2 分钟
LighthouseChrome F12 > Lighthouse > 无障碍性2 分钟
单元测试jest-axe（Jest）或 vitest-axe（Vitest）持续进行

委派

开展无障碍工作时，可委派给：

  • design-system — 颜色令牌和对比度验证
  • react-patterns — 组件模式和钩子
  • testing — jest-axe 集成和测试模式

资源

参考资料

  • 语义化 HTML 和结构 — 文档地标、标题层级、元素选择、跳过链接
  • 焦点管理 — 焦点指示器、焦点不被遮挡、对话框焦点陷阱、SPA 路由焦点、focus-visible 模式
  • ARIA 模式 — 无障碍选项卡、实时区域、带 ARIA 属性的数据表格
  • 表单和验证 — 标签关联、错误播报、冗余输入、无障碍身份验证
  • 颜色和媒体 — 对比度要求、减少动态效果、拖动操作的替代方式、视频字幕、替代文本
  • 测试 — 键盘测试、屏幕阅读器搭配、axe DevTools、jest-axe 和 vitest-axe 单元测试

评论

支持 Markdown