@jmruthers/pace-core 0.6.6 → 0.6.7

package/docs/best-practices/accessibility.md

@@ -1,604 +0,0 @@
----
-lastUpdated: 2025-11-18T17:00:00+11:00
-version: 0.5.181
-reviewedBy: documentation-standards-audit
----
-
-# Best Practices: Accessibility
-
-> **📚 Best Practices**: Accessibility & WCAG Compliance | [← Back](./README.md) | [Implementation Guides](../implementation-guides/README.md)
-
-Accessibility best practices for creating inclusive PACE Core applications that work for all users.
-
----
-
-**Last Updated**: 2025-02-08 | **Version**: v0.5.65+
-
-## Overview
-
-PACE Core components are designed with accessibility in mind, following WCAG 2.1 AA standards. This guide helps you build accessible applications using PACE Core components.
-
-## Core Principles
-
-### Principle 1: Semantic HTML
-
-**Why**: Screen readers rely on semantic HTML to understand page structure and content meaning.
-
-**Implementation**:
-```tsx
-// ✅ Good - Use semantic HTML
-import { Button } from '@jmruthers/pace-core';
-
-function MyComponent() {
-  return (
-    <main>
-      <h1>Page Title</h1>
-      <section>
-        <h2>Section Title</h2>
-        <p>Content here</p>
-      </section>
-      <Button aria-label="Submit form">Submit</Button>
-    </main>
-  );
-}
-```
-
-**Avoid**:
-```tsx
-// ❌ Bad - Overuse of divs
-<div>
-  <div className="title">Page Title</div>
-  <div>
-    <div className="section">Content</div>
-  </div>
-</div>
-```
-
-### Principle 2: Keyboard Navigation
-
-**Why**: Users who cannot use a mouse or prefer keyboard navigation must be able to access all interactive elements.
-
-**Implementation**:
-```tsx
-import { Button, DataTable } from '@jmruthers/pace-core';
-
-// PACE Core components handle keyboard navigation automatically
-function AccessibleTable() {
-  return (
-    <DataTable
-      data={data}
-      columns={columns}
-      features={{
-        // Keyboard navigation enabled by default
-        pagination: true,
-        sorting: true,
-      }}
-    />
-  );
-}
-```
-
-### Principle 3: ARIA Labels and Roles
-
-**Why**: Provide clear context for screen readers when visible text isn't sufficient.
-
-**Implementation**:
-```tsx
-import { Button, Icon } from '@jmruthers/pace-core';
-
-function ActionButton({ onDelete }) {
-  return (
-    <Button
-      onClick={onDelete}
-      aria-label="Delete user"
-      aria-describedby="delete-help-text"
-    >
-      <Icon name="trash" aria-hidden="true" />
-      Delete
-    </Button>
-  );
-}
-```
-
-**Avoid**:
-```tsx
-// ❌ Bad - Icon without label
-<Button onClick={onDelete}>
-  <Icon name="trash" />
-</Button>
-```
-
-## PACE Core Component Accessibility Features
-
-### DataTable Component
-
-**Built-in accessibility**:
-- ✅ Keyboard navigation (Tab, Enter, Arrow keys)
-- ✅ ARIA roles and labels
-- ✅ Screen reader announcements
-- ✅ Focus management
-
-**Example**:
-```tsx
-import { DataTable } from '@jmruthers/pace-core';
-
-function AccessibleDataTable() {
-  return (
-    <DataTable
-      data={data}
-      columns={columns}
-      aria-label="User data table"
-      features={{
-        search: true,
-        pagination: true,
-      }}
-    />
-  );
-}
-```
-
-### Button Component
-
-**Built-in accessibility**:
-- ✅ Keyboard focusable via native HTML `<button>` element
-- ✅ Native keyboard support: `Enter` and `Space` keys automatically activate buttons (standard browser behavior)
-- ✅ Proper focus indicators via `focus-visible` styles
-- ✅ ARIA attributes support via `React.ButtonHTMLAttributes`
-
-**Keyboard Navigation**: The Button component uses native HTML `<button>` elements, which provide automatic keyboard accessibility. When a button is focused, pressing `Enter` or `Space` will trigger the button's `onClick` handler without requiring any custom keyboard event handlers. This is standard browser behavior and works out of the box.
-
-**Example**:
-```tsx
-import { Button } from '@jmruthers/pace-core';
-
-function AccessibleButton() {
-  return (
-    <Button
-      aria-label="Close dialog"
-      aria-describedby="close-help"
-    >
-      Close
-      <span id="close-help" className="sr-only">
-        Closes the current dialog
-      </span>
-    </Button>
-  );
-}
-```
-
-### Form Components
-
-**Built-in accessibility**:
-- ✅ Label associations
-- ✅ Error announcements
-- ✅ Required field indicators
-- ✅ Validation feedback
-
-**Example**:
-```tsx
-import { Input, Label, FormError } from '@jmruthers/pace-core';
-
-function AccessibleForm() {
-  return (
-    <form aria-labelledby="form-title">
-      <h2 id="form-title">User Information</h2>
-      
-      <div>
-        <Label htmlFor="email">Email Address</Label>
-        <Input
-          id="email"
-          type="email"
-          required
-          aria-required="true"
-          aria-describedby="email-error"
-        />
-        <FormError id="email-error" role="alert">
-          Please enter a valid email
-        </FormError>
-      </div>
-    </form>
-  );
-}
-```
-
-### Dialog/Modal Components
-
-**Built-in accessibility**:
-- ✅ Focus trap management
-- ✅ ESC key support
-- ✅ ARIA roles and properties
-- ✅ Screen reader announcements
-
-**Example**:
-```tsx
-import { Dialog, DialogTrigger, DialogContent } from '@jmruthers/pace-core';
-
-function AccessibleDialog() {
-  return (
-    <Dialog>
-      <DialogTrigger aria-label="Open user settings">
-        Settings
-      </DialogTrigger>
-      <DialogContent
-        aria-labelledby="dialog-title"
-        aria-describedby="dialog-description"
-      >
-        <h2 id="dialog-title">User Settings</h2>
-        <p id="dialog-description">
-          Configure your account preferences
-        </p>
-        {/* Dialog content */}
-      </DialogContent>
-    </Dialog>
-  );
-}
-```
-
-## Common Patterns
-
-### Pattern 1: Loading States with Announcements
-
-**Use when**: Data is loading asynchronously
-
-**Example**:
-```tsx
-import { useUnifiedAuth } from '@jmruthers/pace-core';
-
-function AccessibleUserProfile() {
-  const { user, loading, error } = useUnifiedAuth();
-
-  return (
-    <div role="status" aria-live="polite">
-      {loading && (
-        <div aria-busy="true">
-          <span className="sr-only">Loading user data</span>
-          Loading...
-        </div>
-      )}
-      {error && (
-        <div role="alert">
-          <span className="sr-only">Error loading user data</span>
-          Error: {error.message}
-        </div>
-      )}
-      {user && (
-        <div>
-          <h1>Welcome, {user.email}</h1>
-        </div>
-      )}
-    </div>
-  );
-}
-```
-
-### Pattern 2: Skip Links
-
-**Use when**: Creating long pages with repetitive navigation
-
-**Example**:
-```tsx
-function AccessibleLayout() {
-  return (
-    <div>
-      {/* Skip link */}
-      <a href="#main-content" className="skip-link">
-        Skip to main content
-      </a>
-      
-      <Navigation />
-      
-      <main id="main-content" tabIndex="-1">
-        <h1>Main Content</h1>
-      </main>
-      
-      <Footer />
-    </div>
-  );
-}
-```
-
-### Pattern 3: Focus Management
-
-**Use when**: Opening modals or changing page context
-
-**Example**:
-```tsx
-import { useEffect, useRef } from 'react';
-import { Dialog, DialogContent } from '@jmruthers/pace-core';
-
-function AccessibleDialog({ isOpen, onClose }) {
-  const titleRef = useRef<HTMLHeadingElement>(null);
-
-  useEffect(() => {
-    if (isOpen && titleRef.current) {
-      // Focus the dialog title when it opens
-      titleRef.current.focus();
-    }
-  }, [isOpen]);
-
-  return (
-    <Dialog isOpen={isOpen} onClose={onClose}>
-      <DialogContent
-        aria-labelledby="dialog-title"
-        role="dialog"
-        aria-modal="true"
-      >
-        <h2 id="dialog-title" ref={titleRef} tabIndex={-1}>
-          Important Information
-        </h2>
-        {/* Dialog content */}
-      </DialogContent>
-    </Dialog>
-  );
-}
-```
-
-### Pattern 4: Error Messages
-
-**Use when**: Form validation errors or error states
-
-**Example**:
-```tsx
-import { Input, FormError } from '@jmruthers/pace-core';
-
-function AccessibleForm() {
-  const [email, setEmail] = useState('');
-  const [error, setError] = useState('');
-
-  return (
-    <div>
-      <Label htmlFor="email">Email</Label>
-      <Input
-        id="email"
-        type="email"
-        value={email}
-        onChange={(e) => setEmail(e.target.value)}
-        aria-invalid={!!error}
-        aria-describedby={error ? "email-error" : undefined}
-      />
-      {error && (
-        <FormError id="email-error" role="alert">
-          {error}
-        </FormError>
-      )}
-    </div>
-  );
-}
-```
-
-## Advanced Usage
-
-### Custom Accessibility Attributes
-
-When PACE Core components need additional accessibility attributes:
-
-```tsx
-import { Button, DataTable } from '@jmruthers/pace-core';
-
-function AdvancedAccessibility() {
-  return (
-    <>
-      {/* Custom ARIA attributes */}
-      <Button
-        aria-label="Save changes"
-        aria-describedby="save-status"
-        aria-busy={isSaving}
-      >
-        Save
-      </Button>
-      <span id="save-status" className="sr-only">
-        {isSaving ? 'Saving' : 'Save'}
-      </span>
-
-      {/* DataTable with custom accessibility */}
-      <DataTable
-        data={data}
-        columns={columns}
-        aria-label="User management table"
-        aria-describedby="table-description"
-      />
-      <p id="table-description" className="sr-only">
-        Interactive table for managing users with sorting and filtering
-      </p>
-    </>
-  );
-}
-```
-
-### Screen Reader Only Content
-
-Use the `.sr-only` class for content that should only be visible to screen readers:
-
-```tsx
-function ScreenReaderExample() {
-  return (
-    <Button aria-label="Download file">
-      <Icon name="download" aria-hidden="true" />
-      Download
-      <span className="sr-only">PDF document</span>
-    </Button>
-  );
-}
-```
-
-### Live Regions for Dynamic Content
-
-Use live regions for dynamic content updates:
-
-```tsx
-import { useUnifiedAuth } from '@jmruthers/pace-core';
-
-function LiveRegionExample() {
-  const { user } = useUnifiedAuth();
-
-  return (
-    <div role="region" aria-live="polite" aria-label="User status">
-      {user && (
-        <p>
-          Logged in as {user.email}
-        </p>
-      )}
-    </div>
-  );
-}
-```
-
-## Testing Accessibility
-
-### Manual Testing Checklist
-
-- [ ] **Keyboard Navigation**: All interactive elements accessible via keyboard
-- [ ] **Focus Indicators**: Visible focus indicators on all interactive elements
-- [ ] **Screen Reader**: Test with screen reader (NVDA, JAWS, VoiceOver)
-- [ ] **Color Contrast**: Meet WCAG AA contrast ratios (4.5:1 for text, 3:1 for UI)
-- [ ] **ARIA Labels**: All icons and images have appropriate labels
-- [ ] **Semantic HTML**: Using proper HTML elements
-- [ ] **Error Messages**: Properly associated with form fields
-
-### Automated Testing Tools
-
-**Recommended tools**:
-- **axe DevTools**: Browser extension for accessibility testing
-- **WAVE**: Web accessibility evaluation tool
-- **Lighthouse**: Accessibility auditing
-- **Pa11y**: Command-line accessibility testing
-
-**Example setup**:
-```bash
-# Install Pa11y
-npm install -g pa11y
-
-# Run accessibility tests
-pa11y http://localhost:3000
-```
-
-### Color Contrast
-
-Ensure text meets contrast requirements:
-
-```tsx
-// ✅ Good contrast
-<p className="text-sec-800 bg-sec-50">
-  High contrast text
-</p>
-
-// ❌ Poor contrast
-<p className="text-sec-300 bg-sec-400">
-  Low contrast text (hard to read)
-</p>
-```
-
-## Common Issues and Solutions
-
-### Issue 1: Missing Focus Indicators
-
-**Problem**: Interactive elements don't show visible focus state
-
-**Solution**: Use PACE Core components which include focus styles, or add custom focus styles
-
-```css
-/* Custom focus styles */
-button:focus-visible {
-  outline: 2px solid var(--color-main-600);
-  outline-offset: 2px;
-}
-```
-
-### Issue 2: Missing Alt Text
-
-**Problem**: Images without alt text
-
-**Solution**: Always provide meaningful alt text
-
-```tsx
-// ✅ Good
-<img src="user-avatar.jpg" alt="User profile picture" />
-
-// ❌ Bad
-<img src="user-avatar.jpg" />
-```
-
-### Issue 3: Form Labels Not Associated
-
-**Problem**: Input fields without associated labels
-
-**Solution**: Use proper label associations
-
-```tsx
-// ✅ Good
-<Label htmlFor="email">Email</Label>
-<Input id="email" type="email" />
-
-// ❌ Bad
-<div>Email</div>
-<Input type="email" />
-```
-
-## WCAG Compliance
-
-### Level AA Compliance
-
-PACE Core components are designed to meet WCAG 2.1 Level AA standards:
-
-- ✅ **Perceivable**: All information must be perceivable to users
-- ✅ **Operable**: Interface components must be operable
-- ✅ **Understandable**: Information and UI operation must be understandable
-- ✅ **Robust**: Content must be robust enough to work with assistive technologies
-
-### Compliance Checklist
-
-- [ ] **Color Contrast**: All text meets 4.5:1 contrast ratio
-- [ ] **Keyboard Access**: All functionality available via keyboard
-- [ ] **Focus Indicators**: Visible focus on all interactive elements
-- [ ] **ARIA Labels**: Proper labels for all icons and images
-- [ ] **Semantic HTML**: Using appropriate HTML elements
-- [ ] **Error Messages**: Properly announced to screen readers
-- [ ] **Live Regions**: Dynamic content properly announced
-
-## Related Documentation
-
-- [Component API Reference](../api-reference/components.md)
-- [Form Implementation Guide](../implementation-guides/forms.md)
-- [DataTable Guide](../implementation-guides/data-tables.md)
-- [Security Best Practices](./security.md)
-- [Testing Best Practices](./testing.md)
-
-## Additional Resources
-
-- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
-- [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
-- [WebAIM Resources](https://webaim.org/)
-- [MDN Accessibility Guide](https://developer.mozilla.org/en-US/docs/Web/Accessibility)
-
----
-
-**Next Steps**: Review your application's accessibility, implement missing ARIA attributes, and test with screen readers.
-
-## ⚠️ Edge Cases
-
-### Accessibility vs Performance
-
-When accessibility features impact performance:
-- Optimize ARIA live regions to reduce re-renders
-- Use efficient focus management techniques
-- Balance screen reader announcements with performance
-- Test performance with assistive technologies enabled
-- Profile accessibility features for bottlenecks
-
-### Complex Accessibility Scenarios
-
-When dealing with complex accessibility requirements:
-- Test with multiple screen reader combinations
-- Verify keyboard navigation in complex UIs
-- Ensure focus management in dynamic content
-- Test with different assistive technology configurations
-- Document accessibility patterns for complex components
-
-### Third-Party Component Accessibility
-
-When using third-party components:
-- Verify third-party components meet accessibility standards
-- Add wrapper components for accessibility improvements
-- Test third-party integrations with assistive technologies
-- Document accessibility limitations
-- Provide alternatives when components aren't accessible