@jmruthers/pace-core 0.5.75 → 0.5.76

package/docs/best-practices/accessibility.md

@@ -0,0 +1,566 @@
+# 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
+- ✅ Proper focus indicators
+- ✅ ARIA attributes support
+
+**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.