Communitygithub.com

WCAG 审计模式

通过自动化测试、手动验证和修复指导,进行 WCAG 2.2 可访问性审计。适用于审计网站可访问性、修复 WCAG 违规或实现可访问设计模式。

WCAG 审计模式 是什么?

这是一套完整的 WCAG 2.2 可访问性审计指南,提供了从自动化测试到手动验证的全面流程。它涵盖了所有 POUR 原则(可感知、可操作、可理解、健壮性),并配有详细的检查清单和 HTML/CSS/JavaScript 修复示例。该技能支持 Playwright 和 axe-core 集成测试,以及 CLI 工具(如 @axe-core/cli、pa11y 和 Lighthouse)。对于开发者来说,它不仅指出了常见违规模式(如图片缺少 alt 文本、颜色对比度不足、键盘导航缺失),还给出了具体的修复模式,如表单标签、对比度和键盘导航的修复。此外,它还包含了最佳实践和需要避免的常见陷阱,是进行法律合规性审计(ADA/Section 508/VPAT)和提升网站包容性的实用工具。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ulasalyesil/personal-website-v2/tree/HEAD/.agent/skills/wcag-audit-patterns

在你喜欢的 AI 中提问

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

预览

来自技能 README

WCAG 审计模式 preview
WCAG 审计模式 preview

文档

WCAG 审计模式 是做什么的?

根据 WCAG 2.2 指南全面审计网页内容并提供可操作的修复策略。

何时使用此技能

  • 进行可访问性审计
  • 修复 WCAG 违规
  • 实现可访问组件
  • 应对可访问性诉讼
  • 满足 ADA/Section 508 要求
  • 实现 VPAT 合规

核心概念

1. WCAG 合规等级

等级描述适用场景
A最低可访问性法律基准
AA标准合规大多数法规
AAA增强可访问性特殊需求

2. POUR 原则

可感知:用户能否感知内容?
可操作:用户能否操作界面?
可理解:用户能否理解内容?
健壮性:是否能与辅助技术兼容?

3. 常见违规按影响分类

严重(阻塞性):
├── 功能性图片缺少替代文本
├── 交互元素无法键盘访问
├── 缺少表单标签
└── 无控件的自动播放媒体

较严重:
├── 颜色对比度不足
├── 缺少跳过导航链接
├── 不可访问的自定义控件
└── 缺少页面标题

中等:
├── 缺少语言属性
├── 链接文本不清晰
├── 缺少地标
└── 标题层级不当

审计清单

可感知(原则 1)

## 1.1 文本替代

### 1.1.1 非文本内容(A 级)

- [ ] 所有图片都有替代文本
- [ ] 装饰性图片使用 alt=""
- [ ] 复杂图片提供长描述
- [ ] 有意义图标具有可访问名称
- [ ] 验证码提供替代方案

检查:

```html
<!-- 良好 -->
<img src="chart.png" alt="销售额从第一季度到第二季度增长了 25%" />
<img src="decorative-line.png" alt="" />

<!-- 不良 -->
<img src="chart.png" />
<img src="decorative-line.png" alt="装饰线" />

## 1.2 时间媒体

### 1.2.1 纯音频和纯视频(A 级)

- [ ] 音频有文字转录
- [ ] 视频提供音频描述或转录

### 1.2.2 字幕(A 级)

- [ ] 所有视频都有同步字幕
- [ ] 字幕准确且完整
- [ ] 包含说话人标识

### 1.2.3 音频描述(A 级)

- [ ] 视频有音频描述,解释视觉内容

## 1.3 可适应

### 1.3.1 信息和关系(A 级)

- [ ] 标题使用正确标签(h1-h6)
- [ ] 列表使用 ul/ol/dl
- [ ] 表格有表头
- [ ] 表单输入有标签
- [ ] 存在 ARIA 地标

检查:

```html
<!-- 标题层级 -->
<h1>页面标题</h1>
<h2>章节</h2>
<h3>子章节</h3>
<h2>另一个章节</h2>

<!-- 表头 -->
<table>
  <thead>
    <tr>
      <th scope="col">名称</th>
      <th scope="col">价格</th>
    </tr>
  </thead>
</table>

1.3.2 有意义的顺序(A 级)

  • 阅读顺序符合逻辑
  • CSS 定位未破坏顺序
  • 焦点顺序与视觉顺序一致

1.3.3 感官特性(A 级)

  • 指令不依赖形状/颜色
  • "单击红色按钮" → "单击提交(红色按钮)"

1.4 可区分

1.4.1 颜色的使用(A 级)

  • 颜色不是传达信息的唯一方式
  • 链接无需颜色也能区分
  • 错误状态不只用颜色表示

1.4.3 对比度(最低)(AA 级)

  • 文字:4.5:1 对比度
  • 大文本(18pt+):3:1 对比度
  • UI 组件:3:1 对比度

工具:WebAIM 对比度检查器、axe DevTools

1.4.4 文字缩放(AA 级)

  • 文字放大到 200% 时无内容丢失
  • 在 320px 宽度下无水平滚动
  • 内容正确重排

1.4.10 重排(AA 级)

  • 在 400% 缩放时内容可重排
  • 无二维滚动
  • 在 320px 宽度下所有内容可访问

1.4.11 非文本对比度(AA 级)

  • UI 组件具有 3:1 对比度
  • 焦点指示器可见
  • 图形对象可区分

1.4.12 文字间距(AA 级)

  • 增加间距时无内容丢失
  • 行高为字体大小的 1.5 倍
  • 段落间距为字体大小的 2 倍
  • 字母间距为字体大小的 0.12 倍
  • 单词间距为字体大小的 0.16 倍

### 可操作(原则 2)

2.1 键盘可访问

2.1.1 键盘(A 级)

  • 所有功能可通过键盘访问
  • 无键盘陷阱
  • Tab 顺序符合逻辑
  • 自定义控件可通过键盘操作

检查:

// 自定义按钮必须可通过键盘访问
<div role="button" tabindex="0"
     onkeydown="if(event.key === 'Enter' || event.key === ' ') activate()">

2.1.2 无键盘陷阱(A 级)

  • 焦点可从所有组件移开
  • 模态对话框正确捕获焦点
  • 模态关闭后焦点返回

2.2 充足时间

2.2.1 时间可调(A 级)

  • 会话超时可延长
  • 超时前警告用户
  • 提供选项禁用自动刷新

2.2.2 暂停、停止、隐藏(A 级)

  • 移动内容可暂停
  • 自动更新内容可暂停
  • 动画尊重 prefers-reduced-motion
@media (prefers-reduced-motion: reduce) {
  * {
    animation: none !important;
    transition: none !important;
  }
}

2.3 癫痫和身体反应

2.3.1 三次闪烁(A 级)

  • 内容闪烁频率不超过每秒 3 次
  • 闪烁区域较小(< 25% 视口)

2.4 可导航

2.4.1 绕过块(A 级)

  • 存在跳转到主内容的链接
  • 定义了地标区域
  • 标题结构正确
<a href="#main" class="skip-link">跳转到主内容</a>
<main id="main">...</main>

2.4.2 页面标题(A 级)

  • 唯一且描述性的页面标题
  • 标题反映页面内容

2.4.3 焦点顺序(A 级)

  • 焦点顺序与视觉顺序一致
  • 正确使用 tabindex

2.4.4 链接目的(上下文内)(A 级)

  • 链接脱离上下文也有意义
  • 不要单独使用 "点击此处" 或 "阅读更多"
<!-- 不良 -->
<a href="report.pdf">点击此处</a>

<!-- 良好 -->
<a href="report.pdf">下载第四季度销售报告 (PDF)</a>

2.4.6 标题和标签(AA 级)

  • 标题描述内容
  • 标签描述用途

2.4.7 焦点可见(AA 级)

  • 所有元素上焦点指示器可见
  • 自定义焦点样式满足对比度
:focus {
  outline: 3px solid #005fcc;
  outline-offset: 2px;
}

2.4.11 焦点不被遮盖(AA 级)- WCAG 2.2

  • 焦点元素不被完全隐藏
  • 固定页眉不遮挡焦点

### 可理解(原则 3)

3.1 可读

3.1.1 页面语言(A 级)

  • HTML 设置了 lang 属性
  • 语言与实际内容匹配
<html lang="zh-CN">

3.1.2 部分语言(AA 级)

  • 语言变化处已标记
<p>法语单词 <span lang="fr">bonjour</span> 意为你好。</p>

3.2 可预测

3.2.1 焦点触发(A 级)

  • 焦点触发时不改变上下文
  • 焦点触发时不会出现意外弹窗

3.2.2 输入触发(A 级)

  • 不会自动提交表单
  • 上下文变化前警告用户

3.2.3 一致导航(AA 级)

  • 导航在不同页面间保持一致
  • 重复组件顺序相同

3.2.4 一致标识(AA 级)

  • 相同功能使用相同标签
  • 图标使用一致

3.3 输入辅助

3.3.1 错误标识(A 级)

  • 错误被清晰标识
  • 错误信息描述问题
  • 错误与输入字段关联
<input aria-describedby="email-error" aria-invalid="true" />
<span id="email-error" role="alert">请输入有效的电子邮件地址</span>

3.3.2 标签或说明(A 级)

  • 所有输入都有可见标签
  • 必填字段已标识
  • 提供格式提示

3.3.3 错误建议(AA 级)

  • 错误信息包含更正建议
  • 建议具体明确

3.3.4 错误预防(AA 级)

  • 法律/财务表单可撤回
  • 提交前检查数据
  • 用户可以提交前审查

### 健壮性(原则 4)

4.1 兼容

4.1.1 解析(A 级)- WCAG 2.2 中已废弃

  • 有效 HTML(良好实践)
  • 无重复 ID
  • 开始/结束标签完整

4.1.2 名称、角色、值(A 级)

  • 自定义控件具有可访问名称
  • ARIA 角色正确
  • 状态变化被宣布
<!-- 可访问的自定义复选框 -->
<div role="checkbox"
     aria-checked="false"
     tabindex="0"
     aria-labelledby="label">
</div>
<span id="label">接受条款</span>

4.1.3 状态信息(AA 级)

  • 状态更新被宣布
  • 正确使用实时区域
<div role="status" aria-live="polite">已将 3 件商品添加到购物车</div>

<div role="alert" aria-live="assertive">错误:表单提交失败</div>

## 自动化测试

```javascript
// axe-core 集成
const axe = require('axe-core');

async function runAccessibilityAudit(page) {
  await page.addScriptTag({ path: require.resolve('axe-core') });

  const results = await page.evaluate(async () => {
    return await axe.run(document, {
      runOnly: {
        type: 'tag',
        values: ['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa']
      }
    });
  });

  return {
    violations: results.violations,
    passes: results.passes,
    incomplete: results.incomplete
  };
}

// Playwright 测试示例
test('不应该有可访问性违规', async ({ page }) => {
  await page.goto('/');
  const results = await runAccessibilityAudit(page);

  expect(results.violations).toHaveLength(0);
});
# CLI 工具
npx @axe-core/cli https://example.com
npx pa11y https://example.com
lighthouse https://example.com --only-categories=accessibility

修复模式

修复:缺少表单标签

<!-- 修改前 -->
<input type="email" placeholder="电子邮件" />

<!-- 修改后:选项 1 - 可见标签 -->
<label for="email">电子邮件地址</label>
<input id="email" type="email" />

<!-- 修改后:选项 2 - aria-label -->
<input type="email" aria-label="电子邮件地址" />

<!-- 修改后:选项 3 - aria-labelledby -->
<span id="email-label">电子邮件</span>
<input type="email" aria-labelledby="email-label" />

修复:颜色对比度不足

/* 修改前:2.5:1 对比度 */
.text {
  color: #767676;
}

/* 修改后:4.5:1 对比度 */
.text {
  color: #595959;
}

/* 或添加背景 */
.text {
  color: #767676;
  background: #000;
}

修复:键盘导航

// 使自定义元素可通过键盘访问
class AccessibleDropdown extends HTMLElement {
  connectedCallback() {
    this.setAttribute("tabindex", "0");
    this.setAttribute("role", "combobox");
    this.setAttribute("aria-expanded", "false");

    this.addEventListener("keydown", (e) => {
      switch (e.key) {
        case "Enter":
        case " ":
          this.toggle();
          e.preventDefault();
          break;
        case "Escape":
          this.close();
          break;
        case "ArrowDown":
          this.focusNext();
          e.preventDefault();
          break;
        case "ArrowUp":
          this.focusPrevious();
          e.preventDefault();
          break;
      }
    });
  }
}

最佳实践

应做事项

  • 尽早开始 - 从设计阶段考虑可访问性
  • 使用真实用户测试 - 残障用户提供最佳反馈
  • 尽可能自动化 - 30-50% 的问题可检测
  • 使用语义化 HTML - 减少 ARIA 的使用
  • 记录模式 - 构建可访问组件库

不应做事项

  • 不要只依赖自动化测试 - 需要手动测试
  • 不要首先使用 ARIA - 优先使用原生 HTML
  • 不要隐藏焦点轮廓 - 键盘用户需要它们
  • 不要禁用缩放 - 用户需要调整大小
  • 不要仅使用颜色 - 需要多重指示器

资源

Individual skills in this repo

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

ulasalyesil/personal-website-v2

Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.

ulasalyesil/personal-website-v2

Conduct design interviews, generate five distinct UI variations in a temporary design lab, collect feedback, and produce implementation plans. Use when the user wants to explore UI design options, redesign existing components, or create new UI with multiple approaches to compare.

ulasalyesil/personal-website-v2

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.

ulasalyesil/personal-website-v2

Design and implement microinteractions, motion design, transitions, and user feedback patterns. Use when adding polish to UI interactions, implementing loading states, or creating delightful user experiences.

ulasalyesil/personal-website-v2

This skill is for interface design — dashboards, admin panels, apps, tools, and interactive products. NOT for marketing design (landing pages, marketing sites, campaigns).

ulasalyesil/personal-website-v2

Best practices and example-driven guidance for building SwiftUI views and components. Use when creating or refactoring SwiftUI UI, designing tab architecture with TabView, composing screens, or needing component-specific patterns and examples.

ulasalyesil/personal-website-v2

UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient. Integrations: shadcn/ui MCP for component search and examples.

ulasalyesil/personal-website-v2

Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".

ulasalyesil/personal-website-v2

Enforces an opinionated UI baseline to prevent AI-generated interface slop.

ulasalyesil/personal-website-v2

Build modern, composable, and accessible React UI components following the components.build specification. Use when creating, reviewing, or refactoring component libraries, design systems, or any reusable UI components. Triggers on tasks involving component APIs, composition patterns, accessibility, styling systems, or TypeScript props.

ulasalyesil/personal-website-v2

Ship correct, complete metadata.

ulasalyesil/personal-website-v2

Survey any codebase as a senior advisor and produce prioritized, self-contained implementation plans for OTHER models/agents to execute. Strictly read-only on source code — never implements, fixes, or refactors anything itself. Use when asked to audit a codebase, find improvement opportunities (bugs, security, performance, test coverage, tech debt, migrations, DX), suggest features or where to take the project next (roadmap, product direction), or generate handoff plans for another agent to implement.

ulasalyesil/personal-website-v2

Defines the product's objects, relationships, states, and vocabulary independently of any interface — the most load-bearing layer

ulasalyesil/personal-website-v2

Maps domain concepts, terminology conflicts, and bounded contexts — produces a noun harvest for the conceptual model layer

ulasalyesil/personal-website-v2

Maps interaction structure and flow — produces breadboard notation with edge cases, failure paths, and open decisions

ulasalyesil/personal-website-v2

Framework orientation for Layers of Product Design — load this first; provides the context all other skills depend on

ulasalyesil/personal-website-v2

User research planning and synthesis at the observed behaviour layer — produces candidate job stories with confidence ratings

ulasalyesil/personal-website-v2

Diagnostic audit across all seven layers — identifies the bottleneck layer and recommends where to focus

ulasalyesil/personal-website-v2

Connects user opportunities to business outcomes and solution bets — produces a strategy tree and prioritised experiments

ulasalyesil/personal-website-v2

Audits existing surface against lower-layer decisions and produces a surface decision inventory — vocabulary, object consistency, completeness, feedback, hierarchy, accessibility

相关技能