picasso-skill 1.0.0

package/skills/picasso/references/motion-and-animation.md

@@ -0,0 +1,260 @@
+# Motion and Animation Reference
+
+## Table of Contents
+1. Principles
+2. Easing Functions
+3. Duration Guidelines
+4. Staggered Reveals
+5. Scroll-Triggered Animation
+6. Text Morphing
+7. Micro-Interactions
+8. Reduced Motion
+9. Common Mistakes
+
+---
+
+## 1. Principles
+
+Motion serves three purposes: feedback (confirming an action), orientation (showing where something went), and delight (making the interface feel alive). If an animation does not serve one of these, remove it.
+
+### Priority of Animation Investment
+1. Page load choreography (highest impact, seen by everyone)
+2. State transitions (tabs, modals, accordions)
+3. Hover/focus states
+4. Scroll-triggered reveals
+5. Loading states and skeletons
+6. Micro-interactions (button press effects, toggle animations)
+
+Invest time in this order. A well-choreographed page load does more than fifty micro-interactions.
+
+---
+
+## 2. Easing Functions
+
+### Use These
+```css
+/* Standard ease-out: elements arriving */
+--ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+
+/* Standard ease-in: elements departing */
+--ease-in: cubic-bezier(0.55, 0.085, 0.68, 0.53);
+
+/* Standard ease-in-out: elements transforming in place */
+--ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+
+/* Spring-like (subtle): natural deceleration */
+--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
+```
+
+### Never Use
+- `linear` for UI animations (looks mechanical)
+- `ease` (the CSS default is mediocre)
+- `bounce` / elastic easing (looks dated and gimmicky)
+- Spring animations with visible oscillation (too playful for most UIs)
+
+---
+
+## 3. Duration Guidelines
+
+| Type | Duration | Why |
+|---|---|---|
+| Hover state change | 100-150ms | Must feel instant |
+| Button press | 80-120ms | Tactile response |
+| Tooltip appear | 150-200ms | Quick but not jarring |
+| Fade in/out | 150-250ms | Smooth perception |
+| Slide/expand | 200-350ms | Visible movement |
+| Page transition | 300-500ms | Substantial change |
+| Complex choreography | 400-800ms total | Entrance sequence |
+
+Rule of thumb: if the user is waiting for it, it should be fast (under 200ms). If the user is watching it, it can be slower (200-500ms).
+
+---
+
+## 4. Staggered Reveals
+
+The most impactful animation pattern. Elements enter one after another with increasing delay.
+
+### CSS-Only Pattern
+```css
+.reveal-item {
+  opacity: 0;
+  transform: translateY(12px);
+  animation: reveal 0.5s var(--ease-out) forwards;
+}
+
+@keyframes reveal {
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.reveal-item:nth-child(1) { animation-delay: 0ms; }
+.reveal-item:nth-child(2) { animation-delay: 60ms; }
+.reveal-item:nth-child(3) { animation-delay: 120ms; }
+.reveal-item:nth-child(4) { animation-delay: 180ms; }
+.reveal-item:nth-child(5) { animation-delay: 240ms; }
+```
+
+### Key Parameters
+- **Stagger interval**: 40-80ms between items (shorter for many items, longer for few)
+- **Translate distance**: 8-16px (subtle is better)
+- **Do not stagger more than 6-8 items**. After that, group them.
+
+### React with Motion Library
+```jsx
+import { motion } from "framer-motion";
+
+const container = {
+  hidden: {},
+  show: { transition: { staggerChildren: 0.06 } }
+};
+
+const item = {
+  hidden: { opacity: 0, y: 12 },
+  show: { opacity: 1, y: 0, transition: { duration: 0.5, ease: [0.16, 1, 0.3, 1] } }
+};
+```
+
+---
+
+## 5. Scroll-Triggered Animation
+
+### CSS-Only with Scroll-Driven Animations
+```css
+@keyframes fade-in {
+  from { opacity: 0; transform: translateY(20px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+.scroll-reveal {
+  animation: fade-in linear both;
+  animation-timeline: view();
+  animation-range: entry 0% entry 30%;
+}
+```
+
+### Intersection Observer Pattern
+```js
+const observer = new IntersectionObserver(
+  (entries) => {
+    entries.forEach(entry => {
+      if (entry.isIntersecting) {
+        entry.target.classList.add('visible');
+        observer.unobserve(entry.target);
+      }
+    });
+  },
+  { threshold: 0.15, rootMargin: '0px 0px -50px 0px' }
+);
+
+document.querySelectorAll('.animate-on-scroll').forEach(el => observer.observe(el));
+```
+
+---
+
+## 6. Text Morphing
+
+For animated text transitions (changing labels, counters, status updates), use **Torph** (dependency-free).
+
+### Installation
+```
+npm i torph
+```
+
+### Usage
+```jsx
+import { TextMorph } from 'torph/react';
+
+// Automatically animates between text values
+<TextMorph>{status}</TextMorph>
+
+// Works with any dynamic text
+<button>
+  <TextMorph>{isLoading ? "Processing..." : `Buy for $${price}`}</TextMorph>
+</button>
+```
+
+Torph morphs individual characters with smooth enter/exit animations. It works with React, Vue, Svelte, and vanilla TypeScript.
+
+### When to Use
+- Tab labels that change on selection
+- Button text that updates (Add to Cart -> Added!)
+- Counter values that increment
+- Status indicators that cycle through states
+- Any text that changes in response to user action
+
+---
+
+## 7. Micro-Interactions
+
+### Button Press
+```css
+button:active {
+  transform: scale(0.97);
+  transition: transform 80ms var(--ease-in);
+}
+```
+
+### Toggle Switch
+Animate the knob position and background color simultaneously. The knob should arrive slightly before the color finishes changing.
+
+### Checkbox
+Scale the checkmark from 0 to 1 with a slight overshoot:
+```css
+.checkbox-mark {
+  transform: scale(0);
+  transition: transform 200ms cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+.checkbox:checked .checkbox-mark {
+  transform: scale(1);
+}
+```
+
+### Skeleton Loading
+Shimmer from left to right using a gradient animation:
+```css
+.skeleton {
+  background: linear-gradient(90deg,
+    var(--surface-2) 25%,
+    var(--surface-3) 50%,
+    var(--surface-2) 75%
+  );
+  background-size: 200% 100%;
+  animation: shimmer 1.5s infinite;
+}
+@keyframes shimmer {
+  0% { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+}
+```
+
+---
+
+## 8. Reduced Motion
+
+Always respect the user's motion preference:
+```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;
+  }
+}
+```
+
+This does not mean removing all visual feedback. Opacity changes (fades) are still acceptable. Remove translation, scaling, and rotation animations.
+
+---
+
+## 9. Common Mistakes
+
+- Animating everything on the page (creates visual noise, reduces perceived performance)
+- Using `animation-duration: 0` for reduced motion (some browsers behave unexpectedly; use 0.01ms)
+- Bounce/elastic easing on UI elements (acceptable only in game-like or toy-like contexts)
+- Animating layout properties (width, height, top, left) instead of transforms (causes layout thrashing)
+- Forgetting `will-change` on frequently animated elements (or overusing it on everything)
+- Staggering 20+ items with visible delays (group them or animate the container)
+- Using `transition: all 0.3s` (animates properties you did not intend; be explicit about which properties to transition)

package/skills/picasso/references/react-patterns.md

@@ -0,0 +1,216 @@
+# React Patterns Reference
+
+## Table of Contents
+1. Component Architecture
+2. State Management
+3. Performance
+4. Composition Patterns
+5. Data Fetching
+6. Styling
+7. Common Mistakes
+
+---
+
+## 1. Component Architecture
+
+### Server vs. Client Components
+Default to Server Components. Add `'use client'` only when the component needs:
+- Event handlers (onClick, onChange, etc.)
+- useState, useEffect, useRef, or other hooks
+- Browser APIs (window, document, navigator)
+- Third-party libraries that use hooks or browser APIs
+
+### File Organization
+Colocate related files. Keep components, styles, tests, and types in the same directory:
+```
+components/
+  user-card/
+    user-card.tsx
+    user-card.test.tsx
+    user-card.module.css
+    types.ts
+```
+
+### Naming
+- Components: PascalCase (`UserCard`, `DashboardHeader`)
+- Files: kebab-case (`user-card.tsx`, `dashboard-header.tsx`)
+- Hooks: camelCase with `use` prefix (`useAuth`, `useMediaQuery`)
+- Event handlers: `handle` + event (`handleClick`, `handleSubmit`)
+- Boolean props: `is`/`has`/`should` prefix (`isLoading`, `hasError`)
+
+### Export Patterns
+- **Default export**: page/route components and layout components
+- **Named export**: everything else (utilities, hooks, shared components)
+
+---
+
+## 2. State Management
+
+### Where State Lives
+1. **URL state**: filters, pagination, search queries (use `searchParams`)
+2. **Server state**: data from APIs (use React Query, SWR, or server components)
+3. **Local state**: form inputs, UI toggles, hover/focus state (use `useState`)
+4. **Shared local state**: state needed by siblings (lift to parent, or use context)
+5. **Global state**: rarely needed (auth user, theme preference, feature flags)
+
+### Rules
+- Do not store derived state. Compute it during render.
+- Do not sync state between sources. Pick one source of truth.
+- Prefer `useReducer` over `useState` when the next state depends on the previous state or when managing more than 3 related state variables.
+
+```tsx
+// Bad: storing derived state
+const [items, setItems] = useState(data);
+const [filteredItems, setFilteredItems] = useState([]);
+useEffect(() => {
+  setFilteredItems(items.filter(i => i.active));
+}, [items]);
+
+// Good: compute during render
+const [items, setItems] = useState(data);
+const filteredItems = items.filter(i => i.active);
+```
+
+---
+
+## 3. Performance
+
+### Rendering
+- Use `React.memo` only for components that re-render often with the same props
+- Use `useMemo` for expensive computations, not for every variable
+- Use `useCallback` for callbacks passed to memoized children
+- Use `key` props correctly (stable, unique identifiers, never array indices for reorderable lists)
+
+### Code Splitting
+```tsx
+import dynamic from 'next/dynamic';
+
+const Chart = dynamic(() => import('./chart'), {
+  loading: () => <ChartSkeleton />,
+  ssr: false,
+});
+```
+
+### Virtualization
+For lists with 100+ items, use `react-window` or `@tanstack/virtual`:
+```tsx
+import { FixedSizeList } from 'react-window';
+
+<FixedSizeList height={600} itemCount={items.length} itemSize={48} width="100%">
+  {({ index, style }) => <Row style={style} item={items[index]} />}
+</FixedSizeList>
+```
+
+### Image Optimization
+Use `next/image` in Next.js or `loading="lazy"` with explicit `width`/`height` attributes. Always set `aspect-ratio` to prevent layout shift.
+
+---
+
+## 4. Composition Patterns
+
+### Compound Components
+Components that share implicit state through context:
+```tsx
+<Select value={value} onChange={setValue}>
+  <Select.Trigger>Choose a fruit</Select.Trigger>
+  <Select.Content>
+    <Select.Item value="apple">Apple</Select.Item>
+    <Select.Item value="banana">Banana</Select.Item>
+  </Select.Content>
+</Select>
+```
+
+### Slot Pattern
+Flexible component composition through named children:
+```tsx
+function Card({ header, children, footer }) {
+  return (
+    <div className="card">
+      {header && <div className="card-header">{header}</div>}
+      <div className="card-body">{children}</div>
+      {footer && <div className="card-footer">{footer}</div>}
+    </div>
+  );
+}
+```
+
+### Render Props (when needed)
+For components that need to share behavior, not UI:
+```tsx
+<DataFetcher url="/api/users">
+  {({ data, isLoading }) => isLoading ? <Skeleton /> : <UserList users={data} />}
+</DataFetcher>
+```
+
+---
+
+## 5. Data Fetching
+
+### Server Components (preferred)
+```tsx
+async function UserList() {
+  const users = await fetch('/api/users').then(r => r.json());
+  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+```
+
+### Client-Side with Suspense
+```tsx
+function Dashboard() {
+  return (
+    <Suspense fallback={<DashboardSkeleton />}>
+      <DashboardContent />
+    </Suspense>
+  );
+}
+```
+
+### Error Boundaries
+Wrap data-fetching components in error boundaries:
+```tsx
+<ErrorBoundary fallback={<ErrorMessage />}>
+  <Suspense fallback={<Skeleton />}>
+    <DataComponent />
+  </Suspense>
+</ErrorBoundary>
+```
+
+---
+
+## 6. Styling
+
+### Tailwind Best Practices
+- Use Tailwind's core utility classes (pre-defined classes only in Claude artifacts)
+- Extract repeated patterns into component variants, not `@apply` rules
+- Use CSS variables for theme values, Tailwind utilities for everything else
+- Never use more than ~10 utility classes on a single element; extract a component instead
+
+### CSS Modules
+For non-Tailwind projects:
+```tsx
+import styles from './button.module.css';
+<button className={styles.primary}>Click</button>
+```
+
+### Semantic HTML
+Use the right element, not just `div` with classes:
+- `<nav>` for navigation
+- `<main>` for primary content
+- `<section>` for thematic grouping
+- `<article>` for self-contained content
+- `<aside>` for tangentially related content
+- `<header>` and `<footer>` for their semantic purpose
+- `<button>` for clickable actions, `<a>` for navigation
+
+---
+
+## 7. Common Mistakes
+
+- Using `useEffect` for derived state (compute during render instead)
+- Putting everything in global state (most state should be local or server-derived)
+- Using `index` as `key` for dynamic lists
+- Wrapping every component in `React.memo`
+- Using `any` in TypeScript (defeats the purpose of type safety)
+- Fetching data in `useEffect` when a server component would suffice
+- Not using Suspense boundaries (the whole page flashes instead of parts loading independently)
+- Prop drilling through 5+ levels (use composition or context)

package/skills/picasso/references/responsive-design.md

@@ -0,0 +1,118 @@
+# Responsive Design Reference
+
+## 1. Breakpoints
+
+Use content-driven breakpoints, not device-driven. These are sensible defaults:
+
+```css
+/* Mobile first: no media query = mobile */
+/* Small tablets / large phones */
+@media (min-width: 640px) { }
+/* Tablets / small laptops */
+@media (min-width: 768px) { }
+/* Laptops / desktops */
+@media (min-width: 1024px) { }
+/* Large desktops */
+@media (min-width: 1280px) { }
+/* Ultrawide */
+@media (min-width: 1536px) { }
+```
+
+## 2. Mobile-First Approach
+
+Start with the mobile layout (single column, stacked). Add complexity at wider breakpoints. This ensures the core experience works everywhere before enhancements.
+
+```css
+/* Base: single column */
+.grid { display: grid; gap: 1rem; }
+
+/* Tablet: two columns */
+@media (min-width: 768px) {
+  .grid { grid-template-columns: repeat(2, 1fr); }
+}
+
+/* Desktop: three columns */
+@media (min-width: 1024px) {
+  .grid { grid-template-columns: repeat(3, 1fr); }
+}
+```
+
+## 3. Fluid Design
+
+Use `clamp()` for font sizes, padding, and gaps that scale smoothly:
+
+```css
+.container {
+  padding: clamp(1rem, 4vw, 3rem);
+  max-width: 1200px;
+  margin: 0 auto;
+}
+h1 {
+  font-size: clamp(1.75rem, 4vw + 0.5rem, 3.5rem);
+}
+```
+
+## 4. Container Queries
+
+For component-level responsiveness (when the component's width, not the viewport, should determine layout):
+
+```css
+.card-container {
+  container-type: inline-size;
+}
+@container (min-width: 400px) {
+  .card { display: grid; grid-template-columns: 1fr 2fr; }
+}
+```
+
+## 5. Touch Targets
+
+Minimum touch target: 44x44px (WCAG) or 48x48px (Material). Apply to all interactive elements on mobile. If the visual element is smaller, use padding or `::before` pseudo-element to extend the hit area.
+
+```css
+.icon-button {
+  position: relative;
+  width: 24px;
+  height: 24px;
+}
+.icon-button::before {
+  content: '';
+  position: absolute;
+  inset: -12px; /* extends tap area to 48x48 */
+}
+```
+
+## 6. Responsive Typography
+
+Do not just shrink everything on mobile. Adjust the type scale:
+- Mobile: use a smaller ratio (1.2) with a 15-16px base
+- Desktop: use a larger ratio (1.25-1.333) with a 16-18px base
+- Headings should scale more aggressively than body text
+
+## 7. Navigation Patterns
+
+- **Mobile (< 768px)**: Hamburger menu, bottom tab bar, or slide-out drawer
+- **Tablet (768-1024px)**: Collapsed sidebar or icon-only navigation
+- **Desktop (> 1024px)**: Full sidebar, top navigation bar, or mega-menu
+
+## 8. Images
+
+Use `srcset` and `sizes` for responsive images. Use `loading="lazy"` for below-the-fold images. Set `aspect-ratio` to prevent layout shift:
+
+```css
+img {
+  width: 100%;
+  height: auto;
+  aspect-ratio: 16 / 9;
+  object-fit: cover;
+}
+```
+
+## 9. Common Mistakes
+
+- Hiding too much content on mobile (users expect the same information, just reorganized)
+- Using `vw` units for text without a `clamp()` minimum (becomes unreadable on small screens)
+- Horizontal scrolling on mobile (almost never acceptable)
+- Fixed-position elements that cover too much of the mobile viewport
+- Not testing at actual device widths (375px for iPhone SE, 390px for modern iPhones, 360px for Android)
+- Tables that overflow on mobile (use horizontal scroll wrapper or reformat as stacked cards)

package/skills/picasso/references/sensory-design.md

@@ -0,0 +1,125 @@
+# 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.
+
+### The Soundcn Pattern
+Use inline base64 audio data URIs with the Web Audio API. This avoids external file loading, CORS issues, and runtime fetching. Each sound is a self-contained TypeScript module.
+
+```typescript
+// sounds/click-soft.ts
+export const clickSoftSound = "data:audio/wav;base64,UklGR..."; // base64 WAV
+
+// hooks/use-sound.ts
+import { useCallback, useRef } from 'react';
+
+export function useSound(src: string) {
+  const audioContextRef = useRef<AudioContext | null>(null);
+
+  const play = useCallback(() => {
+    if (!audioContextRef.current) {
+      audioContextRef.current = new AudioContext();
+    }
+    const ctx = audioContextRef.current;
+    fetch(src)
+      .then(r => r.arrayBuffer())
+      .then(buf => ctx.decodeAudioData(buf))
+      .then(decoded => {
+        const source = ctx.createBufferSource();
+        source.buffer = decoded;
+        source.connect(ctx.destination);
+        source.start(0);
+      });
+  }, [src]);
+
+  return [play] as const;
+}
+```
+
+### Usage
+```tsx
+import { useSound } from "@/hooks/use-sound";
+import { clickSoftSound } from "@/sounds/click-soft";
+
+function Button() {
+  const [play] = useSound(clickSoftSound);
+  return <button onClick={() => { play(); handleAction(); }}>Save</button>;
+}
+```
+
+### 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
+- Source sounds from CC0 collections (Kenney, Freesound)
+
+---
+
+## 2. Haptic Feedback
+
+### The Vibration API
+```javascript
+// Check support
+if ('vibrate' in navigator) {
+  // Simple tap (10ms pulse)
+  navigator.vibrate(10);
+
+  // Success pattern (two short pulses)
+  navigator.vibrate([10, 50, 10]);
+
+  // Error pattern (one longer pulse)
+  navigator.vibrate(30);
+
+  // Warning (three quick pulses)
+  navigator.vibrate([10, 30, 10, 30, 10]);
+}
+```
+
+### 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`)
+- 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
+- Mobile only: haptics have no effect on desktop
+
+### iOS Considerations
+The Vibration API has limited support on iOS Safari. For broader iOS support, use the experimental Haptic Feedback API or accept that haptics are Android-primary.
+
+---
+
+## 3. Multi-Sensory Integration
+
+The strongest UI moments combine visual, auditory, and haptic feedback simultaneously:
+
+1. User taps "Complete" button
+2. **Visual**: checkmark animation scales in with a satisfying bounce
+3. **Sound**: soft success chime (100ms)
+4. **Haptic**: double-pulse pattern (10ms, 50ms gap, 10ms)
+
+This triple feedback creates a moment of certainty that a single visual change cannot match. Use it sparingly, for milestone moments (order placed, task completed, level achieved).