motion-ui-skill 2.0.0

package/references/motion/file-tree.md

@@ -0,0 +1,139 @@
+---
+title: "File Tree"
+description: "Composable file and folder primitives with springing branches, a gliding selection, and complete keyboard navigation."
+category: "Components"
+publishedAt: "2026-08-27"
+updatedAt: "2026-08-27"
+documentation: "references/motion/file-tree.md"
+markdown: "references/motion/file-tree.md"
+license: "MIT"
+---
+
+# File Tree
+
+> Composable file and folder primitives with springing branches, a gliding selection, and complete keyboard navigation.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py file-tree --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import {
+  Braces,
+  FileCode2,
+  FileJson2,
+  FileText,
+  Palette,
+} from "lucide-react";
+import {
+  FileTree,
+  FileTreeFile,
+  FileTreeFolder,
+} from "@/components/motion/file-tree";
+
+export function FileTreePreview() {
+  return (
+    <div className="flex min-h-[420px] w-full items-start justify-center px-4 pt-10">
+      <div className="w-full max-w-xs p-2">
+        <FileTree
+          defaultValue="file-tree"
+          defaultExpandedIds={["app", "components"]}
+          ariaLabel="Project files"
+        >
+          <FileTreeFolder value="app" name="app">
+            <FileTreeFolder value="components" name="components">
+              <FileTreeFile
+                value="file-tree"
+                name="file-tree.tsx"
+                icon={<Braces className="size-4 text-sky-500" />}
+              />
+              <FileTreeFile
+                value="button"
+                name="button.tsx"
+                icon={<Braces className="size-4 text-sky-500" />}
+              />
+            </FileTreeFolder>
+            <FileTreeFile
+              value="page"
+              name="page.tsx"
+              icon={<FileCode2 className="size-4 text-sky-500" />}
+            />
+            <FileTreeFile
+              value="styles"
+              name="globals.css"
+              icon={<Palette className="size-4 text-violet-500" />}
+            />
+          </FileTreeFolder>
+          <FileTreeFolder value="public" name="public">
+            <FileTreeFile value="logo" name="logo.svg" />
+            <FileTreeFile value="grid" name="grid.svg" />
+          </FileTreeFolder>
+          <FileTreeFile
+            value="package"
+            name="package.json"
+            icon={<FileJson2 className="size-4 text-amber-500" />}
+          />
+          <FileTreeFile
+            value="readme"
+            name="README.md"
+            icon={<FileText className="size-4 text-muted-foreground" />}
+          />
+        </FileTree>
+      </div>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### FileTreeFolder
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | Yes | — |
+| `name` | `string` | — | Yes | — |
+| `icon` | `ReactNode` | — | No | — |
+| `disabled` | `boolean` | — | No | — |
+| `className` | `string` | — | No | — |
+
+### FileTreeFile
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | Yes | — |
+| `name` | `string` | — | Yes | — |
+| `icon` | `ReactNode` | — | No | — |
+| `disabled` | `boolean` | — | No | — |
+| `className` | `string` | — | No | — |
+
+### FileTree
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string \| null` | — | No | — |
+| `defaultValue` | `string \| null` | `null` | No | — |
+| `onValueChange` | `((value: string) => void)` | — | No | — |
+| `expandedIds` | `string[]` | — | No | — |
+| `defaultExpandedIds` | `string[]` | `[]` | No | — |
+| `onExpandedChange` | `((expandedIds: string[]) => void)` | — | No | — |
+| `ariaLabel` | `string` | `Files` | No | — |
+| `indent` | `number` | `18` | No | — |
+| `className` | `string` | — | No | — |
+| `classNames` | `FileTreeClassNames` | — | No | — |
+

package/references/motion/filter-builder.md

@@ -0,0 +1,106 @@
+---
+title: "Filter Builder"
+description: "Faceted stepped query filter builder with dynamic attribute selectors, operator dropdowns, AND/OR logic toggles, and animated chip tags."
+category: "Blocks"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/filter-builder.md"
+markdown: "references/motion/filter-builder.md"
+license: "MIT"
+---
+
+# Filter Builder
+
+> Faceted stepped query filter builder with dynamic attribute selectors, operator dropdowns, AND/OR logic toggles, and animated chip tags. Inspired by KeenThemes ReUI and shadcn/ui.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py filter-builder --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { FilterBuilder, type FilterField, type FilterRule } from "@/components/motion/filter-builder";
+import { useState } from "react";
+
+const FIELDS: FilterField[] = [
+  {
+    id: "status",
+    label: "Status",
+    type: "select",
+    options: ["Active", "Pending", "Suspended", "Archived"],
+  },
+  {
+    id: "role",
+    label: "Team Role",
+    type: "select",
+    options: ["Admin", "Engineer", "Designer", "Auditor"],
+  },
+  {
+    id: "email",
+    label: "User Email",
+    type: "text",
+  },
+  {
+    id: "score",
+    label: "Health Score",
+    type: "number",
+  },
+];
+
+const INITIAL_RULES: FilterRule[] = [
+  {
+    id: "r1",
+    fieldId: "status",
+    operator: "is",
+    value: "Active",
+  },
+  {
+    id: "r2",
+    fieldId: "score",
+    operator: ">",
+    value: "80",
+  },
+];
+
+export function FilterBuilderExample() {
+  const [activeRules, setActiveRules] = useState<FilterRule[]>(INITIAL_RULES);
+
+  return (
+    <div className="max-w-xl p-4">
+      <FilterBuilder
+        fields={FIELDS}
+        initialRules={INITIAL_RULES}
+        conjunction="AND"
+        onChange={(rules, conj) => {
+          setActiveRules(rules);
+          console.log("Updated filters:", rules, "Match:", conj);
+        }}
+      />
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `fields` | `FilterField[]` | required | Available filterable attributes with type and option definitions. |
+| `initialRules` | `FilterRule[]` | `[]` | Initial set of applied filter rules. |
+| `conjunction` | `"AND" \| "OR"` | `"AND"` | Boolean conjunction joining rules together. |
+| `onChange` | `(rules: FilterRule[], conjunction: "AND" \| "OR") => void` | `undefined` | Callback emitted whenever rules or conjunction changes. |
+| `className` | `string` | `undefined` | Custom styling overrides merged via `cn()`. |

package/references/motion/frame.md

@@ -0,0 +1,61 @@
+---
+title: "Frame"
+description: "Interactive browser/device mockup frame with viewport size toggles (desktop, tablet, mobile) and smooth layout resizing."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/frame.md"
+markdown: "references/motion/frame.md"
+license: "MIT"
+---
+
+# Frame
+
+> Interactive browser/device mockup frame with viewport size toggles (desktop, tablet, mobile) and smooth layout resizing. Inspired by KeenThemes ReUI and ibelick/ui-skills.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py frame --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { Frame } from "@/components/motion/frame";
+
+export function FrameExample() {
+  return (
+    <div className="p-8">
+      <Frame url="https://acme.inc/dashboard" defaultViewport="desktop">
+        <div className="p-6 space-y-4">
+          <h1 className="text-xl font-bold">Analytics Dashboard</h1>
+          <p className="text-sm text-muted-foreground">
+            Responsive preview of the application layout across multiple breakpoints.
+          </p>
+        </div>
+      </Frame>
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `url` | `string` | `"https://acme.inc"` | Address bar URL text. |
+| `defaultViewport` | `"desktop" \| "tablet" \| "mobile"` | `"desktop"` | Initial viewport width mode. |
+| `children` | `React.ReactNode` | Required | Content rendered inside the mockup frame. |
+| `className` | `string` | `undefined` | Outer container classes. |

package/references/motion/gantt.md

@@ -0,0 +1,61 @@
+---
+title: "Gantt Chart"
+description: "Interactive Gantt task schedule timeline with milestone diamonds, progress fill overlays, split panes, and hover interactions."
+category: "Blocks"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/gantt.md"
+markdown: "references/motion/gantt.md"
+license: "MIT"
+---
+
+# Gantt Chart
+
+> Interactive Gantt task schedule timeline with milestone diamonds, progress fill overlays, split panes, and hover interactions. Inspired by KeenThemes ReUI.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py gantt --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { Gantt, type GanttTask } from "@/components/motion/gantt";
+
+const TASKS: GanttTask[] = [
+  { id: "1", name: "System Architecture & Specs", startDay: 1, duration: 4, progress: 100 },
+  { id: "2", name: "Motion Tokens Integration", startDay: 4, duration: 6, progress: 75 },
+  { id: "3", name: "Security Audit Alpha", startDay: 10, duration: 1, isMilestone: true },
+  { id: "4", name: "Production Rollout", startDay: 11, duration: 8, progress: 20 },
+];
+
+export function GanttExample() {
+  return (
+    <div className="max-w-4xl p-6">
+      <Gantt tasks={TASKS} totalDays={20} onTaskClick={(t) => console.log("Task:", t.name)} />
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `tasks` | `GanttTask[]` | required | Array of tasks with start day, duration, progress, and milestone flag. |
+| `totalDays` | `number` | `20` | Total horizontal day column span. |
+| `onTaskClick` | `(task: GanttTask) => void` | `undefined` | Callback emitted when a task row is clicked. |
+| `className` | `string` | `undefined` | Custom styling overrides merged via `cn()`. |

package/references/motion/glow-button.md

@@ -0,0 +1,59 @@
+---
+title: "Glow Button"
+description: "Premium CTA button featuring an iridescent glowing perimeter gradient, magnetic pointer attraction, and tactile spring feedback."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/glow-button.md"
+markdown: "references/motion/glow-button.md"
+license: "MIT"
+---
+
+# Glow Button
+
+> Premium CTA button featuring an iridescent glowing perimeter gradient, magnetic pointer attraction, and tactile spring feedback. Inspired by ibelick/ui-skills and Transitions.dev.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py glow-button --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { GlowButton } from "@/components/motion/glow-button";
+import { ArrowRight, Sparkles } from "lucide-react";
+
+export function GlowButtonExample() {
+  return (
+    <div className="flex items-center gap-4 p-8">
+      <GlowButton onClick={() => console.log("Clicked")}>
+        <Sparkles className="size-4 text-purple-400" />
+        <span>Deploy Autonomous Agent</span>
+        <ArrowRight className="size-4" />
+      </GlowButton>
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `children` | `ReactNode` | required | Button label or icon content. |
+| `magnetic` | `boolean` | `true` | Enables subtle magnetic pointer displacement toward cursor. |
+| `magneticDistance` | `number` | `0.25` | Fraction of cursor offset applied to the button element. |
+| `glowColor` | `string` | `"from-primary via-purple-500 to-pink-500"` | Tailwind gradient color classes for perimeter glow. |
+| `className` | `string` | `undefined` | Custom styling overrides merged via `cn()`. |

package/references/motion/haptic-pressable.md

@@ -0,0 +1,64 @@
+---
+title: "Haptic Pressable"
+description: "Cross-platform touchable component with multi-tier semantic haptic feedback, scale press physics, and touch ripple effects."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/haptic-pressable.md"
+markdown: "references/motion/haptic-pressable.md"
+license: "MIT"
+---
+
+# Haptic Pressable
+
+> Cross-platform touchable component with multi-tier semantic haptic feedback, scale press physics, and touch ripple effects. Inspired by Expo and Apple HIG.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py haptic-pressable --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { HapticPressable } from "@/components/motion/haptic-pressable";
+import { Sparkles } from "lucide-react";
+
+export function HapticPressableExample() {
+  return (
+    <div className="p-8">
+      <HapticPressable
+        haptic="medium"
+        pressScale={0.94}
+        onClick={() => console.log("Pressed with haptic feedback")}
+        className="flex items-center gap-2 rounded-2xl bg-primary px-5 py-3 text-sm font-semibold text-primary-foreground shadow-md"
+      >
+        <Sparkles className="size-4" />
+        <span>Tactile Mobile Action</span>
+      </HapticPressable>
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `children` | `ReactNode` | required | Pressable inner content. |
+| `haptic` | `HapticType` | `"selection"` | Sensation type (`selection`, `light`, `medium`, `heavy`, `success`, `error`). |
+| `pressScale` | `number` | `0.96` | Downward scale compression factor during active press. |
+| `showRipple` | `boolean` | `true` | Renders a radial expanding ripple wave at click point. |
+| `disabled` | `boolean` | `false` | Disables interaction and suppresses haptics. |
+| `className` | `string` | `undefined` | Custom styling overrides merged via `cn()`. |

package/references/motion/hover-card.md

@@ -0,0 +1,86 @@
+---
+title: "Hover Card"
+description: "Rich contextual hover card popover with open/close delay buffering, spring entrance, and collision avoidance."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/hover-card.md"
+markdown: "references/motion/hover-card.md"
+license: "MIT"
+---
+
+# Hover Card
+
+> Rich contextual hover card popover with open/close delay buffering, spring entrance, and collision avoidance. Inspired by shadcn/ui and Coss.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py hover-card --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { HoverCard } from "@/components/motion/hover-card";
+import { CalendarDays, Sparkles } from "lucide-react";
+
+export function HoverCardExample() {
+  return (
+    <div className="p-12">
+      <HoverCard
+        side="bottom"
+        align="center"
+        openDelay={150}
+        closeDelay={200}
+        content={
+          <div className="space-y-2">
+            <div className="flex items-center gap-2">
+              <div className="size-8 rounded-full bg-primary/20 flex items-center justify-center text-primary font-bold text-xs">
+                NX
+              </div>
+              <div>
+                <h4 className="text-xs font-semibold">@nextjs</h4>
+                <p className="text-[11px] text-muted-foreground">The React Framework for the Web</p>
+              </div>
+            </div>
+            <p className="text-xs text-muted-foreground leading-relaxed">
+              Production-grade React applications with server components, streaming, and edge caching.
+            </p>
+            <div className="flex items-center gap-2 text-[10px] text-muted-foreground pt-1 border-t border-border">
+              <CalendarDays className="size-3" />
+              <span>Joined December 2021</span>
+            </div>
+          </div>
+        }
+      >
+        <span className="text-sm font-semibold underline decoration-dotted underline-offset-4 cursor-pointer hover:text-primary transition-colors">
+          @nextjs
+        </span>
+      </HoverCard>
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `children` | `ReactNode` | required | The anchor element triggering the hover card. |
+| `content` | `ReactNode` | required | Rich content displayed inside the floating popover card. |
+| `openDelay` | `number` | `200` | Delay in ms before card opens on hover. |
+| `closeDelay` | `number` | `250` | Buffer delay in ms before closing on pointer leave. |
+| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Preferred orientation relative to trigger. |
+| `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment axis of the popover. |
+| `className` | `string` | `undefined` | Custom styling overrides merged via `cn()`. |

package/references/motion/icon-stack.md

@@ -0,0 +1,64 @@
+---
+title: "Icon Stack"
+description: "Overlapping icon and avatar cluster with hover fan-out expansion, spring elevation, and automated tooltip reveals."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/icon-stack.md"
+markdown: "references/motion/icon-stack.md"
+license: "MIT"
+---
+
+# Icon Stack
+
+> Overlapping icon and avatar cluster with hover fan-out expansion, spring elevation, and automated tooltip reveals. Inspired by KeenThemes ReUI and Coss.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py icon-stack --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { IconStack, type IconStackItem } from "@/components/motion/icon-stack";
+
+const ITEMS: IconStackItem[] = [
+  { id: "1", label: "Alex Rivera", src: "https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=100&h=100&fit=crop" },
+  { id: "2", label: "Elena Rostova", src: "https://images.unsplash.com/photo-1517841905240-472988babdf9?w=100&h=100&fit=crop" },
+  { id: "3", label: "Marcus Chen", src: "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=100&h=100&fit=crop" },
+  { id: "4", label: "Sarah Kim", src: "https://images.unsplash.com/photo-1494790108377-be9c29b29330?w=100&h=100&fit=crop" },
+  { id: "5", label: "David Park", src: "https://images.unsplash.com/photo-1500648767791-00dcc994a43e?w=100&h=100&fit=crop" },
+  { id: "6", label: "Rachel Zane" },
+];
+
+export function IconStackExample() {
+  return (
+    <div className="p-8">
+      <IconStack items={ITEMS} maxVisible={4} size="md" overlap="normal" />
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `items` | `IconStackItem[]` | Required | Array of icon / avatar definitions. |
+| `maxVisible` | `number` | `5` | Maximum number of icons rendered before `+N` badge. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size scale of circular avatars. |
+| `spreadOnHover` | `boolean` | `true` | Expands overlap margin when hovering over the container. |
+| `overlap` | `"tight" \| "normal" \| "relaxed"` | `"normal"` | Overlapping spacing density. |
+| `className` | `string` | `undefined` | Container classes. |