fixing-accessibility
Fix accessibility issues.
how to use
/fixing-accessibility
Apply these constraints to any UI work in this conversation.
/fixing-accessibility
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
common fixes
<
button
<
svg
...
</
svg
</
button
<
button
aria-label
=
"
Close
"
<
svg
aria-hidden
=
"
true
"
...
</
svg
</
button
<
div
onclick
=
"
save
(
)
"
Save
</
div
<
button
onclick
=
"
save
(
)
"
Save
</
button
<
input
id
=
"
email
"
/>
<
span
Invalid email
</
span
<
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