axe-core catches the easy 30% — colour contrast, alt text, role / label mismatch. The other 70% (focus traps, missing live regions, broken keyboard order, motion-triggered seizures) needs prompts that name the failure modes and demand reproduction steps.
Who this is for
Engineers shipping consumer apps that must meet WCAG 2.2 AA, designers handling a11y reviews, founders bidding on government / enterprise contracts that require an audit.
When not to use these prompts
Don’t use these for pure backend changes — wrong scope. Don’t use them without running axe-core first; AI shouldn’t re-do what a tool already did better.
Prompt anatomy / structure formula
Every a11y audit prompt should carry six elements:
- Role: who AI plays (SRE / release captain / staff engineer / QA lead).
- Context: stack / branch / failing logs / diff / dashboard URL.
- Goal: one concrete deliverable — root cause, checklist, plan, ticket list, runbook.
- Constraints: what AI MUST NOT do (don’t auto-fix, don’t hallucinate file paths).
- Output format: numbered findings, markdown table, JSON, unified diff, runnable code.
- Examples / signal: 1-2 “good” output examples, or counter-examples.
Best for
- PR-scoped a11y regression check
- Keyboard order verification on a complex component
- Screen-reader experience pass
- Reduced-motion + flicker audit
- Form error accessibility
12 copy-ready prompt templates
1. PR-scoped a11y diff
Audit this PR for a11y regressions in the diff only. Cover: (1) New interactive elements without keyboard handlers, (2) `role="button"` on non-buttons missing key handlers, (3) Removed aria-labels, (4) Decorative imagery added without `alt=""`, (5) Heading order broken. file:line + severity.2. Keyboard order verification
For `{componentName}`, describe the keyboard tab order step by step (Tab / Shift+Tab / Enter / Esc / Arrow keys). Flag: (1) Focus skipping a logical element, (2) Focus moving into invisible content, (3) Tab order that doesn't match visual order, (4) Esc that doesn't close a modal.Variables to swap: componentName
3. Screen-reader copy review
Audit what a screen reader will announce for `{componentName}`: (1) Accessible name (label / aria-label / aria-labelledby), (2) State announcements (selected / expanded / loading), (3) Live region for async results, (4) Icon-only buttons get a visible-or-aria-name. Output a script-like trace of expected announcements.Variables to swap: componentName
4. Form error accessibility
Audit this form's error UX: (1) Errors associated via `aria-describedby` to the right input, (2) Submission summary at top with anchor links, (3) Live region announces error count, (4) Focus moves to first invalid field on submit, (5) Errors don't rely on colour alone. file:line.5. Focus management on route change
For this SPA, audit focus management on navigation: (1) Does focus move to the new page's main heading? (2) Is title announced? (3) Are skip-links present and working? (4) Does focus survive modal open / close? Output failures + recipe per page.6. Motion + prefers-reduced-motion
Audit motion: (1) Any animation > 5s loops without pause? (2) Flashing > 3 times per second (seizure risk)? (3) Parallax / autoplay video without controls? (4) `prefers-reduced-motion` respected? Output file:line + fix.7. Colour contrast on the diff
For colour changes in this diff, compute contrast against WCAG AA: (1) Body text ≥ 4.5:1, (2) Large text / UI components ≥ 3:1, (3) Focus indicator ≥ 3:1 against adjacent colours. Don't check unchanged elements.8. Touch target size
Audit interactive targets on mobile: (1) ≥ 44×44 CSS px for primary actions, (2) Spacing between adjacent targets ≥ 8px, (3) Custom buttons in lists meet target. file:line + severity.9. Loading / async announcement
Audit async UX: (1) Loading state announced via aria-live or role="status", (2) Errors announced via aria-live="assertive" sparingly, (3) Optimistic UI matched by reverted state on failure. file:line.10. Custom widget ARIA pattern
For `{widgetType}`, verify it implements the WAI-ARIA authoring pattern. List: (1) Required role + key behaviours, (2) Where this implementation diverges, (3) Top 3 fixes by impact. Don't propose a full rewrite if 2 patches fix it.Variables to swap: widgetType — combobox / tabs / dialog / menu / treegrid
11. Mobile screen-reader walkthrough
Walk through this screen with VoiceOver (iOS) + TalkBack (Android). Predict announcements per swipe-right. Flag where Android / iOS will diverge meaningfully. Output a comparison table.12. A11y regression triage
Last release had {nIssues} a11y bug reports. Triage: (1) Cluster by component, (2) Identify the top 3 by user impact (severity × reach), (3) Suggest one preventive check per cluster.Variables to swap: nIssues
Common mistakes
- Treating “no axe violations” as a11y pass — covers ~30% of issues.
- Removing focus rings for design — kills keyboard usability.
- Using
<div onClick>instead of<button>— loses keyboard + screen reader. - Tab traps in modals because focus isn’t returned on close.
- Live regions assertive on every update — overwhelms screen readers.
- Form errors marked only with red colour — invisible to colour-blind users.
- Skipping reduced-motion check — modern guideline, easy to add.
How to push results further
- Run axe-core first, then use prompts for what axe misses.
- Test keyboard-only navigation manually on every new component.
- Inspect with VoiceOver / NVDA at least quarterly.
- Use semantic HTML; ARIA is the fallback, not the goal.
- Add a single
a11y.mdper component with the keyboard + screen-reader contract. - Block PRs with new axe-core violations; don’t block on pre-existing ones to avoid PR scope creep.
- Show focus rings — designers, hold the line.
Practical depth notes
Use these prompts as starting points, not final answers. For Accessibility Regression Audit Prompts: 12 Templates Beyond axe-core, the useful extra work is to replace every generic placeholder with a real constraint: audience, channel, length, brand voice, examples to imitate, and examples to avoid. Run at least two versions with different constraints, then compare the outputs side by side instead of accepting the first polished response.
A good result should pass three checks: it is specific enough that another person could reuse it, it avoids vague praise or filler, and it gives you an editable artifact rather than a broad suggestion. If the output feels generic, add one concrete reference, one forbidden pattern, and one measurable success criterion before rerunning the prompt.
FAQ
- Is axe-core enough for WCAG AA?: It covers about a third. Combine with manual keyboard + screen-reader checks.
- Do I need a real disabled tester?: Eventually yes for any consumer-scale product. Tooling + AI gets you to good, not great.
- What’s a quick “is this accessible” smoke test?: Unplug your mouse. Navigate the feature. If you can’t, neither can a keyboard user.
- How do I handle motion-sensitive users?:
@media (prefers-reduced-motion)swap to non-animated variants; never autoplay video with sound. - Are PDFs required to be accessible?: Yes for public-facing in many jurisdictions (US Section 508, EU EN 301 549).
- Can AI replace an a11y consultant?: Not for high-stakes audits. Use AI for routine checks and the consultant for edge cases.