motion-ui-skill 2.0.0

package/references/motion/animated-toast-stack.md

@@ -0,0 +1,214 @@
+---
+title: "Animated Toast Stack"
+description: "Stacked toasts with status morphs, swipe dismissal, actions and layout-aware motion."
+category: "Components"
+publishedAt: "2026-06-05"
+updatedAt: "2026-07-13"
+documentation: "references/motion/animated-toast-stack.md"
+markdown: "references/motion/animated-toast-stack.md"
+license: "MIT"
+---
+
+# Animated Toast Stack
+
+> Stacked toasts with status morphs, swipe dismissal, actions and layout-aware motion.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py animated-toast-stack --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `react-dom`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { Check, LoaderCircle, Sparkles, X } from "lucide-react";
+import { useState } from "react";
+import {
+  AnimatedToastStack,
+  type ToastInput,
+  type ToastPosition,
+  useAnimatedToastStack,
+} from "@/components/motion/animated-toast-stack";
+import { cn } from "@/lib/utils";
+
+const POSITIONS: ToastPosition[] = [
+  "top-left",
+  "top-center",
+  "top-right",
+  "bottom-left",
+  "bottom-center",
+  "bottom-right",
+];
+
+const EXAMPLES: Array<ToastInput & { label: string }> = [
+  {
+    label: "Promise",
+    status: "loading",
+    title: "Publishing component",
+    description: "Bundling source, preview, and registry metadata.",
+    duration: 0,
+  },
+  {
+    label: "Success",
+    status: "success",
+    title: "Component published",
+    description: "Registry endpoint and raw source are available.",
+  },
+  {
+    label: "Error",
+    status: "error",
+    title: "Snapshot failed",
+    description: "Retry after the browser target settles.",
+  },
+];
+
+export function AnimatedToastStackPreview() {
+  const [position, setPosition] = useState<ToastPosition>("bottom-right");
+  const {
+    toasts,
+    showToast,
+    updateToast,
+    dismissToast,
+    clearToasts,
+  } = useAnimatedToastStack({
+    defaultDuration: 3600,
+    limit: 5,
+  });
+
+  const openToast = (input: ToastInput) => {
+    const id = showToast(input);
+    if (input.status === "loading") {
+      window.setTimeout(() => {
+        updateToast(id, {
+          status: "success",
+          title: "Publish complete",
+          description: "Toast updated in-place from loading to success.",
+          duration: 3200,
+        });
+      }, 1800);
+    }
+  };
+
+  const moveStack = (nextPosition: ToastPosition) => {
+    setPosition(nextPosition);
+    showToast({
+      status: "info",
+      title: "Position changed",
+      description: `New toasts open from ${nextPosition}.`,
+    });
+  };
+
+  return (
+    <div className="flex min-h-72 w-full flex-col items-center justify-center gap-6">
+      <AnimatedToastStack
+        toasts={toasts}
+        onDismiss={dismissToast}
+        position={position}
+        placement="fixed"
+        maxVisible={4}
+        classNames={{
+          surface: "bg-card/95",
+        }}
+        icons={{
+          neutral: <Sparkles className="h-3.5 w-3.5" />,
+        }}
+      />
+
+      <div className="flex flex-col items-center gap-2 text-center">
+        <p className="text-sm font-medium text-foreground">Open a real toast</p>
+        <p className="max-w-sm text-xs leading-5 text-muted-foreground">
+          Toasts render fixed on the screen. Change position to open a toast from that edge.
+        </p>
+      </div>
+
+      <div className="flex flex-wrap items-center justify-center gap-2">
+        {EXAMPLES.map((example) => {
+          return (
+            <button
+              key={example.label}
+              type="button"
+              onClick={() => openToast(example)}
+              className="inline-flex h-9 items-center gap-2 rounded-full border border-border bg-card px-4 text-xs font-medium text-foreground transition-colors press hover:border-(--color-border-strong)"
+            >
+              {example.status === "loading" ? (
+                <LoaderCircle className="h-3.5 w-3.5" />
+              ) : example.status === "success" ? (
+                <Check className="h-3.5 w-3.5" />
+              ) : (
+                <X className="h-3.5 w-3.5" />
+              )}
+              {example.label}
+            </button>
+          );
+        })}
+        <button
+          type="button"
+          onClick={clearToasts}
+          className="inline-flex h-9 items-center rounded-full px-4 text-xs font-medium text-muted-foreground press hover:bg-foreground/[0.06] hover:text-foreground"
+        >
+          Clear
+        </button>
+      </div>
+
+      <div className="flex flex-wrap items-center justify-center gap-1.5">
+        {POSITIONS.map((positionOption) => (
+          <button
+            key={positionOption}
+            type="button"
+            onClick={() => moveStack(positionOption)}
+            className={cn(
+              "rounded-full px-2.5 py-1 text-[11px] font-medium transition-colors press",
+              position === positionOption
+                ? "bg-foreground text-background"
+                : "bg-foreground/[0.04] text-muted-foreground hover:bg-foreground/[0.08] hover:text-foreground",
+            )}
+          >
+            {positionOption}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### useAnimatedToastStack
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `initialToasts` | `ToastInput[]` | `[]` | No | — |
+| `defaultDuration` | `number` | `4200` | No | — |
+| `limit` | `number` | — | No | — |
+
+### AnimatedToastStack
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `toasts` | `AnimatedToast[]` | — | Yes | — |
+| `onDismiss` | `((id: string) => void)` | — | No | — |
+| `position` | `"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"` | `bottom-right` | No | — |
+| `placement` | `"static" \| "fixed" \| "absolute"` | — | No | — |
+| `fixed` | `boolean` | `false` | No | — |
+| `portal` | `boolean` | — | No | — |
+| `portalRoot` | `Element \| null` | — | No | — |
+| `maxVisible` | `number` | `4` | No | — |
+| `className` | `string` | — | No | — |
+| `classNames` | `ToastClassNames` | — | No | — |
+| `icons` | `Partial<Record<ToastStatus, ReactNode>>` | — | No | — |
+| `renderToast` | `((toast: AnimatedToast) => ReactNode)` | — | No | — |
+

package/references/motion/aspect-ratio.md

@@ -0,0 +1,59 @@
+---
+title: "Aspect Ratio"
+description: "Animated aspect ratio container maintaining strict geometric proportions with skeleton shimmer underlay."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/aspect-ratio.md"
+markdown: "references/motion/aspect-ratio.md"
+license: "MIT"
+---
+
+# Aspect Ratio
+
+> Animated aspect ratio container maintaining strict geometric proportions with skeleton shimmer underlay. Inspired by shadcn/ui and Motion.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py aspect-ratio --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { AspectRatio } from "@/components/motion/aspect-ratio";
+
+export function AspectRatioExample() {
+  return (
+    <div className="max-w-md p-6 bg-card rounded-2xl border border-border">
+      <AspectRatio ratio={16 / 9} showSkeleton={true}>
+        <img
+          src="https://images.unsplash.com/photo-1579783900882-c0d3dad7b119?auto=format&fit=crop&w=800&q=80"
+          alt="Abstract geometric architecture"
+          className="size-full object-cover"
+        />
+      </AspectRatio>
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `ratio` | `number` | `16 / 9` | Desired aspect ratio width / height (e.g. 16/9, 4/3, 1). |
+| `children` | `ReactNode` | required | Media or content rendered within the container. |
+| `showSkeleton` | `boolean` | `true` | Displays placeholder skeleton pulse while content loads. |
+| `className` | `string` | `undefined` | Custom styling overrides merged via `cn()`. |

package/references/motion/audio-player.md

@@ -0,0 +1,59 @@
+---
+title: "Audio Player"
+description: "Interactive audio player with animated equalizer waveforms, spring play/pause morphs, volume controls, and scrubbing trackbar."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/audio-player.md"
+markdown: "references/motion/audio-player.md"
+license: "MIT"
+---
+
+# Audio Player
+
+> Interactive audio player with animated equalizer waveforms, spring play/pause morphs, volume controls, and scrubbing trackbar. When `src` is omitted, it uses a visual timer demo. Inspired by Origin UI (Coss) and KeenThemes ReUI.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py audio-player --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { AudioPlayer } from "@/components/motion/audio-player";
+
+export function AudioPlayerExample() {
+  return (
+    <div className="p-8 flex justify-center">
+      <AudioPlayer
+        title="Midnight City Serenade"
+        artist="Synthetic Dreams"
+        durationSeconds={195}
+      />
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `title` | `string` | Required | Audio track title. |
+| `artist` | `string` | `undefined` | Performer or creator name. |
+| `durationSeconds` | `number` | `184` | Total audio duration in seconds. |
+| `src` | `string` | `undefined` | Optional audio source URI. |
+| `className` | `string` | `undefined` | Container classes. |

package/references/motion/autocomplete.md

@@ -0,0 +1,69 @@
+---
+title: "Autocomplete"
+description: "Searchable combobox with substring highlighting, keyboard arrow navigation, clear trigger, and spring panel reveal."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/autocomplete.md"
+markdown: "references/motion/autocomplete.md"
+license: "MIT"
+---
+
+# Autocomplete
+
+> Searchable combobox with substring highlighting, keyboard arrow navigation, clear trigger, and spring panel reveal. Inspired by shadcn/ui and KeenThemes ReUI.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py autocomplete --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { Autocomplete, type AutocompleteItem } from "@/components/motion/autocomplete";
+
+const COUNTRIES: AutocompleteItem[] = [
+  { id: "us", label: "United States", category: "North America" },
+  { id: "ca", label: "Canada", category: "North America" },
+  { id: "de", label: "Germany", category: "Europe" },
+  { id: "fr", label: "France", category: "Europe" },
+  { id: "jp", label: "Japan", category: "Asia" },
+  { id: "in", label: "India", category: "Asia" },
+];
+
+export function AutocompleteExample() {
+  return (
+    <div className="p-8">
+      <Autocomplete
+        items={COUNTRIES}
+        placeholder="Select destination..."
+        onChange={(item) => console.log("Selected:", item)}
+      />
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `items` | `AutocompleteItem[]` | Required | Array of searchable items (`{ id, label, category? }`). |
+| `value` | `string` | `""` | Initial input value. |
+| `onChange` | `(item: AutocompleteItem) => void` | `undefined` | Callback fired on item selection. |
+| `placeholder` | `string` | `"Search items..."` | Input placeholder text. |
+| `loading` | `boolean` | `false` | Shows loading spinner. |
+| `className` | `string` | `undefined` | Container classes. |

package/references/motion/avatar-group.md

@@ -0,0 +1,93 @@
+---
+title: "Avatar Group"
+description: "Interactive stacked avatar pile where hovering an avatar springs it forward while adjacent neighbors fan out with distance falloff."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/avatar-group.md"
+markdown: "references/motion/avatar-group.md"
+license: "MIT"
+---
+
+# Avatar Group
+
+> Interactive stacked avatar pile where hovering an avatar springs it forward while adjacent neighbors fan out with distance falloff. Inspired by Transitions.dev (Pattern 11).
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py avatar-group --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { AvatarGroup, type AvatarItem } from "@/components/motion/avatar-group";
+
+const USERS: AvatarItem[] = [
+  {
+    id: "1",
+    name: "Alex River",
+    fallback: "AR",
+    status: "online",
+  },
+  {
+    id: "2",
+    name: "Sarah Chen",
+    fallback: "SC",
+    status: "online",
+  },
+  {
+    id: "3",
+    name: "David Kim",
+    fallback: "DK",
+    status: "busy",
+  },
+  {
+    id: "4",
+    name: "Elena Rostova",
+    fallback: "ER",
+    status: "offline",
+  },
+  {
+    id: "5",
+    name: "Marcus Aurelius",
+    fallback: "MA",
+    status: "online",
+  },
+  {
+    id: "6",
+    name: "Zoe Patel",
+    fallback: "ZP",
+  },
+];
+
+export function AvatarGroupExample() {
+  return (
+    <div className="flex flex-col gap-3 p-6 bg-card rounded-2xl border border-border">
+      <h3 className="text-sm font-semibold">Active Contributors</h3>
+      <AvatarGroup avatars={USERS} max={5} size="md" />
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `avatars` | `AvatarItem[]` | required | Array of avatar objects with name, image source, fallback initials, and status. |
+| `max` | `number` | `5` | Maximum number of avatars shown before displaying an overflow badge. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Avatar circle dimension tier. |
+| `spreadDistance` | `number` | `22` | Maximum displacement distance (px) applied to adjacent neighbors on hover. |
+| `className` | `string` | `undefined` | Custom styling overrides merged via `cn()`. |

package/references/motion/bottom-sheet.md

@@ -0,0 +1,85 @@
+---
+title: "Bottom Sheet"
+description: "Vaul-inspired draggable bottom sheet with snap points, inertia and glass surface."
+category: "Components"
+publishedAt: "2026-05-17"
+updatedAt: "2026-08-20"
+documentation: "references/motion/bottom-sheet.md"
+markdown: "references/motion/bottom-sheet.md"
+license: "MIT"
+---
+
+# Bottom Sheet
+
+> Vaul-inspired draggable bottom sheet with snap points, inertia and glass surface.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py bottom-sheet --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `react-dom`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { BottomSheet } from "@/components/motion/bottom-sheet";
+
+export function BottomSheetPreview() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <button
+        type="button"
+        onClick={() => setOpen(true)}
+        className="inline-flex h-10 items-center rounded-full border border-border bg-card px-5 text-sm font-medium text-foreground press hover:border-(--color-border-strong)"
+      >
+        Open bottom sheet
+      </button>
+      <BottomSheet
+        open={open}
+        onOpenChange={setOpen}
+        snapPoints={[0.4, 0.85]}
+        title="Quick actions"
+        description="Drag the handle, fling, or swipe down to dismiss."
+      >
+        <ul className="divide-y divide-border">
+          {["Share", "Duplicate", "Move to folder", "Rename", "Archive", "Delete"].map((item) => (
+            <li key={item} className="py-3 text-sm text-foreground">{item}</li>
+          ))}
+        </ul>
+        <div className="py-12 text-center text-xs text-muted-foreground">
+          Fling up to expand, fling down to dismiss.
+        </div>
+      </BottomSheet>
+    </>
+  );
+}
+```
+
+## API Reference
+
+### BottomSheet
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | — | Yes | — |
+| `onOpenChange` | `(open: boolean) => void` | — | Yes | — |
+| `snapPoints` | `(number \| "auto")[]` | `[0.5, 0.92]` | No | Heights (0-1 = fraction of viewport, or "auto"). First entry is default. |
+| `defaultSnap` | `number` | `0` | No | — |
+| `title` | `string` | — | No | — |
+| `description` | `string` | — | No | — |
+| `className` | `string` | — | No | — |
+| `dismissThreshold` | `number` | `120` | No | Min drag distance (px) past current snap to dismiss. |
+

package/references/motion/bounce-sidebar.md

@@ -0,0 +1,80 @@
+---
+title: "Bounce Sidebar"
+description: "A vertical sidebar whose active dot jumps between destinations on a curved, spring-loaded path."
+category: "Components"
+publishedAt: "2026-07-22"
+updatedAt: "2026-07-22"
+documentation: "references/motion/bounce-sidebar.md"
+markdown: "references/motion/bounce-sidebar.md"
+license: "MIT"
+---
+
+# Bounce Sidebar
+
+> A vertical sidebar whose active dot jumps between destinations on a curved, spring-loaded path.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py bounce-sidebar --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { BounceSidebar } from "@/components/motion/bounce-sidebar";
+
+const destinations = [
+  { id: "overview", label: "Overview" },
+  { id: "components", label: "Components" },
+  { id: "motion", label: "Motion" },
+  { id: "templates", label: "Templates" },
+  { id: "changelog", label: "Changelog" },
+];
+
+export function BounceSidebarPreview() {
+  const [active, setActive] = useState("components");
+
+  return (
+    <div className="flex min-h-[360px] w-full items-center justify-center">
+      <BounceSidebar
+        items={destinations}
+        value={active}
+        onValueChange={setActive}
+        ariaLabel="Motion UI sections"
+        className="w-52"
+        listClassName="w-full"
+        itemClassName="text-base"
+      />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### BounceSidebar
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `BounceSidebarItem[]` | — | Yes | — |
+| `value` | `string` | — | No | — |
+| `defaultValue` | `string` | — | No | — |
+| `onValueChange` | `((value: string) => void)` | — | No | — |
+| `ariaLabel` | `string` | `Sidebar navigation` | No | — |
+| `className` | `string` | — | No | — |
+| `listClassName` | `string` | — | No | — |
+| `itemClassName` | `string` | — | No | — |
+| `indicatorClassName` | `string` | — | No | — |
+