fixing-accessibility
Fix accessibility issues.
how to use
Do not rewrite large parts of the UI. Prefer minimal, targeted fixes.
When to Use
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
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
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
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-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 Use
24Reference these guidelines when:
25- adding or changing buttons, links, inputs, menus, dialogs, tabs, dropdowns
26- building forms, validation, error states, helper text
27- implementing keyboard shortcuts or custom interactions
28- working on focus states, focus trapping, or modal behavior
29- rendering icon-only controls
30- adding hover-only interactions or hidden content
31
32## rule categories by priority
33
34| priority | category | impact |
35|----------|----------|--------|
36| 1 | accessible names | critical |
37| 2 | keyboard access | critical |
38| 3 | focus and dialogs | critical |
39| 4 | semantics | high |
40| 5 | forms and errors | high |
41| 6 | announcements | medium-high |
42| 7 | contrast and states | medium |
43| 8 | media and motion | low-medium |
44| 9 | tool boundaries | critical |
45
46## quick reference
47
48### 1. accessible names (critical)
49
50- every interactive control must have an accessible name
51- icon-only buttons must have aria-label or aria-labelledby
52- every input, select, and textarea must be labeled
53- links must have meaningful text (no “click here”)
54- decorative icons must be aria-hidden
55
56### 2. keyboard access (critical)
57
58- do not use div or span as buttons without full keyboard support
59- all interactive elements must be reachable by Tab
60- focus must be visible for keyboard users
61- do not use tabindex greater than 0
62- Escape must close dialogs or overlays when applicable
63
64### 3. focus and dialogs (critical)
65
66- modals must trap focus while open
67- restore focus to the trigger on close
68- set initial focus inside dialogs
69- opening a dialog should not scroll the page unexpectedly
70
71### 4. semantics (high)
72
73- prefer native elements (button, a, input) over role-based hacks
74- if a role is used, required aria attributes must be present
75- lists must use ul or ol with li
76- do not skip heading levels
77- tables must use th for headers when applicable
78
79### 5. forms and errors (high)
80
81- errors must be linked to fields using aria-describedby
82- required fields must be announced
83- invalid fields must set aria-invalid
84- helper text must be associated with inputs
85- disabled submit actions must explain why
86
87### 6. announcements (medium-high)
88
89- critical form errors should use aria-live
90- loading states should use aria-busy or status text
91- toasts must not be the only way to convey critical information
92- expandable controls must use aria-expanded and aria-controls
93
94### 7. contrast and states (medium)
95
96- ensure sufficient contrast for text and icons
97- hover-only interactions must have keyboard equivalents
98- disabled states must not rely on color alone
99- do not remove focus outlines without a visible replacement
100
101### 8. media and motion (low-medium)
102
103- images must have correct alt text (meaningful or empty)
104- videos with speech should provide captions when relevant
105- respect prefers-reduced-motion for non-essential motion
106- avoid autoplaying media with sound
107
108### 9. tool boundaries (critical)
109
110- prefer minimal changes, do not refactor unrelated code
111- do not add aria when native semantics already solve the problem
112- do not migrate UI libraries unless requested
113
114## common fixes
115
116```html
117<!-- icon-only button: add aria-label -->
118<!-- before --> <button><svg>...</svg></button>
119<!-- after --> <button aria-label="Close"><svg aria-hidden="true">...</svg></button>
120
121<!-- div as button: use native element -->
122<!-- before --> <div onclick="save()">Save</div>
123<!-- after --> <button onclick="save()">Save</button>
124
125<!-- form error: link with aria-describedby -->
126<!-- before --> <input id="email" /> <span>Invalid email</span>
127<!-- after --> <input id="email" aria-describedby="email-err" aria-invalid="true" /> <span id="email-err">Invalid email</span>
128```
129
130## review guidance
131
132- fix critical issues first (names, keyboard, focus, tool boundaries)
133- prefer native HTML before adding aria
134- quote the exact snippet, state the failure, propose a small fix
135- for complex widgets (menu, dialog, combobox), prefer established accessible primitives over custom behavior
136
137## Limitations
138- Use this skill only when the task clearly matches the scope described above.
139- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
140- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Arjumaan