fixing-accessibility

Fix accessibility issues.

how to use

• •

  /fixing-accessibility Apply these constraints to any UI work in this conversation.

• •

  /fixing-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.

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

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
• •all interactive elements must be reachable by Tab
• •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
• •expandable controls must use aria-expanded and aria-controls

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

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

See Also

• •wcag-audit-patterns — WCAG 2.2 audit checklist, POUR principles, automated testing, remediation patterns