motion-ui-skill 2.0.0

package/references/agents/image-generation.md

@@ -0,0 +1,173 @@
+---
+title: "Image Generation"
+description: "A stable generated-image surface that moves from queued work through progressive refinement to a completed result without layout shift."
+category: "AI Agents"
+publishedAt: "2026-08-02"
+updatedAt: "2026-08-02"
+documentation: "references/agents/image-generation.md"
+markdown: "references/agents/image-generation.md"
+license: "MIT"
+---
+
+# Image Generation
+
+> A stable generated-image surface that moves from queued work through progressive refinement to a completed result without layout shift.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py image-generation --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { RotateCcw } from "lucide-react";
+import { useReducedMotion } from "motion/react";
+import { useEffect, useState } from "react";
+import {
+  ImageGeneration,
+  type ImageGenerationStatus,
+} from "@/components/agents/image-generation";
+
+function GeneratedArtwork() {
+  return (
+    <svg
+      viewBox="0 0 800 600"
+      aria-hidden="true"
+      className="size-full"
+      preserveAspectRatio="xMidYMid slice"
+    >
+      <defs>
+        <linearGradient id="image-sky" x1="0" y1="0" x2="1" y2="1">
+          <stop offset="0" stopColor="#191b33" />
+          <stop offset="0.48" stopColor="#60538d" />
+          <stop offset="1" stopColor="#e59b7b" />
+        </linearGradient>
+        <linearGradient id="image-ground" x1="0" y1="0" x2="0" y2="1">
+          <stop offset="0" stopColor="#314946" />
+          <stop offset="1" stopColor="#101817" />
+        </linearGradient>
+        <radialGradient id="image-glow">
+          <stop offset="0" stopColor="#ffe6b2" stopOpacity="0.95" />
+          <stop offset="1" stopColor="#efb47e" stopOpacity="0" />
+        </radialGradient>
+      </defs>
+      <rect width="800" height="600" fill="url(#image-sky)" />
+      <circle cx="570" cy="210" r="150" fill="url(#image-glow)" />
+      <circle cx="570" cy="210" r="54" fill="#ffe5ad" />
+      <path
+        d="M0 395 120 314l92 54 132-143 116 126 78-66 92 88 170-61v288H0Z"
+        fill="#283d43"
+        opacity="0.9"
+      />
+      <path
+        d="M0 432 118 376l99 73 115-97 107 92 112-52 108 68 141-48v188H0Z"
+        fill="url(#image-ground)"
+      />
+      <path
+        d="M0 505c116-44 190-32 280 6 103 44 212 47 330-7 68-31 126-37 190-28v124H0Z"
+        fill="#13201f"
+      />
+      <g fill="#c9d7c3" opacity="0.65">
+        <circle cx="108" cy="142" r="2" />
+        <circle cx="168" cy="102" r="1.5" />
+        <circle cx="248" cy="154" r="2" />
+        <circle cx="332" cy="84" r="1.5" />
+        <circle cx="414" cy="138" r="2" />
+      </g>
+    </svg>
+  );
+}
+
+function GenerationDemo({ onReplay }: { onReplay: () => void }) {
+  const reduce = useReducedMotion() ?? false;
+  const [status, setStatus] = useState<ImageGenerationStatus>(
+    reduce ? "complete" : "queued",
+  );
+
+  useEffect(() => {
+    if (reduce) return;
+
+    const timers = [
+      window.setTimeout(() => setStatus("generating"), 500),
+      window.setTimeout(() => setStatus("refining"), 3000),
+      window.setTimeout(() => setStatus("complete"), 5200),
+    ];
+
+    return () => {
+      timers.forEach((timer) => {
+        window.clearTimeout(timer);
+      });
+    };
+  }, [reduce]);
+
+  return (
+    <div className="flex w-full flex-col items-center">
+      <ImageGeneration
+        label="A quiet mountain landscape at sunset"
+        prompt="a quiet mountain landscape at sunset"
+        resolution="1024 × 1024"
+        status={status}
+        onRetry={onReplay}
+      >
+        <GeneratedArtwork />
+      </ImageGeneration>
+      <button
+        type="button"
+        onClick={onReplay}
+        className="mt-4 inline-flex min-h-10 items-center gap-2 rounded-full px-3 text-sm font-medium text-muted-foreground outline-none transition-colors hover:bg-muted hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+      >
+        <RotateCcw aria-hidden="true" className="size-4" />
+        Replay
+      </button>
+    </div>
+  );
+}
+
+export function ImageGenerationPreview() {
+  const [run, setRun] = useState(0);
+
+  return (
+    <div className="w-full max-w-xl">
+      <GenerationDemo
+        key={run}
+        onReplay={() => setRun((value) => value + 1)}
+      />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### ImageGeneration
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `children` | `ReactNode` | — | No | The completed media. Pass an img, Next Image, canvas, video, or custom preview. |
+| `status` | `"error" \| "complete" \| "queued" \| "generating" \| "refining"` | `generating` | No | — |
+| `label` | `string` | — | No | Accessible description. Defaults to a description derived from prompt. |
+| `prompt` | `string` | — | No | — |
+| `resolution` | `string` | `1024 × 1024` | No | — |
+| `aspectRatio` | `AspectRatio` | `1 / 1` | No | CSS aspect ratio reserved before generated media is available. |
+| `size` | `"compact" \| "fluid"` | `compact` | No | — |
+| `interactive` | `boolean` | `true` | No | Lets the active dither cluster follow fine-pointer movement. |
+| `statusText` | `string` | — | No | — |
+| `showStatus` | `boolean` | `true` | No | — |
+| `onRetry` | `(() => void)` | — | No | — |
+| `className` | `string` | — | No | — |
+| `mediaClassName` | `string` | — | No | — |
+| `statusClassName` | `string` | — | No | — |
+

package/references/agents/loading-states.md

@@ -0,0 +1,186 @@
+---
+title: "Agent Loading States"
+description: "Three thoughtful loading states for AI interfaces: shimmering status text, live agent progress, and cycling reasoning phrases."
+category: "AI Agents"
+publishedAt: "2026-07-30"
+updatedAt: "2026-08-19"
+documentation: "references/agents/loading-states.md"
+markdown: "references/agents/loading-states.md"
+license: "MIT"
+---
+
+# Agent Loading States
+
+> Three thoughtful loading states for AI interfaces: shimmering status text, live agent progress, and cycling reasoning phrases.
+
+## Install
+
+### Reasoning Text
+
+Shimmering reasoning copy with an ASCII loader and cascade, phrase-swap, or per-letter scramble transitions.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py reasoning-text --dest ./src
+```
+
+### Thinking Shimmer
+
+A quiet shimmer that keeps the agent's current status readable while work continues.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py thinking-shimmer --dest ./src
+```
+
+### Agent Progress
+
+A compact activity glyph, action verb, and live tabular timer for longer-running agent work.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py agent-progress --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `motion`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+### Reasoning Text usage
+
+Shimmering reasoning copy with an ASCII loader and cascade, phrase-swap, or per-letter scramble transitions.
+
+```tsx
+"use client";
+
+import {
+  ReasoningText,
+  type ReasoningTextVariant,
+} from "@/components/agents/loading-states/reasoning-text";
+
+const EXAMPLES: {
+  label: string;
+  variant: ReasoningTextVariant;
+  phrases: string[];
+}[] = [
+  {
+    label: "Cascade",
+    variant: "cascade",
+    phrases: [
+      "Thinking",
+      "Reading the request",
+      "Working through the details",
+      "Preparing the answer",
+    ],
+  },
+  {
+    label: "Swap",
+    variant: "swap",
+    phrases: [
+      "Thinking",
+      "Reading the request",
+      "Working through the details",
+      "Preparing the answer",
+    ],
+  },
+  {
+    label: "Scramble",
+    variant: "scramble",
+    phrases: ["Thinking", "Searching", "Reasoning", "Composing"],
+  },
+];
+
+export function ReasoningTextPreview() {
+  return (
+    <div className="grid w-full max-w-sm gap-7">
+      {EXAMPLES.map(({ label, variant, phrases }) => (
+        <div key={variant} className="grid gap-2">
+          <span className="text-[11px] font-medium uppercase tracking-wider text-muted-foreground/60">
+            {label}
+          </span>
+          <ReasoningText
+            variant={variant}
+            phrases={phrases}
+            className="text-base"
+          />
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Thinking Shimmer usage
+
+A quiet shimmer that keeps the agent's current status readable while work continues.
+
+```tsx
+"use client";
+
+import { ThinkingShimmer } from "@/components/agents/loading-states/thinking-shimmer";
+
+export function ThinkingShimmerPreview() {
+  return (
+    <ThinkingShimmer className="text-lg" duration={1.8}>
+      Thinking…
+    </ThinkingShimmer>
+  );
+}
+```
+
+### Agent Progress usage
+
+A compact activity glyph, action verb, and live tabular timer for longer-running agent work.
+
+```tsx
+"use client";
+
+import { AgentProgress } from "@/components/agents/loading-states/agent-progress";
+
+export function AgentProgressPreview() {
+  return (
+    <AgentProgress
+      label="Churning"
+      initialSeconds={151.6}
+      className="text-base"
+    />
+  );
+}
+```
+
+## API Reference
+
+### ReasoningText
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `phrases` | `string[]` | `[ "Thinking", "Reading the context", "Connecting the details", "Forming a response", ]` | No | Phrases cycled through while the agent works. |
+| `variant` | `"scramble" \| "cascade" \| "swap"` | `cascade` | No | Animation used when the active phrase changes. |
+| `interval` | `number` | `1800` | No | Milliseconds each phrase remains visible. |
+| `shimmerDuration` | `number` | `2.2` | No | Seconds taken for one shimmer pass. |
+| `indicator` | `ReactNode` | — | No | Optional leading visual. Defaults to a terminal-style ASCII loader. |
+| `className` | `string` | — | No | — |
+
+### ThinkingShimmer
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `children` | `ReactNode` | `Thinking…` | No | Loading message shown to the user. |
+| `duration` | `number` | `1.8` | No | Seconds taken for one shimmer pass. |
+| `className` | `string` | — | No | — |
+
+### AgentProgress
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `string` | `Churning` | No | Verb describing the agent's current activity. |
+| `elapsedSeconds` | `number` | — | No | Controlled elapsed time in seconds. |
+| `initialSeconds` | `number` | `0` | No | Starting time for the internal timer, in seconds. |
+| `running` | `boolean` | `true` | No | Whether the internal timer should advance. Ignored when elapsedSeconds is provided. |
+| `className` | `string` | — | No | — |
+

package/references/agents/message-bubble.md

@@ -0,0 +1,274 @@
+---
+title: "Message Bubble"
+description: "A focused conversational surface with visual tones, independent alignment, grouped messages, expandable content, and interactive link or button support."
+category: "AI Agents"
+publishedAt: "2026-08-02"
+updatedAt: "2026-08-02"
+documentation: "references/agents/message-bubble.md"
+markdown: "references/agents/message-bubble.md"
+license: "MIT"
+---
+
+# Message Bubble
+
+> A focused conversational surface with visual tones, independent alignment, grouped messages, expandable content, and interactive link or button support.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py message-bubble --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `react-dom`
+- `tailwind-merge`
+
+## Usage
+
+### Animated Surfaces usage
+
+An interactive conversation where each newly sent user row pops up once while the assistant streams into a stable row.
+
+```tsx
+"use client";
+
+import { ChatPreview } from "@/components/previews/agents/chat-preview";
+
+export function MessageBubblePreview() {
+  return (
+    <ChatPreview
+      reply="That message mounted once with a spring pop. Streaming updates only change its content, so the entrance does not replay."
+      placeholder="Send a bubble…"
+    />
+  );
+}
+```
+
+### With Avatars usage
+
+Progressively arriving messages with sender avatars, metadata, delivery state, and grouped follow-up alignment.
+
+```tsx
+"use client";
+
+import { Bot, RotateCcw, User } from "lucide-react";
+import { AnimatePresence } from "motion/react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  MessageBubble,
+  MessageBubbleContent,
+} from "@/components/agents/message-bubble";
+import {
+  Message,
+  MessageAvatar,
+  MessageContent,
+  MessageFooter,
+  MessageGroup,
+  MessageHeader,
+} from "@/components/agents/message";
+import { StreamingResponse } from "@/components/agents/streaming-response";
+
+export function MessageBubbleAvatarsPreview() {
+  const timer = useRef<number | undefined>(undefined);
+  const [run, setRun] = useState(0);
+  const [step, setStep] = useState(0);
+
+  const replay = useCallback(() => {
+    if (timer.current) window.clearTimeout(timer.current);
+    setStep(0);
+    setRun((value) => value + 1);
+  }, []);
+
+  useEffect(() => {
+    if (step >= 2) return;
+    timer.current = window.setTimeout(
+      () => setStep((value) => value + 1),
+      step === 0 ? 650 : 900,
+    );
+    return () => {
+      if (timer.current) window.clearTimeout(timer.current);
+    };
+  }, [step]);
+
+  return (
+    <div className="flex h-[410px] w-full max-w-xl flex-col justify-center px-3">
+      <MessageGroup key={run} spacing="default">
+        <Message from="user">
+          <MessageAvatar className="bg-foreground text-background">
+            <User />
+          </MessageAvatar>
+          <MessageContent>
+            <MessageHeader>
+              <span className="font-medium text-foreground/70">You</span>
+              <span>Now</span>
+            </MessageHeader>
+            <MessageBubble variant="solid">
+              <MessageBubbleContent>
+                Can you turn these notes into a launch update?
+              </MessageBubbleContent>
+            </MessageBubble>
+            <MessageFooter>Delivered</MessageFooter>
+          </MessageContent>
+        </Message>
+
+        <AnimatePresence mode="popLayout">
+          {step >= 1 ? (
+            <Message key="draft" from="assistant">
+              <MessageAvatar>
+                <Bot />
+              </MessageAvatar>
+              <MessageContent>
+                <MessageHeader>
+                  <span className="font-medium text-foreground/70">Assistant</span>
+                  <span>Just now</span>
+                </MessageHeader>
+                <MessageBubble variant="soft">
+                  <MessageBubbleContent>
+                    <StreamingResponse status="complete" showActions={false}>
+                      Absolutely. I’ll keep it concise and lead with what changed.
+                    </StreamingResponse>
+                  </MessageBubbleContent>
+                </MessageBubble>
+              </MessageContent>
+            </Message>
+          ) : null}
+
+          {step >= 2 ? (
+            <Message key="follow-up" from="assistant">
+              <MessageAvatar placeholder />
+              <MessageContent>
+                <MessageBubble variant="soft">
+                  <MessageBubbleContent>
+                    <StreamingResponse status="complete" showActions={false}>
+                      Do you want the tone to feel more technical or more customer-facing?
+                    </StreamingResponse>
+                  </MessageBubbleContent>
+                </MessageBubble>
+              </MessageContent>
+            </Message>
+          ) : null}
+        </AnimatePresence>
+      </MessageGroup>
+
+      <div className="flex h-11 items-end justify-center">
+        <button
+          type="button"
+          onClick={replay}
+          className="inline-flex h-8 items-center gap-1.5 rounded-full border border-border px-3 text-xs font-medium text-muted-foreground outline-none transition-colors hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          <RotateCcw className="size-3.5" />
+          Replay
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+### Show More usage
+
+A long assistant message with a compact line-clamped preview and animated disclosure control.
+
+```tsx
+"use client";
+
+import { Bot } from "lucide-react";
+import {
+  MessageBubble,
+  MessageBubbleCollapsible,
+  MessageBubbleContent,
+} from "@/components/agents/message-bubble";
+import {
+  Message,
+  MessageAvatar,
+  MessageContent,
+  MessageHeader,
+} from "@/components/agents/message";
+import { StreamingResponse } from "@/components/agents/streaming-response";
+
+export function MessageBubbleCollapsiblePreview() {
+  return (
+    <div className="flex h-[410px] w-full max-w-xl items-start px-3 pt-14">
+      <Message from="assistant">
+        <MessageAvatar>
+          <Bot />
+        </MessageAvatar>
+        <MessageContent>
+          <MessageHeader>
+            <span className="font-medium text-foreground/70">Assistant</span>
+            <span>Summary</span>
+          </MessageHeader>
+          <MessageBubble variant="soft" animateIn={false}>
+            <MessageBubbleContent className="max-w-[90%]">
+              <StreamingResponse status="complete" showActions={false}>
+                <MessageBubbleCollapsible collapsedLines={4}>
+                  <p>
+                    The release is ready for a focused rollout. The main conversation flow,
+                    keyboard navigation, error recovery, and reduced-motion behavior are all
+                    covered.
+                  </p>
+                  <p>
+                    I would keep advanced workflow controls out of this version. They add
+                    configuration without improving the first-run experience, and the usage
+                    data from this release will give us a better basis for those decisions.
+                  </p>
+                  <p>
+                    Before publishing, run the accessibility suite once more and verify the
+                    streaming behavior with a long response on a smaller viewport.
+                  </p>
+                </MessageBubbleCollapsible>
+              </StreamingResponse>
+            </MessageBubbleContent>
+          </MessageBubble>
+        </MessageContent>
+      </Message>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### MessageBubble
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `variant` | `"outline" \| "solid" \| "danger" \| "ghost" \| "soft" \| "tint"` | `soft` | No | — |
+| `align` | `"end" \| "start"` | — | No | Defaults to the surrounding Message alignment when omitted. |
+| `animateIn` | `boolean` | `false` | No | Plays the bubble entrance once when this component mounts. |
+| `className` | `string` | — | No | — |
+
+### MessageBubbleContent
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `render` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | — | No | Replaces the content element while preserving bubble styling. |
+| `className` | `string` | — | No | — |
+
+### MessageBubbleGroup
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `spacing` | `"default" \| "compact"` | `compact` | No | — |
+| `className` | `string` | — | No | — |
+
+### MessageBubbleCollapsible
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | — | No | — |
+| `defaultOpen` | `boolean` | `false` | No | — |
+| `onOpenChange` | `((open: boolean) => void)` | — | No | — |
+| `collapsedLines` | `2 \| 3 \| 4 \| 5 \| 6` | `4` | No | — |
+| `moreLabel` | `ReactNode` | `Show more` | No | — |
+| `lessLabel` | `ReactNode` | `Show less` | No | — |
+| `contentClassName` | `string` | — | No | — |
+| `triggerClassName` | `string` | — | No | — |
+| `className` | `string` | — | No | — |
+