Wcag Accessibility

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). 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:

# 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.

       

         
        
       
  

…      
   
            
        

  
        
                  

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

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

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

  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

  Profile
  Security

…
…

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

Accessible Form Validation

Email *

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

Combobox (Autocomplete)

Search

  Apple
  Avocado

Accessible Button vs. Link (WCAG 2.2 friendly)

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:

  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 |

/* 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.

/* 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
• Source: mrKanoh/claude-wcag-accessibility-skill
• License: MIT
• Homepage: https://pauljadam.com

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