motion-ui-skill 2.0.0

package/references/motion/select.md

@@ -0,0 +1,196 @@
+---
+title: "Select"
+description: "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."
+category: "Components"
+publishedAt: "2026-06-28"
+updatedAt: "2026-07-13"
+documentation: "references/motion/select.md"
+markdown: "references/motion/select.md"
+license: "MIT"
+---
+
+# 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.
+
+## Install
+
+### Select
+
+Composable primitives (Select, SelectTrigger, SelectValue, SelectContent, SelectItem); the panel pinches off the trigger and separates, with staggered items. Position-aware (opens upward when needed).
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py select --dest ./src
+```
+
+### Morph Select
+
+Composable primitives (MorphSelect, MorphSelectTrigger, MorphSelectValue, MorphSelectContent, MorphSelectItem) where the trigger morphs into the panel via a shared layoutId — one continuous surface that grows open and shrinks back, never detaching.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py select-morph --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+### Select usage
+
+Composable primitives (Select, SelectTrigger, SelectValue, SelectContent, SelectItem); the panel pinches off the trigger and separates, with staggered items. Position-aware (opens upward when needed).
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/motion/select";
+
+export function SelectPreview() {
+  const [value, setValue] = useState("next");
+  return (
+    <div className="w-56">
+      <Select value={value} onValueChange={setValue}>
+        <SelectTrigger>
+          <SelectValue placeholder="Pick a framework" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="next">Next.js</SelectItem>
+          <SelectItem value="remix">Remix</SelectItem>
+          <SelectItem value="astro">Astro</SelectItem>
+          <SelectItem value="vite">Vite</SelectItem>
+        </SelectContent>
+      </Select>
+    </div>
+  );
+}
+```
+
+### Morph Select usage
+
+Composable primitives (MorphSelect, MorphSelectTrigger, MorphSelectValue, MorphSelectContent, MorphSelectItem) where the trigger morphs into the panel via a shared layoutId — one continuous surface that grows open and shrinks back, never detaching.
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import {
+  MorphSelect,
+  MorphSelectContent,
+  MorphSelectItem,
+  MorphSelectTrigger,
+  MorphSelectValue,
+} from "@/components/motion/select-morph";
+
+export function SelectMorphPreview() {
+  const [value, setValue] = useState("next");
+  return (
+    <div className="w-56">
+      <MorphSelect value={value} onValueChange={setValue}>
+        <MorphSelectTrigger>
+          <MorphSelectValue placeholder="Pick a framework" />
+        </MorphSelectTrigger>
+        <MorphSelectContent>
+          <MorphSelectItem value="next">Next.js</MorphSelectItem>
+          <MorphSelectItem value="remix">Remix</MorphSelectItem>
+          <MorphSelectItem value="astro">Astro</MorphSelectItem>
+          <MorphSelectItem value="vite">Vite</MorphSelectItem>
+        </MorphSelectContent>
+      </MorphSelect>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### Select
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | No | — |
+| `defaultValue` | `string` | — | No | — |
+| `onValueChange` | `((value: string) => void)` | — | No | — |
+| `open` | `boolean` | — | No | Controlled open state of the panel. A layout that stacks selects can hold this to keep exactly one panel open — the panel is absolutely positioned inside its field, so two open at once paint over each other's options. |
+| `defaultOpen` | `boolean` | `false` | No | Uncontrolled initial open state. Default false. |
+| `onOpenChange` | `((open: boolean) => void)` | — | No | Fires whenever the panel opens or closes. The panel is absolutely positioned inside the field, so a layout that stacks selects has to know which one is open to paint it above its neighbours. |
+| `disabled` | `boolean` | `false` | No | — |
+| `className` | `string` | — | No | — |
+
+### SelectTrigger
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+
+### SelectValue
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `placeholder` | `string` | — | No | — |
+| `className` | `string` | — | No | — |
+
+### SelectContent
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+
+### SelectItem
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | Yes | — |
+| `disabled` | `boolean` | `false` | No | — |
+| `className` | `string` | — | No | — |
+
+### MorphSelect
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | No | — |
+| `defaultValue` | `string` | — | No | — |
+| `onValueChange` | `((value: string) => void)` | — | No | — |
+| `disabled` | `boolean` | `false` | No | — |
+| `className` | `string` | — | No | — |
+
+### MorphSelectValue
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `placeholder` | `string` | — | No | — |
+| `className` | `string` | — | No | — |
+
+### MorphSelectTrigger
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+
+### MorphSelectContent
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+
+### MorphSelectItem
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | Yes | — |
+| `disabled` | `boolean` | `false` | No | — |
+| `className` | `string` | — | No | — |
+

package/references/motion/shader-background.md

@@ -0,0 +1,351 @@
+---
+title: "Shader Background"
+description: "Canvas shader backgrounds (mesh gradient, grain, warp, waves, voronoi, dot orbit and more) with a single typed variant prop. Reduced-motion freezes animated variants."
+category: "Components"
+publishedAt: "2026-07-02"
+updatedAt: "2026-07-13"
+documentation: "references/motion/shader-background.md"
+markdown: "references/motion/shader-background.md"
+license: "MIT"
+---
+
+# 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.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py shader-background --dest ./src
+```
+
+## Dependencies
+
+- `@paper-design/shaders-react`
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { useReducedMotion } from "motion/react";
+import type { ComponentType } from "react";
+import { useEffect, useState } from "react";
+import {
+  ShaderBackground,
+  type ShaderBackgroundProps,
+  type ShaderBackgroundVariant,
+} from "@/components/motion/shader-background";
+import { Tabs, TabsList, TabsTrigger } from "@/components/motion/tabs";
+
+const AUTOPLAY_MS = 2400;
+
+const VARIANTS: {
+  id: string;
+  value: ShaderBackgroundVariant;
+  label: string;
+  props: Record<string, unknown>;
+}[] = [
+  {
+    id: "mesh-gradient",
+    value: "mesh-gradient",
+    label: "Mesh",
+    props: {
+      colors: ["#e0eaff", "#241d9a", "#f75092", "#9f50d3"],
+      distortion: 0.8,
+      swirl: 0.3,
+      speed: 0.4,
+    },
+  },
+  {
+    id: "grain-gradient",
+    value: "grain-gradient",
+    label: "Grain",
+    props: {
+      colors: ["#7300ff", "#eba8ff", "#00bfff", "#2a00ff"],
+      colorBack: "#000000",
+      softness: 0.6,
+      speed: 0.5,
+    },
+  },
+  {
+    id: "grain-sunset",
+    value: "grain-gradient",
+    label: "Grain — Sunset",
+    props: {
+      colors: ["#ff7a00", "#ff2e93", "#ffce54", "#8a2be2"],
+      colorBack: "#1a0500",
+      softness: 0.7,
+      speed: 0.4,
+    },
+  },
+  {
+    id: "grain-pastel",
+    value: "grain-gradient",
+    label: "Grain — Pastel",
+    props: {
+      colors: ["#ffd6e8", "#c9e4ff", "#fff3c4", "#d9c9ff"],
+      colorBack: "#ffffff",
+      softness: 0.85,
+      speed: 0.3,
+    },
+  },
+  {
+    id: "mesh-aurora",
+    value: "mesh-gradient",
+    label: "Mesh — Aurora",
+    props: {
+      colors: ["#00ffb2", "#0072ff", "#a200ff", "#001a2c"],
+      distortion: 0.6,
+      swirl: 0.5,
+      speed: 0.3,
+    },
+  },
+  {
+    id: "mesh-citrus",
+    value: "mesh-gradient",
+    label: "Mesh — Citrus",
+    props: {
+      colors: ["#fff200", "#ff8a00", "#ff3d00", "#ffe08a"],
+      distortion: 0.7,
+      swirl: 0.4,
+      speed: 0.5,
+    },
+  },
+  {
+    id: "warp",
+    value: "warp",
+    label: "Warp",
+    props: {
+      colors: ["#121212", "#9470ff", "#121212", "#8838ff"],
+      speed: 0.4,
+    },
+  },
+  {
+    id: "waves",
+    value: "waves",
+    label: "Waves",
+    props: { colorFront: "#ffbb00", colorBack: "#000000" },
+  },
+  {
+    id: "voronoi",
+    value: "voronoi",
+    label: "Voronoi",
+    props: { colors: ["#ff8247", "#ffe53d"], speed: 0.3 },
+  },
+  {
+    id: "swirl",
+    value: "swirl",
+    label: "Swirl",
+    props: {
+      colorBack: "#180018",
+      colors: ["#ffd1d1", "#ff8a8a", "#660000"],
+      speed: 0.2,
+    },
+  },
+  {
+    id: "dot-orbit",
+    value: "dot-orbit",
+    label: "Orbit",
+    props: {
+      colors: ["#ffc96b", "#ff6200", "#ff2f00"],
+      colorBack: "#000000",
+      speed: 0.6,
+    },
+  },
+  {
+    id: "dot-grid",
+    value: "dot-grid",
+    label: "Grid",
+    props: {
+      colorBack: "#000000",
+      colorFill: "#ffffff",
+      colorStroke: "#ffaa00",
+    },
+  },
+  {
+    id: "smoke-ring",
+    value: "smoke-ring",
+    label: "Smoke",
+    props: { colorBack: "#000000", colors: ["#ffffff"], speed: 0.3 },
+  },
+  {
+    id: "static-radial-gradient",
+    value: "static-radial-gradient",
+    label: "Radial",
+    props: { colorBack: "#000000", colors: ["#00bbff", "#00ffe1", "#ffffff"] },
+  },
+  {
+    id: "neuro-noise",
+    value: "neuro-noise",
+    label: "Neuro",
+    props: {
+      colorFront: "#ffffff",
+      colorMid: "#47a6ff",
+      colorBack: "#000000",
+      speed: 0.4,
+    },
+  },
+  {
+    id: "water",
+    value: "water",
+    label: "Water",
+    props: { colorBack: "#909090", colorHighlight: "#ffffff", speed: 0.4 },
+  },
+  {
+    id: "metaballs",
+    value: "metaballs",
+    label: "Metaballs",
+    props: {
+      colors: ["#ff5cf4", "#4d9eff", "#000000"],
+      colorBack: "#000000",
+      speed: 0.5,
+    },
+  },
+  {
+    id: "god-rays",
+    value: "god-rays",
+    label: "Rays",
+    props: {
+      colors: ["#ffcc66", "#ff6a00"],
+      colorBack: "#000000",
+      speed: 0.4,
+    },
+  },
+  {
+    id: "spiral",
+    value: "spiral",
+    label: "Spiral",
+    props: { colors: ["#7a5cff", "#ff5ca6", "#000000"], speed: 0.4 },
+  },
+  {
+    id: "dithering",
+    value: "dithering",
+    label: "Dither",
+    props: {
+      colorBack: "#000000",
+      colorFront: "#00ff9d",
+      speed: 0.4,
+    },
+  },
+  {
+    id: "pulsing-border",
+    value: "pulsing-border",
+    label: "Pulse",
+    props: {
+      colors: ["#00e5ff", "#7000ff", "#ff00c8"],
+      colorBack: "#000000",
+      speed: 0.5,
+    },
+  },
+  {
+    id: "color-panels",
+    value: "color-panels",
+    label: "Panels",
+    props: { colors: ["#ff3d68", "#ffb800", "#3d7aff", "#00ffb2"], speed: 0.3 },
+  },
+  {
+    id: "static-mesh-gradient",
+    value: "static-mesh-gradient",
+    label: "Static Mesh",
+    props: { colors: ["#ff8a3d", "#ff3d9a", "#3d5aff", "#0a0a0a"] },
+  },
+  {
+    id: "static-mesh-dusk",
+    value: "static-mesh-gradient",
+    label: "Static Mesh — Dusk",
+    props: { colors: ["#2b1055", "#7597de", "#f6a1c8", "#0d0221"] },
+  },
+  {
+    id: "radial-ember",
+    value: "static-radial-gradient",
+    label: "Radial — Ember",
+    props: { colorBack: "#0a0000", colors: ["#ff5100", "#ffce00", "#4a0000"] },
+  },
+  {
+    id: "simplex-noise",
+    value: "simplex-noise",
+    label: "Simplex",
+    props: { colors: ["#ff6ec7", "#6ec7ff", "#000000"], speed: 0.4 },
+  },
+  {
+    id: "perlin-noise",
+    value: "perlin-noise",
+    label: "Perlin",
+    props: { colorFront: "#00ffd5", colorBack: "#000000", speed: 0.3 },
+  },
+];
+
+// Every variant carries a different prop shape; the switcher only ever spreads
+// each entry's own preset, so the loose cast here is safe.
+const Background = ShaderBackground as ComponentType<
+  ShaderBackgroundProps & Record<string, unknown>
+>;
+
+export function ShaderBackgroundPreview() {
+  const [active, setActive] = useState<string>(VARIANTS[0].id);
+  const current = VARIANTS.find((v) => v.id === active) ?? VARIANTS[0];
+  const reduce = useReducedMotion();
+  const [paused, setPaused] = useState(false);
+
+  // Cycles through variants on its own so the preview reads as alive at a
+  // glance; pauses on hover/focus so picking a variant manually sticks.
+  useEffect(() => {
+    if (reduce || paused) return;
+    const id = setInterval(() => {
+      setActive((currentActive) => {
+        const i = VARIANTS.findIndex((v) => v.id === currentActive);
+        return VARIANTS[(i + 1) % VARIANTS.length].id;
+      });
+    }, AUTOPLAY_MS);
+    return () => clearInterval(id);
+  }, [reduce, paused]);
+
+  return (
+    // biome-ignore lint/a11y/noStaticElementInteractions: pause-on-hover for the autoplay timer, not a real control
+    <div
+      className="flex w-full max-w-2xl flex-col gap-5 p-6"
+      onMouseEnter={() => setPaused(true)}
+      onMouseLeave={() => setPaused(false)}
+      onFocus={() => setPaused(true)}
+      onBlur={() => setPaused(false)}
+    >
+      <div className="relative h-80 w-full overflow-hidden rounded-2xl border border-border">
+        <Background
+          key={current.id}
+          variant={current.value}
+          className="absolute inset-0"
+          {...current.props}
+        />
+      </div>
+      <Tabs value={active} onValueChange={setActive}>
+        <TabsList className="flex-wrap justify-center gap-2 rounded-2xl">
+          {VARIANTS.map((v) => (
+            <TabsTrigger
+              key={v.id}
+              value={v.id}
+              className="px-4 py-2 text-sm"
+            >
+              {v.label}
+            </TabsTrigger>
+          ))}
+        </TabsList>
+      </Tabs>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### ShaderBackground
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+

package/references/motion/shared-layout-bg.md

@@ -0,0 +1,80 @@
+---
+title: "Shared Layout Background"
+description: "A pill that glides between hovered items via motion's shared layout, with blur enter/exit."
+category: "Components"
+publishedAt: "2026-05-17"
+updatedAt: "2026-07-29"
+documentation: "references/motion/shared-layout-bg.md"
+markdown: "references/motion/shared-layout-bg.md"
+license: "MIT"
+---
+
+# Shared Layout Background
+
+> A pill that glides between hovered items via motion's shared layout, with blur enter/exit.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py shared-layout-bg --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { ArrowUpRight } from "lucide-react";
+import { SharedLayoutBg } from "@/components/motion/shared-layout-bg";
+
+const items = [
+  { title: "Inbox", body: "12 unread threads, 3 mentions today." },
+  { title: "Drafts", body: "4 posts waiting for a final pass." },
+  { title: "Releases", body: "Last shipped 2 days ago, v0.4.1." },
+  { title: "Billing", body: "Plan renews on the 1st of next month." },
+];
+
+export function SharedLayoutBgPreview() {
+  return (
+    <div className="w-full max-w-lg px-2">
+      <SharedLayoutBg>
+        {items.map((it) => (
+          <button
+            type="button"
+            key={it.title}
+            className="group flex flex-col gap-1 px-2 py-3 text-left"
+          >
+            <div className="flex items-center justify-between gap-3">
+              <span className="text-sm font-medium text-foreground">{it.title}</span>
+              <ArrowUpRight className="h-3.5 w-3.5 text-muted-foreground transition-transform group-hover:translate-x-0.5 group-hover:-translate-y-0.5" />
+            </div>
+            <p className="text-sm text-muted-foreground">{it.body}</p>
+          </button>
+        ))}
+      </SharedLayoutBg>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### SharedLayoutBg
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `as` | `"div" \| "ul"` | `div` | No | Semantic container used for the children. |
+| `pillClassName` | `string` | — | No | Tailwind class applied to the moving pill. Defaults to a subtle foreground tint. |
+| `inset` | `number` | `20` | No | Horizontal inset of the pill relative to each row (px). Default 20. |
+| `pillContainerClassName` | `string` | — | No | Optional positioning override for the pill wrapper inside each item. |
+| `className` | `string` | — | No | — |
+

package/references/motion/sortable-list.md

@@ -0,0 +1,62 @@
+---
+title: "Sortable List"
+description: "Animated drag-and-drop sortable list with tactile elevation, grab handles, and smooth spring reordering."
+category: "Blocks"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/sortable-list.md"
+markdown: "references/motion/sortable-list.md"
+license: "MIT"
+---
+
+# Sortable List
+
+> Animated drag-and-drop sortable list with tactile elevation, grab handles, and smooth spring reordering. Inspired by KeenThemes ReUI and Motion.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py sortable-list --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { SortableList } from "@/components/motion/sortable-list";
+
+const ITEMS = [
+  { id: "1", content: "1. Security Sandbox Policy Verification" },
+  { id: "2", content: "2. Autonomous Code Generation Step" },
+  { id: "3", content: "3. Human Approval Gate" },
+  { id: "4", content: "4. Deployment Canary Traffic 10%" },
+];
+
+export function SortableListExample() {
+  return (
+    <div className="max-w-md p-6 bg-card rounded-2xl border border-border">
+      <h3 className="text-sm font-semibold mb-3">Reorder Execution Pipeline</h3>
+      <SortableList items={ITEMS} onChange={(items) => console.log("New order:", items)} />
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `items` | `SortableListItem[]` | required | Array of list items containing id and content node. |
+| `onChange` | `(items: SortableListItem[]) => void` | `undefined` | Callback emitted when items are reordered. |
+| `showHandle` | `boolean` | `true` | Displays vertical grab grip handle icon. |
+| `className` | `string` | `undefined` | Custom styling overrides merged via `cn()`. |