@smicolon/ai-kit 0.1.0 → 0.1.1

package/packs/nextjs/rules/hooks.md

@@ -0,0 +1,132 @@
+---
+paths:
+  - "**/hooks/**/*.ts"
+  - "**/hooks/**/*.tsx"
+  - "**/use*.ts"
+  - "**/use*.tsx"
+---
+
+# Next.js Custom Hooks Standards
+
+## Structure
+
+```typescript
+import { useState, useEffect, useCallback } from 'react'
+
+interface UseUserOptions {
+  enabled?: boolean
+}
+
+interface UseUserReturn {
+  user: User | null
+  isLoading: boolean
+  error: Error | null
+  refetch: () => Promise<void>
+}
+
+export function useUser(userId: string, options: UseUserOptions = {}): UseUserReturn {
+  const { enabled = true } = options
+  const [user, setUser] = useState<User | null>(null)
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState<Error | null>(null)
+
+  const fetchUser = useCallback(async () => {
+    if (!enabled) return
+    setIsLoading(true)
+    try {
+      const response = await fetch(`/api/users/${userId}`)
+      if (!response.ok) throw new Error('Failed to fetch user')
+      const data = await response.json()
+      setUser(data)
+      setError(null)
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error('Unknown error'))
+    } finally {
+      setIsLoading(false)
+    }
+  }, [userId, enabled])
+
+  useEffect(() => {
+    fetchUser()
+  }, [fetchUser])
+
+  return { user, isLoading, error, refetch: fetchUser }
+}
+```
+
+## Requirements
+
+- TypeScript with proper types
+- Return type interface defined
+- Memoized callbacks with useCallback
+- Proper dependency arrays
+- Error state handling
+- Loading state handling
+
+## Naming Convention
+
+- Prefix with `use`
+- Descriptive name: `useUser`, `useAuth`, `useLocalStorage`
+- Options parameter for configuration
+- Return object with named properties
+
+## TanStack Query Pattern
+
+```typescript
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+
+export function useUser(userId: string) {
+  return useQuery({
+    queryKey: ['user', userId],
+    queryFn: () => fetchUser(userId),
+    enabled: !!userId,
+  })
+}
+
+export function useUpdateUser() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: updateUser,
+    onSuccess: (data) => {
+      queryClient.invalidateQueries({ queryKey: ['user', data.id] })
+    },
+  })
+}
+```
+
+## Common Hooks
+
+### useLocalStorage
+
+```typescript
+export function useLocalStorage<T>(key: string, initialValue: T) {
+  const [storedValue, setStoredValue] = useState<T>(() => {
+    if (typeof window === 'undefined') return initialValue
+    try {
+      const item = window.localStorage.getItem(key)
+      return item ? JSON.parse(item) : initialValue
+    } catch {
+      return initialValue
+    }
+  })
+
+  const setValue = useCallback((value: T | ((val: T) => T)) => {
+    setStoredValue(prev => {
+      const newValue = value instanceof Function ? value(prev) : value
+      window.localStorage.setItem(key, JSON.stringify(newValue))
+      return newValue
+    })
+  }, [key])
+
+  return [storedValue, setValue] as const
+}
+```
+
+## Forbidden Patterns
+
+- Missing dependency arrays
+- Non-memoized callbacks
+- Any type
+- Missing error handling
+- Side effects outside useEffect

package/packs/nextjs/skills/accessibility-validator/SKILL.md

@@ -0,0 +1,445 @@
+---
+name: react-accessibility-validator
+description: Automatically validate React/Next.js components meet WCAG 2.1 AA standards. Use when creating components, forms, buttons, modals, navigation, or any interactive UI elements.
+---
+
+# Accessibility Validator
+
+Auto-enforces WCAG 2.1 AA accessibility standards for all React/Next.js components.
+
+## Activation Triggers
+
+This skill activates when:
+- Creating React/Next.js components
+- Building forms, buttons, modals, navigation
+- Adding interactive elements
+- Mentioning "component", "UI", "form", "button"
+- Creating pages or layouts
+- Working on user-facing features
+
+## WCAG 2.1 AA Requirements (MANDATORY)
+
+All components MUST meet:
+- ✅ **Keyboard navigation** - All interactive elements focusable and usable via keyboard
+- ✅ **Semantic HTML** - Proper HTML elements and ARIA attributes
+- ✅ **Color contrast** - 4.5:1 for normal text, 3:1 for large text
+- ✅ **Screen reader support** - All content accessible to assistive technologies
+- ✅ **Focus management** - Visible focus indicators, logical tab order
+- ✅ **Form accessibility** - Labels, error announcements, help text
+
+## Auto-Validation Process
+
+### Step 1: Detect Component Creation
+
+When detecting component being written:
+
+```tsx
+// Component without accessibility
+function LoginButton({ onClick }) {
+  return <div onClick={onClick}>Login</div>  // ❌ Multiple issues!
+}
+```
+
+### Step 2: Run Accessibility Checklist
+
+Verify:
+1. ❌ Using div instead of button (semantic HTML)
+2. ❌ No keyboard support (only onClick, no onKeyDown)
+3. ❌ Not focusable (div not in tab order)
+4. ❌ No ARIA attributes
+5. ❌ No focus styles
+
+### Step 3: Auto-Fix Violations
+
+**Before (Inaccessible):**
+```tsx
+function LoginButton({ onClick }) {
+  return <div onClick={onClick}>Login</div>
+}
+```
+
+**After (Accessible):**
+```tsx
+function LoginButton({ onClick }) {
+  return (
+    <button
+      onClick={onClick}
+      type="button"
+      className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2"
+    >
+      Login
+    </button>
+  )
+}
+```
+
+### Step 4: Explain Fixes
+
+> **Accessibility Violations Fixed**
+>
+> **Changes:**
+> 1. ✅ Changed `<div>` to `<button>` (semantic HTML)
+> 2. ✅ Added `type="button"` (prevents form submission)
+> 3. ✅ Button is now keyboard accessible (Enter/Space keys work)
+> 4. ✅ Automatically focusable (in tab order)
+> 5. ✅ Added visible focus ring (focus:ring-2)
+>
+> **Why:**
+> - Buttons are natively accessible to keyboard and screen readers
+> - Focus ring shows keyboard users where they are
+> - Proper semantics help assistive technologies
+
+## Common Accessibility Patterns
+
+### Pattern 1: Buttons vs Links
+
+```tsx
+// ❌ WRONG - div as button
+<div onClick={handleClick}>Click me</div>
+
+// ❌ WRONG - link as button
+<a href="#" onClick={handleClick}>Click me</a>
+
+// ✅ CORRECT - button for actions
+<button onClick={handleClick} type="button">
+  Click me
+</button>
+
+// ✅ CORRECT - link for navigation
+<Link href="/page">Go to page</Link>
+```
+
+### Pattern 2: Form Labels
+
+```tsx
+// ❌ WRONG - no label
+<input type="email" placeholder="Email" />
+
+// ❌ WRONG - placeholder as label (insufficient)
+<input type="email" placeholder="Enter your email" />
+
+// ✅ CORRECT - explicit label
+<label htmlFor="email" className="block text-sm font-medium">
+  Email Address
+</label>
+<input
+  id="email"
+  type="email"
+  className="mt-1 block w-full rounded-md border-gray-300"
+  aria-required="true"
+/>
+
+// ✅ CORRECT - with error handling
+<label htmlFor="email" className="block text-sm font-medium">
+  Email Address
+</label>
+<input
+  id="email"
+  type="email"
+  aria-invalid={!!errors.email}
+  aria-describedby={errors.email ? "email-error" : undefined}
+/>
+{errors.email && (
+  <p id="email-error" className="mt-1 text-sm text-red-600" role="alert">
+    {errors.email.message}
+  </p>
+)}
+```
+
+### Pattern 3: Modal Dialogs
+
+```tsx
+// ✅ CORRECT - Accessible modal
+import { Dialog } from '@headlessui/react'
+
+function Modal({ isOpen, onClose, title, children }) {
+  return (
+    <Dialog
+      open={isOpen}
+      onClose={onClose}
+      className="relative z-50"
+    >
+      {/* Backdrop */}
+      <div className="fixed inset-0 bg-black/30" aria-hidden="true" />
+
+      {/* Modal */}
+      <div className="fixed inset-0 flex items-center justify-center p-4">
+        <Dialog.Panel className="bg-white rounded-lg p-6 max-w-md">
+          <Dialog.Title className="text-lg font-semibold">
+            {title}
+          </Dialog.Title>
+
+          <div className="mt-4">
+            {children}
+          </div>
+
+          <button
+            onClick={onClose}
+            className="mt-4 px-4 py-2 bg-gray-200 rounded"
+            aria-label="Close dialog"
+          >
+            Close
+          </button>
+        </Dialog.Panel>
+      </div>
+    </Dialog>
+  )
+}
+```
+
+### Pattern 4: Icon Buttons
+
+```tsx
+// ❌ WRONG - no accessible name
+<button>
+  <XIcon />
+</button>
+
+// ✅ CORRECT - with aria-label
+<button aria-label="Close" type="button">
+  <XIcon className="h-5 w-5" aria-hidden="true" />
+</button>
+
+// ✅ CORRECT - with visually hidden text
+<button type="button" className="relative">
+  <span className="sr-only">Close</span>
+  <XIcon className="h-5 w-5" aria-hidden="true" />
+</button>
+```
+
+### Pattern 5: Loading States
+
+```tsx
+// ❌ WRONG - no screen reader announcement
+{isLoading && <Spinner />}
+
+// ✅ CORRECT - with live region
+{isLoading && (
+  <div role="status" aria-live="polite">
+    <Spinner />
+    <span className="sr-only">Loading...</span>
+  </div>
+)}
+```
+
+### Pattern 6: Images
+
+```tsx
+// ❌ WRONG - no alt text
+<img src="/logo.png" />
+
+// ✅ CORRECT - with alt text
+<img src="/logo.png" alt="Company Logo" />
+
+// ✅ CORRECT - decorative image
+<img src="/decoration.png" alt="" aria-hidden="true" />
+```
+
+## Keyboard Navigation Checklist
+
+For every component, verify:
+
+- ✅ All interactive elements are focusable (button, a, input, etc.)
+- ✅ Tab order is logical (follows visual flow)
+- ✅ Focus is visible (outline, ring, or custom indicator)
+- ✅ No keyboard traps (can escape from all UI)
+- ✅ Enter/Space work on buttons
+- ✅ Escape closes modals/dropdowns
+- ✅ Arrow keys work in lists/menus
+
+## Color Contrast Requirements
+
+Check all text meets minimum contrast:
+
+```tsx
+// ❌ WRONG - insufficient contrast (2.5:1)
+<p className="text-gray-400 bg-white">Low contrast text</p>
+
+// ✅ CORRECT - good contrast (7:1)
+<p className="text-gray-900 bg-white">High contrast text</p>
+
+// ✅ CORRECT - large text can be 3:1
+<h1 className="text-2xl text-gray-600 bg-white">Large heading</h1>
+```
+
+**Minimum Ratios:**
+- Normal text (< 18pt): 4.5:1
+- Large text (≥ 18pt or bold ≥ 14pt): 3:1
+- UI components: 3:1
+
+## Screen Reader Support
+
+### Landmark Regions
+
+```tsx
+// ✅ CORRECT - proper landmarks
+<header role="banner">
+  <nav role="navigation" aria-label="Main navigation">
+    {/* nav items */}
+  </nav>
+</header>
+
+<main role="main">
+  {/* main content */}
+</main>
+
+<aside role="complementary" aria-label="Related content">
+  {/* sidebar */}
+</aside>
+
+<footer role="contentinfo">
+  {/* footer */}
+</footer>
+```
+
+### ARIA Labels
+
+```tsx
+// ✅ CORRECT - descriptive labels
+<button aria-label="Add item to cart">
+  <PlusIcon aria-hidden="true" />
+</button>
+
+<nav aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Home</a></li>
+    <li aria-current="page">Products</li>
+  </ol>
+</nav>
+```
+
+### Live Regions
+
+```tsx
+// ✅ CORRECT - announce changes
+<div role="alert" aria-live="assertive">
+  Error: Please fill in all required fields
+</div>
+
+<div role="status" aria-live="polite">
+  5 items in cart
+</div>
+```
+
+## Focus Management
+
+```tsx
+'use client'
+import { useEffect, useRef } from 'react'
+
+function Modal({ isOpen, title }) {
+  const titleRef = useRef<HTMLHeadingElement>(null)
+
+  // Focus title when modal opens
+  useEffect(() => {
+    if (isOpen && titleRef.current) {
+      titleRef.current.focus()
+    }
+  }, [isOpen])
+
+  return (
+    <div role="dialog" aria-modal="true">
+      <h2 ref={titleRef} tabIndex={-1} className="outline-none">
+        {title}
+      </h2>
+      {/* content */}
+    </div>
+  )
+}
+```
+
+## Testing Recommendations
+
+Suggest automated tests:
+
+```tsx
+import { render } from '@testing-library/react'
+import { axe, toHaveNoViolations } from 'jest-axe'
+
+expect.extend(toHaveNoViolations)
+
+test('LoginButton has no accessibility violations', async () => {
+  const { container } = render(<LoginButton onClick={() => {}} />)
+  const results = await axe(container)
+  expect(results).toHaveNoViolations()
+})
+```
+
+## Common Violations Checked
+
+### Missing Labels
+- Form inputs without labels
+- Icon buttons without aria-label
+- Images without alt text
+
+### Poor Semantics
+- Divs instead of buttons
+- Links instead of buttons
+- Missing heading hierarchy
+
+### Keyboard Issues
+- Elements not in tab order
+- Missing focus indicators
+- Keyboard traps
+
+### Screen Reader Issues
+- Missing ARIA labels
+- Incorrect ARIA roles
+- No live region announcements
+
+### Color Issues
+- Insufficient contrast
+- Color-only information
+- Missing text alternatives
+
+## Integration with Tailwind
+
+```tsx
+// Utility class for screen reader only text
+<span className="sr-only">Accessible description</span>
+
+// Focus ring utilities
+<button className="focus:outline-none focus:ring-2 focus:ring-blue-500">
+  Click me
+</button>
+
+// High contrast text
+<p className="text-gray-900 dark:text-gray-100">
+  Good contrast in both modes
+</p>
+```
+
+## Success Criteria
+
+✅ All interactive elements keyboard accessible
+✅ All images have alt text
+✅ All forms have labels
+✅ Color contrast ≥ 4.5:1 (normal text)
+✅ Proper semantic HTML used
+✅ ARIA attributes where needed
+✅ Focus indicators visible
+✅ Screen reader tested
+✅ Automated axe tests pass
+
+## Behavior
+
+**Proactive enforcement:**
+- Check accessibility without being asked
+- Fix violations immediately
+- Add ARIA attributes automatically
+- Explain WCAG criteria for each fix
+- Suggest automated tests
+
+**Never:**
+- Require explicit "check accessibility" request
+- Wait for accessibility audit
+- Just warn without fixing
+
+**Block completion if:**
+- Buttons are divs
+- Forms lack labels
+- Color contrast fails
+- Icon buttons lack accessible names
+- Images missing alt text
+
+This ensures every component is accessible from day one.