motion-ui-skill 2.0.0

package/references/motion/progress-ring.md

@@ -0,0 +1,73 @@
+---
+title: "Progress Ring"
+description: "Circular animated SVG progress ring with critically damped spring fill tracking, percentage counters, and status variants."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/progress-ring.md"
+markdown: "references/motion/progress-ring.md"
+license: "MIT"
+---
+
+# Progress Ring
+
+> Circular animated SVG progress ring with critically damped spring fill tracking, percentage counters, and status variants. Inspired by Expo and Motion.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py progress-ring --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { ProgressRing } from "@/components/motion/progress-ring";
+import { useState } from "react";
+
+export function ProgressRingExample() {
+  const [progress, setProgress] = useState(68);
+
+  return (
+    <div className="flex flex-col items-center gap-4 p-8 bg-card rounded-2xl border border-border">
+      <ProgressRing value={progress} size="lg" status="default" />
+      <div className="flex gap-2">
+        <button
+          onClick={() => setProgress(Math.max(0, progress - 15))}
+          className="px-3 py-1 text-xs rounded-lg border border-border"
+        >
+          -15%
+        </button>
+        <button
+          onClick={() => setProgress(Math.min(100, progress + 15))}
+          className="px-3 py-1 text-xs rounded-lg bg-primary text-primary-foreground font-semibold"
+        >
+          +15%
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `value` | `number` | required | Progress completion percentage between 0 and 100. |
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Ring diameter scale. |
+| `strokeWidth` | `number` | `undefined` | Optional override for SVG stroke width. |
+| `showValue` | `boolean` | `true` | Renders percentage text inside center. |
+| `status` | `"default" \| "success" \| "warning" \| "destructive"` | `"default"` | Stroke color theme. |
+| `children` | `ReactNode` | `undefined` | Custom center element overriding percentage text. |
+| `className` | `string` | `undefined` | Custom styling overrides merged via `cn()`. |

package/references/motion/pull-to-refresh.md

@@ -0,0 +1,172 @@
+---
+title: "Pull to Refresh"
+description: "Native-feeling pull-to-refresh container with drag resistance, threshold feedback and async refresh handling."
+category: "Components"
+publishedAt: "2026-07-17"
+updatedAt: "2026-07-17"
+documentation: "references/motion/pull-to-refresh.md"
+markdown: "references/motion/pull-to-refresh.md"
+license: "MIT"
+---
+
+# Pull to Refresh
+
+> Native-feeling pull-to-refresh container with drag resistance, threshold feedback and async refresh handling.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py pull-to-refresh --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { Bell, CheckCircle2, GitPullRequest, MessageCircle } from "lucide-react";
+import { useState } from "react";
+import { PullToRefresh } from "@/components/motion/pull-to-refresh";
+
+const initialUpdates = [
+  {
+    id: 1,
+    icon: GitPullRequest,
+    title: "Motion review approved",
+    detail: "The pull request is ready to merge.",
+    time: "4m",
+  },
+  {
+    id: 2,
+    icon: MessageCircle,
+    title: "New component feedback",
+    detail: "The spring feels much closer to native now.",
+    time: "18m",
+  },
+  {
+    id: 3,
+    icon: CheckCircle2,
+    title: "Registry checks passed",
+    detail: "All component files resolved successfully.",
+    time: "31m",
+  },
+  {
+    id: 4,
+    icon: Bell,
+    title: "Preview deployed",
+    detail: "The latest build is ready to inspect.",
+    time: "1h",
+  },
+  {
+    id: 5,
+    icon: MessageCircle,
+    title: "Docs comment resolved",
+    detail: "The usage example now covers async refreshes.",
+    time: "2h",
+  },
+] as const;
+
+export function PullToRefreshPreview() {
+  const [refreshCount, setRefreshCount] = useState(0);
+  const [latestUpdate, setLatestUpdate] = useState<number | null>(null);
+
+  const updates = latestUpdate
+    ? [
+        {
+          id: latestUpdate,
+          icon: Bell,
+          title: "You’re all caught up",
+          detail: "The activity feed was refreshed just now.",
+          time: "now",
+        },
+        ...initialUpdates,
+      ]
+    : initialUpdates;
+
+  return (
+    <div className="flex min-h-[34rem] w-full items-center justify-center p-4">
+      <div className="w-full max-w-sm overflow-hidden rounded-[2rem] border border-border bg-background shadow-2xl">
+        <PullToRefresh
+          ariaLabel="Activity feed"
+          className="h-[30rem]"
+          onRefresh={async () => {
+            await new Promise((resolve) => setTimeout(resolve, 900));
+            const next = refreshCount + 1;
+            setRefreshCount(next);
+            setLatestUpdate(Date.now());
+          }}
+        >
+          <header className="sticky top-0 z-10 flex items-center justify-between border-b border-border bg-background/90 px-5 py-4 backdrop-blur-md">
+            <div>
+              <p className="font-semibold text-foreground">Activity</p>
+              <p className="text-xs text-muted-foreground">
+                Pull down to check for updates
+              </p>
+            </div>
+            <span className="rounded-full bg-muted px-2.5 py-1 font-mono text-[10px] text-muted-foreground">
+              {refreshCount ? `${refreshCount} refreshed` : "live"}
+            </span>
+          </header>
+
+          <div className="divide-y divide-border px-2 pb-3">
+            {updates.map((update) => {
+              const Icon = update.icon;
+
+              return (
+                <article key={update.id} className="flex gap-3 px-3 py-4">
+                  <div className="grid h-9 w-9 shrink-0 place-items-center rounded-xl border border-border bg-card text-muted-foreground shadow-sm">
+                    <Icon className="h-4 w-4" />
+                  </div>
+                  <div className="min-w-0 flex-1">
+                    <div className="flex items-start justify-between gap-3">
+                      <p className="text-sm font-medium text-foreground">
+                        {update.title}
+                      </p>
+                      <span className="shrink-0 font-mono text-[10px] text-muted-foreground">
+                        {update.time}
+                      </span>
+                    </div>
+                    <p className="mt-1 text-xs leading-relaxed text-muted-foreground">
+                      {update.detail}
+                    </p>
+                  </div>
+                </article>
+              );
+            })}
+          </div>
+        </PullToRefresh>
+      </div>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### PullToRefresh
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `onRefresh` | `() => void \| Promise<void>` | — | Yes | Runs after the user pulls beyond the threshold and releases. |
+| `refreshing` | `boolean` | `false` | No | Keeps the indicator active while an externally managed refresh runs. |
+| `disabled` | `boolean` | `false` | No | — |
+| `threshold` | `number` | `76` | No | Resisted pull distance in pixels required to refresh. |
+| `maxPull` | `number` | `132` | No | Maximum resisted pull distance in pixels. |
+| `holdDistance` | `number` | `68` | No | Content offset in pixels while refreshing. |
+| `pullingLabel` | `ReactNode` | `Pull to refresh` | No | — |
+| `releaseLabel` | `ReactNode` | `Release to refresh` | No | — |
+| `refreshingLabel` | `ReactNode` | `Refreshing` | No | — |
+| `ariaLabel` | `string` | `Refreshable content` | No | — |
+| `className` | `string` | — | No | — |
+| `contentClassName` | `string` | — | No | — |
+| `indicatorClassName` | `string` | — | No | — |
+

package/references/motion/radio.md

@@ -0,0 +1,73 @@
+---
+title: "Radio Group"
+description: "Single-select choice control with a gliding layoutId indicator dot and spring press feedback."
+category: "Components"
+publishedAt: "2026-06-23"
+updatedAt: "2026-07-13"
+documentation: "references/motion/radio.md"
+markdown: "references/motion/radio.md"
+license: "MIT"
+---
+
+# Radio Group
+
+> Single-select choice control with a gliding layoutId indicator dot and spring press feedback.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py radio --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { RadioGroup, RadioGroupItem } from "@/components/motion/radio";
+
+export function RadioPreview() {
+  const [plan, setPlan] = useState("pro");
+
+  return (
+    <RadioGroup value={plan} onValueChange={setPlan} className="min-w-48">
+      <RadioGroupItem value="starter" label="Starter — free" />
+      <RadioGroupItem value="pro" label="Pro — $12/mo" />
+      <RadioGroupItem value="team" label="Team — $29/mo" />
+      <RadioGroupItem value="legacy" label="Legacy plan" disabled />
+    </RadioGroup>
+  );
+}
+```
+
+## API Reference
+
+### RadioGroup
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | No | — |
+| `defaultValue` | `string` | — | No | — |
+| `onValueChange` | `((value: string) => void)` | — | No | — |
+| `className` | `string` | — | No | — |
+| `orientation` | `"horizontal" \| "vertical"` | `vertical` | No | — |
+
+### RadioGroupItem
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | Yes | — |
+| `label` | `string` | — | No | — |
+| `disabled` | `boolean` | — | No | — |
+| `className` | `string` | — | No | — |
+| `id` | `string` | — | No | — |
+

package/references/motion/range-slider.md

@@ -0,0 +1,290 @@
+---
+title: "Range Slider"
+description: "Slider with tick dots and a vertical-bar thumb that bounces as it lands on each step. Drag or keyboard, reduced-motion safe."
+category: "Components"
+publishedAt: "2026-06-24"
+updatedAt: "2026-07-31"
+documentation: "references/motion/range-slider.md"
+markdown: "references/motion/range-slider.md"
+license: "MIT"
+---
+
+# Range Slider
+
+> Slider with tick dots and a vertical-bar thumb that bounces as it lands on each step. Drag or keyboard, reduced-motion safe.
+
+## Install
+
+### Range Slider
+
+Tick dots, and a vertical-bar thumb that bounces as it lands on each step.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py range-slider --dest ./src
+```
+
+### Fluid Slider
+
+No thumb. The fill slides behind a rounded liquid cap, and the label flips color wherever the fill covers it.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py range-slider-fluid --dest ./src
+```
+
+### Wave Slider
+
+Equalizer bars peak around the handle and drop back once it passes, so the value moves down the track as a wave.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py range-slider-wave --dest ./src
+```
+
+### Bubble Slider
+
+Grab the thumb and a value bubble pops out of it. The bubble tilts and squashes with how fast you drag, then settles upright.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py range-slider-bubble --dest ./src
+```
+
+### Ruler Slider
+
+The needle stays put and the scale scrolls under it. A flick keeps going and settles on the nearest tick. Fractional steps read at the step's own precision.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py range-slider-ruler --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+### Range Slider usage
+
+Tick dots, and a vertical-bar thumb that bounces as it lands on each step.
+
+```tsx
+"use client";
+
+import { useState } from "react";
+
+import { RangeSlider } from "@/components/motion/range-slider";
+
+export function RangeSliderPreview() {
+  const [value, setValue] = useState(40);
+
+  return (
+    <div className="flex w-full max-w-sm flex-col gap-3">
+      <div className="flex items-center justify-between text-sm text-muted-foreground">
+        <span>Drag the handle</span>
+        <span className="tabular-nums text-foreground">{value}</span>
+      </div>
+      <RangeSlider value={value} onValueChange={setValue} step={5} aria-label="Value" />
+    </div>
+  );
+}
+```
+
+### Fluid Slider usage
+
+No thumb. The fill slides behind a rounded liquid cap, and the label flips color wherever the fill covers it.
+
+```tsx
+"use client";
+
+import { useState } from "react";
+
+import { FluidSlider } from "@/components/motion/range-slider-fluid";
+
+export function RangeSliderFluidPreview() {
+  const [value, setValue] = useState(35);
+
+  return (
+    <div className="w-full max-w-sm">
+      <FluidSlider
+        value={value}
+        onValueChange={setValue}
+        label="Brightness"
+        aria-label="Brightness"
+      />
+    </div>
+  );
+}
+```
+
+### Wave Slider usage
+
+Equalizer bars peak around the handle and drop back once it passes, so the value moves down the track as a wave.
+
+```tsx
+"use client";
+
+import { useState } from "react";
+
+import { WaveSlider } from "@/components/motion/range-slider-wave";
+
+export function RangeSliderWavePreview() {
+  const [value, setValue] = useState(45);
+
+  return (
+    <div className="flex w-full max-w-md flex-col gap-2">
+      <div className="flex items-center justify-between text-sm text-muted-foreground">
+        <span>Gain</span>
+        <span className="tabular-nums text-foreground">{value}</span>
+      </div>
+      <WaveSlider value={value} onValueChange={setValue} aria-label="Gain" />
+    </div>
+  );
+}
+```
+
+### Bubble Slider usage
+
+Grab the thumb and a value bubble pops out of it. The bubble tilts and squashes with how fast you drag, then settles upright.
+
+```tsx
+"use client";
+
+import { useState } from "react";
+
+import { BubbleSlider } from "@/components/motion/range-slider-bubble";
+
+export function RangeSliderBubblePreview() {
+  const [value, setValue] = useState(28);
+
+  return (
+    <div className="flex w-full max-w-sm flex-col gap-1">
+      <span className="text-sm text-muted-foreground">Drag fast and the bubble leans</span>
+      <BubbleSlider value={value} onValueChange={setValue} aria-label="Value" />
+    </div>
+  );
+}
+```
+
+### Ruler Slider usage
+
+The needle stays put and the scale scrolls under it. A flick keeps going and settles on the nearest tick. Fractional steps read at the step's own precision.
+
+```tsx
+"use client";
+
+import { useState } from "react";
+
+import { RulerSlider } from "@/components/motion/range-slider-ruler";
+
+export function RangeSliderRulerPreview() {
+  const [value, setValue] = useState(72.5);
+
+  return (
+    <div className="w-full max-w-sm">
+      <RulerSlider
+        value={value}
+        onValueChange={setValue}
+        min={40}
+        max={120}
+        step={0.5}
+        gap={12}
+        majorEvery={10}
+        unit="kg"
+        aria-label="Weight"
+      />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### RangeSlider
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `showTicks` | `boolean` | `true` | No | Render a tick dot at each step. |
+| `className` | `string` | — | No | — |
+| `value` | `number` | — | No | — |
+| `defaultValue` | `number` | — | No | — |
+| `onValueChange` | `((value: number) => void)` | — | No | — |
+| `min` | `number` | — | No | — |
+| `max` | `number` | — | No | — |
+| `step` | `number` | — | No | — |
+| `disabled` | `boolean` | — | No | — |
+| `aria-label` | `string` | — | No | — |
+| `formatValueText` | `((value: number) => string)` | — | No | Announced instead of the raw number — pass one when the value carries a unit or a suffix ("72.5 kg", "35%"); a bare number needs no valueText. |
+
+### FluidSlider
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `string` | — | No | Text shown on the left of the track. |
+| `format` | `((value: number) => string)` | `(v) => `${v}%`` | No | Formats the value shown on the right. |
+| `className` | `string` | — | No | — |
+| `value` | `number` | — | No | — |
+| `defaultValue` | `number` | — | No | — |
+| `onValueChange` | `((value: number) => void)` | — | No | — |
+| `min` | `number` | — | No | — |
+| `max` | `number` | — | No | — |
+| `step` | `number` | — | No | — |
+| `disabled` | `boolean` | — | No | — |
+| `aria-label` | `string` | — | No | — |
+| `formatValueText` | `((value: number) => string)` | — | No | Announced instead of the raw number — pass one when the value carries a unit or a suffix ("72.5 kg", "35%"); a bare number needs no valueText. |
+
+### WaveSlider
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `bars` | `number` | `32` | No | Number of bars drawn across the track. |
+| `className` | `string` | — | No | — |
+| `value` | `number` | — | No | — |
+| `defaultValue` | `number` | — | No | — |
+| `onValueChange` | `((value: number) => void)` | — | No | — |
+| `min` | `number` | — | No | — |
+| `max` | `number` | — | No | — |
+| `step` | `number` | — | No | — |
+| `disabled` | `boolean` | — | No | — |
+| `aria-label` | `string` | — | No | — |
+| `formatValueText` | `((value: number) => string)` | — | No | Announced instead of the raw number — pass one when the value carries a unit or a suffix ("72.5 kg", "35%"); a bare number needs no valueText. |
+
+### BubbleSlider
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `format` | `((value: number) => string)` | — | No | Formats the value shown in the bubble. |
+| `className` | `string` | — | No | — |
+| `value` | `number` | — | No | — |
+| `defaultValue` | `number` | — | No | — |
+| `onValueChange` | `((value: number) => void)` | — | No | — |
+| `min` | `number` | — | No | — |
+| `max` | `number` | — | No | — |
+| `step` | `number` | — | No | — |
+| `disabled` | `boolean` | — | No | — |
+| `aria-label` | `string` | — | No | — |
+| `formatValueText` | `((value: number) => string)` | — | No | Announced instead of the raw number — pass one when the value carries a unit or a suffix ("72.5 kg", "35%"); a bare number needs no valueText. |
+
+### RulerSlider
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `gap` | `number` | `14` | No | Pixels between two steps. |
+| `majorEvery` | `number` | `5` | No | Label every Nth step; those ticks are drawn tall. |
+| `unit` | `string` | — | No | Unit shown next to the value. |
+| `className` | `string` | — | No | — |
+| `value` | `number` | — | No | — |
+| `defaultValue` | `number` | — | No | — |
+| `onValueChange` | `((value: number) => void)` | — | No | — |
+| `min` | `number` | — | No | — |
+| `max` | `number` | — | No | — |
+| `step` | `number` | — | No | — |
+| `disabled` | `boolean` | — | No | — |
+| `aria-label` | `string` | — | No | — |
+| `formatValueText` | `((value: number) => string)` | — | No | Announced instead of the raw number — pass one when the value carries a unit or a suffix ("72.5 kg", "35%"); a bare number needs no valueText. |
+

package/references/motion/rating.md

@@ -0,0 +1,69 @@
+---
+title: "Rating"
+description: "Interactive star rating component with half-star fractional hover detection, spring bounce micro-interactions on click, and keyboard accessibility."
+category: "Components"
+publishedAt: "2026-09-05"
+updatedAt: "2026-09-05"
+documentation: "references/motion/rating.md"
+markdown: "references/motion/rating.md"
+license: "MIT"
+---
+
+# Rating
+
+> Interactive star rating component with half-star fractional hover detection, spring bounce micro-interactions on click, and keyboard accessibility. Inspired by KeenThemes ReUI and Transitions.dev.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py rating --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { Rating } from "@/components/motion/rating";
+import { useState } from "react";
+
+export function RatingExample() {
+  const [score, setScore] = useState(4.5);
+
+  return (
+    <div className="flex flex-col gap-4 p-6 bg-card rounded-2xl border border-border max-w-sm">
+      <h3 className="text-sm font-semibold">User Experience Rating</h3>
+      <Rating
+        value={score}
+        allowHalf={true}
+        size="md"
+        onChange={(val) => setScore(val)}
+      />
+      <p className="text-xs text-muted-foreground">Current rating: {score} stars</p>
+    </div>
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `value` | `number` | `undefined` | Controlled rating score value. |
+| `defaultValue` | `number` | `0` | Uncontrolled default rating score. |
+| `max` | `number` | `5` | Maximum number of rating stars. |
+| `allowHalf` | `boolean` | `true` | Enables half-star fractional rating increments. |
+| `readOnly` | `boolean` | `false` | Disables user interaction for display-only scorecards. |
+| `disabled` | `boolean` | `false` | Visual disabled state. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Star dimension scale. |
+| `onChange` | `(val: number) => void` | `undefined` | Callback fired when the score changes. |
+| `className` | `string` | `undefined` | Custom styling overrides merged via `cn()`. |