picasso-skill 1.5.1 → 2.0.0

package/references/sensory-design.md

@@ -0,0 +1,369 @@
+# Sensory Design Reference
+
+## Table of Contents
+1. UI Sound Design
+2. Haptic Feedback
+3. Multi-Sensory Integration
+
+---
+
+## 1. UI Sound Design
+
+### Why Sound
+Sound provides confirmation that an action occurred, draws attention to important state changes, and adds personality to the interface. It is underused on the web but highly effective when applied with restraint.
+
+### Sourcing Sounds
+- **Kenney.nl** -- free CC0 game/UI sound packs. High quality, no attribution required.
+- **Freesound.org** -- filter by CC0 license for attribution-free use. Verify license on each clip.
+- **Tone.js synthesis** -- generate procedural sounds at runtime. No files to load. Good for simple tones, chimes, and click sounds. Use `Tone.Synth`, `Tone.MembraneSynth`, or `Tone.NoiseSynth` for UI feedback.
+- **Self-recorded** -- record short foley sounds and export as WAV/MP3 at 44.1kHz mono.
+
+For inline embedding, convert sounds to base64 data URIs to avoid CORS issues and runtime fetching. Each sound becomes a self-contained TypeScript module.
+
+```typescript
+// sounds/click-soft.ts
+export const clickSoftSound = "data:audio/wav;base64,UklGR...";
+```
+
+### The useSound Hook (Production-Ready)
+
+This hook handles AudioContext lifecycle (including the browser autoplay policy that blocks AudioContext until a user gesture), caches decoded buffers so each sound is fetched and decoded only once, and exposes volume control via a GainNode.
+
+```typescript
+// hooks/use-sound.ts
+import { useCallback, useEffect, useRef } from "react";
+
+// Shared AudioContext singleton -- one per page avoids resource waste.
+let sharedCtx: AudioContext | null = null;
+const bufferCache = new Map<string, AudioBuffer>();
+
+function getAudioContext(): AudioContext {
+  if (!sharedCtx) {
+    sharedCtx = new AudioContext();
+  }
+  return sharedCtx;
+}
+
+// Resume AudioContext on first user gesture (required by Chrome, Safari, Firefox).
+// Call this once at app root.
+export function initAudioOnGesture(): void {
+  const resume = () => {
+    const ctx = getAudioContext();
+    if (ctx.state === "suspended") {
+      ctx.resume();
+    }
+  };
+  const events = ["click", "touchstart", "keydown"] as const;
+  events.forEach((e) => document.addEventListener(e, resume, { once: false }));
+}
+
+interface UseSoundOptions {
+  volume?: number; // 0 to 1, default 0.4
+  /** For sound sprites: start offset in seconds */
+  offset?: number;
+  /** For sound sprites: duration in seconds */
+  duration?: number;
+}
+
+export function useSound(src: string, options: UseSoundOptions = {}) {
+  const { volume = 0.4, offset, duration } = options;
+  const gainRef = useRef<GainNode | null>(null);
+
+  const play = useCallback(async () => {
+    const ctx = getAudioContext();
+
+    // Resume if suspended (covers edge cases where gesture init missed)
+    if (ctx.state === "suspended") {
+      await ctx.resume();
+    }
+
+    // Fetch + decode only on first play, then cache
+    let buffer = bufferCache.get(src);
+    if (!buffer) {
+      const response = await fetch(src);
+      const arrayBuf = await response.arrayBuffer();
+      buffer = await ctx.decodeAudioData(arrayBuf);
+      bufferCache.set(src, buffer);
+    }
+
+    // GainNode for volume control
+    const gain = ctx.createGain();
+    gain.gain.value = volume;
+    gain.connect(ctx.destination);
+    gainRef.current = gain;
+
+    const source = ctx.createBufferSource();
+    source.buffer = buffer;
+    source.connect(gain);
+
+    if (offset !== undefined && duration !== undefined) {
+      source.start(0, offset, duration);
+    } else {
+      source.start(0);
+    }
+  }, [src, volume, offset, duration]);
+
+  const setVolume = useCallback(
+    (v: number) => {
+      if (gainRef.current) {
+        gainRef.current.gain.value = Math.max(0, Math.min(1, v));
+      }
+    },
+    []
+  );
+
+  return { play, setVolume } as const;
+}
+```
+
+### App Root Setup
+
+```tsx
+// app/layout.tsx or app entry
+import { initAudioOnGesture } from "@/hooks/use-sound";
+
+// Call once on mount
+useEffect(() => {
+  initAudioOnGesture();
+}, []);
+```
+
+### Basic Usage
+
+```tsx
+import { useSound } from "@/hooks/use-sound";
+import { clickSoftSound } from "@/sounds/click-soft";
+
+function SaveButton() {
+  const { play } = useSound(clickSoftSound, { volume: 0.3 });
+  return (
+    <button onClick={() => { play(); handleSave(); }}>
+      Save
+    </button>
+  );
+}
+```
+
+### Sound Sprite Pattern
+
+Pack multiple short sounds into a single audio file to reduce HTTP requests and simplify asset management. Reference each sound by its offset and duration within the file.
+
+```typescript
+// sounds/ui-sprite.ts
+export const uiSprite = "data:audio/wav;base64,UklGR...";
+
+// Offsets in seconds within the sprite file
+export const SPRITE_MAP = {
+  click:   { offset: 0.0,  duration: 0.08 },
+  success: { offset: 0.1,  duration: 0.15 },
+  error:   { offset: 0.3,  duration: 0.12 },
+  toggle:  { offset: 0.5,  duration: 0.06 },
+  whoosh:  { offset: 0.6,  duration: 0.20 },
+} as const;
+```
+
+```tsx
+import { useSound } from "@/hooks/use-sound";
+import { uiSprite, SPRITE_MAP } from "@/sounds/ui-sprite";
+
+function ToggleSwitch({ checked, onChange }: ToggleProps) {
+  const { play } = useSound(uiSprite, {
+    volume: 0.35,
+    offset: SPRITE_MAP.toggle.offset,
+    duration: SPRITE_MAP.toggle.duration,
+  });
+
+  return (
+    <button
+      role="switch"
+      aria-checked={checked}
+      onClick={() => { play(); onChange(!checked); }}
+    />
+  );
+}
+```
+
+### When to Use Sound
+- **Button clicks**: soft, short click sound (50-100ms)
+- **Success actions**: pleasant confirmation tone
+- **Notifications**: attention-getting but not alarming chime
+- **Errors**: subtle alert, not a harsh buzz
+- **Toggle switches**: satisfying mechanical click
+- **Transitions**: whoosh or swipe sound for page changes
+
+### Rules
+- Always provide a sound toggle in the UI (respect user preference)
+- Keep sounds under 200ms for UI interactions
+- Use the Web Audio API, not `<audio>` elements (lower latency)
+- Sound volume should be subtle by default (0.3-0.5 of max)
+- Never auto-play sounds on page load
+- Gate behind a user preference stored in localStorage or app settings
+- Pre-decode buffers when possible; never decode on every play
+
+---
+
+## 2. Haptic Feedback
+
+### The Vibration API (Android, some desktop browsers)
+
+```typescript
+// utils/haptics.ts
+export function hapticTap() {
+  navigator.vibrate?.(10);
+}
+
+export function hapticSuccess() {
+  navigator.vibrate?.([10, 50, 10]);
+}
+
+export function hapticError() {
+  navigator.vibrate?.(30);
+}
+
+export function hapticWarning() {
+  navigator.vibrate?.([10, 30, 10, 30, 10]);
+}
+```
+
+### iOS Haptic Considerations
+
+The Vibration API is not supported on iOS Safari. For web apps, iOS has no standard haptic API. Strategies for iOS haptic feedback:
+
+1. **Native bridge (Capacitor/React Native)** -- If the app runs in a native wrapper, call `UIImpactFeedbackGenerator` through the bridge. This provides the best haptics on iOS with three intensity levels: `.light`, `.medium`, `.heavy`.
+
+```typescript
+// For Capacitor-based apps
+import { Haptics, ImpactStyle } from "@capacitor/haptics";
+
+export async function hapticTapIOS() {
+  await Haptics.impact({ style: ImpactStyle.Light });
+}
+
+export async function hapticSuccessIOS() {
+  await Haptics.notification({ type: "success" });
+}
+```
+
+2. **Graceful degradation** -- For pure web apps on iOS, accept that haptics are unavailable. Never show broken behavior. Wrap all haptic calls behind a safe helper:
+
+```typescript
+export function haptic(pattern: number | number[]) {
+  if (typeof navigator !== "undefined" && "vibrate" in navigator) {
+    navigator.vibrate(pattern);
+  }
+  // On iOS Safari this is a no-op. The visual and audio
+  // feedback channels carry the interaction.
+}
+```
+
+### When to Use Haptics
+- **Button press confirmation**: 10ms pulse on touch
+- **Toggle switch**: 10ms pulse on state change
+- **Destructive action confirmation**: 30ms pulse before confirmation dialog
+- **Pull-to-refresh threshold**: 10ms pulse when the threshold is reached
+- **Drag and drop**: 10ms pulse on pickup and drop
+
+### Rules
+- Gate behind feature detection (`'vibrate' in navigator` or Capacitor availability)
+- Respect `prefers-reduced-motion` by disabling haptics when motion is reduced
+- Keep durations very short (10-30ms for taps, never longer than 100ms)
+- Do not use haptics for every interaction, only pivotal moments
+- Test on real hardware; emulators do not produce haptic feedback
+
+---
+
+## 3. Multi-Sensory Integration
+
+The strongest UI moments combine visual, auditory, and haptic feedback simultaneously. This triple feedback creates a moment of certainty that a single visual change cannot match. Reserve it for milestone moments: order placed, task completed, level achieved, payment confirmed.
+
+### Integration Principles
+1. **Synchronize channels** -- sound, haptic, and animation should fire at the same instant. Do not stagger them.
+2. **Match intensity** -- a subtle visual pulse pairs with a quiet click and a light tap. A big celebration pairs with a brighter chime and stronger vibration.
+3. **Degrade gracefully** -- if sound is muted, the visual and haptic still work. If haptics are unavailable, sound and visual carry it. Each channel must stand on its own.
+4. **Respect preferences** -- check `prefers-reduced-motion`, sound toggle state, and haptic toggle state independently.
+
+### Complete Example: Task Completion Feedback
+
+```tsx
+import { useCallback } from "react";
+import { motion, AnimatePresence } from "framer-motion";
+import { useSound } from "@/hooks/use-sound";
+import { uiSprite, SPRITE_MAP } from "@/sounds/ui-sprite";
+import { hapticSuccess, haptic } from "@/utils/haptics";
+import { CheckIcon } from "lucide-react";
+
+interface TaskCompleteButtonProps {
+  completed: boolean;
+  onComplete: () => void;
+  soundEnabled?: boolean;
+}
+
+export function TaskCompleteButton({
+  completed,
+  onComplete,
+  soundEnabled = true,
+}: TaskCompleteButtonProps) {
+  const { play } = useSound(uiSprite, {
+    volume: 0.4,
+    offset: SPRITE_MAP.success.offset,
+    duration: SPRITE_MAP.success.duration,
+  });
+
+  const prefersReducedMotion =
+    typeof window !== "undefined" &&
+    window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+  const handleComplete = useCallback(() => {
+    if (completed) return;
+
+    // Fire all three channels simultaneously
+    onComplete();
+    if (soundEnabled) play();
+    hapticSuccess();
+  }, [completed, onComplete, soundEnabled, play]);
+
+  return (
+    <button
+      onClick={handleComplete}
+      className="relative flex items-center gap-2 rounded-lg bg-zinc-900
+                 px-4 py-2 text-sm font-medium text-white
+                 transition-colors hover:bg-zinc-800
+                 disabled:opacity-50"
+      disabled={completed}
+    >
+      <AnimatePresence mode="wait">
+        {completed ? (
+          <motion.span
+            key="done"
+            initial={prefersReducedMotion ? {} : { scale: 0, opacity: 0 }}
+            animate={{ scale: 1, opacity: 1 }}
+            transition={{ type: "spring", stiffness: 500, damping: 25 }}
+            className="flex items-center gap-2 text-emerald-400"
+          >
+            <CheckIcon className="h-4 w-4" />
+            Done
+          </motion.span>
+        ) : (
+          <motion.span
+            key="complete"
+            exit={prefersReducedMotion ? {} : { scale: 0.8, opacity: 0 }}
+            transition={{ duration: 0.1 }}
+          >
+            Mark Complete
+          </motion.span>
+        )}
+      </AnimatePresence>
+    </button>
+  );
+}
+```
+
+### Timeline of a Multi-Sensory Moment
+
+| Time | Visual | Sound | Haptic |
+|------|--------|-------|--------|
+| 0ms | Button state changes, checkmark scales in with spring animation | Success chime begins (100-150ms clip) | Double-pulse fires: 10ms on, 50ms gap, 10ms on |
+| 150ms | Spring animation settles, color transition to emerald completes | Sound fades out naturally | Haptic complete |
+| 300ms | Final resting state | Silent | Idle |
+
+All three channels start at t=0 and resolve independently. The user perceives them as a single unified moment.

package/references/spatial-design.md

@@ -0,0 +1,176 @@
+# Spatial Design Reference
+
+## Table of Contents
+1. Spacing Scale
+2. Grid Systems
+3. Visual Hierarchy
+4. Whitespace
+5. Layout Patterns
+6. Common Mistakes
+
+---
+
+## 1. Spacing Scale
+
+Use a consistent spacing scale based on a 4px unit. Never use arbitrary values like 13px or 7px.
+
+```css
+:root {
+  --space-1: 0.25rem;   /* 4px  - tight inline gaps */
+  --space-2: 0.5rem;    /* 8px  - icon-to-text, compact lists */
+  --space-3: 0.75rem;   /* 12px - form field padding */
+  --space-4: 1rem;      /* 16px - standard element spacing */
+  --space-5: 1.25rem;   /* 20px - card padding */
+  --space-6: 1.5rem;    /* 24px - section padding */
+  --space-8: 2rem;      /* 32px - group separation */
+  --space-10: 2.5rem;   /* 40px - major section gaps */
+  --space-12: 3rem;     /* 48px - large section spacing */
+  --space-16: 4rem;     /* 64px - page-level spacing */
+  --space-20: 5rem;     /* 80px - hero-level breathing room */
+  --space-24: 6rem;     /* 96px - dramatic separation */
+}
+```
+
+### When to Use Which Size
+- **1-2 (4-8px)**: Internal component spacing (icon + label, badge padding)
+- **3-4 (12-16px)**: Component padding, list item spacing
+- **5-6 (20-24px)**: Card padding, form group margins
+- **8-10 (32-40px)**: Section separation within a page
+- **12-16 (48-64px)**: Major content blocks, above/below fold
+- **20-24 (80-96px)**: Hero areas, page-level breathing room
+
+---
+
+## 2. Grid Systems
+
+### CSS Grid Defaults
+```css
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+  gap: var(--space-6);
+}
+```
+
+### 12-Column Grid
+For dashboard and editorial layouts:
+```css
+.page-grid {
+  display: grid;
+  grid-template-columns: repeat(12, 1fr);
+  gap: var(--space-6);
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 0 var(--space-6);
+}
+```
+
+### Asymmetric Grids
+For editorial and portfolio layouts, break the 12-column grid:
+```css
+.editorial-grid {
+  display: grid;
+  grid-template-columns: 2fr 1fr;  /* 2:1 ratio */
+  gap: var(--space-8);
+}
+.portfolio-grid {
+  display: grid;
+  grid-template-columns: 3fr 2fr;  /* golden-ish ratio */
+  gap: var(--space-6);
+}
+```
+
+---
+
+## 3. Visual Hierarchy
+
+Hierarchy is established through size, weight, color, and space. Not all four at once. Pick two.
+
+### Hierarchy Techniques (in order of strength)
+1. **Size difference**: The fastest way to establish priority
+2. **Weight difference**: Bold vs. regular within the same size
+3. **Color contrast**: Primary vs. secondary text color
+4. **Spatial separation**: More space around important elements
+5. **Position**: Top-left gets seen first (in LTR languages)
+
+### Rules
+- If everything is bold, nothing is bold. Limit bold to headings and key data points.
+- If everything is the same size, the eye has nowhere to land. Vary size by at least 1.5x between hierarchy levels.
+- Use secondary/tertiary text colors for supporting information (timestamps, metadata, helper text).
+- Reduce visual weight of labels and increase weight of values in data-heavy UIs.
+
+---
+
+## 4. Whitespace
+
+Whitespace is not wasted space. It is a design element.
+
+### Internal vs. External Spacing
+- **Internal**: Padding inside a component (card padding, button padding). Relates to the component's own content.
+- **External**: Margin between components. Relates to the component's relationship with siblings.
+
+### Gestalt Grouping
+Elements that are closer together are perceived as related. Use tighter spacing within groups and wider spacing between groups. The ratio between intra-group and inter-group spacing should be at least 2:1 (e.g., 8px within, 24px between).
+
+### Generous vs. Dense
+- **Generous**: Marketing pages, portfolios, editorial content. Use 80-120px between major sections.
+- **Dense**: Dashboards, admin panels, data tables. Use 16-32px between sections but maintain consistent rhythm.
+
+---
+
+## 5. Layout Patterns
+
+### Centered Content
+Max-width container with auto margins. Standard max-widths: 640px (narrow/reading), 960px (medium), 1200px (wide), 1440px (ultrawide).
+
+### Sidebar + Main
+```css
+.layout {
+  display: grid;
+  grid-template-columns: 260px 1fr;
+  min-height: 100vh;
+}
+```
+
+### Sticky Header + Scrollable Content
+```css
+.header { position: sticky; top: 0; z-index: 10; }
+.main { overflow-y: auto; }
+```
+
+### Bento Grid
+Irregular grid with varied cell sizes:
+```css
+.bento {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  grid-auto-rows: 200px;
+  gap: var(--space-4);
+}
+.bento .featured {
+  grid-column: span 2;
+  grid-row: span 2;
+}
+```
+
+### Overlap/Layer
+Elements that break out of the grid create visual tension:
+```css
+.overlap-element {
+  position: relative;
+  z-index: 2;
+  margin-top: -3rem;  /* pulls up into previous section */
+}
+```
+
+---
+
+## 6. Common Mistakes
+
+- Using inconsistent spacing values (17px here, 23px there)
+- Centering everything on the page (creates a vertical highway with no anchor points)
+- Not using max-width on content (text that spans 1400px is unreadable)
+- Applying the same padding to all components regardless of their content
+- Putting too many items in a row on mobile (three columns at 375px is almost never right)
+- Using margin-top and margin-bottom on the same element (pick one direction, usually bottom, and stick with it throughout the project)
+- Neglecting the space between the last element and the container edge