devflow-kit 0.9.0 → 1.1.0

package/plugins/devflow-core-skills/skills/accessibility/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: accessibility
+description: This skill should be used when the user asks to "add accessibility", "check ARIA", "handle keyboard navigation", "add focus management", or creates UI components, forms, or interactive elements. Provides WCAG 2.1 AA patterns for keyboard navigation, ARIA roles and states, focus management, color contrast, and screen reader support.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.tsx"
+    - "**/*.jsx"
+    - "**/*.css"
+    - "**/*.scss"
+  exclude:
+    - "node_modules/**"
+    - "**/*.test.*"
+    - "**/*.spec.*"
+---
+
+# Accessibility Patterns
+
+Reference for web accessibility (WCAG 2.1 AA compliance), keyboard navigation, screen reader support, and inclusive design.
+
+## Iron Law
+
+> **EVERY INTERACTION MUST BE POSSIBLE WITHOUT A MOUSE**
+>
+> If a user cannot complete an action using only keyboard, the feature is broken.
+> Mouse-only interactions exclude users with motor disabilities, power users,
+> and anyone navigating with assistive technology. Tab order, focus management,
+> and keyboard shortcuts are not optional enhancements.
+
+## When This Skill Activates
+
+- Creating interactive UI components
+- Building forms and inputs
+- Working with React/JSX code
+- Discussing focus, ARIA, or screen readers
+- Reviewing color schemes or contrast
+
+---
+
+## Keyboard Navigation
+
+### Focus Management
+
+```tsx
+// CORRECT: Focus trap in modal
+function Modal({ isOpen, onClose, children }) {
+  const firstFocusable = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    if (isOpen) firstFocusable.current?.focus();
+  }, [isOpen]);
+
+  return (
+    <div role="dialog" aria-modal="true" onKeyDown={(e) => {
+      if (e.key === 'Escape') onClose();
+    }}>
+      <button ref={firstFocusable}>First action</button>
+      {children}
+    </div>
+  );
+}
+
+// VIOLATION: No focus management, no escape handler
+function BadModal({ children }) {
+  return <div className="modal">{children}</div>;
+}
+```
+
+### Skip Links
+
+```tsx
+// CORRECT: Skip to main content
+<a href="#main-content" className="sr-only focus:not-sr-only">
+  Skip to main content
+</a>
+<main id="main-content" tabIndex={-1}>...</main>
+```
+
+---
+
+## ARIA and Semantic HTML
+
+### Prefer Semantic Elements
+
+```tsx
+// CORRECT: Native semantics
+<button onClick={handleClick}>Submit</button>
+<nav aria-label="Main"><ul>...</ul></nav>
+<article><header>...</header></article>
+
+// VIOLATION: Div with role instead of semantic element
+<div role="button" onClick={handleClick}>Submit</div>
+<div role="navigation">...</div>
+```
+
+### Live Regions
+
+```tsx
+// CORRECT: Announce dynamic changes
+<div aria-live="polite" aria-atomic="true">
+  {message && <p>{message}</p>}
+</div>
+
+// For errors (assertive)
+<div role="alert">{errorMessage}</div>
+```
+
+---
+
+## Color and Contrast
+
+| Element | Minimum Ratio | WCAG Level |
+|---------|--------------|------------|
+| Normal text (<18px) | 4.5:1 | AA |
+| Large text (>=18px bold, >=24px) | 3:1 | AA |
+| UI components | 3:1 | AA |
+| Enhanced | 7:1 | AAA |
+
+### Never Color-Only Meaning
+
+```tsx
+// VIOLATION: Only color indicates error
+<input style={{ borderColor: hasError ? 'red' : 'gray' }} />
+
+// CORRECT: Icon + text + color
+<input aria-invalid={hasError} aria-describedby="error-msg" />
+{hasError && <span id="error-msg" role="alert">Required field</span>}
+```
+
+---
+
+## Motion and Animation
+
+```tsx
+// CORRECT: Respect user preferences
+const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+<div className={prefersReduced ? 'no-animation' : 'animate-fade'}>
+  Content
+</div>
+
+// CSS approach
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+---
+
+## Touch and Pointer
+
+### Minimum Target Size
+
+```css
+/* CORRECT: 44x44px minimum touch target */
+.button {
+  min-width: 44px;
+  min-height: 44px;
+  padding: 12px 16px;
+}
+
+/* VIOLATION: Tiny tap targets */
+.icon-button {
+  width: 20px;
+  height: 20px;
+}
+```
+
+---
+
+## Forms and Errors
+
+```tsx
+// CORRECT: Associated labels and error linking
+<div>
+  <label htmlFor="email">Email</label>
+  <input
+    id="email"
+    type="email"
+    aria-invalid={!!error}
+    aria-describedby={error ? 'email-error' : undefined}
+  />
+  {error && <span id="email-error" role="alert">{error}</span>}
+</div>
+
+// VIOLATION: Placeholder as label
+<input placeholder="Enter email" />
+```
+
+---
+
+## Extended References
+
+For additional patterns and detection rules:
+- `references/violations.md` - Extended accessibility violations
+- `references/patterns.md` - Extended correct patterns
+- `references/detection.md` - Grep patterns for finding issues
+
+---
+
+## Severity Guidelines
+
+| Severity | Criteria |
+|----------|----------|
+| CRITICAL | No keyboard access, missing form labels, zero contrast |
+| HIGH | Missing focus indicators, no skip links, color-only meaning |
+| MEDIUM | Missing ARIA labels, poor focus order, small touch targets |
+| LOW | Missing optional enhancements, could improve announcements |
+
+---
+
+## Checklist
+
+- [ ] All interactive elements reachable via Tab
+- [ ] Visible focus indicators on all focusable elements
+- [ ] Escape closes modals/dropdowns
+- [ ] Skip link to main content
+- [ ] All form inputs have associated labels
+- [ ] Errors linked via aria-describedby
+- [ ] Color contrast meets 4.5:1 (text) / 3:1 (UI)
+- [ ] No color-only meaning
+- [ ] prefers-reduced-motion respected
+- [ ] Touch targets minimum 44x44px
+- [ ] aria-live for dynamic content
+- [ ] Semantic HTML preferred over ARIA roles

package/plugins/devflow-core-skills/skills/accessibility/references/detection.md

@@ -0,0 +1,171 @@
+# Accessibility Detection Patterns
+
+Grep and regex patterns for detecting accessibility issues. Use with `Grep` tool.
+
+## Keyboard Access Issues
+
+```bash
+# onClick without keyboard handler
+rg 'onClick=\{[^}]+\}' --type tsx | rg -v 'onKeyDown|onKeyPress|onKeyUp|<button|<a '
+
+# Non-focusable interactive elements
+rg '<(div|span)\s+[^>]*onClick' --type tsx
+
+# tabIndex with positive values (breaks natural order)
+rg 'tabIndex=\{?[1-9]' --type tsx
+
+# Drag-only interactions
+rg 'onDrag(Start|End|Over)' --type tsx | rg -v 'onKey'
+```
+
+## Missing Labels
+
+```bash
+# Input without id (likely missing label association)
+rg '<input[^>]*>' --type tsx | rg -v 'id='
+
+# Button with only icon (no text or aria-label)
+rg '<button[^>]*>\s*<[A-Z][a-zA-Z]*Icon' --type tsx | rg -v 'aria-label'
+
+# Image without alt
+rg '<img[^>]*>' --type tsx | rg -v 'alt='
+
+# Links without text content
+rg '<a[^>]*>\s*<(img|[A-Z])' --type tsx | rg -v 'aria-label'
+```
+
+## ARIA Misuse
+
+```bash
+# Redundant role on semantic elements
+rg '<button[^>]*role="button"' --type tsx
+rg '<nav[^>]*role="navigation"' --type tsx
+rg '<a[^>]*role="link"' --type tsx
+
+# aria-hidden on focusable elements
+rg 'aria-hidden="true"[^>]*(tabIndex|onClick|href)' --type tsx
+
+# Missing required ARIA attributes
+rg 'role="slider"' --type tsx | rg -v 'aria-value(now|min|max)'
+rg 'role="checkbox"' --type tsx | rg -v 'aria-checked'
+rg 'role="tab"' --type tsx | rg -v 'aria-selected'
+```
+
+## Focus Management Issues
+
+```bash
+# Focus removal (outline: none without replacement)
+rg 'outline:\s*none' --type css --type scss | rg -v 'focus-visible|focus-ring'
+
+# Dialogs without role or aria-modal
+rg 'modal|dialog' --type tsx -i | rg -v 'role="dialog"|aria-modal'
+
+# Missing escape key handler in modals
+rg '(Modal|Dialog|Popup)' --type tsx | rg -v 'Escape|onKeyDown'
+```
+
+## Color and Contrast
+
+```bash
+# Light gray text (potential contrast issue)
+rg 'color:\s*#[a-fA-F0-9]{3,6}' --type css | rg -i '(#[cdef]{3}|#[cdef]{6})'
+
+# Color-only indicators
+rg 'color.*error|color.*success|color.*warning' --type css -i
+
+# Placeholder as only label indicator
+rg '<input[^>]*placeholder=' --type tsx | rg -v '<label|aria-label'
+```
+
+## Form Issues
+
+```bash
+# Missing error association
+rg 'aria-invalid' --type tsx | rg -v 'aria-describedby'
+
+# Form without noValidate (may conflict with custom validation)
+rg '<form[^>]*>' --type tsx | rg 'onSubmit' | rg -v 'noValidate'
+
+# Submit button without type
+rg '<button[^>]*>Submit' --type tsx | rg -v 'type="submit"'
+```
+
+## Motion Issues
+
+```bash
+# Animation without reduced motion check
+rg 'animation(-duration)?:' --type css | rg -v 'prefers-reduced-motion'
+
+# Transition without reduced motion check
+rg 'transition(-duration)?:' --type css | rg -v 'prefers-reduced-motion'
+
+# Autoplay video/audio
+rg '<(video|audio)[^>]*autoPlay' --type tsx
+
+# Infinite animation loops
+rg 'animation:.*infinite' --type css
+```
+
+## Touch Target Issues
+
+```bash
+# Small fixed dimensions
+rg '(width|height):\s*(1[0-9]|2[0-9]|3[0-9])px' --type css
+
+# Icon buttons without adequate sizing
+rg '\.icon(-btn|Button)' --type css -A5 | rg '(width|height)'
+```
+
+## Screen Reader Issues
+
+```bash
+# Generic link text
+rg '>click here<|>here<|>read more<|>learn more<' --type tsx -i
+
+# aria-label duplicating visible text
+rg 'aria-label="([^"]+)"[^>]*>\1<' --type tsx
+
+# Missing landmark regions
+rg '<div[^>]*class="(header|footer|nav|sidebar|main)"' --type tsx | rg -v 'role='
+```
+
+## Live Region Issues
+
+```bash
+# Dynamic content without aria-live
+rg '(loading|spinner|toast|notification|alert)' --type tsx -i | rg -v 'aria-live|role="alert"|role="status"'
+
+# Missing aria-atomic on live regions
+rg 'aria-live=' --type tsx | rg -v 'aria-atomic'
+```
+
+## Semantic HTML Issues
+
+```bash
+# Div/span used instead of semantic elements
+rg '<div[^>]*role="(button|link|navigation|main|banner|contentinfo)"' --type tsx
+rg '<span[^>]*role="(button|link)"' --type tsx
+
+# Heading level skips (partial detection)
+rg '<h[1-6]' --type tsx
+
+# List items outside lists
+rg '<li[^>]*>' --type tsx | rg -v '<ul|<ol'
+```
+
+## Testing Commands
+
+```bash
+# Full accessibility audit on changed files
+git diff --name-only HEAD~1 | xargs -I{} rg -l 'onClick|<input|<button|<a ' {} 2>/dev/null
+
+# Count potential issues by category
+echo "=== Potential Keyboard Issues ==="
+rg '<(div|span)\s+[^>]*onClick' --type tsx -c
+
+echo "=== Potential Label Issues ==="
+rg '<input[^>]*>' --type tsx | rg -v 'id=' | wc -l
+
+echo "=== Potential ARIA Issues ==="
+rg '<button[^>]*role="button"' --type tsx -c
+```