1---
2name: fixing-accessibility
3description: 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-accessibility
7 
8Fix accessibility issues.
9 
10## how to use
11 
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 apply
24 
25Reference these guidelines when:
26- adding or changing buttons, links, inputs, menus, dialogs, tabs, dropdowns
27- building forms, validation, error states, helper text
28- implementing keyboard shortcuts or custom interactions
29- working on focus states, focus trapping, or modal behavior
30- rendering icon-only controls
31- adding hover-only interactions or hidden content
32 
33## rule categories by priority
34 
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 reference
48 
49### 1. accessible names (critical)
50 
51- every interactive control must have an accessible name
52- icon-only buttons must have aria-label or aria-labelledby
53- every input, select, and textarea must be labeled
54- links must have meaningful text (no “click here”)
55- decorative icons must be aria-hidden
56 
57### 2. keyboard access (critical)
58 
59- do not use div or span as buttons without full keyboard support
60- all interactive elements must be reachable by Tab
61- focus must be visible for keyboard users
62- do not use tabindex greater than 0
63- Escape must close dialogs or overlays when applicable
64 
65### 3. focus and dialogs (critical)
66 
67- modals must trap focus while open
68- restore focus to the trigger on close
69- set initial focus inside dialogs
70- opening a dialog should not scroll the page unexpectedly
71 
72### 4. semantics (high)
73 
74- prefer native elements (button, a, input) over role-based hacks
75- if a role is used, required aria attributes must be present
76- lists must use ul or ol with li
77- do not skip heading levels
78- tables must use th for headers when applicable
79 
80### 5. forms and errors (high)
81 
82- errors must be linked to fields using aria-describedby
83- required fields must be announced
84- invalid fields must set aria-invalid
85- helper text must be associated with inputs
86- disabled submit actions must explain why
87 
88### 6. announcements (medium-high)
89 
90- critical form errors should use aria-live
91- loading states should use aria-busy or status text
92- toasts must not be the only way to convey critical information
93- expandable controls must use aria-expanded and aria-controls
94 
95### 7. contrast and states (medium)
96 
97- ensure sufficient contrast for text and icons
98- hover-only interactions must have keyboard equivalents
99- disabled states must not rely on color alone
100- do not remove focus outlines without a visible replacement
101 
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 relevant
106- respect prefers-reduced-motion for non-essential motion
107- avoid autoplaying media with sound
108 
109### 9. tool boundaries (critical)
110 
111- prefer minimal changes, do not refactor unrelated code
112- do not add aria when native semantics already solve the problem
113- do not migrate UI libraries unless requested
114 
115## common fixes
116 
117```html
118<!-- 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 guidance
132 
133- fix critical issues first (names, keyboard, focus, tool boundaries)
134- prefer native HTML before adding aria
135- quote the exact snippet, state the failure, propose a small fix
136- for complex widgets (menu, dialog, combobox), prefer established accessible primitives over custom behavior