ux-toolkit 0.1.0

package/skills/interaction-patterns/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: interaction-patterns
+description: Micro-interaction patterns, loading states, feedback mechanisms, and animation guidelines
+license: MIT
+---
+
+# Interaction Design Patterns
+
+## Micro-interaction Anatomy
+
+Every micro-interaction has four parts:
+
+1. **Trigger** - What initiates it (user action or system event)
+2. **Rules** - What happens in response
+3. **Feedback** - Visual/audio response to the user
+4. **Loops/Modes** - What happens on repeat or over time
+
+## Feedback Timing
+
+| Response Time | User Perception | Guidance |
+|---------------|-----------------|----------|
+| <100ms | Instant | No indicator needed |
+| 100-300ms | Slight delay | Optional subtle feedback |
+| 300-1000ms | Noticeable | Show loading indicator |
+| 1-5s | Waiting | Show progress or skeleton |
+| >5s | Long wait | Show progress + estimated time |
+
+## Loading State Patterns
+
+### Skeleton Screens (Preferred)
+Best for: Content with predictable layout
+
+```css
+.skeleton {
+  background: linear-gradient(
+    90deg,
+    #f0f0f0 25%,
+    #e0e0e0 50%,
+    #f0f0f0 75%
+  );
+  background-size: 200% 100%;
+  animation: shimmer 1.5s infinite;
+}
+
+@keyframes shimmer {
+  0% { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .skeleton {
+    animation: none;
+    background: #e0e0e0;
+  }
+}
+```
+
+### Spinner
+Best for: Short operations, unknown duration
+
+- Use for actions <3 seconds
+- Center within the loading area
+- Include text for longer waits ("Loading...")
+
+### Progress Bar
+Best for: Determinate operations
+
+- Show percentage or steps completed
+- Move smoothly, never backwards
+- Include text description of current step
+
+### Optimistic UI
+Best for: High-confidence operations
+
+- Update UI immediately before server confirms
+- Show subtle pending indicator
+- Revert gracefully on failure
+
+## Button States
+
+| State | Visual Treatment | Timing |
+|-------|------------------|--------|
+| Default | Base style | - |
+| Hover | Subtle highlight (5-10% lighter/darker) | Immediate |
+| Focus | Visible ring/outline (2px+) | Immediate |
+| Active | Pressed appearance (slight scale/shadow) | Immediate |
+| Loading | Spinner replaces or joins text | During operation |
+| Disabled | Reduced opacity (50-60%), no pointer | - |
+| Success | Brief green flash (optional) | 1-2s then reset |
+
+### Button Loading Pattern
+```tsx
+<button disabled={isLoading}>
+  {isLoading ? (
+    <>
+      <Spinner className="mr-2" />
+      Saving...
+    </>
+  ) : (
+    'Save'
+  )}
+</button>
+```
+
+## Form Interactions
+
+### Validation Timing
+| Approach | When | Best For |
+|----------|------|----------|
+| On change (debounced) | As user types | Real-time feedback, username availability |
+| On blur | When leaving field | Most form fields |
+| On submit | Form submission | Final validation |
+
+### Input States
+- **Default**: Ready for input
+- **Focused**: Active, ready for input
+- **Filled**: Has value, not focused
+- **Error**: Invalid value, show message
+- **Success**: Valid value (optional)
+- **Disabled**: Not editable
+
+### Error Message Pattern
+```html
+<div class="form-field">
+  <label for="email">Email</label>
+  <input 
+    id="email"
+    type="email"
+    aria-invalid="true"
+    aria-describedby="email-error"
+  />
+  <span id="email-error" class="error" role="alert">
+    Please enter a valid email address
+  </span>
+</div>
+```
+
+## Animation Guidelines
+
+### Principles
+1. **Purposeful** - Guides attention, communicates meaning
+2. **Subtle** - Enhances, doesn't distract
+3. **Fast** - 150-300ms for micro-interactions
+4. **Smooth** - 60fps, no jank
+5. **Respectful** - Honors `prefers-reduced-motion`
+
+### Easing Functions
+| Easing | Use Case |
+|--------|----------|
+| ease-out | Elements entering (fast start, slow end) |
+| ease-in | Elements exiting (slow start, fast end) |
+| ease-in-out | Elements moving within view |
+| linear | Progress indicators, loading |
+
+### Duration Guidelines
+| Animation Type | Duration |
+|----------------|----------|
+| Micro-interaction | 100-200ms |
+| State change | 150-300ms |
+| Page transition | 300-500ms |
+| Complex animation | 500-1000ms |
+
+### Reduced Motion
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+## Error Handling UX
+
+### Principles
+1. **Prevent first** - Validate before errors occur
+2. **Be specific** - What exactly went wrong
+3. **Be helpful** - How to fix it
+4. **Be kind** - Don't blame the user
+5. **Preserve work** - Never lose user input
+
+### Error Message Components
+1. **What happened** - Clear description of the problem
+2. **Why it happened** - Context if helpful
+3. **What to do** - Specific recovery action
+
+### Error Display Patterns
+
+**Inline (field-level)**
+- Show next to the problematic field
+- Use for form validation
+- Red border + error message below
+
+**Toast (transient)**
+- Auto-dismiss after 5-10 seconds
+- Use for non-critical errors
+- Include dismiss button
+
+**Banner (persistent)**
+- Show at top of page/section
+- Use for page-level issues
+- Stays until resolved
+
+**Modal (blocking)**
+- Use sparingly for critical errors
+- Require acknowledgment
+- Provide clear action path
+
+## Optimistic UI Pattern
+
+### When to Use
+- Toggle states (like, bookmark)
+- Simple text edits
+- Reordering items
+- Adding to lists
+
+### When to Avoid
+- Financial transactions
+- Irreversible actions
+- Complex server validation
+- Multi-step processes
+
+### Implementation
+```typescript
+async function toggleLike(itemId: string) {
+  // 1. Optimistically update UI
+  setLiked(true);
+  
+  try {
+    // 2. Send to server
+    await api.like(itemId);
+  } catch (error) {
+    // 3. Revert on failure
+    setLiked(false);
+    showError('Failed to save');
+  }
+}
+```
+
+## Notification Patterns
+
+### Types
+| Type | Duration | Dismissible | Use |
+|------|----------|-------------|-----|
+| Success | 3-5s | Yes | Confirmation of action |
+| Info | 5-10s | Yes | Neutral information |
+| Warning | Persistent | Yes | Requires attention |
+| Error | Persistent | Yes | Problem occurred |
+
+### Placement
+- **Top right** - Most common, notifications
+- **Top center** - Important alerts
+- **Bottom center** - Mobile, snackbars
+- **Inline** - Context-specific feedback

package/skills/mobile-responsive-ux/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: mobile-responsive-ux
+description: Mobile UX patterns including touch targets, gestures, responsive design, and mobile-specific considerations
+license: MIT
+---
+
+# Mobile & Responsive UX
+
+## Touch Target Sizes
+
+| Standard | Size | Notes |
+|----------|------|-------|
+| WCAG 2.2 AA | 24×24px | Absolute minimum |
+| Apple HIG | 44×44px | Recommended minimum |
+| Material Design | 48×48px | Recommended minimum |
+| Comfortable | 48×48px+ | Best for accessibility |
+
+### Spacing Between Targets
+- Minimum: 8px between touch targets
+- Recommended: 16px for comfortable tapping
+- Critical actions: Extra spacing to prevent mis-taps
+
+## Mobile Navigation Patterns
+
+### Bottom Navigation (Recommended)
+Best for: 3-5 primary destinations
+
+**Guidelines:**
+- Maximum 5 items
+- Icon + text label for each
+- Highlight active state clearly
+- Most important items in thumb-reach zone
+
+**Thumb Zone (Right-handed)**
+```
+┌─────────────────┐
+│  Hard to reach  │
+│                 │
+│  Comfortable    │
+│                 │
+│  Easy to reach  │
+└─────────────────┘
+```
+
+### Hamburger Menu
+Best for: Secondary navigation, settings
+
+**Guidelines:**
+- Use clear ☰ icon or "Menu" label
+- Full-screen overlay on mobile
+- Easy close (X button + tap outside)
+- Remember scroll position
+
+### Tab Bar
+Best for: Parallel content sections
+
+**Guidelines:**
+- Maximum 5 tabs
+- Scrollable if more needed
+- Clear active state
+- Consider icons + text
+
+## Gesture Patterns
+
+| Gesture | Common Use | Consider |
+|---------|------------|----------|
+| Tap | Select, activate | Primary interaction |
+| Long press | Context menu, select mode | Discoverable alternative needed |
+| Swipe horizontal | Delete, archive, navigation | Provide visual hint |
+| Swipe vertical | Refresh, dismiss, scroll | Pull-to-refresh standard |
+| Pinch | Zoom in/out | Images, maps |
+| Double tap | Zoom, like | Secondary action |
+| Drag | Reorder, move | Provide handle affordance |
+
+### Gesture Best Practices
+- Always provide button alternative for gestures
+- Add visual hints for available gestures
+- Use standard platform conventions
+- Provide haptic feedback when appropriate
+
+## Responsive Design Checklist
+
+### Content
+- [ ] Text readable without zooming (16px+ base)
+- [ ] Images scale appropriately
+- [ ] No horizontal scrolling required
+- [ ] Tables adapt or scroll horizontally
+- [ ] Long words break appropriately
+
+### Interaction
+- [ ] Touch targets ≥44px
+- [ ] Adequate spacing between targets
+- [ ] Forms usable with on-screen keyboard
+- [ ] Dropdowns have mobile-friendly alternatives
+- [ ] Date pickers use native when possible
+
+### Layout
+- [ ] Single column on mobile
+- [ ] Critical content above fold
+- [ ] Navigation accessible
+- [ ] Fixed headers not too tall
+- [ ] Bottom nav in thumb zone
+
+## Mobile-First CSS
+
+```css
+/* Base: Mobile styles */
+.container {
+  padding: 16px;
+  font-size: 16px;
+}
+
+.grid {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+/* Tablet: 768px+ */
+@media (min-width: 768px) {
+  .container {
+    padding: 24px;
+  }
+  
+  .grid {
+    flex-direction: row;
+    flex-wrap: wrap;
+  }
+  
+  .grid-item {
+    flex: 0 0 calc(50% - 8px);
+  }
+}
+
+/* Desktop: 1024px+ */
+@media (min-width: 1024px) {
+  .container {
+    padding: 32px;
+    max-width: 1200px;
+    margin: 0 auto;
+  }
+  
+  .grid-item {
+    flex: 0 0 calc(33.333% - 11px);
+  }
+}
+```
+
+## Mobile Form UX
+
+### Input Types
+| Data | Input Type | Keyboard |
+|------|------------|----------|
+| Email | `type="email"` | @ and .com keys |
+| Phone | `type="tel"` | Number pad |
+| Number | `type="number"` | Number pad |
+| URL | `type="url"` | .com and / keys |
+| Search | `type="search"` | Search button |
+| Date | `type="date"` | Date picker |
+
+### Form Best Practices
+- Use large touch targets for inputs
+- Show inline validation
+- Enable autocomplete (`autocomplete` attribute)
+- Use appropriate `inputmode` for custom keyboards
+- Avoid dropdowns when possible (use segmented controls)
+- Group related fields
+- Show keyboard-appropriate labels
+
+### Keyboard Handling
+```html
+<input
+  type="text"
+  inputmode="numeric"
+  pattern="[0-9]*"
+  autocomplete="cc-number"
+  enterkeyhint="next"
+/>
+```
+
+## Safe Areas
+
+Handle notches, home indicators, and rounded corners:
+
+```css
+.app-container {
+  padding-top: env(safe-area-inset-top);
+  padding-right: env(safe-area-inset-right);
+  padding-bottom: env(safe-area-inset-bottom);
+  padding-left: env(safe-area-inset-left);
+}
+
+/* For fixed bottom navigation */
+.bottom-nav {
+  padding-bottom: calc(16px + env(safe-area-inset-bottom));
+}
+```
+
+## Mobile Performance UX
+
+### Image Optimization
+```html
+<img
+  src="image-800.jpg"
+  srcset="
+    image-400.jpg 400w,
+    image-800.jpg 800w,
+    image-1200.jpg 1200w
+  "
+  sizes="(max-width: 600px) 100vw, 50vw"
+  loading="lazy"
+  alt="Description"
+/>
+```
+
+### Lazy Loading
+- Images below fold: `loading="lazy"`
+- Iframes: `loading="lazy"`
+- Heavy components: Dynamic import with Suspense
+
+### Perceived Performance
+- Show skeleton screens immediately
+- Progressive image loading (blur-up)
+- Optimistic UI for common actions
+- Prefetch likely next pages
+
+## Offline & Slow Network
+
+### Offline States
+- Clear "offline" indicator
+- Cache critical content
+- Queue actions for sync
+- Show last updated timestamp
+
+### Slow Network Handling
+- Skeleton screens
+- Lower quality images first
+- Retry failed requests
+- Show progress for large uploads
+
+## Mobile Testing Checklist
+
+### Device Testing
+- [ ] Test on actual devices (not just emulators)
+- [ ] Test on different screen sizes
+- [ ] Test in portrait and landscape
+- [ ] Test with different text sizes (accessibility)
+- [ ] Test with one-handed use
+
+### Network Testing
+- [ ] Test on slow 3G
+- [ ] Test offline mode
+- [ ] Test intermittent connection
+- [ ] Test large file uploads
+
+### Input Testing
+- [ ] Test with on-screen keyboard
+- [ ] Test keyboard dismissal
+- [ ] Test with voice input
+- [ ] Test copy/paste