accessibility.yaml

# Accessibility Code Review Guidelines
# Comprehensive rules for web accessibility (WCAG) compliance

description: Web accessibility best practices covering semantic HTML, ARIA, keyboard navigation, screen readers, and accessibility testing
globs:
  - "**/*.html"
  - "**/*.jsx"
  - "**/*.tsx"
  - "**/*.vue"
  - "**/*.svelte"
  - "**/components/**"
  - "**/*.css"
  - "**/*.scss"

rules:
  # Semantic HTML Rules
  - name: use-semantic-elements
    description: >
      Use semantic HTML elements (nav, main, article, section, aside, header, footer) instead
      of generic divs. Semantic elements provide meaning to assistive technologies and improve
      document structure. Use headings (h1-h6) for document outline. Buttons for actions, links for navigation.
    severity: high

  - name: use-landmark-regions
    description: >
      Use ARIA landmark roles or semantic elements to define page regions: banner, navigation,
      main, contentinfo, complementary, search. Landmarks help screen reader users navigate.
      Each page should have one main landmark. Don't overuse - landmarks should be meaningful.
    severity: medium

  - name: maintain-heading-hierarchy
    description: >
      Maintain proper heading hierarchy without skipping levels (h1 -> h2 -> h3). One h1 per
      page. Headings provide document outline for screen readers. Don't use headings for
      styling - use CSS. Visual hierarchy should match semantic hierarchy.
    severity: high

  - name: use-lists-for-related-items
    description: >
      Use ul, ol, or dl for lists of related items. Screen readers announce list length
      helping users understand content structure. Navigation menus should be lists. Don't
      use lists solely for indentation. Nested lists should maintain proper structure.
    severity: medium

  - name: provide-text-alternatives
    description: >
      All non-text content must have text alternatives. Use alt for images, captions/transcripts
      for video, text descriptions for charts. Decorative images use empty alt="". Complex
      images need long descriptions. SVGs need title or aria-label.
    severity: critical

  # ARIA Rules
  - name: use-aria-correctly
    description: >
      First rule of ARIA: don't use ARIA if native HTML works. Use proper semantic HTML first.
      ARIA adds meaning to custom widgets. Don't change native semantics unless necessary.
      ARIA doesn't add behavior - only announces to assistive technologies.
    severity: high

  - name: use-aria-labels-appropriately
    description: >
      Use aria-label for elements without visible labels, aria-labelledby to reference visible
      labels. Icons buttons need aria-label. Don't duplicate visible text. aria-labelledby can
      combine multiple labels. Test with screen readers to verify announcements.
    severity: high

  - name: implement-live-regions
    description: >
      Use aria-live for dynamic content updates that should be announced. aria-live="polite"
      announces when user is idle, "assertive" interrupts. Use aria-atomic, aria-relevant
      to control what's announced. Don't overuse - too many announcements overwhelm users.
    severity: medium

  - name: use-roles-correctly
    description: >
      Use ARIA roles to define widget types for custom elements. Roles must include required
      states and properties. button role needs keyboard activation, tabindex. Don't change
      native element roles unless creating custom widgets. Follow ARIA authoring practices.
    severity: high

  # Keyboard Navigation Rules
  - name: ensure-keyboard-accessibility
    description: >
      All interactive elements must be keyboard accessible. Users must be able to navigate,
      activate, and interact using only keyboard. Test Tab, Enter, Space, Escape, Arrow keys.
      Custom widgets need keyboard handlers. Don't rely on mouse-only events.
    severity: critical

  - name: manage-focus-properly
    description: >
      Manage focus for dynamic content: move focus to dialogs when opened, return focus
      when closed. Focus first interactive element or dialog title. Use tabindex="-1" for
      programmatic focus on non-interactive elements. Don't remove focus outlines without replacement.
    severity: high

  - name: maintain-logical-tab-order
    description: >
      Tab order should follow visual/logical order. Don't use positive tabindex values.
      Use tabindex="0" for custom interactive elements, "-1" for programmatic focus only.
      Test keyboard navigation flow. Reordering DOM via CSS doesn't change tab order.
    severity: high

  - name: avoid-keyboard-traps
    description: >
      Ensure users can always escape any component using keyboard. Modal dialogs should
      trap focus but allow Escape to close. Avoid custom widgets that trap Tab without
      escape mechanism. Test that Tab eventually leaves the component.
    severity: critical

  - name: implement-skip-links
    description: >
      Provide skip links to bypass repetitive content (navigation). "Skip to main content"
      link should be first focusable element. Make visible on focus. Multiple skip links
      for complex pages. Essential for keyboard users navigating pages with heavy navigation.
    severity: medium

  # Screen Reader Rules
  - name: write-descriptive-alt-text
    description: >
      Write alt text that conveys image meaning, not just description. Consider image context
      and purpose. Decorative images use empty alt="". Functional images (buttons) describe
      action. Complex images need longer descriptions. Don't start with "Image of".
    severity: high

  - name: use-announcements-for-updates
    description: >
      Announce important updates to screen readers using aria-live or role="alert".
      Form validation errors, loading states, successful actions. Don't announce too frequently.
      Use appropriate politeness level. Test with actual screen readers.
    severity: medium

  - name: hide-content-appropriately
    description: >
      Hide decorative content from screen readers with aria-hidden="true" or role="presentation".
      Visually hidden but screen reader accessible content uses sr-only/visually-hidden CSS.
      display:none and visibility:hidden hide from both. Choose based on intended audience.
    severity: medium

  # Visual Accessibility Rules
  - name: ensure-color-contrast
    description: >
      Maintain WCAG color contrast ratios: 4.5:1 for normal text, 3:1 for large text and
      UI components. Use contrast checking tools. Don't rely on color alone to convey
      information. Test with color blindness simulators. Consider dark mode contrast.
    severity: high

  - name: provide-visible-focus-indicators
    description: >
      Focus indicators must be visible with minimum 3:1 contrast. Don't remove outline
      without providing alternative. Custom focus styles should be clearly visible.
      Test in different themes. Focus indicators are essential for keyboard navigation.
    severity: high

  - name: respect-motion-preferences
    description: >
      Honor prefers-reduced-motion media query for users with vestibular disorders. Reduce
      or eliminate animations, auto-playing videos, parallax effects. Provide controls for
      moving content. Never auto-play audio. Essential motion can be retained.
    severity: medium

  - name: support-text-scaling
    description: >
      Content must remain usable at 200% text zoom. Use relative units (rem, em) not fixed
      pixels. Test with browser zoom. Avoid fixed height containers that clip text. Responsive
      design helps but test specifically. Don't disable pinch-zoom on mobile.
    severity: high

  # Testing Rules
  - name: use-automated-accessibility-testing
    description: >
      Use automated tools (axe, WAVE, Lighthouse) in development and CI. Automated testing
      catches ~30% of issues. Run on all components and pages. Fix violations before merge.
      Automated testing is necessary but not sufficient for accessibility.
    severity: high

  - name: perform-manual-accessibility-testing
    description: >
      Manual testing catches issues automation misses: reading order, context, usability.
      Test with keyboard only. Navigate with screen reader (NVDA, VoiceOver). Verify focus
      management, announcements, and logical flow. Include users with disabilities in testing.
    severity: high

  - name: test-with-screen-readers
    description: >
      Test with actual screen readers, not just automated tools. Use NVDA (Windows), VoiceOver
      (Mac/iOS), TalkBack (Android). Test common flows and interactions. Listen to how content
      is announced. Screen reader behavior varies - test multiple. Document known issues.
    severity: high