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

priority category impact

1 accessible names critical

2 keyboard access critical

3 focus and dialogs critical

4 semantics high

5 forms and errors high

6 announcements medium-high

7 contrast and states medium

8 media and motion low-medium

9 tool boundaries critical

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