motion-ui-skill 2.0.0

package/references/guides/craft-surface-design-system.md

@@ -0,0 +1,120 @@
+---
+title: "Craft & Surface Design System"
+description: "Design specifications, typography, elevation, and component patterns for Motion UI Craft & Surface components."
+category: "Design Systems"
+publishedAt: "2026-07-09"
+updatedAt: "2026-09-17"
+documentation: "references/guides/craft-surface-design-system.md"
+markdown: "references/guides/craft-surface-design-system.md"
+license: "MIT"
+---
+
+# Craft & Surface Design System
+
+The Craft & Surface aesthetic is built around the concept of a clean, quiet workbench: tools and components laid out with tactile precision, ready for production. The brand and showcase surfaces remain neutral so that interactive controls and components remain the focal point.
+
+---
+
+## 1. Color Palette
+
+The palette pairs deep neutral ink with crisp white surfaces and restrained, purposeful accents:
+
+| Token | Hex | Usage |
+| :--- | :--- | :--- |
+| `ink` | `#171717` | Primary text, high-contrast headings, solid button fills |
+| `ink-soft` | `#262626` | Secondary headings, active icons, subtle text |
+| `body` | `#404040` | Body copy, descriptions, article text |
+| `muted` | `#737373` | Secondary labels, captions, metadata |
+| `faint` | `#a3a3a3` | Placeholder text, disabled glyphs |
+| `border` | `#e5e5e5` | Standard structural borders, dividers |
+| `border-subtle` | `#f5f5f5` | Inner container borders, secondary cards |
+| `paper` | `#ffffff` | Primary background, card surfaces, button labels |
+| `paper-tint` | `#fafafa` | Subtle stage backgrounds, preview containers |
+| `accent-rose` | `#f43f5e` | Active likes, bookmark highlights, badges |
+| `accent-cyan` | `#a5f3fc` | Highlight glows, subtle cyan badges |
+| `danger` | `#fda4af` | Error borders, destructive states |
+
+---
+
+## 2. Typography
+
+Components utilize a pairing of expressive serif display typography and crisp geometric sans-serif for UI controls:
+
+- **Display & Headline**: `Instrument Serif`, `ui-serif`, `Georgia`, `serif`
+  - Font size: `1.875rem` (Display), `1.5rem` (Headline)
+  - Weight: `400`
+  - Purpose: Editorial headers, hero titles, ticket labels, certificate cards
+- **Title & UI Labels**: `Geist`, `ui-sans-serif`, `system-ui`, `sans-serif`
+  - Font size: `0.875rem` (Title, 600 weight), `0.75rem` (Label, 500 weight)
+  - Purpose: Button labels, form inputs, table headers, widget status
+- **Body**: `Geist`, `ui-sans-serif`, `system-ui`, `sans-serif`
+  - Font size: `1rem` / `0.875rem`, weight `400`, letter spacing `-0.025em`
+- **Monospace**: `Geist Mono`, `ui-monospace`, `monospace`
+  - Font size: `0.75rem` / `0.625rem`
+  - Purpose: Timestamps, transaction IDs, code snippets, coordinates
+
+---
+
+## 3. Geometry & Elevation
+
+- **Radii Tokens**:
+  - `rounded-md` (`6px` - `8px`): Buttons, input fields, badges, tags
+  - `rounded-lg` (`12px` - `16px`): Cards, dropdown menus, notification banners
+  - `rounded-2xl` (`24px`): Editorial cards, mockups, large containers
+  - `rounded-full` (`9999px`): Pills, avatar rings, slider handles
+- **Internal Spacing**:
+  - Standard container padding: `p-4` or `p-6`
+  - Compact widget spacing: `gap-2` or `gap-3`
+- **Border-Based Focus**:
+  - Input focus states avoid neon rings. Instead, focus transitions to a darker border (`border-neutral-800`) with `ring-0` or `outline-none`.
+
+---
+
+## 4. Tactile & Physical Interactions
+
+Craft components incorporate physical, skeuomorphic cues without visual clutter:
+
+1. **Tactile 3D Buttons**:
+   - Built with multi-layered box-shadows mimicking physical keycaps:
+     `shadow-[0_4px_0_0_#171717] active:shadow-[0_0px_0_0_#171717] active:translate-y-1`
+   - Tactile feedback indicates exact button depression upon press.
+2. **Neumorphic Soft UI**:
+   - Dual-shadow light/dark balance on soft neutral surfaces:
+     `shadow-[-4px_-4px_10px_rgba(255,255,255,0.8),4px_4px_10px_rgba(0,0,0,0.08)]`
+   - Transitions to inset shadows when toggled active.
+3. **Physical Widgets & Mockups**:
+   - High-fidelity SVG frames for Apple iPhone, MacBook, iPad, Watch, and iPod.
+   - Dynamic indicators for battery, audio recording, stopwatch, compass, and hydration.
+
+---
+
+## 5. Integration with Multi-Style Presets
+
+Craft components fit into the `origin` and `minimal` style presets of Motion UI, offering developers pre-built editorial layouts, device mockups, and physical tactile buttons that complement standard motion primitives.
+
+---
+
+## 6. Next.js Image Domain Configuration
+
+Several craft showcase components utilize `next/image` to render high-fidelity mockups, avatars, and editorial media. When using these components in a Next.js application, configure `next.config.js` or `next.config.mjs` to permit the required remote image hostnames:
+
+```js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  images: {
+    remotePatterns: [
+      { protocol: "https", hostname: "images.unsplash.com" },
+      { protocol: "https", hostname: "cursor.com" },
+      { protocol: "https", hostname: "flagcdn.com" },
+      { protocol: "https", hostname: "ditherit.com" },
+      { protocol: "https", hostname: "lucide.dev" },
+      { protocol: "https", hostname: "www.producthunt.com" },
+    ],
+  },
+};
+
+module.exports = nextConfig;
+```
+
+For pure React or Vite setups, replace `next/image` imports with standard HTML `<img>` elements or local asset paths.
+

package/references/guides/design-system-checklist.md

@@ -0,0 +1,98 @@
+---
+title: "Design System Architecture & Production Checklist"
+description: "Comprehensive engineering checklist and architectural standards for modern design systems, covering design tokens, WCAG 2.1 AA/AAA accessibility, component health, and governance."
+documentation: "references/guides/design-system-checklist.md"
+markdown: "references/guides/design-system-checklist.md"
+---
+
+# Design System Architecture & Production Checklist
+
+> Synthesized from [design-system-checklist](https://github.com/ardakaracizmeli/design-system-checklist) and modern production design systems ([shadcn/ui](https://github.com/shadcn-ui/ui), Radix, Tailwind CSS).
+
+A design system is not just a UI kit; it is the contract between design tokens, accessible components, developer experience, and governance. Use this checklist before releasing or auditing components in your design system.
+
+---
+
+## 1. Design Language & Brand Foundations
+
+- [ ] **Design Principles Established**: Defined 3–5 core principles (e.g. *Predictable over clever*, *Frictionless by default*, *Accessible for all*).
+- [ ] **Voice & Tone Guidelines**: Established standards for error messages, empty states, confirmation alerts, and technical explanations.
+- [ ] **Brand Identity Mapping**: Logo assets, icon styles (stroke width, corner radiuses), and brand accent alignments documented.
+
+---
+
+## 2. Design Tokens Architecture
+
+Design tokens represent the single source of truth for visual attributes across web, mobile, and agent interfaces.
+
+### Color Tokens
+- [ ] **Semantic Layering**: Never use raw hex codes or static palette values directly in components.
+  - Primitive scale: `slate-50` through `slate-950`
+  - Semantic roles: `--background`, `--foreground`, `--card`, `--primary`, `--secondary`, `--muted`, `--accent`, `--destructive`, `--border`, `--ring`
+- [ ] **WCAG 2.1 Contrast Standards**:
+  - Minimum 4.5:1 for normal body copy (AA standard).
+  - Minimum 3:1 for large text (18pt+ or 14pt bold) and active UI controls/borders.
+  - Aim for 7:1 (AAA standard) on critical informational displays.
+- [ ] **Dark Mode Inversion**:
+  - Dark mode surfaces must use layered elevation (base is darker, elevated surfaces like cards and dialogs are lighter with subtle border rings).
+  - Test pure black (`#000000`) vs deep obsidian (`#09090b` / `#0f172a`) to ensure anti-banding on OLED displays.
+
+### Typography Scale
+- [ ] **Modular Ratio Scale**:
+  - `xs`: 12px / line-height 16px
+  - `sm`: 14px / line-height 20px
+  - `base`: 16px / line-height 24px
+  - `lg`: 18px / line-height 28px
+  - `xl`: 20px / line-height 28px
+  - `2xl`: 24px / line-height 32px
+  - `3xl`: 30px / line-height 36px
+- [ ] **Tabular Figures (`tabular-nums`)**: Enabled on all metrics, counters, pricing, and streaming agent text to eliminate jitter.
+- [ ] **Truncation & Ellipsis Rules**: Specified multiline clamping (`line-clamp-2`) and tooltip fallbacks for truncated titles.
+
+### Spacing & Grid System
+- [ ] **4px / 8px Spatial Rhythm**: All padding, margin, and gaps conform to multiples of 4:
+  - `1`: 4px | `2`: 8px | `3`: 12px | `4`: 16px | `6`: 24px | `8`: 32px | `12`: 48px
+- [ ] **Layout Containers**: Standardized container constraints (`sm: 640px`, `md: 768px`, `lg: 1024px`, `xl: 1280px`).
+
+### Elevation & Border Radius
+- [ ] **Elevation Tiers**: Defined shadow tokens for ambient, dropdown, card, modal, and popover depths.
+- [ ] **Consistent Radius Scale**: `rounded-sm` (4px), `rounded-md` (6px), `rounded-lg` (8px), `rounded-full` (9999px). Nested radiuses follow the inner formula: `R_inner = R_outer - padding`.
+
+---
+
+## 3. Component Health & API Contract
+
+Every component must satisfy these 7 core requirements:
+
+1. **Controlled & Uncontrolled Support**:
+   - Provide `value` + `onChange` for controlled state.
+   - Provide `defaultValue` for uncontrolled state.
+2. **Class Merging**:
+   - Always accept `className` and wrap with `cn(...)` (`clsx` + `tailwind-merge`) so consumer utilities override defaults without specificity hacks.
+3. **Ref Forwarding**:
+   - Forward DOM refs with `React.forwardRef` or modern React 19 ref attributes to allow focus management, positioning libraries, and measuring.
+4. **Accessible Keyboard Navigation**:
+   - Interactive elements must be reachable via `Tab` / `Shift+Tab`.
+   - Menus, comboboxes, and lists must support `ArrowUp`, `ArrowDown`, `Home`, `End`, and `Enter`/`Space`.
+   - Overlays must close on `Escape`.
+5. **Visible Focus Rings**:
+   - Distinct focus indicator using `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`.
+   - Never suppress focus rings with `outline-none` unless replaced with a compliant visible ring.
+6. **ARIA Roles & States**:
+   - Proper `role` attribute (`dialog`, `listbox`, `tablist`, `menu`, `tooltip`).
+   - Live states: `aria-expanded`, `aria-selected`, `aria-checked`, `aria-disabled`, `aria-invalid`.
+   - Labeling: `aria-labelledby`, `aria-describedby`, or `aria-label` for icon-only buttons.
+7. **Reduced Motion Adaptation**:
+   - Query `useReducedMotion()`. Swap spatial translations and spring overshoots for instant opacity transitions.
+
+---
+
+## 4. Documentation & Governance
+
+- [ ] **Anatomy Breakdown**: Labeled diagram of component parts (Trigger, Content, Header, Footer, Item, Indicator).
+- [ ] **Do's and Don'ts**: Concrete visual examples of correct vs improper usage.
+- [ ] **SemVer Release Contract**:
+  - `Patch`: Bug fixes, CSS refactor without breaking consumer layouts.
+  - `Minor`: New components, backward-compatible props.
+  - `Major`: Removed props, changed event signatures, or modified required peer dependencies.
+- [ ] **Deprecation Lifecycle**: Deprecated props emit development warnings for at least one minor version before deletion.

package/references/guides/enterprise-dashboard-patterns.md

@@ -0,0 +1,53 @@
+---
+title: "Enterprise Dashboard Architecture & Complex UI Patterns"
+description: "Architectural guidelines for high-density enterprise dashboard interfaces, data grids, kanban boards, faceted filter builders, timelines, and cascading selectors."
+documentation: "references/guides/enterprise-dashboard-patterns.md"
+markdown: "references/guides/enterprise-dashboard-patterns.md"
+---
+
+# Enterprise Dashboard Architecture & Complex UI Patterns
+
+> Architectural patterns for complex, data-intensive web applications, directly synthesized from [keenthemes/reui](https://github.com/keenthemes/reui) and [shadcn/ui](https://github.com/shadcn-ui/ui).
+
+---
+
+## 1. Information Density vs Visual Clarity
+
+Enterprise dashboards deal with high volumes of structured data. Successful layouts balance three constraints:
+1. **Scannability**: Critical numbers and statuses readable at a glance without horizontal scanning fatigue.
+2. **Progressive Disclosure**: Detailed metadata hidden behind hover cards, popovers, or expandable disclosures until requested.
+3. **Responsive Adaptation**: Grids collapse from 4 columns on widescreen $\to$ 2 columns on tablet $\to$ 1 column cards on mobile.
+
+---
+
+## 2. The 5 Core Enterprise Primitives
+
+### 1. Stepped Filter Query Builders
+Faceted filtering enables non-technical users to build complex boolean queries (e.g. `Status == "Active"` AND `Department in ["Eng", "Product"]`):
+- **Attribute Selector**: Dropdown to pick target field.
+- **Operator Selector**: `equals`, `contains`, `greater than`, `is empty`.
+- **Value Input**: Combobox, date range picker, or tag selector.
+- **Visual Pills**: Each applied filter renders as a dismissible chip.
+
+### 2. Timelines & Audit Trails
+Chronological event streams that track order workflows, build pipelines, or agent actions:
+- **Node Statuses**: `completed` (green check), `current` (pulsing primary node), `upcoming` (muted outline), `failed` (destructive cross).
+- **Connecting Track**: Dynamic vertical line with gradient fill indicating progress.
+- **Timestamp Alignment**: Monospace relative timestamps (`2m ago`, `14:32:05`).
+
+### 3. Kanban Task Boards
+Multi-column workflow managers (e.g. Backlog $\to$ In Progress $\to$ Review $\to$ Done):
+- **WIP Limits**: Column headers display task counts against max capacity (e.g. `3 / 5`).
+- **Drag Reordering**: Cards lift with a slight rotation ($2^\circ$) and drop shadow when grabbed, while target drop zones highlight.
+- **Keyboard Shortcuts**: `Enter` to open card, `Space` to pick up, arrow keys to move between columns.
+
+### 4. Cascader / Multi-Level Drilldown
+For deep hierarchical taxonomies (e.g. Category $\to$ Subcategory $\to$ Item, or Region $\to$ Country $\to$ City):
+- Replaces overwhelming deeply nested menus with a single compact footprint.
+- Clicking a branch node slides the next tier of options into view with breadcrumbs.
+- Search input instantly filters across all nested levels.
+
+### 5. High-Density Virtualized Data Grids
+- **Windowing**: Render only the visible rows in the viewport using `@tanstack/react-virtual` to support $10{,}000+$ rows at 60 FPS.
+- **Sticky Column Freezing**: Left-pinning primary keys (e.g. User Name / ID) and right-pinning action rows during horizontal scrolling.
+- **Batch Selection**: Header master checkbox with indeterminate state for partial selection.

package/references/guides/interaction-transitions.md

@@ -0,0 +1,71 @@
+---
+title: "The 12 Canonical Interaction Transitions"
+description: "Reference catalog and implementation blueprints for the 12 essential UI transitions from Transitions.dev, including cubic-bezier tokens, spring physics, and zero-layout-shift formulas."
+documentation: "references/guides/interaction-transitions.md"
+markdown: "references/guides/interaction-transitions.md"
+---
+
+# The 12 Canonical Interaction Transitions
+
+> Synthesized from [transitions.dev](https://github.com/Jakubantalik/transitions.dev) by Jakub Antalík.
+
+Micro-interactions make the difference between an application that feels static and one that feels responsive, continuous, and physical. Here are the 12 canonical transitions, their physics parameters, and exact implementation patterns.
+
+---
+
+## 1. Interaction Transition Catalog
+
+| # | Pattern Name | Interaction Description | Physics / Curve | Duration / Spring |
+|---|:---|:---|:---|:---|
+| **1** | **Card Resize** | Container expands or contracts its footprint smoothly without layout distortion. | `cubic-bezier(0.16, 1, 0.3, 1)` | 280–350ms or `SPRING_PANEL` |
+| **2** | **Number Pop-In** | Value changes with rolling digit slot animation and subtle directional blur. | `cubic-bezier(0.34, 1.56, 0.64, 1)` | 200–280ms / stagger 20ms |
+| **3** | **Notification Badge** | Badge pops onto an icon with a spring overshoot and scales in from center. | `SPRING_BOUNCE` | Stiffness: 300, Damping: 18 |
+| **4** | **Text States Swap** | Label trades places (e.g. "Save" $\to$ "Saved") with directional fade & blur. | `SPRING_SWAP` | Stiffness: 460, Damping: 30 |
+| **5** | **Menu Dropdown** | Menu unfolds from the trigger origin using clip-path or scaleY with blur. | `cubic-bezier(0.16, 1, 0.3, 1)` | 180–220ms |
+| **6** | **Modal Open/Close** | Backdrop fades while panel scales from 0.95 to 1.0 with subtle spring brake. | `SPRING_PANEL` | Stiffness: 420, Damping: 40 |
+| **7** | **Panel Reveal** | Side or bottom drawer slides along axis with inertia and edge damping. | `cubic-bezier(0.32, 0.72, 0, 1)` | 300–400ms |
+| **8** | **Page Side-by-Side** | Multi-step navigation slides current view left while incoming view slides in. | `cubic-bezier(0.2, 0, 0, 1)` | 320ms / `mode="wait"` |
+| **9** | **Icon Swap** | Action icon changes (e.g. Hamburger $\to$ X, Play $\to$ Pause) with rotation and scale. | `SPRING_SWAP` | Stiffness: 460, Damping: 30 |
+| **10** | **Success Check** | Circle halo pulses outward while checkmark draws itself along SVG path. | Multi-stage timeline | 350ms total sequence |
+| **11** | **Avatar Group Hover** | Hovered avatar springs up and scales up while neighbor avatars fan apart. | `SPRING_BOUNCE` + Falloff | Stiffness: 300, Damping: 20 |
+| **12** | **Error Shake** | Input shakes horizontally 3–4 times on validation failure then returns to neutral. | Keyframe oscillate | 350ms (`[-4px, 4px, -3px, 3px, 0]`) |
+
+---
+
+## 2. Key Interaction Recipes
+
+### Pattern 10: Success Check Animation
+The success check is a compound celebration micro-interaction:
+1. Halo circle scales out with fading opacity.
+2. Background pill or circle pops in with `SPRING_BOUNCE`.
+3. SVG checkmark uses `pathLength: 0` to `pathLength: 1` stroke animation.
+
+```tsx
+<motion.svg viewBox="0 0 24 24" className="size-6 text-emerald-500" fill="none">
+  <motion.circle
+    cx="12"
+    cy="12"
+    r="10"
+    stroke="currentColor"
+    strokeWidth="2"
+    initial={{ pathLength: 0, opacity: 0 }}
+    animate={{ pathLength: 1, opacity: 1 }}
+    transition={{ duration: 0.3, ease: EASE_OUT }}
+  />
+  <motion.path
+    d="M8 12.5l2.5 2.5L16 9"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    initial={{ pathLength: 0 }}
+    animate={{ pathLength: 1 }}
+    transition={{ duration: 0.25, delay: 0.2, ease: EASE_OUT }}
+  />
+</motion.svg>
+```
+
+### Pattern 11: Avatar Group Distance Falloff
+When hovering over avatar $i$, calculate each neighbor's offset based on its distance $|j - i|$:
+$$\Delta x = \operatorname{sign}(j - i) \times \frac{24\text{px}}{1 + |j - i|}$$
+This produces an organic magnetic dispersal effect where immediate neighbors move substantially and distant avatars remain undisturbed.

package/references/guides/motion-engineering.md

@@ -0,0 +1,137 @@
+---
+title: "Motion Engineering Guide"
+description: "In-depth guide to modern Motion (motion/react v12/v13+), physics-based springs, layout animations, exit orchestration, gesture velocity handoffs, and hardware acceleration."
+documentation: "references/guides/motion-engineering.md"
+markdown: "references/guides/motion-engineering.md"
+---
+
+# Motion Engineering Guide
+
+> Deep technical guide to building robust, high-performance animations with **Motion** (`motion/react` / `framer-motion`), based on core principles from [motiondivision/motion](https://github.com/motiondivision/motion).
+
+---
+
+## 1. Physics-Based Springs vs Duration Easings
+
+In UI engineering, duration-based transitions (`transition: all 300ms ease`) often feel robotic and interrupt-unsafe. When an interaction is canceled mid-flight, a CSS transition reverses awkwardly. **Spring physics** calculate movement continuously based on mass, tension, and damping, allowing natural velocity preservation when gestures are interrupted.
+
+### Spring Equation Model
+$$\ddot{x} + 2\zeta\omega_0 \dot{x} + \omega_0^2 x = 0$$
+
+Where:
+- **Stiffness** ($k$): Resistance to stretching. Higher values increase speed and responsiveness.
+- **Damping** ($c$): Friction that resists motion. Low damping yields bouncy overshoots; high damping prevents oscillation (critically damped).
+- **Mass** ($m$): Heaviness of the element. Higher mass gives slow, deliberate inertia.
+
+### Canonical Spring Configurations (`lib/ease.ts`)
+
+```tsx
+// 1. Tappable / Press feedback (stiff, responsive, instant feedback)
+export const SPRING_PRESS = { type: "spring", stiffness: 500, damping: 30, mass: 0.6 };
+
+// 2. Playful Micro-Pops & Celebrations (springy bounce)
+export const SPRING_BOUNCE = { type: "spring", stiffness: 300, damping: 18, mass: 0.8 };
+
+// 3. Modals, Sheets, and Panels (controlled, weighted arrival)
+export const SPRING_PANEL = { type: "spring", stiffness: 420, damping: 40, mass: 0.5 };
+
+// 4. Shared Layout Glide (morphing pills, indicator glides)
+export const SPRING_LAYOUT = { type: "spring", stiffness: 360, damping: 32, mass: 0.6 };
+
+// 5. Critically Damped Slider / Handle (zero overshoot, buttery tracking)
+export const SPRING_GLIDE = { stiffness: 700, damping: 50, mass: 0.5 };
+```
+
+---
+
+## 2. Layout Animations & Shared Elements (`layoutId`)
+
+Motion's layout engine uses an inverted FLIP (First, Last, Invert, Play) technique computed entirely with GPU-accelerated transforms.
+
+### Rules for Flawless Layout Animations
+1. **Never animate `width` and `height` directly**: Use `<motion.div layout>` or `<motion.div layoutId="unique-key">`. Motion calculates the bounding box change and applies an inverse `scale(x, y)` transform.
+2. **Correcting Child Distortion**: When a parent morphs its dimensions via `layout`, children can appear stretched. Add `layout` to direct children or use `layout="position"` on the parent to restrict morphing to coordinate positioning.
+3. **Pill & Indicator Gliding**:
+```tsx
+{tabs.map((tab) => (
+  <button key={tab.id} onClick={() => setSelected(tab.id)} className="relative px-3 py-1.5">
+    {selected === tab.id && (
+      <motion.div
+        layoutId="active-tab-indicator"
+        className="absolute inset-0 rounded-full bg-primary/10 dark:bg-primary/20"
+        transition={SPRING_LAYOUT}
+      />
+    )}
+    <span className="relative z-10 text-sm">{tab.label}</span>
+  </button>
+))}
+```
+
+---
+
+## 3. Exit Animations & `AnimatePresence`
+
+`AnimatePresence` enables React elements to animate as they are removed from the DOM.
+
+### Orchestration Modes
+- **`mode="sync"` (default)**: Entering and exiting elements animate simultaneously. Best for independent items or list row insertions.
+- **`mode="wait"`**: The exiting element finishes its exit animation completely before the new element mounts. Best for page transitions, stepped wizards, and tab panels.
+- **`mode="popLayout"`**: Exiting elements are immediately taken out of the document layout flow (`position: absolute`) so sibling items glide immediately into their target positions without waiting for the exit to finish.
+
+```tsx
+<AnimatePresence mode="popLayout">
+  {items.map((item) => (
+    <motion.li
+      key={item.id}
+      layout
+      initial={{ opacity: 0, scale: 0.9, y: 10 }}
+      animate={{ opacity: 1, scale: 1, y: 0 }}
+      exit={{ opacity: 0, scale: 0.85, transition: { duration: 0.15 } }}
+      transition={SPRING_LAYOUT}
+    >
+      {item.title}
+    </motion.li>
+  ))}
+</AnimatePresence>
+```
+
+---
+
+## 4. Imperative Sequencing with `useAnimate`
+
+When animations require complex multi-step choreographies (e.g. badge expands $\to$ text scrambles $\to$ checkmark draws $\to$ settles), declarative props can become unwieldy. Use `useAnimate` for precise async/await timelines:
+
+```tsx
+const [scope, animate] = useAnimate();
+
+const handleSuccess = async () => {
+  // Step 1: scale down trigger
+  await animate(scope.current, { scale: 0.95 }, { duration: 0.1 });
+  // Step 2: pop open success container with spring
+  await animate(scope.current, { scale: 1, width: 220 }, SPRING_BOUNCE);
+  // Step 3: draw SVG checkmark
+  await animate("path.check", { pathLength: 1, opacity: 1 }, { duration: 0.25, ease: EASE_OUT });
+};
+```
+
+---
+
+## 5. Drag Gestures & Momentum Handoff
+
+Motion provides robust pointer gestures with built-in inertia and constraint bounding:
+
+```tsx
+<motion.div
+  drag="y"
+  dragConstraints={{ top: 0, bottom: 0 }}
+  dragElastic={{ top: 0.1, bottom: 0.6 }} // Rubber-banding resistance
+  onDragEnd={(_e, info) => {
+    // If flicked with downward velocity > 300 or dragged past 100px threshold
+    if (info.velocity.y > 300 || info.offset.y > 100) {
+      onDismiss();
+    }
+  }}
+>
+  <SheetContent />
+</motion.div>
+```

package/references/guides/motion-patterns.md

@@ -0,0 +1,106 @@
+---
+title: "Motion Guides"
+description: "Practical guidance for purposeful animation, timing, easing, springs, and accessible motion in React interfaces."
+documentation: "references/guides/motion-patterns.md"
+markdown: "references/guides/motion-patterns.md"
+---
+
+# Motion Guides
+
+> Practical guidance for purposeful animation, timing, easing, springs, and accessible motion in React interfaces.
+
+## Decision framework
+
+Ask four questions before choosing a duration or spring:
+
+1. **Check frequency.** Repeated actions should feel nearly instant. Save expressive motion for rare moments.
+2. **Name the purpose.** Motion should explain space, confirm input, show state, or soften a change.
+3. **Choose the physics.** Use ease-out for entrances, ease-in-out for movement, linear motion for progress, and springs for gestures.
+4. **Design the fallback.** Reduced motion should keep useful opacity and color feedback while removing travel, scale, parallax, and overshoot.
+
+## Motion tokens
+
+- `EASE_OUT`: entrances and exits that respond immediately, then settle quietly.
+- `EASE_IN_OUT`: objects already on screen moving between positions.
+- `SPRING_PRESS`: fast, weighted feedback for pressable surfaces.
+- `SPRING_LAYOUT`: shared surfaces and indicators that preserve spatial continuity.
+- `SPRING_BOUNCE`: lively playful bounce for badges, celebration checks, stars, and micro-pops.
+- `SPRING_GENTLE`: gentle, natural spring for spacious card expansions and drawer reveals.
+- `SPRING_SNAPPY`: snappy, high-velocity spring for fast toggles, segmented pills, and tabs.
+- `SPRING_FLOAT`: soft floating physics for tooltips, hover cards, and ambient elevation.
+- `SPRING_GLIDE`: critically damped slider handles with zero overshoot.
+
+## Timing
+
+| Interaction | Range | Desired feel |
+| --- | --- | --- |
+| Press feedback | 100–160ms | Immediate and physical |
+| Tooltip or popover | 125–200ms | Quick and origin-aware |
+| Dropdown or select | 150–250ms | Responsive, with no waiting |
+| Modal or drawer | 200–500ms | Enough time to explain space |
+| Marketing demo | Flexible | Clarity matters more than speed |
+
+Under 300ms is the default for interface motion. Longer motion belongs to explanatory demos, deliberate gestures, and large spatial changes.
+
+## Comprehensive Guides Suite
+
+For specialized engineering topics, consult the dedicated companion guides:
+- [Design System Architecture & Checklist](./design-system-checklist.md): Tokens, WCAG contrast, typography, and component health.
+- [Motion Engineering Guide](./motion-engineering.md): Deep dive into `motion/react`, physics springs, `layoutId`, and gestures.
+- [Motion Performance & 60/120 FPS](./motion-performance.md): Compositor properties, avoiding layout thrashing, and layer budgets.
+- [Baseline UI Craft & Anti-Slop](./baseline-ui-craft.md): Design engineering principles, optical alignment, and micro-interactions.
+- [The 12 Canonical Interaction Transitions](./interaction-transitions.md): Transitions.dev interaction patterns and token specs.
+- [Universal Mobile-First Interaction Patterns](./universal-mobile-patterns.md): Touch ergonomics, haptic feedback semantics, and swipe gestures.
+- [Enterprise Dashboard Architecture](./enterprise-dashboard-patterns.md): High-density data grids, kanban boards, faceted query builders, and timelines.
+
+## Recipes
+
+### Press feedback
+
+Confirm input before the action finishes. Keep the scale change small and the response immediate.
+
+```tsx
+const reduce = useReducedMotion();
+
+<motion.button
+  whileTap={reduce ? undefined : { scale: 0.97 }}
+  transition={SPRING_PRESS}
+>
+  Continue
+</motion.button>
+```
+
+### Semantic icon motion
+
+Let an icon imitate its real action. Gate decorative hover motion behind pointer capability and reduced-motion preferences.
+
+### Content reveal
+
+Reveal one meaningful surface with a short lift and restrained blur. Finish before the surface becomes the focus.
+
+### Layout continuity
+
+Keep the same surface visible while its footprint changes. Move the shape first, then introduce its label.
+
+### Content swap
+
+For small view changes, let old content leave faster than new content arrives. Keep travel to a few pixels.
+
+## Accessibility
+
+Reduced motion is a designed state. Preserve opacity, color, and instant state changes. Remove parallax, large transforms, repeated scale, and spring overshoot.
+
+```tsx
+const reduce = useReducedMotion();
+
+const hidden = {
+  opacity: 0,
+  transform: reduce ? "none" : "translateY(8px)",
+};
+
+const visible = {
+  opacity: 1,
+  transform: "translateY(0px)",
+};
+```
+

package/references/guides/motion-performance.md

@@ -0,0 +1,66 @@
+---
+title: "Motion Performance & 60/120 FPS Engineering"
+description: "Auditing and optimizing animation performance: compositor-only properties, eliminating layout thrashing, scroll-linked motion decoupling, layer budgets, and GPU compositing rules."
+documentation: "references/guides/motion-performance.md"
+markdown: "references/guides/motion-performance.md"
+---
+
+# Motion Performance & 60/120 FPS Engineering
+
+> Production performance guidelines for fluid, stutter-free animations, directly synthesized from [ibelick/ui-skills](https://github.com/ibelick/ui-skills) (`/fixing-motion-performance`).
+
+---
+
+## 1. The Rendering Pipeline
+
+Modern browsers render every frame through three distinct phases:
+
+| Phase | Affected Properties | Cost & FPS Risk |
+| :--- | :--- | :--- |
+| **Composite** | `transform` (`translate`, `scale`, `rotate`), `opacity`, `filter` (partial) | **Low (Best)**: Runs off-thread directly on the GPU. Never causes reflow. |
+| **Paint** | `background-color`, `color`, `box-shadow`, `border-radius`, `outline` | **Medium**: Repaints pixels into bitmap layers. Costly on large surfaces. |
+| **Layout** | `width`, `height`, `top`, `left`, `margin`, `padding`, `display`, `flex` | **Critical (Worst)**: Triggers geometry recalculation across the entire document tree. |
+
+### Rule #1: Only Animate Composite Properties
+Stick strictly to `transform` and `opacity` for animation. If a component appears to change size, use Motion's `layout` prop (which simulates dimension shifts via transform scaling) or CSS scale transforms.
+
+---
+
+## 2. The "Never Patterns" (Critical Performance Violations)
+
+1. **Never Interleave Layout Reads & Writes in the Same Frame**:
+   - Reading `offsetWidth`, `scrollTop`, `getBoundingClientRect()` immediately after modifying CSS forces the browser to synchronously recalculate layout (**forced reflow** or **layout thrashing**).
+   - Solution: Read all metrics in one phase, then apply style mutations in `requestAnimationFrame`.
+2. **Never Drive Animations from Raw Scroll Events**:
+   - Never attach heavy state updates or DOM manipulation directly to `window.addEventListener("scroll", ...)`.
+   - Solution: Use `useScroll` with Motion values or native CSS `animation-timeline: scroll()`.
+3. **No Infinite `requestAnimationFrame` Loops Without a Stop Condition**:
+   - Every continuous rAF loop burns CPU cycles and drains battery life on mobile devices. Ensure an active velocity threshold or time limit breaks the loop when the value settles.
+4. **Never Animate `blur()` Dynamically Across Large Screens**:
+   - Real-time Gaussian blur calculation over large surfaces (`backdrop-filter: blur(20px)`) is computationally intensive on integrated GPUs and mobile chipsets. Keep blur radii static and animate opacity instead.
+
+---
+
+## 3. Layer Promotion & `will-change`
+
+`will-change: transform` informs the browser's compositing engine to allocate a dedicated GPU backing store (layer) for the element.
+
+### Rules for Layer Budgeting:
+- **Do not apply `will-change` globally or perpetually**: Each promoted layer consumes VRAM. 100 promoted layers can exhaust GPU memory and cause mobile browser crashes.
+- **Apply conditionally**: Only apply `will-change: transform` while an interaction is actively occurring (e.g. during hover, drag, or active slide), and remove it once the element is at rest.
+- **Hardware Acceleration Hack**: If an element stutters during entrance, apply `transform: translateZ(0)` or `backface-visibility: hidden` to force hardware compositing without memory bloat.
+
+---
+
+## 4. Diagnostics & Profiling Workflow
+
+When an animation drops frames:
+1. **Chrome DevTools Performance Panel**:
+   - Record a 5-second trace of the interaction.
+   - Look for long red bars under the **Main thread** flame graph.
+   - Look for **Layout** or **Recalculate Style** events occurring every frame (16.6ms at 60Hz or 8.3ms at 120Hz).
+2. **Rendering Tab**:
+   - Enable **Paint Flashing**: Green flashes reveal which elements are being repainted each frame. Good animations only flash when entering/exiting, never during movement.
+   - Enable **Layer Borders**: Inspect which elements have their own composite layers (orange borders) and tile borders (cyan).
+3. **Core Web Vitals Check**:
+   - Ensure animations do not cause Cumulative Layout Shift (CLS). Elements entering the page must be absolutely positioned or have pre-reserved container bounds.