motion-ui-skill 2.0.0

package/README.md

@@ -0,0 +1,637 @@
+# Motion UI Skill
+
+<div align="center">
+
+![Motion UI Banner](https://img.shields.io/badge/Components-339%20Total-6366f1?style=for-the-badge)
+![React](https://img.shields.io/badge/React-18%20%2F%2019-61dafb?style=for-the-badge&logo=react)
+![Next.js](https://img.shields.io/badge/Next.js-14%20%2F%2015-000000?style=for-the-badge&logo=next.js)
+![Tailwind CSS](https://img.shields.io/badge/Tailwind-v3%20%2F%20v4-38bdf8?style=for-the-badge&logo=tailwindcss)
+![Motion](https://img.shields.io/badge/Motion-Framer%20Motion-f43f5e?style=for-the-badge)
+![Local](https://img.shields.io/badge/Skill-Local--First-10b981?style=for-the-badge)
+![License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)
+
+<p align="center">
+  <b>Comprehensive Library of 339 Animated React & Next.js UI Components</b><br/>
+  Built with Motion and Tailwind CSS. Designed as an offline-first AI Agent Skill & Developer Toolkit with 6 aesthetic style presets.
+</p>
+
+</div>
+
+---
+
+## Overview
+
+**Motion UI Skill** is a production-ready, fully self-contained collection of **339 interactive, animated UI components** across four distinct categories:
+
+1. **Motion Components (80)**: Micro-interactions, spring-loaded buttons, morphing inputs, bouncily unfolding selects, bottom sheets, virtualized tables, 3D cylinder carousels, 17 loader variants, cascaders, ratings, avatar groups, celebration success checks, rich hover cards, keyboard keycaps, smart password fields, spotlight cards, glow buttons, chronological timelines, steppers, segmented controls, breadcrumbs, pagination, collapsibles, chips, copy buttons, progress rings, tree views, sortable lists, date range pickers, icon stacks, phone inputs, speed dials, color pickers, magnet docks, page transitions, card resizes, error shakes, text swaps, and autocompletes.
+2. **AI Agent Surfaces (17)**: Complete modern conversational agent interfaces including message bubbles, viewport scrollers, expandable prompt composers, human-in-the-loop approval cards, streaming responses, diff viewers, syntax-highlighted code blocks, and adaptive activity streams.
+3. **Blocks & Widgets (33)**: Rich, composable application widgets such as drag-and-drop kanban workflow boards, faceted query filter builders, universal mobile action sheets, Apple-style dynamic islands, ⌘K command palettes, knockout tournament fixtures, weekly availability schedulers, cross-chain swaps, prediction market tickets, morphing tab views, event calendars, gantt timeline charts, resizable split panels, audio players, metric stat cards with sparklines, reorder grids, and browser frame mockups.
+4. **Craft & Surface Components (209)**: Tactile 3D buttons, neumorphic soft UI controls, high-fidelity Apple device mockups (iPhone, MacBook, iPad, Watch, iPod), background gradients & geometric patterns, booking calendars, customer and transaction tables, editorial typography cards, social cards, and interactive widgets.
+
+### 🌟 Key Highlights
+- **Local-First**: Every bundled component source file (`.tsx`), shared utility (`lib/`), and markdown guide exists directly in this repository. No remote registry is needed to discover or copy the bundled components.
+- **6 Aesthetic Style Presets**: Built-in support for `minimal` (shadcn), `origin` (Coss / Cal.com), `enterprise` (ReUI), `glow` (ibelick), `ios` (Expo), and `brutalist` (neo-brutalist) styles.
+- **Physics-Based Animation**: Powered by Motion (`motion/react` or `framer-motion`) using calibrated spring configurations (`SPRING_PRESS`, `SPRING_PANEL`, `SPRING_LAYOUT`, `SPRING_BOUNCE`, `SPRING_GENTLE`, `SPRING_SNAPPY`, `SPRING_FLOAT`, `SPRING_MOUSE`, `SPRING_GLIDE`).
+- **Accessible & Reduced-Motion Safe**: Every component natively respects `prefers-reduced-motion` and suppresses phantom touch `:hover` states on mobile via pointer capability detection.
+- **Ecosystem Integration**: Enriched with patterns and standards from KeenThemes ReUI, Design System Checklist, Motion, Expo, Transitions.dev, shadcn/ui, Coss (Origin UI), and ibelick/ui-skills.
+- **Copy-Paste & Drop-In Ready**: Drop files directly into your project's `components/` and `lib/` folders, or use the included CLI installer.
+
+---
+
+## Multi-Style Selection for AI Agents & Developers
+
+Shared tokens support 6 distinct design aesthetics. `MetricCard` accepts `stylePreset` directly; other components can use `getStylePreset` for custom wrappers:
+
+| Style Preset | Border & Geometry | Surface & Lighting | Target Aesthetic |
+| :--- | :--- | :--- | :--- |
+| **`minimal`** | `border-border`, `rounded-xl` | Flat monochrome, subtle transitions | shadcn/ui, Linear clean |
+| **`origin`** | `border-border/70`, `rounded-2xl`, inner specular | Subtle gradient cards, micro-shadows | Cal.com, Coss high-craft |
+| **`enterprise`** | `border-border`, `rounded-md`, compact | High data density, structured hierarchy | KeenThemes ReUI, admin ERP |
+| **`glow`** | `border-border/60`, `rounded-2xl` | Radial gradient spotlights, halo beams | ibelick, Web3, AI platforms |
+| **`ios`** | `border-white/10`, `rounded-3xl` | Translucent glass, fluid squircle bounce | Expo mobile, Apple iOS |
+| **`brutalist`** | `border-2 border-foreground`, `rounded-none` | High contrast flat fills, 4px drop shadows | Neo-brutalist, retro bold |
+
+```bash
+# List available style presets:
+python scripts/install-component.py --list-styles
+
+# Install component and include the shared style tokens:
+python scripts/install-component.py metric-card --style origin --dest ./src
+# The flag copies lib/styles.ts; it does not rewrite component class names.
+```
+
+Read [`references/guides/style-presets.md`](./references/guides/style-presets.md) for complete token documentation.
+
+---
+
+## Installation & Setup Guide
+
+### Universal Agent Setup (Auto-Detect)
+
+The fastest way to connect and configure Motion UI for **Claude Code, Cursor, Windsurf, Codex, Antigravity, OpenCode, and GitHub Copilot**:
+
+```bash
+npx motion-ui-skill
+```
+
+The installer auto-detects supported AI harnesses and configures the skill and agent rules for you.
+
+- **Auto-Update on Activation**: Every time the skill is activated, it quickly verifies the upstream version and auto-updates in place so physics tokens and component catalogs stay current.
+- **Manual update check**: `npx motion-ui-skill update` (or `node bin/updater.mjs`)
+
+---
+
+### Manual Harness Setup
+
+#### A. Google Antigravity
+This repository is pre-configured with workspace skill discovery:
+- Clone or copy into your workspace's `.agents/skills/motion-ui`:
+  ```bash
+  git clone https://github.com/Rkj0123/motion-ui-skill.git .agents/skills/motion-ui
+  ```
+- Antigravity automatically detects the skill and activates it whenever you ask for UI components, animations, or agent interfaces.
+
+#### B. Codex app or Codex CLI
+Recommended project-scoped install:
+```bash
+npx skills add Rkj0123/motion-ui-skill --skill motion-ui --agent codex --copy -y
+```
+This creates `.agents/skills/motion-ui` in the current project. For a global install visible in every project:
+```bash
+npx skills add Rkj0123/motion-ui-skill --skill motion-ui --agent codex --global --copy -y
+```
+
+---
+
+## CLI Component Installer
+
+A standalone Python resolver and installer is included in `scripts/install-component.py`:
+
+#### List all 339 components:
+```bash
+python scripts/install-component.py --list
+```
+
+#### List available aesthetic styles:
+```bash
+python scripts/install-component.py --list-styles
+```
+
+#### Search components by keyword:
+```bash
+python scripts/install-component.py --search "kanban"
+python scripts/install-component.py --search "agent"
+```
+
+#### Inspect component files & dependencies:
+```bash
+python scripts/install-component.py spotlight-card --info
+```
+
+#### Install a component into your project:
+```bash
+python scripts/install-component.py spotlight-card --style glow --dest ./src
+```
+This automatically:
+1. Copies the component file to `./src/components/motion/spotlight-card.tsx`.
+2. Copies all required utilities (`lib/ease.ts`, `lib/utils.ts`, `lib/hooks/...`) to `./src/lib/`.
+3. With `--style`, also copies `lib/styles.ts` and its `lib/ease.ts` dependency.
+4. Outputs the exact `npm install` command for any missing dependencies.
+
+---
+
+## Prerequisites for Projects
+
+Ensure your target React or Next.js project has the base dependencies installed:
+
+```bash
+npm install motion@^13.1.0 clsx tailwind-merge lucide-react
+# or: pnpm add motion@^13.1.0 clsx tailwind-merge lucide-react
+```
+
+### Tailwind Configuration
+Ensure your `tailwind.config.js` or `globals.css` supports CSS variable colors (`background`, `foreground`, `muted`, `border`, etc.). The canonical `cn` helper is provided in [`lib/utils.ts`](./lib/utils.ts).
+
+---
+
+## Component Catalog (339 Components)
+
+### 1. Motion Components (80)
+
+| Component | Slug | Description | Dependencies | Primary File | Docs |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **Action Swap** | `action-swap` | CTA button and slot primitives for swapping text and icons with blur motion. | `lucide-react`, `motion` | [`components/motion/action-swap.tsx`](components/motion/action-swap.tsx) | [Guide](references/motion/action-swap.md) |
+| **Adaptive Stepper** | `adaptive-stepper` | Composable numeric stepper whose fixed footprint adapts at its minimum and maximum while the value rolls between steps. | `lucide-react`, `motion` | [`components/motion/adaptive-stepper.tsx`](components/motion/adaptive-stepper.tsx) | [Guide](references/motion/adaptive-stepper.md) |
+| **Animated Badge** | `animated-badge` | Status badge with animated state icons, pulse feedback and compact size variants. | `lucide-react`, `motion` | [`components/motion/animated-badge.tsx`](components/motion/animated-badge.tsx) | [Guide](references/motion/animated-badge.md) |
+| **Animated Context Menu** | `context-menu` | Composable context-menu primitives with a pointer-origin clip morph, a gliding active row, checkbox and radio choices, keyboard navigation, typeahead, and long-press support. | `lucide-react`, `motion`, `react-dom` | [`components/motion/context-menu.tsx`](components/motion/context-menu.tsx) | [Guide](references/motion/context-menu.md) |
+| **Animated CTA Buttons** | `expanding-arrow-button` | Expressive call-to-action buttons with expanding, hold, and slide interactions. | `motion` | [`components/motion/expanding-arrow-button.tsx`](components/motion/expanding-arrow-button.tsx) | [Guide](references/motion/expanding-arrow-button.md) |
+| **Animated Sidebar** | `animated-sidebar` | A composable application sidebar with morphing nested navigation that folds into an animated icon rail on desktop and becomes a focus-managed sheet on mobile. | `lucide-react`, `motion`, `react-dom` | [`components/motion/animated-sidebar.tsx`](components/motion/animated-sidebar.tsx) | [Guide](references/motion/animated-sidebar.md) |
+| **Animated Toast Stack** | `animated-toast-stack` | Stacked toasts with status morphs, swipe dismissal, actions and layout-aware motion. | `lucide-react`, `motion`, `react-dom` | [`components/motion/animated-toast-stack.tsx`](components/motion/animated-toast-stack.tsx) | [Guide](references/motion/animated-toast-stack.md) |
+| **Aspect Ratio** | `aspect-ratio` | Adaptive aspect ratio container with smooth geometry transitions when switching ratios and zero cumulative layout shift. | `motion` | [`components/motion/aspect-ratio.tsx`](components/motion/aspect-ratio.tsx) | [Guide](references/motion/aspect-ratio.md) |
+| **Autocomplete** | `autocomplete` | Searchable combobox with substring highlighting, keyboard arrow navigation, clear trigger, and spring panel reveal. | `lucide-react`, `motion` | [`components/motion/autocomplete.tsx`](components/motion/autocomplete.tsx) | [Guide](references/motion/autocomplete.md) |
+| **Avatar Group** | `avatar-group` | Interactive stacked avatar pile where hovering an avatar springs it forward while adjacent neighbors fan out with distance falloff. | `motion` | [`components/motion/avatar-group.tsx`](components/motion/avatar-group.tsx) | [Guide](references/motion/avatar-group.md) |
+| **Bottom Sheet** | `bottom-sheet` | Vaul-inspired draggable bottom sheet with snap points, inertia and glass surface. | `motion`, `react-dom` | [`components/motion/bottom-sheet.tsx`](components/motion/bottom-sheet.tsx) | [Guide](references/motion/bottom-sheet.md) |
+| **Bounce Sidebar** | `bounce-sidebar` | A vertical sidebar whose active dot jumps between destinations on a curved, spring-loaded path. | `motion` | [`components/motion/bounce-sidebar.tsx`](components/motion/bounce-sidebar.tsx) | [Guide](references/motion/bounce-sidebar.md) |
+| **Bouncy Accordion** | `bouncy-accordion` | Single-open accordion with weighted spring layout, icon rows and reduced-motion-safe content reveals. | `lucide-react`, `motion` | [`components/motion/bouncy-accordion.tsx`](components/motion/bouncy-accordion.tsx) | [Guide](references/motion/bouncy-accordion.md) |
+| **Breadcrumb** | `breadcrumb` | Accessible hierarchical navigation trail with animated item insertions, collapsed dropdown menu, and spring hover highlights. | `lucide-react`, `motion` | [`components/motion/breadcrumb.tsx`](components/motion/breadcrumb.tsx) | [Guide](references/motion/breadcrumb.md) |
+| **Button** | `button` | Spring-pressed Button plus StatefulButton, MagneticButton, and MetallicButton variants. | `lucide-react`, `motion` | [`components/motion/button/index.tsx`](components/motion/button/index.tsx) | [Guide](references/motion/button.md) |
+| **Card Resize (Morph)** | `card-resize` | Expanding card container that morphs seamlessly from a compact card to an expanded modal dialog using shared layoutId physics. | `lucide-react`, `motion` | [`components/motion/card-resize.tsx`](components/motion/card-resize.tsx) | [Guide](references/motion/card-resize.md) |
+| **Cascader** | `cascader` | Multi-level cascading drill-down selector with sliding column transitions, breadcrumb trails, instant global search, and keyboard navigation. | `lucide-react`, `motion` | [`components/motion/cascader.tsx`](components/motion/cascader.tsx) | [Guide](references/motion/cascader.md) |
+| **Center Morph Modal** | `center-morph-modal` | A composable modal whose full-size surface unfolds from its exact center toward every edge, then folds back the same way with an inset close control. | `lucide-react`, `motion`, `react-dom` | [`components/motion/center-morph-modal.tsx`](components/motion/center-morph-modal.tsx) | [Guide](references/motion/center-morph-modal.md) |
+| **Checkbox** | `checkbox` | Form choice control with a draw-on checkmark, spring press feedback and indeterminate state support. | `motion` | [`components/motion/checkbox.tsx`](components/motion/checkbox.tsx) | [Guide](references/motion/checkbox.md) |
+| **Chip** | `chip` | Interactive filter chip and badge with removable dismissal animation, selection toggle, and status dot. | `lucide-react`, `motion` | [`components/motion/chip.tsx`](components/motion/chip.tsx) | [Guide](references/motion/chip.md) |
+| **Collapsible** | `collapsible` | Interactive disclosure panel with smooth spring height animation, rotating trigger icon, and zero layout shift. | `lucide-react`, `motion` | [`components/motion/collapsible.tsx`](components/motion/collapsible.tsx) | [Guide](references/motion/collapsible.md) |
+| **Color Picker** | `color-picker` | Interactive hex/rgb color selector with preset swatches, native eyedropper API integration, spring popover, and one-click copy. | `lucide-react`, `motion` | [`components/motion/color-picker.tsx`](components/motion/color-picker.tsx) | [Guide](references/motion/color-picker.md) |
+| **Combobox** | `combobox` | Searchable combobox with a morphing portal, grouped filtering, keyboard navigation, and controlled or uncontrolled state. | `lucide-react`, `motion`, `react-dom` | [`components/motion/combobox.tsx`](components/motion/combobox.tsx) | [Guide](references/motion/combobox.md) |
+| **Confetti** | `confetti` | Hardware-accelerated celebratory particle burst with realistic air-resistance physics, rotations, and color palettes. | `motion` | [`components/motion/confetti.tsx`](components/motion/confetti.tsx) | [Guide](references/motion/confetti.md) |
+| **Copy Button** | `copy-button` | One-click clipboard copy button with spring checkmark morph, haptic confirmation, and tooltip feedback. | `lucide-react`, `motion` | [`components/motion/copy-button.tsx`](components/motion/copy-button.tsx) | [Guide](references/motion/copy-button.md) |
+| **Cylinder Carousel** | `cylinder-carousel` | A carousel whose items line the inside of a cylinder, receding into the center and growing toward the edges. Drag, scroll or arrow-key to roll it, with a springy glide and snap. Reduced-motion drops the glide. | `@paper-design/shaders-react`, `motion` | [`components/motion/cylinder-carousel.tsx`](components/motion/cylinder-carousel.tsx) | [Guide](references/motion/cylinder-carousel.md) |
+| **Date Range Picker** | `date-range-picker` | Interactive calendar popover for selecting start and end date ranges with preset shortcuts, month navigation, and spring micro-interactions. | `lucide-react`, `motion` | [`components/motion/date-range-picker.tsx`](components/motion/date-range-picker.tsx) | [Guide](references/motion/date-range-picker.md) |
+| **Dock** | `dock` | macOS-style dock with grouped actions and a gliding active pill. | `lucide-react`, `motion` | [`components/motion/dock.tsx`](components/motion/dock.tsx) | [Guide](references/motion/dock.md) |
+| **Drawer** | `drawer` | Side panel that slides in from the left or right with a spring, backdrop blur, body scroll lock and esc-to-close. | `motion` | [`components/motion/drawer.tsx`](components/motion/drawer.tsx) | [Guide](references/motion/drawer.md) |
+| **Error Shake** | `error-shake` | Damped oscillation shake wrapper with haptic error vibration feedback and configurable intensity for form validations. | `motion` | [`components/motion/error-shake.tsx`](components/motion/error-shake.tsx) | [Guide](references/motion/error-shake.md) |
+| **Expandable Control** | `expandable-control` | Click-to-expand button and chip controls that reveal a label or trailing action through spring layout continuity. | `lucide-react`, `motion` | [`components/motion/expandable-control.tsx`](components/motion/expandable-control.tsx) | [Guide](references/motion/expandable-control.md) |
+| **File Tree** | `file-tree` | Composable file and folder primitives with springing branches, a gliding selection, and complete keyboard navigation. | `lucide-react`, `motion` | [`components/motion/file-tree.tsx`](components/motion/file-tree.tsx) | [Guide](references/motion/file-tree.md) |
+| **Glow Button** | `glow-button` | Premium CTA button featuring an iridescent glowing perimeter gradient, magnetic pointer attraction, and tactile spring feedback. | `motion` | [`components/motion/glow-button.tsx`](components/motion/glow-button.tsx) | [Guide](references/motion/glow-button.md) |
+| **Haptic Pressable** | `haptic-pressable` | Universal touch-first interactive wrapper with physical spring compression, semantic vibration feedback, and hover guards. | `motion` | [`components/motion/haptic-pressable.tsx`](components/motion/haptic-pressable.tsx) | [Guide](references/motion/haptic-pressable.md) |
+| **Hover Card** | `hover-card` | Rich contextual hover card popover with open/close delay buffering, spring entrance, and collision avoidance. | `motion` | [`components/motion/hover-card.tsx`](components/motion/hover-card.tsx) | [Guide](references/motion/hover-card.md) |
+| **Icon Stack** | `icon-stack` | Overlapping icon and avatar cluster with hover fan-out expansion, spring elevation, and automated tooltip reveals. | `motion` | [`components/motion/icon-stack.tsx`](components/motion/icon-stack.tsx) | [Guide](references/motion/icon-stack.md) |
+| **Input** | `input` | Text input with label, left/right icons, optional stable error row, error shake and success check draw. | `lucide-react`, `motion` | [`components/motion/input.tsx`](components/motion/input.tsx) | [Guide](references/motion/input.md) |
+| **Keyboard Keycap** | `kbd` | Hardware-styled keyboard shortcut cap with OS auto-detection (macOS ⌘ vs Windows Ctrl), key combination joins, and tactile spring press feedback. | `motion` | [`components/motion/kbd.tsx`](components/motion/kbd.tsx) | [Guide](references/motion/kbd.md) |
+| **Loader** | `loader` | Loading indicator with seventeen variants: spinner, dots, bars, dot-matrix, dither, morph, comet, scramble, metaballs, newton, helix, percent, and five terminal-style ascii spinners. Scales from one size prop, uses currentColor, and reduced-motion swaps every transform for a calm opacity pulse. | `motion` | [`components/motion/loader.tsx`](components/motion/loader.tsx) | [Guide](references/motion/loader.md) |
+| **Magnet Dock** | `magnet-dock` | Interactive application dock whose icons magnify continuously based on pointer proximity using spring physics and motion values. | `motion` | [`components/motion/magnet-dock.tsx`](components/motion/magnet-dock.tsx) | [Guide](references/motion/magnet-dock.md) |
+| **Marquee** | `marquee` | Infinite horizontal or vertical scroll with pause-on-hover. | None (core) | [`components/motion/marquee.tsx`](components/motion/marquee.tsx) | [Guide](references/motion/marquee.md) |
+| **Morphing Modal** | `morphing-modal` | Family-app-style modal. A single panel that morphs its height as you navigate between inner views, with blur cross-fade on content. | `lucide-react`, `motion` | [`components/motion/morphing-modal.tsx`](components/motion/morphing-modal.tsx) | [Guide](references/motion/morphing-modal.md) |
+| **Multi Select** | `multi-select` | Composable multi-select primitives with searchable options, removable animated tokens, and a morphing collision-aware panel. | `lucide-react`, `motion`, `react-dom` | [`components/motion/multi-select/index.tsx`](components/motion/multi-select/index.tsx) | [Guide](references/motion/multi-select.md) |
+| **Number Animation** | `number` | Animated number primitives for count-up values, rolling tickers, and fixed-slot digit swaps. | `motion` | [`components/motion/animated-number.tsx`](components/motion/animated-number.tsx) | [Guide](references/motion/number.md) |
+| **Number Field** | `number-field` | Precision numeric stepper input with increment/decrement hold acceleration, rolling number animation, and min/max limits. | `lucide-react`, `motion` | [`components/motion/number-field.tsx`](components/motion/number-field.tsx) | [Guide](references/motion/number-field.md) |
+| **Page Transition** | `page-transition` | Composable page and view transition container supporting fade, slide, scale, push, and 3D flip modes with AnimatePresence. | `motion` | [`components/motion/page-transition.tsx`](components/motion/page-transition.tsx) | [Guide](references/motion/page-transition.md) |
+| **Pagination** | `pagination` | Accessible multi-page navigation bar with sliding active page pill, ellipsis jumps, and previous/next page triggers. | `lucide-react`, `motion` | [`components/motion/pagination.tsx`](components/motion/pagination.tsx) | [Guide](references/motion/pagination.md) |
+| **Password Input** | `password-input` | Smart password field with show/hide toggle, animated multi-segment strength meter, and live criteria validation checklist. | `lucide-react`, `motion` | [`components/motion/password-input.tsx`](components/motion/password-input.tsx) | [Guide](references/motion/password-input.md) |
+| **Phone Input** | `phone-input` | International phone number input with search-filtered country selector dropdown, flags, dial codes, and spring transitions. | `lucide-react`, `motion` | [`components/motion/phone-input.tsx`](components/motion/phone-input.tsx) | [Guide](references/motion/phone-input.md) |
+| **Popover** | `popover` | Gooey popover whose panel oozes out of the trigger through an SVG goo filter — a liquid neck that stretches and pinches — with crisp content fading in on top, plus a Morph variant that clip-morphs open from the trigger corner. Click or hover trigger, controlled or uncontrolled. | `lucide-react`, `motion`, `react-dom` | [`components/motion/popover.tsx`](components/motion/popover.tsx) | [Guide](references/motion/popover.md) |
+| **Preview Rail** | `preview-rail` | Codex app-inspired navigation rail with compact ticks that form a hover pyramid and reveal a floating destination preview. | `motion` | [`components/motion/preview-rail.tsx`](components/motion/preview-rail.tsx) | [Guide](references/motion/preview-rail.md) |
+| **Progress Ring** | `progress-ring` | Circular animated SVG progress gauge with spring stroke dashoffset, customizable gradient stroke, and center label. | `motion` | [`components/motion/progress-ring.tsx`](components/motion/progress-ring.tsx) | [Guide](references/motion/progress-ring.md) |
+| **Pull to Refresh** | `pull-to-refresh` | Native-feeling pull-to-refresh container with drag resistance, threshold feedback and async refresh handling. | `lucide-react`, `motion` | [`components/motion/pull-to-refresh.tsx`](components/motion/pull-to-refresh.tsx) | [Guide](references/motion/pull-to-refresh.md) |
+| **Radio Group** | `radio` | Single-select choice control with a gliding layoutId indicator dot and spring press feedback. | `motion` | [`components/motion/radio.tsx`](components/motion/radio.tsx) | [Guide](references/motion/radio.md) |
+| **Range Slider** | `range-slider` | Slider with tick dots and a vertical-bar thumb that bounces as it lands on each step. Drag or keyboard, reduced-motion safe. | `motion` | [`components/motion/range-slider.tsx`](components/motion/range-slider.tsx) | [Guide](references/motion/range-slider.md) |
+| **Rating** | `rating` | Interactive star rating component with half-star fractional hover detection, spring bounce micro-interactions on click, and keyboard accessibility. | `lucide-react`, `motion` | [`components/motion/rating.tsx`](components/motion/rating.tsx) | [Guide](references/motion/rating.md) |
+| **Scroll Animation** | `scroll-animation` | Scroll-driven motion: a Lenis smooth-scroll provider and a reading-progress indicator that reads from it. | `lenis`, `motion` | [`components/motion/smooth-scroll.tsx`](components/motion/smooth-scroll.tsx) | [Guide](references/motion/scroll-animation.md) |
+| **Segmented Control** | `segmented-control` | iOS / macOS-style segmented pill selector with continuous sliding layoutId spring indicator and haptic touch. | `motion` | [`components/motion/segmented-control.tsx`](components/motion/segmented-control.tsx) | [Guide](references/motion/segmented-control.md) |
+| **Segmented Progress** | `segmented-progress` | Instagram / WhatsApp Stories-style segmented progress bar with auto-advancing timers, pause on hold, and step jumps. | `motion` | [`components/motion/segmented-progress.tsx`](components/motion/segmented-progress.tsx) | [Guide](references/motion/segmented-progress.md) |
+| **Select** | `select` | Composable select primitives whose panel bouncily unfolds out of the trigger and separates, plus a Morph variant where the trigger grows into the panel via shared layout. | `lucide-react`, `motion` | [`components/motion/select.tsx`](components/motion/select.tsx) | [Guide](references/motion/select.md) |
+| **Shader Background** | `shader-background` | Canvas shader backgrounds (mesh gradient, grain, warp, waves, voronoi, dot orbit and more) with a single typed variant prop. Reduced-motion freezes animated variants. | `@paper-design/shaders-react`, `motion` | [`components/motion/shader-background.tsx`](components/motion/shader-background.tsx) | [Guide](references/motion/shader-background.md) |
+| **Shared Layout Background** | `shared-layout-bg` | A pill that glides between hovered items via motion's shared layout, with blur enter/exit. | `lucide-react`, `motion` | [`components/motion/shared-layout-bg.tsx`](components/motion/shared-layout-bg.tsx) | [Guide](references/motion/shared-layout-bg.md) |
+| **Sortable List** | `sortable-list` | Accessible drag-to-reorder list with drag handle controls, shadow elevation, layout spring realignment, and drop callbacks. | `lucide-react`, `motion` | [`components/motion/sortable-list.tsx`](components/motion/sortable-list.tsx) | [Guide](references/motion/sortable-list.md) |
+| **Speed Dial** | `speed-dial` | Mobile-first floating action button (FAB) that blossoms outwards with staggered action items, 45-degree icon morph, and haptic feedback. | `lucide-react`, `motion` | [`components/motion/speed-dial.tsx`](components/motion/speed-dial.tsx) | [Guide](references/motion/speed-dial.md) |
+| **Split Text** | `split-text` | High-performance typography reveal that splits sentences into characters or words with staggered spring entrances. | `motion` | [`components/motion/split-text.tsx`](components/motion/split-text.tsx) | [Guide](references/motion/split-text.md) |
+| **Spotlight Card** | `spotlight-card` | Interactive craft card with mouse-tracking radial spotlight glow, rotating border beam highlight, and subtle depth elevation. | `motion` | [`components/motion/spotlight-card.tsx`](components/motion/spotlight-card.tsx) | [Guide](references/motion/spotlight-card.md) |
+| **Stepper** | `stepper` | Multi-step wizard progress indicator with animated connecting lines, completed checkmarks, and active status indicators. | `lucide-react`, `motion` | [`components/motion/stepper.tsx`](components/motion/stepper.tsx) | [Guide](references/motion/stepper.md) |
+| **Success Check** | `success-check` | Celebration confirmation micro-interaction featuring an expanding circle halo, spring pop-in, SVG path draw checkmark, and haptic feedback. | `motion` | [`components/motion/success-check.tsx`](components/motion/success-check.tsx) | [Guide](references/motion/success-check.md) |
+| **Switch** | `switch` | Toggle with a spring-driven thumb and press feedback. | `motion` | [`components/motion/switch.tsx`](components/motion/switch.tsx) | [Guide](references/motion/switch.md) |
+| **Table** | `table` | Virtualized data table that stays smooth at 10k+ rows, with sortable headers, row selection, column resize and reorder, and a sticky header. Minimal, reduced-motion-safe motion. | `@tanstack/react-virtual`, `lucide-react`, `motion`, `react-dom` | [`components/motion/table/index.tsx`](components/motion/table/index.tsx) | [Guide](references/motion/table.md) |
+| **Tabs** | `tabs` | Pill, segment or underline tabs with a spring layoutId indicator. | `motion` | [`components/motion/tabs.tsx`](components/motion/tabs.tsx) | [Guide](references/motion/tabs.md) |
+| **Text Animation** | `text-animation` | Animated text primitives for spring reveals, chromatic sweeps, shimmer loading states, letter-cascade swaps and character scrambles. | `motion` | [`components/motion/text-reveal.tsx`](components/motion/text-reveal.tsx) | [Guide](references/motion/text-animation.md) |
+| **Text Swap** | `text-swap` | Slot-machine vertical ticker transition that rolls text or numbers with subtle blur and spring velocity handoffs. | `motion` | [`components/motion/text-swap.tsx`](components/motion/text-swap.tsx) | [Guide](references/motion/text-swap.md) |
+| **Theme Toggle** | `theme-toggle` | Theme toggle button that repaints the whole page through the View Transition API — a rectangle or circle clip-path reveal, or slats that open across the screen like a shutter. | `lucide-react`, `motion`, `next-themes` | [`components/motion/theme-toggle.tsx`](components/motion/theme-toggle.tsx) | [Guide](references/motion/theme-toggle.md) |
+| **Tilt Card** | `tilt-card` | 3D perspective tilt on hover with cursor-tracked glare. | `motion` | [`components/motion/tilt-card.tsx`](components/motion/tilt-card.tsx) | [Guide](references/motion/tilt-card.md) |
+| **Timeline** | `timeline` | Interactive chronological milestone and audit tracker with animated progress lines, status badges, and expandable step disclosures. | `lucide-react`, `motion` | [`components/motion/timeline.tsx`](components/motion/timeline.tsx) | [Guide](references/motion/timeline.md) |
+| **Toggle Group** | `toggle-group` | Multi-item selection toggle bar supporting single and multiple choice modes with sliding layout springs. | `motion` | [`components/motion/toggle-group.tsx`](components/motion/toggle-group.tsx) | [Guide](references/motion/toggle-group.md) |
+| **Tooltip** | `tooltip` | Hover or focus tooltip with blur enter/exit and spring spawn. | `lucide-react`, `motion`, `react-dom` | [`components/motion/tooltip.tsx`](components/motion/tooltip.tsx) | [Guide](references/motion/tooltip.md) |
+| **Tree View** | `tree-view` | Hierarchical nested folder tree with animated node collapse/expand, file type icons, selection highlights, and keyboard navigation. | `lucide-react`, `motion` | [`components/motion/tree-view.tsx`](components/motion/tree-view.tsx) | [Guide](references/motion/tree-view.md) |
+| **Wheel Picker** | `wheel-picker` | iOS-style picker wheel: a 3D drum on native momentum scroll that snaps to the nearest notch, with wheel, drag and keyboard control. Composes side by side for date and time pickers, reduced-motion safe. | `motion` | [`components/motion/wheel-picker.tsx`](components/motion/wheel-picker.tsx) | [Guide](references/motion/wheel-picker.md) |
+
+---
+
+### 2. AI Agent Surfaces (17)
+
+| Component | Slug | Description | Dependencies | Primary File | Docs |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **Agent Activity** | `agent-activity` | One adaptive activity stream for reasoning, searches, tool calls, structured execution traces, or a chronological mix. | `lucide-react`, `motion` | [`components/agents/agent-activity/index.tsx`](components/agents/agent-activity/index.tsx) | [Guide](references/agents/agent-activity.md) |
+| **Agent Loading States** | `loading-states` | Three thoughtful loading states for AI interfaces: shimmering status text, live agent progress, and cycling reasoning phrases. | `motion` | [`components/agents/loading-states/index.ts`](components/agents/loading-states/index.ts) | [Guide](references/agents/loading-states.md) |
+| **AI Sidebar** | `ai-sidebar` | A collapsible AI workspace sidebar for folders, projects, files, and bookmarks with keyboard navigation, optimistic moves, inline rename, and overflow-aware labels. | `lucide-react`, `motion`, `react-dom` | [`components/agents/ai-sidebar.tsx`](components/agents/ai-sidebar.tsx) | [Guide](references/agents/ai-sidebar.md) |
+| **Approval Card** | `approval-card` | A human-in-the-loop decision surface for approvals, single or multiple-choice questions, custom responses, and multi-step review flows. | `lucide-react`, `motion` | [`components/agents/approval-card/index.tsx`](components/agents/approval-card/index.tsx) | [Guide](references/agents/approval-card.md) |
+| **Chat App** | `chat-app` | A complete agent conversation workspace composing navigation, messages, streaming, planning, approvals, tools, code, diffs, generated media, sources, and prompt input. | `lucide-react`, `motion`, `react-dom`, `shiki` | [`components/agents/chat-app.tsx`](components/agents/chat-app.tsx) | [Guide](references/agents/chat-app.md) |
+| **Citations** | `citations` | Inline citation markers paired with a collapsible, progressively rendered reference collection for grounded agent responses. | `lucide-react`, `motion` | [`components/agents/citations.tsx`](components/agents/citations.tsx) | [Guide](references/agents/citations.md) |
+| **Code Block** | `code-block` | A syntax-highlighted code surface with stable streaming updates, line numbers, focused lines, smooth following, and copy feedback. | `ai`, `lucide-react`, `motion`, `shiki` | [`components/agents/code-block.tsx`](components/agents/code-block.tsx) | [Guide](references/agents/code-block.md) |
+| **File Diff** | `file-diff` | A syntax-highlighted file change disclosure with progressive rows, line numbers, live change counts, smooth following, and completion collapse. | `lucide-react`, `motion`, `shiki` | [`components/agents/file-diff.tsx`](components/agents/file-diff.tsx) | [Guide](references/agents/file-diff.md) |
+| **Image Generation** | `image-generation` | A stable generated-image surface that moves from queued work through progressive refinement to a completed result without layout shift. | `lucide-react`, `motion` | [`components/agents/image-generation.tsx`](components/agents/image-generation.tsx) | [Guide](references/agents/image-generation.md) |
+| **Message** | `message` | Composable conversation primitives for message rows, grouped bubbles, avatars, metadata, live markers, and a mount-only trailing-edge pop-up for newly sent rows. | `lucide-react`, `motion`, `react-dom` | [`components/agents/message.tsx`](components/agents/message.tsx) | [Guide](references/agents/message.md) |
+| **Message Bubble** | `message-bubble` | A focused conversational surface with visual tones, independent alignment, grouped messages, expandable content, and interactive link or button support. | `lucide-react`, `motion`, `react-dom` | [`components/agents/message-bubble.tsx`](components/agents/message-bubble.tsx) | [Guide](references/agents/message-bubble.md) |
+| **Message Scroller** | `message-scroller` | A reader-aware conversation viewport that follows streamed output at the live edge and releases control when the reader moves away. | `lucide-react`, `motion`, `react-dom` | [`components/agents/message-scroller.tsx`](components/agents/message-scroller.tsx) | [Guide](references/agents/message-scroller.md) |
+| **Prompt Input** | `prompt-input` | An auto-growing agent composer with prompt actions, model selection, keyboard submission, and animated send and stop states. | `lucide-react`, `motion`, `react-dom` | [`components/agents/prompt-input.tsx`](components/agents/prompt-input.tsx) | [Guide](references/agents/prompt-input.md) |
+| **Streaming Response** | `streaming-response` | A stable response surface with completion actions, rendered content, and an expandable source summary. | `lucide-react`, `motion` | [`components/agents/streaming-response.tsx`](components/agents/streaming-response.tsx) | [Guide](references/agents/streaming-response.md) |
+| **Todo List** | `todo-list` | A collapsible agent task plan with morphing status marks, a completion count, compact metadata, and smooth list updates. | `lucide-react`, `motion` | [`components/agents/todo-list.tsx`](components/agents/todo-list.tsx) | [Guide](references/agents/todo-list.md) |
+| **Tool Approval** | `tool-approval` | A human-in-the-loop permission card for reviewing tool details, allowing once, remembering access, or denying execution. | `lucide-react`, `motion`, `shiki` | [`components/agents/tool-approval.tsx`](components/agents/tool-approval.tsx) | [Guide](references/agents/tool-approval.md) |
+| **Tool Result** | `tool-result` | A lightweight execution disclosure for syntax-highlighted terminal output and request responses that collapses into a compact completed state. | `lucide-react`, `motion`, `shiki` | [`components/agents/tool-result.tsx`](components/agents/tool-result.tsx) | [Guide](references/agents/tool-result.md) |
+
+---
+
+### 3. Blocks & Widgets (33)
+
+| Component | Slug | Description | Dependencies | Primary File | Docs |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **404 / Not Found** | `not-found` | Animated 404 pages in five styles: glitch scramble, magnetic digits, cursor spotlight, a fanning card stack and a typed terminal. | `motion` | [`components/motion/not-found/index.tsx`](components/motion/not-found/index.tsx) | [Guide](references/blocks/not-found.md) |
+| **Action Sheet** | `action-sheet` | Universal mobile action sheet menu with drag gesture dismissal, rubber-band resistance, haptic feedback, and desktop center modal fallback. | `motion`, `react-dom` | [`components/motion/action-sheet.tsx`](components/motion/action-sheet.tsx) | [Guide](references/motion/action-sheet.md) |
+| **Audio Player** | `audio-player` | Interactive audio player with animated equalizer waveforms, spring play/pause morphs, volume controls, and scrubbing trackbar. | `lucide-react`, `motion` | [`components/motion/audio-player.tsx`](components/motion/audio-player.tsx) | [Guide](references/motion/audio-player.md) |
+| **Availability Scheduler** | `availability-scheduler` | Weekly availability editor where each day springs between available and unavailable, time ranges add and remove with blur-slide motion, times pick from a scrollable dropdown, and a copy menu clones hours to other days. | `lucide-react`, `motion`, `react-dom` | [`components/motion/availability-scheduler/index.tsx`](components/motion/availability-scheduler/index.tsx) | [Guide](references/blocks/availability-scheduler.md) |
+| **Bloom Menu** | `bloom-menu` | A button that morphs open into a menu and blooms iris-out from the center, the grid revealing in every direction with radially staggered items. | `lucide-react`, `motion` | [`components/motion/bloom-menu.tsx`](components/motion/bloom-menu.tsx) | [Guide](references/blocks/bloom-menu.md) |
+| **Card Folder** | `card-folder` | A landscape card tucked into a stitched purse pocket that lifts forward as the purse compresses into its bottom seam, with controlled open and card-detail visibility plus a separate overflow action. | `lucide-react`, `motion` | [`components/motion/card-folder.tsx`](components/motion/card-folder.tsx) | [Guide](references/blocks/card-folder.md) |
+| **Command Palette** | `command-palette` | ⌘K palette with fuzzy filter, spring-animated active row and glass surface. | `lucide-react`, `motion`, `react-dom` | [`components/motion/command-palette.tsx`](components/motion/command-palette.tsx) | [Guide](references/blocks/command-palette.md) |
+| **Dynamic Island** | `dynamic-island` | iOS-style island pill that morphs between live activity views with bouncy shell resize and blur crossfades. | `lucide-react`, `motion` | [`components/motion/dynamic-island.tsx`](components/motion/dynamic-island.tsx) | [Guide](references/blocks/dynamic-island.md) |
+| **Event Calendar** | `event-calendar` | Full-featured interactive scheduling calendar with month/week views, animated day cells, event pills, and popover creation. | `lucide-react`, `motion` | [`components/motion/event-calendar.tsx`](components/motion/event-calendar.tsx) | [Guide](references/motion/event-calendar.md) |
+| **Expandable Action Bar** | `expandable-action-bar` | Compact icon actions that expand into labeled controls on hover or focus with shared layout motion. | `lucide-react`, `motion` | [`components/motion/expandable-action-bar.tsx`](components/motion/expandable-action-bar.tsx) | [Guide](references/blocks/expandable-action-bar.md) |
+| **Expandable Tabs** | `expandable-tabs` | Icon tab bar where the active tab expands to a labelled pill, with a panel above that morphs height and slides content direction-aware on switch. | `lucide-react`, `motion` | [`components/motion/expandable-tabs.tsx`](components/motion/expandable-tabs.tsx) | [Guide](references/blocks/expandable-tabs.md) |
+| **Feedback Widget** | `feedback-widget` | Corner trigger that morphs open into a feedback popup with message entry and animated sending, success and retry states. | `lucide-react`, `motion` | [`components/motion/feedback-widget.tsx`](components/motion/feedback-widget.tsx) | [Guide](references/blocks/feedback-widget.md) |
+| **File Upload** | `file-upload` | Two file upload patterns: an attachment workspace for mixed files, links, audio and media, plus a progress queue with retry and removal. | `lucide-react`, `motion`, `react-dom` | [`components/motion/file-upload.tsx`](components/motion/file-upload.tsx) | [Guide](references/blocks/file-upload.md) |
+| **Filter Builder** | `filter-builder` | Faceted stepped query filter builder with dynamic attribute selectors, operator dropdowns, AND/OR logic toggles, and animated chip tags. | `lucide-react`, `motion` | [`components/motion/filter-builder.tsx`](components/motion/filter-builder.tsx) | [Guide](references/motion/filter-builder.md) |
+| **Fixtures** | `knockout-bracket` | Animated tournament fixtures in two styles: a knockout bracket that pages through rounds, and a wheel that wraps the same tree around the champion. Both read the same array of rounds, so one dataset draws either. | `lucide-react`, `motion`, `react-dom` | [`components/motion/knockout-bracket.tsx`](components/motion/knockout-bracket.tsx) | [Guide](references/blocks/knockout-bracket.md) |
+| **Frame** | `frame` | Interactive browser/device mockup frame with viewport size toggles (desktop, tablet, mobile) and smooth layout resizing. | `lucide-react`, `motion` | [`components/motion/frame.tsx`](components/motion/frame.tsx) | [Guide](references/motion/frame.md) |
+| **Gantt Timeline Chart** | `gantt` | Enterprise project management timeline with draggable milestone bars, percentage progress fills, and dependency connections. | `lucide-react`, `motion` | [`components/motion/gantt.tsx`](components/motion/gantt.tsx) | [Guide](references/motion/gantt.md) |
+| **Infinite Masonry** | `infinite-masonry` | Responsive virtualized masonry that measures variable-height cards and loads more data as the user nears the end. | `@tanstack/react-virtual`, `lucide-react`, `motion`, `next` | [`components/motion/infinite-masonry.tsx`](components/motion/infinite-masonry.tsx) | [Guide](references/blocks/infinite-masonry.md) |
+| **Kanban Board** | `kanban` | Interactive drag-and-drop task workflow board with spring layoutId reordering, column drop zones, WIP counters, and priority tags. | `lucide-react`, `motion` | [`components/motion/kanban.tsx`](components/motion/kanban.tsx) | [Guide](references/motion/kanban.md) |
+| **Metric Card** | `metric-card` | KPI stat card with animated SVG sparkline charts, positive/negative delta badges, and full multi-style preset support. | `lucide-react`, `motion` | [`components/motion/metric-card.tsx`](components/motion/metric-card.tsx) | [Guide](references/motion/metric-card.md) |
+| **Morphing Search** | `morphing-search` | Search field or compact icon that morphs into a glass results surface, whether opened by click or keyboard shortcut. | `lucide-react`, `motion`, `react-dom` | [`components/motion/morphing-search.tsx`](components/motion/morphing-search.tsx) | [Guide](references/blocks/morphing-search.md) |
+| **Morphing Tabs** | `morphing-tabs` | Reorderable tabs whose selected item grows into a white content surface, with the active shape gliding as tabs move and a shared morph between rooms. | `lucide-react`, `motion`, `react-dom` | [`components/motion/morphing-tabs.tsx`](components/motion/morphing-tabs.tsx) | [Guide](references/blocks/morphing-tabs.md) |
+| **Multi-chain Swap** | `swap` | Cross-chain swap widget with chain + token selectors, morphing views, animated flip and quote. | `lucide-react`, `motion` | [`components/motion/swap.tsx`](components/motion/swap.tsx) | [Guide](references/blocks/swap.md) |
+| **Notification Stack** | `notification-stack` | Compact notification cards that spring from a stacked summary into a readable list on hover, focus or tap. | `lucide-react`, `motion` | [`components/motion/notification-stack.tsx`](components/motion/notification-stack.tsx) | [Guide](references/blocks/notification-stack.md) |
+| **OTP Input** | `otp-input` | One-time-code input with a gliding focus ring, digits that roll in per slot, error shake and a success check draw. | `motion` | [`components/motion/otp-input.tsx`](components/motion/otp-input.tsx) | [Guide](references/blocks/otp-input.md) |
+| **Overflow Actions** | `overflow-actions` | Connected pill rail for primary actions that springs open to reveal extra controls. | `lucide-react`, `motion` | [`components/motion/overflow-actions.tsx`](components/motion/overflow-actions.tsx) | [Guide](references/blocks/overflow-actions.md) |
+| **Prediction Market** | `prediction-market` | Prediction market trade ticket with buy/sell modes, outcome prices, rolling amount entry, quick add chips and trade states. | `lucide-react`, `motion` | [`components/motion/prediction-market.tsx`](components/motion/prediction-market.tsx) | [Guide](references/blocks/prediction-market.md) |
+| **Project Folder** | `project-folder` | An interactive project folder that opens its file fan on hover or focus, expands into a focus-managed overlay, then retraces the complete path when closed. | `lucide-react`, `motion`, `react-dom` | [`components/motion/project-folder.tsx`](components/motion/project-folder.tsx) | [Guide](references/blocks/project-folder.md) |
+| **Reorder Grid** | `reorder-grid` | Drag-and-drop sortable grid driven by Motion's native Reorder primitives with spring elevation and haptic feedback. | `lucide-react`, `motion` | [`components/motion/reorder-grid.tsx`](components/motion/reorder-grid.tsx) | [Guide](references/motion/reorder-grid.md) |
+| **Resizable Panel** | `resizable-panel` | Accessible multi-direction split container with smooth pointer dragging, keyboard ratio controls, and boundary snapping. | `lucide-react`, `motion` | [`components/motion/resizable-panel.tsx`](components/motion/resizable-panel.tsx) | [Guide](references/motion/resizable-panel.md) |
+| **Sign Up Form** | `signup-form` | Composed sign-up form that flags a field only once it is left, then clears the moment it is fixed, with a length-weighted strength meter, password reveal and an animated submit lifecycle. | `lucide-react`, `motion` | [`components/motion/signup-form.tsx`](components/motion/signup-form.tsx) | [Guide](references/blocks/signup-form.md) |
+| **Swipeable List** | `swipeable-list` | Mobile-style list rows that swipe left or right to reveal contextual action buttons. | `lucide-react`, `motion` | [`components/motion/swipeable-list.tsx`](components/motion/swipeable-list.tsx) | [Guide](references/blocks/swipeable-list.md) |
+| **Wallet Card** | `wallet-card` | Wallet overview card with an account switcher and search that morph open from their triggers, a cascading balance with a live change pill and privacy toggle, copy-address, and Send / Deposit / Swap / Buy actions. | `lucide-react`, `motion` | [`components/motion/wallet-card/index.tsx`](components/motion/wallet-card/index.tsx) | [Guide](references/blocks/wallet-card.md) |
+
+---
+
+### 4. Craft & Surface Components (209)
+
+| Component | Slug | Description | Dependencies | Primary File | Docs |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **Add to Cart** | `add-to-cart-button` | Raised 3D add-to-cart key that sinks in while adding, with gentle label crossfades, then pops back up in a solid emerald added state before resetting. | `lucide-react` | [`components/buttons/add-to-cart-button.tsx`](components/buttons/add-to-cart-button.tsx) | [Guide](references/craft/add-to-cart-button.md) |
+| **Analog Clock — Minimal** | `analog-clock-minimal` | Ticks and hands on a quiet face, nothing else. When you want the time to sit in the background without shouting over your UI. | None (core) | [`components/widgets/analog-clock-widget.tsx`](components/widgets/analog-clock-widget.tsx) | [Guide](references/craft/analog-clock-minimal.md) |
+| **Analog Clock — Numeric** | `analog-clock-numeric` | Arabic numerals and a live second hand on a clean analog dial. Readable from across the room, still far from a default system clock. | None (core) | [`components/widgets/analog-clock-widget.tsx`](components/widgets/analog-clock-widget.tsx) | [Guide](references/craft/analog-clock-numeric.md) |
+| **Analog Clock — Roman** | `analog-clock-roman` | A live analog clock dressed in roman numerals — classic dial, real moving hands. Swap the variant prop to match the mood of your layout. | None (core) | [`components/widgets/analog-clock-widget.tsx`](components/widgets/analog-clock-widget.tsx) | [Guide](references/craft/analog-clock-roman.md) |
+| **Annotated Text** | `annotated-text` | Hand-drawn text annotations — wavy underlines, highlights, arrows, brackets, and more. Pass variant and optional color to style any inline label or callout. | None (core) | [`components/underlines/annotated-text.tsx`](components/underlines/annotated-text.tsx) | [Guide](references/craft/annotated-text.md) |
+| **App Dock** | `app-dock` | Bottom app launcher dock matching MacDock shell, spacing, and hover lift — with active state and optional labels. | `lucide-react` | [`components/docks/app-dock.tsx`](components/docks/app-dock.tsx) | [Guide](references/craft/app-dock.md) |
+| **Apple Browser** | `browser` | Desktop browser chrome with traffic lights and a URL bar framing your website screenshot. Pass theme for light, dark, or transparent chrome. | None (core) | [`components/mockups/browser-mockup-card.tsx`](components/mockups/browser-mockup-card.tsx) | [Guide](references/craft/browser.md) |
+| **Apple Hello Loader** | `apple-hello-loader` | Apple-style greeting loader that cycles through hello, bonjour, hola, and more with a soft fade. Pass greetings, intervalMs, and fadeMs to tune the loop. | None (core) | [`components/loaders/apple-hello-loader.tsx`](components/loaders/apple-hello-loader.tsx) | [Guide](references/craft/apple-hello-loader.md) |
+| **Apple iPad** | `ipad` | iPad Air frame with metallic bezel, top-edge buttons, and a full-screen preview slot. Pass variant for space gray, space black, silver, starlight, blue, purple, pink, or yellow finishes. Use visibleRatio to crop from the top, and showCamera to toggle the front camera dot. | None (core) | [`components/mockups/tablet-mockup-card.tsx`](components/mockups/tablet-mockup-card.tsx) | [Guide](references/craft/ipad.md) |
+| **Apple iPhone** | `phone` | iPhone 15 Pro frame with Dynamic Island and a full-screen preview slot. Pass variant for purple, orange, white, titanium, or cherry finishes. Use visibleRatio to crop from the top, and showDynamicIsland to toggle the island and camera. | None (core) | [`components/mockups/phone-mockup-card.tsx`](components/mockups/phone-mockup-card.tsx) | [Guide](references/craft/phone.md) |
+| **Apple iPod** | `ipod` | Classic iPod frame with a screen slot and click wheel — silver, black, white, pink, blue, green, or red finishes. Drop any UI into the screen area. | None (core) | [`components/mockups/apple-ipod-mockup-card.tsx`](components/mockups/apple-ipod-mockup-card.tsx) | [Guide](references/craft/ipod.md) |
+| **Apple Macbook** | `laptop` | Apple Macbook component. | None (core) | [`components/mockups/laptop-mockup-card.tsx`](components/mockups/laptop-mockup-card.tsx) | [Guide](references/craft/laptop.md) |
+| **Apple Notification** | `apple-notification` | Frosted iOS notification with app name, sender, message, and avatar — dismisses with animation and can be triggered again via button. | `lucide-react`, `next` | [`components/notifications/apple-notification-banner.tsx`](components/notifications/apple-notification-banner.tsx) | [Guide](references/craft/apple-notification.md) |
+| **Apple Watch** | `apple-watch` | Apple Watch frame with sport band and a rounded display slot for your UI. Pass variant for black, silver, titanium, starlight, blue, gold, or rose finishes. | None (core) | [`components/mockups/apple-watch-mockup-card.tsx`](components/mockups/apple-watch-mockup-card.tsx) | [Guide](references/craft/apple-watch.md) |
+| **Arc Bands** | `arc-bands-background` | Retro poster arcs with sky, teal, amber, and rose blending in soft radial gradients from the base — festivals, launches, and playful brand moments. | None (core) | [`components/background-gradient/arc-bands-background.tsx`](components/background-gradient/arc-bands-background.tsx) | [Guide](references/craft/arc-bands-background.md) |
+| **Audio Recorder** | `audio-recorder` | Dark recording card with title, date, animated red waveform, and elapsed time. Play and pause feel like a native voice memo app. | `lucide-react` | [`components/widgets/audio-recorder-widget.tsx`](components/widgets/audio-recorder-widget.tsx) | [Guide](references/craft/audio-recorder.md) |
+| **Aurora Background** | `aurora-background` | Soft aurora wash with lime, mint, cyan, and blue blobs over a warm paper base — wrap any page section or hero and pass children on top. | None (core) | [`components/background-gradient/aurora-background.tsx`](components/background-gradient/aurora-background.tsx) | [Guide](references/craft/aurora-background.md) |
+| **Battery Face** | `battery-face` | Battery level as a character — arc ring, percentage, hours left, and a face that actually looks sad when you're running low. | `lucide-react` | [`components/widgets/battery-face-widget.tsx`](components/widgets/battery-face-widget.tsx) | [Guide](references/craft/battery-face.md) |
+| **Blob Profile** | `blob-profile` | Profile card with an organic blob-shaped photo frame, name, verified check, and handle. Stands out from every circular-avatar layout on the web. | `lucide-react`, `next` | [`components/widgets/blob-profile.tsx`](components/widgets/blob-profile.tsx) | [Guide](references/craft/blob-profile.md) |
+| **Bluetooth Face** | `bluetooth-face` | A teal mascot face that reacts when Bluetooth connects or drops. Toggle on/off with an expression change — playful, but still reads as a real status widget. | `lucide-react` | [`components/widgets/bluetooth-face-widget.tsx`](components/widgets/bluetooth-face-widget.tsx) | [Guide](references/craft/bluetooth-face.md) |
+| **Booking Slot Calendar** | `booking-slot-calendar` | Appointment booking flow — week strip on top, time slots below. Unavailable slots are crossed out, tap to book. | `lucide-react` | [`components/calendar/booking-slot-calendar.tsx`](components/calendar/booking-slot-calendar.tsx) | [Guide](references/craft/booking-slot-calendar.md) |
+| **Bookmark Save** | `bookmark-save-button` | Save for later — bookmark icon fills amber and label swaps to Saved. Square-ish control for articles and products. | `lucide-react` | [`components/buttons/bookmark-save-button.tsx`](components/buttons/bookmark-save-button.tsx) | [Guide](references/craft/bookmark-save-button.md) |
+| **Cafe Menu Board** | `cafe-menu-board` | Dark chalkboard-style menu with cafe header, item notes, and amber price accents — hospitality and local brand sites. | `lucide-react` | [`components/text/cafe-menu-board-card.tsx`](components/text/cafe-menu-board-card.tsx) | [Guide](references/craft/cafe-menu-board.md) |
+| **Calendar Reminder Notification** | `calendar-reminder-notification` | Calendar reminder on the iOS grid — red app tile, event name, and time until it starts. | `lucide-react` | [`components/notifications/calendar-reminder-notification-banner.tsx`](components/notifications/calendar-reminder-notification-banner.tsx) | [Guide](references/craft/calendar-reminder-notification.md) |
+| **Chat Bubble Notification** | `chat-bubble-notification` | Messenger-style bubble — small avatar, sender name, rounded message bubble with a flat tail corner. | `lucide-react`, `next` | [`components/notifications/chat-bubble-notification-banner.tsx`](components/notifications/chat-bubble-notification-banner.tsx) | [Guide](references/craft/chat-bubble-notification.md) |
+| **Checkbox Field Input** | `checkbox-field-input` | Accessible checkbox with custom mark, inline label, hint, and error. Controlled or uncontrolled checked state. | `lucide-react` | [`components/inputs/checkbox-field-input.tsx`](components/inputs/checkbox-field-input.tsx) | [Guide](references/craft/checkbox-field-input.md) |
+| **Cherry Petal** | `cherry-petal-background` | Soft spring canvas with drifting cherry petals and a blush radial glow — weddings, florists, and seasonal campaigns. | None (core) | [`components/background-gradient/cherry-petal-background.tsx`](components/background-gradient/cherry-petal-background.tsx) | [Guide](references/craft/cherry-petal-background.md) |
+| **Cinder Latch** | `cinder-latch-button` | Charcoal latch button with a warm ember under-glow, center groove, and face sheen — built for secure-action CTAs. | None (core) | [`components/buttons/cinder-latch-button.tsx`](components/buttons/cinder-latch-button.tsx) | [Guide](references/craft/cinder-latch-button.md) |
+| **Cinema Ticket** | `cinema-ticket` | Split cinema ticket with film title, venue, screen, seats, show time, and a perforated stub. Dark ticket stock that feels printed, not flat. | `lucide-react` | [`components/text/cinema-ticket-card.tsx`](components/text/cinema-ticket-card.tsx) | [Guide](references/craft/cinema-ticket.md) |
+| **Circle Cut Frame** | `circle-cut-frame` | Ticket-style frame with circle-cut edges on all sides — defaults to white; pass width, height, frameColor, and any image, video, or content as children. | None (core) | [`components/frames/circle-cut-frame.tsx`](components/frames/circle-cut-frame.tsx) | [Guide](references/craft/circle-cut-frame.md) |
+| **Combobox Field Input** | `combobox-field-input` | Searchable combobox with filtered listbox, keyboard navigation, click-outside close, and hidden field for form posts. | `lucide-react` | [`components/inputs/combobox-field-input.tsx`](components/inputs/combobox-field-input.tsx) | [Guide](references/craft/combobox-field-input.md) |
+| **Compass** | `compass` | A compass dial with labeled directions and a needle that follows device tilt. Pass a heading prop or let the browser handle orientation. | None (core) | [`components/widgets/compass-widget.tsx`](components/widgets/compass-widget.tsx) | [Guide](references/craft/compass.md) |
+| **Contact Form** | `contact-form` | Contact form with honeypot spam guard, character count, field validation, loading state, and success confirmation screen. | `lucide-react` | [`components/forms/contact-form.tsx`](components/forms/contact-form.tsx) | [Guide](references/craft/contact-form.md) |
+| **Contact Profile** | `contact-profile` | Museum placard contact directory — mono labels, serif name, and typographic rows without icon clutter. | `next` | [`components/profile/contact-profile-card.tsx`](components/profile/contact-profile-card.tsx) | [Guide](references/craft/contact-profile.md) |
+| **Copy Email Button** | `copy-email` | One-click copy maintainer email address with inline tooltip feedback ("Click to copy" / "Copied") and zero mailbox popup. | None (core) | [`components/contact/copy-email.tsx`](components/contact/copy-email.tsx) | [Guide](references/craft/copy-email.md) |
+| **Coral Glow** | `coral-glow-background` | Warm aurora wash in rose, peach, coral, and gold over a blush paper base — beauty, lifestyle, and invitation hero sections. | None (core) | [`components/background-gradient/coral-glow-background.tsx`](components/background-gradient/coral-glow-background.tsx) | [Guide](references/craft/coral-glow-background.md) |
+| **Craft Signup Form** | `craft-signup-form` | Registration form with name, email, password strength rules, confirm password match, and required terms acceptance. | `lucide-react`, `next` | [`components/forms/signup-form.tsx`](components/forms/signup-form.tsx) | [Guide](references/craft/craft-signup-form.md) |
+| **Credit Card Glass** | `credit-card-glass` | Glassmorphism payment card with chip, masked number, holder name, and expiry. Glow on hover — fintech landing pages eat this up. | None (core) | [`components/users/credit-card-glass.tsx`](components/users/credit-card-glass.tsx) | [Guide](references/craft/credit-card-glass.md) |
+| **Customers Table** | `customers-table` | SaaS customer list with plan, last active, and MRR. Common billing dashboard table. | `next` | [`components/table/customers-table.tsx`](components/table/customers-table.tsx) | [Guide](references/craft/customers-table.md) |
+| **Daily Activity Calendar** | `daily-activity-calendar` | Month grid for the current month — today is highlighted in orange, with a short emerald streak on prior days. Pass activeDays or highlightDay to override. | `lucide-react` | [`components/widgets/daily-activity-calendar-widget.tsx`](components/widgets/daily-activity-calendar-widget.tsx) | [Guide](references/craft/daily-activity-calendar.md) |
+| **Daily Motivation** | `daily-motivation` | Editorial poster with multi-line headline, flower icon, tilted polaroid, and a GOOD DAY sticker. Morning routine apps and wellness newsletters. | `lucide-react`, `next` | [`components/text/daily-motivation-card.tsx`](components/text/daily-motivation-card.tsx) | [Guide](references/craft/daily-motivation.md) |
+| **Dark Arc Bands** | `dark-arc-bands-background` | Blended sky, teal, amber, and rose arcs on a midnight base — cinematic dark posters and event keynotes. | None (core) | [`components/background-gradient/dark-arc-bands-background.tsx`](components/background-gradient/dark-arc-bands-background.tsx) | [Guide](references/craft/dark-arc-bands-background.md) |
+| **Dark Aurora** | `dark-aurora-background` | Charcoal stage with soft teal, cyan, and emerald aurora blooms — premium dark hero sections and product launches. | None (core) | [`components/background-gradient/dark-aurora-background.tsx`](components/background-gradient/dark-aurora-background.tsx) | [Guide](references/craft/dark-aurora-background.md) |
+| **Dark Carbon Spotlight** | `dark-carbon-spotlight-background` | Carbon black stage with a soft overhead spotlight and vignette — product reveals, keynotes, and gallery dark modes. | None (core) | [`components/background-gradient/dark-carbon-spotlight-background.tsx`](components/background-gradient/dark-carbon-spotlight-background.tsx) | [Guide](references/craft/dark-carbon-spotlight-background.md) |
+| **Dark Ember** | `dark-ember-background` | Warm noir base with amber, ember orange, and rose glow pools — luxury dining, nightlife, and editorial dark modes. | None (core) | [`components/background-gradient/dark-ember-background.tsx`](components/background-gradient/dark-ember-background.tsx) | [Guide](references/craft/dark-ember-background.md) |
+| **Dark Ink Field** | `dark-ink-field-background` | Near-black canvas with soft graphite ink washes — galleries, studios, and minimal dark editorial layouts. | None (core) | [`components/background-gradient/dark-ink-field-background.tsx`](components/background-gradient/dark-ink-field-background.tsx) | [Guide](references/craft/dark-ink-field-background.md) |
+| **Dark Midnight Mesh** | `dark-midnight-mesh-background` | Midnight frost mesh with whisper-soft grid, teal and sky blooms, and a gentle vignette — dashboards, terminals, and refined dark UI. | None (core) | [`components/background-gradient/dark-midnight-mesh-background.tsx`](components/background-gradient/dark-midnight-mesh-background.tsx) | [Guide](references/craft/dark-midnight-mesh-background.md) |
+| **Dark Rose Noir** | `dark-rose-noir-background` | Elegant noir with restrained rose and crimson bloom accents — fashion, beauty, and premium dark branding. | None (core) | [`components/background-gradient/dark-rose-noir-background.tsx`](components/background-gradient/dark-rose-noir-background.tsx) | [Guide](references/craft/dark-rose-noir-background.md) |
+| **Dark Teal Depth** | `dark-teal-depth-background` | Deep oceanic black with layered teal and cyan depth blooms — fintech, dev tools, and refined SaaS dark themes. | None (core) | [`components/background-gradient/dark-teal-depth-background.tsx`](components/background-gradient/dark-teal-depth-background.tsx) | [Guide](references/craft/dark-teal-depth-background.md) |
+| **Date Field Input** | `date-field-input` | Custom calendar popover with month navigation, today shortcut, min/max limits, and styled day grid — no native browser picker. | `lucide-react` | [`components/inputs/date-field-input.tsx`](components/inputs/date-field-input.tsx) | [Guide](references/craft/date-field-input.md) |
+| **Date Range Picker Card** | `date-range-picker-card` | Travel-style date range picker — first tap sets check-in, second sets check-out, days between fill in. | `lucide-react` | [`components/calendar/date-range-picker-card.tsx`](components/calendar/date-range-picker-card.tsx) | [Guide](references/craft/date-range-picker-card.md) |
+| **Delivery Notification** | `delivery-notification` | Shipping update — package icon, delivery status, ETA, and order number in a compact row. | `lucide-react` | [`components/notifications/delivery-notification-banner.tsx`](components/notifications/delivery-notification-banner.tsx) | [Guide](references/craft/delivery-notification.md) |
+| **Denim Product Editorial** | `denim-product-editorial` | Fashion editorial with two square photos, rotated callout labels, and uppercase product description. Lookbook energy for apparel and accessories. | `next` | [`components/text/denim-product-editorial-card.tsx`](components/text/denim-product-editorial-card.tsx) | [Guide](references/craft/denim-product-editorial.md) |
+| **Deploy Notification** | `deploy-notification` | Deploy alert on the iOS grid — Vercel triangle tile, short status line with project, branch, and duration. | `lucide-react` | [`components/notifications/deploy-notification-banner.tsx`](components/notifications/deploy-notification-banner.tsx) | [Guide](references/craft/deploy-notification.md) |
+| **Depth Outline** | `depth-outline-button` | Premium outline button with layered float depth, a soft top lip, and a press-in sink — secondary CTA that still feels tactile. Pass any children. | None (core) | [`components/buttons/depth-outline-button.tsx`](components/buttons/depth-outline-button.tsx) | [Guide](references/craft/depth-outline-button.md) |
+| **Diagonal Box** | `diagonal-box-pattern` | Classic 45° hairline hatch on white — the same quiet stage used across marketing mockups and component previews. | None (core) | [`components/background-pattern/diagonal-box-pattern.tsx`](components/background-pattern/diagonal-box-pattern.tsx) | [Guide](references/craft/diagonal-box-pattern.md) |
+| **Dimple Switch** | `dimple-switch` | Tactile switch with a dimpled knob, metallic track, and amber on-state fill. Hidden checkbox drives the slide — controlled or uncontrolled. | None (core) | [`components/buttons/dimple-switch.tsx`](components/buttons/dimple-switch.tsx) | [Guide](references/craft/dimple-switch.md) |
+| **Discord Chat** | `discord-chat` | Dark Discord channel with server header, threaded messages, avatars, timestamps, and a send input. Community product mockups in one card. | `lucide-react`, `next` | [`components/socials/discord-chat-card.tsx`](components/socials/discord-chat-card.tsx) | [Guide](references/craft/discord-chat.md) |
+| **Dnd Face** | `dnd-face` | Focus mode as a purple moon mascot — tap to toggle DND and watch the expression shift. Makes a utilitarian setting feel a little human. | `lucide-react` | [`components/widgets/dnd-face-widget.tsx`](components/widgets/dnd-face-widget.tsx) | [Guide](references/craft/dnd-face.md) |
+| **Dot Grid** | `dot-grid-pattern` | Soft dotted grid on neutral paper — watch mockup stages, device demos, and minimal product sections. | None (core) | [`components/background-pattern/dot-grid-pattern.tsx`](components/background-pattern/dot-grid-pattern.tsx) | [Guide](references/craft/dot-grid-pattern.md) |
+| **Download with States** | `download-button` | Raised 3D download key that sinks while downloading — arrow morphs to spinner to check — then pops back up as a solid emerald done state. | `lucide-react` | [`components/buttons/download-button.tsx`](components/buttons/download-button.tsx) | [Guide](references/craft/download-button.md) |
+| **Drop Cap Editorial** | `drop-cap-editorial` | Editorial quote block with a large drop-cap letter, body text, and author attribution. Magazine typography without opening InDesign. | `lucide-react` | [`components/text/drop-cap-editorial-card.tsx`](components/text/drop-cap-editorial-card.tsx) | [Guide](references/craft/drop-cap-editorial.md) |
+| **Editor Tool Dock** | `editor-tool-dock` | Vertical editor tool dock using MacDock tile size, padding, and ease-smooth hover scale. | `lucide-react` | [`components/docks/editor-tool-dock.tsx`](components/docks/editor-tool-dock.tsx) | [Guide](references/craft/editor-tool-dock.md) |
+| **Editorial Quote** | `editorial-quote` | Pull quote with issue metadata and a highlighted word inside the line — author and role at the bottom. Built for case studies and long reads. | `lucide-react` | [`components/text/editorial-quote-card.tsx`](components/text/editorial-quote-card.tsx) | [Guide](references/craft/editorial-quote.md) |
+| **Editorial Staff Profile** | `editorial-staff-profile` | Numbered editorial roster row with serif name, uppercase role, and a square photo. Built for about pages and team indexes. | None (core) | [`components/profile/editorial-staff-profile-card.tsx`](components/profile/editorial-staff-profile-card.tsx) | [Guide](references/craft/editorial-staff-profile.md) |
+| **Electric Scooter** | `electric-scooter` | Ride summary with scooter photo, distance, average speed, and duration. Leaf icon included — built for micro-mobility or fitness stats. | `lucide-react`, `next` | [`components/widgets/electric-scooter-widget.tsx`](components/widgets/electric-scooter-widget.tsx) | [Guide](references/craft/electric-scooter.md) |
+| **Email Notification** | `email-notification` | Mail alert on the iOS grid — sender avatar, app name header, natural from: subject — preview body line. | `lucide-react`, `next` | [`components/notifications/email-notification-banner.tsx`](components/notifications/email-notification-banner.tsx) | [Guide](references/craft/email-notification.md) |
+| **Event Countdown Card** | `event-countdown-card` | Live countdown to an event — days, hours, and minutes update every minute. Editorial typography, no ticker gimmicks. | None (core) | [`components/calendar/event-countdown-card.tsx`](components/calendar/event-countdown-card.tsx) | [Guide](references/craft/event-countdown-card.md) |
+| **Event Ticket** | `event-ticket` | Perforated event ticket with a cover-image date block and VIP pass details on the right. Concert, conference, or launch night — same component. | `lucide-react`, `next` | [`components/event/event-ticket-card.tsx`](components/event/event-ticket-card.tsx) | [Guide](references/craft/event-ticket.md) |
+| **Facebook Post** | `facebook-post` | Facebook feed post with reactions, comments, share counts, optional image, and the full action bar. Familiar layout, your content. | `lucide-react`, `next` | [`components/socials/facebook-post-card.tsx`](components/socials/facebook-post-card.tsx) | [Guide](references/craft/facebook-post.md) |
+| **File Menu** | `file-menu` | Folder icon you can right-click or tap to open a centered action menu — edit, duplicate, pin, move, delete. Keyboard-friendly item hints included. | `lucide-react` | [`components/dropdowns/file-menu-dropdown.tsx`](components/dropdowns/file-menu-dropdown.tsx) | [Guide](references/craft/file-menu.md) |
+| **File Upload Field Input** | `file-upload-field-input` | Card-style file upload with drag-and-drop zone, browse button, format/size hints, typed file rows, and remove actions. | `lucide-react` | [`components/inputs/file-upload-field-input.tsx`](components/inputs/file-upload-field-input.tsx) | [Guide](references/craft/file-upload-field-input.md) |
+| **Film Strip** | `film-strip` | Horizontal 35mm strip with sprocket holes and multiple frames. Roll label up top — great for photo galleries and vintage layouts. | `next` | [`components/gallery/film-strip-card.tsx`](components/gallery/film-strip-card.tsx) | [Guide](references/craft/film-strip.md) |
+| **Filter Sort** | `filter-sort` | Native select-style box — dropdown is flush below the trigger with matching width and a left-border active state. | `lucide-react` | [`components/dropdowns/filter-sort-dropdown.tsx`](components/dropdowns/filter-sort-dropdown.tsx) | [Guide](references/craft/filter-sort.md) |
+| **Fine Grain** | `fine-grain-pattern` | Micro dot grain for a film-paper feel — hero backgrounds that need texture without competing with content. | None (core) | [`components/background-pattern/fine-grain-pattern.tsx`](components/background-pattern/fine-grain-pattern.tsx) | [Guide](references/craft/fine-grain-pattern.md) |
+| **Flight Arrival** | `flight-arrival` | Countdown to landing with departure and arrival airports and a plane moving along a progress bar. Built for travel dashboards and trip widgets. | `lucide-react` | [`components/widgets/flight-arrival-widget.tsx`](components/widgets/flight-arrival-widget.tsx) | [Guide](references/craft/flight-arrival.md) |
+| **Flight Boarding** | `flight-boarding` | Airline boarding pass with tear line, route codes, seat, gate, boarding time, and passenger name. Travel mockups that feel airport-real. | `lucide-react` | [`components/travel/flight-boarding-card.tsx`](components/travel/flight-boarding-card.tsx) | [Guide](references/craft/flight-boarding.md) |
+| **Floating Label Field Input** | `floating-label-field-input` | Outlined floating label that rests on the border notch when focused or filled — matches Material-style fields with autofill detection. | None (core) | [`components/inputs/floating-label-field-input.tsx`](components/inputs/floating-label-field-input.tsx) | [Guide](references/craft/floating-label-field-input.md) |
+| **Floating Pill** | `soft-pill-button` | Floating rounded pill with a soft drop shadow — light or dark. Pass any children. Nudges down slightly on press. | None (core) | [`components/buttons/soft-pill-button.tsx`](components/buttons/soft-pill-button.tsx) | [Guide](references/craft/soft-pill-button.md) |
+| **Focus Breath** | `focus-breath` | A breathing guide that pulses between inhale and exhale every four seconds. One tap to start — useful in wellness or focus flows. | None (core) | [`components/widgets/focus-breath-widget.tsx`](components/widgets/focus-breath-widget.tsx) | [Guide](references/craft/focus-breath.md) |
+| **Folder Tab Card** | `folder-tab-card` | Folder tab card with black frame, top-half image, and dark panel showing library stats. Studio App branding by default. | `next` | [`components/folder/folder-tab-card.tsx`](components/folder/folder-tab-card.tsx) | [Guide](references/craft/folder-tab-card.md) |
+| **Follow Toggle** | `follow-button` | Social follow toggle — dark Follow pill becomes a quiet Following state with a user-check icon. Tap again to unfollow. | `lucide-react` | [`components/buttons/follow-button.tsx`](components/buttons/follow-button.tsx) | [Guide](references/craft/follow-button.md) |
+| **Forgot Password Form** | `forgot-password-form` | Password reset request form with email validation, loading state, success screen, and back-to-login navigation. | `lucide-react`, `next` | [`components/forms/forgot-password-form.tsx`](components/forms/forgot-password-form.tsx) | [Guide](references/craft/forgot-password-form.md) |
+| **Frost Mesh** | `frost-mesh-background` | Cool frost-white mesh with teal and emerald corner washes — SaaS dashboards, health apps, and minimal product launches. | None (core) | [`components/background-gradient/frost-mesh-background.tsx`](components/background-gradient/frost-mesh-background.tsx) | [Guide](references/craft/frost-mesh-background.md) |
+| **Gallery Grid** | `gallery-grid` | Album preview with title, subtitle, and a three-cell photo grid — last cell shows a +N overflow count. Portfolio and gallery index pages. | `lucide-react`, `next` | [`components/gallery/gallery-grid-card.tsx`](components/gallery/gallery-grid-card.tsx) | [Guide](references/craft/gallery-grid.md) |
+| **Gallery Wall** | `gallery-wall` | Gallery wall mat with cream matting, artwork preview, and caption block — clean exhibition styling. | `next` | [`components/gallery/gallery-wall-card.tsx`](components/gallery/gallery-wall-card.tsx) | [Guide](references/craft/gallery-wall.md) |
+| **Github Contribution** | `github-contribution` | GitHub-style contribution heatmap with year selector, total count, and Less/More legend. Pulls real data when you pass a username. | `lucide-react` | [`components/socials/github-contribution.tsx`](components/socials/github-contribution.tsx) | [Guide](references/craft/github-contribution.md) |
+| **Github Repo** | `github-repo` | GitHub repo card with owner, description, language dot, star/fork counts, and a toggleable Star button. Open source landing pages, simplified. | `lucide-react` | [`components/socials/github-repo-card.tsx`](components/socials/github-repo-card.tsx) | [Guide](references/craft/github-repo.md) |
+| **Glass Overlay Image** | `glass-overlay-image` | Full-bleed photo with frosted bottom panel — location, title, saved avatars, and Explore CTA. Like and share buttons float top-right. | `lucide-react`, `next` | [`components/gallery/glass-overlay-image-card.tsx`](components/gallery/glass-overlay-image-card.tsx) | [Guide](references/craft/glass-overlay-image.md) |
+| **Graph Paper** | `graph-paper-pattern` | Clean square grid for sketches, wireframes, and planning boards — subtle ink lines on white. | None (core) | [`components/background-pattern/graph-paper-pattern.tsx`](components/background-pattern/graph-paper-pattern.tsx) | [Guide](references/craft/graph-paper-pattern.md) |
+| **Halftone Pop** | `halftone-pop-background` | Risograph-style halftone dots in rose, teal, and amber on cream — posters, zines, and bold creative brands. | None (core) | [`components/background-gradient/halftone-pop-background.tsx`](components/background-gradient/halftone-pop-background.tsx) | [Guide](references/craft/halftone-pop-background.md) |
+| **Hard Shadow Polaroid Frame** | `hard-shadow-polaroid-frame` | Polaroid frame with a crisp inner border, thick caption chin, and hard offset shadow — pass caption and any image or video as children. | None (core) | [`components/frames/hard-shadow-polaroid-frame.tsx`](components/frames/hard-shadow-polaroid-frame.tsx) | [Guide](references/craft/hard-shadow-polaroid-frame.md) |
+| **Heart Rate** | `heart-rate` | Heart rate in the DND face layout — mascot at the bottom, BPM above the dial, soft pulse on the ring. | `lucide-react` | [`components/widgets/heart-rate-widget.tsx`](components/widgets/heart-rate-widget.tsx) | [Guide](references/craft/heart-rate.md) |
+| **Hold to Delete** | `hold-to-delete-button` | Press and hold as a fill sweeps across; release early to cancel, hold to the end to delete. Prevents accidental destructive taps. | `lucide-react` | [`components/buttons/hold-to-delete-button.tsx`](components/buttons/hold-to-delete-button.tsx) | [Guide](references/craft/hold-to-delete-button.md) |
+| **Home** | `mac-dock` | Frosted macOS-style app dock with smooth hover lift, tooltips, and brand icons — Tailwind-only, no motion library. | `next` | [`components/docks/mac-dock.tsx`](components/docks/mac-dock.tsx) | [Guide](references/craft/mac-dock.md) |
+| **Honey Ember** | `honey-ember-background` | Cozy aurora glow in honey, amber, ember orange, and soft rose over warm ivory — food, bakery, and autumn campaigns. | None (core) | [`components/background-gradient/honey-ember-background.tsx`](components/background-gradient/honey-ember-background.tsx) | [Guide](references/craft/honey-ember-background.md) |
+| **Hydration** | `hydration` | Tall bottle card — count at the top, water level rises inside a simple bottle outline. Tap to log a glass. | None (core) | [`components/widgets/hydration-widget.tsx`](components/widgets/hydration-widget.tsx) | [Guide](references/craft/hydration.md) |
+| **Incoming Call Notification** | `incoming-call-notification` | Incoming call card — large avatar, caller name, FaceTime label, Accept and Decline buttons. | `lucide-react`, `next` | [`components/notifications/incoming-call-notification-banner.tsx`](components/notifications/incoming-call-notification-banner.tsx) | [Guide](references/craft/incoming-call-notification.md) |
+| **Ink Stamp Document** | `ink-stamp-document` | Paper filing card with reference metadata and a rotated approval stamp — contracts, invoices, and admin dashboards. | `lucide-react` | [`components/files/ink-stamp-document-card.tsx`](components/files/ink-stamp-document-card.tsx) | [Guide](references/craft/ink-stamp-document.md) |
+| **Ink Wash** | `ink-wash-background` | Minimal sumi-e ink clouds in soft stone gray on warm paper — galleries, studios, and calm editorial layouts. | None (core) | [`components/background-gradient/ink-wash-background.tsx`](components/background-gradient/ink-wash-background.tsx) | [Guide](references/craft/ink-wash-background.md) |
+| **Input Group Field** | `input-group-field` | Grouped input with prefix and suffix slots — URLs, currency, units. Wrapper border highlights on focus; inputs use border-only focus with ring-0. | None (core) | [`components/inputs/input-group-field.tsx`](components/inputs/input-group-field.tsx) | [Guide](references/craft/input-group-field.md) |
+| **Instagram Post** | `instagram-post` | Full Instagram post layout — header, square image, action icons, like count, caption, and timestamp. Looks native, props for your content. | `lucide-react`, `next` | [`components/socials/instagram-post-card.tsx`](components/socials/instagram-post-card.tsx) | [Guide](references/craft/instagram-post.md) |
+| **Ios Calendar Widget** | `ios-calendar-widget` | Today's date in the classic iOS calendar tile — red weekday, big day number, month underneath. Updates live, no refresh needed. | None (core) | [`components/widgets/ios-calendar-widget.tsx`](components/widgets/ios-calendar-widget.tsx) | [Guide](references/craft/ios-calendar-widget.md) |
+| **Ios Digital Clock** | `ios-digital-clock` | Live HH:MM in an iOS squircle with subtle tick marks around the edge. The kind of clock tile you'd find on a lock screen. | None (core) | [`components/widgets/ios-digital-clock-widget.tsx`](components/widgets/ios-digital-clock-widget.tsx) | [Guide](references/craft/ios-digital-clock.md) |
+| **Ios Earbuds** | `ios-earbuds` | AirPods-style widget showing device name and connection status. Small, familiar, and perfect beside other iOS-style controls. | None (core) | [`components/widgets/ios-earbuds-widget.tsx`](components/widgets/ios-earbuds-widget.tsx) | [Guide](references/craft/ios-earbuds.md) |
+| **Ios Map Location** | `ios-map-location` | Map pin widget with your city name — simple location card in the iOS family. Good for travel apps, weather screens, or profile headers. | None (core) | [`components/widgets/ios-map-location-widget.tsx`](components/widgets/ios-map-location-widget.tsx) | [Guide](references/craft/ios-map-location.md) |
+| **Journal Writing** | `journal-writing` | Journal card with title, date header, editable textarea, live word count, and saving status. The writing flow, not just a static textarea mockup. | `lucide-react` | [`components/text/journal-writing-card.tsx`](components/text/journal-writing-card.tsx) | [Guide](references/craft/journal-writing.md) |
+| **Kebab Actions** | `kebab-actions` | List row that expands inline — actions open inside the same card so widths always align. | `lucide-react` | [`components/dropdowns/kebab-actions-dropdown.tsx`](components/dropdowns/kebab-actions-dropdown.tsx) | [Guide](references/craft/kebab-actions.md) |
+| **Keyboard Shortcuts** | `keyboard-shortcuts` | Shortcut reference card with rendered key caps and a ⌘K header hint. Docs pages and onboarding modals use this constantly. | `lucide-react` | [`components/text/keyboard-shortcuts-card.tsx`](components/text/keyboard-shortcuts-card.tsx) | [Guide](references/craft/keyboard-shortcuts.md) |
+| **Like Toggle** | `like-button` | Heart toggle that pops and scatters particles on the way up, with a live count. Pill fills rose when active — no glow, no gradient. | `lucide-react` | [`components/buttons/like-button.tsx`](components/buttons/like-button.tsx) | [Guide](references/craft/like-button.md) |
+| **Line Grid** | `line-grid-pattern` | Horizontal ruled lines with a soft paper gradient — editorial layouts, docs, and notebook-style sections. | None (core) | [`components/background-pattern/line-grid-pattern.tsx`](components/background-pattern/line-grid-pattern.tsx) | [Guide](references/craft/line-grid-pattern.md) |
+| **Linen Tab** | `linen-tab-button` | Woven linen tab with dashed stitch borders and a soft fold sheen — warm, editorial, and understated. | None (core) | [`components/buttons/linen-tab-button.tsx`](components/buttons/linen-tab-button.tsx) | [Guide](references/craft/linen-tab-button.md) |
+| **Linen Weave** | `linen-weave-background` | Warm editorial linen with crosshatch weave, soft paper grain, and a gentle vignette — portfolios, magazines, and craft-brand pages. | None (core) | [`components/background-gradient/linen-weave-background.tsx`](components/background-gradient/linen-weave-background.tsx) | [Guide](references/craft/linen-weave-background.md) |
+| **Linked In Post** | `linked-in-post` | LinkedIn feed post with headline, body text, link preview card, reaction counts, and like/comment/repost/send actions. | `lucide-react`, `next` | [`components/socials/linked-in-post-card.tsx`](components/socials/linked-in-post-card.tsx) | [Guide](references/craft/linked-in-post.md) |
+| **Linked In Profile** | `linked-in-profile` | LinkedIn profile card with cover photo, avatar, headline, stats, bio, and Connect/Message buttons. Professional social, component-sized. | `next` | [`components/socials/linked-in-profile-card.tsx`](components/socials/linked-in-profile-card.tsx) | [Guide](references/craft/linked-in-profile.md) |
+| **Login Form** | `login-form` | Production login form with email/password validation, remember me, show password, loading state, and forgot-password link. | `lucide-react`, `next` | [`components/forms/login-form.tsx`](components/forms/login-form.tsx) | [Guide](references/craft/login-form.md) |
+| **Magazine Cover** | `magazine-cover` | Tall magazine cover with issue badge, category, title, author, and read time. Hover zoom on the cover image — editorial hero material. | `lucide-react`, `next` | [`components/text/magazine-cover-card.tsx`](components/text/magazine-cover-card.tsx) | [Guide](references/craft/magazine-cover.md) |
+| **Minimal Agenda** | `minimal-agenda` | Today's tasks with times — tap a row to mark it done with a strikethrough and checkmark. Clean enough for a daily planner sidebar. | `lucide-react` | [`components/widgets/minimal-agenda-widget.tsx`](components/widgets/minimal-agenda-widget.tsx) | [Guide](references/craft/minimal-agenda.md) |
+| **Mint Lagoon** | `mint-lagoon-background` | Cool aurora wash in emerald, teal, cyan, and mint over a fresh white base — wellness, spa, and clean product launches. | None (core) | [`components/background-gradient/mint-lagoon-background.tsx`](components/background-gradient/mint-lagoon-background.tsx) | [Guide](references/craft/mint-lagoon-background.md) |
+| **Month Picker Calendar** | `month-picker-calendar` | Full month picker with prev/next navigation — tap any day to select it, today gets a quiet ring. | `lucide-react` | [`components/calendar/month-picker-calendar.tsx`](components/calendar/month-picker-calendar.tsx) | [Guide](references/craft/month-picker-calendar.md) |
+| **Museum Placard** | `museum-placard` | Gallery exhibition label that flips to reveal curator notes and acquisition details. Art portfolios and culture sites love this interaction. | None (core) | [`components/gallery/museum-placard-card.tsx`](components/gallery/museum-placard-card.tsx) | [Guide](references/craft/museum-placard.md) |
+| **Music Player** | `music-player` | Full dark player card with cover art, album info, progress scrubber with times, and transport controls. Not a bar — the whole now-playing screen. | `lucide-react`, `next` | [`components/audio/music-player-card.tsx`](components/audio/music-player-card.tsx) | [Guide](references/craft/music-player.md) |
+| **Music Playlist** | `music-playlist` | Playlist card with cover, header stats, and a track list where each row toggles play independently. One component, full playlist UI. | `lucide-react`, `next` | [`components/audio/music-playlist-card.tsx`](components/audio/music-playlist-card.tsx) | [Guide](references/craft/music-playlist.md) |
+| **Neumorphic Soft UI** | `soft-ui-button` | Universal soft-UI / neumorphic button — even light and dark shadows. Pass any children. Press flips to an inset look. | None (core) | [`components/buttons/soft-ui-button.tsx`](components/buttons/soft-ui-button.tsx) | [Guide](references/craft/soft-ui-button.md) |
+| **Newsletter Form** | `newsletter-form` | Email subscribe form with inline button, validation, privacy note, and inline success message — built for footers and landing pages. | `lucide-react` | [`components/forms/newsletter-form.tsx`](components/forms/newsletter-form.tsx) | [Guide](references/craft/newsletter-form.md) |
+| **Notepad** | `notepad` | Sticky notepad with an italic quote, author line, and checkbox task list. Bookmark ribbon on top — good for editorial or productivity layouts. | `lucide-react` | [`components/text/notepad-card.tsx`](components/text/notepad-card.tsx) | [Guide](references/craft/notepad.md) |
+| **Notification** | `notification` | Square bell trigger with a gray inset tray — each notification is a small bordered card inside the panel. | `lucide-react` | [`components/dropdowns/notification-dropdown.tsx`](components/dropdowns/notification-dropdown.tsx) | [Guide](references/craft/notification.md) |
+| **Now Playing Bar** | `now-playing-bar` | Compact dark player bar with artwork, track info, transport controls, and a scrubber. The footer bar every music app eventually needs. | `lucide-react`, `next` | [`components/audio/now-playing-bar.tsx`](components/audio/now-playing-bar.tsx) | [Guide](references/craft/now-playing-bar.md) |
+| **Orders Table** | `orders-table` | E-commerce orders table — sort by date, total, or status. The standard admin dashboard orders view. | `lucide-react` | [`components/table/orders-table.tsx`](components/table/orders-table.tsx) | [Guide](references/craft/orders-table.md) |
+| **Otp Boxed Input** | `otp-boxed-input` | Full email verification card with icon header, destination text, animated square cells, progress dots, shake-on-error, and resend countdown. | `lucide-react` | [`components/otp/otp-boxed-input.tsx`](components/otp/otp-boxed-input.tsx) | [Guide](references/craft/otp-boxed-input.md) |
+| **Otp Underline Input** | `otp-underline-input` | Editorial underline OTP with serif heading and animated focus rules. Same edge-case handling as boxed — typing, delete, paste, and one-time-code autocomplete. | None (core) | [`components/otp/otp-underline-input.tsx`](components/otp/otp-underline-input.tsx) | [Guide](references/craft/otp-underline-input.md) |
+| **Page Loader Overlay** | `page-loader-overlay` | Full-screen page loader overlay with an ink spinner, subtle backdrop, and polite accessibility announcements. | `lucide-react` | [`components/system/loaders/page-loader-overlay.tsx`](components/system/loaders/page-loader-overlay.tsx) | [Guide](references/craft/page-loader-overlay.md) |
+| **Paper Fold** | `paper-fold-background` | Tactile cardstock with a diagonal crease, soft highlight, and shadow — invitations, stationery, and craft portfolios. | None (core) | [`components/background-gradient/paper-fold-background.tsx`](components/background-gradient/paper-fold-background.tsx) | [Guide](references/craft/paper-fold-background.md) |
+| **Password Field Input** | `password-field-input` | Password input with show/hide toggle, hint text, and error state. Keeps autocomplete defaults and accessible visibility control. | `lucide-react` | [`components/inputs/password-field-input.tsx`](components/inputs/password-field-input.tsx) | [Guide](references/craft/password-field-input.md) |
+| **Payment Notification** | `payment-notification` | Payment received on the iOS grid — emerald tile, amount, and sender name. | `lucide-react` | [`components/notifications/payment-notification-banner.tsx`](components/notifications/payment-notification-banner.tsx) | [Guide](references/craft/payment-notification.md) |
+| **Phone Field Input** | `phone-field-input` | Phone field with dial-code prefix and live US-style formatting. Returns raw digits via onChange for validation and API calls. | None (core) | [`components/inputs/phone-field-input.tsx`](components/inputs/phone-field-input.tsx) | [Guide](references/craft/phone-field-input.md) |
+| **Photo Album** | `photo-album` | Swipeable square photo carousel with place and date caption plus dot indicators. Swap in your own photos and tell a travel story. | `next` | [`components/gallery/photo-album-card.tsx`](components/gallery/photo-album-card.tsx) | [Guide](references/craft/photo-album.md) |
+| **Photo Contact Sheet** | `photo-contact-sheet` | Film contact sheet with a 2×2 numbered frame grid and roll label header. Photographer portfolio vibes, straight from the darkroom. | `next` | [`components/gallery/photo-contact-sheet-card.tsx`](components/gallery/photo-contact-sheet-card.tsx) | [Guide](references/craft/photo-contact-sheet.md) |
+| **Polaroid Image** | `polaroid-image` | Classic white polaroid with photo, caption, and date — slight tilt that straightens on hover. Nostalgic without feeling like a filter preset. | `next` | [`components/gallery/polaroid-image-card.tsx`](components/gallery/polaroid-image-card.tsx) | [Guide](references/craft/polaroid-image.md) |
+| **Pomodoro** | `pomodoro` | Dark pomodoro timer — thin ring, split monospace time, tap to start or pause. Polished to match the DND card size and proportions. | `lucide-react` | [`components/widgets/pomodoro-widget.tsx`](components/widgets/pomodoro-widget.tsx) | [Guide](references/craft/pomodoro.md) |
+| **Presence Dock** | `presence-dock` | Collaborator presence dock with MacDock-sized avatar tiles and expandable member list. | None (core) | [`components/docks/presence-dock.tsx`](components/docks/presence-dock.tsx) | [Guide](references/craft/presence-dock.md) |
+| **Prism Depth** | `prism-depth-button` | Dark depth button with a cyan edge flare, rim glow, and layered core veil — pass any label as children. | None (core) | [`components/buttons/prism-depth-button.tsx`](components/buttons/prism-depth-button.tsx) | [Guide](references/craft/prism-depth-button.md) |
+| **Progress Ring Card** | `progress-ring-card` | Animated SVG ring with percentage label and clickable stage rows below. Defaults to Design/Development/Testing — pass your own milestones. | None (core) | [`components/others/progress-ring-card.tsx`](components/others/progress-ring-card.tsx) | [Guide](references/craft/progress-ring-card.md) |
+| **Quantity Stepper** | `quantity-stepper-button` | Inline minus / count / plus control for carts and forms. Clamps between min and max, disables at the edges. | `lucide-react` | [`components/buttons/quantity-stepper-button.tsx`](components/buttons/quantity-stepper-button.tsx) | [Guide](references/craft/quantity-stepper-button.md) |
+| **Radio Group Field Input** | `radio-group-field-input` | Card-style radio group for checkout and settings flows. Vertical or horizontal layout, descriptions, and arrow-key navigation. | None (core) | [`components/inputs/radio-group-field-input.tsx`](components/inputs/radio-group-field-input.tsx) | [Guide](references/craft/radio-group-field-input.md) |
+| **Rain Prism** | `rain-prism-background` | Moody rainfall with angled streaks and a soft prism band across the scene — music, film, and reflective editorial layouts. | None (core) | [`components/background-gradient/rain-prism-background.tsx`](components/background-gradient/rain-prism-background.tsx) | [Guide](references/craft/rain-prism-background.md) |
+| **Recent Transactions Table** | `recent-transactions-table` | Stripe-style transaction list with positive and negative amounts and simple pagination. | `lucide-react` | [`components/table/recent-transactions-table.tsx`](components/table/recent-transactions-table.tsx) | [Guide](references/craft/recent-transactions-table.md) |
+| **Recessed Inset** | `inset-button` | Recessed inset button — looks pressed into the surface. Light or dark variant. Pass any children. | None (core) | [`components/buttons/inset-button.tsx`](components/buttons/inset-button.tsx) | [Guide](references/craft/inset-button.md) |
+| **Recorder Face** | `recorder-face` | A quirky record button with a mascot face, circular dial, and live timer. Tap to start and pause — feels like a tiny dedicated recorder app. | `lucide-react` | [`components/widgets/recorder-face-widget.tsx`](components/widgets/recorder-face-widget.tsx) | [Guide](references/craft/recorder-face.md) |
+| **Resource Links Panel** | `resource-links-panel` | Resource link list with logo, name, description, and domain per row — same layout as the homepage Resources section. Copy and pass title + items. | `next` | [`components/resources/resource-links-panel.tsx`](components/resources/resource-links-panel.tsx) | [Guide](references/craft/resource-links-panel.md) |
+| **Retail Price Tag** | `retail-price-tag` | Hanging store tag with discount badge, sale price, SKU, and barcode stripes. E-commerce editorial and product drops. | None (core) | [`components/pricing/retail-price-tag-card.tsx`](components/pricing/retail-price-tag-card.tsx) | [Guide](references/craft/retail-price-tag.md) |
+| **Reverse Diagonal Box** | `reverse-diagonal-box-pattern` | Mirrored 45° hairline hatch — same quiet stage as Diagonal Box, rotated right to left for visual variety. | None (core) | [`components/background-pattern/reverse-diagonal-box-pattern.tsx`](components/background-pattern/reverse-diagonal-box-pattern.tsx) | [Guide](references/craft/reverse-diagonal-box-pattern.md) |
+| **Ride Pickup** | `ride-pickup` | Uber-style pickup card with brand, ETA, car illustration, and vehicle ID. The waiting-screen moment, ready to paste into a mobility app. | `lucide-react`, `next` | [`components/widgets/ride-pickup-widget.tsx`](components/widgets/ride-pickup-widget.tsx) | [Guide](references/craft/ride-pickup.md) |
+| **Sand Drift** | `sand-drift-background` | Layered desert dunes in stone and amber tones with fine grain — travel, hospitality, and calm wellness layouts. | None (core) | [`components/background-gradient/sand-drift-background.tsx`](components/background-gradient/sand-drift-background.tsx) | [Guide](references/craft/sand-drift-background.md) |
+| **Search Input** | `search-input` | Search field with leading icon and clear button. Controlled or uncontrolled value, hidden native cancel, and keyboard-friendly reset. | `lucide-react` | [`components/inputs/search-input.tsx`](components/inputs/search-input.tsx) | [Guide](references/craft/search-input.md) |
+| **Segmented Toggle Button** | `segmented-toggle-button` | iOS segmented control — sliding white pill between Day, Week, and Month. Pass your own options array for view modes or filters. | None (core) | [`components/buttons/segmented-toggle-button.tsx`](components/buttons/segmented-toggle-button.tsx) | [Guide](references/craft/segmented-toggle-button.md) |
+| **Select Field Input** | `select-field-input` | Custom listbox select with styled dropdown, keyboard navigation, click-outside close, and hidden input for native form posts. | `lucide-react` | [`components/inputs/select-field-input.tsx`](components/inputs/select-field-input.tsx) | [Guide](references/craft/select-field-input.md) |
+| **Share Menu** | `share-menu` | Square icon trigger opens a horizontal brand rail — four social tiles in a row plus a full-width copy button. | `lucide-react` | [`components/dropdowns/share-menu-dropdown.tsx`](components/dropdowns/share-menu-dropdown.tsx) | [Guide](references/craft/share-menu.md) |
+| **Sheen Pill** | `sheen-pill-button` | Frosted pill with layered shade veil, light band, and rim wire — hover brightens the sheen and clears the fill. Pass width, height, and highlight to tune the frame. | None (core) | [`components/buttons/sheen-pill-button.tsx`](components/buttons/sheen-pill-button.tsx) | [Guide](references/craft/sheen-pill-button.md) |
+| **Slate Chip Switch** | `slate-chip-switch` | Smooth pill chip switch with a white thumb and sky on-state fill — a cleaner alternative to textured toggles. | None (core) | [`components/buttons/slate-chip-switch.tsx`](components/buttons/slate-chip-switch.tsx) | [Guide](references/craft/slate-chip-switch.md) |
+| **Sleep Score** | `sleep-score` | Sleep score in the DND face layout — sleeping mascot at the bottom, score and quality above, duration tucked below. | `lucide-react` | [`components/widgets/sleep-score-widget.tsx`](components/widgets/sleep-score-widget.tsx) | [Guide](references/craft/sleep-score.md) |
+| **Slide to Confirm** | `slide-to-confirm-button` | Drag the knob across the track to commit an action — snaps back if you release early, locks green when confirmed. Great for irreversible or high-intent actions. | `lucide-react` | [`components/buttons/slide-to-confirm-button.tsx`](components/buttons/slide-to-confirm-button.tsx) | [Guide](references/craft/slide-to-confirm-button.md) |
+| **Slow Living Polaroid** | `slow-living-polaroid` | Dark editorial layout with a taped, tilted polaroid and lowercase lifestyle copy. Slow living, coffee brands, quiet product launches. | `next` | [`components/gallery/slow-living-polaroid-card.tsx`](components/gallery/slow-living-polaroid-card.tsx) | [Guide](references/craft/slow-living-polaroid.md) |
+| **Soft Spotlight** | `soft-spotlight-background` | Gallery stage light from above with a gentle vignette — product reveals, keynote heroes, and museum-style layouts. | None (core) | [`components/background-gradient/soft-spotlight-background.tsx`](components/background-gradient/soft-spotlight-background.tsx) | [Guide](references/craft/soft-spotlight-background.md) |
+| **Spin Loader** | `spin-loader` | Minimal spinning loader built on a lucide icon — defaults to Loader, but pass any icon prop. Sizes: sm, md, lg. | `lucide-react` | [`components/loaders/spin-loader.tsx`](components/loaders/spin-loader.tsx) | [Guide](references/craft/spin-loader.md) |
+| **Spotlight Bar** | `spotlight-bar` | Spotlight-style command search in the frosted dock shell — keyboard nav and suggestions. | `lucide-react` | [`components/docks/spotlight-bar.tsx`](components/docks/spotlight-bar.tsx) | [Guide](references/craft/spotlight-bar.md) |
+| **Stacked Cards Effect** | `stacked-cards-effect` | Three skewed cards fanned behind a front hero card — hover brings subtle motion. Collection and portfolio layouts with depth, no Three.js required. | `next` | [`components/others/stacked-cards-effect.tsx`](components/others/stacked-cards-effect.tsx) | [Guide](references/craft/stacked-cards-effect.md) |
+| **Stacked Folder Card** | `stacked-folder-card` | Three stacked folder cards with thick white borders and smooth hover rotation — back and middle peeks bring any card to the front. | `next` | [`components/files/stacked-folder-card.tsx`](components/files/stacked-folder-card.tsx) | [Guide](references/craft/stacked-folder-card.md) |
+| **Stamp Postcard** | `stamp-postcard` | Vintage postcard with landscape photo, postage stamp overlay, handwritten message, and posted-from address. Travel and lifestyle brands love this one. | `next` | [`components/gallery/stamp-postcard-card.tsx`](components/gallery/stamp-postcard-card.tsx) | [Guide](references/craft/stamp-postcard.md) |
+| **Step Count** | `step-count` | Editorial step stat — light wide card, large number, goal in a quiet footer row. No progress bars or icons. | None (core) | [`components/widgets/step-count-widget.tsx`](components/widgets/step-count-widget.tsx) | [Guide](references/craft/step-count.md) |
+| **Sticky Note Polaroid Frame** | `sticky-note-polaroid-frame` | Polaroid-style frame with a paper-clipped sticky note overlay — pass noteHeader, noteBody, noteFooter, and any image or video as children. | None (core) | [`components/frames/sticky-note-polaroid-frame.tsx`](components/frames/sticky-note-polaroid-frame.tsx) | [Guide](references/craft/sticky-note-polaroid-frame.md) |
+| **Stopwatch** | `stopwatch` | Millisecond-precision stopwatch with reset, play-pause, and stop in a compact white widget. Running state shown with a small indicator dot. | `lucide-react` | [`components/widgets/stopwatch-widget.tsx`](components/widgets/stopwatch-widget.tsx) | [Guide](references/craft/stopwatch.md) |
+| **Sunrise Horizon** | `sunrise-horizon-background` | Warm dawn sky with peach horizon bands, a soft sun glow, and cool teal lift at the base — editorial hero sections and landing pages. | None (core) | [`components/background-gradient/sunrise-horizon-background.tsx`](components/background-gradient/sunrise-horizon-background.tsx) | [Guide](references/craft/sunrise-horizon-background.md) |
+| **Sunset Bloom** | `sunset-bloom-background` | Golden-hour aurora with orange, rose, amber, and sun yellow blooms — events, photography, and warm brand storytelling. | None (core) | [`components/background-gradient/sunset-bloom-background.tsx`](components/background-gradient/sunset-bloom-background.tsx) | [Guide](references/craft/sunset-bloom-background.md) |
+| **Switch Field Input** | `switch-field-input` | Toggle switch with role=switch, keyboard support, hidden input for forms, and label/hint/error layout. | None (core) | [`components/inputs/switch-field-input.tsx`](components/inputs/switch-field-input.tsx) | [Guide](references/craft/switch-field-input.md) |
+| **System Alert** | `system-alert` | Settings-style iOS alert — amber app tile, title: description in one natural line. For storage, limits, and warnings. | `lucide-react` | [`components/notifications/system-alert-banner.tsx`](components/notifications/system-alert-banner.tsx) | [Guide](references/craft/system-alert.md) |
+| **Tactile 3D** | `3d-button` | Universal 3D button with tactile keycap shadows — pass any children (label, icon + label). Variants: solid, soft, muted. Sizes: sm, md, lg, icon. Press sinks the key in. | None (core) | [`components/buttons/three-d-button.tsx`](components/buttons/three-d-button.tsx) | [Guide](references/craft/3d-button.md) |
+| **Tactile 3D Icon** | `3d-icon-button` | Square 3D icon button — pass any icon as children and a required label for accessibility. Same solid / soft / muted materials as ThreeDButton. | None (core) | [`components/buttons/three-d-icon-button.tsx`](components/buttons/three-d-icon-button.tsx) | [Guide](references/craft/3d-icon-button.md) |
+| **Tactile Copy Button** | `craft-copy-button` | Copies text to the clipboard and cross-fades the copy icon into a check with a Copied label. Monospace value, resets on its own. | `lucide-react` | [`components/buttons/copy-button.tsx`](components/buttons/copy-button.tsx) | [Guide](references/craft/craft-copy-button.md) |
+| **Tasks Table** | `tasks-table` | Project tasks with checkboxes, assignee avatars, and due dates. Tap to mark complete. | `lucide-react`, `next` | [`components/table/tasks-table.tsx`](components/table/tasks-table.tsx) | [Guide](references/craft/tasks-table.md) |
+| **Team Member** | `team-member` | Full-bleed portrait card — hover reveals GitHub and mail buttons, role, name, and bio. About pages without the generic card grid. | `lucide-react`, `next` | [`components/users/team-member-card.tsx`](components/users/team-member-card.tsx) | [Guide](references/craft/team-member.md) |
+| **Team Member Profile Grid** | `team-member-profile-grid` | Responsive team grid with vertical portrait cards — section header plus name, role, bio, and profile link per member. | `next` | [`components/profile/team-member-profile-grid.tsx`](components/profile/team-member-profile-grid.tsx) | [Guide](references/craft/team-member-profile-grid.md) |
+| **Team Members Table** | `team-members-table` | Team members with profile photos, email, role, and status. Uses /profile-picture.png and /woman.png avatars. | `lucide-react`, `next` | [`components/table/team-members-table.tsx`](components/table/team-members-table.tsx) | [Guide](references/craft/team-members-table.md) |
+| **Terminal Log** | `terminal-log` | macOS terminal window with traffic-light dots, colored log lines, blinking cursor, and status footer. Dev tool aesthetic for changelogs or demos. | `lucide-react` | [`components/others/terminal-log-card.tsx`](components/others/terminal-log-card.tsx) | [Guide](references/craft/terminal-log.md) |
+| **Terrazzo Fragment** | `terrazzo-fragment-background` | Stone terrazzo base with scattered rose, teal, amber, and clay fragments — interior brands, cafés, and design studios. | None (core) | [`components/background-gradient/terrazzo-fragment-background.tsx`](components/background-gradient/terrazzo-fragment-background.tsx) | [Guide](references/craft/terrazzo-fragment-background.md) |
+| **Testimonial** | `testimonial` | Auto-advancing testimonial carousel with stars, quote, avatar, and dot navigation. Social proof that moves on its own. | `lucide-react`, `next` | [`components/users/testimonial-card.tsx`](components/users/testimonial-card.tsx) | [Guide](references/craft/testimonial.md) |
+| **Text Field Input** | `text-field-input` | Standard labeled text field with hint and error states. Supports all native input types, required marker, disabled, and full a11y wiring. | None (core) | [`components/inputs/text-field-input.tsx`](components/inputs/text-field-input.tsx) | [Guide](references/craft/text-field-input.md) |
+| **Text Loader** | `text-loader` | Animated text loader with a spinning color orb and staggered letter pulses. Pass text, variant, and textColor to match your UI. | None (core) | [`components/loaders/text-loader.tsx`](components/loaders/text-loader.tsx) | [Guide](references/craft/text-loader.md) |
+| **Textarea Field Input** | `textarea-field-input` | Multiline field with live character count, max length guard, resize support, and the same label/hint/error pattern as text fields. | None (core) | [`components/inputs/textarea-field-input.tsx`](components/inputs/textarea-field-input.tsx) | [Guide](references/craft/textarea-field-input.md) |
+| **Thermal Receipt** | `thermal-receipt` | Monospace receipt with line items, tax, total, perforated edges, and a QR footer. Reads like paper from a real register. | `lucide-react` | [`components/others/thermal-receipt-card.tsx`](components/others/thermal-receipt-card.tsx) | [Guide](references/craft/thermal-receipt.md) |
+| **Threads Post** | `threads-post` | Threads-style post with avatar thread line, text, optional image, and engagement counts. Like toggles on tap. | `lucide-react`, `next` | [`components/socials/threads-post-card.tsx`](components/socials/threads-post-card.tsx) | [Guide](references/craft/threads-post.md) |
+| **Toast Notification** | `toast-notification` | Light snackbar with check icon — message, undo action, slides up on dismiss. For save confirmations and quick feedback. | `lucide-react` | [`components/notifications/toast-notification-banner.tsx`](components/notifications/toast-notification-banner.tsx) | [Guide](references/craft/toast-notification.md) |
+| **Toggle Pricing Cards** | `toggle-pricing-cards` | Monthly and yearly billing toggle that updates three plan cards side by side — price and feature checklist included. SaaS pricing page, one paste away. | `lucide-react` | [`components/pricing/toggle-pricing-cards.tsx`](components/pricing/toggle-pricing-cards.tsx) | [Guide](references/craft/toggle-pricing-cards.md) |
+| **Torch Face** | `torch-face` | Yellow flashlight toggle with a face that lights up when the torch is on. Small detail, but the kind people notice on a control sheet. | `lucide-react` | [`components/widgets/torch-face-widget.tsx`](components/widgets/torch-face-widget.tsx) | [Guide](references/craft/torch-face.md) |
+| **Transform Box Frame** | `transform-box-frame` | Design-tool bounding box with separate line and handle colors — defaults to all black; pass lineColor and handleColor for dual-tone frames. | None (core) | [`components/frames/transform-box-frame.tsx`](components/frames/transform-box-frame.tsx) | [Guide](references/craft/transform-box-frame.md) |
+| **Transform Plus Frame** | `transform-plus-frame` | Bounding box with plus corner handles — thicker handle strokes than border lines. Defaults to all black; pass lineColor and handleColor for dual-tone frames. | None (core) | [`components/frames/transform-plus-frame.tsx`](components/frames/transform-plus-frame.tsx) | [Guide](references/craft/transform-plus-frame.md) |
+| **Travel Postcard** | `travel-postcard` | Vintage sepia postcard with map badge, greeting title, location, and author signature. Wanderlust landing pages and newsletter headers. | `lucide-react`, `next` | [`components/travel/travel-postcard-card.tsx`](components/travel/travel-postcard-card.tsx) | [Guide](references/craft/travel-postcard.md) |
+| **Tropical Tide** | `tropical-tide-background` | Vibrant aurora wash in turquoise, lime, sky blue, and sea green — travel, resorts, and summer product drops. | None (core) | [`components/background-gradient/tropical-tide-background.tsx`](components/background-gradient/tropical-tide-background.tsx) | [Guide](references/craft/tropical-tide-background.md) |
+| **Twitter Post** | `twitter-post` | Tweet card with avatar, handle, timestamp, hashtags, and full engagement row. For social embeds, mockups, or feed previews. | `lucide-react`, `next` | [`components/socials/twitter-post-card.tsx`](components/socials/twitter-post-card.tsx) | [Guide](references/craft/twitter-post.md) |
+| **Twitter Profile** | `twitter-profile` | Twitter/X profile with cover, avatar, bio, location, website link, and follower counts. Follow button included. | `lucide-react`, `next` | [`components/socials/twitter-profile-card.tsx`](components/socials/twitter-profile-card.tsx) | [Guide](references/craft/twitter-profile.md) |
+| **User Menu** | `user-menu` | Account pill with avatar, name, and email that opens into profile, settings, messages, and sign out. The header dropdown every SaaS app needs, with keyboard shortcut labels. | `lucide-react`, `next` | [`components/dropdowns/user-menu-dropdown.tsx`](components/dropdowns/user-menu-dropdown.tsx) | [Guide](references/craft/user-menu.md) |
+| **User Profile** | `user-profile` | Author byline on warm editorial paper — square portrait, serif name, and text links. Built for personal sites and portfolio sidebars. | `lucide-react`, `next` | [`components/profile/user-profile-card.tsx`](components/profile/user-profile-card.tsx) | [Guide](references/craft/user-profile.md) |
+| **Users Select Table** | `users-select-table` | Bulk-select users table with header checkbox and live selection count. Clean white admin pattern for permissions or exports. | `lucide-react`, `next` | [`components/table/users-select-table.tsx`](components/table/users-select-table.tsx) | [Guide](references/craft/users-select-table.md) |
+| **Voice Assistant** | `voice-assistant` | Animated equalizer bars and a mic button that flip between idle and listening. Builds the voice-AI moment without building the whole assistant. | `lucide-react` | [`components/widgets/voice-assistant-widget.tsx`](components/widgets/voice-assistant-widget.tsx) | [Guide](references/craft/voice-assistant.md) |
+| **Wallet Pass** | `wallet-pass` | Flippable membership pass — gradient front with tier and expiry, QR grid on the back. Tap or hover to flip between sides. | `next` | [`components/wallet/wallet-pass-card.tsx`](components/wallet/wallet-pass-card.tsx) | [Guide](references/craft/wallet-pass.md) |
+| **Weather Snapshot** | `weather-snapshot` | Compact weather card with temperature, highs/lows, humidity, and wind — clear or rain variants. | `lucide-react` | [`components/others/weather-snapshot-card.tsx`](components/others/weather-snapshot-card.tsx) | [Guide](references/craft/weather-snapshot.md) |
+| **Week Strip Calendar** | `week-strip-calendar` | Horizontal week strip for booking and scheduling apps — arrow through weeks, tap a day to select. | `lucide-react` | [`components/calendar/week-strip-calendar.tsx`](components/calendar/week-strip-calendar.tsx) | [Guide](references/craft/week-strip-calendar.md) |
+| **Wifi Toggle** | `wifi-toggle` | The toggle you'd expect on an iPhone — network name, on/off switch, that familiar iOS weight. Drop it into any control panel or settings screen. | `lucide-react` | [`components/widgets/wifi-toggle-widget.tsx`](components/widgets/wifi-toggle-widget.tsx) | [Guide](references/craft/wifi-toggle.md) |
+| **Workspace Switcher** | `workspace-switcher` | Rectangular org bar that expands inline — workspace list opens inside the same bordered box, not a floating panel. | `lucide-react` | [`components/dropdowns/workspace-switcher-dropdown.tsx`](components/dropdowns/workspace-switcher-dropdown.tsx) | [Guide](references/craft/workspace-switcher.md) |
+
+---
+
+## Comprehensive Guides Suite
+
+- [Multi-Style Presets Guide](./references/guides/style-presets.md): Architecture and token matrices for minimal, origin, enterprise, glow, ios, and brutalist styles.
+- [Motion Guides & Principles](./references/guides/motion-patterns.md): Decision framework, physics tokens, timing tables, recipes, and accessibility rules.
+- [Design System Architecture & Checklist](./references/guides/design-system-checklist.md): Standards for color contrast (WCAG 2.1 AA/AAA), typography scales, spacing grids, and component health.
+- [Motion Engineering Guide](./references/guides/motion-engineering.md): Motion v12/v13+ architecture, spring formulas, shared layoutId morphs, and AnimatePresence.
+- [Motion Performance & 60/120 FPS](./references/guides/motion-performance.md): Compositor properties, avoiding layout thrashing, and layer budgets.
+- [Baseline UI Craft & Anti-Slop](./references/guides/baseline-ui-craft.md): Design engineering principles, optical alignment, spacing rhythm, and micro-interactions.
+- [The 12 Canonical Interaction Transitions](./references/guides/interaction-transitions.md): Transitions.dev interaction patterns and token specs.
+- [Universal Mobile-First Interaction Patterns](./references/guides/universal-mobile-patterns.md): Touch ergonomics, haptic feedback semantics, and swipe gestures.
+- [Craft & Surface Design System](./references/guides/craft-surface-design-system.md): Visual language, tactile 3D elevation, typography pairing, and component patterns.
+- [Enterprise Dashboard Architecture](./references/guides/enterprise-dashboard-patterns.md): High-density data grids, kanban boards, faceted query builders, and timelines.
+
+---
+
+## Animation Physics & Motion Tokens
+
+Components use standardized spring and easing constants defined in [`lib/ease.ts`](./lib/ease.ts):
+
+```typescript
+export const EASE_OUT = [0.16, 1, 0.3, 1] as const;
+export const EASE_IN_OUT = [0.77, 0, 0.175, 1] as const;
+export const EASE_EMPHASIZED = [0.2, 0, 0, 1] as const;
+
+export const SPRING_PRESS = {
+  type: "spring",
+  stiffness: 500,
+  damping: 30,
+  mass: 0.6,
+} as const;
+
+export const SPRING_BOUNCE = {
+  type: "spring",
+  stiffness: 300,
+  damping: 18,
+  mass: 0.8,
+} as const;
+
+export const SPRING_LAYOUT = {
+  type: "spring",
+  stiffness: 360,
+  damping: 32,
+  mass: 0.6,
+} as const;
+
+export const SPRING_PANEL = {
+  type: "spring",
+  stiffness: 420,
+  damping: 40,
+  mass: 0.5,
+} as const;
+```
+
+---
+
+## Validate the package
+
+Run the dependency-free integrity gate, release checks, and catalog evaluation before publishing a change:
+
+```bash
+python scripts/verify_skill.py
+python scripts/test_release.py
+python evals/catalog_eval.py
+```
+
+The checks cover the 339-component catalog, referenced files, installer safety, generated docs, dependency coverage, and the source-reference exclusion rule.
+
+---
+
+## Directory Structure
+
+```text
+motion-ui-skill/
+├── README.md                      # Comprehensive guide & installation instructions
+├── SKILL.md                       # Main agent skill definition with catalog & instructions
+├── agents/openai.yaml             # Codex skill-list metadata and default prompt
+├── catalog.json                   # Machine-readable metadata for all 339 components
+├── components/                    # Production TypeScript/React source code
+│   ├── motion/                    # 80 motion primitives and composed blocks
+│   ├── agents/                    # 17 conversational agent surfaces
+│   ├── previews/                  # Component preview & demo implementations
+│   └── [category]/                # 209 craft & surface component files across categories
+├── icons/                         # 21 custom brand and annotation icons
+├── lib/                           # Foundation tokens, easing physics, and utility hooks
+│   ├── ease.ts                    # Easing curves and spring physics constants
+│   ├── styles.ts                  # Multi-style preset tokens (minimal, origin, enterprise, glow, ios, brutalist)
+│   ├── utils.ts                   # cn() utility
+│   ├── cn.ts                      # cn() re-export
+│   └── hooks/                     # Custom hooks (use-haptic, use-dismiss, use-measure, etc.)
+├── references/                    # Offline-first detailed markdown component documentation
+│   ├── motion/                    # 90 component guides with props & examples
+│   ├── agents/                    # 17 agent component guides
+│   ├── blocks/                    # 23 block guides
+│   ├── craft/                     # 209 craft and surface component guides
+│   ├── guides/                    # Complete suite of 10 motion & design system guides
+│   └── codex-install.md            # Codex app and CLI installation guide
+├── prompts/
+│   └── install-motion-ui.md        # Copy-paste prompt for AI-agent installation
+├── evals/
+│   └── catalog_eval.py              # Dependency-free catalog coverage evaluation
+└── scripts/
+    ├── install-component.py       # Standalone CLI tool to install components into projects
+    ├── build_docs.py              # Script to synchronize SKILL.md and README.md from catalog
+    ├── verify_skill.py            # Dependency-free package integrity gate
+    └── test_release.py            # Installer and release regression checks
+```
+
+---
+
+## License
+
+This project is licensed under the [MIT License](./LICENSE).