ai-qakit 1.0.0

package/templates/.claude/skills/frontend-development/references/accessibility.md

@@ -0,0 +1,720 @@
+# Accessibility (a11y)
+
+Web accessibility best practices for inclusive React applications.
+
+---
+
+## Core Principles (WCAG 2.1)
+
+1. **Perceivable** - Content must be presentable in ways users can perceive
+2. **Operable** - UI components must be operable by all users
+3. **Understandable** - Information and UI operation must be understandable
+4. **Robust** - Content must be interpreted reliably by assistive technologies
+
+---
+
+## Semantic HTML
+
+### Use Correct Elements
+
+```tsx
+// ❌ Bad - div with click handler
+<div onClick={handleClick} className="button-style">
+  Submit
+</div>
+
+// ✅ Good - button element
+<button onClick={handleClick} className="button-style">
+  Submit
+</button>
+
+// ❌ Bad - div for navigation
+<div className="nav">
+  <div onClick={() => navigate('/')}>Home</div>
+</div>
+
+// ✅ Good - nav with links
+<nav aria-label="Main navigation">
+  <a href="/">Home</a>
+</nav>
+
+// ❌ Bad - span for heading
+<span className="text-2xl font-bold">Page Title</span>
+
+// ✅ Good - heading element
+<h1 className="text-2xl font-bold">Page Title</h1>
+```
+
+### Landmark Regions
+
+```tsx
+export const PageLayout: React.FC<{ children: React.ReactNode }> = ({
+  children,
+}) => (
+  <>
+    <header role="banner">
+      <nav aria-label="Main">
+        {/* Primary navigation */}
+      </nav>
+    </header>
+
+    <main role="main" id="main-content">
+      {children}
+    </main>
+
+    <aside role="complementary" aria-label="Related content">
+      {/* Sidebar */}
+    </aside>
+
+    <footer role="contentinfo">
+      {/* Footer content */}
+    </footer>
+  </>
+);
+```
+
+---
+
+## ARIA Attributes
+
+### Labels and Descriptions
+
+```tsx
+// Label for icons-only buttons
+<button aria-label="Close dialog">
+  <X className="h-4 w-4" />
+</button>
+
+// Description for additional context
+<button aria-describedby="delete-description">
+  Delete Account
+</button>
+<p id="delete-description" className="sr-only">
+  This action cannot be undone. All your data will be permanently removed.
+</p>
+
+// Labelled by another element
+<div role="region" aria-labelledby="section-heading">
+  <h2 id="section-heading">User Settings</h2>
+  {/* Section content */}
+</div>
+```
+
+### Live Regions
+
+```tsx
+// Announce dynamic content changes
+<div role="status" aria-live="polite" aria-atomic="true">
+  {message}
+</div>
+
+// Announce urgent updates
+<div role="alert" aria-live="assertive">
+  {errorMessage}
+</div>
+
+// Toast notifications
+export const Toast: React.FC<{ message: string }> = ({ message }) => (
+  <div
+    role="status"
+    aria-live="polite"
+    className="fixed bottom-4 right-4 p-4 bg-card rounded-lg shadow-lg"
+  >
+    {message}
+  </div>
+);
+```
+
+### State Indicators
+
+```tsx
+// Expanded/collapsed
+<button
+  aria-expanded={isOpen}
+  aria-controls="menu-content"
+  onClick={() => setIsOpen(!isOpen)}
+>
+  Menu
+</button>
+<div id="menu-content" hidden={!isOpen}>
+  {/* Menu items */}
+</div>
+
+// Selected state
+<li role="option" aria-selected={isSelected}>
+  {option.label}
+</li>
+
+// Loading state
+<button aria-busy={isLoading} disabled={isLoading}>
+  {isLoading ? 'Loading...' : 'Submit'}
+</button>
+
+// Current page in navigation
+<nav aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Home</a></li>
+    <li><a href="/products">Products</a></li>
+    <li aria-current="page">Product Details</li>
+  </ol>
+</nav>
+```
+
+---
+
+## Keyboard Navigation
+
+### Focus Management
+
+```tsx
+import { useRef, useEffect } from 'react';
+
+export const Dialog: React.FC<DialogProps> = ({ isOpen, onClose, children }) => {
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const previousFocusRef = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    if (isOpen) {
+      // Store previously focused element
+      previousFocusRef.current = document.activeElement as HTMLElement;
+      // Focus the dialog
+      dialogRef.current?.focus();
+    } else {
+      // Return focus when closing
+      previousFocusRef.current?.focus();
+    }
+  }, [isOpen]);
+
+  // Trap focus within dialog
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === 'Escape') {
+      onClose();
+      return;
+    }
+
+    if (e.key === 'Tab') {
+      const focusable = dialogRef.current?.querySelectorAll<HTMLElement>(
+        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+      );
+      
+      if (!focusable?.length) return;
+
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    }
+  };
+
+  if (!isOpen) return null;
+
+  return (
+    <div
+      ref={dialogRef}
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="dialog-title"
+      tabIndex={-1}
+      onKeyDown={handleKeyDown}
+      className="fixed inset-0 z-50 flex items-center justify-center"
+    >
+      <div className="bg-background p-6 rounded-lg shadow-lg">
+        {children}
+      </div>
+    </div>
+  );
+};
+```
+
+### Skip Links
+
+```tsx
+export const SkipLink: React.FC = () => (
+  <a
+    href="#main-content"
+    className="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:px-4 focus:py-2 focus:bg-background focus:border focus:rounded"
+  >
+    Skip to main content
+  </a>
+);
+
+// Usage at top of layout
+export const Layout: React.FC = ({ children }) => (
+  <>
+    <SkipLink />
+    <Header />
+    <main id="main-content" tabIndex={-1}>
+      {children}
+    </main>
+  </>
+);
+```
+
+### Keyboard Patterns
+
+```tsx
+// Dropdown menu with arrow key navigation
+export const DropdownMenu: React.FC<DropdownMenuProps> = ({
+  items,
+  onSelect,
+}) => {
+  const [activeIndex, setActiveIndex] = useState(-1);
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault();
+        setActiveIndex((prev) => Math.min(prev + 1, items.length - 1));
+        break;
+      case 'ArrowUp':
+        e.preventDefault();
+        setActiveIndex((prev) => Math.max(prev - 1, 0));
+        break;
+      case 'Enter':
+      case ' ':
+        e.preventDefault();
+        if (activeIndex >= 0) onSelect(items[activeIndex]);
+        break;
+      case 'Escape':
+        onClose();
+        break;
+      case 'Home':
+        e.preventDefault();
+        setActiveIndex(0);
+        break;
+      case 'End':
+        e.preventDefault();
+        setActiveIndex(items.length - 1);
+        break;
+    }
+  };
+
+  return (
+    <ul
+      role="listbox"
+      tabIndex={0}
+      onKeyDown={handleKeyDown}
+      aria-activedescendant={activeIndex >= 0 ? `item-${activeIndex}` : undefined}
+    >
+      {items.map((item, index) => (
+        <li
+          key={item.id}
+          id={`item-${index}`}
+          role="option"
+          aria-selected={index === activeIndex}
+          className={cn(
+            'px-4 py-2 cursor-pointer',
+            index === activeIndex && 'bg-accent'
+          )}
+          onClick={() => onSelect(item)}
+        >
+          {item.label}
+        </li>
+      ))}
+    </ul>
+  );
+};
+```
+
+---
+
+## Forms Accessibility
+
+### Labels and Inputs
+
+```tsx
+// ✅ Explicit label association
+<FormItem>
+  <FormLabel htmlFor="email">Email</FormLabel>
+  <FormControl>
+    <Input
+      id="email"
+      type="email"
+      aria-describedby="email-description email-error"
+    />
+  </FormControl>
+  <FormDescription id="email-description">
+    We'll never share your email.
+  </FormDescription>
+  <FormMessage id="email-error" />
+</FormItem>
+
+// Required fields
+<FormLabel>
+  Email <span aria-hidden="true">*</span>
+</FormLabel>
+<Input required aria-required="true" />
+
+// Invalid state
+<Input
+  aria-invalid={!!error}
+  aria-describedby={error ? 'error-message' : undefined}
+/>
+{error && (
+  <p id="error-message" role="alert" className="text-destructive">
+    {error}
+  </p>
+)}
+```
+
+### Form Validation Announcements
+
+```tsx
+export const AccessibleForm: React.FC = () => {
+  const [errors, setErrors] = useState<string[]>([]);
+
+  return (
+    <form>
+      {/* Announce errors to screen readers */}
+      <div role="alert" aria-live="assertive" className="sr-only">
+        {errors.length > 0 && (
+          <p>
+            Form contains {errors.length} error{errors.length > 1 ? 's' : ''}.
+            Please review and correct.
+          </p>
+        )}
+      </div>
+
+      {/* Visible error summary */}
+      {errors.length > 0 && (
+        <div className="p-4 bg-destructive/10 rounded-lg mb-4">
+          <h2 className="font-medium text-destructive">
+            Please correct the following errors:
+          </h2>
+          <ul className="list-disc list-inside">
+            {errors.map((error, index) => (
+              <li key={index}>{error}</li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      {/* Form fields */}
+    </form>
+  );
+};
+```
+
+---
+
+## Images and Media
+
+### Image Alternatives
+
+```tsx
+// Informative images
+<img src="/chart.png" alt="Sales increased 25% in Q4 2024" />
+
+// Decorative images
+<img src="/decorative.png" alt="" role="presentation" />
+
+// Complex images with extended description
+<figure>
+  <img
+    src="/complex-diagram.png"
+    alt="System architecture diagram"
+    aria-describedby="diagram-desc"
+  />
+  <figcaption id="diagram-desc">
+    The system consists of three main components: API Gateway,
+    Processing Service, and Database cluster...
+  </figcaption>
+</figure>
+
+// Icons with text
+<button>
+  <Save className="h-4 w-4 mr-2" aria-hidden="true" />
+  Save
+</button>
+
+// Icon-only buttons
+<button aria-label="Save document">
+  <Save className="h-4 w-4" />
+</button>
+```
+
+### Video Accessibility
+
+```tsx
+export const AccessibleVideo: React.FC<{ src: string }> = ({ src }) => (
+  <div>
+    <video controls aria-describedby="video-description">
+      <source src={src} type="video/mp4" />
+      <track kind="captions" src="/captions.vtt" srcLang="en" label="English" />
+      <track kind="descriptions" src="/descriptions.vtt" srcLang="en" />
+      Your browser does not support the video tag.
+    </video>
+    <p id="video-description" className="sr-only">
+      This video demonstrates the product setup process.
+    </p>
+  </div>
+);
+```
+
+---
+
+## Color and Contrast
+
+### Color Contrast
+
+```tsx
+// ✅ Good contrast ratios
+// Text: at least 4.5:1 for normal text, 3:1 for large text
+// UI components: at least 3:1
+
+// Tailwind classes with good contrast
+<p className="text-foreground">High contrast text</p>
+<p className="text-muted-foreground">Slightly lower but acceptable</p>
+
+// ❌ Avoid low contrast
+<p className="text-gray-400 bg-gray-200">Hard to read</p>
+```
+
+### Don't Rely on Color Alone
+
+```tsx
+// ❌ Bad - color only indicator
+<span className={isValid ? 'text-green-500' : 'text-red-500'}>
+  Status
+</span>
+
+// ✅ Good - color + icon + text
+<span className={cn('flex items-center gap-2', isValid ? 'text-green-500' : 'text-red-500')}>
+  {isValid ? (
+    <>
+      <Check className="h-4 w-4" aria-hidden="true" />
+      <span>Valid</span>
+    </>
+  ) : (
+    <>
+      <X className="h-4 w-4" aria-hidden="true" />
+      <span>Invalid</span>
+    </>
+  )}
+</span>
+```
+
+---
+
+## Screen Reader Utilities
+
+### Visually Hidden Content
+
+```tsx
+// Tailwind class for screen-reader only content
+// Add to globals.css or use existing sr-only class
+
+// Usage
+<button>
+  <Heart className="h-4 w-4" aria-hidden="true" />
+  <span className="sr-only">Add to favorites</span>
+</button>
+
+// Announce changes without visual
+<span className="sr-only" role="status" aria-live="polite">
+  {itemCount} items in cart
+</span>
+```
+
+### Announcements Hook
+
+```tsx
+// hooks/useAnnounce.ts
+import { useCallback, useRef } from 'react';
+
+export function useAnnounce() {
+  const regionRef = useRef<HTMLDivElement>(null);
+
+  const announce = useCallback((message: string, priority: 'polite' | 'assertive' = 'polite') => {
+    if (regionRef.current) {
+      regionRef.current.setAttribute('aria-live', priority);
+      regionRef.current.textContent = message;
+      
+      // Clear after announcement
+      setTimeout(() => {
+        if (regionRef.current) {
+          regionRef.current.textContent = '';
+        }
+      }, 1000);
+    }
+  }, []);
+
+  const AnnouncerRegion = () => (
+    <div
+      ref={regionRef}
+      role="status"
+      aria-live="polite"
+      aria-atomic="true"
+      className="sr-only"
+    />
+  );
+
+  return { announce, AnnouncerRegion };
+}
+
+// Usage
+const { announce, AnnouncerRegion } = useAnnounce();
+
+const handleSubmit = async () => {
+  await submitForm();
+  announce('Form submitted successfully');
+};
+
+return (
+  <>
+    <AnnouncerRegion />
+    <form onSubmit={handleSubmit}>
+      {/* form content */}
+    </form>
+  </>
+);
+```
+
+---
+
+## Accessible Components
+
+### Toggle Button
+
+```tsx
+export const ToggleButton: React.FC<{
+  pressed: boolean;
+  onToggle: () => void;
+  children: React.ReactNode;
+}> = ({ pressed, onToggle, children }) => (
+  <button
+    type="button"
+    aria-pressed={pressed}
+    onClick={onToggle}
+    className={cn(
+      'px-4 py-2 rounded',
+      pressed ? 'bg-primary text-primary-foreground' : 'bg-secondary'
+    )}
+  >
+    {children}
+  </button>
+);
+```
+
+### Tabs
+
+```tsx
+export const Tabs: React.FC<TabsProps> = ({ tabs, activeTab, onChange }) => {
+  const handleKeyDown = (e: React.KeyboardEvent, index: number) => {
+    let newIndex = index;
+    
+    switch (e.key) {
+      case 'ArrowRight':
+        newIndex = (index + 1) % tabs.length;
+        break;
+      case 'ArrowLeft':
+        newIndex = (index - 1 + tabs.length) % tabs.length;
+        break;
+      case 'Home':
+        newIndex = 0;
+        break;
+      case 'End':
+        newIndex = tabs.length - 1;
+        break;
+      default:
+        return;
+    }
+    
+    e.preventDefault();
+    onChange(tabs[newIndex].id);
+  };
+
+  return (
+    <div>
+      <div role="tablist" aria-label="Content tabs">
+        {tabs.map((tab, index) => (
+          <button
+            key={tab.id}
+            role="tab"
+            id={`tab-${tab.id}`}
+            aria-selected={activeTab === tab.id}
+            aria-controls={`panel-${tab.id}`}
+            tabIndex={activeTab === tab.id ? 0 : -1}
+            onClick={() => onChange(tab.id)}
+            onKeyDown={(e) => handleKeyDown(e, index)}
+            className={cn(
+              'px-4 py-2',
+              activeTab === tab.id && 'border-b-2 border-primary'
+            )}
+          >
+            {tab.label}
+          </button>
+        ))}
+      </div>
+      
+      {tabs.map((tab) => (
+        <div
+          key={tab.id}
+          role="tabpanel"
+          id={`panel-${tab.id}`}
+          aria-labelledby={`tab-${tab.id}`}
+          hidden={activeTab !== tab.id}
+          tabIndex={0}
+        >
+          {tab.content}
+        </div>
+      ))}
+    </div>
+  );
+};
+```
+
+---
+
+## Testing Accessibility
+
+### Automated Testing
+
+```tsx
+// With jest-axe
+import { axe, toHaveNoViolations } from 'jest-axe';
+
+expect.extend(toHaveNoViolations);
+
+it('has no accessibility violations', async () => {
+  const { container } = render(<MyComponent />);
+  const results = await axe(container);
+  expect(results).toHaveNoViolations();
+});
+```
+
+### Manual Testing Checklist
+
+- [ ] Navigate with keyboard only (Tab, Shift+Tab, Enter, Space, Arrow keys)
+- [ ] Test with screen reader (VoiceOver, NVDA)
+- [ ] Verify focus indicators are visible
+- [ ] Check color contrast (4.5:1 for text)
+- [ ] Ensure all images have alt text
+- [ ] Verify form labels are associated
+- [ ] Test at 200% zoom
+- [ ] Verify without CSS/JavaScript
+
+---
+
+## Accessibility Checklist
+
+- [ ] Semantic HTML elements
+- [ ] ARIA labels on interactive elements
+- [ ] Keyboard navigation works
+- [ ] Focus management for modals/dialogs
+- [ ] Skip links present
+- [ ] Color contrast meets WCAG AA
+- [ ] Form fields have labels
+- [ ] Error messages are announced
+- [ ] Images have alt text
+- [ ] Live regions for dynamic content
+- [ ] Reduced motion support
+- [ ] Test with screen reader
+
+