# Accessibility Checklist (WCAG 2.1 AA)

This checklist ensures all UI components meet WCAG 2.1 AA accessibility standards.

## Keyboard Navigation

### ✅ Focus Management
- [ ] All interactive elements are focusable via Tab key
- [ ] Focus order is logical and follows visual flow
- [ ] Focus is visible with clear outline (2px minimum)
- [ ] Focus is not trapped inappropriately
- [ ] Focus returns to trigger element when modal closes

### ✅ Keyboard Activation
- [ ] Buttons activate with Enter and Space keys
- [ ] Links activate with Enter key
- [ ] Custom controls have proper keyboard support
- [ ] Escape key closes modals and dropdowns
- [ ] Arrow keys navigate within components (menus, lists)

## ARIA Semantics

### ✅ Roles
- [ ] `role="button"` for custom buttons
- [ ] `role="dialog"` for modals
- [ ] `role="alert"` for error messages and urgent notifications
- [ ] `role="status"` for loading states and non-urgent updates
- [ ] `role="tablist"`, `role="tab"`, `role="tabpanel"` for tabs
- [ ] `role="menu"`, `role="menuitem"` for menus

### ✅ States and Properties
- [ ] `aria-expanded` for collapsible content
- [ ] `aria-selected` for selected items
- [ ] `aria-checked` for checkboxes and radio buttons
- [ ] `aria-disabled` for disabled elements
- [ ] `aria-hidden` for decorative elements
- [ ] `aria-live` for dynamic content updates

### ✅ Labels and Descriptions
- [ ] `aria-label` for elements without visible text
- [ ] `aria-labelledby` to reference visible labels
- [ ] `aria-describedby` for additional descriptions
- [ ] `aria-required` for required form fields
- [ ] `aria-invalid` for form validation errors

## Forms

### ✅ Label Association
- [ ] Every form control has an associated label
- [ ] Labels are properly linked using `for` attribute
- [ ] Required fields are clearly marked
- [ ] Error messages are associated with form controls
- [ ] Helper text is properly linked

### ✅ Error Handling
- [ ] Error messages are announced to screen readers
- [ ] Errors are clearly visible and descriptive
- [ ] Error state is programmatically determinable
- [ ] Users can easily identify and correct errors

## Dynamic Content

### ✅ Live Regions
- [ ] `role="alert"` for urgent messages (errors, warnings)
- [ ] `aria-live="polite"` for non-urgent updates
- [ ] `aria-live="assertive"` for important updates
- [ ] Content changes are announced appropriately

### ✅ Modal and Dialog Behavior
- [ ] Focus is trapped within modal when open
- [ ] Focus returns to trigger element when closed
- [ ] Modal is announced when opened
- [ ] Background content is not accessible when modal is open

## Color and Contrast

### ✅ Color Requirements
- [ ] Normal text: 4.5:1 contrast ratio minimum
- [ ] Large text (18pt+): 3:1 contrast ratio minimum
- [ ] UI components: 3:1 contrast ratio minimum
- [ ] Color is not the only means of conveying information
- [ ] Focus indicators meet contrast requirements

### ✅ Visual Indicators
- [ ] Error states use more than just color
- [ ] Success states use more than just color
- [ ] Required fields are marked with text or symbol
- [ ] Status changes are communicated clearly

## Screen Reader Support

### ✅ Content Structure
- [ ] Proper heading hierarchy (h1, h2, h3, etc.)
- [ ] Lists use proper list markup
- [ ] Tables have proper headers and structure
- [ ] Landmarks are used appropriately

### ✅ Text Alternatives
- [ ] Images have meaningful alt text
- [ ] Decorative images have empty alt text
- [ ] Icons have appropriate labels
- [ ] Complex images have detailed descriptions

## Testing Checklist

### ✅ Automated Testing
- [ ] axe-core audit passes with no critical violations
- [ ] Lighthouse accessibility score is 90+
- [ ] No console errors related to accessibility
- [ ] All ARIA attributes are valid

### ✅ Manual Testing
- [ ] Test with keyboard only (no mouse)
- [ ] Test with screen reader (NVDA, JAWS, VoiceOver)
- [ ] Test with high contrast mode
- [ ] Test with zoom up to 200%
- [ ] Test with reduced motion preferences

### ✅ User Testing
- [ ] Test with actual users who rely on assistive technology
- [ ] Verify all functionality is accessible
- [ ] Confirm error messages are helpful
- [ ] Ensure navigation is intuitive

## Implementation Guidelines

### Focus Management
```typescript
// Focus trap for modals
focusTrap: FocusTrap = new FocusTrap();

// Focus management
focusElement(element: HTMLElement) {
  element.focus();
}

// Keyboard event handling
@HostListener('keydown', ['$event'])
onKeydown(event: KeyboardEvent) {
  if (event.key === 'Escape') {
    this.close();
  }
}
```

### ARIA Implementation
```html
<!-- Button with proper ARIA -->
<button 
  [attr.aria-label]="ariaLabel"
  [attr.aria-disabled]="disabled"
  [attr.aria-expanded]="expanded">
  {{ label }}
</button>

<!-- Form field with proper associations -->
<label [for]="inputId">{{ label }}</label>
<input 
  [id]="inputId"
  [attr.aria-describedby]="hintId"
  [attr.aria-invalid]="hasError"
  [attr.aria-required]="required">
<div [id]="hintId">{{ hint }}</div>
```

### Live Regions
```html
<!-- Alert for urgent messages -->
<div role="alert" aria-live="assertive">
  {{ errorMessage }}
</div>

<!-- Status for non-urgent updates -->
<div role="status" aria-live="polite">
  {{ statusMessage }}
</div>
```

## Common Issues and Solutions

### Issue: Missing Focus Outline
**Solution:** Add focus styles using design tokens
```css
.ccl-button:focus-visible {
  outline: 2px solid var(--color-focus-outline);
  outline-offset: 2px;
}
```

### Issue: Poor Color Contrast
**Solution:** Use design tokens with verified contrast ratios
```css
.ccl-error {
  color: var(--color-error-text); /* 4.5:1 contrast */
  background: var(--color-error-bg);
}
```

### Issue: Missing ARIA Labels
**Solution:** Add appropriate ARIA attributes
```html
<button aria-label="Close dialog">×</button>
<input aria-label="Search products" placeholder="Search...">
```

### Issue: Dynamic Content Not Announced
**Solution:** Use appropriate live regions
```html
<div role="alert" aria-live="assertive">
  {{ urgentMessage }}
</div>
```

## Resources

- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
- [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/)
- [axe-core Testing](https://github.com/dequelabs/axe-core)
- [Angular Accessibility Guide](https://angular.io/guide/accessibility)