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

68 lines
3.0 KiB
Markdown

---
name: wcag-accessibility-a11y
description: >-
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:
```jsx
<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:
```jsx
<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`:
```css
@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;
}
}
```