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.csvto 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 foc |