motion-ui-skill 2.0.0

package/references/motion/bouncy-accordion.md

@@ -0,0 +1,115 @@
+---
+title: "Bouncy Accordion"
+description: "Single-open accordion with weighted spring layout, icon rows and reduced-motion-safe content reveals."
+category: "Components"
+publishedAt: "2026-06-16"
+updatedAt: "2026-07-13"
+documentation: "references/motion/bouncy-accordion.md"
+markdown: "references/motion/bouncy-accordion.md"
+license: "MIT"
+---
+
+# Bouncy Accordion
+
+> Single-open accordion with weighted spring layout, icon rows and reduced-motion-safe content reveals.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py bouncy-accordion --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import {
+  CalendarClock,
+  FileText,
+  FolderKanban,
+  PackageCheck,
+  RadioTower,
+  ShieldCheck,
+} from "lucide-react";
+import { BouncyAccordion } from "@/components/motion/bouncy-accordion";
+
+const items = [
+  {
+    id: "brief",
+    title: "Release Brief",
+    description:
+      "Collect launch notes, owners, and risks in one compact handoff before the release window opens.",
+    icon: <FileText className="h-4 w-4" />,
+  },
+  {
+    id: "launch",
+    title: "Launch Checklist",
+    description:
+      "Verify copy, links, analytics, rollback steps, and final approvals without leaving the queue.",
+    icon: <ShieldCheck className="h-4 w-4" />,
+  },
+  {
+    id: "campaign",
+    title: "Campaign Notes",
+    description:
+      "Keep channel-specific notes close to the task while preserving a calm collapsed list.",
+    icon: <RadioTower className="h-4 w-4" />,
+  },
+  {
+    id: "calendar",
+    title: "Rollout Calendar",
+    description:
+      "Plan announcements, staging checks, reminders, and quiet periods around the same timeline.",
+    icon: <CalendarClock className="h-4 w-4" />,
+  },
+  {
+    id: "ship",
+    title: "Ship Build",
+    description:
+      "Track the current artifact, deploy status, and final sign-off before marking the release complete.",
+    icon: <PackageCheck className="h-4 w-4" />,
+  },
+  {
+    id: "archive",
+    title: "Archive Assets",
+    description:
+      "Move final copy, images, and source files into the campaign folder once the rollout is done.",
+    icon: <FolderKanban className="h-4 w-4" />,
+  },
+];
+
+export function BouncyAccordionPreview() {
+  return (
+    <div className="flex min-h-96 w-full items-center justify-center">
+      <div className="w-full max-w-sm h-[480px]">
+        <BouncyAccordion items={items} defaultValue="calendar" />
+      </div>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### BouncyAccordion
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `BouncyAccordionItem[]` | — | Yes | — |
+| `value` | `string \| null` | — | No | — |
+| `defaultValue` | `string \| null` | `null` | No | — |
+| `onValueChange` | `((value: string \| null) => void)` | — | No | — |
+| `collapsible` | `boolean` | `true` | No | — |
+| `className` | `string` | — | No | — |
+| `classNames` | `BouncyAccordionClassNames` | — | No | — |
+

package/references/motion/breadcrumb.md

@@ -0,0 +1,62 @@
+---
+title: "Breadcrumb"
+description: "Accessible hierarchical breadcrumb navigation with collapsible ellipsis expander, custom separators, and responsive overflow handling."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/breadcrumb.md"
+markdown: "references/motion/breadcrumb.md"
+license: "MIT"
+---
+
+# Breadcrumb
+
+> Accessible hierarchical breadcrumb navigation with collapsible ellipsis expander, custom separators, and responsive overflow handling. Inspired by shadcn/ui and Design System Checklist.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py breadcrumb --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { Breadcrumb } from "@/components/motion/breadcrumb";
+
+const PATH = [
+  { id: "home", label: "Dashboard", href: "/" },
+  { id: "projects", label: "Projects", href: "/projects" },
+  { id: "ai", label: "Agent Pipelines", href: "/projects/agent-pipelines" },
+  { id: "runs", label: "Run #1842", href: "/projects/agent-pipelines/runs" },
+  { id: "diff", label: "Diff Inspector" },
+];
+
+export function BreadcrumbExample() {
+  return (
+    <div className="p-6 bg-card rounded-2xl border border-border">
+      <Breadcrumb items={PATH} maxItems={4} />
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `items` | `BreadcrumbItem[]` | required | Array of breadcrumb nodes with id, label, and href or onClick. |
+| `maxItems` | `number` | `4` | Maximum visible path items before collapsing middle steps into an ellipsis. |
+| `separator` | `ReactNode` | `<ChevronRight />` | Custom separator element placed between nodes. |
+| `className` | `string` | `undefined` | Custom styling overrides merged via `cn()`. |

package/references/motion/button.md

@@ -0,0 +1,271 @@
+---
+title: "Button"
+description: "Spring-pressed Button plus StatefulButton, MagneticButton, and MetallicButton variants."
+category: "Components"
+publishedAt: "2026-05-17"
+updatedAt: "2026-08-25"
+documentation: "references/motion/button.md"
+markdown: "references/motion/button.md"
+license: "MIT"
+---
+
+# Button
+
+> Spring-pressed Button plus StatefulButton, MagneticButton, and MetallicButton variants.
+
+## Install
+
+### Metallic Button
+
+A neutral button surface framed by a pronounced chrome rim with a straight traveling reflection.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py button-metallic --dest ./src
+```
+
+### Button
+
+Press scale, hover lift, variants and sizes.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py button-base --dest ./src
+```
+
+### Stateful Button
+
+Idle → loading → success / error with blur-swap slots and morphing width.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py button-stateful --dest ./src
+```
+
+### Magnetic Button
+
+Button composed with the Magnetic wrapper for cursor-attracted pull.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py button-magnetic --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+### Metallic Button usage
+
+A neutral button surface framed by a pronounced chrome rim with a straight traveling reflection.
+
+```tsx
+"use client";
+
+import { ArrowUpRight, Sparkles } from "lucide-react";
+import { MetallicButton } from "@/components/motion/button";
+
+export function ButtonMetallicPreview() {
+  return (
+    <div className="flex flex-wrap items-center justify-center gap-3 px-6 py-10">
+      <MetallicButton>
+        Continue
+        <ArrowUpRight className="size-4" />
+      </MetallicButton>
+      <MetallicButton size="sm">
+        <Sparkles className="size-3.5" />
+        Generate
+      </MetallicButton>
+      <MetallicButton size="icon" aria-label="Magic tools">
+        <Sparkles className="size-4" />
+      </MetallicButton>
+    </div>
+  );
+}
+```
+
+### Button usage
+
+Press scale, hover lift, variants and sizes.
+
+```tsx
+"use client";
+
+import { ArrowRight, Download, Trash2 } from "lucide-react";
+import { Button } from "@/components/motion/button";
+
+export function ButtonBasePreview() {
+  return (
+    <div className="flex flex-col items-center gap-6">
+      <div className="flex flex-wrap items-center justify-center gap-3">
+        <Button variant="primary" size="md">
+          Continue
+          <ArrowRight className="h-4 w-4" />
+        </Button>
+        <Button variant="secondary" size="md">
+          <Download className="h-4 w-4" />
+          Download
+        </Button>
+        <Button variant="outline" size="md">Outline</Button>
+        <Button variant="ghost" size="md">Ghost</Button>
+      </div>
+      <div className="flex flex-wrap items-center justify-center gap-3">
+        <Button variant="primary" size="sm">Small</Button>
+        <Button variant="primary" size="md">Medium</Button>
+        <Button variant="primary" size="lg">Large</Button>
+        <Button variant="secondary" size="icon" aria-label="Delete">
+          <Trash2 className="h-4 w-4" />
+        </Button>
+      </div>
+      <div className="flex flex-wrap items-center justify-center gap-3">
+        <Button variant="primary" size="md" ripple>Ripple</Button>
+        <Button variant="outline" size="md" ripple>Tap me</Button>
+      </div>
+    </div>
+  );
+}
+```
+
+### Stateful Button usage
+
+Idle → loading → success / error with blur-swap slots and morphing width.
+
+```tsx
+"use client";
+
+import { ArrowRight } from "lucide-react";
+import { useState } from "react";
+import { type ButtonState, StatefulButton } from "@/components/motion/button";
+
+export function ButtonStatefulPreview() {
+  const [okState, setOkState] = useState<ButtonState>("idle");
+  const [errState, setErrState] = useState<ButtonState>("idle");
+
+  const run = (target: "ok" | "err") => {
+    const setter = target === "ok" ? setOkState : setErrState;
+    setter("loading");
+    setTimeout(() => {
+      setter(target === "ok" ? "success" : "error");
+      setTimeout(() => setter("idle"), 1800);
+    }, 1400);
+  };
+
+  return (
+    <div className="flex flex-col items-center justify-center gap-3">
+      <StatefulButton
+        state={okState}
+        variant="primary"
+        size="md"
+        onClick={() => run("ok")}
+        loadingText="Saving"
+        successText="Saved"
+        icon={<ArrowRight className="h-4 w-4" />}
+      >
+        Save changes
+      </StatefulButton>
+      <StatefulButton
+        state={errState}
+        variant="secondary"
+        size="md"
+        onClick={() => run("err")}
+        loadingText="Submitting"
+        errorText="Failed"
+      >
+        Submit
+      </StatefulButton>
+    </div>
+  );
+}
+```
+
+### Magnetic Button usage
+
+Button composed with the Magnetic wrapper for cursor-attracted pull.
+
+```tsx
+"use client";
+
+import { ArrowRight } from "lucide-react";
+import { MagneticButton } from "@/components/motion/button";
+
+export function ButtonMagneticPreview() {
+  return (
+    <div className="flex flex-wrap items-center justify-center gap-4">
+      <MagneticButton variant="primary" size="md" strength={0.35}>
+        Hover me
+        <ArrowRight className="h-4 w-4" />
+      </MagneticButton>
+      <MagneticButton variant="secondary" size="md" strength={0.25}>
+        Subtle pull
+      </MagneticButton>
+      <MagneticButton variant="outline" size="md" strength={0.5}>
+        Strong pull
+      </MagneticButton>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### MetallicButton
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+| `size` | `"sm" \| "md" \| "lg" \| "icon"` | `md` | No | — |
+| `pressScale` | `number` | — | No | — |
+| `paused` | `boolean` | `false` | No | Stops the traveling reflection while preserving the chrome rim. |
+
+### Button
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `ripple` | `boolean` | `false` | No | Spawn a Material-style ripple from the press point. Off by default. |
+| `variant` | `"outline" \| "primary" \| "secondary" \| "ghost"` | `primary` | No | — |
+| `className` | `string` | — | No | — |
+| `size` | `"sm" \| "md" \| "lg" \| "icon"` | `md` | No | — |
+| `pressScale` | `number` | `0.93` | No | — |
+
+### ButtonLink
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `variant` | `"outline" \| "primary" \| "secondary" \| "ghost"` | `primary` | No | — |
+| `className` | `string` | — | No | — |
+| `size` | `"sm" \| "md" \| "lg" \| "icon"` | `md` | No | — |
+| `pressScale` | `number` | `0.93` | No | — |
+
+### StatefulButton
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `ripple` | `boolean` | — | No | Spawn a Material-style ripple from the press point. Off by default. |
+| `variant` | `"outline" \| "primary" \| "secondary" \| "ghost"` | — | No | — |
+| `className` | `string` | — | No | — |
+| `size` | `"sm" \| "md" \| "lg" \| "icon"` | — | No | — |
+| `pressScale` | `number` | — | No | — |
+| `icon` | `ReactNode` | — | No | — |
+| `state` | `"idle" \| "loading" \| "success" \| "error"` | `idle` | No | — |
+| `loadingText` | `ReactNode` | `Loading` | No | — |
+| `successText` | `ReactNode` | `Done` | No | — |
+| `errorText` | `ReactNode` | `Try again` | No | — |
+
+### MagneticButton
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `ripple` | `boolean` | — | No | Spawn a Material-style ripple from the press point. Off by default. |
+| `variant` | `"outline" \| "primary" \| "secondary" \| "ghost"` | — | No | — |
+| `className` | `string` | — | No | — |
+| `size` | `"sm" \| "md" \| "lg" \| "icon"` | — | No | — |
+| `pressScale` | `number` | — | No | — |
+| `strength` | `number` | `0.25` | No | Magnetic pull strength. Default 0.25. |
+| `magneticClassName` | `string` | — | No | Class applied to the magnetic wrapper. |
+

package/references/motion/card-resize.md

@@ -0,0 +1,60 @@
+---
+title: "Card Resize (Morph)"
+description: "Expanding card container that morphs seamlessly from a compact card to an expanded modal dialog using shared layoutId physics."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/card-resize.md"
+markdown: "references/motion/card-resize.md"
+license: "MIT"
+---
+
+# Card Resize (Morph)
+
+> Expanding card container that morphs seamlessly from a compact card to an expanded modal dialog using shared `layoutId` physics. Inspired by transitions.dev and ibelick/ui-skills.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py card-resize --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { CardResize } from "@/components/motion/card-resize";
+
+export function CardResizeExample() {
+  return (
+    <div className="max-w-sm p-8">
+      <CardResize
+        card={{
+          id: "design-systems",
+          category: "Architecture",
+          title: "Building World-Class Design Systems",
+          description: "Explore the end-to-end token pipelines, component anatomy, and accessibility contracts required for scalable enterprise frontends.",
+          image: "https://images.unsplash.com/photo-1507238691740-187a5b1d37b8?w=800&auto=format&fit=crop",
+        }}
+      />
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `card` | `CardResizeItem` | Required | Object with id, title, category, description, and optional image. |
+| `className` | `string` | `undefined` | Container classes for resting state. |

package/references/motion/cascader.md

@@ -0,0 +1,99 @@
+---
+title: "Cascader"
+description: "Multi-level cascading drill-down selector with sliding column transitions, breadcrumb trails, instant global search, and keyboard navigation."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/cascader.md"
+markdown: "references/motion/cascader.md"
+license: "MIT"
+---
+
+# Cascader
+
+> Multi-level cascading drill-down selector with sliding column transitions, breadcrumb trails, instant global search, and keyboard navigation. Inspired by KeenThemes ReUI.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py cascader --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { Cascader, type CascaderOption } from "@/components/motion/cascader";
+import { useState } from "react";
+
+const OPTIONS: CascaderOption[] = [
+  {
+    value: "engineering",
+    label: "Engineering",
+    children: [
+      {
+        value: "frontend",
+        label: "Frontend Systems",
+        children: [
+          { value: "react", label: "React & Next.js" },
+          { value: "animation", label: "Motion & WebGL" },
+        ],
+      },
+      {
+        value: "infrastructure",
+        label: "Infrastructure",
+        children: [
+          { value: "kubernetes", label: "Kubernetes" },
+          { value: "terraform", label: "Terraform & IaC" },
+        ],
+      },
+    ],
+  },
+  {
+    value: "design",
+    label: "Design",
+    children: [
+      { value: "tokens", label: "Design Tokens & WCAG" },
+      { value: "prototyping", label: "Interactive Prototyping" },
+    ],
+  },
+];
+
+export function CascaderExample() {
+  const [value, setValue] = useState<string[]>([]);
+
+  return (
+    <div className="p-6">
+      <Cascader
+        options={OPTIONS}
+        value={value}
+        onChange={(path, opt) => {
+          setValue(path);
+          console.log("Picked:", opt.label, "Path:", path);
+        }}
+      />
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `options` | `CascaderOption[]` | required | Nested tree array of selectable options and children. |
+| `value` | `string[]` | `[]` | Selected leaf path array of string IDs. |
+| `onChange` | `(path: string[], selectedOption: CascaderOption) => void` | `undefined` | Callback emitted when a leaf is chosen. |
+| `placeholder` | `string` | `"Select category..."` | Placeholder text for header. |
+| `searchable` | `boolean` | `true` | Enables flat recursive search across all levels. |
+| `className` | `string` | `undefined` | Custom styling overrides merged via `cn()`. |