--- name: fixing-accessibility description: 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. risk: unknown source: community --- # 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 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 ```html

Save

Invalid email Invalid email ``` ## 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.

fixing-accessibility

Install this skill

Comments