@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/shared/external/web-accessibility/SKILL.md

@@ -0,0 +1,373 @@
+---
+description: "WCAG 2.2 AA web accessibility: ARIA roles/states, keyboard navigation, screen readers, color contrast, focus management, axe-core testing"
+tags: [accessibility, a11y, wcag, aria, screen-reader, frontend]
+version: "2025.1"
+---
+
+# Web Accessibility (WCAG 2.2 AA)
+
+## Core Principles (POUR)
+
+Web accessibility follows four principles: Perceivable, Operable, Understandable, Robust.
+All production websites must meet WCAG 2.2 Level AA. This includes proper semantic HTML,
+keyboard operability, screen reader support, and sufficient color contrast.
+
+## Semantic HTML First
+
+```html
+<!-- Use native HTML elements before reaching for ARIA -->
+
+<!-- Navigation -->
+<nav aria-label="Main navigation">
+  <ul>
+    <li><a href="/" aria-current="page">Home</a></li>
+    <li><a href="/products">Products</a></li>
+    <li><a href="/about">About</a></li>
+  </ul>
+</nav>
+
+<!-- Page structure -->
+<header>
+  <h1>Page Title</h1>
+</header>
+<main id="main-content">
+  <article>
+    <h2>Article Heading</h2>
+    <p>Content...</p>
+    <section aria-labelledby="comments-heading">
+      <h3 id="comments-heading">Comments</h3>
+    </section>
+  </article>
+  <aside aria-label="Related articles">
+    <h2>Related</h2>
+  </aside>
+</main>
+<footer>
+  <p>&copy; 2025 Company</p>
+</footer>
+
+<!-- Skip link (first element in body) -->
+<a href="#main-content" class="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:bg-white focus:px-4 focus:py-2 focus:rounded">
+  Skip to main content
+</a>
+```
+
+## ARIA Roles, States, and Properties
+
+```html
+<!-- Dialog / Modal -->
+<div
+  role="dialog"
+  aria-modal="true"
+  aria-labelledby="dialog-title"
+  aria-describedby="dialog-desc"
+>
+  <h2 id="dialog-title">Confirm Delete</h2>
+  <p id="dialog-desc">This action cannot be undone.</p>
+  <button>Cancel</button>
+  <button>Delete</button>
+</div>
+
+<!-- Tabs -->
+<div role="tablist" aria-label="Product info">
+  <button role="tab" id="tab-1" aria-selected="true" aria-controls="panel-1">
+    Description
+  </button>
+  <button role="tab" id="tab-2" aria-selected="false" aria-controls="panel-2" tabindex="-1">
+    Reviews
+  </button>
+</div>
+<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">
+  <p>Product description...</p>
+</div>
+<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>
+  <p>Product reviews...</p>
+</div>
+
+<!-- Live region for dynamic content -->
+<div aria-live="polite" aria-atomic="true">
+  <!-- Screen reader announces changes here -->
+  <p>3 items in your cart</p>
+</div>
+
+<!-- Status messages -->
+<div role="status" aria-live="polite">
+  Form submitted successfully.
+</div>
+<div role="alert" aria-live="assertive">
+  Error: Please correct the highlighted fields.
+</div>
+
+<!-- Loading state -->
+<div aria-busy="true" aria-live="polite">
+  Loading results...
+</div>
+
+<!-- Expandable content -->
+<button aria-expanded="false" aria-controls="details-section">
+  Show Details
+</button>
+<div id="details-section" hidden>
+  <p>Additional information...</p>
+</div>
+```
+
+## Form Accessibility
+
+```html
+<form aria-label="Contact form">
+  <!-- Visible label (preferred) -->
+  <div>
+    <label for="name">Full Name <span aria-hidden="true">*</span></label>
+    <input
+      type="text"
+      id="name"
+      name="name"
+      required
+      aria-required="true"
+      autocomplete="name"
+    />
+  </div>
+
+  <!-- Error state -->
+  <div>
+    <label for="email">Email <span aria-hidden="true">*</span></label>
+    <input
+      type="email"
+      id="email"
+      name="email"
+      required
+      aria-required="true"
+      aria-invalid="true"
+      aria-describedby="email-error email-hint"
+      autocomplete="email"
+    />
+    <p id="email-hint" class="hint">We'll never share your email.</p>
+    <p id="email-error" class="error" role="alert">
+      Please enter a valid email address.
+    </p>
+  </div>
+
+  <!-- Fieldset for related inputs -->
+  <fieldset>
+    <legend>Preferred contact method</legend>
+    <label>
+      <input type="radio" name="contact" value="email" /> Email
+    </label>
+    <label>
+      <input type="radio" name="contact" value="phone" /> Phone
+    </label>
+  </fieldset>
+
+  <button type="submit">Send Message</button>
+</form>
+```
+
+## Keyboard Navigation
+
+```typescript
+// Focus trap for modals
+function trapFocus(element: HTMLElement) {
+  const focusableSelectors = [
+    'a[href]', 'button:not([disabled])', 'input:not([disabled])',
+    'select:not([disabled])', 'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])',
+  ];
+  const focusableElements = element.querySelectorAll<HTMLElement>(
+    focusableSelectors.join(',')
+  );
+  const firstFocusable = focusableElements[0];
+  const lastFocusable = focusableElements[focusableElements.length - 1];
+
+  element.addEventListener('keydown', (e) => {
+    if (e.key !== 'Tab') return;
+
+    if (e.shiftKey) {
+      if (document.activeElement === firstFocusable) {
+        e.preventDefault();
+        lastFocusable.focus();
+      }
+    } else {
+      if (document.activeElement === lastFocusable) {
+        e.preventDefault();
+        firstFocusable.focus();
+      }
+    }
+  });
+
+  firstFocusable?.focus();
+}
+
+// React: accessible keyboard handler
+function handleKeyDown(event: React.KeyboardEvent, action: () => void) {
+  if (event.key === 'Enter' || event.key === ' ') {
+    event.preventDefault();
+    action();
+  }
+}
+
+// Roving tabindex for arrow key navigation (toolbar, menu, listbox)
+function useRovingTabindex(items: HTMLElement[]) {
+  let currentIndex = 0;
+
+  items.forEach((item, index) => {
+    item.tabIndex = index === 0 ? 0 : -1;
+    item.addEventListener('keydown', (e) => {
+      let newIndex = currentIndex;
+      if (e.key === 'ArrowDown' || e.key === 'ArrowRight') {
+        newIndex = (currentIndex + 1) % items.length;
+      } else if (e.key === 'ArrowUp' || e.key === 'ArrowLeft') {
+        newIndex = (currentIndex - 1 + items.length) % items.length;
+      } else if (e.key === 'Home') {
+        newIndex = 0;
+      } else if (e.key === 'End') {
+        newIndex = items.length - 1;
+      } else {
+        return;
+      }
+      e.preventDefault();
+      items[currentIndex].tabIndex = -1;
+      items[newIndex].tabIndex = 0;
+      items[newIndex].focus();
+      currentIndex = newIndex;
+    });
+  });
+}
+```
+
+## Color Contrast and Visual Design
+
+```css
+/* Minimum contrast ratios (WCAG 2.2 AA) */
+/* Normal text (< 18pt / < 14pt bold): 4.5:1 */
+/* Large text (>= 18pt / >= 14pt bold): 3:1 */
+/* UI components and graphical objects: 3:1 */
+
+/* Focus indicators must be visible */
+:focus-visible {
+  outline: 2px solid #4f46e5;
+  outline-offset: 2px;
+}
+
+/* Do not use color alone to convey information */
+.error-field {
+  border-color: #dc2626;         /* Red border */
+  border-width: 2px;             /* Thicker border */
+  background: url('error.svg');  /* Error icon */
+}
+
+/* Ensure text remains readable over images */
+.text-overlay {
+  background: linear-gradient(to top, rgba(0,0,0,0.7), transparent);
+  color: white;
+}
+
+/* Prefers reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+/* Prefers high contrast */
+@media (forced-colors: active) {
+  .custom-checkbox {
+    forced-color-adjust: none;
+    /* Use system colors */
+    border-color: ButtonText;
+    background-color: Canvas;
+  }
+}
+```
+
+## Screen Reader Utilities
+
+```css
+/* Visually hidden but accessible to screen readers */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}
+
+/* Make visible on focus (skip links) */
+.sr-only-focusable:focus {
+  position: static;
+  width: auto;
+  height: auto;
+  padding: 0.5rem 1rem;
+  margin: 0;
+  overflow: visible;
+  clip: auto;
+  white-space: normal;
+}
+```
+
+## Testing with axe-core
+
+```typescript
+// Vitest + axe-core
+import { render } from '@testing-library/react';
+import { axe, toHaveNoViolations } from 'jest-axe';
+
+expect.extend(toHaveNoViolations);
+
+test('page has no accessibility violations', async () => {
+  const { container } = render(<MyPage />);
+  const results = await axe(container);
+  expect(results).toHaveNoViolations();
+});
+
+// Playwright accessibility testing
+import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+test('homepage has no a11y violations', async ({ page }) => {
+  await page.goto('/');
+  const results = await new AxeBuilder({ page })
+    .withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])
+    .analyze();
+  expect(results.violations).toEqual([]);
+});
+```
+
+## Do's
+
+- Use semantic HTML elements (`button`, `nav`, `main`, `article`) before ARIA
+- Provide visible focus indicators on all interactive elements
+- Ensure all images have descriptive `alt` text (or `alt=""` for decorative images)
+- Support keyboard navigation for every interactive element
+- Use `aria-live` regions for dynamic content updates
+- Test with actual screen readers (VoiceOver, NVDA, JAWS)
+- Include skip links at the top of every page
+- Respect `prefers-reduced-motion` and `prefers-color-scheme`
+
+## Don'ts
+
+- Do not use `div` or `span` as buttons; use `<button>` or `<a>`
+- Do not rely on color alone to convey meaning (add icons, text, patterns)
+- Do not remove focus outlines without providing an alternative
+- Do not use `tabindex` > 0; it breaks natural tab order
+- Do not auto-play media without user control
+- Do not use ARIA when native HTML achieves the same result
+- Do not hide content with `display: none` and expect screen readers to read it
+- Do not use placeholder text as the only label for form fields
+
+## Troubleshooting
+
+| Problem | Cause | Solution |
+|---------|-------|----------|
+| Screen reader ignores element | `display: none` or `visibility: hidden` | Use `.sr-only` class to hide visually but keep accessible |
+| Focus lost after DOM update | Focused element removed | Programmatically move focus to the next logical element |
+| axe reports "color-contrast" | Text/background ratio too low | Use a contrast checker tool; adjust colors to meet 4.5:1 |
+| Tab order is wrong | Unstructured DOM or tabindex misuse | Restructure DOM to match visual order; remove tabindex > 0 |
+| Modal doesn't trap focus | No focus management | Implement focus trap and restore focus on close |
+| Live region not announced | Missing `aria-live` or wrong timing | Add `aria-live="polite"` and inject content after region exists in DOM |