Fixing Accessibility

1---2name: fixing-accessibility3description: Audit and fix HTML accessibility issues including ARIA labels, keyboard navigation, focus management, color contrast, and form errors. Use when adding interactive controls, forms, dialogs, or reviewing WCAG compliance.4---5 6# fixing-accessibility7 8Fix accessibility issues.9 10## how to use11 12- `/fixing-accessibility`13  Apply these constraints to any UI work in this conversation.14 15- `/fixing-accessibility <file>`16  Review the file against all rules below and report:17  - violations (quote the exact line or snippet)18  - why it matters (one short sentence)19  - a concrete fix (code-level suggestion)20 21Do not rewrite large parts of the UI. Prefer minimal, targeted fixes.22 23## when to apply24 25Reference these guidelines when:26- adding or changing buttons, links, inputs, menus, dialogs, tabs, dropdowns27- building forms, validation, error states, helper text28- implementing keyboard shortcuts or custom interactions29- working on focus states, focus trapping, or modal behavior30- rendering icon-only controls31- adding hover-only interactions or hidden content32 33## rule categories by priority34 35| priority | category | impact |36|----------|----------|--------|37| 1 | accessible names | critical |38| 2 | keyboard access | critical |39| 3 | focus and dialogs | critical |40| 4 | semantics | high |41| 5 | forms and errors | high |42| 6 | announcements | medium-high |43| 7 | contrast and states | medium |44| 8 | media and motion | low-medium |45| 9 | tool boundaries | critical |46 47## quick reference48 49### 1. accessible names (critical)50 51- every interactive control must have an accessible name52- icon-only buttons must have aria-label or aria-labelledby53- every input, select, and textarea must be labeled54- links must have meaningful text (no “click here”)55- decorative icons must be aria-hidden56 57### 2. keyboard access (critical)58 59- do not use div or span as buttons without full keyboard support60- all interactive elements must be reachable by Tab61- focus must be visible for keyboard users62- do not use tabindex greater than 063- Escape must close dialogs or overlays when applicable64 65### 3. focus and dialogs (critical)66 67- modals must trap focus while open68- restore focus to the trigger on close69- set initial focus inside dialogs70- opening a dialog should not scroll the page unexpectedly71 72### 4. semantics (high)73 74- prefer native elements (button, a, input) over role-based hacks75- if a role is used, required aria attributes must be present76- lists must use ul or ol with li77- do not skip heading levels78- tables must use th for headers when applicable79 80### 5. forms and errors (high)81 82- errors must be linked to fields using aria-describedby83- required fields must be announced84- invalid fields must set aria-invalid85- helper text must be associated with inputs86- disabled submit actions must explain why87 88### 6. announcements (medium-high)89 90- critical form errors should use aria-live91- loading states should use aria-busy or status text92- toasts must not be the only way to convey critical information93- expandable controls must use aria-expanded and aria-controls94 95### 7. contrast and states (medium)96 97- ensure sufficient contrast for text and icons98- hover-only interactions must have keyboard equivalents99- disabled states must not rely on color alone100- do not remove focus outlines without a visible replacement101 102### 8. media and motion (low-medium)103 104- images must have correct alt text (meaningful or empty)105- videos with speech should provide captions when relevant106- respect prefers-reduced-motion for non-essential motion107- avoid autoplaying media with sound108 109### 9. tool boundaries (critical)110 111- prefer minimal changes, do not refactor unrelated code112- do not add aria when native semantics already solve the problem113- do not migrate UI libraries unless requested114 115## common fixes116 117```html118<!-- icon-only button: add aria-label -->119<!-- before --> <button><svg>...</svg></button>120<!-- after -->  <button aria-label="Close"><svg aria-hidden="true">...</svg></button>121 122<!-- div as button: use native element -->123<!-- before --> <div onclick="save()">Save</div>124<!-- after -->  <button onclick="save()">Save</button>125 126<!-- form error: link with aria-describedby -->127<!-- before --> <input id="email" /> <span>Invalid email</span>128<!-- after -->  <input id="email" aria-describedby="email-err" aria-invalid="true" /> <span id="email-err">Invalid email</span>129```130 131## review guidance132 133- fix critical issues first (names, keyboard, focus, tool boundaries)134- prefer native HTML before adding aria135- quote the exact snippet, state the failure, propose a small fix136- for complex widgets (menu, dialog, combobox), prefer established accessible primitives over custom behavior