motion-ui-skill 2.0.0

package/references/motion/text-animation.md

@@ -0,0 +1,285 @@
+---
+title: "Text Animation"
+description: "Animated text primitives for spring reveals, chromatic sweeps, shimmer loading states, letter-cascade swaps and character scrambles."
+category: "Components"
+publishedAt: "2026-05-17"
+updatedAt: "2026-08-19"
+documentation: "references/motion/text-animation.md"
+markdown: "references/motion/text-animation.md"
+license: "MIT"
+---
+
+# Text Animation
+
+> Animated text primitives for spring reveals, chromatic sweeps, shimmer loading states, letter-cascade swaps and character scrambles.
+
+## Install
+
+### Text Scramble
+
+A controlled character scramble that resolves changed text while keeping its final value accessible.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py text-scramble --dest ./src
+```
+
+### Dia Text Animation
+
+A Dia-inspired text effect with a fixed sentence prefix and a cycling final word revealed by a colorful sweep.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py chromatic-text-reveal --dest ./src
+```
+
+### Text Reveal
+
+Word or character reveal with spring slide-up and blur.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py text-reveal --dest ./src
+```
+
+### Text Shimmer
+
+Gradient sweep across text for loading or emphasis.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py text-shimmer --dest ./src
+```
+
+### Text Cascade
+
+Letter-by-letter slot roll for standalone text — old letters drop away as new ones land, left to right.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py text-cascade --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+### Text Scramble usage
+
+A controlled character scramble that resolves changed text while keeping its final value accessible.
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { TextScramble } from "@/components/motion/text-scramble";
+
+const PHRASES = [
+  "Inspecting the repository",
+  "Running the checks",
+  "Preparing the update",
+];
+
+export function TextScramblePreview() {
+  const [index, setIndex] = useState(0);
+
+  return (
+    <div className="flex w-full flex-col items-center gap-8 text-center">
+      <TextScramble
+        text={PHRASES[index]}
+        className="font-mono text-xl font-medium text-foreground"
+      />
+
+      <button
+        type="button"
+        onClick={() => setIndex((current) => (current + 1) % PHRASES.length)}
+        className="inline-flex h-9 items-center rounded-full border border-border bg-card px-4 text-xs font-medium text-foreground press hover:border-(--color-border-strong)"
+      >
+        Next phrase
+      </button>
+    </div>
+  );
+}
+```
+
+### Dia Text Animation usage
+
+A Dia-inspired text effect with a fixed sentence prefix and a cycling final word revealed by a colorful sweep.
+
+```tsx
+import { ChromaticTextReveal } from "@/components/motion/chromatic-text-reveal";
+
+export function ChromaticTextRevealPreview() {
+  return (
+    // The sentence never wraps, so it has to be sized against the space it
+    // actually gets — the surrounding column, not the viewport.
+    <div className="@container flex w-full justify-center">
+      <ChromaticTextReveal
+        prefix="Motion that feels"
+        words={["natural.", "intentional.", "alive."]}
+        startOnView={false}
+        className="shrink-0 font-medium tracking-[-0.04em] text-foreground [font-size:clamp(1.25rem,7.8cqw,3rem)]"
+      />
+    </div>
+  );
+}
+```
+
+### Text Reveal usage
+
+Word or character reveal with spring slide-up and blur.
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { TextReveal } from "@/components/motion/text-reveal";
+
+export function TextRevealPreview() {
+  const [key, setKey] = useState(0);
+  return (
+    <div className="flex w-full flex-col items-center gap-8 text-center">
+      <div key={key} className="flex flex-col gap-2">
+        <TextReveal
+          as="h2"
+          text={["Motion that feels", "considered."]}
+          className="text-balance text-4xl font-semibold leading-[0.95] tracking-[-0.04em] text-foreground sm:text-5xl"
+        />
+        <TextReveal
+          text="Word by word, with a soft blur."
+          delay={0.9}
+          stagger={0.05}
+          blur={6}
+          yOffset="20%"
+          className="text-sm text-muted-foreground"
+        />
+      </div>
+
+      <button
+        type="button"
+        onClick={() => setKey((k) => k + 1)}
+        className="inline-flex h-9 items-center rounded-full border border-border bg-card px-4 text-xs font-medium text-foreground press hover:border-(--color-border-strong)"
+      >
+        Replay
+      </button>
+    </div>
+  );
+}
+```
+
+### Text Shimmer usage
+
+Gradient sweep across text for loading or emphasis.
+
+```tsx
+"use client";
+
+import { TextShimmer } from "@/components/motion/text-shimmer";
+
+export function TextShimmerPreview() {
+  return (
+    <div className="flex flex-col gap-4">
+      <TextShimmer className="text-3xl font-semibold">Loading projects…</TextShimmer>
+      <TextShimmer duration={1.5} className="text-sm">Faster shimmer</TextShimmer>
+    </div>
+  );
+}
+```
+
+### Text Cascade usage
+
+Letter-by-letter slot roll for standalone text — old letters drop away as new ones land, left to right.
+
+```tsx
+"use client";
+
+import { useEffect, useState } from "react";
+import { TextCascade } from "@/components/motion/text-cascade";
+
+const PHRASES = ["Install skills", "Open settings", "Ship updates"];
+
+export function TextCascadePreview() {
+  const [phrase, setPhrase] = useState(0);
+
+  useEffect(() => {
+    const id = window.setInterval(() => {
+      setPhrase((p) => (p + 1) % PHRASES.length);
+    }, 2400);
+    return () => window.clearInterval(id);
+  }, []);
+
+  return (
+    <div className="flex w-full justify-center">
+      <p className="text-lg font-medium text-foreground">
+        <TextCascade text={PHRASES[phrase] ?? PHRASES[0]} />
+      </p>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### TextScramble
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `text` | `string` | — | Yes | Final text revealed by the scramble animation. |
+| `duration` | `number` | — | No | Maximum animation duration in milliseconds. |
+| `glyphs` | `string` | `ABCDEFGHJKLMNPQRSTUVWXYZ0123456789#%&@$?/` | No | Characters sampled while unresolved positions are scrambling. |
+| `className` | `string` | — | No | — |
+| `style` | `CSSProperties` | — | No | — |
+
+### ChromaticTextReveal
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `prefix` | `string` | — | Yes | Sentence fragment that remains fixed while the final word changes. |
+| `words` | `string[]` | — | Yes | Words revealed one after another after the fixed prefix. |
+| `colors` | `string[]` | `[ "#60a5fa", "#818cf8", "#c084fc", "#fb7185", "#fbbf24", ]` | No | Colors used along the moving chromatic edge. |
+| `foregroundColor` | `string` | `var(--foreground)` | No | Final text color after the sweep passes. |
+| `duration` | `number` | `1.2` | No | Sweep duration in seconds. |
+| `delay` | `number` | `0` | No | Delay before the first sweep, in seconds. |
+| `pauseDuration` | `number` | `0.8` | No | Rest after a word finishes revealing, in seconds. |
+| `loop` | `boolean` | `true` | No | Returns to the first word after the final word. |
+| `startOnView` | `boolean` | `true` | No | Starts when the text enters the viewport. |
+| `once` | `boolean` | `true` | No | Only starts on the first viewport entry. |
+| `inViewMargin` | `MarginType` | — | No | IntersectionObserver root margin used by the viewport trigger. |
+| `className` | `string` | — | No | — |
+
+### TextReveal
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `text` | `string \| string[]` | — | Yes | — |
+| `as` | `ElementType` | `span` | No | — |
+| `className` | `string` | — | No | — |
+| `split` | `"word" \| "char"` | `word` | No | — |
+| `stagger` | `number` | `0.09` | No | — |
+| `delay` | `number` | `0` | No | — |
+| `blur` | `number` | `12` | No | — |
+| `yOffset` | `string \| number` | `40%` | No | — |
+| `spring` | `{ stiffness?: number; damping?: number; mass?: number \| undefined; } \| undefined` | — | No | — |
+| `once` | `boolean` | `true` | No | — |
+| `whileInView` | `boolean` | `false` | No | — |
+
+### TextShimmer
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `as` | `ElementType` | `span` | No | — |
+| `duration` | `number` | `2.5` | No | — |
+| `className` | `string` | — | No | — |
+
+### TextCascade
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `text` | `string` | — | Yes | Current text. Changing it cascades the letters to the new value. |
+| `className` | `string` | — | No | — |
+

package/references/motion/text-swap.md

@@ -0,0 +1,64 @@
+---
+title: "Text Swap"
+description: "Slot-machine vertical ticker transition that rolls text or numbers with subtle blur and spring velocity handoffs."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/text-swap.md"
+markdown: "references/motion/text-swap.md"
+license: "MIT"
+---
+
+# Text Swap
+
+> Slot-machine vertical ticker transition that rolls text or numbers with subtle blur and spring velocity handoffs. Inspired by transitions.dev and ibelick/ui-skills.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py text-swap --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { TextSwap } from "@/components/motion/text-swap";
+import { useState, useEffect } from "react";
+
+const WORDS = ["Developers", "Designers", "Founders", "Teams"];
+
+export function TextSwapExample() {
+  const [index, setIndex] = useState(0);
+
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setIndex((prev) => (prev + 1) % WORDS.length);
+    }, 2000);
+    return () => clearInterval(timer);
+  }, []);
+
+  return (
+    <div className="p-8 text-2xl font-bold">
+      Built for <TextSwap text={WORDS[index]} className="text-primary ml-1.5" />
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `text` | `string \| number` | Required | Content string or number that triggers rolling animation on change. |
+| `direction` | `"up" \| "down"` | `"up"` | Rolling direction. |
+| `className` | `string` | `undefined` | Container classes. |

package/references/motion/theme-toggle.md

@@ -0,0 +1,82 @@
+---
+title: "Theme Toggle"
+description: "Theme toggle button that repaints the whole page through the View Transition API — a rectangle or circle clip-path reveal, or slats that open across the screen like a shutter."
+category: "Components"
+publishedAt: "2026-06-15"
+updatedAt: "2026-06-20"
+documentation: "references/motion/theme-toggle.md"
+markdown: "references/motion/theme-toggle.md"
+license: "MIT"
+---
+
+# Theme Toggle
+
+> Theme toggle button that repaints the whole page through the View Transition API — a rectangle or circle clip-path reveal, or slats that open across the screen like a shutter.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py theme-toggle --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `next-themes`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { ThemeToggle, type ThemeVariant } from "@/components/motion/theme-toggle";
+
+const VARIANTS: { variant: ThemeVariant; label: string }[] = [
+  { variant: "rectangle", label: "Rectangle" },
+  { variant: "circle", label: "Circle" },
+  { variant: "circle-blur", label: "Circle blur" },
+  { variant: "blinds", label: "Blinds" },
+];
+
+export function ThemeTogglePreview() {
+  return (
+    <div className="flex h-full w-full items-center justify-center gap-5">
+      {VARIANTS.map(({ variant, label }) => (
+        <div key={variant} className="flex flex-col items-center gap-2">
+          <ThemeToggle
+            variant={variant}
+            start="bottom-up"
+            className="rounded-xl border border-border bg-background p-2.5"
+            iconClassName="h-5 w-5"
+          />
+          <span className="text-[11px] text-muted-foreground">{label}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### useThemeToggle
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `variant` | `"circle" \| "rectangle" \| "circle-blur" \| "blinds"` | `rectangle` | No | — |
+| `start` | `"center" \| "top-left" \| "top-right" \| "bottom-left" \| "bottom-right" \| "bottom-up"` | `bottom-up` | No | — |
+
+### ThemeToggle
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `variant` | `"circle" \| "rectangle" \| "circle-blur" \| "blinds"` | `rectangle` | No | Animation variant. Default: "rectangle". |
+| `start` | `"center" \| "top-left" \| "top-right" \| "bottom-left" \| "bottom-right" \| "bottom-up"` | `bottom-up` | No | Origin direction for the reveal. Default: "bottom-up". |
+| `iconClassName` | `string` | — | No | — |
+| `className` | `string` | — | No | — |
+

package/references/motion/tilt-card.md

@@ -0,0 +1,59 @@
+---
+title: "Tilt Card"
+description: "3D perspective tilt on hover with cursor-tracked glare."
+category: "Components"
+publishedAt: "2026-05-17"
+updatedAt: "2026-06-22"
+documentation: "references/motion/tilt-card.md"
+markdown: "references/motion/tilt-card.md"
+license: "MIT"
+---
+
+# Tilt Card
+
+> 3D perspective tilt on hover with cursor-tracked glare.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py tilt-card --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { TiltCard } from "@/components/motion/tilt-card";
+
+export function TiltCardPreview() {
+  return (
+    <div className="flex items-center justify-center p-6">
+      <TiltCard className="w-[280px] border border-border bg-card p-8">
+        <div className="text-xs uppercase tracking-wider text-muted-foreground">Premium</div>
+        <h3 className="mt-2 text-2xl font-semibold text-foreground">Tilt me</h3>
+        <p className="mt-3 text-sm text-muted-foreground">Move your cursor across the card to see 3D tilt + glare.</p>
+      </TiltCard>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### TiltCard
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `max` | `number` | `12` | No | — |
+| `glare` | `boolean` | `true` | No | — |
+| `className` | `string` | — | No | — |
+

package/references/motion/timeline.md

@@ -0,0 +1,85 @@
+---
+title: "Timeline"
+description: "Interactive chronological milestone and audit tracker with animated progress lines, status badges, and expandable step disclosures."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/timeline.md"
+markdown: "references/motion/timeline.md"
+license: "MIT"
+---
+
+# Timeline
+
+> Interactive chronological milestone and audit tracker with animated progress lines, status badges, and expandable step disclosures. Inspired by KeenThemes ReUI.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py timeline --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { Timeline, type TimelineItem } from "@/components/motion/timeline";
+import { GitBranch, Rocket, ShieldCheck } from "lucide-react";
+
+const ITEMS: TimelineItem[] = [
+  {
+    id: "step-1",
+    title: "Code Review Approved",
+    description: "2 senior engineers signed off on PR #142 across security and performance checks.",
+    timestamp: "10:45 AM",
+    status: "completed",
+    icon: GitBranch,
+    tags: ["GitHub", "Verified"],
+  },
+  {
+    id: "step-2",
+    title: "Security Sandbox Verification",
+    description: "Running automated SAST scanning and container isolation policy tests.",
+    timestamp: "10:48 AM",
+    status: "current",
+    icon: ShieldCheck,
+    tags: ["In Progress"],
+  },
+  {
+    id: "step-3",
+    title: "Production Deployment",
+    description: "Canary rollout to 10% edge traffic nodes across us-east and eu-west.",
+    timestamp: "Pending",
+    status: "upcoming",
+    icon: Rocket,
+  },
+];
+
+export function TimelineExample() {
+  return (
+    <div className="max-w-md p-6 bg-card rounded-2xl border border-border">
+      <h3 className="text-base font-semibold mb-6">Deployment Pipeline</h3>
+      <Timeline items={ITEMS} />
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `items` | `TimelineItem[]` | required | Array of timeline steps with statuses, icons, timestamps, and tags. |
+| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Directional layout of the timeline stream. |
+| `collapsible` | `boolean` | `true` | Allows clicking on milestone headers to expand or collapse step details. |
+| `className` | `string` | `undefined` | Custom styling overrides merged via `cn()`. |

package/references/motion/toggle-group.md

@@ -0,0 +1,70 @@
+---
+title: "Toggle Group"
+description: "Single or multiple selection button group with active state elevation, icon labels, and tactile spring feedback."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/toggle-group.md"
+markdown: "references/motion/toggle-group.md"
+license: "MIT"
+---
+
+# Toggle Group
+
+> Single or multiple selection button group with active state elevation, icon labels, and tactile spring feedback. Inspired by shadcn/ui and Coss.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py toggle-group --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { ToggleGroup } from "@/components/motion/toggle-group";
+import { AlignCenter, AlignJustify, AlignLeft, AlignRight } from "lucide-react";
+import { useState } from "react";
+
+export function ToggleGroupExample() {
+  const [alignment, setAlignment] = useState("left");
+
+  return (
+    <div className="p-6 bg-card rounded-2xl border border-border inline-block">
+      <ToggleGroup
+        type="single"
+        value={alignment}
+        onChange={setAlignment}
+        items={[
+          { value: "left", icon: <AlignLeft className="size-4" />, ariaLabel: "Align left" },
+          { value: "center", icon: <AlignCenter className="size-4" />, ariaLabel: "Align center" },
+          { value: "right", icon: <AlignRight className="size-4" />, ariaLabel: "Align right" },
+          { value: "justify", icon: <AlignJustify className="size-4" />, ariaLabel: "Justify" },
+        ]}
+      />
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `items` | `ToggleItem[]` | required | Array of toggle button definitions with value, label, icon, and ariaLabel. |
+| `type` | `"single" \| "multiple"` | `"single"` | Selection mode allowing one or multiple active toggles. |
+| `value` | `string \| string[]` | `undefined` | Controlled active value(s). |
+| `onChange` | `(val: any) => void` | `undefined` | Callback emitted on toggle state changes. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Button size tier. |
+| `variant` | `"default" \| "outline"` | `"default"` | Background wrapper visual style. |
+| `className` | `string` | `undefined` | Custom styling overrides merged via `cn()`. |