Accessibility Complaint Narrative Generation

Overview

This skill transforms technical WCAG accessibility scan data into human-centered violation narratives by combining:

1. Personal accessibility testing experiences (keyboard navigation, screen reader usage)
2. Technical scan findings (violation counts, WCAG criteria, code examples)
3. Real website content examples
4. Legal/technical citations

Output is plain-text prose suitable for demand letters, accessibility complaints, and audit documentation—without unnecessary formatting, section titles, or bold headings.

Workflow

Step 1: Extract Personal Experience Data

Document what you encountered when testing the website with actual assistive technology or keyboard-only navigation:

• Specific interaction failures (what broke, where, when)
• Exact error messages or stuck states
• Real content examples that failed (product names, page names, specific elements)
• User impact (what you couldn't accomplish)

Step 2: Extract Scan Data

From accessibility evaluation reports, collect:

• Total violation count
• Critical barrier count
• Pages evaluated / coverage percentage
• Violation counts by WCAG criterion (organize by Level A, Level AA, Level AAA)
• Specific violation instance counts (keyboard traps, missing alt text, heading issues, etc.)
• Semantic structure violation categories and counts
• Contact information for remediation
• Evaluation date, Scan ID, Data Integrity Hash
• Tools used (axe-core version, browser automation tool, custom analyzers)

Step 3: Map Personal Experience to Scan Data

Link your experienced barriers to technical violations:

• "I got stuck navigating the menu" → "19 keyboard trap instances found (WCAG 2.1.2 A)"
• "Carousel photos had no descriptions" → "Carousel images use empty alt="" tags, 28 semantic structure violations"
• "Site claims WCAG compliance but I found barriers" → "131 total violations across 20 pages, false accessibility claims"

Step 4: Structure Violation Narratives

For each major barrier, write one paragraph containing:

Pattern: [Personal experience using specific details] → [Scan finding with instance count] → [WCAG citation(s)]

Example: "When I try to navigate using only my keyboard, I immediately hit a barrier. The cookie consent modal at the bottom of the page traps my focus—I can't escape it until I tab through the entire website first. This is one of 19 keyboard trap instances the scan identified (WCAG 2.1.2 A violation)."

Step 5: Combine Narratives into Complaint

Order violation narratives by severity and impact:

1. Keyboard traps (blocks entire navigation)
2. Content accessibility (images, carousels, menus)
3. Page structure (headings, landmarks)
4. False accessibility claims (legal impact)
5. Summary statistics from scan

End with evaluation metadata (date, scan ID, hash, tools used).

Key Requirements

DO:

• Use first-person language ("When I try to navigate," "I get stuck," "I can't access")
• Name specific website elements (carousel, hero images, lunch menu)
• Include real content examples (product names, page names from the site)
• Cite WCAG criteria by number and level (WCAG 2.1.2 A, WCAG 1.1.1 A, etc.)
• Include violation instance counts from scan
• Connect personal barriers to technical findings
• Explain the impact (what users can't do)
• Provide evaluation metadata (date, scan ID, hash, tools)

DON'T:

• Use section titles or headers
• Use bold or other formatting
• Write generic descriptions ("some images lack alt text")
• Include markup or HTML code examples in plain narrative
• Separate violation narratives into different sections
• Repeat information unnecessarily
• Include legal language or demand language (this is narrative only)

Critical Violations to Prioritize

Order narratives by legal/user impact severity:

1. Keyboard Traps (WCAG 2.1.2 A) — Complete navigation failure, affects all users
2. Missing Alt Text (WCAG 1.1.1 A) — Blind/screen reader users completely excluded
3. Unlabeled Controls (WCAG 2.4.9 AAA) — Keyboard users can't understand purpose
4. Missing Headings (WCAG 2.4.6 AA) — Page structure broken for screen readers
5. Semantic Issues (WCAG 1.3.1 A, WCAG 2.4.1 A) — Navigation broken for multiple user types
6. Contrast Failures (WCAG 1.4.3 AA) — Low vision users can't read text
7. False Claims (ADA Title III) — Regulatory/legal violation

Data Mapping Reference

Keyboard Navigation Issues → WCAG Criteria:

• Focus trapped in modals, menus, carousels → WCAG 2.1.2 A (No Keyboard Trap)
• Illogical tab order → WCAG 2.4.3 (Focus Order)
• Missing focus indicators → WCAG 2.4.7 AA (Focus Visible)
• tabindex="-1" removing interactive elements from focus → WCAG 2.1.2 A, WCAG 2.4.3

Content Accessibility → WCAG Criteria:

• Empty alt attributes, missing descriptions → WCAG 1.1.1 A (Non-text Content)
• Background images with no alt text → WCAG 1.1.1 A
• Unlabeled buttons, links, controls → WCAG 2.4.9 AAA (Link Purpose), WCAG 4.1.2 A (Name, Role, Value)

Page Structure → WCAG Criteria:

• Missing H1 elements → WCAG 2.4.6 AA (Headings and Labels)
• Heading level skipping → WCAG 1.3.1 A (Info and Relationships)
• Duplicate landmarks → WCAG 2.4.1 A (Bypass Blocks)
• Improper semantic markup → WCAG 1.3.1 A

Visual Issues → WCAG Criteria:

• Insufficient color contrast → WCAG 1.4.3 AA (Contrast Minimum)

Markup Issues → WCAG Criteria:

• ARIA role/attribute mismatch → WCAG 4.1.2 A (Name, Role, Value)

Example Narrative Structure

Input data:

• Personal: "When I tab through the menu, I get stuck on lunch menu, can't reach other menu tabs"
• Scan: "19 keyboard trap instances. Menu uses tabindex='-1' on inactive tabs. WCAG 2.1.2 A violation"
• Content: "Lunch menu, main menu sections"

Output narrative: "The menu system is the worst offender. When I tab to the lunch menu, I get stuck there. The inactive menu tabs have tabindex="-1" on them, which completely removes them from keyboard focus. There's no way to switch to other menu sections—I'm trapped. The scan documented this across the menu system with tabindex="-1" errors leaving users unable to reach or interact with inactive tabs (WCAG 2.1.2 A, WCAG 2.4.3)."

Evaluation Metadata Template

Include at end of complaint narrative:

"Evaluation conducted [DATE]. Scan ID: [ID]. [X] of [Y] pages evaluated ([Z]% coverage). [N] keyboard trap instances, [N] semantic violations, [N] contrast failures, [N] missing H1 headings, [N] ARIA mismatches. Data Integrity Hash: [HASH]. Tools used: axe-core v[VERSION], [BROWSER AUTOMATION TOOL] v[VERSION], [CUSTOM ANALYZERS] v[VERSION]."

Common Pitfalls

WRONG: "The website has accessibility problems." RIGHT: "When I navigate using only my keyboard, I get stuck on the lunch menu because inactive tabs have tabindex="-1" on them. The scan found 19 keyboard trap instances (WCAG 2.1.2 A)."

WRONG: Organizing violations by WCAG criterion RIGHT: Ordering violations by user impact (keyboard traps first, affecting all users)

WRONG: Separating "what I experienced" from "what the scan found" RIGHT: Integrating both into single flowing paragraph

WRONG: Including HTML code examples in plain narrative RIGHT: Referencing violations conceptually (e.g., "tabindex='-1' errors" not <code> blocks)

WRONG: Generic language ("images lack descriptions") RIGHT: Specific details ("Carousel images use sr-only empty alt="" tags," "Gaspacho Moreira photo has no description")

When to Use This Skill

• Writing accessibility complaints or demand letters
• Creating audit narratives combining personal testing with automated scan results
• Generating evidence-based violation descriptions for legal proceedings
• Creating compelling accessibility violation reports
• Documenting barriers in plain language for stakeholders
• Combining user experience data with technical findings

When NOT to Use This Skill

• Creating formal legal documents (use template documents instead)
• Writing highly technical accessibility documentation
• Creating remediation guides
• Summarizing scan data without personal testing experience