# Accessibility Guide (WCAG 2.1 AA)

This guide ensures all UI components meet WCAG 2.1 AA accessibility standards and provides implementation guidelines for developers.

## Overview

Our design system is built with accessibility as a core principle, ensuring that all users, including those using assistive technologies, can effectively interact with our components.

## Key Principles

### 1. Perceivable
- Information and UI components must be presentable in ways users can perceive
- Color is not the only means of conveying information
- Text alternatives are provided for non-text content
- Content can be presented in different ways without losing information

### 2. Operable
- UI components and navigation must be operable
- All functionality is available from a keyboard
- Users have enough time to read and use content
- Content does not cause seizures or physical reactions

### 3. Understandable
- Information and UI operation must be understandable
- Text content is readable and understandable
- Content appears and operates in predictable ways
- Users are helped to avoid and correct mistakes

### 4. Robust
- Content must be robust enough for interpretation by assistive technologies
- Components work with current and future assistive technologies

## Component Accessibility Features

### Button Component (`ccl-button`)

**Keyboard Navigation:**
- Activates with Enter and Space keys
- Proper focus management with visible focus indicators
- Disabled state prevents interaction

**ARIA Support:**
- `aria-label` for custom labels
- `aria-describedby` for additional descriptions
- `aria-expanded` for toggle buttons
- `aria-pressed` for toggle states
- `aria-disabled` for disabled state

**Usage Examples:**
```html
<!-- Basic button -->
<ccl-button>Save Changes</ccl-button>

<!-- Button with custom label -->
<ccl-button ariaLabel="Submit form">Submit</ccl-button>

<!-- Toggle button -->
<ccl-button 
  ariaExpanded="false" 
  ariaLabel="Toggle menu">
  Menu
</ccl-button>

<!-- Button with description -->
<ccl-button 
  ariaDescribedBy="save-hint">
  Save
</ccl-button>
<div id="save-hint">Saves your changes to the server</div>
```

### Input Component (`ccl-input`)

**Form Accessibility:**
- Proper label association with `for` attribute
- Required field indicators with visual and programmatic marking
- Error messages with `role="alert"` for immediate announcement
- Helper text properly linked with `aria-describedby`

**ARIA Support:**
- `aria-label` for custom labels
- `aria-describedby` for hints and error messages
- `aria-invalid` for validation state
- `aria-required` for required fields

**Usage Examples:**
```html
<!-- Basic input with label -->
<ccl-input 
  label="Email Address" 
  type="email" 
  required="true">
</ccl-input>

<!-- Input with error state -->
<ccl-input 
  label="Password" 
  type="password"
  [error]="true"
  errorMessage="Password must be at least 8 characters">
</ccl-input>

<!-- Input with helper text -->
<ccl-input 
  label="Username" 
  helperText="Choose a unique username">
</ccl-input>
```

### Modal Component (`ccl-modal`)

**Focus Management:**
- Focus is trapped within modal when open
- Focus returns to trigger element when closed
- Escape key closes modal
- Proper tab order within modal

**ARIA Support:**
- `role="dialog"` for modal container
- `aria-modal="true"` to indicate modal state
- `aria-labelledby` for modal title
- `aria-label` for custom labels

**Usage Examples:**
```html
<!-- Basic modal -->
<ccl-modal 
  [isOpen]="showModal" 
  title="Confirm Action"
  (closed)="closeModal()">
  <p>Are you sure you want to continue?</p>
</ccl-modal>

<!-- Modal with custom label -->
<ccl-modal 
  [isOpen]="showModal" 
  ariaLabel="Settings panel"
  (closed)="closeModal()">
  <!-- Modal content -->
</ccl-modal>
```

### Toast Component (`ccl-toast`)

**Live Regions:**
- `role="alert"` for urgent messages (errors, warnings)
- `role="status"` for non-urgent updates (success, info)
- `aria-live` for screen reader announcements
- Proper timing for announcements

**ARIA Support:**
- `role` attribute for message type
- `aria-live` for announcement priority
- `aria-labelledby` for titled toasts
- `aria-label` for close button

**Usage Examples:**
```html
<!-- Success toast -->
<ccl-toast 
  variant="success" 
  message="Changes saved successfully"
  role="status"
  ariaLive="polite">
</ccl-toast>

<!-- Error toast -->
<ccl-toast 
  variant="error" 
  message="Failed to save changes"
  role="alert"
  ariaLive="assertive">
</ccl-toast>

<!-- Toast with title -->
<ccl-toast 
  variant="info" 
  title="New Message"
  message="You have 3 unread messages"
  role="status">
</ccl-toast>
```

### Loading Component (`ccl-loading`)

**Status Announcements:**
- `role="status"` for loading indicators
- Customizable `aria-label` for context
- Proper announcement timing

**Usage Examples:**
```html
<!-- Basic loading -->
<ccl-loading 
  variant="spinner" 
  label="Loading data">
</ccl-loading>

<!-- Loading with context -->
<ccl-loading 
  variant="bar" 
  label="Uploading file... 45% complete">
</ccl-loading>
```

## Focus Management

### Focus Indicators
All interactive elements have visible focus indicators that meet WCAG contrast requirements:

```css
.ccl-button:focus-visible,
.ccl-input:focus-visible {
  outline: 2px solid var(--color-focus-outline);
  outline-offset: 2px;
}
```

### Focus Order
- Focus follows logical reading order
- Modal focus is trapped appropriately
- Focus returns to trigger element when modal closes

### Keyboard Navigation
- Tab key moves focus forward
- Shift+Tab moves focus backward
- Enter and Space activate buttons
- Escape closes modals and dropdowns
- Arrow keys navigate within components

## Color and Contrast

### Contrast Requirements
- Normal text: 4.5:1 contrast ratio minimum
- Large text (18pt+): 3:1 contrast ratio minimum
- UI components: 3:1 contrast ratio minimum
- Focus indicators: 3:1 contrast ratio minimum

### Color Usage
- Color is never the only means of conveying information
- Error states use icons and text in addition to color
- Success states use icons and text in addition to color
- Required fields are marked with asterisk and text

## Screen Reader Support

### Semantic HTML
- Proper heading hierarchy (h1, h2, h3, etc.)
- Lists use proper list markup
- Tables have proper headers and structure
- Form controls have associated labels

### ARIA Landmarks
- `role="main"` for main content
- `role="navigation"` for navigation areas
- `role="banner"` for page headers
- `role="contentinfo"` for page footers

### Live Regions
- `role="alert"` for urgent messages
- `aria-live="polite"` for non-urgent updates
- `aria-live="assertive"` for important updates
- Content changes are announced appropriately

## Testing Guidelines

### Automated Testing
Use these tools to test accessibility:

```bash
# Install axe-core for automated testing
npm install --save-dev @axe-core/playwright

# Run accessibility tests
npx playwright test --grep="accessibility"
```

### Manual Testing
1. **Keyboard Only Testing:**
   - Navigate through the interface using only the keyboard
   - Verify all interactive elements are reachable
   - Check that focus order is logical

2. **Screen Reader Testing:**
   - Test with NVDA (Windows), JAWS (Windows), or VoiceOver (Mac)
   - Verify that content is announced correctly
   - Check that form labels are properly associated

3. **Visual Testing:**
   - Test with high contrast mode enabled
   - Test with browser zoom up to 200%
   - Test with reduced motion preferences

### Testing Checklist
- [ ] All interactive elements are keyboard accessible
- [ ] Focus indicators are visible and meet contrast requirements
- [ ] Form labels are properly associated
- [ ] Error messages are announced to screen readers
- [ ] Modal focus is trapped appropriately
- [ ] Dynamic content is announced correctly
- [ ] Color is not the only means of conveying information
- [ ] Text alternatives are provided for images and icons

## Implementation Best Practices

### 1. Always Provide Labels
```html
<!-- Good -->
<ccl-input label="Email Address"></ccl-input>

<!-- Better -->
<ccl-input 
  label="Email Address" 
  ariaLabel="Enter your email address">
</ccl-input>
```

### 2. Use Semantic HTML
```html
<!-- Good -->
<button>Submit</button>

<!-- Better -->
<ccl-button ariaLabel="Submit form">Submit</ccl-button>
```

### 3. Provide Context for Dynamic Content
```html
<!-- Good -->
<ccl-toast message="Saved"></ccl-toast>

<!-- Better -->
<ccl-toast 
  message="Document saved successfully" 
  role="status"
  ariaLive="polite">
</ccl-toast>
```

### 4. Handle Loading States
```html
<!-- Good -->
<div *ngIf="loading">Loading...</div>

<!-- Better -->
<ccl-loading 
  *ngIf="loading" 
  variant="spinner" 
  label="Loading user data">
</ccl-loading>
```

## Common Issues and Solutions

### Issue: Missing Focus Indicators
**Problem:** Interactive elements don't have visible focus indicators.
**Solution:** Add focus-visible styles using design tokens.

```css
.component:focus-visible {
  outline: 2px solid var(--color-focus-outline);
  outline-offset: 2px;
}
```

### Issue: Poor Color Contrast
**Problem:** Text doesn't meet contrast requirements.
**Solution:** Use design tokens with verified contrast ratios.

```css
.error-text {
  color: var(--color-error-text); /* 4.5:1 contrast verified */
}
```

### Issue: Missing ARIA Labels
**Problem:** Screen readers can't identify elements.
**Solution:** Add appropriate ARIA attributes.

```html
<button aria-label="Close dialog">×</button>
<input aria-label="Search products" placeholder="Search...">
```

### Issue: Dynamic Content Not Announced
**Problem:** Screen readers don't announce content changes.
**Solution:** Use appropriate live regions.

```html
<div role="alert" aria-live="assertive">
  {{ errorMessage }}
</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)
- [WebAIM Screen Reader Testing](https://webaim.org/articles/screenreader_testing/)

## Support

For accessibility questions or issues:
1. Check the [Accessibility Checklist](./accessibility-checklist.md)
2. Review component documentation
3. Test with assistive technologies
4. Consult the WCAG 2.1 guidelines

Remember: Accessibility is not optional—it's a fundamental requirement for inclusive design.