ux-toolkit 0.1.0

package/skills/react-ux-patterns/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: react-ux-patterns
+description: React and Next.js specific UX patterns including state management, data fetching, and component patterns
+license: MIT
+---
+
+# React UX Best Practices
+
+## Loading States
+
+### Suspense Pattern
+```tsx
+import { Suspense } from 'react';
+
+<Suspense fallback={<Skeleton />}>
+  <DataComponent />
+</Suspense>
+```
+
+### Query Hook Pattern
+```tsx
+const { data, isLoading, error } = useQuery({
+  queryKey: ['items'],
+  queryFn: fetchItems,
+});
+
+if (isLoading) return <Skeleton />;
+if (error) return <ErrorState error={error} onRetry={refetch} />;
+return <ItemList items={data} />;
+```
+
+### Deferred Loading
+```tsx
+import { useDeferredValue } from 'react';
+
+function SearchResults({ query }) {
+  const deferredQuery = useDeferredValue(query);
+  const isStale = query !== deferredQuery;
+  
+  return (
+    <div style={{ opacity: isStale ? 0.7 : 1 }}>
+      <Results query={deferredQuery} />
+    </div>
+  );
+}
+```
+
+## Form Patterns
+
+### Controlled Form with Validation
+```tsx
+import { useForm } from 'react-hook-form';
+
+function ContactForm() {
+  const { 
+    register, 
+    handleSubmit, 
+    formState: { errors, isSubmitting } 
+  } = useForm();
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <label htmlFor="email">Email</label>
+      <input
+        id="email"
+        type="email"
+        aria-invalid={errors.email ? 'true' : 'false'}
+        aria-describedby={errors.email ? 'email-error' : undefined}
+        {...register('email', { 
+          required: 'Email is required',
+          pattern: {
+            value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i,
+            message: 'Invalid email address'
+          }
+        })}
+      />
+      {errors.email && (
+        <span id="email-error" role="alert">
+          {errors.email.message}
+        </span>
+      )}
+      
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? 'Sending...' : 'Submit'}
+      </button>
+    </form>
+  );
+}
+```
+
+### Validation Timing
+| Event | Use Case |
+|-------|----------|
+| onChange | Real-time feedback (debounce 300ms+) |
+| onBlur | Field-level validation on exit |
+| onSubmit | Final validation before submission |
+
+## Optimistic Updates
+
+### With React Query
+```tsx
+const mutation = useMutation({
+  mutationFn: updateItem,
+  onMutate: async (newData) => {
+    await queryClient.cancelQueries({ queryKey: ['items'] });
+    const previous = queryClient.getQueryData(['items']);
+    
+    queryClient.setQueryData(['items'], (old) =>
+      old.map((item) =>
+        item.id === newData.id ? { ...item, ...newData } : item
+      )
+    );
+    
+    return { previous };
+  },
+  onError: (err, newData, context) => {
+    queryClient.setQueryData(['items'], context.previous);
+    toast.error('Failed to update');
+  },
+  onSettled: () => {
+    queryClient.invalidateQueries({ queryKey: ['items'] });
+  },
+});
+```
+
+### Use Cases for Optimistic UI
+- Toggle states (like, bookmark, follow)
+- Simple text edits
+- Reordering items
+- Adding/removing from lists
+
+### Avoid Optimistic UI When
+- Complex server validation required
+- Financial transactions
+- Irreversible actions
+- Multi-step processes
+
+## Focus Management
+
+### Modal Focus Trap
+```tsx
+import { useRef, useEffect } from 'react';
+
+function Modal({ isOpen, onClose, children }) {
+  const modalRef = useRef(null);
+  const previousFocus = useRef(null);
+
+  useEffect(() => {
+    if (isOpen) {
+      previousFocus.current = document.activeElement;
+      modalRef.current?.focus();
+    }
+    return () => {
+      previousFocus.current?.focus();
+    };
+  }, [isOpen]);
+
+  return isOpen ? (
+    <div
+      ref={modalRef}
+      role="dialog"
+      aria-modal="true"
+      tabIndex={-1}
+      onKeyDown={(e) => e.key === 'Escape' && onClose()}
+    >
+      {children}
+    </div>
+  ) : null;
+}
+```
+
+### Skip Link
+```tsx
+function SkipLink() {
+  return (
+    <a
+      href="#main-content"
+      className="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4"
+    >
+      Skip to main content
+    </a>
+  );
+}
+```
+
+## Announcements for Screen Readers
+
+### Live Region Hook
+```tsx
+import { useState, useCallback } from 'react';
+
+function useAnnounce() {
+  const [message, setMessage] = useState('');
+
+  const announce = useCallback((text, priority = 'polite') => {
+    setMessage('');
+    setTimeout(() => setMessage(text), 100);
+  }, []);
+
+  const Announcer = () => (
+    <div
+      role="status"
+      aria-live="polite"
+      aria-atomic="true"
+      className="sr-only"
+    >
+      {message}
+    </div>
+  );
+
+  return { announce, Announcer };
+}
+```
+
+## Error Boundaries
+
+### Functional Error Boundary
+```tsx
+import { ErrorBoundary } from 'react-error-boundary';
+
+function ErrorFallback({ error, resetErrorBoundary }) {
+  return (
+    <div role="alert">
+      <h2>Something went wrong</h2>
+      <pre>{error.message}</pre>
+      <button onClick={resetErrorBoundary}>Try again</button>
+    </div>
+  );
+}
+
+<ErrorBoundary
+  FallbackComponent={ErrorFallback}
+  onReset={() => queryClient.clear()}
+>
+  <App />
+</ErrorBoundary>
+```
+
+## Performance UX
+
+### Code Splitting
+```tsx
+import { lazy, Suspense } from 'react';
+
+const HeavyComponent = lazy(() => import('./HeavyComponent'));
+
+function App() {
+  return (
+    <Suspense fallback={<Skeleton />}>
+      <HeavyComponent />
+    </Suspense>
+  );
+}
+```
+
+### Image Optimization (Next.js)
+```tsx
+import Image from 'next/image';
+
+<Image
+  src="/hero.jpg"
+  alt="Hero image description"
+  width={1200}
+  height={600}
+  priority={isAboveFold}
+  placeholder="blur"
+  blurDataURL={blurPlaceholder}
+/>
+```
+
+### Virtualization for Long Lists
+```tsx
+import { useVirtualizer } from '@tanstack/react-virtual';
+
+function VirtualList({ items }) {
+  const parentRef = useRef(null);
+  
+  const virtualizer = useVirtualizer({
+    count: items.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 50,
+  });
+
+  return (
+    <div ref={parentRef} style={{ height: '400px', overflow: 'auto' }}>
+      <div style={{ height: virtualizer.getTotalSize() }}>
+        {virtualizer.getVirtualItems().map((virtualRow) => (
+          <div
+            key={virtualRow.key}
+            style={{
+              position: 'absolute',
+              top: virtualRow.start,
+              height: virtualRow.size,
+            }}
+          >
+            {items[virtualRow.index]}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## Reduced Motion Support
+
+```tsx
+function AnimatedComponent() {
+  const prefersReducedMotion = useMediaQuery(
+    '(prefers-reduced-motion: reduce)'
+  );
+
+  return (
+    <motion.div
+      animate={{ x: 100 }}
+      transition={{
+        duration: prefersReducedMotion ? 0 : 0.3,
+      }}
+    />
+  );
+}
+```
+
+### CSS Approach
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```

package/skills/ux-heuristics/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: ux-heuristics
+description: Nielsen's 10 usability heuristics with evaluation methodology and severity scoring
+license: MIT
+---
+
+# Usability Heuristics Evaluation
+
+## Nielsen's 10 Heuristics
+
+### 1. Visibility of System Status
+Keep users informed through timely feedback.
+
+**Check for:**
+- Loading states and progress indicators
+- Save/submit confirmations
+- Error notifications
+- Connection status indicators
+
+**Severity if missing:** High - users feel lost without feedback
+
+### 2. Match Between System and Real World
+Use familiar language and follow real-world conventions.
+
+**Check for:**
+- User-friendly terminology (not developer jargon)
+- Intuitive iconography
+- Logical information ordering
+- Cultural appropriateness
+
+**Severity if violated:** Medium-High
+
+### 3. User Control and Freedom
+Provide emergency exits and undo support.
+
+**Check for:**
+- Cancel buttons on forms/dialogs
+- Back navigation
+- Undo/redo functionality
+- Clear exit paths from workflows
+
+**Severity if missing:** High
+
+### 4. Consistency and Standards
+Follow platform conventions and internal patterns.
+
+**Check for:**
+- Consistent button styles and placement
+- Uniform terminology across screens
+- Standard interaction patterns (e.g., swipe to delete)
+- Platform-specific conventions (iOS HIG, Material Design)
+
+**Severity if violated:** Medium-High
+
+### 5. Error Prevention
+Prevent problems before they occur.
+
+**Check for:**
+- Confirmation dialogs for destructive actions
+- Input validation before submission
+- Constraints that prevent invalid states
+- Clear affordances for interactive elements
+
+**Severity if missing:** High for destructive actions
+
+### 6. Recognition Rather Than Recall
+Minimize memory load by making options visible.
+
+**Check for:**
+- Visible navigation and options
+- Contextual help and hints
+- Recent items and history
+- Autocomplete suggestions
+
+**Severity if violated:** Medium
+
+### 7. Flexibility and Efficiency of Use
+Provide accelerators for expert users.
+
+**Check for:**
+- Keyboard shortcuts
+- Customization options
+- Shortcuts for frequent actions
+- Power user features
+
+**Severity if missing:** Low-Medium
+
+### 8. Aesthetic and Minimalist Design
+Remove irrelevant or rarely needed information.
+
+**Check for:**
+- Information density (too much? too little?)
+- Visual clutter
+- Clear hierarchy
+- Purposeful use of color and typography
+
+**Severity if violated:** Medium
+
+### 9. Help Users Recognize, Diagnose, and Recover from Errors
+Provide clear error messages with solutions.
+
+**Check for:**
+- Human-readable error messages (not error codes)
+- Specific problem identification
+- Actionable recovery suggestions
+- Non-blaming tone
+
+**Severity if violated:** High
+
+### 10. Help and Documentation
+Provide searchable, task-focused help.
+
+**Check for:**
+- Help availability (tooltips, docs, FAQs)
+- Searchable documentation
+- Task-oriented guidance
+- Contextual help
+
+**Severity if missing:** Low-Medium
+
+## Severity Rating Scale
+
+| Rating | Label | Description | Action |
+|--------|-------|-------------|--------|
+| 0 | Not a problem | No usability issue | None |
+| 1 | Cosmetic | Minor visual issue | Fix if time permits |
+| 2 | Minor | Causes slight confusion | Low priority |
+| 3 | Major | Significantly impacts task completion | High priority |
+| 4 | Catastrophic | Prevents task completion | Must fix immediately |
+
+## Evaluation Process
+
+1. **Identify the scope** - Which screens/flows to evaluate
+2. **Review independently** - Evaluate each heuristic separately
+3. **Document issues** - Note location, heuristic violated, severity
+4. **Calculate priority** - Frequency × Severity = Priority
+5. **Recommend fixes** - Provide specific, actionable solutions
+
+## Output Format
+
+For each issue found:
+
+```
+**Issue:** [Brief description]
+**Location:** [Screen/component/flow]
+**Heuristic:** [Number and name]
+**Severity:** [0-4]
+**Impact:** [How it affects users]
+**Recommendation:** [Specific fix]
+```

package/skills/visual-design-system/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: visual-design-system
+description: Visual design principles including layout, typography, color theory, and spacing systems
+license: MIT
+---
+
+# Visual Design System Principles
+
+## Visual Hierarchy
+
+Priority order: **Size > Color > Contrast > Position > Whitespace**
+
+### Typography Scale
+
+| Level | Size | Weight | Use |
+|-------|------|--------|-----|
+| Display | 48-72px | Bold | Hero headlines |
+| H1 | 32-48px | Bold | Page titles |
+| H2 | 24-32px | Semibold | Section headers |
+| H3 | 20-24px | Semibold | Subsections |
+| H4 | 18-20px | Medium | Card titles |
+| Body | 16-18px | Regular | Content |
+| Small | 14px | Regular | Captions, metadata |
+| Tiny | 12px | Regular | Labels, hints |
+
+### Typography Best Practices
+- Line height: 1.4-1.6 for body text
+- Line length: 50-75 characters optimal
+- Font families: Maximum 2-3 per design
+- Heading contrast: Darker than body text
+
+## 8pt Grid System
+
+Base unit: 8px (4px for fine adjustments)
+
+| Token | Value | Use |
+|-------|-------|-----|
+| space-0 | 0 | Reset |
+| space-1 | 4px | Tight spacing, icons |
+| space-2 | 8px | Inline elements, small gaps |
+| space-3 | 16px | Component padding |
+| space-4 | 24px | Card padding |
+| space-5 | 32px | Section spacing |
+| space-6 | 48px | Large sections |
+| space-7 | 64px | Page sections |
+| space-8 | 96px | Hero spacing |
+
+### Grid Alignment Checklist
+- [ ] All spacing uses 8px increments (4px for fine tuning)
+- [ ] Component padding is consistent
+- [ ] Margins between sections are uniform
+- [ ] Icons align to 4px grid
+
+## Color System
+
+### 60-30-10 Rule
+- **60%** Neutral/background colors
+- **30%** Secondary/surface colors
+- **10%** Accent colors (CTAs, highlights)
+
+### Semantic Color Tokens
+
+| Token | Purpose | Example Use |
+|-------|---------|-------------|
+| primary | Brand, main actions | Submit buttons, links |
+| secondary | Alternative actions | Cancel, secondary buttons |
+| success | Positive feedback | Success messages, completed |
+| warning | Caution states | Unsaved changes, warnings |
+| error | Problems | Validation errors, failures |
+| info | Neutral information | Tips, hints, help text |
+
+### Color Contrast Requirements
+| Use Case | Minimum Ratio | WCAG Level |
+|----------|---------------|------------|
+| Body text | 4.5:1 | AA |
+| Large text (18px+) | 3:1 | AA |
+| UI components | 3:1 | AA |
+| Enhanced | 7:1 | AAA |
+
+### Dark Mode Considerations
+- Invert semantic meanings carefully
+- Reduce pure white (#fff) to off-white
+- Adjust shadows to glows
+- Test contrast in both modes
+
+## Layout Patterns
+
+### Common Layouts
+
+**F-Pattern**
+- Best for: Text-heavy content
+- Eye movement: Left to right, then down left side
+- Place important content along the F
+
+**Z-Pattern**
+- Best for: Landing pages, minimal content
+- Eye movement: Top left → top right → bottom left → bottom right
+- Place CTA at end of Z
+
+**Card Grid**
+- Best for: Content collections, dashboards
+- Use consistent card sizes
+- Maintain gutters between cards
+
+**Split Screen**
+- Best for: Comparisons, form + preview
+- Balance visual weight
+- Consider responsive behavior
+
+### Container Widths
+| Size | Max Width | Use |
+|------|-----------|-----|
+| xs | 320px | Mobile narrow |
+| sm | 540px | Mobile |
+| md | 720px | Tablet |
+| lg | 960px | Desktop |
+| xl | 1140px | Large desktop |
+| 2xl | 1320px | Extra large |
+| full | 100% | Full bleed |
+
+## Responsive Design
+
+### Breakpoints
+| Name | Width | Typical Device |
+|------|-------|----------------|
+| xs | <576px | Phone portrait |
+| sm | ≥576px | Phone landscape |
+| md | ≥768px | Tablet |
+| lg | ≥992px | Desktop |
+| xl | ≥1200px | Large desktop |
+| 2xl | ≥1400px | Extra large |
+
+### Mobile-First CSS
+```css
+.element {
+  padding: 16px;
+}
+
+@media (min-width: 768px) {
+  .element {
+    padding: 24px;
+  }
+}
+
+@media (min-width: 1024px) {
+  .element {
+    padding: 32px;
+  }
+}
+```
+
+## Gestalt Principles
+
+### Proximity
+Elements close together are perceived as related.
+- Group related controls
+- Add space between unrelated items
+- Use whitespace to create sections
+
+### Similarity
+Similar elements are perceived as related.
+- Use consistent styling for similar functions
+- Differentiate distinct element types
+- Color, shape, size signal relationships
+
+### Continuity
+Elements arranged in a line are perceived as related.
+- Align elements along invisible lines
+- Use consistent alignment throughout
+- Guide the eye with visual flow
+
+### Closure
+The mind fills in gaps to complete shapes.
+- Incomplete elements can suggest meaning
+- Icons don't need full outlines
+- Whitespace can define boundaries
+
+## Design Review Checklist
+
+### Visual Hierarchy
+- [ ] Clear primary focal point
+- [ ] Logical reading order
+- [ ] Consistent heading levels
+- [ ] Appropriate text sizes
+
+### Spacing
+- [ ] Consistent padding within components
+- [ ] Consistent margins between sections
+- [ ] Adequate whitespace for breathing room
+- [ ] Touch targets ≥44px on mobile
+
+### Color
+- [ ] Follows 60-30-10 rule
+- [ ] Semantic colors used appropriately
+- [ ] Sufficient contrast ratios
+- [ ] Works in dark mode (if applicable)
+
+### Typography
+- [ ] Readable font sizes
+- [ ] Appropriate line height
+- [ ] Good line length (50-75 chars)
+- [ ] Limited font families (2-3 max)
+
+### Alignment
+- [ ] Elements aligned to grid
+- [ ] Consistent left/center/right alignment
+- [ ] Visual balance across page
+- [ ] No orphaned elements