motion-ui-skill 2.0.0

package/references/motion/confetti.md

@@ -0,0 +1,65 @@
+---
+title: "Confetti"
+description: "Celebration confetti particle burst with physics-based gravity dispersion, rotation, and haptic support."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/confetti.md"
+markdown: "references/motion/confetti.md"
+license: "MIT"
+---
+
+# Confetti
+
+> Celebration confetti particle burst with physics-based gravity dispersion, rotation, and haptic support. Inspired by Transitions.dev and Coss.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py confetti --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { Confetti } from "@/components/motion/confetti";
+import { useState } from "react";
+
+export function ConfettiExample() {
+  const [celebrate, setCelebrate] = useState(false);
+
+  return (
+    <div className="p-8 flex flex-col items-center gap-4">
+      <Confetti trigger={celebrate} onComplete={() => setCelebrate(false)} />
+      <button
+        type="button"
+        onClick={() => setCelebrate(true)}
+        className="px-5 py-2.5 rounded-xl bg-primary text-primary-foreground text-xs font-semibold"
+      >
+        Trigger Celebration 🎉
+      </button>
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `trigger` | `boolean` | `false` | Dispatches particle burst animation. |
+| `particleCount` | `number` | `40` | Number of individual confetti fragments. |
+| `colors` | `string[]` | rainbow array | Palette of particle background colors. |
+| `duration` | `number` | `2.5` | Lifetime in seconds before particles fade and unmount. |
+| `onComplete` | `() => void` | `undefined` | Callback emitted when the burst concludes. |
+| `className` | `string` | `undefined` | Custom styling overrides merged via `cn()`. |

package/references/motion/context-menu.md

@@ -0,0 +1,269 @@
+---
+title: "Animated Context Menu"
+description: "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."
+category: "Components"
+publishedAt: "2026-07-27"
+updatedAt: "2026-07-27"
+documentation: "references/motion/context-menu.md"
+markdown: "references/motion/context-menu.md"
+license: "MIT"
+---
+
+# Animated 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.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py context-menu --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `react-dom`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import {
+  Check,
+  Copy,
+  Download,
+  Eye,
+  Pencil,
+  Trash2,
+} from "lucide-react";
+import { AnimatePresence, motion, useReducedMotion } from "motion/react";
+import { useState } from "react";
+import {
+  ContextMenu,
+  ContextMenuCheckboxItem,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuLabel,
+  ContextMenuSeparator,
+  ContextMenuShortcut,
+  ContextMenuTrigger,
+} from "@/components/motion/context-menu";
+import { SPRING_SWAP } from "@/lib/ease";
+
+export function ContextMenuPreview() {
+  const reduce = useReducedMotion() ?? false;
+  const [message, setMessage] = useState<string | null>(null);
+  const [offline, setOffline] = useState(false);
+
+  return (
+    <div className="flex min-h-[360px] w-full items-center justify-center">
+      <ContextMenu>
+        <ContextMenuTrigger>
+          <button
+            type="button"
+            className="group flex flex-col items-center outline-none"
+          >
+            <div className="relative h-24 w-32 transition-transform duration-150 group-active:scale-[0.98] group-focus-visible:rounded-2xl group-focus-visible:ring-2 group-focus-visible:ring-foreground/20 group-focus-visible:ring-offset-4 group-focus-visible:ring-offset-background">
+              <div className="absolute left-1 top-1 h-7 w-14 rounded-t-[10px] bg-[#d4a84f] dark:bg-[#a77d2f]" />
+              <div className="absolute inset-x-0 bottom-0 top-5 rounded-[14px] bg-[#e7bb61] shadow-[0_14px_24px_-16px_rgba(90,58,8,0.75)] dark:bg-[#bd8d36]" />
+              <div className="absolute inset-x-0 bottom-0 top-9 rounded-[14px] bg-[#efc86f] dark:bg-[#cb9a41]" />
+              <div className="absolute inset-x-5 bottom-4 h-px bg-black/10 dark:bg-white/10" />
+            </div>
+
+            <span className="mt-4 text-sm font-medium text-foreground">
+              Right click on me
+            </span>
+
+            <div className="mt-1 h-4">
+              <AnimatePresence mode="wait" initial={false}>
+                {message ? (
+                  <motion.span
+                    key={message}
+                    initial={
+                      reduce
+                        ? { opacity: 0 }
+                        : { opacity: 0, y: 3, filter: "blur(2px)" }
+                    }
+                    animate={{ opacity: 1, y: 0, filter: "blur(0px)" }}
+                    exit={
+                      reduce
+                        ? { opacity: 0 }
+                        : { opacity: 0, y: -2, filter: "blur(2px)" }
+                    }
+                    transition={reduce ? { duration: 0.1 } : SPRING_SWAP}
+                    className="flex items-center gap-1 text-[10px] text-muted-foreground"
+                  >
+                    <Check aria-hidden="true" className="h-3 w-3 text-success" />
+                    {message}
+                  </motion.span>
+                ) : (
+                  <span className="text-[10px] text-muted-foreground">
+                    or long-press · Shift + F10
+                  </span>
+                )}
+              </AnimatePresence>
+            </div>
+          </button>
+        </ContextMenuTrigger>
+
+        <ContextMenuContent ariaLabel="Folder actions" className="w-60">
+          <ContextMenuLabel>Project files</ContextMenuLabel>
+          <ContextMenuItem
+            textValue="Open"
+            onSelect={() => setMessage("Folder opened")}
+          >
+            <Eye aria-hidden="true" className="h-4 w-4" />
+            Open
+            <ContextMenuShortcut>↵</ContextMenuShortcut>
+          </ContextMenuItem>
+          <ContextMenuItem
+            textValue="Rename"
+            onSelect={() => setMessage("Ready to rename")}
+          >
+            <Pencil aria-hidden="true" className="h-4 w-4" />
+            Rename
+            <ContextMenuShortcut>R</ContextMenuShortcut>
+          </ContextMenuItem>
+          <ContextMenuItem
+            textValue="Duplicate"
+            onSelect={() => setMessage("Folder duplicated")}
+          >
+            <Copy aria-hidden="true" className="h-4 w-4" />
+            Duplicate
+            <ContextMenuShortcut>⌘D</ContextMenuShortcut>
+          </ContextMenuItem>
+          <ContextMenuItem
+            textValue="Download"
+            onSelect={() => setMessage("Download started")}
+          >
+            <Download aria-hidden="true" className="h-4 w-4" />
+            Download
+          </ContextMenuItem>
+
+          <ContextMenuSeparator />
+
+          <ContextMenuCheckboxItem
+            textValue="Keep offline"
+            checked={offline}
+            closeOnSelect={false}
+            onCheckedChange={(checked) => {
+              setOffline(checked);
+              setMessage(checked ? "Available offline" : "Online only");
+            }}
+          >
+            Keep offline
+          </ContextMenuCheckboxItem>
+
+          <ContextMenuSeparator />
+
+          <ContextMenuItem
+            tone="destructive"
+            textValue="Move to trash"
+            onSelect={() => setMessage("Moved to trash")}
+          >
+            <Trash2 aria-hidden="true" className="h-4 w-4" />
+            Move to trash
+            <ContextMenuShortcut>⌘⌫</ContextMenuShortcut>
+          </ContextMenuItem>
+        </ContextMenuContent>
+      </ContextMenu>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### ContextMenu
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | — | No | — |
+| `defaultOpen` | `boolean` | `false` | No | — |
+| `onOpenChange` | `((open: boolean) => void)` | — | No | — |
+| `className` | `string` | — | No | — |
+
+### ContextMenuTrigger
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `disabled` | `boolean` | `false` | No | — |
+| `className` | `string` | — | No | — |
+
+### ContextMenuContent
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+| `ariaLabel` | `string` | `Context menu` | No | — |
+
+### ContextMenuItem
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `onSelect` | `(() => void)` | — | No | — |
+| `disabled` | `boolean` | — | No | — |
+| `closeOnSelect` | `boolean` | — | No | — |
+| `tone` | `"default" \| "destructive"` | — | No | — |
+| `inset` | `boolean` | — | No | — |
+| `className` | `string` | — | No | — |
+| `textValue` | `string` | — | No | — |
+
+### ContextMenuCheckboxItem
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `checked` | `boolean` | — | Yes | — |
+| `onCheckedChange` | `((checked: boolean) => void)` | — | No | — |
+| `disabled` | `boolean` | — | No | — |
+| `className` | `string` | — | No | — |
+| `inset` | `boolean` | — | No | — |
+| `closeOnSelect` | `boolean` | — | No | — |
+| `tone` | `"default" \| "destructive"` | — | No | — |
+| `textValue` | `string` | — | No | — |
+
+### ContextMenuRadioGroup
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | Yes | — |
+| `onValueChange` | `((value: string) => void)` | — | No | — |
+| `className` | `string` | — | No | — |
+
+### ContextMenuRadioItem
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | Yes | — |
+| `disabled` | `boolean` | — | No | — |
+| `className` | `string` | — | No | — |
+| `inset` | `boolean` | — | No | — |
+| `closeOnSelect` | `boolean` | — | No | — |
+| `tone` | `"default" \| "destructive"` | — | No | — |
+| `textValue` | `string` | — | No | — |
+
+### ContextMenuLabel
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `inset` | `boolean` | `false` | No | — |
+| `className` | `string` | — | No | — |
+
+### ContextMenuSeparator
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+
+### ContextMenuShortcut
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+

package/references/motion/copy-button.md

@@ -0,0 +1,59 @@
+---
+title: "Copy Button"
+description: "Micro-interaction copy button with spring icon swaps, status transitions, clipboard feedback, and haptic support."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/copy-button.md"
+markdown: "references/motion/copy-button.md"
+license: "MIT"
+---
+
+# Copy Button
+
+> Micro-interaction copy button with spring icon swaps, status transitions, clipboard feedback, and haptic support. Inspired by Coss (Origin UI) and Transitions.dev.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py copy-button --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { CopyButton } from "@/components/motion/copy-button";
+
+export function CopyButtonExample() {
+  const codeSnippet = "npx skills add motion-ui";
+
+  return (
+    <div className="flex items-center justify-between p-4 bg-card rounded-2xl border border-border max-w-sm">
+      <code className="text-xs font-mono text-foreground">{codeSnippet}</code>
+      <CopyButton textToCopy={codeSnippet} showText={true} />
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `textToCopy` | `string` | required | Text string dispatched to user's system clipboard. |
+| `label` | `string` | `"Copy"` | Idle button accessible label. |
+| `copiedLabel` | `string` | `"Copied!"` | Success confirmation label. |
+| `showText` | `boolean` | `false` | Displays label text beside the icon. |
+| `timeout` | `number` | `2000` | Duration in ms to retain the success state before resetting. |
+| `className` | `string` | `undefined` | Custom styling overrides merged via `cn()`. |

package/references/motion/cylinder-carousel.md

@@ -0,0 +1,151 @@
+---
+title: "Cylinder Carousel"
+description: "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."
+category: "Components"
+publishedAt: "2026-07-04"
+updatedAt: "2026-07-13"
+documentation: "references/motion/cylinder-carousel.md"
+markdown: "references/motion/cylinder-carousel.md"
+license: "MIT"
+---
+
+# 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.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py cylinder-carousel --dest ./src
+```
+
+## Dependencies
+
+- `@paper-design/shaders-react`
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { type ComponentType, useState } from "react";
+import { CylinderCarousel } from "@/components/motion/cylinder-carousel";
+import {
+  ShaderBackground,
+  type ShaderBackgroundVariant,
+} from "@/components/motion/shader-background";
+import { Tabs, TabsList, TabsTrigger } from "@/components/motion/tabs";
+
+// Each variant has its own prop shape; the slides only spread their own preset.
+const Background = ShaderBackground as ComponentType<
+  { variant: ShaderBackgroundVariant; className?: string } & Record<
+    string,
+    unknown
+  >
+>;
+
+const SLIDES: { variant: ShaderBackgroundVariant; props: Record<string, unknown> }[] = [
+  {
+    variant: "dithering",
+    props: { colorBack: "#1a1030", colorFront: "#b98cff", speed: 0.3 },
+  },
+  {
+    variant: "metaballs",
+    props: { colors: ["#e8e8ef", "#8a8a9a", "#1a1a22"], colorBack: "#c9b9a8", speed: 0.4 },
+  },
+  {
+    variant: "warp",
+    props: { colors: ["#c8ff00", "#3a5a00", "#c8ff00", "#88bb00"], speed: 0.4 },
+  },
+  {
+    variant: "god-rays",
+    props: { colors: ["#6a7bff", "#00114d"], colorBack: "#000000", speed: 0.5 },
+  },
+  {
+    variant: "swirl",
+    props: { colorBack: "#1a0000", colors: ["#ffd1a8", "#ff6a3d", "#b31a57"], speed: 0.3 },
+  },
+  {
+    variant: "mesh-gradient",
+    props: { colors: ["#e0eaff", "#241d9a", "#f75092", "#9f50d3"], speed: 0.3 },
+  },
+  {
+    variant: "voronoi",
+    props: { colors: ["#ff8247", "#ffe53d"], speed: 0.3 },
+  },
+  {
+    variant: "neuro-noise",
+    props: { colorFront: "#ffffff", colorMid: "#47a6ff", colorBack: "#000000", speed: 0.4 },
+  },
+];
+
+export function CylinderCarouselPreview() {
+  const [variant, setVariant] = useState<"concave" | "convex">("concave");
+
+  return (
+    <div className="flex w-full flex-col items-center gap-4 p-6">
+      <Tabs
+        value={variant}
+        onValueChange={(v) => setVariant(v as "concave" | "convex")}
+        variant="segment"
+      >
+        <TabsList>
+          <TabsTrigger value="concave">Concave</TabsTrigger>
+          <TabsTrigger value="convex">Convex</TabsTrigger>
+        </TabsList>
+      </Tabs>
+      {/* clip-path (not overflow) so the rounded corner also clips the GPU-composited balls */}
+      <div className="w-full rounded-3xl border border-border/60 bg-muted/20 py-6 [clip-path:inset(0_round_1.5rem)]">
+        <CylinderCarousel
+          variant={variant}
+          itemSize={230}
+          height={310}
+          className="w-full"
+        >
+          {SLIDES.map((slide) => (
+            <div
+              key={slide.variant}
+              className="h-full w-full overflow-hidden rounded-full border border-border/40"
+            >
+              <Background
+                variant={slide.variant}
+                className="h-full w-full"
+                {...slide.props}
+              />
+            </div>
+          ))}
+        </CylinderCarousel>
+      </div>
+      <p className="text-xs text-muted-foreground">
+        Drag, scroll or use arrow keys to roll
+      </p>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### CylinderCarousel
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `itemSize` | `number` | `200` | No | Max item box size in px (square) at full size, i.e. at the container edge. Balls shrink below this automatically so the row keeps breathing room in narrow containers. |
+| `visibleItems` | `number` | `5` | No | How many item slots span the container width. |
+| `variant` | `"concave" \| "convex"` | `concave` | No | "concave" (default): inside of the cylinder — center ball smallest and dipped, growing toward the edges. "convex": outside of the cylinder — center ball biggest and raised, shrinking toward the edges. |
+| `minScale` | `number` | `0.55` | No | Scale of the smallest ball (center for concave, edges for convex); the biggest reaches 1. |
+| `dragSpeed` | `number` | `1.5` | No | Items rolled per item-width dragged — above 1 the wall outruns the pointer, which reads as a lighter, freer roll. |
+| `arc` | `number` | — | No | Curve depth in px: for concave, how far the edge balls ride above the center one (valley); for convex, how far below (arch). 0 = flat line. Defaults to 35% of the item size. |
+| `snap` | `boolean` | `true` | No | Snap to the nearest item when the roll settles. |
+| `autoRotate` | `boolean` | `false` | No | Roll on its own until interacted with. |
+| `autoRotateSpeed` | `number` | `0.4` | No | Auto-roll speed in items per second. |
+| `defaultIndex` | `number` | `0` | No | — |
+| `onIndexChange` | `((index: number) => void)` | — | No | — |
+| `height` | `number` | — | No | Stage height in px. Defaults to `itemSize`. |
+| `className` | `string` | — | No | — |
+

package/references/motion/date-range-picker.md

@@ -0,0 +1,68 @@
+---
+title: "Date Range Picker"
+description: "Interactive calendar popover for selecting start and end date ranges with preset shortcuts, month navigation, and spring micro-interactions."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/date-range-picker.md"
+markdown: "references/motion/date-range-picker.md"
+license: "MIT"
+---
+
+# Date Range Picker
+
+> Interactive calendar popover for selecting start and end date ranges with preset shortcuts, month navigation, and spring micro-interactions. Inspired by KeenThemes ReUI and Coss / Origin UI.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py date-range-picker --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { DateRangePicker, type DateRange } from "@/components/motion/date-range-picker";
+import { useState } from "react";
+
+export function DateRangePickerExample() {
+  const [range, setRange] = useState<DateRange>({
+    from: new Date(),
+    to: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
+  });
+
+  return (
+    <div className="p-8">
+      <DateRangePicker
+        value={range}
+        onChange={(newRange) => setRange(newRange)}
+      />
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `value` | `DateRange` | `undefined` | Current selected date range (`{ from?: Date; to?: Date }`). |
+| `onChange` | `(range: DateRange) => void` | `undefined` | Callback invoked when range changes. |
+| `className` | `string` | `undefined` | Container classes. |
+
+## Keyboard & Accessibility
+
+- Dismisses automatically on outside click or escape through `useDismiss`.
+- Haptic click feedback on mobile touch platforms.
+- `useReducedMotion()` gracefully suppresses popover scale and button taps.