@mmerterden/multi-agent-pipeline 20.35.0 → 20.37.0

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

@@ -57,186 +57,15 @@ keyboard operability, screen reader support, and sufficient color contrast.
 
 ## 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>
-```
+Code for this section: [Web accessibility examples](references/a11y-examples.md).
 
 ## 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>
-```
+Code for this section: [Web accessibility examples](references/a11y-examples.md).
 
 ## 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;
-    });
-  });
-}
-```
+Code for this section: [Web accessibility examples](references/a11y-examples.md).
 
 ## Color Contrast and Visual Design
 
@@ -374,3 +203,7 @@ test('homepage has no a11y violations', async ({ page }) => {
 | 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 |
+
+## References
+
+- [Web accessibility examples](references/a11y-examples.md): open when building ARIA widgets, accessible forms, focus traps or roving tab index.

package/pipeline/skills/shared/external/web-accessibility/references/a11y-examples.md

@@ -0,0 +1,192 @@
+# Web accessibility examples
+
+<!-- toc -->
+- [ARIA Roles, States, and Properties](#aria-roles-states-and-properties)
+- [Form Accessibility](#form-accessibility)
+- [Keyboard Navigation](#keyboard-navigation)
+<!-- /toc -->
+
+Markup and script for ARIA widgets, accessible forms and keyboard navigation. SKILL.md keeps the principles, contrast rules, testing and troubleshooting.
+
+## 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;
+    });
+  });
+}
+```

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

@@ -159,42 +159,9 @@ module.exports = withBundleAnalyzer({
 
 ## Caching Strategies
 
-```typescript
-// Service Worker caching with Workbox
-import { precacheAndRoute } from 'workbox-precaching';
-import { registerRoute } from 'workbox-routing';
-import { StaleWhileRevalidate, CacheFirst, NetworkFirst } from 'workbox-strategies';
-import { ExpirationPlugin } from 'workbox-expiration';
-
-// Precache static assets
-precacheAndRoute(self.__WB_MANIFEST);
-
-// Cache-first for images (long-lived)
-registerRoute(
-  ({ request }) => request.destination === 'image',
-  new CacheFirst({
-    cacheName: 'images',
-    plugins: [
-      new ExpirationPlugin({ maxEntries: 100, maxAgeSeconds: 30 * 24 * 60 * 60 }),
-    ],
-  })
-);
+With a service worker (Workbox): precache static assets, cache-first for long-lived images, stale-while-revalidate for CSS and JS, network-first for API calls.
 
-// Stale-while-revalidate for CSS/JS
-registerRoute(
-  ({ request }) => request.destination === 'style' || request.destination === 'script',
-  new StaleWhileRevalidate({ cacheName: 'static-resources' })
-);
-
-// Network-first for API calls
-registerRoute(
-  ({ url }) => url.pathname.startsWith('/api/'),
-  new NetworkFirst({
-    cacheName: 'api-cache',
-    networkTimeoutSeconds: 3,
-  })
-);
-```
+Code: [Caching Strategies](references/code-examples.md#caching-strategies).
 
 ### HTTP Caching Headers
 
@@ -254,38 +221,9 @@ export async function GET() {
 
 ## Reducing INP (Interaction to Next Paint)
 
-```typescript
-// Break up long tasks with scheduler.yield() or setTimeout
-async function processLargeList(items: Item[]) {
-  const CHUNK_SIZE = 50;
-  for (let i = 0; i < items.length; i += CHUNK_SIZE) {
-    const chunk = items.slice(i, i + CHUNK_SIZE);
-    processChunk(chunk);
-
-    // Yield to the browser between chunks
-    if ('scheduler' in globalThis && 'yield' in scheduler) {
-      await scheduler.yield();
-    } else {
-      await new Promise((resolve) => setTimeout(resolve, 0));
-    }
-  }
-}
-
-// Debounce expensive input handlers
-import { useDebouncedCallback } from 'use-debounce';
-
-function SearchInput() {
-  const handleSearch = useDebouncedCallback((term: string) => {
-    performSearch(term); // Expensive operation
-  }, 300);
-
-  return <input onChange={(e) => handleSearch(e.target.value)} />;
-}
+Break long tasks into chunks and yield to the browser between them, debounce expensive input handlers, and use CSS containment on complex layouts.
 
-// Use CSS containment for complex layouts
-// .card { contain: content; }
-// .sidebar { contain: layout style; }
-```
+Code: [Reducing INP (Interaction to Next Paint)](references/code-examples.md#reducing-inp-interaction-to-next-paint).
 
 ## Lighthouse Audit Checklist
 
@@ -346,3 +284,7 @@ npx lhci autorun --config=lighthouserc.json
 | Large bundle | Importing entire libraries | Use tree-shakeable imports, analyze with bundle visualizer |
 | Slow TTFB | No server caching, slow DB | Add CDN, implement server-side caching, optimize queries |
 | Flash of unstyled text | Web font loading | Use `font-display: swap`, preload font files |
+
+## References
+
+- [Code examples](references/code-examples.md): open for the full code behind Caching Strategies, Reducing INP (Interaction to Next Paint).

package/pipeline/skills/shared/external/web-performance/references/code-examples.md

@@ -0,0 +1,77 @@
+# Web Performance Code Examples
+
+Full code samples for the SKILL.md sections that link here. The rules and the decision guidance stay in SKILL.md; each heading below matches the SKILL.md section the code belongs to.
+
+## Caching Strategies
+
+```typescript
+// Service Worker caching with Workbox
+import { precacheAndRoute } from 'workbox-precaching';
+import { registerRoute } from 'workbox-routing';
+import { StaleWhileRevalidate, CacheFirst, NetworkFirst } from 'workbox-strategies';
+import { ExpirationPlugin } from 'workbox-expiration';
+
+// Precache static assets
+precacheAndRoute(self.__WB_MANIFEST);
+
+// Cache-first for images (long-lived)
+registerRoute(
+  ({ request }) => request.destination === 'image',
+  new CacheFirst({
+    cacheName: 'images',
+    plugins: [
+      new ExpirationPlugin({ maxEntries: 100, maxAgeSeconds: 30 * 24 * 60 * 60 }),
+    ],
+  })
+);
+
+// Stale-while-revalidate for CSS/JS
+registerRoute(
+  ({ request }) => request.destination === 'style' || request.destination === 'script',
+  new StaleWhileRevalidate({ cacheName: 'static-resources' })
+);
+
+// Network-first for API calls
+registerRoute(
+  ({ url }) => url.pathname.startsWith('/api/'),
+  new NetworkFirst({
+    cacheName: 'api-cache',
+    networkTimeoutSeconds: 3,
+  })
+);
+```
+
+## Reducing INP (Interaction to Next Paint)
+
+```typescript
+// Break up long tasks with scheduler.yield() or setTimeout
+async function processLargeList(items: Item[]) {
+  const CHUNK_SIZE = 50;
+  for (let i = 0; i < items.length; i += CHUNK_SIZE) {
+    const chunk = items.slice(i, i + CHUNK_SIZE);
+    processChunk(chunk);
+
+    // Yield to the browser between chunks
+    if ('scheduler' in globalThis && 'yield' in scheduler) {
+      await scheduler.yield();
+    } else {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+  }
+}
+
+// Debounce expensive input handlers
+import { useDebouncedCallback } from 'use-debounce';
+
+function SearchInput() {
+  const handleSearch = useDebouncedCallback((term: string) => {
+    performSearch(term); // Expensive operation
+  }, 300);
+
+  return <input onChange={(e) => handleSearch(e.target.value)} />;
+}
+
+// Use CSS containment for complex layouts
+// .card { contain: content; }
+// .sidebar { contain: layout style; }
+```