Fix Web Accessibility

Fix Web Accessibility

Fix accessibility issues.

how to use

• /fix-web-accessibility Apply these constraints to any UI work in this conversation.

• /fix-web-accessibility <file> Review the file against all rules below and report:

  • violations (quote the exact line or snippet)
  • why it matters (one short sentence)
  • a concrete fix (code-level suggestion)

Do not rewrite large parts of the UI. Prefer minimal, targeted fixes.

standards and conformance target

• target WCAG 2.2 Level AA by default, while honoring explicit project conformance requirements; AA covers both Level A and Level AA success criteria
• use the WCAG 2.2 Quick Reference to check applicable criteria and their exceptions; the rules below are a focused checklist, not a complete conformance audit
• include relevant WCAG 2.2 additions: obscured focus (2.4.11), alternatives to dragging (2.5.7), pointer target size (2.5.8), consistent help placement (3.2.6), repeated data entry (3.3.7), and accessible authentication (3.3.8)
• use ARIA APG patterns for widget semantics, keyboard interaction, states, and focus management; preserve native HTML behavior where it provides the needed interaction
• APG is informative implementation guidance, and its examples require integration and testing; following a pattern alone does not establish WCAG conformance
• conformance applies to full pages and complete processes; a component review or passing automated scan cannot establish that the entire product conforms

when to apply

Reference these guidelines when:

• adding or changing buttons, links, inputs, menus, dialogs, tabs, dropdowns
• building forms, validation, error states, helper text
• implementing keyboard shortcuts or custom interactions
• working on focus states, focus trapping, or modal behavior
• rendering icon-only controls
• adding hover-only interactions or hidden content

rule categories by priority

These priorities are triage hints. Assess actual user impact and distinguish priority from WCAG conformance level.

quick reference

1. accessible names (critical)

• every interactive control must have an accessible name
• icon-only buttons must have aria-label or aria-labelledby
• every input, select, and textarea must be labeled
• links must have meaningful text (no “click here”)
• decorative icons must be aria-hidden

2. keyboard access (critical)

• do not use div or span as buttons without full keyboard support
• make every interaction operable by keyboard; use Tab between components and pattern-specific navigation within composite widgets, following APG keyboard conventions
• focus must be visible for keyboard users
• do not use tabindex greater than 0
• Escape must close dialogs or overlays when applicable

3. focus and dialogs (critical)

• modals must trap focus while open
• restore focus to the trigger on close
• set initial focus inside dialogs
• opening a dialog should not scroll the page unexpectedly

4. semantics (high)

• prefer native elements (button, a, input) over role-based hacks
• if a role is used, required aria attributes must be present
• lists must use ul or ol with li
• do not skip heading levels
• tables must use th for headers when applicable

5. forms and errors (high)

• errors must be linked to fields using aria-describedby
• required fields must be announced
• invalid fields must set aria-invalid
• helper text must be associated with inputs
• disabled submit actions must explain why

6. announcements (medium-high)

• critical form errors should use aria-live
• loading states should use aria-busy or status text
• toasts must not be the only way to convey critical information
• expose expanded state through native semantics or aria-expanded; apply aria-controls according to the chosen pattern, since it is optional for the disclosure pattern

7. contrast and states (medium)

• ensure sufficient contrast for text and icons
• hover-only interactions must have keyboard equivalents
• disabled states must not rely on color alone
• do not remove focus outlines without a visible replacement

8. media and motion (low-medium)

• images must have correct alt text (meaningful or empty)
• videos with speech should provide captions when relevant
• respect prefers-reduced-motion for non-essential motion
• avoid autoplaying media with sound

9. tool boundaries (critical)

• prefer minimal changes, do not refactor unrelated code
• do not add aria when native semantics already solve the problem
• do not migrate UI libraries unless requested

common fixes

<!-- icon-only button: add aria-label -->
<!-- before -->
<button><svg>...</svg></button>
<!-- after -->
<button aria-label="Close"><svg aria-hidden="true">...</svg></button>

<!-- div as button: use native element -->
<!-- before -->
<div
<!-- after -->
<button

<!-- form error: link with aria-describedby -->
<!-- before -->
<input id="email" /> <span>Invalid email</span>
<!-- after -->
<input id="email" aria-describedby="email-err" aria-invalid="true" /> <span id="email-err">Invalid email</span>

review guidance

• fix critical issues first (names, keyboard, focus, tool boundaries)
• prefer native HTML before adding aria
• quote the exact snippet, state the failure, propose a small fix
• for complex widgets (menu, dialog, combobox), prefer established accessible primitives over custom behavior
• cite the success criterion and level for verified WCAG failures; identify APG recommendations and other best practices separately
• combine automated checks with manual keyboard, focus, zoom/reflow, and relevant screen-reader testing; WAI evaluation guidance explains the limits of automation. Report the tested scope, remaining issues, and checks that could not be performed