motion-ui-skill 2.0.0

package/references/blocks/signup-form.md

@@ -0,0 +1,92 @@
+---
+title: "Sign Up Form"
+description: "Composed sign-up form that flags a field only once it is left, then clears the moment it is fixed, with a length-weighted strength meter, password reveal and an animated submit lifecycle."
+category: "Blocks"
+publishedAt: "2026-08-08"
+updatedAt: "2026-08-28"
+documentation: "references/blocks/signup-form.md"
+markdown: "references/blocks/signup-form.md"
+license: "MIT"
+---
+
+# Sign Up Form
+
+> Composed sign-up form that flags a field only once it is left, then clears the moment it is fixed, with a length-weighted strength meter, password reveal and an animated submit lifecycle.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py signup-form --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { SignUpForm } from "@/components/motion/signup-form";
+
+export function SignUpFormPreview() {
+  const [formError, setFormError] = useState<string>();
+
+  return (
+    <div className="flex w-full justify-center py-4">
+      <SignUpForm
+        description="Sign up with taken@example.com to see the failure state."
+        errorMessage={formError}
+        onSubmit={async (values) => {
+          setFormError(undefined);
+          await new Promise((resolve) => setTimeout(resolve, 1200));
+          if (values.email.toLowerCase().startsWith("taken@")) {
+            setFormError("That email is already registered.");
+            throw new Error("Email already registered");
+          }
+        }}
+        footer={
+          <>
+            Already have an account?{" "}
+            <button
+              type="button"
+              className="font-medium text-foreground underline underline-offset-4"
+            >
+              Sign in
+            </button>
+          </>
+        }
+      />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### SignUpForm
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `values` | `SignUpValues` | — | No | Controlled values. Omit for uncontrolled. |
+| `defaultValues` | `Partial<SignUpValues>` | — | No | — |
+| `onValuesChange` | `((values: SignUpValues) => void)` | — | No | — |
+| `onSubmit` | `((values: SignUpValues) => void \| Promise<void>)` | — | No | Called with valid values only. Return a promise to drive the button state. |
+| `validate` | `((values: SignUpValues) => Partial<Record<keyof SignUpValues, string>>)` | — | No | Replace the built-in rules — return a message per invalid field. |
+| `status` | `"error" \| "success" \| "loading" \| "idle"` | — | No | Controlled submit state. Omit to let the form track it. |
+| `errorMessage` | `string` | — | No | Form-level failure message, shown above the submit button. |
+| `title` | `ReactNode` | `Create your account` | No | — |
+| `description` | `ReactNode` | `Start building in under a minute.` | No | — |
+| `submitLabel` | `string` | `Create account` | No | — |
+| `footer` | `ReactNode` | — | No | — |
+| `strengthMeter` | `boolean` | `true` | No | Show the password strength meter. |
+| `className` | `string` | — | No | — |
+| `classNames` | `SignUpFormClassNames` | — | No | — |
+

package/references/blocks/swap.md

@@ -0,0 +1,58 @@
+---
+title: "Multi-chain Swap"
+description: "Cross-chain swap widget with chain + token selectors, morphing views, animated flip and quote."
+category: "Blocks"
+publishedAt: "2026-05-19"
+updatedAt: "2026-06-13"
+documentation: "references/blocks/swap.md"
+markdown: "references/blocks/swap.md"
+license: "MIT"
+---
+
+# Multi-chain Swap
+
+> Cross-chain swap widget with chain + token selectors, morphing views, animated flip and quote.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py swap --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { MultiChainSwap } from "@/components/motion/swap";
+
+export function SwapPreview() {
+  return (
+    <div className="flex w-full items-center justify-center">
+      <MultiChainSwap />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### MultiChainSwap
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `chains` | `Chain[]` | `[ { id: "eth", name: "Ethereum", tone: "bg-primary text-primary-foreground", symbol: "Ξ" }, { id: "sol", name: "Solana", tone: "bg-secondary text-secondary-foreground", symbol: "◎" }, { id: "base", name: "Base", tone: "bg-accent text-accent-foreground", symbol: "B" }, { id: "arb", name: "Arbitrum", tone: "bg-muted text-muted-foreground", symbol: "A" }, { id: "op", name: "Optimism", tone: "bg-destructive text-primary-foreground", symbol: "O" }, { id: "poly", name: "Polygon", tone: "bg-primary/80 text-primary-foreground", symbol: "P" }, { id: "bnb", name: "BNB", tone: "bg-secondary text-secondary-foreground", symbol: "B" }, { id: "avax", name: "Avalanche", tone: "bg-destructive/80 text-primary-foreground", symbol: "A" }, ]` | No | — |
+| `tokens` | `Token[]` | `[ { id: "eth-eth", symbol: "ETH", name: "Ether", chainId: "eth", balance: 1.245, usd: 3142, popular: true, }, { id: "eth-weth", symbol: "WETH", name: "Wrapped Ether", chainId: "eth", balance: 0.5, usd: 3142, popular: true, }, { id: "eth-usdc", symbol: "USDC", name: "USD Coin", chainId: "eth", balance: 4521, usd: 1, popular: true, }, { id: "eth-usdt", symbol: "USDT", name: "Tether", chainId: "eth", balance: 2100, usd: 1, popular: true, }, { id: "eth-dai", symbol: "DAI", name: "Dai Stablecoin", chainId: "eth", balance: 800, usd: 1, popular: true, }, { id: "eth-wbtc", symbol: "WBTC", name: "Wrapped Bitcoin", chainId: "eth", balance: 0.04, usd: 96000, popular: true, }, { id: "eth-link", symbol: "LINK", name: "ChainLink Token", chainId: "eth", balance: 120, usd: 22, address: "0x51...86ca", trending: true, }, { id: "eth-aztec", symbol: "AZTEC", name: "AZTEC", chainId: "eth", balance: 0, address: "0xa2...62d2", trending: true, }, { id: "eth-cfg", symbol: "CFG", name: "Centrifuge", chainId: "eth", balance: 0, address: "0xcc...8a94", trending: true, }, { id: "eth-ondo", symbol: "ONDO", name: "Ondo", chainId: "eth", balance: 0, address: "0xfa...9be3", trending: true, }, { id: "sol-sol", symbol: "SOL", name: "Solana", chainId: "sol", balance: 12.4, usd: 168, }, { id: "sol-usdc", symbol: "USDC", name: "USD Coin", chainId: "sol", balance: 985.32, usd: 1, }, { id: "base-eth", symbol: "ETH", name: "Ether", chainId: "base", balance: 0.65, usd: 3142, }, { id: "base-usdc", symbol: "USDC", name: "USD Coin", chainId: "base", balance: 1200, usd: 1, }, { id: "arb-arb", symbol: "ARB", name: "Arbitrum", chainId: "arb", balance: 800, usd: 0.95, }, { id: "arb-eth", symbol: "ETH", name: "Ether", chainId: "arb", balance: 0.32, usd: 3142, }, { id: "op-op", symbol: "OP", name: "Optimism", chainId: "op", balance: 450, usd: 2.8, }, { id: "poly-matic", symbol: "MATIC", name: "Polygon", chainId: "poly", balance: 1500, usd: 0.75, }, { id: "bnb-bnb", symbol: "BNB", name: "BNB", chainId: "bnb", balance: 0, usd: 620, }, { id: "avax-avax", symbol: "AVAX", name: "Avalanche", chainId: "avax", balance: 0, usd: 38, }, ]` | No | — |
+| `defaultFromId` | `string` | `eth-eth` | No | — |
+| `defaultToId` | `string` | `sol-sol` | No | — |
+| `className` | `string` | — | No | — |
+

package/references/blocks/swipeable-list.md

@@ -0,0 +1,202 @@
+---
+title: "Swipeable List"
+description: "Mobile-style list rows that swipe left or right to reveal contextual action buttons."
+category: "Blocks"
+publishedAt: "2026-06-15"
+updatedAt: "2026-06-28"
+documentation: "references/blocks/swipeable-list.md"
+markdown: "references/blocks/swipeable-list.md"
+license: "MIT"
+---
+
+# Swipeable List
+
+> Mobile-style list rows that swipe left or right to reveal contextual action buttons.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py swipeable-list --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import {
+  Check,
+  Clock3,
+  FileText,
+  Flag,
+  Mail,
+  Pin,
+  RotateCcw,
+  Trash2,
+  UserRound,
+} from "lucide-react";
+import { useState } from "react";
+import {
+  type SwipeAction,
+  SwipeableList,
+  type SwipeableListItem,
+} from "@/components/motion/swipeable-list";
+
+const leftActions: SwipeAction[] = [
+  {
+    id: "done",
+    label: "Done",
+    icon: <Check className="h-4 w-4" />,
+    tone: "success",
+  },
+  {
+    id: "pin",
+    label: "Pin",
+    icon: <Pin className="h-4 w-4" />,
+    tone: "primary",
+  },
+];
+
+const rightActions: SwipeAction[] = [
+  {
+    id: "later",
+    label: "Later",
+    icon: <Clock3 className="h-4 w-4" />,
+    tone: "warning",
+  },
+  {
+    id: "trash",
+    label: "Trash",
+    icon: <Trash2 className="h-4 w-4" />,
+    tone: "danger",
+  },
+];
+
+const initialItems: SwipeableListItem[] = [
+  {
+    id: "brief",
+    title: "Launch brief",
+    description: "Finalize the announcement copy",
+    meta: "9:41",
+    leading: (
+      <div className="grid h-10 w-10 place-items-center rounded-xl border border-border bg-background text-muted-foreground">
+        <FileText className="h-4 w-4" />
+      </div>
+    ),
+    leftActions,
+    rightActions,
+  },
+  {
+    id: "feedback",
+    title: "Client feedback",
+    description: "Three comments need a response",
+    meta: "11:08",
+    leading: (
+      <div className="grid h-10 w-10 place-items-center rounded-xl border border-border bg-background text-muted-foreground">
+        <Mail className="h-4 w-4" />
+      </div>
+    ),
+    leftActions,
+    rightActions,
+  },
+  {
+    id: "review",
+    title: "Design review",
+    description: "Check spacing before handoff",
+    meta: "13:20",
+    leading: (
+      <div className="grid h-10 w-10 place-items-center rounded-xl border border-border bg-background text-muted-foreground">
+        <UserRound className="h-4 w-4" />
+      </div>
+    ),
+    leftActions,
+    rightActions,
+  },
+  {
+    id: "incident",
+    title: "Flagged run",
+    description: "Retry queue has one failed job",
+    meta: "Now",
+    leading: (
+      <div className="grid h-10 w-10 place-items-center rounded-xl border border-border bg-background text-muted-foreground">
+        <Flag className="h-4 w-4" />
+      </div>
+    ),
+    leftActions,
+    rightActions,
+  },
+];
+
+export function SwipeableListPreview() {
+  const [items, setItems] = useState(initialItems);
+  const [lastAction, setLastAction] = useState("Ready");
+
+  return (
+    <div className="flex min-h-96 w-full items-center justify-center">
+      <div className="w-full max-w-sm rounded-[2rem] border border-border bg-background p-3 shadow-2xl">
+        <div className="mb-3 flex items-center justify-between px-1">
+          <div>
+            <p className="text-sm font-semibold text-foreground">Priority queue</p>
+            <p className="text-xs text-muted-foreground">{lastAction}</p>
+          </div>
+          <button
+            type="button"
+            onClick={() => {
+              setItems(initialItems);
+              setLastAction("Queue restored");
+            }}
+            className="inline-flex h-8 items-center gap-1.5 rounded-full border border-border px-3 text-xs font-medium text-muted-foreground transition-colors hover:text-foreground"
+          >
+            <RotateCcw className="h-3.5 w-3.5" />
+            Reset
+          </button>
+        </div>
+
+        <SwipeableList
+          items={items}
+          onAction={({ item, action }) => {
+            setLastAction(`${action.label} · ${item.title}`);
+
+            if (action.id === "trash") {
+              setItems((current) => current.filter((entry) => entry.id !== item.id));
+            }
+          }}
+        />
+
+        <div className="mt-3 flex items-center justify-between px-1 text-[11px] font-medium text-muted-foreground">
+          <span>{items.length} open</span>
+          <span>Today</span>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### SwipeableList
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `SwipeableListItem[]` | — | Yes | — |
+| `value` | `SwipeableListValue \| null` | — | No | — |
+| `defaultValue` | `SwipeableListValue \| null` | `null` | No | — |
+| `onValueChange` | `((value: SwipeableListValue \| null) => void)` | — | No | — |
+| `onAction` | `((payload: { item: SwipeableListItem; action: SwipeAction; side: SwipeSide; }) => void)` | — | No | — |
+| `actionWidth` | `number` | `56` | No | — |
+| `revealThreshold` | `number` | `34` | No | — |
+| `closeOnAction` | `boolean` | `true` | No | — |
+| `className` | `string` | — | No | — |
+| `classNames` | `SwipeableListClassNames` | — | No | — |
+| `renderItem` | `((item: SwipeableListItem) => ReactNode)` | — | No | — |
+

package/references/blocks/wallet-card.md

@@ -0,0 +1,97 @@
+---
+title: "Wallet Card"
+description: "Wallet overview card with an account switcher and search that morph open from their triggers, a cascading balance with a live change pill and privacy toggle, copy-address, and Send / Deposit / Swap / Buy actions."
+category: "Blocks"
+publishedAt: "2026-07-03"
+updatedAt: "2026-07-03"
+documentation: "references/blocks/wallet-card.md"
+markdown: "references/blocks/wallet-card.md"
+license: "MIT"
+---
+
+# Wallet Card
+
+> Wallet overview card with an account switcher and search that morph open from their triggers, a cascading balance with a live change pill and privacy toggle, copy-address, and Send / Deposit / Swap / Buy actions.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py wallet-card --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { WalletCard } from "@/components/motion/wallet-card";
+import { Button } from "@/components/motion/button";
+
+const ACCOUNTS = [
+  { id: "main", name: "Main Wallet", address: "0x8f3Cb1a29e4D7c6F1B2a3E9d0C4b5A6f7D8e9C0b" },
+  { id: "trading", name: "Trading", address: "0x1a2B3c4D5e6F7a8B9c0D1e2F3a4B5c6D7e8F9a0B" },
+  { id: "cold", name: "Cold Storage", address: "0x9F8e7D6c5B4a3E2d1C0b9A8f7E6d5C4b3A2e1F0d" },
+];
+
+const RECENT_SEARCHES = ["vitalik.eth", "0xA0b8…6EB4", "Uniswap", "Send to Trading"];
+
+export function WalletCardPreview() {
+  const [balance, setBalance] = useState(12480.32);
+
+  return (
+    <div className="flex w-full flex-col items-center gap-4 p-6">
+      <WalletCard
+        accounts={ACCOUNTS}
+        balance={balance}
+        defaultChange={124.5}
+        searchRecent={RECENT_SEARCHES}
+        hasNotifications
+      />
+      <Button
+        variant="ghost"
+        size="sm"
+        onClick={() => setBalance((b) => b + (Math.random() > 0.5 ? 1 : -1) * (50 + Math.random() * 400))}
+      >
+        Simulate balance change
+      </Button>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### WalletCard
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `accounts` | `WalletAccount[]` | — | Yes | — |
+| `accountId` | `string` | — | No | — |
+| `defaultAccountId` | `string` | — | No | — |
+| `onAccountChange` | `((id: string) => void)` | — | No | — |
+| `balance` | `number` | — | Yes | — |
+| `balancePrefix` | `string` | `$` | No | — |
+| `defaultChange` | `number` | — | No | Initial balance change shown in the pill before any live change. |
+| `defaultBalanceHidden` | `boolean` | `false` | No | Start with the balance hidden behind dots. |
+| `onSend` | `(() => void)` | — | No | — |
+| `onDeposit` | `(() => void)` | — | No | — |
+| `onSwap` | `(() => void)` | — | No | — |
+| `onBuy` | `(() => void)` | — | No | — |
+| `searchPlaceholder` | `string` | — | No | — |
+| `searchRecent` | `string[]` | — | No | Recent searches shown in the expanded search panel. |
+| `onSearchChange` | `((value: string) => void)` | — | No | — |
+| `onSearchSubmit` | `((value: string) => void)` | — | No | — |
+| `hasNotifications` | `boolean` | `false` | No | Show an unread pulse on the notifications bell. |
+| `onNotifications` | `(() => void)` | — | No | — |
+| `className` | `string` | — | No | — |
+

package/references/codex-install.md

@@ -0,0 +1,59 @@
+# Install Motion UI in Codex
+
+Motion UI is a local Codex skill package. It is not an npm library and does not need a server, API key, or MCP connection.
+
+## Project-scoped install
+
+Run this from the root of the project where Codex will work:
+
+```bash
+npx skills add Rkj0123/motion-ui-skill --skill motion-ui --agent codex --copy -y
+```
+
+The command creates `.agents/skills/motion-ui/SKILL.md` and copies the component source, references, catalog, and installer into that project.
+
+Verify the installation:
+
+```bash
+npx skills list --json
+```
+
+The result should contain `motion-ui` with `scope: "project"` and an agent list containing `Codex`.
+
+Start a new Codex task after installing, then invoke it explicitly when needed:
+
+```text
+Use $motion-ui to build the requested interface. Read the local catalog and component guide before writing code.
+```
+
+## Global install
+
+Use this when every project on the machine should see the skill:
+
+```bash
+npx skills add Rkj0123/motion-ui-skill --skill motion-ui --agent codex --global --copy -y
+```
+
+Verify global skills with:
+
+```bash
+npx skills list --global --agent codex --json
+```
+
+## Manual install
+
+If the skills CLI is unavailable, install into Codex's global skill directory:
+
+```bash
+mkdir -p ~/.codex/skills
+git clone https://github.com/Rkj0123/motion-ui-skill.git ~/.codex/skills/motion-ui
+```
+
+Reload Codex or start a new task. The skill entrypoint is `~/.codex/skills/motion-ui/SKILL.md`.
+
+## Troubleshooting
+
+- If the skill is not listed, run the command from the project root and confirm that `.agents/skills/motion-ui/SKILL.md` exists.
+- If the skill is listed but not active, start a new Codex task and write `Use $motion-ui ...` in the first message.
+- Use `--global` only when project-scoped installation is not enough.
+- Review the package before granting an agent permission to run its installer or copy files.

package/references/craft/3d-button.md

@@ -0,0 +1,51 @@
+---
+title: "Tactile 3D"
+description: "Universal 3D button with tactile keycap shadows — pass any children (label, icon + label). Variants: solid, soft, muted. Sizes: sm, md, lg, icon. Press sinks the key in."
+category: "Components"
+publishedAt: "2026-07-09"
+updatedAt: "2026-09-17"
+documentation: "references/craft/3d-button.md"
+markdown: "references/craft/3d-button.md"
+license: "MIT"
+---
+
+# Tactile 3D
+
+> Universal 3D button with tactile keycap shadows — pass any children (label, icon + label). Variants: solid, soft, muted. Sizes: sm, md, lg, icon. Press sinks the key in.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py 3d-button --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { ThreeDButton } from "@/components/buttons/three-d-button";
+
+export function ThreeDButtonDemo() {
+  return (
+    <div className="flex items-center justify-center p-6">
+      <ThreeDButton />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### ThreeDButton
+
+| Prop | Type | Default | Required | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `className` | `string` | — | No | Additional CSS classes |

package/references/craft/3d-icon-button.md

@@ -0,0 +1,51 @@
+---
+title: "Tactile 3D Icon"
+description: "Square 3D icon button — pass any icon as children and a required label for accessibility. Same solid / soft / muted materials as ThreeDButton."
+category: "Components"
+publishedAt: "2026-07-09"
+updatedAt: "2026-09-17"
+documentation: "references/craft/3d-icon-button.md"
+markdown: "references/craft/3d-icon-button.md"
+license: "MIT"
+---
+
+# Tactile 3D Icon
+
+> Square 3D icon button — pass any icon as children and a required label for accessibility. Same solid / soft / muted materials as ThreeDButton.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py 3d-icon-button --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { ThreeDIconButton } from "@/components/buttons/three-d-icon-button";
+
+export function ThreeDIconButtonDemo() {
+  return (
+    <div className="flex items-center justify-center p-6">
+      <ThreeDIconButton />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### ThreeDIconButton
+
+| Prop | Type | Default | Required | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `className` | `string` | — | No | Additional CSS classes |

package/references/craft/add-to-cart-button.md

@@ -0,0 +1,52 @@
+---
+title: "Add to Cart"
+description: "Raised 3D add-to-cart key that sinks in while adding, with gentle label crossfades, then pops back up in a solid emerald added state before resetting."
+category: "Components"
+publishedAt: "2026-07-09"
+updatedAt: "2026-09-17"
+documentation: "references/craft/add-to-cart-button.md"
+markdown: "references/craft/add-to-cart-button.md"
+license: "MIT"
+---
+
+# Add to Cart
+
+> Raised 3D add-to-cart key that sinks in while adding, with gentle label crossfades, then pops back up in a solid emerald added state before resetting.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py add-to-cart-button --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { AddToCartButton } from "@/components/buttons/add-to-cart-button";
+
+export function AddToCartButtonDemo() {
+  return (
+    <div className="flex items-center justify-center p-6">
+      <AddToCartButton />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### AddToCartButton
+
+| Prop | Type | Default | Required | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `className` | `string` | — | No | Additional CSS classes |