---
id: sm-wcag-audit-patterns
name: "wcag-audit-patterns"
url: https://skills.yangsir.net/skill/sm-wcag-audit-patterns
author: wshobson
domain: ai-frontend-engineering
tags: ["wcag", "web-accessibility", "accessibility-audits", "frontend-development", "compliance-testing"]
install_count: 12400
rating: 4.50 (20 reviews)
github: https://github.com/wshobson/agents
---

# wcag-audit-patterns

> 掌握WCAG审计模式，结合智能自动化与多智能体编排，确保前端应用符合无障碍标准，提升用户体验。

**Stats**: 12,400 installs · 4.5/5 (20 reviews)

## Before / After 对比

### WCAG无障碍审计效率对比

| Metric | Before | After | Change |
|---|---|---|---|
| - | - | - | - |
| - | - | - | - |
| - | - | - | - |

## Readme

# wcag-audit-patterns

# WCAG Audit Patterns

Comprehensive guide to auditing web content against WCAG 2.2 guidelines with actionable remediation strategies.

## When to Use This Skill

- Conducting accessibility audits

- Fixing WCAG violations

- Implementing accessible components

- Preparing for accessibility lawsuits

- Meeting ADA/Section 508 requirements

- Achieving VPAT compliance

## Core Concepts

### 1. WCAG Conformance Levels

Level
Description
Required For

**A**
Minimum accessibility
Legal baseline

**AA**
Standard conformance
Most regulations

**AAA**
Enhanced accessibility
Specialized needs

### 2. POUR Principles

```
Perceivable:  Can users perceive the content?
Operable:     Can users operate the interface?
Understandable: Can users understand the content?
Robust:       Does it work with assistive tech?

```

### 3. Common Violations by Impact

```
Critical (Blockers):
├── Missing alt text for functional images
├── No keyboard access to interactive elements
├── Missing form labels
└── Auto-playing media without controls

Serious:
├── Insufficient color contrast
├── Missing skip links
├── Inaccessible custom widgets
└── Missing page titles

Moderate:
├── Missing language attribute
├── Unclear link text
├── Missing landmarks
└── Improper heading hierarchy

```

## Audit Checklist

### Perceivable (Principle 1)

```
## 1.1 Text Alternatives

### 1.1.1 Non-text Content (Level A)

- [ ] All images have alt text
- [ ] Decorative images have alt=""
- [ ] Complex images have long descriptions
- [ ] Icons with meaning have accessible names
- [ ] CAPTCHAs have alternatives

Check:

```html
<!-- Good -->
<img src="chart.png" alt="Sales increased 25% from Q1 to Q2" />
<img src="decorative-line.png" alt="" />

<!-- Bad -->
<img src="chart.png" />
<img src="decorative-line.png" alt="decorative line" />
```

```

## 1.2 Time-based Media

### 1.2.1 Audio-only and Video-only (Level A)

-  Audio has text transcript

-  Video has audio description or transcript

### 1.2.2 Captions (Level A)

-  All video has synchronized captions

-  Captions are accurate and complete

-  Speaker identification included

### 1.2.3 Audio Description (Level A)

-  Video has audio description for visual content

## 1.3 Adaptable

### 1.3.1 Info and Relationships (Level A)

-  Headings use proper tags (h1-h6)

-  Lists use ul/ol/dl

-  Tables have headers

-  Form inputs have labels

-  ARIA landmarks present

Check:

```
<!-- Heading hierarchy -->
<h1>Page Title</h1>
<h2>Section</h2>
<h3>Subsection</h3>
<h2>Another Section</h2>

<!-- Table headers -->
<table>
  <thead>
    <tr>
      <th scope="col">Name</th>
      <th scope="col">Price</th>
    </tr>
  </thead>
</table>

```

### 1.3.2 Meaningful Sequence (Level A)

-  Reading order is logical

-  CSS positioning doesn't break order

-  Focus order matches visual order

### 1.3.3 Sensory Characteristics (Level A)

-  Instructions don't rely on shape/color alone

-  "Click the red button" → "Click Submit (red button)"

## 1.4 Distinguishable

### 1.4.1 Use of Color (Level A)

-  Color is not only means of conveying info

-  Links distinguishable without color

-  Error states not color-only

### 1.4.3 Contrast (Minimum) (Level AA)

-  Text: 4.5:1 contrast ratio

-  Large text (18pt+): 3:1 ratio

-  UI components: 3:1 ratio

Tools: WebAIM Contrast Checker, axe DevTools

### 1.4.4 Resize Text (Level AA)

-  Text resizes to 200% without loss

-  No horizontal scrolling at 320px

-  Content reflows properly

### 1.4.10 Reflow (Level AA)

-  Content reflows at 400% zoom

-  No two-dimensional scrolling

-  All content accessible at 320px width

### 1.4.11 Non-text Contrast (Level AA)

-  UI components have 3:1 contrast

-  Focus indicators visible

-  Graphical objects distinguishable

### 1.4.12 Text Spacing (Level AA)

-  No content loss with increased spacing

-  Line height 1.5x font size

-  Paragraph spacing 2x font size

-  Letter spacing 0.12x font size

-  Word spacing 0.16x font size

```

### Operable (Principle 2)

```markdown
## 2.1 Keyboard Accessible

### 2.1.1 Keyboard (Level A)
- [ ] All functionality keyboard accessible
- [ ] No keyboard traps
- [ ] Tab order is logical
- [ ] Custom widgets are keyboard operable

Check:
```javascript
// Custom button must be keyboard accessible
<div role="button" tabindex="0"
     onkeydown="if(event.key === 'Enter' || event.key === ' ') activate()">

```

### 2.1.2 No Keyboard Trap (Level A)

-  Focus can move away from all components

-  Modal dialogs trap focus correctly

-  Focus returns after modal closes

## 2.2 Enough Time

### 2.2.1 Timing Adjustable (Level A)

-  Session timeouts can be extended

-  User warned before timeout

-  Option to disable auto-refresh

### 2.2.2 Pause, Stop, Hide (Level A)

-  Moving content can be paused

-  Auto-updating content can be paused

-  Animations respect prefers-reduced-motion

```
@media (prefers-reduced-motion: reduce) {
  * {
    animation: none !important;
    transition: none !important;
  }
}

```

## 2.3 Seizures and Physical Reactions

### 2.3.1 Three Flashes (Level A)

-  No content flashes more than 3 times/second

-  Flashing area is small (<25% viewport)

## 2.4 Navigable

### 2.4.1 Bypass Blocks (Level A)

-  Skip to main content link present

-  Landmark regions defined

-  Proper heading structure

```
<a href="#main" class="skip-link">Skip to main content</a>
<main id="main">...</main>

```

### 2.4.2 Page Titled (Level A)

-  Unique, descriptive page titles

-  Title reflects page content

### 2.4.3 Focus Order (Level A)

-  Focus order matches visual order

-  tabindex used correctly

### 2.4.4 Link Purpose (In Context) (Level A)

-  Links make sense out of context

-  No "click here" or "read more" alone

```
<!-- Bad -->
<a href="report.pdf">Click here</a>

<!-- Good -->
<a href="report.pdf">Download Q4 Sales Report (PDF)</a>

```

### 2.4.6 Headings and Labels (Level AA)

-  Headings describe content

-  Labels describe purpose

### 2.4.7 Focus Visible (Level AA)

-  Focus indicator visible on all elements

-  Custom focus styles meet contrast

```
:focus {
  outline: 3px solid #005fcc;
  outline-offset: 2px;
}

```

### 2.4.11 Focus Not Obscured (Level AA) - WCAG 2.2

-  Focused element not fully hidden

-  Sticky headers don't obscure focus

```

### Understandable (Principle 3)

```markdown
## 3.1 Readable

### 3.1.1 Language of Page (Level A)
- [ ] HTML lang attribute set
- [ ] Language correct for content

```html
<html lang="en">

```

### 3.1.2 Language of Parts (Level AA)

-  Language changes marked

```
<p>The French word <span lang="fr">bonjour</span> means hello.</p>

```

## 3.2 Predictable

### 3.2.1 On Focus (Level A)

-  No context change on focus alone

-  No unexpected popups on focus

### 3.2.2 On Input (Level A)

-  No automatic form submission

-  User warned before context change

### 3.2.3 Consistent Navigation (Level AA)

-  Navigation consistent across pages

-  Repeated components same order

### 3.2.4 Consistent Identification (Level AA)

-  Same functionality = same label

-  Icons used consistently

## 3.3 Input Assistance

### 3.3.1 Error Identification (Level A)

-  Errors clearly identified

-  Error message describes problem

-  Error linked to field

```
<input aria-describedby="email-error" aria-invalid="true" />
<span id="email-error" role="alert">Please enter valid email</span>

```

### 3.3.2 Labels or Instructions (Level A)

-  All inputs have visible labels

-  Required fields indicated

-  Format hints provided

### 3.3.3 Error Suggestion (Level AA)

-  Errors include correction suggestion

-  Suggestions are specific

### 3.3.4 Error Prevention (Level AA)

-  Legal/financial forms reversible

-  Data checked before submission

-  User can review before submit

```

### Robust (Principle 4)

```markdown
## 4.1 Compatible

### 4.1.1 Parsing (Level A) - Obsolete in WCAG 2.2
- [ ] Valid HTML (good practice)
- [ ] No duplicate IDs
- [ ] Complete start/end tags

### 4.1.2 Name, Role, Value (Level A)
- [ ] Custom widgets have accessible names
- [ ] ARIA roles correct
- [ ] State changes announced

```html
<!-- Accessible custom checkbox -->
<div role="checkbox"
     aria-checked="false"
     tabindex="0"
     aria-labelledby="label">
</div>
<span id="label">Accept terms</span>

```

### 4.1.3 Status Messages (Level AA)

-  Status updates announced

-  Live regions used correctly

```
<div role="status" aria-live="polite">3 items added to cart</div>

<div role="alert" aria-live="assertive">Error: Form submission failed</div>

```

```

## Automated Testing

```javascript
// axe-core integration
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 example
test('should have no accessibility violations', async ({ page }) => {
  await page.goto('/');
  const results = await runAccessibilityAudit(page);

  expect(results.violations).toHaveLength(0);
});

```

```
# CLI tools
npx @axe-core/cli https://example.com
npx pa11y https://example.com
lighthouse https://example.com --only-categories=accessibility

```

## Remediation Patterns

### Fix: Missing Form Labels

```
<!-- Before -->
<input type="email" placeholder="Email" />

<!-- After: Option 1 - Visible label -->
<label for="email">Email address</label>
<input id="email" type="email" />

<!-- After: Option 2 - aria-label -->
<input type="email" aria-label="Email address" />

<!-- After: Option 3 - aria-labelledby -->
<span id="email-label">Email</span>
<input type="email" aria-labelledby="email-label" />

```

### Fix: Insufficient Color Contrast

```
/* Before: 2.5:1 contrast */
.text {
  color: #767676;
}

/* After: 4.5:1 contrast */
.text {
  color: #595959;
}

/* Or add background */
.text {
  color: #767676;
  background: #000;
}

```

### Fix: Keyboard Navigation

```
// Make custom element keyboard accessible
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;
      }
    });
  }
}

```

## Best Practices

### Do's

- **Start early** - Accessibility from design phase

- **Test with real users** - Disabled users provide best feedback

- **Automate what you can** - 30-50% issues detectable

- **Use semantic HTML** - Reduces ARIA needs

- **Document patterns** - Build accessible component library

### Don'ts

- **Don't rely only on automated testing** - Manual testing required

- **Don't use ARIA as first solution** - Native HTML first

- **Don't hide focus outlines** - Keyboard users need them

- **Don't disable zoom** - Users need to resize

- **Don't use color alone** - Multiple indicators needed

Weekly Installs3.3KRepository[wshobson/agents](https://github.com/wshobson/agents)GitHub Stars31.5KFirst SeenJan 20, 2026Security Audits[Gen Agent Trust HubPass](/wshobson/agents/wcag-audit-patterns/security/agent-trust-hub)[SocketPass](/wshobson/agents/wcag-audit-patterns/security/socket)[SnykWarn](/wshobson/agents/wcag-audit-patterns/security/snyk)Installed onclaude-code2.5Kopencode2.4Kgemini-cli2.4Kcursor2.3Kcodex2.3Kgithub-copilot2.0K

---
*Source: https://skills.yangsir.net/skill/sm-wcag-audit-patterns*
*Markdown mirror: https://skills.yangsir.net/api/skill/sm-wcag-audit-patterns/markdown*