domains / software-engineering / web-accessibility-audit / accessibility

accessibility

Skill card

combined

The two skills cover the same domain but have distinct, non-overlapping material steps. The first skill (addyosmani) provides a specific 'Evidence-led audit workflow' involving Lighthouse/axe tools, accessibility-tree snapshots, and a re-run verification loop, which the second skill lacks. The second skill (LeoYeAI) provides a '5-Step Accessibility Process' with a semantic HTML decision tree, specific ARIA usage rules (Golden Rule), and a detailed React/TypeScript focus-trap implementation, which the first skill lacks. Additionally, they target different WCAG versions (2.2 vs 2.1). Combining them creates a complete skill that covers both the audit/verification process and the implementation patterns.

Repositories

Other copies

Combined skill

---
name: accessibility
description: Audit and implement web accessibility following WCAG 2.2 guidelines. Use for a11y audits, WCAG compliance, screen reader support, and keyboard navigation.
---

# Web Accessibility (WCAG 2.2)

## 1. Evidence-Led Audit Workflow
When a rendered page is available:
1. Run a live Lighthouse Accessibility audit (or axe CLI if live tools are unavailable).
2. Use failed audit nodes to localize the relevant component.
3. Inspect the accessibility tree for names, roles, and landmarks.
4. Fix the source, then re-run the audit and manual keyboard interaction.

*Note: Automated tools detect only a subset of barriers. A score of 100 is not conformance.*

## 2. Implementation: The 5-Step Process

### Step 1: Semantic HTML Foundation
Use the correct element for the job. Do not use `div` for interactive elements.
- **Navigation:** `<a href>`
- **Actions:** `<button>`
- **Grouping:** `<article>`, `<section>`, `<nav>`, `<aside>`

### Step 2: ARIA (The Golden Rule)
Use ARIA only when HTML cannot express the pattern.
- **Wrong:** `<button role="button">` (Redundant)
- **Right:** `<div role="dialog" aria-modal="true">` (Fills semantic gap)
- **Common:** `aria-label`, `aria-describedby`, `aria-live`, `aria-expanded`.

### Step 3: Keyboard Navigation & Focus Management
All interactive elements must be keyboard accessible.
- **Native:** Prefer `<button>` and `<a>` for free keyboard support.
- **Custom:** If using `div[role="button"]`, add `tabindex="0"` and handle `Enter`/`Space`.
- **Focus Traps:** In dialogs, save previous focus, trap Tab/Shift+Tab, and restore focus on close.

### Step 4: Color Contrast (WCAG 2.2)
- **Normal text:** 4.5:1 (AA) / 7:1 (AAA)
- **Large text:** 3:1 (AA) / 4.5:1 (AAA)
- **UI Components:** 3:1
- **Focus Indicators:** Must have 3:1 contrast against the background.

### Step 5: Forms & Text Alternatives
- **Labels:** Every input needs a visible `<label>`. Placeholders are not labels.
- **Images:** Descriptive `alt` text for content; `alt=""` for decorative.
- **Icons:** Icon buttons need `aria-label` or visually hidden text.

## 3. Code Patterns

### Focus Management (React/TS Example)
```typescript
useEffect(() => {
  const previousFocus = document.activeElement;
  const firstFocusable = dialogRef.current?.querySelector('button, [href], input');
  firstFocusable?.focus();

  const handleKeyDown = (e: KeyboardEvent) => {
    if (e.key === 'Escape') onClose();
    // Implement focus trap logic for Tab
  };

  document.addEventListener('keydown', handleKeyDown);
  return () => {
    document.removeEventListener('keydown', handleKeyDown);
    (previousFocus as HTMLElement)?.focus();
  };
}, []);
```

### Visually Hidden Text
```css
.visually-hidden {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}
```