Back to Details

a11y-audit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Accessibility Audit

无障碍审计

WCAG 2.2 Accessibility Audit and Remediation Skill
WCAG 2.2 无障碍审计与修复Skill

Description

描述

The a11y-audit skill provides a complete accessibility audit pipeline for modern web applications. It implements a three-phase workflow -- Scan, Fix, Verify -- that identifies WCAG 2.2 Level A and AA violations, generates exact fix code per framework, and produces stakeholder-ready compliance reports.
For every violation it finds, it provides the precise before/after code fix tailored to your framework (React, Next.js, Vue, Angular, Svelte, or plain HTML).
What this skill does:
  1. Scans your codebase for every WCAG 2.2 Level A and AA violation, categorized by severity (Critical, Major, Minor)
  2. Fixes each violation with framework-specific before/after code patterns
  3. Verifies that fixes resolve the original violations and introduces no regressions
  4. Reports findings in a structured format suitable for developers, PMs, and compliance stakeholders
  5. Integrates into CI/CD pipelines to prevent accessibility regressions
a11y-audit Skill为现代Web应用提供完整的无障碍审计流水线，实现扫描、修复、验证三阶段工作流——识别WCAG 2.2 A级和AA级违规问题，生成针对各框架的精准修复代码，并输出适合相关人员查看的合规报告。
针对每一个发现的违规问题，它都会提供适配你所用框架（React、Next.js、Vue、Angular、Svelte或纯HTML）的修复前后代码对比。
该Skill的功能：
  1. 扫描代码库中所有WCAG 2.2 A级和AA级违规问题，并按严重程度（严重、主要、次要）分类
  2. 修复每个违规问题，提供框架专属的修复前后代码示例
  3. 验证修复是否解决了原始违规问题且未引入新的回归
  4. 报告以结构化格式输出结果，适配开发者、产品经理和合规相关人员的需求
  5. 集成到CI/CD流水线中，防止无障碍问题出现回归

Features

功能特性

FeatureDescription
Full WCAG 2.2 ScanChecks all Level A and AA success criteria across your codebase
Framework DetectionAuto-detects React, Next.js, Vue, Angular, Svelte, or plain HTML
Severity ClassificationCategorizes each violation as Critical, Major, or Minor
Fix Code GenerationProduces before/after code diffs for every issue
Color Contrast CheckerValidates foreground/background pairs against AA and AAA ratios
Compliance ReportingGenerates stakeholder reports with pass/fail summaries
CI/CD IntegrationGitHub Actions, GitLab CI, Azure DevOps pipeline configs
Keyboard Navigation AuditDetects missing focus management and tab order issues
ARIA ValidationChecks for incorrect, redundant, or missing ARIA attributes
功能描述
完整WCAG 2.2扫描检查代码库中所有A级和AA级成功标准
框架自动检测自动识别React、Next.js、Vue、Angular、Svelte或纯HTML
严重程度分类将每个违规问题分为严重、主要、次要三个等级
修复代码生成为每个问题生成修复前后的代码差异
色彩对比度检查器验证前景/背景色组合是否符合AA和AAA对比度标准
合规报告生成生成适合开发者、产品经理和合规相关人员的结构化报告
CI/CD集成提供GitHub Actions、GitLab CI、Azure DevOps流水线配置
键盘导航审计检测缺失的焦点管理和Tab顺序问题
ARIA验证检查ARIA属性是否存在错误、冗余或缺失

Severity Definitions

严重程度定义

SeverityDefinitionExampleSLA
CriticalBlocks access for entire user groupsMissing alt text, no keyboard access to navigationFix before release
MajorSignificant barrier that degrades experienceInsufficient color contrast, missing form labelsFix within current sprint
MinorUsability issue that causes frictionRedundant ARIA roles, suboptimal heading hierarchyFix within next 2 sprints
严重程度定义示例处理时限
严重阻碍特定用户群体完全访问缺失替代文本、导航无法通过键盘访问发布前修复
主要造成显著障碍，降低体验质量色彩对比度不足、表单标签缺失当前迭代内修复
次要导致使用摩擦的可用性问题ARIA角色冗余、标题层级不合理未来两个迭代内修复

Usage

使用方法

Quick Start

快速开始

bash
undefined
bash
undefined

Scan entire project

扫描整个项目

python scripts/a11y_scanner.py /path/to/project
python scripts/a11y_scanner.py /path/to/project

Scan with JSON output for tooling

扫描并输出JSON格式结果供工具调用

python scripts/a11y_scanner.py /path/to/project --json
python scripts/a11y_scanner.py /path/to/project --json

Check color contrast for specific values

检查特定颜色值的对比度

python scripts/contrast_checker.py --fg "#777777" --bg "#ffffff"
python scripts/contrast_checker.py --fg "#777777" --bg "#ffffff"

Check contrast across a CSS/Tailwind file

检查CSS/Tailwind文件中的色彩对比度

python scripts/contrast_checker.py --file /path/to/styles.css
undefined
python scripts/contrast_checker.py --file /path/to/styles.css
undefined

Slash Command

斜杠命令

/a11y-audit                    # Audit current project
/a11y-audit --scope src/       # Audit specific directory
/a11y-audit --fix              # Audit and auto-apply fixes
/a11y-audit --report           # Generate stakeholder report
/a11y-audit --ci               # Output CI-compatible results
/a11y-audit                    # 审计当前项目
/a11y-audit --scope src/       # 审计指定目录
/a11y-audit --fix              # 审计并自动应用修复
/a11y-audit --report           # 生成面向相关人员的报告
/a11y-audit --ci               # 输出兼容CI的结果

Three-Phase Workflow

三阶段工作流

Phase 1: Scan -- Walk the source tree, detect framework, apply rule set.
bash
python scripts/a11y_scanner.py /path/to/project --format table
Phase 2: Fix -- Apply framework-specific fixes for each violation.
See references/framework-a11y-patterns.md for the complete fix patterns catalog.
Phase 3: Verify -- Re-run the scanner to confirm fixes and check for regressions.
bash
python scripts/a11y_scanner.py /path/to/project --baseline audit-baseline.json
阶段1：扫描 —— 遍历源码目录，检测框架，应用规则集。
bash
python scripts/a11y_scanner.py /path/to/project --format table
阶段2：修复 —— 针对每个违规问题应用框架专属修复方案。
完整修复模式目录请查看 references/framework-a11y-patterns.md。
阶段3：验证 —— 重新运行扫描器，确认修复生效且无回归问题。
bash
python scripts/a11y_scanner.py /path/to/project --baseline audit-baseline.json

Example: React Component Audit

示例：React组件审计

tsx
// BEFORE: src/components/ProductCard.tsx
function ProductCard({ product }) {
  return (
    <div onClick={() => navigate(`/product/${product.id}`)}>
      <img src={product.image} />
      <div style={{ color: '#aaa', fontSize: '12px' }}>{product.name}</div>
      <span style={{ color: '#999' }}>${product.price}</span>
    </div>
  );
}
#WCAGSeverityIssue
11.1.1Critical
<img>
missing 
alt
attribute
22.1.1Critical
<div onClick>
not keyboard accessible
31.4.3MajorColor 
#aaa
on white fails contrast (2.32:1, needs 4.5:1)
41.4.3MajorColor 
#999
on white fails contrast (2.85:1, needs 4.5:1)
54.1.2MajorInteractive element missing role and accessible name
tsx
// AFTER: src/components/ProductCard.tsx
function ProductCard({ product }) {
  return (
    <a href={`/product/${product.id}`} className="product-card"
       aria-label={`View ${product.name} - $${product.price}`}>
      <img src={product.image} alt={product.imageAlt || product.name} />
      <div style={{ color: '#595959', fontSize: '12px' }}>{product.name}</div>
      <span style={{ color: '#767676' }}>${product.price}</span>
    </a>
  );
}
See references/examples-by-framework.md for Vue, Angular, Next.js, and Svelte examples.
tsx
// 修复前：src/components/ProductCard.tsx
function ProductCard({ product }) {
  return (
    <div onClick={() => navigate(`/product/${product.id}`)}>
      <img src={product.image} />
      <div style={{ color: '#aaa', fontSize: '12px' }}>{product.name}</div>
      <span style={{ color: '#999' }}>${product.price}</span>
    </div>
  );
}
#WCAG标准严重程度问题
11.1.1严重
<img>
缺失
alt
属性
22.1.1严重
<div onClick>
无法通过键盘访问
31.4.3主要白色背景上的
#aaa
颜色对比度不达标（2.32:1，需达到4.5:1）
41.4.3主要白色背景上的
#999
颜色对比度不达标（2.85:1，需达到4.5:1）
54.1.2主要交互元素缺失角色和无障碍名称
tsx
// 修复后：src/components/ProductCard.tsx
function ProductCard({ product }) {
  return (
    <a href={`/product/${product.id}`} className="product-card"
       aria-label={`View ${product.name} - $${product.price}`}>
      <img src={product.image} alt={product.imageAlt || product.name} />
      <div style={{ color: '#595959', fontSize: '12px' }}>{product.name}</div>
      <span style={{ color: '#767676' }}>${product.price}</span>
    </a>
  );
}
Vue、Angular、Next.js和Svelte的完整审计示例请查看 references/examples-by-framework.md。

Tools Reference

工具参考

a11y_scanner.py

a11y_scanner.py

Usage: python scripts/a11y_scanner.py <path> [options]

Options:
  --json                  Output results as JSON
  --format {table,csv}    Output format (default: table)
  --severity {critical,major,minor}  Filter by minimum severity
  --framework {react,vue,angular,svelte,html,auto}  Force framework (default: auto)
  --baseline FILE         Compare against previous scan results
  --report                Generate stakeholder report
  --output FILE           Write results to file
  --quiet                 Suppress output, exit code only
  --ci                    CI mode: non-zero exit on critical issues
Usage: python scripts/a11y_scanner.py <path> [options]

Options:
  --json                  以JSON格式输出结果
  --format {table,csv}    输出格式（默认：table）
  --severity {critical,major,minor}  按最低严重程度过滤
  --framework {react,vue,angular,svelte,html,auto}  强制指定框架（默认：auto）
  --baseline FILE         与之前的扫描结果对比
  --report                生成面向相关人员的报告
  --output FILE           将结果写入文件
  --quiet                 抑制输出，仅返回退出码
  --ci                    CI模式：出现严重问题时返回非零退出码

contrast_checker.py

contrast_checker.py

Usage: python scripts/contrast_checker.py [options]

Options:
  --fg COLOR              Foreground color (hex)
  --bg COLOR              Background color (hex)
  --file FILE             Scan CSS file for color pairs
  --tailwind DIR          Scan directory for Tailwind color classes
  --json                  Output results as JSON
  --suggest               Suggest accessible alternatives for failures
  --level {aa,aaa}        Target conformance level (default: aa)
Usage: python scripts/contrast_checker.py [options]

Options:
  --fg COLOR              前景色（十六进制）
  --bg COLOR              背景色（十六进制）
  --file FILE             扫描CSS文件中的颜色组合
  --tailwind DIR          扫描目录中的Tailwind颜色类
  --json                  以JSON格式输出结果
  --suggest               为不达标颜色提供无障碍替代方案建议
  --level {aa,aaa}        目标合规等级（默认：aa）

Common Pitfalls

常见误区

PitfallCorrect Approach
role="button"
on a 
<div>
Use native 
<button>
-- includes keyboard handling for free
tabindex="0"
on everything		Only interactive elements need focus; use native elements
aria-label
on non-interactive elements		Use 
aria-labelledby
pointing to visible text
display: none
for screen reader hiding		Use 
.sr-only
class instead
Color alone to convey meaningAdd icons, text labels, or patterns alongside color
Placeholder as only labelAlways provide a visible 
<label>
outline: none
without replacement		Always provide a visible focus indicator via 
focus-visible
Empty 
alt=""
on informational images		Informational images need descriptive alt text
Skipping heading levels (h1 -> h3)Heading levels must be sequential
onClick
without 
onKeyDown
Add keyboard support or prefer native elements
Ignoring 
prefers-reduced-motion
Wrap animations in 
@media (prefers-reduced-motion: no-preference)
常见误区正确做法
在
<div>
上添加
role="button"
使用原生
<button>
标签——默认包含键盘处理功能
给所有元素添加
tabindex="0"
仅交互元素需要焦点；优先使用原生元素
在非交互元素上添加
aria-label
使用
aria-labelledby
指向可见文本
使用
display: none
隐藏屏幕阅读器内容		改用
.sr-only
类
仅通过颜色传达信息同时添加图标、文本标签或图案
仅使用占位符作为标签始终提供可见的
<label>
标签
使用
outline: none
但未替代		始终通过
focus-visible
提供可见的焦点指示器
给信息性图片添加空
alt=""
信息性图片需要描述性替代文本
跳过标题层级（h1 -> h3）标题层级必须连续
仅使用
onClick
而未添加
onKeyDown
添加键盘支持或优先使用原生元素
忽略
prefers-reduced-motion
将动画包裹在
@media (prefers-reduced-motion: no-preference)
中

Related Skills

关联Skill

SkillRelationship
senior-frontendFrontend patterns used in a11y fixes
code-reviewerInclude a11y checks in code review workflows
senior-qaIntegration of a11y testing into QA processes
playwright-proAutomated browser testing with accessibility assertions
epic-designWCAG 2.1 AA compliant animations and scroll storytelling
tdd-guideTest-driven development patterns for a11y test cases
Skill关联关系
senior-frontend无障碍修复中使用的前端模式
code-reviewer在代码审查流程中加入无障碍检查
senior-qa将无障碍测试集成到QA流程中
playwright-pro带有无障碍断言的自动化浏览器测试
epic-design符合WCAG 2.1 AA标准的动画和滚动叙事
tdd-guide无障碍测试用例的测试驱动开发模式

Reference Documentation

参考文档

ReferenceDescription
wcag-quick-ref.mdWCAG 2.2 Level A & AA criteria quick reference
wcag-22-new-criteria.mdNew WCAG 2.2 success criteria (Focus Appearance, Target Size, etc.)
aria-patterns.mdARIA patterns, keyboard interaction, and live regions
framework-a11y-patterns.mdFramework-specific fix patterns (React, Vue, Angular, Svelte, HTML)
color-contrast-guide.mdColor contrast checker details, Tailwind palette mapping, sr-only class
ci-cd-integration.mdGitHub Actions, GitLab CI, Azure DevOps, pre-commit hook configs
audit-report-template.mdStakeholder-ready audit report template
testing-checklist.mdManual testing checklist (keyboard, screen reader, visual, forms)
examples-by-framework.mdFull audit examples for Vue, Angular, Next.js, and Svelte
参考文档描述
wcag-quick-ref.mdWCAG 2.2 A级和AA级标准速查手册
wcag-22-new-criteria.mdWCAG 2.2新增成功标准（焦点外观、目标尺寸等）
aria-patterns.mdARIA模式、键盘交互和实时区域
framework-a11y-patterns.md框架特定修复模式（React、Vue、Angular、Svelte、HTML）
color-contrast-guide.md色彩对比度检查器详情、Tailwind调色板映射、sr-only类说明
ci-cd-integration.mdGitHub Actions、GitLab CI、Azure DevOps、提交前钩子配置
audit-report-template.md面向相关人员的审计报告模板
testing-checklist.md手动测试清单（键盘、屏幕阅读器、视觉、表单）
examples-by-framework.mdVue、Angular、Next.js和Svelte的完整审计示例

Resources

资源