All skills
Skillintermediate

aria fix

Fix ARIA attributes and accessibility issues in web components.

Claude Code Knowledge Pack7/10/2026

Overview

Fix ARIA attributes and accessibility issues in web components.

Steps

  1. Read the target component and identify accessibility issues.
  2. Apply ARIA fixes by category:
    • Roles: Add role attributes to custom interactive elements.
    • States: Add aria-expanded, aria-selected, aria-checked for stateful components.
    • Properties: Add aria-label, aria-describedby, aria-labelledby.
    • Live regions: Add aria-live for dynamic content updates.
  3. Fix interactive element accessibility:
    • Add tabIndex={0} to custom interactive elements.
    • Add keyboard event handlers (onKeyDown for Enter/Space).
    • Ensure focus is visible with proper styling.
    • Trap focus in modal dialogs.
  4. Fix form accessibility:
    • Associate labels with inputs.
    • Add aria-invalid and aria-describedby for validation errors.
    • Group related fields with fieldset and legend.
  5. Fix semantic HTML:
    • Replace div click handlers with button elements.
    • Use proper heading hierarchy (h1 > h2 > h3).
    • Use landmark elements (nav, main, aside, footer).
  6. Verify fixes do not break existing functionality.

Format

ARIA Fixes Applied: <file>

Changes:
  - L: Added role="button" and keyboard handler to clickable div
  - L: Added aria-label="Close dialog" to icon button
  - L: Added aria-live="polite" to status message container
  - L: Replaced div with semantic <nav> element

Tests: verify with keyboard navigation and screen reader

Rules

  • Prefer semantic HTML over ARIA attributes (a button over div with role=button).
  • Never use aria-hidden="true" on focusable elements.
  • Ensure every ARIA role has the required states and properties.
  • Test keyboard navigation order matches visual order.
  • Do not add ARIA attributes that duplicate native HTML semantics.