motion-ui-skill 2.0.0

package/references/motion/morphing-modal.md

@@ -0,0 +1,230 @@
+---
+title: "Morphing Modal"
+description: "Family-app-style modal. A single panel that morphs its height as you navigate between inner views, with blur cross-fade on content."
+category: "Components"
+publishedAt: "2026-05-17"
+updatedAt: "2026-08-20"
+documentation: "references/motion/morphing-modal.md"
+markdown: "references/motion/morphing-modal.md"
+license: "MIT"
+---
+
+# Morphing Modal
+
+> Family-app-style modal. A single panel that morphs its height as you navigate between inner views, with blur cross-fade on content.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py morphing-modal --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { Ban, Lock, ScanFace, ScrollText, ShieldCheck, Trash2 } from "lucide-react";
+import { useState } from "react";
+import { MorphingModal } from "@/components/motion/morphing-modal";
+
+type View = "options" | "private-key" | "recovery" | null;
+
+export function MorphingModalPreview() {
+  const [view, setView] = useState<View>(null);
+
+  return (
+    <div className="flex flex-col items-center gap-3">
+      <button
+        type="button"
+        onClick={() => setView("options")}
+        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 wallet options
+      </button>
+      <p className="text-xs text-muted-foreground">Click a row. The modal morphs height to match new content.</p>
+
+      <MorphingModal viewId={view} onClose={() => setView(null)}>
+        {view === "options" ? (
+          <Options
+            onPrivateKey={() => setView("private-key")}
+            onRecovery={() => setView("recovery")}
+            onClose={() => setView(null)}
+          />
+        ) : view === "private-key" ? (
+          <PrivateKey onBack={() => setView("options")} />
+        ) : view === "recovery" ? (
+          <Recovery onBack={() => setView("options")} />
+        ) : null}
+      </MorphingModal>
+    </div>
+  );
+}
+
+function Header({ title, onClose }: { title: string; onClose: () => void }) {
+  return (
+    <div className="mb-4 flex items-center justify-between">
+      <h2 className="text-base font-semibold text-foreground">{title}</h2>
+      <button
+        type="button"
+        onClick={onClose}
+        aria-label="Close"
+        className="inline-flex h-7 w-7 items-center justify-center rounded-full text-muted-foreground hover:bg-foreground/[0.06]"
+      >
+        ✕
+      </button>
+    </div>
+  );
+}
+
+function Row({
+  icon: Icon,
+  label,
+  destructive,
+  onClick,
+}: {
+  icon: typeof Lock;
+  label: string;
+  destructive?: boolean;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className={`flex w-full items-center gap-3 rounded-2xl px-4 py-3 text-sm font-medium transition-colors press ${
+        destructive
+          ? "bg-destructive/10 text-destructive hover:bg-destructive/15"
+          : "bg-foreground/[0.04] text-foreground hover:bg-foreground/[0.08]"
+      }`}
+    >
+      <Icon className="h-4 w-4" />
+      {label}
+    </button>
+  );
+}
+
+function Options({
+  onPrivateKey,
+  onRecovery,
+  onClose,
+}: {
+  onPrivateKey: () => void;
+  onRecovery: () => void;
+  onClose: () => void;
+}) {
+  return (
+    <div>
+      <Header title="Options" onClose={onClose} />
+      <div className="flex flex-col gap-2">
+        <Row icon={Lock} label="View Private Key" onClick={onPrivateKey} />
+        <Row icon={ScrollText} label="View Recovery Phrase" onClick={onRecovery} />
+        <Row icon={Trash2} label="Remove Wallet" destructive onClick={onClose} />
+      </div>
+    </div>
+  );
+}
+
+function PrivateKey({ onBack }: { onBack: () => void }) {
+  return (
+    <div>
+      <div className="mb-3 flex items-start justify-between">
+        <Lock className="h-5 w-5 text-foreground" />
+        <button
+          type="button"
+          onClick={onBack}
+          aria-label="Back"
+          className="inline-flex h-7 w-7 items-center justify-center rounded-full text-muted-foreground hover:bg-foreground/[0.06]"
+        >
+          ✕
+        </button>
+      </div>
+      <h2 className="text-xl font-semibold tracking-tight text-foreground">Private Key</h2>
+      <p className="mt-2 text-sm text-muted-foreground">
+        Your Private Key is the key used to back up your wallet. Keep it secret and secure at all times.
+      </p>
+      <hr className="my-4 border-border" />
+      <ul className="flex flex-col gap-2.5 text-sm text-muted-foreground">
+        <li className="flex items-center gap-2.5"><ShieldCheck className="h-4 w-4" /> Keep your private key safe</li>
+        <li className="flex items-center gap-2.5"><ScrollText className="h-4 w-4" /> Don&apos;t share it with anyone else</li>
+        <li className="flex items-center gap-2.5"><Ban className="h-4 w-4" /> If you lose it, we can&apos;t recover it</li>
+      </ul>
+      <div className="mt-5 flex gap-2">
+        <button
+          type="button"
+          onClick={onBack}
+          className="inline-flex h-10 flex-1 items-center justify-center rounded-full bg-foreground/[0.06] text-sm font-medium text-foreground press"
+        >
+          Cancel
+        </button>
+        <button
+          type="button"
+          onClick={onBack}
+          className="inline-flex h-10 flex-1 items-center justify-center gap-2 rounded-full bg-foreground text-sm font-medium text-background press"
+        >
+          <ScanFace className="h-4 w-4" />
+          Reveal
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function Recovery({ onBack }: { onBack: () => void }) {
+  return (
+    <div>
+      <div className="mb-3 flex items-start justify-between">
+        <ScrollText className="h-5 w-5 text-foreground" />
+        <button
+          type="button"
+          onClick={onBack}
+          aria-label="Back"
+          className="inline-flex h-7 w-7 items-center justify-center rounded-full text-muted-foreground hover:bg-foreground/[0.06]"
+        >
+          ✕
+        </button>
+      </div>
+      <h2 className="text-xl font-semibold tracking-tight text-foreground">Recovery Phrase</h2>
+      <p className="mt-2 text-sm text-muted-foreground">
+        12 words you can use to restore your wallet on any device. Write them down somewhere safe.
+      </p>
+      <div className="mt-4 grid grid-cols-3 gap-2">
+        {["mountain", "river", "candle", "harbor", "amber", "violet", "spring", "ocean", "marble", "thunder", "willow", "crystal"].map((w, i) => (
+          <div key={w} className="rounded-lg border border-border bg-background/40 px-2 py-1.5 text-xs text-foreground">
+            <span className="mr-1 text-muted-foreground">{i + 1}.</span>
+            {w}
+          </div>
+        ))}
+      </div>
+      <button
+        type="button"
+        onClick={onBack}
+        className="mt-5 inline-flex h-10 w-full items-center justify-center rounded-full bg-foreground text-sm font-medium text-background press"
+      >
+        Done
+      </button>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### MorphingModal
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `viewId` | `string \| null` | — | Yes | Which view is currently shown. `null` closes the modal. |
+| `onClose` | `() => void` | — | Yes | — |
+| `placement` | `"bottom" \| "center"` | `bottom` | No | "bottom" anchors to the viewport bottom (mobile-like). "center" centers vertically. |
+| `className` | `string` | — | No | — |
+

package/references/motion/multi-select.md

@@ -0,0 +1,202 @@
+---
+title: "Multi Select"
+description: "Composable multi-select primitives with searchable options, removable animated tokens, and a morphing collision-aware panel."
+category: "Components"
+publishedAt: "2026-08-29"
+updatedAt: "2026-08-29"
+documentation: "references/motion/multi-select.md"
+markdown: "references/motion/multi-select.md"
+license: "MIT"
+---
+
+# Multi Select
+
+> Composable multi-select primitives with searchable options, removable animated tokens, and a morphing collision-aware panel.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py multi-select --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `react-dom`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { Circle } from "lucide-react";
+import {
+  MultiSelect,
+  MultiSelectContent,
+  MultiSelectEmpty,
+  MultiSelectGroup,
+  MultiSelectInput,
+  MultiSelectItem,
+  MultiSelectLabel,
+  MultiSelectList,
+  MultiSelectTrigger,
+  MultiSelectValue,
+} from "@/components/motion/multi-select";
+
+const colors = {
+  design: "fill-rose-500 text-rose-500",
+  engineering: "fill-sky-500 text-sky-500",
+  product: "fill-amber-500 text-amber-500",
+  research: "fill-violet-500 text-violet-500",
+  marketing: "fill-emerald-500 text-emerald-500",
+  operations: "fill-slate-500 text-slate-500",
+};
+
+function Option({
+  value,
+  children,
+}: {
+  value: keyof typeof colors;
+  children: string;
+}) {
+  return (
+    <MultiSelectItem value={value} textValue={children}>
+      <span className="flex items-center gap-2.5">
+        <Circle aria-hidden="true" className={`size-2.5 ${colors[value]}`} />
+        {children}
+      </span>
+    </MultiSelectItem>
+  );
+}
+
+export function MultiSelectPreview() {
+  return (
+    <div className="flex min-h-[420px] w-full items-start justify-center px-4 pt-24">
+      <div className="w-full max-w-sm">
+        <MultiSelect defaultValue={["design", "engineering"]}>
+          <MultiSelectTrigger>
+            <MultiSelectValue placeholder="Choose teams" />
+            <MultiSelectInput aria-label="Search teams" />
+          </MultiSelectTrigger>
+          <MultiSelectContent>
+            <MultiSelectList ariaLabel="Teams">
+              <MultiSelectGroup>
+                <MultiSelectLabel>Product teams</MultiSelectLabel>
+                <Option value="design">Design</Option>
+                <Option value="engineering">Engineering</Option>
+                <Option value="product">Product</Option>
+                <Option value="research">Research</Option>
+              </MultiSelectGroup>
+              <MultiSelectGroup>
+                <MultiSelectLabel>Business teams</MultiSelectLabel>
+                <Option value="marketing">Marketing</Option>
+                <Option value="operations">Operations</Option>
+              </MultiSelectGroup>
+              <MultiSelectEmpty>No teams found.</MultiSelectEmpty>
+            </MultiSelectList>
+          </MultiSelectContent>
+        </MultiSelect>
+      </div>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### MultiSelect
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string[]` | — | No | — |
+| `defaultValue` | `string[]` | `[]` | No | — |
+| `onValueChange` | `((value: string[]) => void)` | — | No | — |
+| `open` | `boolean` | — | No | — |
+| `defaultOpen` | `boolean` | `false` | No | — |
+| `onOpenChange` | `((open: boolean) => void)` | — | No | — |
+| `query` | `string` | — | No | — |
+| `defaultQuery` | `string` | — | No | — |
+| `onQueryChange` | `((query: string) => void)` | — | No | — |
+| `filter` | `MultiSelectFilter` | `(value, query, keywords) => { const needle = query.trim().toLocaleLowerCase(); if (!needle) return true; const haystack = [value, ...keywords].join(" ").toLocaleLowerCase(); let queryIndex = 0; for (const character of haystack) { if (character === needle[queryIndex]) queryIndex += 1; if (queryIndex === needle.length) return true; } return false; }` | No | — |
+| `disabled` | `boolean` | `false` | No | — |
+| `className` | `string` | — | No | — |
+
+### MultiSelectInput
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `ref` | `Ref<HTMLInputElement>` | — | No | — |
+| `showIcon` | `boolean` | `false` | No | — |
+| `className` | `string` | — | No | — |
+
+### MultiSelectTrigger
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+
+### MultiSelectValue
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `placeholder` | `ReactNode` | `Select options` | No | — |
+| `className` | `string` | — | No | — |
+| `chipClassName` | `string` | — | No | — |
+
+### MultiSelectContent
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `side` | `"bottom" \| "top"` | `bottom` | No | — |
+| `align` | `"end" \| "start" \| "center"` | `start` | No | — |
+| `sideOffset` | `number` | `6` | No | — |
+| `avoidCollisions` | `boolean` | `true` | No | — |
+| `className` | `string` | — | No | — |
+
+### MultiSelectEmpty
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+
+### MultiSelectGroup
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+
+### MultiSelectItem
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | Yes | — |
+| `textValue` | `string` | — | No | — |
+| `keywords` | `string[]` | `[]` | No | — |
+| `disabled` | `boolean` | `false` | No | — |
+| `onSelect` | `((value: string) => void)` | — | No | — |
+| `className` | `string` | — | No | — |
+
+### MultiSelectLabel
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+
+### MultiSelectList
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `ariaLabel` | `string` | `Options` | No | — |
+| `className` | `string` | — | No | — |
+
+### MultiSelectSeparator
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | — | No | — |
+

package/references/motion/number-field.md

@@ -0,0 +1,70 @@
+---
+title: "Number Field"
+description: "Precision numeric stepper with increment/decrement buttons, hold-to-accelerate speed, directional digit swaps, and keyboard controls."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/number-field.md"
+markdown: "references/motion/number-field.md"
+license: "MIT"
+---
+
+# Number Field
+
+> Precision numeric stepper with increment/decrement buttons, hold-to-accelerate speed, directional digit swaps, and keyboard controls. Inspired by KeenThemes ReUI and Coss.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py number-field --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { NumberField } from "@/components/motion/number-field";
+import { useState } from "react";
+
+export function NumberFieldExample() {
+  const [quantity, setQuantity] = useState(3);
+
+  return (
+    <div className="flex items-center gap-4 p-6 bg-card rounded-2xl border border-border">
+      <span className="text-xs font-medium text-muted-foreground">Cluster Replicas:</span>
+      <NumberField
+        value={quantity}
+        min={1}
+        max={10}
+        step={1}
+        onChange={(val) => setQuantity(val)}
+        suffix="pods"
+      />
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `value` | `number` | `undefined` | Controlled numeric value. |
+| `defaultValue` | `number` | `0` | Uncontrolled initial value. |
+| `min` | `number` | `-Infinity` | Minimum boundary clamp. |
+| `max` | `number` | `Infinity` | Maximum boundary clamp. |
+| `step` | `number` | `1` | Increment step size per tick. |
+| `prefix` | `string` | `undefined` | Text prefix preceding number (e.g. "$"). |
+| `suffix` | `string` | `undefined` | Text suffix following number (e.g. "%", "px"). |
+| `onChange` | `(val: number) => void` | `undefined` | Callback emitted when value changes. |
+| `className` | `string` | `undefined` | Custom styling overrides merged via `cn()`. |

package/references/motion/number.md

@@ -0,0 +1,198 @@
+---
+title: "Number Animation"
+description: "Animated number primitives for count-up values, rolling tickers, and fixed-slot digit swaps."
+category: "Components"
+publishedAt: "2026-05-17"
+updatedAt: "2026-09-04"
+documentation: "references/motion/number.md"
+markdown: "references/motion/number.md"
+license: "MIT"
+---
+
+# Number Animation
+
+> Animated number primitives for count-up values, rolling tickers, and fixed-slot digit swaps.
+
+## Install
+
+### Digit Swap
+
+Fixed-slot digits and mask glyphs that roll on change with controllable direction, stagger, replay, and suffix emphasis.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py digit-swap --dest ./src
+```
+
+### Number Ticker
+
+Slot-machine rolling digits with staggered entry.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py number-ticker --dest ./src
+```
+
+### Animated Number
+
+Spring-driven count-up triggered when in view.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py animated-number --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+### Digit Swap usage
+
+Fixed-slot digits and mask glyphs that roll on change with controllable direction, stagger, replay, and suffix emphasis.
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { DigitSwap } from "@/components/motion/digit-swap";
+
+const CARD_NUMBER = "4242 4242 4242 0806";
+const MASKED_NUMBER = "•••• •••• •••• 0806";
+
+export function DigitSwapPreview() {
+  const [revealed, setRevealed] = useState(false);
+
+  return (
+    <div className="flex w-80 flex-col gap-5">
+      <div className="flex flex-col gap-2">
+        <span className="text-xs font-medium text-muted-foreground">
+          Card number
+        </span>
+        <DigitSwap
+          value={revealed ? CARD_NUMBER : MASKED_NUMBER}
+          animationKey={revealed ? "revealed" : "masked"}
+          direction={revealed ? "up" : "down"}
+          suffixLength={4}
+          glyphClassName={
+            revealed ? "text-foreground" : "text-muted-foreground"
+          }
+          suffixClassName="text-foreground"
+          className="font-mono text-lg tracking-[0.08em] tabular-nums"
+        />
+      </div>
+
+      <button
+        type="button"
+        aria-label={revealed ? "Animate masked number" : "Animate card number"}
+        aria-pressed={revealed}
+        onClick={() => setRevealed((current) => !current)}
+        className="h-10 self-start rounded-lg border border-border px-3 text-sm font-medium text-foreground outline-none transition-colors hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
+      >
+        Animate
+      </button>
+    </div>
+  );
+}
+```
+
+### Number Ticker usage
+
+Slot-machine rolling digits with staggered entry.
+
+```tsx
+"use client";
+
+import { useEffect, useState } from "react";
+import { NumberTicker } from "@/components/motion/number-ticker";
+
+export function NumberTickerPreview() {
+  const [value, setValue] = useState(48273);
+  useEffect(() => {
+    const id = setInterval(() => setValue((v) => v + Math.floor(Math.random() * 50)), 2500);
+    return () => clearInterval(id);
+  }, []);
+  return (
+    <div className="flex flex-col items-center gap-3">
+      <p className="text-xs text-muted-foreground">Active users</p>
+      <NumberTicker
+        value={value}
+        prefix=""
+        className="text-4xl font-semibold tracking-tight text-foreground tabular-nums"
+        format={(n) => n.toLocaleString()}
+      />
+      <p className="text-xs text-muted-foreground">live · updates every 2.5s</p>
+    </div>
+  );
+}
+```
+
+### Animated Number usage
+
+Spring-driven count-up triggered when in view.
+
+```tsx
+"use client";
+
+import { AnimatedNumber } from "@/components/motion/animated-number";
+
+export function AnimatedNumberPreview() {
+  return (
+    <div className="flex flex-col items-center gap-3">
+      <p className="text-xs text-muted-foreground">Monthly recurring revenue</p>
+      <div className="text-4xl font-semibold tracking-tight text-foreground tabular-nums">
+        <AnimatedNumber value={129480} format={(n) => `$${Math.round(n).toLocaleString()}`} />
+      </div>
+      <p className="text-xs text-(--color-success)">+12.4% vs last month</p>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### DigitSwap
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string \| number` | — | Yes | Numeric or masked value rendered in fixed character slots. |
+| `animationKey` | `string \| number` | — | No | Replays every glyph when the value itself contains unchanged characters. |
+| `direction` | `"up" \| "down"` | `up` | No | Direction the next glyph enters from. |
+| `duration` | `number` | `0.18` | No | Per-glyph transition duration in seconds. |
+| `stagger` | `number` | `0.006` | No | Delay in seconds between neighboring glyphs. |
+| `suffixLength` | `number` | `0` | No | Number of final characters that receive `suffixClassName`. |
+| `className` | `string` | — | No | — |
+| `glyphClassName` | `string` | — | No | — |
+| `suffixClassName` | `string` | — | No | — |
+
+### NumberTicker
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `number` | — | Yes | — |
+| `pad` | `number` | — | No | Digits to pad to (left). |
+| `duration` | `number` | `0.9` | No | Per-digit roll duration in seconds. |
+| `stagger` | `number` | `0.04` | No | Stagger between digits. |
+| `startOnView` | `boolean` | `true` | No | Render only after the element enters the viewport. |
+| `prefix` | `string` | — | No | — |
+| `suffix` | `string` | — | No | — |
+| `blur` | `boolean` | `false` | No | Add a small blur during digit rolls. |
+| `className` | `string` | — | No | — |
+| `digitClassName` | `string` | — | No | — |
+| `locale` | `boolean` | — | No | Insert locale group separators (commas). Server-component safe. |
+| `format` | `((value: number) => string)` | — | No | Custom formatter. Client-only — server components must use `locale` instead. |
+
+### AnimatedNumber
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `number` | — | Yes | — |
+| `duration` | `number` | `1.2` | No | — |
+| `format` | `((n: number) => string)` | `(n) => Math.round(n).toLocaleString()` | No | — |
+| `className` | `string` | — | No | — |
+| `startOnView` | `boolean` | `true` | No | — |
+