motion-ui-skill 2.0.0

package/references/blocks/card-folder.md

@@ -0,0 +1,165 @@
+---
+title: "Card Folder"
+description: "A landscape card tucked into a stitched purse pocket that lifts forward as the purse compresses into its bottom seam, with controlled open and card-detail visibility plus a separate overflow action."
+category: "Blocks"
+publishedAt: "2026-09-04"
+updatedAt: "2026-09-04"
+documentation: "references/blocks/card-folder.md"
+markdown: "references/blocks/card-folder.md"
+license: "MIT"
+---
+
+# Card Folder
+
+> A landscape card tucked into a stitched purse pocket that lifts forward as the purse compresses into its bottom seam, with controlled open and card-detail visibility plus a separate overflow action.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py card-folder --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { CardFolder } from "@/components/motion/card-folder";
+import { DigitSwap } from "@/components/motion/digit-swap";
+
+const CARD_NUMBER = "3745 6987 4096 0806";
+const MASKED_CARD_NUMBER = "•••• •••• •••• 0806";
+const CONTOUR_RADII = Array.from({ length: 18 }, (_, index) => 72 + index * 24);
+
+function CardArtwork({ detailsVisible }: { detailsVisible: boolean }) {
+  return (
+    <span className="relative block h-full w-full overflow-hidden bg-[linear-gradient(135deg,#383a38_0%,#202120_48%,#111211_100%)] text-white">
+      <svg
+        aria-hidden="true"
+        viewBox="0 0 640 404"
+        className="absolute inset-0 h-full w-full"
+      >
+        {CONTOUR_RADII.map((radius, index) => (
+          <circle
+            // The concentric contours deliberately begin outside the card so
+            // their cropped curves read like the reference artwork.
+            key={radius}
+            cx="-20"
+            cy="-28"
+            r={radius}
+            fill="none"
+            stroke="currentColor"
+            strokeOpacity={0.32 - index * 0.009}
+            strokeWidth="1.5"
+          />
+        ))}
+      </svg>
+
+      <span className="absolute inset-0 bg-[radial-gradient(circle_at_78%_8%,rgb(255_255_255/0.11),transparent_32%)]" />
+
+      <span className="absolute left-[6%] top-[8%] flex flex-col gap-2">
+        <span className="text-[10px] font-medium uppercase tracking-[0.22em] text-white/55">
+          Saurabh Chauhan
+        </span>
+        <DigitSwap
+          value={detailsVisible ? CARD_NUMBER : MASKED_CARD_NUMBER}
+          animationKey={detailsVisible ? "revealed" : "masked"}
+          direction={detailsVisible ? "up" : "down"}
+          suffixLength={4}
+          glyphClassName={detailsVisible ? "text-white/90" : "text-white/65"}
+          suffixClassName="text-white/90"
+          className="font-mono text-xs tracking-[0.13em]"
+        />
+      </span>
+
+      <span className="absolute top-[8%] right-[7%] h-[20%] w-[13%] overflow-hidden rounded-[18%] border border-black/30 bg-[linear-gradient(135deg,#f2f0ea_0%,#b9b7b1_45%,#e4e1d9_100%)]">
+        <span className="absolute inset-y-0 left-1/2 w-px -translate-x-1/2 bg-black/30" />
+        <span className="absolute inset-x-0 top-1/3 h-px bg-black/30" />
+        <span className="absolute inset-x-0 bottom-1/3 h-px bg-black/30" />
+        <span className="absolute left-0 top-1/2 h-[34%] w-[28%] -translate-y-1/2 rounded-r-[35%] border border-l-0 border-black/30" />
+        <span className="absolute right-0 top-1/2 h-[34%] w-[28%] -translate-y-1/2 rounded-l-[35%] border border-r-0 border-black/30" />
+      </span>
+
+      <span className="absolute bottom-[9%] left-[6%] flex items-center gap-2 text-lg font-semibold tracking-[-0.04em]">
+        Motion UI <span className="block size-2.5 rotate-45 rounded-[2px] bg-white/85" />
+      </span>
+
+      <span className="absolute right-[7%] bottom-[10%] flex items-end gap-5">
+        <span className="flex flex-col gap-1">
+          <span className="text-[8px] font-medium uppercase tracking-[0.16em] text-white/40">
+            Expiry
+          </span>
+          <span className="text-xs font-medium text-white/90 tabular-nums">
+            08/29
+          </span>
+        </span>
+        <span className="flex flex-col gap-1">
+          <span className="text-[8px] font-medium uppercase tracking-[0.16em] text-white/40">
+            CVV
+          </span>
+          <DigitSwap
+            value={detailsVisible ? "123" : "•••"}
+            animationKey={detailsVisible ? "revealed" : "masked"}
+            direction={detailsVisible ? "up" : "down"}
+            className="font-mono text-xs font-medium text-white/90"
+          />
+        </span>
+      </span>
+    </span>
+  );
+}
+
+export function CardFolderPreview() {
+  const [detailsVisible, setDetailsVisible] = useState(false);
+
+  return (
+    <div className="flex min-h-72 w-full items-center justify-center px-6 py-9">
+      <CardFolder
+        title="Saurabh Chauhan"
+        cardNumber={CARD_NUMBER}
+        expiry="08/29"
+        cvv="123"
+        detailsVisible={detailsVisible}
+        onDetailsVisibleChange={setDetailsVisible}
+        card={<CardArtwork detailsVisible={detailsVisible} />}
+      />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### CardFolder
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `title` | `string` | — | Yes | — |
+| `cardNumber` | `string` | — | Yes | — |
+| `expiry` | `string` | — | Yes | — |
+| `cvv` | `string` | — | Yes | — |
+| `card` | `ReactNode` | — | Yes | — |
+| `open` | `boolean` | — | No | — |
+| `defaultOpen` | `boolean` | `false` | No | — |
+| `onOpenChange` | `((open: boolean) => void)` | — | No | — |
+| `detailsVisible` | `boolean` | — | No | — |
+| `defaultDetailsVisible` | `boolean` | `false` | No | — |
+| `onDetailsVisibleChange` | `((visible: boolean) => void)` | — | No | — |
+| `onClick` | `(() => void)` | — | No | — |
+| `onAction` | `(() => void)` | — | No | — |
+| `ariaLabel` | `string` | — | No | — |
+| `actionLabel` | `string` | — | No | — |
+| `disabled` | `boolean` | `false` | No | — |
+| `className` | `string` | — | No | — |
+| `cardClassName` | `string` | — | No | — |
+

package/references/blocks/command-palette.md

@@ -0,0 +1,89 @@
+---
+title: "Command Palette"
+description: "⌘K palette with fuzzy filter, spring-animated active row and glass surface."
+category: "Blocks"
+publishedAt: "2026-05-17"
+updatedAt: "2026-08-22"
+documentation: "references/blocks/command-palette.md"
+markdown: "references/blocks/command-palette.md"
+license: "MIT"
+---
+
+# Command Palette
+
+> ⌘K palette with fuzzy filter, spring-animated active row and glass surface.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py command-palette --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `react-dom`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { FileText, Home, Plus, Settings, User } from "lucide-react";
+import { useState } from "react";
+import { CommandPalette } from "@/components/motion/command-palette";
+
+export function CommandPalettePreview() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div className="flex flex-col items-start gap-3">
+      <button
+        type="button"
+        onClick={() => setOpen(true)}
+        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 command palette
+      </button>
+      <p className="text-sm text-muted-foreground">
+        Press{" "}
+        <kbd className="rounded border border-border bg-card px-1.5 py-0.5 text-xs text-foreground">
+          ⌘ J
+        </kbd>{" "}
+        (or <kbd className="rounded border border-border bg-card px-1.5 py-0.5 text-xs text-foreground">Ctrl J</kbd>) to open.
+      </p>
+      <CommandPalette
+        open={open}
+        onOpenChange={setOpen}
+        shortcut="j"
+        items={[
+          { id: "home", label: "Go to Home", group: "Navigation", icon: Home, hint: "G H", onSelect: () => {} },
+          { id: "profile", label: "Open profile", group: "Navigation", icon: User, hint: "G P", onSelect: () => {} },
+          { id: "settings", label: "Settings", group: "Navigation", icon: Settings, onSelect: () => {} },
+          { id: "new-doc", label: "Create document", group: "Actions", icon: FileText, hint: "⌘ N", onSelect: () => {} },
+          { id: "new-project", label: "New project", group: "Actions", icon: Plus, hint: "⌘ ⇧ N", onSelect: () => {} },
+        ]}
+      />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### CommandPalette
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `CommandItem[]` | — | Yes | — |
+| `shortcut` | `string` | `k` | No | Opens with Cmd/Ctrl + this key. Default: "k" |
+| `placeholder` | `string` | `Type a command or search…` | No | — |
+| `emptyMessage` | `string` | `No results found.` | No | — |
+| `open` | `boolean` | — | No | — |
+| `onOpenChange` | `((open: boolean) => void)` | — | No | — |
+

package/references/blocks/dynamic-island.md

@@ -0,0 +1,203 @@
+---
+title: "Dynamic Island"
+description: "iOS-style island pill that morphs between live activity views with bouncy shell resize and blur crossfades."
+category: "Blocks"
+publishedAt: "2026-06-10"
+updatedAt: "2026-07-13"
+documentation: "references/blocks/dynamic-island.md"
+markdown: "references/blocks/dynamic-island.md"
+license: "MIT"
+---
+
+# Dynamic Island
+
+> iOS-style island pill that morphs between live activity views with bouncy shell resize and blur crossfades.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py dynamic-island --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { Music, Phone, PhoneOff, Timer } from "lucide-react";
+import { motion, useReducedMotion } from "motion/react";
+import { useEffect, useState } from "react";
+import { Button } from "@/components/motion/button";
+import {
+  DynamicIsland,
+  DynamicIslandView,
+} from "@/components/motion/dynamic-island";
+import { NumberTicker } from "@/components/motion/number-ticker";
+
+type IslandView = "call" | "timer" | "music" | null;
+
+const BAR_DELAYS = [0, 0.18, 0.09, 0.27];
+
+function EqBars() {
+  const reduce = useReducedMotion();
+  return (
+    <span className="flex h-4 items-end gap-0.5" aria-hidden>
+      {BAR_DELAYS.map((delay) => (
+        <motion.span
+          key={delay}
+          animate={reduce ? undefined : { scaleY: [0.4, 1, 0.55, 0.9, 0.4] }}
+          transition={{
+            duration: 1.1,
+            repeat: Infinity,
+            ease: "easeInOut",
+            delay,
+          }}
+          className="h-full w-0.5 origin-bottom rounded-full bg-(--color-success)"
+          style={{ scaleY: 0.6 }}
+        />
+      ))}
+    </span>
+  );
+}
+
+function formatClock(totalSeconds: number) {
+  const m = Math.floor(totalSeconds / 60);
+  const s = totalSeconds % 60;
+  return `${m}:${String(s).padStart(2, "0")}`;
+}
+
+export function DynamicIslandPreview() {
+  const [view, setView] = useState<IslandView>(null);
+  const [seconds, setSeconds] = useState(154);
+
+  useEffect(() => {
+    if (view !== "timer") return;
+    const id = window.setInterval(() => {
+      setSeconds((s) => (s > 0 ? s - 1 : 0));
+    }, 1000);
+    return () => window.clearInterval(id);
+  }, [view]);
+
+  return (
+    <div className="flex w-full flex-col items-center gap-4">
+      {/* Fixed-height, top-aligned zone: the island stays pinned at the top
+          like under a notch and unfurls downward into reserved space. */}
+      <div className="flex h-32 w-full items-start justify-center pt-2">
+        <DynamicIsland
+          view={view}
+          compact={
+            <>
+              <span className="h-1.5 w-1.5 rounded-full bg-(--color-success)" />
+              <span>9:41</span>
+            </>
+          }
+        >
+          <DynamicIslandView id="call" className="gap-4">
+            <div className="flex flex-col">
+              <span className="text-[10px] uppercase tracking-wider opacity-60">
+                Incoming call
+              </span>
+              <span className="text-sm font-semibold">Saurabh</span>
+            </div>
+            <div className="flex items-center gap-2">
+              <button
+                type="button"
+                aria-label="Decline"
+                onClick={() => setView(null)}
+                className="flex h-8 w-8 items-center justify-center rounded-full bg-destructive text-white"
+              >
+                <PhoneOff className="h-3.5 w-3.5" />
+              </button>
+              <button
+                type="button"
+                aria-label="Accept"
+                onClick={() => setView(null)}
+                className="flex h-8 w-8 items-center justify-center rounded-full bg-(--color-success) text-white"
+              >
+                <Phone className="h-3.5 w-3.5" />
+              </button>
+            </div>
+          </DynamicIslandView>
+
+          <DynamicIslandView id="timer" className="gap-3">
+            <Timer className="h-4 w-4 text-(--color-warning)" />
+            <span className="text-[10px] uppercase tracking-wider opacity-60">
+              Timer
+            </span>
+            <NumberTicker
+              value={seconds}
+              format={formatClock}
+              startOnView={false}
+              duration={0.5}
+              className="text-sm font-semibold"
+            />
+          </DynamicIslandView>
+
+          <DynamicIslandView id="music" className="gap-3">
+            <span className="flex h-7 w-7 items-center justify-center rounded-lg bg-background/15">
+              <Music className="h-3.5 w-3.5" />
+            </span>
+            <div className="flex flex-col text-left">
+              <span className="text-xs font-semibold leading-tight">
+                Midnight City
+              </span>
+              <span className="text-[10px] opacity-60">M83</span>
+            </div>
+            <EqBars />
+          </DynamicIslandView>
+        </DynamicIsland>
+      </div>
+
+      <div className="flex flex-wrap items-center justify-center gap-2">
+        <Button size="sm" variant="secondary" onClick={() => setView("call")}>
+          Call
+        </Button>
+        <Button
+          size="sm"
+          variant="secondary"
+          onClick={() => {
+            setSeconds(154);
+            setView("timer");
+          }}
+        >
+          Timer
+        </Button>
+        <Button size="sm" variant="secondary" onClick={() => setView("music")}>
+          Music
+        </Button>
+        <Button size="sm" variant="ghost" onClick={() => setView(null)}>
+          Dismiss
+        </Button>
+      </div>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### DynamicIsland
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `view` | `string \| null` | — | Yes | Active view id. `null` shows the compact pill. |
+| `compact` | `ReactNode` | — | No | Compact pill content, shown when no view is active. |
+| `children` | `ReactNode` | — | No | DynamicIslandView elements. |
+| `className` | `string` | — | No | — |
+
+### DynamicIslandView
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `id` | `string` | — | Yes | Matches the parent `view` prop when active. |
+| `className` | `string` | — | No | — |
+

package/references/blocks/expandable-action-bar.md

@@ -0,0 +1,191 @@
+---
+title: "Expandable Action Bar"
+description: "Compact icon actions that expand into labeled controls on hover or focus with shared layout motion."
+category: "Blocks"
+publishedAt: "2026-06-05"
+updatedAt: "2026-06-22"
+documentation: "references/blocks/expandable-action-bar.md"
+markdown: "references/blocks/expandable-action-bar.md"
+license: "MIT"
+---
+
+# Expandable Action Bar
+
+> Compact icon actions that expand into labeled controls on hover or focus with shared layout motion.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py expandable-action-bar --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import {
+  Archive,
+  Bell,
+  Copy,
+  Download,
+  Send,
+  Settings,
+} from "lucide-react";
+import { AnimatePresence, motion } from "motion/react";
+import { useMemo, useState } from "react";
+import {
+  ExpandableActionBar,
+  type ExpandableActionBarItem,
+} from "@/components/motion/expandable-action-bar";
+
+const ACTIONS: ExpandableActionBarItem[] = [
+  {
+    id: "send",
+    label: "Send",
+    icon: <Send className="h-4 w-4 motion-safe:group-hover:animate-action-send" />,
+    shortcut: "S",
+  },
+  {
+    id: "copy",
+    label: "Copy",
+    icon: <Copy className="h-4 w-4 motion-safe:group-hover:animate-action-copy" />,
+    shortcut: "C",
+  },
+  {
+    id: "download",
+    label: "Export",
+    icon: <Download className="h-4 w-4 motion-safe:group-hover:animate-action-download" />,
+    shortcut: "E",
+  },
+  {
+    id: "archive",
+    label: "Archive",
+    icon: <Archive className="h-4 w-4 motion-safe:group-hover:animate-action-archive" />,
+  },
+  {
+    id: "alerts",
+    label: "Alerts",
+    icon: <Bell className="h-4 w-4 origin-top motion-safe:group-hover:animate-action-bell" />,
+    badge: "3",
+  },
+  {
+    id: "settings",
+    label: "Settings",
+    icon: <Settings className="h-4 w-4 motion-safe:group-hover:animate-action-settings" />,
+  },
+];
+
+export function ExpandableActionBarPreview() {
+  const [expanded, setExpanded] = useState(false);
+  const [activeId, setActiveId] = useState("send");
+
+  const items = useMemo(
+    () =>
+      ACTIONS.map((item) => ({
+        ...item,
+        active: item.id === activeId,
+      })),
+    [activeId],
+  );
+
+  return (
+    <div className="flex min-h-72 w-full flex-col items-center justify-center gap-6">
+      <div className="flex min-h-24 w-full items-center justify-center">
+        <ExpandableActionBar
+          items={items}
+          expanded={expanded}
+          onExpandedChange={setExpanded}
+          activeId={activeId}
+          onAction={(item) => setActiveId(item.id)}
+          classNames={{
+            item: "group",
+          }}
+        />
+      </div>
+
+      <div className="flex flex-wrap items-center justify-center gap-2">
+        <motion.button
+          type="button"
+          onClick={() => setExpanded((current) => !current)}
+          className="relative flex h-9 w-[110px] items-center justify-center overflow-hidden rounded-full border border-border bg-card text-xs font-medium text-foreground transition-colors hover:border-(--color-border-strong)"
+          whileHover={{ scale: 1.02 }}
+          whileTap={{ scale: 0.96 }}
+        >
+          <motion.div layout className="flex items-center gap-1.5">
+            <motion.svg
+              width="24"
+              height="24"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              className="h-3.5 w-3.5 shrink-0"
+            >
+              <motion.path
+                initial={false}
+                animate={{
+                  d: expanded ? "M 10 20 L 10 14 L 4 14" : "M 9 21 L 3 21 L 3 15",
+                }}
+                transition={{ type: "spring", bounce: 0, duration: 0.3 }}
+              />
+              <motion.path
+                initial={false}
+                animate={{
+                  d: expanded ? "M 14 4 L 14 10 L 20 10" : "M 15 3 L 21 3 L 21 9",
+                }}
+                transition={{ type: "spring", bounce: 0, duration: 0.3 }}
+              />
+              <line x1="14" x2="21" y1="10" y2="3" />
+              <line x1="3" x2="10" y1="21" y2="14" />
+            </motion.svg>
+            <AnimatePresence mode="popLayout" initial={false}>
+              <motion.span
+                key={expanded ? "expanded" : "collapsed"}
+                initial={{ opacity: 0, y: -25, filter: "blur(4px)" }}
+                animate={{ opacity: 1, y: 0, filter: "blur(0px)" }}
+                exit={{ opacity: 0, y: 25, filter: "blur(4px)" }}
+                transition={{ type: "spring", bounce: 0, duration: 0.3 }}
+              >
+                {expanded ? "Collapse" : "Expand"}
+              </motion.span>
+            </AnimatePresence>
+          </motion.div>
+        </motion.button>
+      </div>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### ExpandableActionBar
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `ExpandableActionBarItem[]` | — | Yes | — |
+| `expanded` | `boolean` | — | No | — |
+| `defaultExpanded` | `boolean` | `false` | No | — |
+| `onExpandedChange` | `((expanded: boolean) => void)` | — | No | — |
+| `activeId` | `string` | — | No | — |
+| `onAction` | `((item: ExpandableActionBarItem) => void)` | — | No | — |
+| `size` | `"sm" \| "md"` | `md` | No | — |
+| `expandOnHover` | `boolean` | `true` | No | Expand when a pointer that hovers rests on the bar. Default true. It also governs the touch equivalent: with no hover to reveal the labels, the first tap expands the bar and runs no action, and the second one acts. Set false to make every tap and click act immediately. |
+| `expandOnFocus` | `boolean` | `true` | No | — |
+| `collapseDelay` | `number` | `90` | No | — |
+| `className` | `string` | — | No | — |
+| `classNames` | `ExpandableActionBarClassNames` | — | No | — |
+| `renderItem` | `((item: ExpandableActionBarItem, state: { expanded: boolean; active: boolean; }) => ReactNode)` | — | No | — |
+