git:20260121.6ccb8ef to git:20260121.fa3901e

+ # 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