---
name: accessibility
source: botcore
description: >
  Ensure WCAG 2.1 AA compliance with keyboard navigation, ARIA, and screen reader support.
  Use when building interactive components, auditing UI, or implementing focus management.
version: "2.1.0"
triggers:
  - a11y
  - accessibility
  - ARIA
  - keyboard
  - screen reader
  - WCAG
---

# Accessibility

Best practices for WCAG 2.1 AA compliance.

## When to Use

- Creating interactive components
- Auditing existing UI
- Implementing keyboard navigation
- Adding ARIA attributes and roles

## Workflow

1. **Audit** — Review current accessibility state
2. **Research** — Find accessible patterns
3. **Implement** — Apply WCAG-compliant patterns
4. **Test** — Keyboard + screen reader
5. **Verify** — Automated + manual testing

## WCAG 2.1 AA Quick Reference

### Perceivable
- Text alternatives for images (`alt`)
- Captions for video
- Color contrast 4.5:1 (text), 3:1 (large/UI)

### Operable
- Keyboard accessible
- Focus visible
- Target size 24x24px minimum
- No keyboard traps

### Understandable
- Consistent navigation
- Error identification
- Labels for inputs

### Robust
- Valid HTML
- Name, role, value exposed

## Keyboard Patterns

```typescript
// Handle keyboard activation
element.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' || e.key === ' ') {
    e.preventDefault();
    element.click();
  }
});

// Manage focus on modal open
dialog.showModal();
closeButton.focus();

// Trap focus in modal
dialog.addEventListener('keydown', (e) => {
  if (e.key === 'Tab') {
    // Trap logic
  }
  if (e.key === 'Escape') {
    dialog.close();
  }
});
```

## Common ARIA Patterns

| Component | Role | Key Attributes |
|-----------|------|----------------|
| Button | `button` | `aria-pressed`, `aria-expanded` |
| Modal | `dialog` | `aria-modal`, `aria-labelledby` |
| Tab | `tab` | `aria-selected`, `aria-controls` |
| Menu | `menu` | `aria-activedescendant` |

## Checklist

- [ ] Keyboard accessible (Tab, Enter, Space, Escape)
- [ ] Focus visible and not obscured
- [ ] Target size 24x24px minimum
- [ ] ARIA roles and labels
- [ ] Color contrast 4.5:1+
- [ ] Screen reader tested

## Detailed References

- `{baseDir}/references/wcag-guidelines.md` — WCAG criteria
- `{baseDir}/references/keyboard-nav.md` — Keyboard patterns
- `{baseDir}/references/aria-patterns.md` — ARIA usage
