# Wcag Accessibility

> >

- **Type:** Skill
- **Install:** `agentstack add skill-mrkanoh-claude-wcag-accessibility-skill-claude-wcag-accessibility-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mrKanoh](https://agentstack.voostack.com/s/mrkanoh)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mrKanoh](https://github.com/mrKanoh)
- **Source:** https://github.com/mrKanoh/claude-wcag-accessibility-skill
- **Website:** https://pauljadam.com

## Install

```sh
agentstack add skill-mrkanoh-claude-wcag-accessibility-skill-claude-wcag-accessibility-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Paul J. Adam Web & Mobile Accessibility Skill

## Overview

Comprehensive accessibility knowledge grounded in **WCAG 2.1 AA by default** (with full **WCAG 2.2** coverage), WAI-ARIA 1.2, and real-world audit, remediation, and handoff practice. Spans standards, semantic HTML, ARIA patterns, keyboard, screen readers, mobile (iOS/Android), typography, color, CI testing, KPIs, organizational processes, and disability theory.

### 🌍 Multilingual Behavior (CRITICAL)
You are a **polyglot accessibility expert**. While your underlying databases and CSV files are in English, you must **ALWAYS respond in the exact language the user is speaking**. 
- If the user asks in Spanish, translate the WCAG criteria, ARIA patterns, and explanations into Spanish on the fly.
- When speaking Spanish, ALWAYS use the terminology defined in `data/glossary-es.csv` to ensure industry-standard translations (e.g., "Screen reader" = "Lector de pantalla", "Landmark" = "Región de la página", "Focus" = "Foco").
- Never tell the user "the database is in English", just provide the translated answer seamlessly.

**Authority**: Paul J. Adam — Web & Mobile Accessibility Specialist/Consultant ([pauljadam.com](https://pauljadam.com/)). Curriculum themes additionally informed by industry-standard training paths (semantic HTML for designers, ARIA, NVDA, VoiceOver/TalkBack, accessibility audits, inclusive research, accessibility KPIs, handoff, typography, color palette, disability models, mobile, developer test tooling).

---

## Searchable Data

CSV databases + a single Python CLI. Run from the skill root:

```bash
# WCAG
python scripts/search.py wcag --level AA
python scripts/search.py wcag --keyword contrast
python scripts/search.py wcag --id 2.5.8            # WCAG 2.2 target size

# Legal framework
python scripts/search.py legal --jurisdiction EU
python scripts/search.py legal --jurisdiction Chile

# Glossary ES ↔ EN
python scripts/search.py glossary --keyword lector
python scripts/search.py glossary --context Legal

# ARIA patterns
python scripts/search.py aria --component modal --detail

# Tools
python scripts/search.py tools --type screen-reader --platform Windows --free

# Screen reader shortcuts
python scripts/search.py keys --reader NVDA --action heading

# Semantic HTML reference
python scripts/search.py semantic --element nav

# Typography & color
python scripts/search.py typography --category Spacing
python scripts/search.py color --scope Non-text

# Accessibility KPIs and handoff
python scripts/search.py kpis --category Remediation
python scripts/search.py handoff --phase Design --owner Designer

# Theoretical models of disability
python scripts/search.py models --keyword social

# Resources (books, blogs, research, tools)
python scripts/search.py resources --category Official
python scripts/search.py resources --type Blog
python scripts/search.py resources --authority W3C
python scripts/search.py resources --keyword WCAG
```

| File | Contents |
|------|----------|
| `data/wcag-criteria.csv` | WCAG 2.1 A/AA + **WCAG 2.2** additions (2.4.11–2.4.13, 2.5.7–2.5.8, 3.2.6, 3.3.7–3.3.9) |
| `data/aria-patterns.csv` | 25+ component patterns with required ARIA, keyboard, focus mgmt |
| `data/testing-tools.csv` | 30+ tools by type, platform, browser, cost |
| `data/screen-reader-keys.csv` | Shortcuts for NVDA, JAWS, VoiceOver (macOS/iOS), TalkBack, Narrator |
| `data/semantic-html.csv` | Semantic HTML reference — element → role → when to use / avoid |
| `data/typography-rules.csv` | 20 rules for accessible typography mapped to WCAG |
| `data/color-palette-rules.csv` | Palette creation rules (contrast, states, color blindness, HCM) |
| `data/kpis.csv` | 15 accessibility KPIs with formulas and targets |
| `data/handoff-checklist.csv` | Research → Design → Dev → QA → Release handoff checklist |
| `data/disability-models.csv` | Medical / Social / Biopsychosocial / CRPD / etc. |
| `data/glossary-es.csv` | Spanish ↔ English a11y terminology (70+ terms) |
| `data/legal-framework.csv` | 25+ jurisdictions: laws, standards, effective dates |
| `data/resources.csv` | 50+ authoritative books, blogs, research papers, tools, standards |
| `scripts/search.py` | CLI search across all databases |
| `templates/audit-report.md` | Complete audit report template (fill-in) |
| `templates/a11y-ci.yml` | GitHub Actions CI pipeline (axe + pa11y + Playwright + Lighthouse) |
| `prompts/` | Ready-to-use Claude prompts (audit, ARIA, alt text, handoff, KPIs) |

---

## When to Use

- WCAG 2.0 / 2.1 / 2.2 / Section 508 / EAA compliance questions
- WAI-ARIA roles, states, properties — which to use and how
- Building accessible forms, modals, tabs, accordions, tables, date pickers, autocompletes
- Keyboard navigation patterns and focus management
- Screen reader testing methodology (NVDA, JAWS, VoiceOver, TalkBack)
- Accessible typography, color palettes, buttons, links
- Designer → developer accessibility handoff
- Running an accessibility audit (scope, sampling, severity, reporting)
- Inclusive user research and interviews
- Accessibility KPIs and ACR/VPAT reporting
- Mobile accessibility (iOS VoiceOver / Android TalkBack)
- AI-assisted accessible development

---

## 1. Disability Models & Inclusive Mindset

Design decisions depend on which model of disability you implicitly assume. Prefer **Social** and **Human Rights (CRPD)** models; use **Biopsychosocial (WHO ICF)** when discussing context and interaction.

| Model | View | Design implication |
|-------|------|--------------------|
| **Medical** | Impairment to fix | Assistive devices; risk of pathologizing users |
| **Social** | Barriers disable people, not impairments | Remove barriers; universal design |
| **Biopsychosocial (ICF)** | Interaction of body, activity, participation, environment | Consider context & situational limitations |
| **Human Rights (CRPD)** | Access is a right | Accessibility is mandatory, not charity |
| **Charity** (avoid) | Pity-driven | Paternalistic design |
| **Identity / Affirmative** | Disability as valued identity | Co-design with disabled users |

> Full table: `data/disability-models.csv`

**Language**: use person-first ("person with a disability") or identity-first ("Deaf person", "autistic person") as the community prefers; avoid "suffers from", "wheelchair-bound", "handicapped", "special needs", "normal".

**Global statistics (WHO 2023)**: ~1.3 billion people — 16% of the world's population — live with a significant disability. Plan for permanent, temporary, and situational impairments.

---

## 2. WCAG Principles (POUR)

| Principle | Core requirement |
|-----------|-----------------|
| **Perceivable** | Alt text, captions, contrast, reflow, text spacing |
| **Operable** | Keyboard access, no traps, focus visible, skip links, no seizure triggers |
| **Understandable** | Page language, consistent nav, error identification and recovery |
| **Robust** | Valid HTML, ARIA name/role/value, status messages programmatically exposed |

### High-impact AA criteria (most commonly failed)

| ID | Criterion | Requirement |
|----|-----------|-------------|
| 1.1.1 | Non-text Content | `alt` for informative; `alt=""` for decorative |
| 1.3.1 | Info and Relationships | Semantic structure preserved programmatically |
| 1.4.3 | Contrast (Minimum) | 4.5:1 text / 3:1 large (18pt or 14pt bold) |
| 1.4.10 | Reflow | Usable at 320 CSS px with no horizontal scroll |
| 1.4.11 | Non-text Contrast | 3:1 for UI components and graphics |
| 1.4.12 | Text Spacing | Supports line-height 1.5, paragraph 2×, letter 0.12×, word 0.16× |
| 2.1.1 | Keyboard | All functionality operable by keyboard |
| 2.1.2 | No Keyboard Trap | Focus must never get stuck |
| 2.4.3 | Focus Order | Logical focus sequence |
| 2.4.7 | Focus Visible | Focus indicator must be visible |
| 3.3.1 | Error Identification | Errors described in text |
| 4.1.2 | Name, Role, Value | Interactive elements expose name/role/state |
| 4.1.3 | Status Messages | Dynamic updates announced without focus move |

### WCAG 2.2 additions (new since 2.1)

| ID | Level | Criterion | What changed |
|----|-------|-----------|--------------|
| 2.4.11 | AA | **Focus Not Obscured (Minimum)** | Focused element can't be entirely hidden by sticky UI |
| 2.4.12 | AAA | Focus Not Obscured (Enhanced) | …or *partially* hidden |
| 2.4.13 | AAA | Focus Appearance | ≥ 2 CSS px perimeter + 3:1 contrast |
| 2.5.7 | AA | **Dragging Movements** | Drag operations need a single-pointer alternative |
| 2.5.8 | AA | **Target Size (Minimum)** | Pointer targets ≥ 24×24 CSS px (exceptions apply) |
| 3.2.6 | A | **Consistent Help** | Help mechanisms in consistent relative order |
| 3.3.7 | A | **Redundant Entry** | Don't force re-entry of already-provided info |
| 3.3.8 | AA | **Accessible Authentication (Minimum)** | No cognitive-function tests (allow paste, password manager, WebAuthn) |
| 3.3.9 | AAA | Accessible Authentication (Enhanced) | No cognitive-function tests at all |

> Full criteria database: `data/wcag-criteria.csv`

---

## 3. Semantic HTML First

**Rule of thumb**: semantic HTML > ARIA. Only reach for ARIA when no native element provides the semantics.

```html
       

         
        
       
  

…      
   
            
        

  
        
                  
```

**Common mistake**: using `` for a button — breaks keyboard, SR, and focus. Always prefer ``.

> Full element reference: `data/semantic-html.csv`

---

## 4. WAI-ARIA Quick Reference

### Three rules of ARIA
1. Don't use ARIA if a native element exists.
2. Don't change native semantics unless you really must.
3. All interactive ARIA controls must be keyboard-operable and have an accessible name.

### Essential roles
```html
role="dialog"      aria-modal="true"
role="alertdialog"
role="alert"                             
role="status"                            
role="tablist" role="tab" role="tabpanel"
role="combobox" role="listbox" role="option"
role="grid" role="row" role="gridcell"
role="progressbar" role="slider" role="switch"
role="tree" role="treeitem"
role="menu" role="menuitem"
```

### Essential properties & states
```html
aria-label="Close"
aria-labelledby="heading-id"
aria-describedby="hint-id"
aria-expanded="true|false"
aria-selected="true|false"
aria-checked="true|false|mixed"
aria-hidden="true"                 
aria-live="polite|assertive"
aria-invalid="true"
aria-required="true"
aria-modal="true"
aria-disabled="true"
aria-sort="ascending|descending"
aria-current="page|step|date|true"
aria-haspopup="menu|listbox|dialog|grid|tree"
aria-activedescendant="id"
aria-controls="id"
aria-owns="id"
```

> Full component patterns: `data/aria-patterns.csv`

---

## 5. Accessible Components

### Modal Dialog
```html

  Confirm Delete
  This action cannot be undone.
  Delete
  ×

```
- Move focus to first focusable element inside on open
- Return focus to trigger on close
- Tab cycles within dialog; Escape closes
- Background: `inert` (or `aria-hidden="true"` with care)

### Tab Panel
```html

  Profile
  Security

…
…
```
- Arrow keys switch tabs; Home/End jump to first/last
- Active tab `tabindex="0"`; inactive `tabindex="-1"` (roving tabindex)

### Accessible Form Validation
```html
Email *

We'll never share it.
Enter a valid email address.
```

### Combobox (Autocomplete)
```html
Search

  Apple
  Avocado

```

### Accessible Button vs. Link (WCAG 2.2 friendly)
```html

Like

Dashboard

  …

```
- Targets ≥ **24×24 CSS px** (WCAG 2.5.8). 44×44 recommended for touch.
- Visible focus ring, ≥ 3:1 vs adjacent colors (WCAG 2.4.11).
- Never rely on color alone for state (e.g., disabled, selected).

### Accessible Drag & Drop (WCAG 2.5.7)
Always provide a non-drag alternative:
```html

  Item A
    ↑
    ↓
  

```

---

## 6. Accessible Typography

| Rule | Recommendation | WCAG |
|------|----------------|------|
| Body size | ≥ 16 px / 1rem | 1.4.4 |
| Line height | ≥ 1.5× font size | 1.4.12 |
| Paragraph spacing | ≥ 2× font size | 1.4.12 |
| Letter / word spacing | 0.12× / 0.16× supported | 1.4.12 |
| Line length | 45–75 characters | 1.4.8 AAA |
| Alignment | Left-align LTR; avoid justified | 1.4.8 AAA |
| Reflow | Usable at 320 CSS px width | 1.4.10 |
| Zoom | Works at 200% (AA) / 400% reflow | 1.4.4 / 1.4.10 |
| Contrast | 4.5:1 body / 3:1 large | 1.4.3 |
| Avoid all-caps for long copy | Reduces legibility & SR may spell | — |
| Body weight ≥ 400 | Avoid 100–300 for paragraphs | 1.4.3 |
| Dyslexia-friendly faces | Atkinson Hyperlegible, Lexend, Inter | — |
| No text-in-images | Use real text (logos exempt) | 1.4.5 |

```css
/* Text-spacing user override test — content must not be clipped */
* {
  line-height: 1.5 !important;
  letter-spacing: 0.12em !important;
  word-spacing: 0.16em !important;
}
p { margin-bottom: 2em !important; }
```

> Full ruleset: `data/typography-rules.csv`

---

## 7. Accessible Color Palettes

### Contrast matrix (WCAG 2.1 / 2.2)

| Context | Ratio |
|---------|-------|
| Body text (AA) | 4.5:1 |
| Large text (AA) — 18pt / 14pt bold | 3:1 |
| Body text (AAA) | 7:1 |
| UI components / icons / borders | 3:1 (1.4.11) |
| Focus indicator vs adjacent | 3:1 (2.4.11 / 2.4.13) |

### Palette design workflow
1. Define semantic tokens: `text`, `text-muted`, `bg`, `surface`, `border`, `primary`, `success`, `warning`, `error`, `focus`.
2. For each token, define **default / hover / active / focus / disabled** variants.
3. Audit every *pair* used in UI against the matrix.
4. Test in **dark mode**, **high contrast mode** (`forced-colors: active`), and color-blindness simulators (deuteranopia, protanopia, tritanopia).
5. Never encode meaning in color alone — pair with icon, text, or pattern.

```css
/* Windows High Contrast Mode support */
@media (forced-colors: active) {
  button { border: 1px solid ButtonText; }
  :focus-visible { outline: 2px solid CanvasText; }
}
```

> Full rules: `data/color-palette-rules.csv`

---

## 8. Keyboard Interaction Patterns

| Widget | Keys |
|--------|------|
| Link | Tab, Enter |
| Button | Tab, Enter, Space |
| Checkbox / Switch | Tab, Space |
| Radio group | Tab onto group; Arrow keys between |
| Select / Listbox | Tab, Arrows, Home/End, type-ahead |
| Combobox | Tab, Arrows, Enter, Esc |
| Tabs | Tab to list; Arrow keys switch; Enter/Space activate |
| Menu / Menu bar | Arrow keys, Enter, Esc, Tab exits |
| Dialog | Tab cycles inside; Esc closes |
| Tree | Arrows (→ expand, ← collapse), Enter activates |
| Grid / Data table | Arrow keys between cells; Enter activates cell editor |
| Slider | Arrow keys, Home/End, PgUp/PgDn |
| Date picker | Arrow keys calendar, PgUp/PgDn months |

---

## 9. Audit Methodology

Structured audit framework (matches professional curriculum):

```
1. Scope       Sample pages (home, template types, auth, checkout, top 10 by traffic)
2. Standard    WCAG 2.1/2.2 level (usually AA); jurisdictional overlays (Section 508, EN 301 549, EAA)
3. Automated   axe DevTools + Lighthouse + WAVE → baseline violations
4. Keyboard    Tab through every flow; verify reachability + visible focus
5. Screen AT   NVDA+Firefox, VoiceOver+Safari, TalkBack+Chrome
6. Visual      Zoom 200% & 400%; reflow 320 px; text-spacing override
7. Manual SC   Check non-automatable criteria (1.3.1 structure, 2.4.3 order, 3.3.x errors, 2.5.x target size, 2.4.11 focus obscured)
8. Findings    One row per issue: URL · element · criterion · severity · steps · recommendation
9. Severity    Critical / Serious / Moderate / Minor (align to Deque or internal scale)
10. Report     Executive summary, remediation plan, VPAT/ACR update, retest plan
```

**Sampling guidance**: choose representative templates rather than every page. Re-audit the same sample after remediation to measure regression.

**ACR/VPAT**: maintain a current Accessibility Conformance Report mapping every WCAG SC → Supports / Partially Supports / Does Not Support / Not Applicable with rationale.

---

## 10. Inclusive Research & Interviews

- Recruit across disability categories: vision (blind, low

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mrKanoh](https://github.com/mrKanoh)
- **Source:** [mrKanoh/claude-wcag-accessibility-skill](https://github.com/mrKanoh/claude-wcag-accessibility-skill)
- **License:** MIT
- **Homepage:** https://pauljadam.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mrkanoh-claude-wcag-accessibility-skill-claude-wcag-accessibility-skill
- Seller: https://agentstack.voostack.com/s/mrkanoh
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.