Claude Code Prompt to Fix WCAG Accessibility Violations

What this prompt does

This prompt turns Claude Code into a WCAG 2.1 auditor that reads your actual codebase instead of one pasted snippet. You point it at your [framework], your [view_directory], and your [component_directory], and it walks every template, every component, the inline HTML your controllers and helpers echo out, and the Tailwind or CSS classes that affect visibility and focus. Nothing gets skipped because you forgot to paste it.

It works because the checklist is structured the way an accessibility engineer actually audits: images and media, forms and inputs, navigation and document structure, interactive widgets, then color and contrast. Each item maps to a concrete failure mode — a placeholder masquerading as a label, a div with a click handler and no keyboard path, a modal that never traps focus — not a vague rule number. The [compliance_level] variable scopes the run to A, AA, or AAA, so you are not drowning in AAA findings when you only owe AA.

The output is what saves the hours. Every violation returns the file, the line, the exact WCAG criterion, a severity, the current code, and the fixed code, then a summary with counts by severity, an estimated fix time, and a compliance score. You get a prioritized, paste-ready punch list, not an essay.

When to use it

• Before a compliance deadline or formal accessibility audit, while there is still time to ship the fixes.
• When you inherit a legacy codebase and need a fast map of where the accessibility debt actually lives.
• After building custom interactive components — modals, dropdowns, comboboxes — the things screen readers and keyboards reliably break on.
• When Lighthouse or axe flags a score but hands you no corrected markup.
• As a recurring pass over the view layer so regressions get caught before users hit them.
• When onboarding a team to ARIA patterns and you want real before/after examples from your own code.

Example output

File: resources/views/components/newsletter-form.blade.php
Line: 14
Rule: 1.3.1 Info and Relationships (Level A)
Severity: Critical
Current code:
  <input type="email" placeholder="Your email" class="...">
Fixed code:
  <label for="nl-email" class="sr-only">Email address</label>
  <input id="nl-email" type="email" name="email"
         aria-required="true" placeholder="Your email" class="...">

File: resources/views/components/mobile-menu.blade.php
Line: 8
Rule: 4.1.2 Name, Role, Value (Level A)
Severity: Major
Current code:
  <div @click="open = !open">☰</div>
Fixed code:
  <button type="button" @click="open = !open"
          :aria-expanded="open" aria-controls="mobile-nav"
          aria-label="Toggle menu">☰</button>

— Summary —
Critical: 3  Major: 7  Minor: 5
Estimated fix time: ~2.5 hours
Compliance score (AA): 82%

Pro tips

• Scope the directories tightly. Setting [view_directory] and [component_directory] to your real paths (e.g. resources/views) keeps the audit fast and stops it inventing files. Broad scopes produce noise; narrow ones produce a punch list.
• Match [contrast_ratio] to your level. Pass 4.5:1 for AA body text or 3:1 for large text and UI; do not leave it implied. Note the model flags likely contrast failures from class names — verify the borderline ones in a real contrast tool.
• Spend the [additional_pattern] slot. This is where app-specific widgets go: a date picker, a Livewire modal, a custom file uploader. Naming your real components gets you targeted ARIA fixes instead of generic boilerplate.
• Treat the compliance score as relative, not certified. It is a triage signal for tracking progress run-to-run — it is not a legal conformance statement, and a static read cannot fully judge focus order or live-region behavior.
• Pair it with a runtime checker. This prompt sees source and writes the fixes; axe-core or Lighthouse catches computed contrast and dynamic states. Use the prompt for the corrected markup, the automated tool to confirm it in the rendered DOM.