mcpField
A
a11y-audit

a11y-audit

github.com/borghei测试与质量1.0k72 次安装1 周前更新
代码仓库

关于 a11y-audit

Accessibility Audit 是面向开发者的技能，用于检查 HTML 和 CSS 是否符合 WCAG 2.1 无障碍标准。它结合标记扫描与颜色对比度检查，并支持 JSON 输出和 CI 严格门禁。

主要功能

  1. 01扫描 HTML 中的 WCAG 2.1 问题
  2. 02检查图片替代文本与标题层级
  3. 03验证表单、ARIA 和地标
  4. 04测量 AA 与 AAA 颜色对比度
  5. 05建议符合标准的替代颜色
  6. 06支持 JSON 输出和严格模式

适用场景

  1. 01开发期间审计 HTML 模板
  2. 02发布前检查样式表对比度
  3. 03在 CI 中拦截 A 级违规
  4. 04修复无障碍问题后重新扫描

安装

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

$npx skills add https://github.com/borghei/claude-skills --skill a11y-audit

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

包含的文件

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

examples/
sample-page.html
references/
wcag-guidelines.md
scripts/
a11y_scanner.py
contrast_checker.py

详细介绍

无障碍审计

类别： 工程 领域： Web 无障碍

概述

无障碍审计技能可自动扫描 HTML 文件，检查是否违反 WCAG 2.1 合规要求，并依据 AA/AAA 标准检查颜色对比度。它能在开发早期发现缺失的替代文本、不正确的标题层级、未标注的表单输入项，以及不足的颜色对比度。

首先确认

运行审计前，请确认以下输入。如果任何信息未知或含糊不清，请询问，不要自行假设：

  • 目标与范围 — 要扫描哪些 HTML 文件、目录或 CSS（决定检查内容以及 --file/--dir/--css 参数）
  • 合规等级 — 目标为 A、AA 还是 AAA（决定对比度阈值，以及哪些违规项属于 CRITICAL、WARNING 或 INFO）
  • 使用场景 — 一次性修复还是 CI 门禁（决定是否使用 --strict 门禁及 JSON 输出）

停止规则：只询问最能影响输出的 2-3 项。如果用户说“直接起草”，则继续处理，并在文档开头列出你的假设。

快速开始

# Scan HTML for WCAG violations
python scripts/a11y_scanner.py --file index.html

# Scan a directory of HTML files
python scripts/a11y_scanner.py --dir ./src/templates

# Check color contrast
python scripts/contrast_checker.py --foreground "#333333" --background "#ffffff"

# Parse CSS file for contrast issues
python scripts/contrast_checker.py --css styles.css

# JSON output for CI
python scripts/a11y_scanner.py --file index.html --format json

工具概览

a11y_scanner.py

扫描 HTML 文件中的 WCAG 2.1 违规项，包括结构、语义和交互元素问题。

功能描述
图片替代文本检测非装饰性图片是否缺少或具有空的替代文本
标题层级验证 h1-h6 级别是否连续
表单标签确保输入项具有关联的 label 元素
ARIA 属性检查 ARIA 用法是否正确
链接文本标记“点击此处”或“阅读更多”等泛化文本
语言属性检查 html 元素是否包含 lang
Tab 顺序检测正数 tabindex 值
地标验证语义地标的使用情况
contrast_checker.py

依据 WCAG AA 和 AAA 阈值检查颜色对比度。

功能描述
比率计算计算相对亮度对比度比率
AA 合规普通文本为 4.5:1，大号文本为 3:1
AAA 合规普通文本为 7:1，大号文本为 4.5:1
CSS 解析从 CSS 中提取颜色/背景颜色对
颜色建议推荐最接近的合规颜色

工作流

完整无障碍审计
  1. 扫描 HTML - 对所有模板运行 a11y_scanner.py
  2. 检查对比度 - 对样式表运行 contrast_checker.py
  3. 分类处理 - 优先处理 A 级违规项
  4. 修复 - 修复关键问题（替代文本、表单标签、标题）
  5. 重新扫描 - 验证修复通过所有检查
CI 集成
# Gate on Level A violations
python scripts/a11y_scanner.py --dir ./templates --format json --level A --strict

# Check CSS contrast
python scripts/contrast_checker.py --css ./static/css/main.css --format json
开发工作流
  1. 提交前 - 快速扫描有更改的 HTML 文件
  2. PR 审查 - 将完整扫描纳入审查清单
  3. 预发布审计 - 发布前进行全面扫描
  4. 监控 - 定期安排审计

参考文档

  • WCAG 指南 - 合规等级、成功标准、常见修复方法

常见模式速查

WCAG 等级
等级描述典型要求
A最低基线法律合规
AA行业标准大多数法规、ADA
AAA增强级最佳实践目标
对比度比率
场景AAAAA
普通文本（<18pt）4.5:17:1
大号文本（>=18pt 粗体或 >=14pt）3:14.5:1
UI 组件3:13:1
快速修复
问题修复方法
缺少替代文本<img alt="Description of image">
跳过标题级别按顺序使用 h1 到 h6
没有表单标签<label for="inputId">Label</label>
链接文本泛化将“点击此处”替换为描述性文本
缺少 lang<html lang="en">
正数 tabindex仅使用 tabindex="0" 或 tabindex="-1"
严重级别映射
  • CRITICAL - WCAG A 级违规
  • WARNING - WCAG AA 级违规
  • INFO - WCAG AAA 级建议

评论

支持 Markdown