a2host/.agents/skills/wcag-accessibility-a11y/SKILL.md

3.0 KiB

name description
wcag-accessibility-a11y Applies WCAG 2.1 AA/AAA accessibility guidelines, color contrast verification, screen reader support, keyboard navigation, and reduced motion adaptations to frontend components. Use when reviewing, styling, or creating accessible UI elements.

WCAG Accessibility (A11y) Skill

Core Standards & Implementation Checklist

  1. Semantic HTML First:

    • Use proper Landmark elements: <header>, <nav>, <main>, <aside>, <footer>.
    • Use <button> for clickable actions and <a> strictly for navigation links with valid href.
    • Never attach onClick handlers to generic <div> or <span> without role="button", tabIndex={0}, and onKeyDown handlers for Enter/Space.
  2. Accessible Names & Labels:

    • Every icon-only button must have an explicit aria-label or visually hidden screen reader text:
      <button aria-label={t('nav.openMenu')} className="...">
        <i className="fa-solid fa-bars" aria-hidden="true" />
      </button>
      
    • Form controls must have associated <label> tags with matching htmlFor or explicit aria-label.
    • Interactive dropdowns and accordions must declare state:
      • aria-expanded={isOpen}
      • aria-controls="panel-id"
      • aria-haspopup="true"
  3. Keyboard Navigation & Focus Management:

    • Focus Indicators: Ensure visible, prominent focus rings (focus-visible:ring-2 focus-visible:ring-lime).
    • Tab Order: Logical top-to-bottom and left-to-right order. Do not use positive tabIndex values.
    • Modal Dialogs:
      • Trap focus within the open modal.
      • Automatically return focus to the trigger button when dismissed.
      • Listen for the Escape key to close overlays.
  4. Screen Reader & Live Regions:

    • Use aria-live="polite" for asynchronous status updates, chat incoming responses, and copy-to-clipboard alerts:
      <div aria-live="polite" className="sr-only">
        {isAnalyzing ? t('chat.typingAnalyzing') : ''}
      </div>
      
    • Decorative icons must have aria-hidden="true".
  5. Color Contrast & Readability:

    • Maintain minimum contrast ratio of 4.5:1 for normal text and 3:1 for large text/icons against their background.
    • Never convey critical state using color alone; pair color changes with text, icons, or badges.
    • Respect system and custom accessibility settings:
      • High contrast modes (.a11y-high-contrast / data-theme).
      • Color blindness filters (data-color-blind="protanopia|deuteranopia|tritanopia").
      • Dyslexia-friendly font settings (data-font="dyslexic").
  6. Reduced Motion Adaptation:

    • Wrap transitions and animations with motion-safe: or respect prefers-reduced-motion:
      @media (prefers-reduced-motion: reduce) {
        *, ::before, ::after {
          animation-duration: 0.01ms !important;
          animation-iteration-count: 1 !important;
          transition-duration: 0.01ms !important;
          scroll-behavior: auto !important;
        }
      }