Communitygithub.com

无障碍审核员

审核UI组件是否符合WCAG合规性、ARIA属性、键盘导航和屏幕阅读器支持。在构建前端组件或用户请求无障碍改进时使用。

无障碍审核员 是什么?

这个技能用于审核Web应用的无障碍合规性,主要依据WCAG 2.1 Level AA标准,并提供改进建议。它适用于构建或审核UI组件、用户提出无障碍改进需求、准备无障碍审计,或用户提及“无障碍”、“a11y”、“WCAG”、“屏幕阅读器”或“键盘导航”等关键词的场景。该技能详细列出了12个检查项,包括语义HTML、ARIA属性、键盘导航、替代文本、颜色对比度、表单标签、标题结构、动态内容、屏幕阅读器测试、常见问题、自动化测试工具和完整的WCAG 2.1 AA检查清单。它会指导开发者识别和修复缺失的替代文本、表单标签、标题层级、键盘焦点指示器,以及不合理的颜色对比度、非语义化标记、模态框焦点管理缺失、键盘陷阱和自动播放媒体等问题。该技能还推荐了自动化测试工具,如Lighthouse、axe-core和pa11y,并提供了在测试中集成的示例代码。它适用于多种开发平台和AI辅助开发环境,帮助团队从一开始就构建无障碍的应用。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/aiskillstore/marketplace/crazydubya/accessibility-auditor

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

预览

来自技能 README

无障碍审核员 preview
无障碍审核员 preview
无障碍审核员 preview

文档

无障碍审核员 是做什么的?

审核Web应用的无障碍合规性(WCAG 2.1 Level AA)并提供改进建议。

何时使用

  • 构建或审核UI组件
  • 用户请求无障碍改进
  • 准备无障碍审计
  • 用户提及“无障碍”、“a11y”、“WCAG”、“屏幕阅读器”或“键盘导航”

操作指南

1. 语义化HTML检查

使用正确的HTML元素:

<!-- 错误 -->
<div onclick="submit()">提交</div>

<!-- 正确 -->
<button onclick="submit()">提交</button>

语义化结构:

  • <header>、<nav>、<main>、<footer>
  • <article>、<section>、<aside>
  • <h1> 到 <h6> 按正确层级排列
  • <button> 用于操作,<a> 用于导航

2. ARIA属性

何时使用ARIA:

  • 自定义组件(标签页、手风琴、模态框)
  • 动态内容更新
  • 复杂交互
  • 语义化HTML不足以表达时

常用ARIA属性:

<!-- 地标角色 -->
<nav role="navigation" aria-label="主导航">

<!-- 组件角色 -->
<div role="button" tabindex="0" aria-pressed="false">

<!-- 实时区域 -->
<div role="alert" aria-live="assertive">发生错误</div>

<!-- 标签和描述 -->
<button aria-label="关闭对话框">×</button>
<input aria-describedby="password-help" />

ARIA第一条规则: 如果语义化HTML可行,就不要使用ARIA

3. 键盘导航

所有交互元素必须支持键盘操作:

// 为自定义元素添加键盘支持
<div
  role="button"
  tabindex="0"
  onClick={handleClick}
  onKeyDown={(e) => {
    if (e.key === 'Enter' || e.key === ' ') {
      handleClick();
    }
  }}
>
  点击我
</div>

Tab键顺序:

  • 使用 tabindex="0" 用于自定义交互元素
  • 避免使用 tabindex > 0(会导致混乱的Tab键顺序)
  • 仅使用 tabindex="-1" 实现编程焦点管理

焦点管理:

  • 可见的焦点指示器
  • 在模态框中锁定焦点
  • 关闭对话框时返回焦点
  • 主要内容跳过链接

4. 替代文本和图片

信息性图片:

<img src="chart.png" alt="第三季度销售额增长25%" />

装饰性图片:

<img src="decoration.png" alt="" />
<!-- 或 -->
<img src="decoration.png" role="presentation" />

复杂图片:

<figure>
  <img src="complex-chart.png" alt="季度销售图表" />
  <figcaption>
    图表数据的详细描述...
  </figcaption>
</figure>

5. 颜色和对比度

对比度比率(WCAG AA):

  • 普通文本:最低 4.5:1
  • 大号文本(18pt及以上):最低 3:1
  • UI组件:最低 3:1

不要仅依赖颜色:

<!-- 错误:仅使用颜色 -->
<span style="color: red;">错误</span>

<!-- 正确:图标 + 颜色 -->
<span style="color: red;">
  <svg aria-hidden="true"><!-- 错误图标 --></svg>
  <span class="sr-only">错误:</span>
  输入无效
</span>

6. 表单和标签

每个输入框都需要标签:

<!-- 显式标签 -->
<label for="email">邮箱</label>
<input id="email" type="email" />

<!-- 隐式标签 -->
<label>
  邮箱
  <input type="email" />
</label>

<!-- 图标按钮的 aria-label -->
<button aria-label="搜索">
  <svg><!-- 搜索图标 --></svg>
</button>

错误消息:

<input
  id="password"
  aria-invalid="true"
  aria-describedby="password-error"
/>
<div id="password-error" role="alert">
  密码必须至少8个字符
</div>

7. 标题和文档结构

正确的标题层级:

<h1>页面标题</h1>
  <h2>第一部分</h2>
    <h3>子部分 1.1</h3>
    <h3>子部分 1.2</h3>
  <h2>第二部分</h2>

不要跳过层级: h1 → h2 → h3(不要 h1 → h3)

8. 动态内容

向屏幕阅读器宣布更新:

<!-- 礼貌:等待用户暂停 -->
<div role="status" aria-live="polite">
  5条新消息
</div>

<!-- 断言:立即打断 -->
<div role="alert" aria-live="assertive">
  您的会话将在1分钟后过期
</div>

加载状态:

<button aria-busy="true" aria-label="加载中...">
  <span aria-hidden="true">加载</span>
</button>

9. 屏幕阅读器测试

仅屏幕阅读器可见的文本:

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

隐藏装饰性元素:

<svg aria-hidden="true"><!-- 图标 --></svg>

10. 常见检查问题

缺失:

  • 图片的替代文本
  • 表单输入框的标签
  • 正确的标题层级
  • 键盘焦点指示器
  • 图标按钮的ARIA标签

不当:

  • 低对比度文本
  • 非语义化标记(用div作为按钮)
  • 模态框缺少焦点管理
  • 键盘陷阱
  • 自动播放媒体

测试:

  • 仅键盘导航
  • 屏幕阅读器(NVDA、JAWS、VoiceOver)
  • 色盲模拟
  • 放大至200%
  • 自动化工具(axe、Lighthouse)

11. 自动化测试

工具:

# Lighthouse
npx lighthouse https://example.com --only-categories=accessibility

# axe-core
npm install --save-dev @axe-core/cli
npx axe https://example.com

# pa11y
npm install --save-dev pa11y
npx pa11y https://example.com

测试中集成:

import { axe } from 'jest-axe';

test('不应有无障碍违规项', async () => {
  const { container } = render(<MyComponent />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

12. WCAG 2.1 Level AA检查清单

可感知:

  • 非文本内容的文本替代
  • 音频/视频的字幕
  • 内容可适配(语义化标记)
  • 足够的颜色对比度

可操作:

  • 键盘可访问
  • 无键盘陷阱
  • 足够的时间限制(可调节)
  • 无诱发性癫痫的闪烁
  • 跳过导航链接
  • 描述性页面标题
  • 焦点顺序合理
  • 链接目的从上下文明确

可理解:

  • 指定页面语言(<html lang="en">)
  • 可预测的导航
  • 输入辅助(标签、说明、错误消息)

稳健:

  • 有效的HTML
  • 自定义组件的名称、角色、值
  • 与辅助技术兼容

最佳实践

  • 从一开始就构建无障碍
  • 使用真实的辅助技术进行测试
  • 优先使用语义化HTML,其次是ARIA
  • 保持逻辑文档结构
  • 提供多种访问内容的方式
  • 彻底测试键盘导航
  • 不要禁用页面缩放
  • 使用地标和标题

支持文件

  • reference/wcag-checklist.md:完整的WCAG 2.1 AA检查清单
  • reference/aria-patterns.md:常见的ARIA组件模式

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

相关技能