npm - @harness-engineering/cli - Versions diffs - 1.23.2 → 1.24.1 - Mend

@harness-engineering/cli 1.23.2 → 1.24.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5716) hide show

package/dist/agents/skills/claude-code/a11y-keyboard-navigation/SKILL.md ADDED Viewed

@@ -0,0 +1,169 @@
+# Keyboard Navigation
+> Ensure all interactive elements are reachable and operable via keyboard alone without requiring a mouse
+## When to Use
+- Building any interactive web component
+- Adding custom widgets (dropdowns, sliders, tabs, drag-and-drop)
+- Reviewing focus order after layout changes
+- Implementing focus management for modals, drawers, or dynamic content
+- Ensuring compliance with WCAG 2.1 Success Criterion 2.1.1 (Keyboard)
+## Instructions
+1. **Use native interactive elements.** `<button>`, `<a>`, `<input>`, `<select>`, and `<textarea>` are keyboard-accessible by default. They receive focus, respond to Enter/Space, and are announced by screen readers. Never recreate this behavior on `<div>` or `<span>`.
+2. **Provide a visible focus indicator.** Users must see where focus is. Never remove the outline without providing an alternative.
+```css
+/* Remove default only if providing a custom indicator */
+:focus-visible {
+  outline: 2px solid #005fcc;
+  outline-offset: 2px;
+}
+/* Never do this without a replacement */
+/* :focus { outline: none; } */
+```
+Use `:focus-visible` instead of `:focus` so the indicator appears only for keyboard users, not mouse clicks.
+3. **Add a skip navigation link** as the first focusable element on every page. This lets keyboard users bypass repetitive navigation.
+```html
+<body>
+  <a href="#main-content" class="skip-link">Skip to main content</a>
+  <nav><!-- navigation --></nav>
+  <main id="main-content"><!-- content --></main>
+</body>
+```
+```css
+.skip-link {
+  position: absolute;
+  left: -10000px;
+}
+.skip-link:focus {
+  position: static;
+  display: block;
+}
+```
+4. **Maintain a logical tab order.** The DOM order should match the visual order. Avoid `tabindex` values greater than 0 — they disrupt the natural flow. Use only `tabindex="0"` (add to tab order) and `tabindex="-1"` (programmatically focusable but not in tab order).
+```tsx
+// tabindex="0" — makes a non-interactive element focusable
+<div role="listbox" tabIndex={0}>
+// tabindex="-1" — focusable via JavaScript, not via Tab
+<div id="error-message" tabIndex={-1} ref={errorRef}>
+```
+5. **Implement keyboard event handlers for custom widgets.** Follow WAI-ARIA Authoring Practices for expected key bindings:
+   - **Tabs:** Arrow keys move between tabs, Tab moves to the tab panel
+   - **Menus:** Arrow keys navigate items, Enter selects, Escape closes
+   - **Combobox:** Arrow keys navigate options, Enter selects, Escape clears
+   - **Dialog:** Tab cycles within the dialog, Escape closes
+```tsx
+function handleKeyDown(e: React.KeyboardEvent) {
+  switch (e.key) {
+    case 'ArrowDown':
+      e.preventDefault();
+      focusNextItem();
+      break;
+    case 'ArrowUp':
+      e.preventDefault();
+      focusPreviousItem();
+      break;
+    case 'Home':
+      e.preventDefault();
+      focusFirstItem();
+      break;
+    case 'End':
+      e.preventDefault();
+      focusLastItem();
+      break;
+    case 'Escape':
+      closeMenu();
+      break;
+  }
+}
+```
+6. **Manage focus when content changes dynamically.** When a modal opens, move focus into it. When it closes, return focus to the trigger element. When a route changes in a SPA, move focus to the new page heading or main content.
+```tsx
+function openModal() {
+  triggerRef.current = document.activeElement as HTMLElement;
+  setIsOpen(true);
+  // Focus the modal after render
+  requestAnimationFrame(() => modalRef.current?.focus());
+}
+function closeModal() {
+  setIsOpen(false);
+  triggerRef.current?.focus(); // return focus to trigger
+}
+```
+7. **Implement focus trapping in modals and dialogs.** When a modal is open, Tab and Shift+Tab should cycle only through focusable elements within the modal — not escape to the page behind.
+```typescript
+function trapFocus(container: HTMLElement) {
+  const focusable = container.querySelectorAll<HTMLElement>(
+    'a[href], button:not([disabled]), input:not([disabled]), select, textarea, [tabindex]:not([tabindex="-1"])'
+  );
+  const first = focusable[0];
+  const last = focusable[focusable.length - 1];
+  container.addEventListener('keydown', (e) => {
+    if (e.key !== 'Tab') return;
+    if (e.shiftKey && document.activeElement === first) {
+      e.preventDefault();
+      last.focus();
+    } else if (!e.shiftKey && document.activeElement === last) {
+      e.preventDefault();
+      first.focus();
+    }
+  });
+}
+```
+8. **Never create keyboard traps.** Users must always be able to navigate away from any component using standard keys (Tab, Escape). The only exception is modal dialogs, which trap focus intentionally but provide an Escape key exit.
+## Details
+**WCAG requirements:** SC 2.1.1 (Keyboard) requires all functionality to be operable via keyboard. SC 2.1.2 (No Keyboard Trap) requires users to be able to move focus away from any component. SC 2.4.7 (Focus Visible) requires a visible focus indicator.
+**`tabindex` values:**
+- Omitted or not applicable: Element follows default focusability (interactive elements are focusable, non-interactive are not)
+- `0`: Element is added to the natural tab order based on DOM position
+- `-1`: Element is focusable via `element.focus()` but not via Tab key
+- Positive values (`1`, `2`, etc.): Avoid — they override natural tab order and create maintenance nightmares
+**Roving tabindex pattern:** For composite widgets (tab lists, toolbars), only one item has `tabindex="0"` at a time. Arrow keys move `tabindex="0"` to the next item and `tabindex="-1"` to the previous. Tab moves focus out of the widget entirely.
+**Testing keyboard navigation:** Unplug your mouse and use the application with keyboard only. Tab through every page, activate every button, fill every form, dismiss every dialog. If you get stuck or cannot see where focus is, there is a bug.
+## Source
+https://www.w3.org/WAI/WCAG21/Understanding/keyboard
+## Process
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+## Harness Integration
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+## Success Criteria
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/claude-code/a11y-keyboard-navigation/skill.yaml ADDED Viewed

@@ -0,0 +1,46 @@
+name: a11y-keyboard-navigation
+version: '1.0.0'
+description: Ensure all interactive elements are reachable and operable via keyboard alone
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.tsx'
+  - '**/*.html'
+  - '**/*.vue'
+  - '**/*.svelte'
+  - '**/*.astro'
+related_skills:
+  - a11y-semantic-html
+  - a11y-modal-patterns
+  - a11y-form-patterns
+  - design-affordances
+  - design-feedback-patterns
+stack_signals:
+  - accessibility
+  - react
+  - typescript
+keywords:
+  - keyboard
+  - tab-order
+  - focus
+  - focus-trap
+  - focus-visible
+  - tabindex
+  - skip-link
+metadata:
+  author: community
+  upstream: w3.org/WAI/WCAG21/Understanding/keyboard
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/a11y-modal-patterns/SKILL.md ADDED Viewed

@@ -0,0 +1,201 @@
+# Accessible Modal Dialog Patterns
+> Build accessible modal dialogs with focus trapping, escape dismissal, background inertness, and screen reader announcements
+## When to Use
+- Implementing modal dialogs, confirmation prompts, or alert dialogs
+- Building sheet/drawer overlays that require user attention
+- Creating image lightboxes or video players in overlay
+- Reviewing existing modals for keyboard and screen reader accessibility
+## Instructions
+1. **Use the native `<dialog>` element when possible.** Modern browsers support `<dialog>` with `.showModal()`, which provides built-in focus trapping, Escape dismissal, and backdrop styling.
+```tsx
+function Modal({ isOpen, onClose, children }: ModalProps) {
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    if (isOpen) {
+      dialog.showModal();
+    } else {
+      dialog.close();
+    }
+  }, [isOpen]);
+  return (
+    <dialog ref={dialogRef} onClose={onClose} aria-labelledby="dialog-title">
+      {children}
+    </dialog>
+  );
+}
+```
+2. **If using a custom modal (not `<dialog>`), implement all accessibility requirements manually:**
+```tsx
+function CustomModal({ isOpen, onClose, title, children }: ModalProps) {
+  const modalRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLElement | null>(null);
+  useEffect(() => {
+    if (isOpen) {
+      triggerRef.current = document.activeElement as HTMLElement;
+      // Focus the first focusable element in the modal
+      requestAnimationFrame(() => {
+        const firstFocusable = modalRef.current?.querySelector<HTMLElement>(
+          'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+        );
+        firstFocusable?.focus();
+      });
+    }
+    return () => {
+      // Return focus to trigger when closing
+      triggerRef.current?.focus();
+    };
+  }, [isOpen]);
+  if (!isOpen) return null;
+  return (
+    <>
+      <div className="backdrop" onClick={onClose} />
+      <div
+        ref={modalRef}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="dialog-title"
+        onKeyDown={(e) => {
+          if (e.key === 'Escape') onClose();
+        }}
+      >
+        <h2 id="dialog-title">{title}</h2>
+        {children}
+      </div>
+    </>
+  );
+}
+```
+3. **Trap focus inside the modal.** Tab and Shift+Tab must cycle through focusable elements within the modal only. Use a focus trap library or implement manually.
+```typescript
+function useFocusTrap(ref: RefObject<HTMLElement>, active: boolean) {
+  useEffect(() => {
+    if (!active || !ref.current) return;
+    const container = ref.current;
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab') return;
+      const focusable = container.querySelectorAll<HTMLElement>(
+        'a[href], button:not([disabled]), input:not([disabled]), select, textarea, [tabindex]:not([tabindex="-1"])'
+      );
+      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();
+      }
+    };
+    container.addEventListener('keydown', handleKeyDown);
+    return () => container.removeEventListener('keydown', handleKeyDown);
+  }, [ref, active]);
+}
+```
+4. **Make background content inert.** When the modal is open, background content must not be interactive. Use the `inert` attribute on the main content.
+```tsx
+useEffect(() => {
+  const main = document.getElementById('app-root');
+  if (isOpen && main) {
+    main.setAttribute('inert', '');
+    return () => main.removeAttribute('inert');
+  }
+}, [isOpen]);
+```
+5. **Close on Escape key press.** This is expected behavior — users should never be trapped in a dialog without a keyboard exit.
+6. **Close on backdrop click** for non-critical dialogs. For confirmation dialogs (`role="alertdialog"`), require explicit button interaction.
+7. **Use `role="alertdialog"` for confirmation prompts** that require the user to acknowledge or make a choice. These should not close on backdrop click.
+```tsx
+<div
+  role="alertdialog"
+  aria-modal="true"
+  aria-labelledby="alert-title"
+  aria-describedby="alert-desc"
+>
+  <h2 id="alert-title">Delete Account?</h2>
+  <p id="alert-desc">
+    This will permanently delete your account and all data. This cannot be undone.
+  </p>
+  <button onClick={onCancel}>Cancel</button>
+  <button onClick={onConfirm}>Delete Account</button>
+</div>
+```
+8. **Return focus to the trigger element when the modal closes.** Save a reference to `document.activeElement` before opening the modal and call `.focus()` on it after closing.
+9. **Prevent body scroll when modal is open.**
+```css
+body.modal-open {
+  overflow: hidden;
+}
+```
+## Details
+**`<dialog>` vs. custom modal:** The native `<dialog>` element with `.showModal()` provides focus trapping, Escape dismissal, `::backdrop` styling, top-layer rendering, and `inert` behavior on background content — all for free. It is supported in all modern browsers. Use custom implementations only when you need behavior that `<dialog>` does not support.
+**Focus management sequence:**
+1. User clicks trigger button
+2. Save reference to trigger element
+3. Open modal, move focus to first focusable element (or the modal container with `tabIndex={-1}`)
+4. Trap focus within modal
+5. User closes modal (Escape, close button, or backdrop click)
+6. Return focus to saved trigger element
+**`aria-modal="true"` vs. `inert`:** `aria-modal="true"` tells screen readers that content behind the dialog is not interactive. However, some screen readers do not fully respect this. Adding `inert` to background content provides a robust fallback that works at the browser level.
+**Common mistakes:**
+- Focus escaping the modal when Tab reaches the end (no focus trap)
+- Not returning focus to trigger on close (user is lost on the page)
+- Background content scrollable and interactive while modal is open
+- Missing accessible name (`aria-labelledby` or `aria-label`)
+- Auto-focusing a close button instead of the most relevant element
+## Source
+https://www.w3.org/WAI/ARIA/apd/patterns/dialog-modal/
+## Process
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+## Harness Integration
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+## Success Criteria
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/claude-code/a11y-modal-patterns/skill.yaml ADDED Viewed

@@ -0,0 +1,43 @@
+name: a11y-modal-patterns
+version: '1.0.0'
+description: Build accessible modal dialogs with focus trapping, escape dismissal, and screen reader announcements
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.tsx'
+  - '**/*.html'
+  - '**/*.vue'
+  - '**/*.svelte'
+  - '**/*.astro'
+related_skills:
+  - a11y-keyboard-navigation
+  - a11y-aria-patterns
+  - a11y-semantic-html
+stack_signals:
+  - accessibility
+  - react
+  - typescript
+keywords:
+  - modal
+  - dialog
+  - focus-trap
+  - inert
+  - overlay
+  - dismiss
+metadata:
+  author: community
+  upstream: w3.org/WAI/ARIA/apd/patterns/dialog-modal
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/a11y-motion-animation/SKILL.md ADDED Viewed

@@ -0,0 +1,199 @@
+# Motion and Animation Accessibility
+> Implement animations that respect user motion preferences, avoid seizure triggers, and provide pause controls
+## When to Use
+- Adding animations, transitions, or motion effects to a UI
+- Building auto-playing carousels, videos, or background animations
+- Implementing page transitions in a SPA
+- Using parallax scrolling or scroll-triggered animations
+- Reviewing existing animations for accessibility compliance
+## Instructions
+1. **Respect `prefers-reduced-motion`.** Users who enable "Reduce motion" in their OS settings have vestibular disorders or motion sensitivity. Query this preference and eliminate or simplify animations.
+```css
+/* Default: full animations */
+.card {
+  transition:
+    transform 0.3s ease,
+    opacity 0.3s ease;
+}
+.card:hover {
+  transform: scale(1.05);
+}
+/* Reduced motion: remove or simplify */
+@media (prefers-reduced-motion: reduce) {
+  .card {
+    transition: none;
+  }
+  .card:hover {
+    transform: none;
+  }
+}
+```
+2. **Use a motion-first or reduce-first strategy.** Choose one approach and apply it consistently:
+```css
+/* Approach A: motion-first (add animations, remove for reduced-motion) */
+.element {
+  animation: slide-in 0.5s ease;
+}
+@media (prefers-reduced-motion: reduce) {
+  .element {
+    animation: none;
+  }
+}
+/* Approach B: reduce-first (no animations by default, add for no-preference) */
+.element {
+  animation: none;
+}
+@media (prefers-reduced-motion: no-preference) {
+  .element {
+    animation: slide-in 0.5s ease;
+  }
+}
+```
+Approach B is safer — users get no animation by default.
+3. **In JavaScript, check the preference before triggering animations.**
+```typescript
+const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+function animateElement(element: HTMLElement) {
+  if (prefersReducedMotion) {
+    // Instant state change, no animation
+    element.style.opacity = '1';
+    return;
+  }
+  element.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 300, easing: 'ease-in' });
+}
+```
+4. **In React, create a hook for motion preferences.**
+```typescript
+function usePrefersReducedMotion(): boolean {
+  const [prefersReduced, setPrefersReduced] = useState(
+    () => window.matchMedia('(prefers-reduced-motion: reduce)').matches
+  );
+  useEffect(() => {
+    const mql = window.matchMedia('(prefers-reduced-motion: reduce)');
+    const handler = (e: MediaQueryListEvent) => setPrefersReduced(e.matches);
+    mql.addEventListener('change', handler);
+    return () => mql.removeEventListener('change', handler);
+  }, []);
+  return prefersReduced;
+}
+// Usage
+function AnimatedCard() {
+  const reduceMotion = usePrefersReducedMotion();
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: reduceMotion ? 0 : 20 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ duration: reduceMotion ? 0 : 0.3 }}
+    />
+  );
+}
+```
+5. **Provide pause, stop, or hide controls for auto-playing content.** Any content that moves, blinks, or auto-updates for more than 5 seconds must have user controls (WCAG 2.2.2).
+```tsx
+function AutoCarousel({ slides }: { slides: Slide[] }) {
+  const [isPaused, setIsPaused] = useState(false);
+  return (
+    <div>
+      <button
+        onClick={() => setIsPaused(!isPaused)}
+        aria-label={isPaused ? 'Play slideshow' : 'Pause slideshow'}
+      >
+        {isPaused ? <PlayIcon /> : <PauseIcon />}
+      </button>
+      <Carousel autoPlay={!isPaused} slides={slides} />
+    </div>
+  );
+}
+```
+6. **Avoid flashing content.** Content that flashes more than 3 times per second can trigger seizures (WCAG 2.3.1 — Three Flashes). This is a hard constraint with no workaround.
+7. **Avoid large-scale motion.** Parallax effects, zooming transitions, and full-page scroll animations are common vestibular triggers. When using these, always check `prefers-reduced-motion` and provide a static alternative.
+8. **Keep essential animations short.** Transitions that communicate state changes (loading, success, error) should be under 500ms. Long, elaborate animations add cognitive load and frustrate users who interact frequently.
+9. **Use `will-change` and GPU-composited properties for performance.** Janky animations that drop frames are worse than no animation. Stick to `transform` and `opacity` for smooth 60fps animations.
+```css
+.animated {
+  will-change: transform, opacity;
+  transition:
+    transform 0.2s ease,
+    opacity 0.2s ease;
+}
+```
+## Details
+**WCAG requirements:**
+- **2.2.2 Pause, Stop, Hide:** Auto-playing content that lasts more than 5 seconds must have controls
+- **2.3.1 Three Flashes:** No content flashes more than 3 times per second
+- **2.3.3 Animation from Interactions (AAA):** Motion triggered by user interaction can be disabled
+**What counts as "reduced motion":**
+- Remove: parallax scrolling, auto-playing animations, bouncing/shaking effects, zoom transitions
+- Keep: opacity fades (instant or very fast), color changes, layout reflows
+- Simplify: Replace slide transitions with fade, replace bounce with ease
+**Framer Motion integration:**
+```tsx
+<motion.div
+  layout
+  transition={{
+    layout: { duration: prefersReduced ? 0 : 0.3 },
+  }}
+/>
+```
+**Common mistakes:**
+- Checking `prefers-reduced-motion` once at load (user can change it at runtime — use `addEventListener`)
+- Removing only CSS animations while JavaScript-driven animations still run
+- Interpreting "reduced motion" as "no animation" (subtle fades and opacity changes are usually fine)
+- Auto-playing video backgrounds without a pause button
+## Source
+https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions
+## Process
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+## Harness Integration
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+## Success Criteria
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/claude-code/a11y-motion-animation/skill.yaml ADDED Viewed

@@ -0,0 +1,46 @@
+name: a11y-motion-animation
+version: '1.0.0'
+description: Implement animations that respect user motion preferences and avoid triggering vestibular disorders
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.tsx'
+  - '**/*.html'
+  - '**/*.vue'
+  - '**/*.svelte'
+  - '**/*.astro'
+  - '**/*.css'
+  - '**/*.scss'
+related_skills:
+  - a11y-color-contrast
+  - a11y-semantic-html
+  - design-motion-principles
+  - design-micro-interactions
+stack_signals:
+  - accessibility
+  - react
+  - typescript
+keywords:
+  - motion
+  - animation
+  - reduced-motion
+  - prefers-reduced-motion
+  - vestibular
+  - transitions
+metadata:
+  author: community
+  upstream: w3.org/WAI/WCAG21/Understanding/animation-from-interactions
+state:
+  persistent: false
+  files: []
+depends_on: []