motion-ui-skill 2.0.0

package/references/blocks/not-found.md

@@ -0,0 +1,228 @@
+---
+title: "404 / Not Found"
+description: "Animated 404 pages in five styles: glitch scramble, magnetic digits, cursor spotlight, a fanning card stack and a typed terminal."
+category: "Blocks"
+publishedAt: "2026-06-21"
+updatedAt: "2026-06-21"
+documentation: "references/blocks/not-found.md"
+markdown: "references/blocks/not-found.md"
+license: "MIT"
+---
+
+# 404 / Not Found
+
+> Animated 404 pages in five styles: glitch scramble, magnetic digits, cursor spotlight, a fanning card stack and a typed terminal.
+
+## Install
+
+### Glitch
+
+Digits scramble through random glyphs before resolving, with a chromatic split on hover.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py not-found-glitch --dest ./src
+```
+
+### Magnetic
+
+Each digit is cursor-attracted via the Magnetic wrapper and springs back on leave.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py not-found-magnetic --dest ./src
+```
+
+### Spotlight
+
+A dark panel where a cursor-tracked spotlight reveals the bright code from a dim base.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py not-found-spotlight --dest ./src
+```
+
+### Stacked
+
+A code card over a hidden stack that fans out with a spring on hover.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py not-found-stacked --dest ./src
+```
+
+### Terminal
+
+A terminal window that types a failed cd command and a 404 status, with a blinking caret.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py not-found-terminal --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+### Glitch usage
+
+Digits scramble through random glyphs before resolving, with a chromatic split on hover.
+
+```tsx
+"use client";
+
+import { NotFoundGlitch } from "@/components/motion/not-found/glitch";
+
+export function NotFoundGlitchPreview() {
+  return (
+    <div className="w-full">
+      <NotFoundGlitch />
+    </div>
+  );
+}
+```
+
+### Magnetic usage
+
+Each digit is cursor-attracted via the Magnetic wrapper and springs back on leave.
+
+```tsx
+"use client";
+
+import { NotFoundMagnetic } from "@/components/motion/not-found/magnetic";
+
+export function NotFoundMagneticPreview() {
+  return (
+    <div className="w-full">
+      <NotFoundMagnetic />
+    </div>
+  );
+}
+```
+
+### Spotlight usage
+
+A dark panel where a cursor-tracked spotlight reveals the bright code from a dim base.
+
+```tsx
+"use client";
+
+import { NotFoundSpotlight } from "@/components/motion/not-found/spotlight";
+
+export function NotFoundSpotlightPreview() {
+  return (
+    <div className="w-full">
+      <NotFoundSpotlight />
+    </div>
+  );
+}
+```
+
+### Stacked usage
+
+A code card over a hidden stack that fans out with a spring on hover.
+
+```tsx
+"use client";
+
+import { NotFoundStacked } from "@/components/motion/not-found/stacked";
+
+export function NotFoundStackedPreview() {
+  return (
+    <div className="w-full">
+      <NotFoundStacked />
+    </div>
+  );
+}
+```
+
+### Terminal usage
+
+A terminal window that types a failed cd command and a 404 status, with a blinking caret.
+
+```tsx
+"use client";
+
+import { NotFoundTerminal } from "@/components/motion/not-found/terminal";
+
+export function NotFoundTerminalPreview() {
+  return (
+    <div className="w-full">
+      <NotFoundTerminal />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### NotFoundGlitch
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+| `code` | `string` | `404` | No | The big status code. |
+| `title` | `string` | `Page not found` | No | — |
+| `description` | `string` | `The page you are looking for moved, vanished, or never existed.` | No | — |
+| `homeHref` | `string` | — | No | — |
+| `homeLabel` | `string` | — | No | — |
+| `browseHref` | `string` | — | No | — |
+| `browseLabel` | `string` | — | No | — |
+
+### NotFoundMagnetic
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+| `code` | `string` | `404` | No | The big status code. |
+| `title` | `string` | `Page not found` | No | — |
+| `description` | `string` | `The page you are looking for moved, vanished, or never existed.` | No | — |
+| `homeHref` | `string` | — | No | — |
+| `homeLabel` | `string` | — | No | — |
+| `browseHref` | `string` | — | No | — |
+| `browseLabel` | `string` | — | No | — |
+
+### NotFoundSpotlight
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+| `code` | `string` | `404` | No | The big status code. |
+| `title` | `string` | `Page not found` | No | — |
+| `description` | `string` | `The page you are looking for moved, vanished, or never existed.` | No | — |
+| `homeHref` | `string` | — | No | — |
+| `homeLabel` | `string` | — | No | — |
+| `browseHref` | `string` | — | No | — |
+| `browseLabel` | `string` | — | No | — |
+
+### NotFoundStacked
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+| `code` | `string` | `404` | No | The big status code. |
+| `title` | `string` | `Page not found` | No | — |
+| `description` | `string` | `The page you are looking for moved, vanished, or never existed.` | No | — |
+| `homeHref` | `string` | — | No | — |
+| `homeLabel` | `string` | — | No | — |
+| `browseHref` | `string` | — | No | — |
+| `browseLabel` | `string` | — | No | — |
+
+### NotFoundTerminal
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+| `code` | `string` | `404` | No | The big status code. |
+| `title` | `string` | `Page not found` | No | — |
+| `description` | `string` | `The page you are looking for moved, vanished, or never existed.` | No | — |
+| `homeHref` | `string` | — | No | — |
+| `homeLabel` | `string` | — | No | — |
+| `browseHref` | `string` | — | No | — |
+| `browseLabel` | `string` | — | No | — |
+

package/references/blocks/notification-stack.md

@@ -0,0 +1,92 @@
+---
+title: "Notification Stack"
+description: "Compact notification cards that spring from a stacked summary into a readable list on hover, focus or tap."
+category: "Blocks"
+publishedAt: "2026-07-14"
+updatedAt: "2026-07-14"
+documentation: "references/blocks/notification-stack.md"
+markdown: "references/blocks/notification-stack.md"
+license: "MIT"
+---
+
+# Notification Stack
+
+> Compact notification cards that spring from a stacked summary into a readable list on hover, focus or tap.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py notification-stack --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { RotateCw } from "lucide-react";
+import {
+  NotificationStack,
+  type NotificationStackItem,
+} from "@/components/motion/notification-stack";
+
+const notifications: NotificationStackItem[] = [
+  {
+    id: "import-failed",
+    title: "Orders import failed",
+    description: "42s · TimeoutError at Step 2",
+    trailing: (
+      <span className="inline-flex items-center gap-1 text-amber-500 dark:text-amber-400">
+        <RotateCw className="h-3.5 w-3.5" aria-hidden="true" />
+        2
+      </span>
+    ),
+  },
+  {
+    id: "sla-breach",
+    title: "SLA breach",
+    description: "2m 11s · Data enrichment",
+  },
+  {
+    id: "sync-fixed",
+    title: "Product sync auto-fixed",
+    description: "5m · 404 on GET /products",
+  },
+];
+
+export function NotificationStackPreview() {
+  return (
+    <div className="flex w-full items-center justify-center pt-52 pb-6">
+      <NotificationStack items={notifications} />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### NotificationStack
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `NotificationStackItem[]` | — | Yes | — |
+| `expanded` | `boolean` | — | No | — |
+| `defaultExpanded` | `boolean` | `false` | No | — |
+| `onExpandedChange` | `((expanded: boolean) => void)` | — | No | — |
+| `onViewAll` | `(() => void)` | — | No | — |
+| `maxVisible` | `number` | `3` | No | — |
+| `collapsedLabel` | `string` | `Notifications` | No | — |
+| `expandedLabel` | `string` | `View all` | No | — |
+| `emptyLabel` | `string` | `All caught up` | No | — |
+| `className` | `string` | — | No | — |
+| `classNames` | `NotificationStackClassNames` | — | No | — |
+

package/references/blocks/otp-input.md

@@ -0,0 +1,85 @@
+---
+title: "OTP Input"
+description: "One-time-code input with a gliding focus ring, digits that roll in per slot, error shake and a success check draw."
+category: "Blocks"
+publishedAt: "2026-06-13"
+updatedAt: "2026-07-13"
+documentation: "references/blocks/otp-input.md"
+markdown: "references/blocks/otp-input.md"
+license: "MIT"
+---
+
+# OTP Input
+
+> One-time-code input with a gliding focus ring, digits that roll in per slot, error shake and a success check draw.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py otp-input --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { OTPInput, type OTPStatus } from "@/components/motion/otp-input";
+
+const CODE = "123456";
+
+export function OTPInputPreview() {
+  const [value, setValue] = useState("");
+  const [status, setStatus] = useState<OTPStatus>("idle");
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      <OTPInput
+        label="Verification code"
+        hint={`Enter ${CODE} to verify.`}
+        successMessage="Verified."
+        errorMessage="Wrong code, try again."
+        value={value}
+        status={status}
+        onChange={(v) => {
+          setValue(v);
+          if (status !== "idle") setStatus("idle");
+        }}
+        onComplete={(v) => setStatus(v === CODE ? "success" : "error")}
+      />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### OTPInput
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `length` | `number` | `6` | No | Number of slots. Default 6. |
+| `value` | `string` | — | No | — |
+| `defaultValue` | `string` | — | No | — |
+| `onChange` | `((value: string) => void)` | — | No | — |
+| `onComplete` | `((value: string) => void)` | — | No | Fires once every slot is filled. |
+| `label` | `string` | — | No | Optional label rendered above the slots. |
+| `hint` | `string` | — | No | Helper text shown below the slots while idle. |
+| `successMessage` | `string` | — | No | Message shown below the slots when status is "success". |
+| `errorMessage` | `string` | — | No | Message shown below the slots when status is "error". |
+| `status` | `"error" \| "success" \| "idle"` | `idle` | No | External validation feedback. "error" shakes, "success" draws a check. |
+| `mask` | `boolean` | `false` | No | Render dots instead of the typed digits. |
+| `disabled` | `boolean` | `false` | No | — |
+| `autoFocus` | `boolean` | `false` | No | — |
+| `aria-label` | `string` | `One-time passcode` | No | Accessible label for the underlying input. |
+| `className` | `string` | — | No | — |
+

package/references/blocks/overflow-actions.md

@@ -0,0 +1,105 @@
+---
+title: "Overflow Actions"
+description: "Connected pill rail for primary actions that springs open to reveal extra controls."
+category: "Blocks"
+publishedAt: "2026-06-19"
+updatedAt: "2026-06-28"
+documentation: "references/blocks/overflow-actions.md"
+markdown: "references/blocks/overflow-actions.md"
+license: "MIT"
+---
+
+# Overflow Actions
+
+> Connected pill rail for primary actions that springs open to reveal extra controls.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py overflow-actions --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { CalendarClock, Eye, GitBranch, Pin } from "lucide-react";
+import { useState } from "react";
+import {
+  type OverflowActionItem,
+  OverflowActions,
+} from "@/components/motion/overflow-actions";
+
+const primaryActions: OverflowActionItem[] = [
+  {
+    id: "preview",
+    label: "Preview",
+    icon: <Eye className="h-4 w-4" />,
+  },
+  {
+    id: "pin",
+    label: "Pin",
+    icon: <Pin className="h-4 w-4" />,
+  },
+];
+
+const overflowActions: OverflowActionItem[] = [
+  {
+    id: "branch",
+    label: "Branch",
+    icon: <GitBranch className="h-4 w-4" />,
+  },
+  {
+    id: "schedule",
+    label: "Schedule",
+    icon: <CalendarClock className="h-4 w-4" />,
+  },
+];
+
+export function OverflowActionsPreview() {
+  const [expanded, setExpanded] = useState(false);
+
+  return (
+    <div className="flex w-full items-center justify-center">
+      <OverflowActions
+        primaryActions={primaryActions}
+        overflowActions={overflowActions}
+        expanded={expanded}
+        onExpandedChange={setExpanded}
+        openLabel="Open action rail"
+        closeLabel="Collapse action rail"
+      />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### OverflowActions
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `primaryActions` | `OverflowActionItem[]` | — | Yes | — |
+| `overflowActions` | `OverflowActionItem[]` | — | Yes | — |
+| `expanded` | `boolean` | — | No | — |
+| `defaultExpanded` | `boolean` | `false` | No | — |
+| `onExpandedChange` | `((expanded: boolean) => void)` | — | No | — |
+| `onAction` | `((item: OverflowActionItem) => void)` | — | No | — |
+| `collapseOnAction` | `boolean` | `false` | No | — |
+| `size` | `"sm" \| "md"` | `md` | No | — |
+| `openLabel` | `string` | `Show extra actions` | No | — |
+| `closeLabel` | `string` | `Hide extra actions` | No | — |
+| `className` | `string` | — | No | — |
+| `classNames` | `OverflowActionsClassNames` | — | No | — |
+

package/references/blocks/prediction-market.md

@@ -0,0 +1,97 @@
+---
+title: "Prediction Market"
+description: "Prediction market trade ticket with buy/sell modes, outcome prices, rolling amount entry, quick add chips and trade states."
+category: "Blocks"
+publishedAt: "2026-06-18"
+updatedAt: "2026-06-21"
+documentation: "references/blocks/prediction-market.md"
+markdown: "references/blocks/prediction-market.md"
+license: "MIT"
+---
+
+# Prediction Market
+
+> Prediction market trade ticket with buy/sell modes, outcome prices, rolling amount entry, quick add chips and trade states.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py prediction-market --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import {
+  PredictionMarket,
+  type PredictionMarketOrderValue,
+} from "@/components/motion/prediction-market";
+
+const outcomes = [
+  {
+    id: "yes",
+    label: "Yes",
+    price: 0.167,
+  },
+  {
+    id: "no",
+    label: "No",
+    price: 0.834,
+  },
+];
+
+export function PredictionMarketPreview() {
+  const [order, setOrder] = useState<PredictionMarketOrderValue>({
+    mode: "buy",
+    outcomeId: "yes",
+    amount: "115",
+  });
+
+  return (
+    <div className="flex w-full items-center justify-center">
+      <PredictionMarket
+        outcomes={outcomes}
+        value={order}
+        onValueChange={setOrder}
+        balance={500}
+        positions={{ yes: 125, no: 48 }}
+        quickAmounts={[1, 5, 10, 100]}
+      />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### PredictionMarket
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `outcomes` | `PredictionMarketOutcome[]` | `[ { id: "up", label: "Up", price: 0.09 }, { id: "down", label: "Down", price: 0.91 }, ]` | No | — |
+| `value` | `PredictionMarketOrderValue` | — | No | — |
+| `defaultValue` | `Partial<PredictionMarketOrderValue>` | — | No | — |
+| `onValueChange` | `((value: PredictionMarketOrderValue) => void)` | — | No | — |
+| `onTrade` | `((order: PredictionMarketOrderValue, quote: PredictionMarketQuote) => void)` | — | No | — |
+| `onSignIn` | `(() => void)` | — | No | — |
+| `authenticated` | `boolean` | `true` | No | — |
+| `orderTypeLabel` | `string` | `Market` | No | — |
+| `balance` | `number` | `500` | No | — |
+| `positions` | `Record<string, number>` | `{ up: 24, down: 16 }` | No | — |
+| `quickAmounts` | `number[]` | `[10, 50, 100, 500]` | No | — |
+| `minTrade` | `number` | `1` | No | — |
+| `className` | `string` | — | No | — |
+| `classNames` | `PredictionMarketClassNames` | — | No | — |
+

package/references/blocks/project-folder.md

@@ -0,0 +1,99 @@
+---
+title: "Project Folder"
+description: "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."
+category: "Blocks"
+publishedAt: "2026-08-15"
+updatedAt: "2026-08-20"
+documentation: "references/blocks/project-folder.md"
+markdown: "references/blocks/project-folder.md"
+license: "MIT"
+---
+
+# 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.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py project-folder --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `react-dom`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { ProjectFolder } from "@/components/motion/project-folder";
+
+const previews = [
+  { id: "moss", color: "bg-emerald-200", mark: "A" },
+  { id: "clay", color: "bg-orange-200", mark: "B" },
+  { id: "sky", color: "bg-sky-200", mark: "C" },
+  { id: "lilac", color: "bg-violet-200", mark: "D" },
+  { id: "sand", color: "bg-amber-100", mark: "E" },
+].map((preview) => ({
+  id: preview.id,
+  content: (
+    <span className={cn("relative block h-full w-full", preview.color)}>
+      <span className="absolute left-3 top-3 h-2 w-8 rounded-full bg-black/15" />
+      <span className="absolute inset-x-3 top-8 h-px bg-black/10" />
+      <span className="absolute inset-x-3 top-11 h-px bg-black/10" />
+      <span className="absolute bottom-3 right-3 text-sm font-medium text-black/50">
+        {preview.mark}
+      </span>
+    </span>
+  ),
+}));
+
+function cn(...classes: string[]) {
+  return classes.filter(Boolean).join(" ");
+}
+
+export function ProjectFolderPreview() {
+  return (
+    <div className="flex min-h-80 w-full items-center justify-center px-6 py-10">
+      <ProjectFolder
+        title="Brand direction"
+        description="Updated recently"
+        count={5}
+        previews={previews}
+        onClick={() => {}}
+      />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### ProjectFolder
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `title` | `string` | — | Yes | — |
+| `description` | `string` | `Updated recently` | No | — |
+| `previews` | `ProjectFolderPreview[]` | `[]` | No | — |
+| `count` | `number` | `previews.length` | No | — |
+| `itemLabel` | `string` | `file` | No | — |
+| `open` | `boolean` | — | No | — |
+| `defaultOpen` | `boolean` | `false` | No | — |
+| `onOpenChange` | `((open: boolean) => void)` | — | No | — |
+| `expanded` | `boolean` | — | No | — |
+| `defaultExpanded` | `boolean` | `false` | No | — |
+| `onExpandedChange` | `((expanded: boolean) => void)` | — | No | — |
+| `onClick` | `(() => void)` | — | No | — |
+| `disabled` | `boolean` | `false` | No | — |
+| `ariaLabel` | `string` | — | No | — |
+| `className` | `string` | — | No | — |
+