Production-ready animations, transitions, backgrounds, and scenes for Remotion
TypeScript ai-agentsclaude-codedemo-videomcpmcp-servermodel-context-protocolmotion-designproduct-demoreactremotionshadcnvideo
feat: gate the registry-docs contract in CI
kapishdima635038f3aecd
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 61ea79dd..d029af3c 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -20,6 +20,9 @@ jobs:# PR #61 (12 remocn-ui suites + 2 real source bugs) are fixed.- run: bun run testcontinue-on-error: true+ # Blocking on its own, because the suite above is not. Guards the+ # registry <-> docs contract the remocn skill reads at runtime.+ - run: bun test lib/docs-meta.test.ts- run: bun run registry:checkbuild:diff --git a/CLAUDE.md b/CLAUDE.mdindex d60d8029..4956c6cd 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -35,6 +35,17 @@ Solo builders и маленькие команды (1-2 чел), фронтен- Превью на сайте через `@remotion/player` — интерактивный плеер в браузере- Лицензия: MIT+## Документация — источник правды для агентов++Доки описывают компоненты и для людей, и для AI-агентов. Скилл `remocn` не хранит свою копию каталога, а читает документацию по URL, поэтому страница компонента — единственное место, где живут его пропсы, пример и сигнал выбора.++- Каждый item из трёх `registry.json` обязан иметь страницу с `component: <name>` во frontmatter. Исключения перечислены в `UNDOCUMENTED` в `lib/docs-meta.test.ts` и требуют причины — это либы, внутренние примитивы и sub-item'ы, свёрнутые в страницу контейнера. Иконки документируются галереей, а не страницей на штуку+- Frontmatter компонента: `component`, `vibe` (одно из семи значений в `lib/docs-schema.ts`), `length`, `useWhen` и `avoidWhen` — списки строк в двойных кавычках. Поля машинные, на странице не рендерятся+- `length` — кадры **собственного движения** компонента при 30fps: у перехода это значение для `linearTiming`/`springTiming`, у остальных — момент, когда анимация закончилась. Это нижняя граница `Sequence`, а не длина бита: холд сверху добавляется отдельно. Поэтому `length` намеренно расходится с `durationInFrames` в `config.ts` — там длина демо-композиции вместе с холдом. `"state-driven"` — компонент рендерится из пропа `state` и своей длительности не имеет+- В `avoidWhen` называй компонент-замену в бэктиках. Тест валит сборку, если такого имени нет в registry+- `bun test lib/docs-meta.test.ts` — блокирующий шаг CI, отдельный от основного прогона тестов (тот пока `continue-on-error`)+- Агентские артефакты генерируются из этого frontmatter: `/llms-components.txt` (роутер по всем компонентам) и `/docs/**.md` (страница как чистый markdown, см. `lib/mdx-to-markdown.ts`)+## ChangelogЛюбая ветка, которая добавляет или заметно меняет компоненты registry, обязана содержать запись ченджлога — в том же PR, что и сама фича.diff --git a/app/llms-components.txt/route.ts b/app/llms-components.txt/route.tsindex d2a4c56b..a2d633d3 100644--- a/app/llms-components.txt/route.ts+++ b/app/llms-components.txt/route.ts@@ -54,7 +54,11 @@ export function GET() {"Install any entry: `npx shadcn@latest add @remocn/<name>` (lands in `components/remocn/`;","`registryDependencies` install transitively).","",- "`Length` is the component's natural duration at 30fps — budget its `Sequence` accordingly.",+ "`Length` is how many frames of motion the component itself runs at 30fps — for a transition it",+ "is the value to pass to `linearTiming` / `springTiming`, for everything else it is the point at",+ "which the animation has finished. It is a floor for the `Sequence`, not the whole beat: add hold",+ "time on top when the element should stay on screen after it settles. `state-driven` means the",+ "component renders purely from its `state` prop and has no duration of its own.","`Vibe` is the tonal tag; match it to the brand rather than mixing freely.",];diff --git a/content/changelog/2026-07-25-docs-for-agents.mdx b/content/changelog/2026-07-25-docs-for-agents.mdxindex 9bd16386..2f77bfa6 100644--- a/content/changelog/2026-07-25-docs-for-agents.mdx+++ b/content/changelog/2026-07-25-docs-for-agents.mdx@@ -22,6 +22,8 @@ Six components were installable from the registry but had no documentation. They- [Field](/docs/ui/components/field) — the static layout family for labeled form controls- [Skeleton Block](/docs/ui/components/skeleton-block) — the single shimmer rectangle underneath`skeleton`+- [Chat to Preview Layout](/docs/layout/chat-to-preview-layout) — a two-column split where the chat+ column shrinks as the preview expands<ChangelogPreview name="simulated-cursor" />@@ -45,3 +47,8 @@ Six components were installable from the registry but had no documentation. Theyin one table with its use and avoid signal, natural length, vibe, tier and dependencies, linkingto each component's full page. It is the entry point for an agent picking components for a scene.- [`/llms.txt`](https://remocn.dev/llms.txt) points at the new component index.+- Every component page now carries that selection metadata, so the index covers the whole catalogue+ rather than a sample of it.+- CI now fails when a registry component has no docs page, when a page is missing its metadata, or+ when a page recommends a component that does not exist. The catalogue had drifted silently before+ this: ten shipped components were missing from the agent's view entirely.diff --git a/content/docs/ai/chat-gpt.mdx b/content/docs/ai/chat-gpt.mdxindex 86c10f70..bc1500f0 100644--- a/content/docs/ai/chat-gpt.mdx+++ b/content/docs/ai/chat-gpt.mdx@@ -1,6 +1,17 @@---title: ChatGPTdescription: Animated ChatGPT composer that types a prompt and morphs the voice button into a send button+component: chat-gpt+vibe: tech+length: 150+useWhen:+ - "Announcing a ChatGPT integration or GPT-powered feature where the OpenAI brand must be recognizable."+ - "Showing a prompt-to-result workflow where the ChatGPT interface is the entry point."+ - "A comparison video contrasts multiple AI products — use this for the ChatGPT card, `claude-chat` for Claude."+avoidWhen:+ - "The product being demoed is Claude — use `claude-chat` instead to match Anthropic's UI and warm color palette."+ - "The product is Vercel's v0 — use `v0` instead, which replicates the v0 dark textarea and mic-to-send morph."+ - "The product is a CLI/terminal AI agent — use `claude-code` or `opencode` instead."---<ComponentPreview name="chat-gpt" />diff --git a/content/docs/ai/claude-chat.mdx b/content/docs/ai/claude-chat.mdxindex 2d7a74c4..baeed470 100644--- a/content/docs/ai/claude-chat.mdx+++ b/content/docs/ai/claude-chat.mdx@@ -1,6 +1,17 @@---title: Claude Chatdescription: Animated Claude chat input that types a prompt and morphs the waveform button into a send button+component: claude-chat+vibe: tech+length: 150+useWhen:+ - "Announcing a Claude integration or Anthropic-powered feature where the Claude brand must be visible."+ - "Showcasing a prompt workflow where claude.ai is the UI surface — the warm terracotta accent is the brand signal."+ - "A multi-AI comparison video needs the Claude card alongside `chat-gpt` and `v0`."+avoidWhen:+ - "The product is Claude Code CLI — use `claude-code` instead, which shows the terminal welcome screen with `cwd` and agent context."+ - "The product is ChatGPT — use `chat-gpt` instead for the correct pill-input and blue accent."+ - "The integration is with OpenCode's TUI — use `opencode` instead."---<ComponentPreview name="claude-chat" />diff --git a/content/docs/ai/claude-code.mdx b/content/docs/ai/claude-code.mdxindex 71bc0613..875d955d 100644--- a/content/docs/ai/claude-code.mdx+++ b/content/docs/ai/claude-code.mdx@@ -1,6 +1,17 @@---title: Claude Codedescription: Animated Claude Code CLI welcome screen that types a command into the terminal prompt+component: claude-code+vibe: tech+length: 160+useWhen:+ - "Depicting a Claude Code / agentic-CLI workflow as a recognizable branded surface in a dev-tool demo."+ - "You want a coding-agent prompt to type itself out with the authentic welcome-screen chrome."+ - "The scene calls for a terminal-app card rather than a raw shell — recent-activity and what's-new panels carry product context."+avoidWhen:+ - "You need a generic, unbranded terminal — use `terminal-simulator`."+ - "You're depicting a different product's UI — use the matching card (`opencode`, `v0`, `chat-gpt`, `claude-chat`)."+ - "You only need a typed command line with a cursor and no app frame — use `typewriter` over a plain surface."---<ComponentPreview name="claude-code" />diff --git a/content/docs/ai/opencode.mdx b/content/docs/ai/opencode.mdxindex b9a5cebe..29700fd1 100644--- a/content/docs/ai/opencode.mdx+++ b/content/docs/ai/opencode.mdx@@ -1,6 +1,17 @@---title: OpenCodedescription: Animated OpenCode TUI welcome screen that types a query into the input+component: opencode+vibe: tech+length: 150+useWhen:+ - "Depicting the OpenCode TUI as a recognizable branded surface in a dev-tool demo."+ - "A coding-agent query should type itself into the authentic welcome screen with model/provider context."+ - "The scene wants a terminal-UI card rather than a raw shell."+avoidWhen:+ - "You're depicting a different product — use the matching card (`claude-code`, `v0`, `chat-gpt`, `claude-chat`)."+ - "You need a generic, unbranded terminal — use `terminal-simulator`."+ - "You only need a typed line with a cursor and no app chrome — use `typewriter`."---<ComponentPreview name="opencode" />diff --git a/content/docs/ai/v0.mdx b/content/docs/ai/v0.mdxindex ff328245..3e833d43 100644--- a/content/docs/ai/v0.mdx+++ b/content/docs/ai/v0.mdx@@ -1,6 +1,17 @@---title: v0description: Animated Vercel v0 composer that types a prompt and morphs the mic button into a send button+component: v0+vibe: tech+length: 150+useWhen:+ - "Depicting the Vercel v0 composer as a recognizable branded surface in a generative-UI demo."+ - "A build prompt should type itself in with the mic→send button morph as the action beat."+ - "The scene wants the v0 product surface specifically, not a generic chat box."+avoidWhen:+ - "You're depicting a different product — use the matching card (`chat-gpt`, `claude-chat`, `claude-code`, `opencode`)."+ - "You need a general AI chat exchange rather than a prompt composer — use `chat-gpt` or `claude-chat`."+ - "You only need a typed input with a cursor and no app chrome — use `typewriter`."---<ComponentPreview name="v0" />diff --git a/content/docs/compositions/ecosystem-constellation.mdx b/content/docs/compositions/ecosystem-constellation.mdxindex b250ec00..42ff692e 100644--- a/content/docs/compositions/ecosystem-constellation.mdx+++ b/content/docs/compositions/ecosystem-constellation.mdx@@ -1,6 +1,17 @@---title: Ecosystem Constellationdescription: A central product logo orbited by integration satellites with pulsing data lines+component: ecosystem-constellation+vibe: tech+length: 240+useWhen:+ - "The story is \"we plug into everything\" — one hub product ringed by the tools it connects to."+ - "You want recognizable integration marks on screen without shipping any logo assets: GitHub, Vercel, Stripe, Slack, Linear, Figma, Notion and Discord are inline SVGs in the component."+ - "The shot has to hold for a while — satellites assemble once on a staggered spring, then orbit and fire their connection lines one at a time indefinitely."+avoidWhen:+ - "You need your own integration logos; the eight marks are hardcoded in the file, so swapping them means editing the copied component."+ - "The point is data moving from one named system to another rather than radiating from a centre — `data-flow-pipes` sends packets along pipes between nodes."+ - "You just want a set of brand chips to arrive and hold with no orbit; `logo-enter` springs a stacked group in one-by-one."---<ComponentPreview name="ecosystem-constellation" />diff --git a/content/docs/compositions/infinite-bento-pan.mdx b/content/docs/compositions/infinite-bento-pan.mdxindex 292c5257..eb9c5848 100644--- a/content/docs/compositions/infinite-bento-pan.mdx+++ b/content/docs/compositions/infinite-bento-pan.mdx@@ -1,6 +1,17 @@---title: Infinite Bento Pandescription: A hypnotic diagonal camera glide over an oversized grid of bento cards+component: infinite-bento-pan+vibe: data+length: 300+useWhen:+ - "You need an ambient establishing shot that says \"a lot is happening here\" without asking anyone to read a single number."+ - "The shot should be one uninterrupted camera move — the diagonal traversal is interpolated across the composition's whole `durationInFrames`, so a longer duration slows the glide rather than changing its path."+ - "A background layer is wanted behind a title or logo, with dozens of dashboard cards drifting past and a built-in vignette darkening the frame edges."+avoidWhen:+ - "The figures on screen have to mean something — every counter, stat and chart here is sine-driven filler, so use `animated-line-chart` or `animated-bar-chart` for a number the viewer should actually read."+ - "You need the camera to slow down, hold, or land on one specific card; the pan is a single linear diagonal with no easing and no dwell."+ - "You want a horizontal loop rather than a camera over a grid; `infinite-marquee` and `perspective-marquee` scroll a strip seamlessly instead."---<ComponentPreview name="infinite-bento-pan" />diff --git a/content/docs/compositions/live-code-compilation.mdx b/content/docs/compositions/live-code-compilation.mdxindex 99cbd4f7..50324889 100644--- a/content/docs/compositions/live-code-compilation.mdx+++ b/content/docs/compositions/live-code-compilation.mdx@@ -1,6 +1,17 @@---title: Live Code Compilationdescription: A split-screen where code is typed on the left and the right-side UI snaps to match in a single frame+component: live-code-compilation+vibe: tech+length: 260+useWhen:+ - "You want to show cause and effect for a developer audience: a style prop finishes typing on the left and the button on the right changes on that exact frame."+ - "The pitch needs an HMR moment — the preview button carries `transition: none`, so every property lands as a hard snap rather than an ease."+ - "You need a self-contained developer-tooling beat that takes no props beyond an accent colour and runs its own typing schedule to completion."+avoidWhen:+ - "The code on screen has to be yours — the eight typed fragments and the resulting button are hardcoded, while `glass-code-block` and `glass-code-walk` take arbitrary code as a `code` prop."+ - "The shot is about commands and their output rather than an editor next to a preview; `terminal-simulator` types commands and rolls older lines off the top."+ - "The split should read as a conversation driving the result; `chat-to-preview-layout` shrinks a chat column while the preview column expands."---<ComponentPreview name="live-code-compilation" />diff --git a/content/docs/effects/confetti.mdx b/content/docs/effects/confetti.mdxindex 90a9d20d..289fb212 100644--- a/content/docs/effects/confetti.mdx+++ b/content/docs/effects/confetti.mdx@@ -1,6 +1,17 @@---title: Confettidescription: Deterministic confetti burst for Remotion — seeded particles with gravity, spin, and flutter+component: confetti+vibe: playful+length: 90+useWhen:+ - "A milestone moment needs a celebratory payoff — product launch, plan completion, success screen."+ - "You want a deterministic particle burst that renders identically on every export pass (seed-controlled)."+ - "The effect should fire mid-composition at a specific frame via `startFrame`."+avoidWhen:+ - "The video has a clean, minimal, or corporate tone — confetti reads as celebration-specific and breaks professional pacing; use a subtle shader backdrop like `shader-grain-gradient` instead."+ - "You need a looping ambient particle background — confetti is a one-shot burst with gravity falloff, not a loop; use `shader-dot-orbit` for sustained motion."+ - "The burst should originate from a specific UI element offscreen — `originX`/`originY` are normalized 0–1 to the frame, not element-relative; compose with `AbsoluteFill` positioning instead."---<ComponentPreview name="confetti" />diff --git a/content/docs/effects/crumple-toss.mdx b/content/docs/effects/crumple-toss.mdxindex 4aee4474..73ed02da 100644--- a/content/docs/effects/crumple-toss.mdx+++ b/content/docs/effects/crumple-toss.mdx@@ -1,6 +1,16 @@---title: Crumple Tossdescription: Crushes an element into a ball of paper and throws it out of frame+component: crumple-toss+vibe: paper+length: 27+useWhen:+ - "Discarding something on screen — the old plan, the wrong answer, the previous version."+ - "Building a before/after beat where the replacement is revealed as the ball leaves."+avoidWhen:+ - "You want a general element exit in a clean UI scene — this one is loud and physical; use a fade instead."+ - "You need a scene-level exit that replaces the whole frame — that is `page-turn`. This is **not** a `TransitionPresentation` and does not belong in a `<TransitionSeries>`."+ - "You want the ball to land, bounce, or hit a wastebasket; none of that is here."---<ComponentPreview name="crumple-toss" />diff --git a/content/docs/effects/ink-arrow.mdx b/content/docs/effects/ink-arrow.mdxindex 517e70e1..b438be66 100644--- a/content/docs/effects/ink-arrow.mdx+++ b/content/docs/effects/ink-arrow.mdx@@ -1,6 +1,15 @@---title: Ink Arrowdescription: A hand-drawn arrow that draws itself from one point to another in stop-motion poses+component: ink-arrow+vibe: paper+length: 150+useWhen:+ - "A hand-drawn annotation should point from one thing to another — callouts over paper or scrapbook scenes."+ - "The pointing itself is part of the story and should be seen being drawn, pose by pose."+avoidWhen:+ - "You need a straight technical connector or a diagram edge — this is a wobbly pen line with a personality, not a flowchart arrow."+ - "The arrow must anchor itself to another component's live position: `from`/`to` are fixed coordinates you supply."---<ComponentPreview name="ink-arrow" />diff --git a/content/docs/effects/paper-wobble.mdx b/content/docs/effects/paper-wobble.mdxindex 45d57ba4..39c2cebc 100644--- a/content/docs/effects/paper-wobble.mdx+++ b/content/docs/effects/paper-wobble.mdx@@ -1,6 +1,16 @@---title: Paper Wobbledescription: Per-pose reshoot jitter that makes any content feel hand-placed on a desk+component: paper-wobble+vibe: paper+length: 90+useWhen:+ - "Any block should carry the stop-motion reshoot wobble — headlines, cards, or content that must feel hand-placed rather than laid out."+ - "Two or more elements should read as separate objects on a desk: give each its own `seed`."+avoidWhen:+ - "The content should sit rock-still — UI simulations, code blocks being read."+ - "You want smooth floating motion rather than discrete poses — use `drift`."+ - "The component already jitters itself, like `paper-sticker`; wrapping it just doubles the shake."---<ComponentPreview name="paper-wobble" />diff --git a/content/docs/effects/scribble-circle.mdx b/content/docs/effects/scribble-circle.mdxindex be2ff8ee..f88a357b 100644--- a/content/docs/effects/scribble-circle.mdx+++ b/content/docs/effects/scribble-circle.mdx@@ -1,6 +1,16 @@---title: Scribble Circledescription: A brush circle that sweeps itself around a region of the frame, opening thin and closing thick+component: scribble-circle+vibe: paper+length: 30+useWhen:+ - "Circling the one element that matters — a button, a number, a row in a screenshot."+ - "Building the full annotation beat: circle the thing, then point at it with `ink-arrow`."+avoidWhen:+ - "You need a permanent border or a focus ring. This is a gesture that happens once, not a state."+ - "You want a rectangular or bracket-shaped annotation, or to cross something out."+ - "The target's size is not known at author time — this component cannot measure it."---<ComponentPreview name="scribble-circle" />diff --git a/content/docs/layout/backdrop.mdx b/content/docs/layout/backdrop.mdxindex a4712c90..53fbb6d2 100644--- a/content/docs/layout/backdrop.mdx+++ b/content/docs/layout/backdrop.mdx@@ -1,6 +1,17 @@---title: Backdropdescription: Full-frame fill with an optional rounded, shadowed content frame — accepts a color, gradient, image, or any React element as a live animated background+component: backdrop+vibe: clean+length: 150+useWhen:+ - "You need a scene background — wrap every composition in `Backdrop` rather than hardcoding background colors on individual components."+ - "You want the Screen Studio floating-card look: colored surround with a padded, rounded, shadowed inner frame."+ - "The background itself should animate (pass a shader backdrop like `ShaderMeshGradient` as the `fill`)."+avoidWhen:+ - "You need an infinitely looping ambient background as a standalone track — use a shader backdrop directly and let the composition handle framing."+ - "You want a raw full-bleed color with no frame treatment — set `padding={0}` and `radius={0}`, or just set `backgroundColor` in the Remotion composition root."+ - "You're inside a transition presentation — transitions like `whip-pan` manage their own full-frame layout; nesting Backdrop inside them creates double-framing."---<ComponentPreview name="backdrop" />diff --git a/content/docs/layout/chat-to-preview-layout.mdx b/content/docs/layout/chat-to-preview-layout.mdxnew file mode 100644index 00000000..038c1be6--- /dev/null+++ b/content/docs/layout/chat-to-preview-layout.mdx@@ -0,0 +1,101 @@+---+title: Chat to Preview Layout+description: A two-column split where the chat column shrinks and the preview column expands, for showing an agent building something+component: chat-to-preview-layout+vibe: tech+length: 120+useWhen:+ - "Showing an AI agent at work — the conversation starts as the subject, then yields the frame to what it produced"+ - "You need a two-column split whose ratio animates, without writing the width interpolation yourself"+ - "A demo has to hand attention from input to output inside a single continuous shot, with no cut"+avoidWhen:+ - "Both columns should stay the same size — this component exists for the ratio change; use a plain flex row"+ - "The transition between the two states is a cut rather than a squeeze — use a transition from `TransitionSeries` instead"+ - "You need more than two columns, or a vertical split — the layout is horizontal and two-up by construction"+---++<ComponentPreview name="chat-to-preview-layout" />++## Installation++<InstallBlock name="chat-to-preview-layout" />++## Usage++Both columns are slots — pass whatever you want rendered. The layout animates the split from+`startChatRatio` to `endChatRatio`, so the chat side gives up width as the preview grows.++```tsx+// src/Root.tsx+import { Composition } from "remotion";+import { ChatToPreviewLayout } from "@/components/remocn/chat-to-preview-layout";++const AgentScene = () => (+ <ChatToPreviewLayout+ chat={<YourConversation />}+ preview={<YourAppPreview />}+ startChatRatio={0.5}+ endChatRatio={0.25}+ />+);++export const RemotionRoot = () => (+ <Composition+ id="ChatToPreviewLayout"+ component={AgentScene}+ durationInFrames={120}+ fps={30}+ width={1280}+ height={720}+ />+);+```++Leaving `chat` or `preview` unset renders a built-in placeholder, which is useful while you are+blocking out the timing before the real content exists.++<Note title="Columns have minimum widths">+ The chat column will not squeeze below 520px of inner width and the preview will not go below+ 720px, so extreme ratios clamp rather than collapse. Keep `endChatRatio` at or above roughly+ `0.2` on the standard `1280×720` canvas to stay clear of the clamp.+</Note>++## Props++<PropsTable+ rows={[+ {+ name: "chat",+ type: "ReactNode",+ description: "Content of the left column. Falls back to a built-in placeholder conversation.",+ },+ {+ name: "preview",+ type: "ReactNode",+ description: "Content of the right column. Falls back to a built-in placeholder preview.",+ },+ {+ name: "startChatRatio",+ type: "number",+ default: "0.5",+ description: "Share of the width the chat column holds at the start, from 0 to 1.",+ },+ {+ name: "endChatRatio",+ type: "number",+ default: "0.25",+ description: "Share of the width the chat column holds once the squeeze completes.",+ },+ {+ name: "speed",+ type: "number",+ default: "1",+ description: "Time multiplier applied as frame × speed. Above 1 the columns resize sooner.",+ },+ {+ name: "className",+ type: "string",+ description: "Optional className passed to the root element.",+ },+ ]}+/>diff --git a/content/docs/layout/drift.mdx b/content/docs/layout/drift.mdxindex 33e55892..81bf1da1 100644--- a/content/docs/layout/drift.mdx+++ b/content/docs/layout/drift.mdx@@ -1,6 +1,15 @@---title: Driftdescription: Wrap any scene in a slow camera push-in so no frame is ever static+component: drift+vibe: clean+length: 90+useWhen:+ - "Any static scene should feel alive — hero cards, feature panels, dashboards sitting between transitions."+ - "You want the default anti-static wrapper of the catalog — reach for it whenever a scene would otherwise hold a frozen frame."+avoidWhen:+ - "The content is already animated with strong motion — layering drift on top of it doubles the movement and muddies the read."+ - "You need a noticeable, dramatic zoom — this is a creep, not a statement; use a real scale animation or `zoom-blur` for punch."---<ComponentPreview name="drift" />diff --git a/content/docs/layout/meta.json b/content/docs/layout/meta.jsonindex 6b538281..380ce0cf 100644--- a/content/docs/layout/meta.json+++ b/content/docs/layout/meta.json@@ -1,5 +1,5 @@{"title": "Layout","collapsible": false,- "pages": ["index", "backdrop", "drift"]+ "pages": ["index", "backdrop", "drift", "chat-to-preview-layout"]}diff --git a/content/docs/shaders/components/shader-caustics.mdx b/content/docs/shaders/components/shader-caustics.mdxindex 7361e46c..f5571435 100644--- a/content/docs/shaders/components/shader-caustics.mdx+++ b/content/docs/shaders/components/shader-caustics.mdx@@ -1,6 +1,16 @@---title: Causticsdescription: A field of refracted light — the bright filaments light makes through a rippling surface+component: shader-caustics+vibe: premium+length: 150+useWhen:+ - "Water, light, or premium ambient backdrops where refracted-light filaments fit the mood."+ - "A calm, elegant scene wants motion without a strong directional pull."+ - "You want the light density to build toward one edge of the frame (denser toward the bottom by default)."+avoidWhen:+ - "You want structured cellular noise — use `shader-voronoi`."+ - "You want soft fog instead of filaments — use `shader-perlin-noise`."---<ComponentPreview name="shader-caustics" />diff --git a/content/docs/shaders/components/shader-color-panels.mdx b/content/docs/shaders/components/shader-color-panels.mdxindex 15bf291e..feb4ad17 100644--- a/content/docs/shaders/components/shader-color-panels.mdx+++ b/content/docs/shaders/components/shader-color-panels.mdx@@ -1,6 +1,17 @@---title: Color Panelsdescription: Overlapping translucent color panels sliding past each other+component: shader-color-panels+vibe: premium+length: 150+useWhen:+ - "You want an architectural, glassy backdrop of translucent panes sliding past each other."+ - "A scene benefits from layered depth without organic blob motion."+ - "You want the panel count tunable via `density`."+avoidWhen:+ - "You want organic, flowing motion — use `shader-warp` or `shader-metaballs`."+ - "The overlap patterns would clutter dense foreground content — lower `density`."+ - "You need a single smooth gradient — use `shader-mesh-gradient`."---<ComponentPreview name="shader-color-panels" />diff --git a/content/docs/shaders/components/shader-dithering.mdx b/content/docs/shaders/components/shader-dithering.mdxindex ede1ef25..d3f4be4f 100644--- a/content/docs/shaders/components/shader-dithering.mdx+++ b/content/docs/shaders/components/shader-dithering.mdx@@ -1,6 +1,17 @@---title: Ditheringdescription: Ordered-dither shading over an animated gradient field+component: shader-dithering+vibe: tech+length: 150+useWhen:+ - "You want a retro/print, 1-bit ordered-dither texture over a moving gradient."+ - "A tech or lo-fi scene benefits from visible bayer/ordered dot structure."+ - "You want the matrix tunable via `type` (`\"2x2\"`, `\"4x4\"`, `\"8x8\"`)."+avoidWhen:+ - "You want a centered dithered sphere — override `shape` (this wrapper defaults to full-bleed `\"wave\"`)."+ - "You want smooth, non-textured color — use `shader-mesh-gradient`."+ - "The dot pattern would reduce legibility of small text — raise `size` or use a solid `backdrop`."---<ComponentPreview name="shader-dithering" />diff --git a/content/docs/shaders/components/shader-dot-orbit.mdx b/content/docs/shaders/components/shader-dot-orbit.mdxindex 901696f1..7e2f6365 100644--- a/content/docs/shaders/components/shader-dot-orbit.mdx+++ b/content/docs/shaders/components/shader-dot-orbit.mdx@@ -1,6 +1,17 @@---title: Dot Orbitdescription: Dots orbiting on concentric paths across the frame+component: shader-dot-orbit+vibe: tech+length: 150+useWhen:+ - "You want a structured dot-grid backdrop with gentle orbital motion."+ - "A tech scene benefits from a regular pattern that reads as \"network\" or \"system\"."+ - "You want dot size/spread tunable via `size`/`spreading`."+avoidWhen:+ - "You want a static dot grid — the static `dot-grid` shader is intentionally not shipped; use a CSS grid."+ - "You want organic, flowing motion — use `shader-warp` or `shader-metaballs`."+ - "The regular pattern would clash with dense foreground content."---<ComponentPreview name="shader-dot-orbit" />diff --git a/content/docs/shaders/components/shader-gem-smoke.mdx b/content/docs/shaders/components/shader-gem-smoke.mdxindex a7e80a99..420f6e44 100644--- a/content/docs/shaders/components/shader-gem-smoke.mdx+++ b/content/docs/shaders/components/shader-gem-smoke.mdx@@ -1,6 +1,16 @@---title: Gem Smokedescription: Animated color fields flowing behind and inside a glassy logo silhouette+component: shader-gem-smoke+vibe: premium+length: 150+useWhen:+ - "Brand or logo reveals that want smoke living inside and around a mark."+ - "You have a static brand asset (SVG/PNG) to feed as `image` and want it treated as a glassy silhouette."+ - "A premium product intro wants color fields flowing through a recognizable shape."+avoidWhen:+ - "You have no logo or mark to feed as `image` — use `shader-smoke-ring` or `shader-neuro-noise` for a shapeless field instead."+ - "The brand mark should stay static and legible — the smoke will distort its read."---<ComponentPreview name="shader-gem-smoke" />diff --git a/content/docs/shaders/components/shader-god-rays.mdx b/content/docs/shaders/components/shader-god-rays.mdxindex 3e8cecba..4fb9152f 100644--- a/content/docs/shaders/components/shader-god-rays.mdx+++ b/content/docs/shaders/components/shader-god-rays.mdx@@ -1,6 +1,17 @@---title: God Raysdescription: Volumetric light rays radiating from an off-screen source+component: shader-god-rays+vibe: premium+length: 150+useWhen:+ - "A hero or reveal scene wants cinematic volumetric light rays from a corner source."+ - "You want atmosphere and depth behind a title without geometric structure."+ - "The palette is dark and you want soft neutral rays (override `colors` to brand-tint)."+avoidWhen:+ - "The brief bans decorative glow — this is a genuine volumetric shader, but keep `bloom`/`intensity` restrained so it does not read as an AI-slop glow."+ - "You want structured or cellular motion — use `shader-dot-orbit` or `shader-voronoi`."+ - "Bright rays would wash out foreground text — lower `intensity`/`bloom`."---<ComponentPreview name="shader-god-rays" />diff --git a/content/docs/shaders/components/shader-grain-gradient.mdx b/content/docs/shaders/components/shader-grain-gradient.mdxindex 2ee5bced..89e73ec8 100644--- a/content/docs/shaders/components/shader-grain-gradient.mdx+++ b/content/docs/shaders/components/shader-grain-gradient.mdx@@ -1,6 +1,17 @@---title: Grain Gradientdescription: Grainy multi-stop gradient that drifts slowly with film-grain texture over the blend+component: shader-grain-gradient+vibe: premium+length: 150+useWhen:+ - "A gradient backdrop needs analog texture — the grain reads as film/print rather than flat digital."+ - "The scene tone is premium and editorial and you want subtle motion that does not distract."+ - "You want the gradient softened; raise `softness`/`noise` for an even quieter field."+avoidWhen:+ - "You need crisp, clean color with no texture — use `shader-mesh-gradient`."+ - "Foreground content is tiny text — heavy grain can reduce contrast; lower `intensity`/`noise` or pick a solid `backdrop`."+ - "You want structured geometry — use `shader-dot-orbit` or `shader-voronoi`."---<ComponentPreview name="shader-grain-gradient" />diff --git a/content/docs/shaders/components/shader-liquid-metal.mdx b/content/docs/shaders/components/shader-liquid-metal.mdxindex c1a27bde..212cc279 100644--- a/content/docs/shaders/components/shader-liquid-metal.mdx+++ b/content/docs/shaders/components/shader-liquid-metal.mdx@@ -1,6 +1,17 @@---title: Liquid Metaldescription: Molten metallic surface with flowing specular highlights+component: shader-liquid-metal+vibe: premium+length: 150+useWhen:+ - "A premium, industrial, or luxury scene wants a brushed/molten metal surface."+ - "You want reflective, flowing highlights that read as material rather than color."+ - "The palette is neutral/monochrome and you want tint to lead subtly."+avoidWhen:+ - "You want a centered metallic emblem — override `shape` back to a paper shape (this wrapper defaults to full-bleed `\"none\"`)."+ - "The brief calls for color — liquid-metal is tonal; use `shader-warp` or `shader-mesh-gradient`."+ - "High contrast highlights would fight fine text — lower `contour`/`repetition`."---<ComponentPreview name="shader-liquid-metal" />diff --git a/content/docs/shaders/components/shader-mesh-gradient.mdx b/content/docs/shaders/components/shader-mesh-gradient.mdxindex 117a1aad..de928976 100644--- a/content/docs/shaders/components/shader-mesh-gradient.mdx+++ b/content/docs/shaders/components/shader-mesh-gradient.mdx@@ -1,6 +1,17 @@---title: Mesh Gradientdescription: WebGL mesh gradient backdrop driven per-frame for deterministic Remotion renders+component: shader-mesh-gradient+vibe: premium+length: 150+useWhen:+ - "You need a quality, production-grade gradient backdrop."+ - "A hero or title scene wants slow, living color motion behind foreground text without competing for attention."+ - "The brand palette is soft/dark and you want the gradient to lead only when you override `colors`."+avoidWhen:+ - "You want a structured, geometric background — use `shader-dot-orbit` or `shader-voronoi`."+ - "The shader must animate on a wall clock rather than the timeline — these wrappers are frame-driven by design; that is what keeps renders deterministic."+ - "You need a static, single-frame image — a solid `backdrop` fill is lighter."---<ComponentPreview name="shader-mesh-gradient" />diff --git a/content/docs/shaders/components/shader-metaballs.mdx b/content/docs/shaders/components/shader-metaballs.mdxindex 7923e21d..c4ca0c58 100644--- a/content/docs/shaders/components/shader-metaballs.mdx+++ b/content/docs/shaders/components/shader-metaballs.mdx@@ -1,6 +1,17 @@---title: Metaballsdescription: Organic blobs merging and splitting like lava+component: shader-metaballs+vibe: playful+length: 150+useWhen:+ - "A playful or organic scene wants lava-lamp blobs merging and splitting."+ - "You want soft, rounded motion that reads as fun without being childish."+ - "You want blob count/size tunable via `count`/`size`."+avoidWhen:+ - "The brand is strictly serious/corporate — metaballs read playful."+ - "You want structured or geometric motion — use `shader-dot-orbit` or `shader-voronoi`."+ - "Blobs would obscure dense foreground content — lower `count`/`size`."---<ComponentPreview name="shader-metaballs" />diff --git a/content/docs/shaders/components/shader-neuro-noise.mdx b/content/docs/shaders/components/shader-neuro-noise.mdxindex 1f143375..bd21e985 100644--- a/content/docs/shaders/components/shader-neuro-noise.mdx+++ b/content/docs/shaders/components/shader-neuro-noise.mdx@@ -1,6 +1,17 @@---title: Neuro Noisedescription: Organic neural-web noise field that slowly morphs+component: shader-neuro-noise+vibe: tech+length: 150+useWhen:+ - "An AI / ML / tech scene wants an organic neural-web texture that reads as \"intelligence\"."+ - "You want slow morphing structure behind text without hard geometry."+ - "The palette is dark and you want a filamentary web to sit low-contrast in the back."+avoidWhen:+ - "You want smooth cloud noise instead of web filaments — use `shader-perlin-noise` or `shader-simplex-noise`."+ - "The brief is playful or warm — neuro-noise reads technical."+ - "Bright filaments would fight small text — lower `brightness`/`contrast`."---<ComponentPreview name="shader-neuro-noise" />diff --git a/content/docs/shaders/components/shader-perlin-noise.mdx b/content/docs/shaders/components/shader-perlin-noise.mdxindex 49856e19..5bf3c732 100644--- a/content/docs/shaders/components/shader-perlin-noise.mdx+++ b/content/docs/shaders/components/shader-perlin-noise.mdx@@ -1,6 +1,17 @@---title: Perlin Noisedescription: Classic Perlin noise clouds drifting across the frame+component: shader-perlin-noise+vibe: clean+length: 150+useWhen:+ - "You want a soft, cloudy, organic backdrop that drifts slowly and stays calm."+ - "A clean scene needs texture without structure or color."+ - "You want a duotone fog — `colorFront` clouds over `colorBack`."+avoidWhen:+ - "You want a smoother, more flowing field — use `shader-simplex-noise`."+ - "You want neural-web filaments — use `shader-neuro-noise`."+ - "You need sharp cellular structure — use `shader-voronoi`."---<ComponentPreview name="shader-perlin-noise" />diff --git a/content/docs/shaders/components/shader-pulsing-border.mdx b/content/docs/shaders/components/shader-pulsing-border.mdxindex c80158b0..1899bf8f 100644--- a/content/docs/shaders/components/shader-pulsing-border.mdx+++ b/content/docs/shaders/components/shader-pulsing-border.mdx@@ -1,6 +1,17 @@---title: Pulsing Borderdescription: Glowing border frame that pulses around the edges+component: shader-pulsing-border+vibe: premium+length: 150+useWhen:+ - "You want a pulsing lit frame around the scene edges to contain foreground content."+ - "A premium reveal benefits from an edge glow that leaves the center clear for text."+ - "You want corner radius / thickness tunable via `roundness`/`thickness`."+avoidWhen:+ - "The brief bans decorative glow — keep `bloom`/`intensity` restrained so the border does not read as AI-slop neon."+ - "You want a full-field texture — the interior stays mostly `colorBack`; use a noise or gradient shader."+ - "The scene already has a strong border/frame in the layout."---<ComponentPreview name="shader-pulsing-border" />diff --git a/content/docs/shaders/components/shader-simplex-noise.mdx b/content/docs/shaders/components/shader-simplex-noise.mdxindex 4f75b1d7..13df05c3 100644--- a/content/docs/shaders/components/shader-simplex-noise.mdx+++ b/content/docs/shaders/components/shader-simplex-noise.mdx@@ -1,6 +1,17 @@---title: Simplex Noisedescription: Simplex noise flow field, smoother than Perlin+component: shader-simplex-noise+vibe: clean+length: 150+useWhen:+ - "You want the smoothest of the noise backdrops — fewer directional artifacts than Perlin."+ - "A clean, minimal scene needs gentle multi-stop color drift."+ - "You want posterized banding control via `stepsPerColor`."+avoidWhen:+ - "You want cloudier, softer fog — use `shader-perlin-noise`."+ - "You want cellular structure — use `shader-voronoi`."+ - "You want neural-web filaments — use `shader-neuro-noise`."---<ComponentPreview name="shader-simplex-noise" />diff --git a/content/docs/shaders/components/shader-smoke-ring.mdx b/content/docs/shaders/components/shader-smoke-ring.mdxindex ad84eefd..028570a2 100644--- a/content/docs/shaders/components/shader-smoke-ring.mdx+++ b/content/docs/shaders/components/shader-smoke-ring.mdx@@ -1,6 +1,17 @@---title: Smoke Ringdescription: Soft smoke ring curling and dissipating in place+component: shader-smoke-ring+vibe: premium+length: 150+useWhen:+ - "You want a single soft, centered smoke ring as a focal atmospheric element."+ - "A minimal, premium scene benefits from one curling shape on a dark field."+ - "You want a neutral, near-monochrome look (override `colors` to tint)."+avoidWhen:+ - "You need a full-bleed edge-to-edge texture — this is a centered object; use a noise or gradient shader."+ - "The center sits behind key text — the ring draws the eye inward."+ - "You want multiple elements or busy motion — smoke-ring is deliberately singular."---<ComponentPreview name="shader-smoke-ring" />diff --git a/content/docs/shaders/components/shader-spiral.mdx b/content/docs/shaders/components/shader-spiral.mdxindex d20780f1..efc6f543 100644--- a/content/docs/shaders/components/shader-spiral.mdx+++ b/content/docs/shaders/components/shader-spiral.mdx@@ -1,6 +1,17 @@---title: Spiraldescription: Rotating spiral arms radiating from the center+component: shader-spiral+vibe: premium+length: 150+useWhen:+ - "You want a hypnotic, rotating radial background with visible arm structure."+ - "A transition or intro benefits from a strong \"pulling in toward the center\" motion."+ - "You want a two-tone, minimal look — `colorFront` on `colorBack`."+avoidWhen:+ - "You want closed concentric rings rather than open arms — use `shader-swirl`."+ - "The center sits behind key text — the convergence point competes for attention."+ - "You need multi-color richness — spiral is duotone by default; use `shader-warp`."---<ComponentPreview name="shader-spiral" />diff --git a/content/docs/shaders/components/shader-strata.mdx b/content/docs/shaders/components/shader-strata.mdxindex 096b658f..4e41e8cb 100644--- a/content/docs/shaders/components/shader-strata.mdx+++ b/content/docs/shaders/components/shader-strata.mdx@@ -1,6 +1,16 @@---title: Stratadescription: Fine horizontal sediment layers displaced by fbm noise, each drifting at its own depth+component: shader-strata+vibe: clean+length: 150+useWhen:+ - "Calm, grounded, geological ambient backdrops — foundations, stability, \"built on\" narratives."+ - "A scene wants texture and depth without directional motion."+ - "You want each layer moving at its own depth speed rather than a single flat gradient."+avoidWhen:+ - "You want motion with a clear direction or flow — use `shader-warp`."+ - "You want cellular texture instead of layered sediment — use `shader-voronoi`."---<ComponentPreview name="shader-strata" />diff --git a/content/docs/shaders/components/shader-swirl.mdx b/content/docs/shaders/components/shader-swirl.mdxindex 4f807254..6ff93963 100644--- a/content/docs/shaders/components/shader-swirl.mdx+++ b/content/docs/shaders/components/shader-swirl.mdx@@ -1,6 +1,17 @@---title: Swirldescription: Concentric bands swirling around a center point+component: shader-swirl+vibe: premium+length: 150+useWhen:+ - "You want a hypnotic, radial background with clear banded structure around a center."+ - "A scene benefits from rotational motion that reads as \"spinning up\" or focus."+ - "You want the band count tunable — raise `bandCount` for tighter rings."+avoidWhen:+ - "You want free-flowing liquid folds rather than concentric bands — use `shader-warp`."+ - "The center would sit behind critical text — the convergence point draws the eye."+ - "You want spiral arms instead of closed rings — use `shader-spiral`."---<ComponentPreview name="shader-swirl" />diff --git a/content/docs/shaders/components/shader-voronoi.mdx b/content/docs/shaders/components/shader-voronoi.mdxindex 3130f952..29507eec 100644--- a/content/docs/shaders/components/shader-voronoi.mdx+++ b/content/docs/shaders/components/shader-voronoi.mdx@@ -1,6 +1,17 @@---title: Voronoidescription: Animated Voronoi cells shifting and re-tessellating+component: shader-voronoi+vibe: tech+length: 150+useWhen:+ - "You want a cellular, crystalline backdrop that shifts and re-tessellates."+ - "A tech scene benefits from clear cell structure with dark gaps between cells."+ - "You want the gap thickness tunable via `gap`."+avoidWhen:+ - "You want soft, structureless fog — use `shader-perlin-noise` or `shader-simplex-noise`."+ - "You want a glow-heavy look — `glow` defaults to `0` on purpose; keep it low to avoid decorative bloom."+ - "Busy cells would clutter dense foreground content — lower `distortion` or use a solid `backdrop`."---<ComponentPreview name="shader-voronoi" />diff --git a/content/docs/shaders/components/shader-warp.mdx b/content/docs/shaders/components/shader-warp.mdxindex 6398de00..7b8cfb3b 100644--- a/content/docs/shaders/components/shader-warp.mdx+++ b/content/docs/shaders/components/shader-warp.mdx@@ -1,6 +1,17 @@---title: Warpdescription: Domain-warped color field that folds and stretches like liquid+component: shader-warp+vibe: premium+length: 150+useWhen:+ - "A hero scene wants organic, liquid motion that feels alive but stays out of the way."+ - "You want a flowing alternative to a static gradient with more directional movement."+ - "The palette is dark and you want folds of a single accent to read as depth."+avoidWhen:+ - "Text legibility over the whole frame is critical — raise `softness` and keep `distortion` low, or use a solid `backdrop`."+ - "You want tight, repeating structure — use `shader-swirl` (banded) or `shader-spiral`."+ - "You need a metallic sheen rather than color folds — use `shader-liquid-metal`."---<ComponentPreview name="shader-warp" />diff --git a/content/docs/shaders/components/shader-water.mdx b/content/docs/shaders/components/shader-water.mdxindex 876c722e..6918694a 100644--- a/content/docs/shaders/components/shader-water.mdx+++ b/content/docs/shaders/components/shader-water.mdx@@ -1,6 +1,17 @@---title: Waterdescription: Caustic water-surface ripples with subtle refraction+component: shader-water+vibe: premium+length: 150+useWhen:+ - "A scene wants a calm, aquatic atmosphere with gentle refracted highlights."+ - "You need a cool, dark blue backdrop that moves slowly without pulling focus."+ - "The brief calls for depth or \"flow\" imagery (data lakes, streaming, calm)."+avoidWhen:+ - "The palette must be warm or vibrant — water reads cool by design; recolor via `colorHighlight`/`colorBack` or choose another shader."+ - "You want sharp geometric motion — use `shader-swirl` or `shader-dot-orbit`."+ - "Bright caustics would fight small text — lower `caustic`/`highlights` or use a solid `backdrop`."---<ComponentPreview name="shader-water" />diff --git a/content/docs/shaders/components/shader-weave.mdx b/content/docs/shaders/components/shader-weave.mdxindex 73ab8c86..b4f89d19 100644--- a/content/docs/shaders/components/shader-weave.mdx+++ b/content/docs/shaders/components/shader-weave.mdx@@ -1,6 +1,16 @@---title: Weavedescription: A woven substrate of warp and weft threads crossing on a domain-warped grid+component: shader-weave+vibe: premium+length: 150+useWhen:+ - "Tactile, crafted, \"made-of\" textures — fabric, mesh, or substrate metaphors."+ - "A scene wants a slow sheen of light traveling across a textured surface."+ - "The brand voice is handcrafted or material rather than digital and smooth."+avoidWhen:+ - "You want a smooth gradient field — use `shader-mesh-gradient`."+ - "You want organic noise instead of a woven structure — use `shader-neuro-noise`."---<ComponentPreview name="shader-weave" />diff --git a/content/docs/social/github-sponsors.mdx b/content/docs/social/github-sponsors.mdxindex a285559d..ab6445be 100644--- a/content/docs/social/github-sponsors.mdx+++ b/content/docs/social/github-sponsors.mdx@@ -1,6 +1,17 @@---title: GitHub Sponsorsdescription: Animated GitHub Sponsors lockup — a self-drawing heart that docks to a header, every sponsor avatar blur-staggering into a grid, then a thank-you headline and a CTA+component: github-sponsors+vibe: social+length: 270+useWhen:+ - "A thank-you beat for funders — the heart draws itself, docks upward, and every sponsor avatar blur-staggers into a grid beneath it."+ - "An OSS funding ask needs to end on the \"Become a sponsor\" pill and the github.com/sponsors/<account> line."+ - "You want the card to size itself to a live sponsor list, since the grid columns and the \"Powered by N sponsors\" line both derive from the array length."+avoidWhen:+ - "The milestone is a star count rather than funding — use `github-stars`, whose odometer counts up to a total."+ - "The subject is one person's profile instead of a group of supporters — use `x-follow-card`."+ - "You need a neutral partner or integration lineup without the Sponsors heart and pink CTA — use `logo-enter`."---<ComponentPreview name="github-sponsors" />diff --git a/content/docs/social/github-stars.mdx b/content/docs/social/github-stars.mdxindex d891b8e5..ff55aa22 100644--- a/content/docs/social/github-stars.mdx+++ b/content/docs/social/github-stars.mdx@@ -1,6 +1,17 @@---title: GitHub Starsdescription: Stargazer list fly-through with a synced odometer counter — renders standalone from sample data or accepts live stargazer props+component: github-stars+vibe: data+length: 120+useWhen:+ - "Celebrating an OSS milestone — the count-up odometer landing on a star total is the payoff beat."+ - "A repo-showcase or social-proof scene needs real stargazer faces flying past."+ - "You want one self-contained card that pairs the avatar fly-through with the synced counter."+avoidWhen:+ - "You only need the number to roll up without the stargazer fly-through — use `number-wheel` or `rolling-number`."+ - "The metric isn't GitHub stars — use a generic counter (`rolling-number`) or `animated-bar-chart` for compared values."+ - "You're depicting follower growth on X — use `x-followers-overview`."---<ComponentPreview name="github-stars" />diff --git a/content/docs/social/logo-enter.mdx b/content/docs/social/logo-enter.mdxindex aa207d42..e8938b60 100644--- a/content/docs/social/logo-enter.mdx+++ b/content/docs/social/logo-enter.mdx@@ -1,6 +1,17 @@---title: Logo Enterdescription: A stacked group of round brand chips that spring in one-by-one, then hold+component: logo-enter+vibe: social+length: 90+useWhen:+ - "Showing a cluster of brand/partner/integration logos arriving together (\"works with…\", an AI-tool lineup, an icon cloud)."+ - "A positioning or proof beat needs several marks to land as a stacked, overlapping group."+ - "You want logo chips that spring in and hold, with the exit owned by your `TransitionSeries` transition."+avoidWhen:+ - "You need a single product wordmark lockup — this is a multi-chip cluster, not one mark; build a lightweight lockup or resolve kinetic text (`kinetic-center-build`, `per-character-rise`) into the name."+ - "You're depicting one specific brand's product UI — use the matching card (`chat-gpt`, `claude-code`, `v0`, `opencode`)."+ - "The logos must orbit or scatter in 3D rather than stack — compose your own layout; this one stacks on a single axis."---<ComponentPreview name="logo-enter" />diff --git a/content/docs/social/x-follow-card.mdx b/content/docs/social/x-follow-card.mdxindex 75134892..425ccc3c 100644--- a/content/docs/social/x-follow-card.mdx+++ b/content/docs/social/x-follow-card.mdx@@ -1,6 +1,17 @@---title: X Follow Carddescription: Animated X profile follow card with spring bounce-in, staggered blur-in, and cursor-driven Follow transition+component: x-follow-card+vibe: social+length: 165+useWhen:+ - "Showcasing a single X profile with the recognizable click-to-Follow payoff as the action beat."+ - "A social-proof or creator-intro scene needs one branded profile card with the cursor interaction."+ - "You want an offline-safe card (gradient avatar fallback) without wiring real image URLs."+avoidWhen:+ - "You're aggregating follower growth or notifications rather than one profile — use `x-followers-overview`."+ - "The brand is GitHub, not X — use `github-stars`."+ - "You need a generic testimonial/quote card, not an X profile — compose a plain card."---<ComponentPreview name="x-follow-card" />diff --git a/content/docs/social/x-followers-overview.mdx b/content/docs/social/x-followers-overview.mdxindex e6f16fc0..e4b28609 100644--- a/content/docs/social/x-followers-overview.mdx+++ b/content/docs/social/x-followers-overview.mdx@@ -1,6 +1,17 @@---title: X Followers Overviewdescription: X follow notifications flip through in 3D, then the total follower count blurs in+component: x-followers-overview+vibe: data+length: 360+useWhen:+ - "A milestone or social-proof scene needs cycling follow notifications building to a total reveal."+ - "You want the confetti-backed follower-count payoff at the end of a growth story."+ - "Depicting X audience growth with multiple recent followers, not a single profile."+avoidWhen:+ - "You're highlighting one profile and a Follow click — use `x-follow-card`."+ - "The metric is GitHub stars — use `github-stars`."+ - "You only need a bare count-up with no notification feed or confetti — use `rolling-number` or `number-wheel`."---<ComponentPreview name="x-followers-overview" />diff --git a/content/docs/transitions/ascii-dissolve.mdx b/content/docs/transitions/ascii-dissolve.mdxindex 148e5070..9e58a7c4 100644--- a/content/docs/transitions/ascii-dissolve.mdx+++ b/content/docs/transitions/ascii-dissolve.mdx@@ -1,6 +1,17 @@---title: ASCII Dissolvedescription: Dissolve one scene into the next through a drifting field of ASCII glyphs+component: ascii-dissolve+vibe: tech+length: 40+useWhen:+ - "The video has a retro, terminal, or print aesthetic — the text-grid dissolve reads as CRT or risograph texture."+ - "Content is dev-tool or teletype in tone and a monospace-glyph cut fits the brand."+ - "The cut needs to stay content-agnostic — it works between any two scenes with no color matching required."+avoidWhen:+ - "The tone is soft or organic — use `grain-dissolve` or `perlin-dissolve` for a gentler texture instead."+ - "You need a camera move rather than a dissolve — use `whip-pan` or `push-through`."+ - "The brand is clean and minimal — the character grid reads as deliberately rough, not polished."---<ComponentPreview name="ascii-dissolve" />diff --git a/content/docs/transitions/caret-wipe.mdx b/content/docs/transitions/caret-wipe.mdxindex ba955813..a1eff1f9 100644--- a/content/docs/transitions/caret-wipe.mdx+++ b/content/docs/transitions/caret-wipe.mdx@@ -1,6 +1,16 @@---title: Caret Wipedescription: Sweep a typing caret across the frame, wiping the outgoing scene into the next+component: caret-wipe+vibe: clean+length: 40+useWhen:+ - "Dev-tool, editor, or terminal demos where a typing cursor is the natural through-line between scenes."+ - "The scenes are UI or text surfaces that plausibly get \"typed\" or \"erased.\""+ - "A directional wipe with a clear metaphor fits better than a generic dissolve."+avoidWhen:+ - "The scenes aren't text or UI surfaces — the caret metaphor has nothing to type over."+ - "You want a textured dissolve instead of a directional wipe — use `ascii-dissolve` or `dither-dissolve`."---<ComponentPreview name="caret-wipe" />diff --git a/content/docs/transitions/dither-dissolve.mdx b/content/docs/transitions/dither-dissolve.mdxindex 99a7a724..0ae01c34 100644--- a/content/docs/transitions/dither-dissolve.mdx+++ b/content/docs/transitions/dither-dissolve.mdx@@ -1,6 +1,16 @@---title: Dither Dissolvedescription: Dissolve one scene into the next through a drifting field of dither pixels+component: dither-dissolve+vibe: tech+length: 40+useWhen:+ - "The video has a retro, terminal, or print aesthetic — the dither reads as CRT/risograph texture."+ - "Dev-tool and CLI content — pairs naturally with `terminal-simulator` and `matrix-decode`."+ - "Cuts need to stay quick but textured — 40 frames, unlike the longer dissolves."+avoidWhen:+ - "The tone is soft and organic — the pixel grid reads technical; use `grain-dissolve` or `perlin-dissolve`."+ - "Brand colors clash with a two-color reduction — the field is strictly `colorBack`/`colorFront`."---<ComponentPreview name="dither-dissolve" />diff --git a/content/docs/transitions/focus-pull.mdx b/content/docs/transitions/focus-pull.mdxindex 86f6ee36..c2433441 100644--- a/content/docs/transitions/focus-pull.mdx+++ b/content/docs/transitions/focus-pull.mdx@@ -1,6 +1,16 @@---title: Focus Pulldescription: Rack focus from one scene to the next through a soft defocus breath+component: focus-pull+vibe: premium+length: 46+useWhen:+ - "The tone is refined and editorial — premium product films, calm brand moments, testimonials."+ - "Scenes shift attention rather than location — a neutral, cinematic alternative to `fade-through`."+ - "Adjacent scenes share a similar palette — the defocus blends them seamlessly."+avoidWhen:+ - "The cut needs energy or direction — use `whip-pan` or `push-through`."+ - "Fine text must stay legible up to the cut — the defocus starts eating detail early."---<ComponentPreview name="focus-pull" />diff --git a/content/docs/transitions/grain-dissolve.mdx b/content/docs/transitions/grain-dissolve.mdxindex 56e97893..495a6ff8 100644--- a/content/docs/transitions/grain-dissolve.mdx+++ b/content/docs/transitions/grain-dissolve.mdx@@ -1,6 +1,16 @@---title: Grain Dissolvedescription: Disintegrate the outgoing scene into soft grainy shapes and condense the next scene out of the noise+component: grain-dissolve+vibe: premium+length: 76+useWhen:+ - "The video has an editorial, textured, analog feel — grain reads as film and print."+ - "Chapter or mood changes where the scene should decompose rather than move."+ - "The `shape` prop should match the brand: `blob` organic, `wave` calm, `dots` halftone, `sphere` volumetric."+avoidWhen:+ - "The transition must be fast — under ~50 frames the intensity/softness sweep has no room to read."+ - "The tone is crisp and minimal — the grain texture adds visual noise by design."---<ComponentPreview name="grain-dissolve" />diff --git a/content/docs/transitions/icon-scatter.mdx b/content/docs/transitions/icon-scatter.mdxindex c6c079b4..1cfdc576 100644--- a/content/docs/transitions/icon-scatter.mdx+++ b/content/docs/transitions/icon-scatter.mdx@@ -1,6 +1,16 @@---title: Icon Scatterdescription: Scatter a field of icons over the cut, hiding the scene swap at the field's peak+component: icon-scatter+vibe: playful+length: 40+useWhen:+ - "Playful product or app transitions where icons are part of the brand's visual language."+ - "A feature-to-feature cut wants a moment of energy before settling into the next scene."+ - "The cover fill can be tuned to match the outgoing scene's background so the swap hides cleanly."+avoidWhen:+ - "The piece is minimal or serious — use `fade-through` for a quieter cut instead."+ - "The brand has no icon system to draw from — a generic icon field would look unrelated to the product."---<ComponentPreview name="icon-scatter" />diff --git a/content/docs/transitions/page-turn.mdx b/content/docs/transitions/page-turn.mdxindex 0fe94c8d..2a89dffc 100644--- a/content/docs/transitions/page-turn.mdx+++ b/content/docs/transitions/page-turn.mdx@@ -1,6 +1,16 @@---title: Page Turndescription: The exiting scene swings up and away like a notebook page in stop-motion poses+component: page-turn+vibe: paper+length: 128+useWhen:+ - "Act breaks in paper or scrapbook stop-motion videos — the current page physically leaves and the next scene is already living beneath it."+ - "You want the outgoing scene to pass IN FRONT of the incoming one. This is the only transition in the catalog that does that: the exiting wrapper takes `zIndex: 2`, inverting the TransitionSeries default."+avoidWhen:+ - "You need a smooth cinematic cut between UI scenes — use `whip-pan` or `push-through`."+ - "You want a dissolve — use the shader dissolve family."+ - "The entering scene needs its own entrance animation: here the reveal IS the entrance, and the entering scene is rendered untouched."---<ComponentPreview name="page-turn" />diff --git a/content/docs/transitions/perlin-dissolve.mdx b/content/docs/transitions/perlin-dissolve.mdxindex b266b491..0b4819b5 100644--- a/content/docs/transitions/perlin-dissolve.mdx+++ b/content/docs/transitions/perlin-dissolve.mdx@@ -1,6 +1,16 @@---title: Perlin Dissolvedescription: Sweep a perlin-noise threshold across the frame to dissolve into the next scene+component: perlin-dissolve+vibe: premium+length: 104+useWhen:+ - "Organic, atmospheric chapter changes — nature, ambient, calm product films."+ - "The two scenes differ strongly in content — the noise field neutralizes the mismatch."+ - "You want the classic film-dissolve feel with texture instead of a plain crossfade."+avoidWhen:+ - "Fast cuts — the threshold sweep needs ~100 frames to read as a sweep, not a flicker."+ - "Sharp geometric brand language — the noise is deliberately unstructured; use `dither-dissolve`."---<ComponentPreview name="perlin-dissolve" />diff --git a/content/docs/transitions/push-through.mdx b/content/docs/transitions/push-through.mdxindex 4f0d538e..1bc51ab7 100644--- a/content/docs/transitions/push-through.mdx+++ b/content/docs/transitions/push-through.mdx@@ -1,6 +1,16 @@---title: Push Throughdescription: Dolly through the outgoing scene while the next one approaches from the depth+component: push-through+vibe: premium+length: 40+useWhen:+ - "The narrative moves deeper into a topic — zooming in on a feature, entering a product, chapter descent."+ - "A climactic arrival: the CTA or logo scene deserves the camera physically landing on it."+ - "You want spatial continuity between scenes without any texture or overlay."+avoidWhen:+ - "Scenes are peers moving sideways — use `whip-pan`; the push implies hierarchy (outer → inner)."+ - "Dense text fills the outgoing scene edge-to-edge — the scale-up crops it awkwardly mid-flight."---<ComponentPreview name="push-through" />diff --git a/content/docs/transitions/ripple-zoom.mdx b/content/docs/transitions/ripple-zoom.mdxindex e264bac6..c2574321 100644--- a/content/docs/transitions/ripple-zoom.mdx+++ b/content/docs/transitions/ripple-zoom.mdx@@ -1,6 +1,16 @@---title: Ripple Zoomdescription: Fly the camera through the center of grainy ripple rings while the next scene approaches from the depth+component: ripple-zoom+vibe: premium+length: 88+useWhen:+ - "A hero statement or logo deserves a camera move — the dolly-through-rings reads as arriving at the point."+ - "The narrative zooms in: overview → detail, product → feature, chapter → moment."+ - "The video already uses the grain-gradient family (grain-dissolve, wave-wipe) — same texture language."+avoidWhen:+ - "The incoming scene has an opaque full-frame background — it hides the field and kills the depth illusion."+ - "Scenes chain rapidly — the fly-through needs ~88 frames; shorter reads as a scale pop."---<ComponentPreview name="ripple-zoom" />diff --git a/content/docs/transitions/slide-swap.mdx b/content/docs/transitions/slide-swap.mdxindex 62284baa..9ef8d76a 100644--- a/content/docs/transitions/slide-swap.mdx+++ b/content/docs/transitions/slide-swap.mdx@@ -1,6 +1,17 @@---title: Slide Swapdescription: Shove one scene off the canvas and spring the next in from the opposite edge+component: slide-swap+vibe: clean+length: 210+useWhen:+ - "You want a scene-to-scene grammar with no overlap at all — the outgoing content is fully gone before the incoming content's first frame."+ - "The canvas colour is constant across the whole sequence and only the content should travel."+ - "The video is a run of short claims where a directional shove keeps the pace up, and `axis` lets you pick horizontal or vertical for the whole run."+avoidWhen:+ - "The stage colour has to change between scenes — this sequencer paints one constant canvas, while `spring-settle` crossfades the background inside a dedicated gap."+ - "You need a presentation to drop into a `TransitionSeries` between two `<Sequence>`s; this owns its own scene list, so reach for `push-through` or `whip-pan` instead."+ - "What is swapping is a single phrase rather than a whole scene — `shared-axis-y` or `fade-through` replace text without moving the entire stage."---<ComponentPreview name="slide-swap" />diff --git a/content/docs/transitions/smoke-dissolve.mdx b/content/docs/transitions/smoke-dissolve.mdxindex 2ac0b9c3..8e05cebc 100644--- a/content/docs/transitions/smoke-dissolve.mdx+++ b/content/docs/transitions/smoke-dissolve.mdx@@ -1,6 +1,16 @@---title: Smoke Dissolvedescription: Expand a smoke ring outward across the frame to reveal the next scene+component: smoke-dissolve+vibe: premium+length: 104+useWhen:+ - "A reveal should feel like emerging from mist — moody, cinematic, mysterious openings."+ - "Center-out motion suits the content: the new scene is literally born at the middle of the frame."+ - "Dark palettes — the smoke ring reads best against deep backgrounds."+avoidWhen:+ - "Fast cuts — the ring expansion needs ~100 frames of runway."+ - "Bright, flat, poster-like scenes — the smoke loses definition on light backgrounds."---<ComponentPreview name="smoke-dissolve" />diff --git a/content/docs/transitions/spring-settle.mdx b/content/docs/transitions/spring-settle.mdxindex 741d775c..f85cca9f 100644--- a/content/docs/transitions/spring-settle.mdx+++ b/content/docs/transitions/spring-settle.mdx@@ -1,6 +1,17 @@---title: Spring Settledescription: Shrink a scene away as one group, hold the stage empty for a beat, then land the next one from above+component: spring-settle+vibe: premium+length: 213+useWhen:+ - "The stage colour changes from scene to scene — the crossfade happens inside the empty gap, so it never muddies two scenes together."+ - "Each scene is a small stack of elements that should land one after another, which is what `SpringSettleItem` and its compressed stagger are for."+ - "You want a deliberate, unhurried cadence: the outgoing scene shrinks away as one group and the next settles down onto the stage from slightly larger than life."+avoidWhen:+ - "You want directional momentum between scenes; `slide-swap` shoves the outgoing content off one edge and springs the next in from the opposite one."+ - "You need a presentation to drop into a `TransitionSeries` between two `<Sequence>`s; this owns its own scene list, so use `push-through` or `zoom-blur` instead."+ - "The scene should keep breathing while it holds — content is perfectly still between boundaries here, so wrap it in `drift` if you want a constant camera push."---<ComponentPreview name="spring-settle" />diff --git a/content/docs/transitions/swirl-dissolve.mdx b/content/docs/transitions/swirl-dissolve.mdxindex d55ee65a..2a3a7a4e 100644--- a/content/docs/transitions/swirl-dissolve.mdx+++ b/content/docs/transitions/swirl-dissolve.mdx@@ -1,6 +1,16 @@---title: Swirl Dissolvedescription: Unwind a swirl shader open and wind it shut to reveal the next scene+component: swirl-dissolve+vibe: premium+length: 104+useWhen:+ - "A dramatic chapter break where the frame should visibly transform — reveals, act changes."+ - "The brand can carry hypnotic, rotational motion; band colors take brand palettes well."+ - "You have runtime to spare — the full twist-untwist arc needs ~3.5 seconds."+avoidWhen:+ - "Fast cuts — under ~80 frames the twist arc collapses into noise."+ - "Repeated use within one video — the vortex is a statement move, one per video."---<ComponentPreview name="swirl-dissolve" />diff --git a/content/docs/transitions/warp-dissolve.mdx b/content/docs/transitions/warp-dissolve.mdxindex f4798b12..1080b82a 100644--- a/content/docs/transitions/warp-dissolve.mdx+++ b/content/docs/transitions/warp-dissolve.mdx@@ -1,6 +1,16 @@---title: Warp Dissolvedescription: Melt the outgoing scene into a folding domain-warp field that straightens back out into the next scene+component: warp-dissolve+vibe: premium+length: 76+useWhen:+ - "Moving between chapters or moods — the melt reads as time passing or context shifting."+ - "The brand is organic, creative, or experimental; the field colors take brand palettes well."+ - "You want a slow, textured transition that holds attention for two-plus seconds."+avoidWhen:+ - "The transition must be fast — under ~50 frames the melt has no room to read and looks like a smeared crossfade."+ - "Scenes are spatially related steps of one flow — use a directional move instead of a dissolve."---<ComponentPreview name="warp-dissolve" />diff --git a/content/docs/transitions/wave-wipe.mdx b/content/docs/transitions/wave-wipe.mdxindex 93fda1dc..e9183764 100644--- a/content/docs/transitions/wave-wipe.mdx+++ b/content/docs/transitions/wave-wipe.mdx@@ -1,6 +1,16 @@---title: Wave Wipedescription: Sweep a grainy wave up across the frame, covering the outgoing scene and revealing the next one from below+component: wave-wipe+vibe: premium+length: 60+useWhen:+ - "The transition should feel like physical motion — a swell washing over the frame, tides, page-over-page."+ - "Scenes stack vertically in the narrative: the next chapter literally arrives from below."+ - "The video has a textured, analog tone that the grain complements."+avoidWhen:+ - "Scenes relate horizontally (steps in a flow) — the vertical sweep fights the reading direction."+ - "The tone is crisp and minimal — the grain texture adds visual noise by design."---<ComponentPreview name="wave-wipe" />diff --git a/content/docs/transitions/whip-pan.mdx b/content/docs/transitions/whip-pan.mdxindex c2dc7dc1..11e1c45b 100644--- a/content/docs/transitions/whip-pan.mdx+++ b/content/docs/transitions/whip-pan.mdx@@ -1,6 +1,16 @@---title: Whip Pandescription: Whip the camera sideways with motion blur so both scenes fly through the frame in one move+component: whip-pan+vibe: playful+length: 26+useWhen:+ - "Cuts need to feel fast and energetic — feature-to-feature jumps, montage rhythm, tech demos."+ - "Scenes are peers in a sequence and the narrative moves sideways (or up/down a stack)."+ - "You need the workhorse directional cut — this is the default kinetic transition of the catalog."+avoidWhen:+ - "The moment is calm or contemplative — the whip reads as urgency; use `focus-pull`."+ - "More than ~3 whips in a row in the same direction — vary direction or alternate with `fade-through`."---<ComponentPreview name="whip-pan" />diff --git a/content/docs/transitions/zoom-blur.mdx b/content/docs/transitions/zoom-blur.mdxindex 8692c0da..11abe0d0 100644--- a/content/docs/transitions/zoom-blur.mdx+++ b/content/docs/transitions/zoom-blur.mdx@@ -1,6 +1,16 @@---title: Zoom Blurdescription: Push the outgoing scene through the viewer while the incoming one resolves out of blur+component: zoom-blur+vibe: clean+length: 18+useWhen:+ - "You need a default, general-purpose cut for a product demo — the de-facto workhorse transition of the catalog."+ - "The rhythm can be anything — it reads clean at both fast and slow cadences."+ - "You want a sense of depth without committing to a strong directional statement."+avoidWhen:+ - "The cut needs lateral direction — use `whip-pan`."+ - "The moment needs explicit hierarchy descent (outer → inner) — use `push-through`."---<ComponentPreview name="zoom-blur" />diff --git a/content/docs/typography/blur-out-up.mdx b/content/docs/typography/blur-out-up.mdxindex df6db70d..70e1c65a 100644--- a/content/docs/typography/blur-out-up.mdx+++ b/content/docs/typography/blur-out-up.mdx@@ -1,6 +1,17 @@---title: Blur Out Updescription: Words arrive clean and depart upward with increasing blur for airy exits+component: blur-out-up+vibe: premium+length: 90+useWhen:+ - "A title or tagline needs a graceful upward exit before the next scene cuts in."+ - "The scene calls for an airy, editorial tone — text that drifts rather than snaps away."+ - "You need a per-word stagger on exit without any blur-in entrance (the arrival is clean)."+avoidWhen:+ - "You want a blurred entrance that resolves to crisp — that is `focus-blur-resolve`, which opens blurry and sharpens in."+ - "The text is a paragraph or multi-line block where per-word stagger would drag too long; use `line-by-line-slide` for multi-line exits instead."+ - "The scene needs a hard cut or a simple opacity fade, not an upward drift — use `fade-through` for a clean A→B replacement."---<ComponentPreview name="blur-out-up" />diff --git a/content/docs/typography/bottom-up-letters.mdx b/content/docs/typography/bottom-up-letters.mdxindex 4ffe51e9..647a0a68 100644--- a/content/docs/typography/bottom-up-letters.mdx+++ b/content/docs/typography/bottom-up-letters.mdx@@ -1,6 +1,17 @@---title: Bottom-Up Lettersdescription: Letters rise from below in a pronounced staircase, one symbol at a time+component: bottom-up-letters+vibe: clean+length: 60+useWhen:+ - "A short punchy word or acronym should land with clear, visible per-character energy."+ - "The scene has a slow reveal cadence where the staircase wave is the hero moment."+ - "You want a crisp, sharp reveal without any softness or blur at all."+avoidWhen:+ - "The text is a full sentence or phrase — the high stagger makes long strings feel sluggish; use `per-character-rise` (faster, more even) or `mask-reveal-up` (line-level) instead."+ - "You want blur or softness in the reveal — `blur-out-up` or `focus-blur-resolve` add atmosphere that this component deliberately omits."+ - "The entrance should read as smooth and unified rather than letter-by-letter theatrical; use `micro-scale-fade` for a single calm pop."---<ComponentPreview name="bottom-up-letters" />diff --git a/content/docs/typography/fade-through.mdx b/content/docs/typography/fade-through.mdxindex 55efc56c..4289ad8e 100644--- a/content/docs/typography/fade-through.mdx+++ b/content/docs/typography/fade-through.mdx@@ -1,6 +1,17 @@---title: Fade Throughdescription: Old text fades out as new fades in with a soft delay, Material-style+component: fade-through+vibe: clean+length: 90+useWhen:+ - "One label, stat, or short phrase needs to swap cleanly into another in the same slot."+ - "The transition should be neutral and unobtrusive — content changes, nothing moves."+ - "You're following Material motion guidelines where the gap between out and in reinforces the content change."+avoidWhen:+ - "You want the incoming words to arrive one by one — use `per-word-crossfade` for a sequential word-level fade instead."+ - "The A→B swap should carry kinetic weight or directional momentum — use `line-by-line-slide` (slide direction) or `blur-out-up` (upward drift)."+ - "There is no outgoing text (first entrance only) — skip the \"from\" slot and use `micro-scale-fade` or `mask-reveal-up` for a single entrance."---<ComponentPreview name="fade-through" />diff --git a/content/docs/typography/focus-blur-resolve.mdx b/content/docs/typography/focus-blur-resolve.mdxindex 43aa005e..a2e4a698 100644--- a/content/docs/typography/focus-blur-resolve.mdx+++ b/content/docs/typography/focus-blur-resolve.mdx@@ -1,6 +1,18 @@---title: Focus Blur Resolvedescription: A premium focus pull from heavy blur to crisp text, then a soft blur-out exit+component: focus-blur-resolve+vibe: premium+length: 90+useWhen:+ - "A hero word or short phrase should feel like a camera lens pulling into focus."+ - "The scene calls for a full in-and-out arc in a single component without composing separate entrance and exit clips."+ - "Premium cinematic aesthetics are required — the blur depth conveys intentional production quality."+avoidWhen:+ - "You want a clean departure upward after a crisp entrance — that arc belongs to `blur-out-up`, which arrives clean and exits with upward blur."+ - "The text is multiple lines or a paragraph — the blur radius is designed for a single short phrase; use `mask-reveal-up` or `line-by-line-slide` for multi-line reveals."+ - "The entrance should be sharp from frame one — use `kinetic-center-build` or `per-character-rise` when there should be no blurry opener."+ - "You want a blur entrance that holds crisp with no exit — `focus-blur-resolve` forces a blur-out departure; use `soft-blur-in` for an entrance-only blur reveal."---<ComponentPreview name="focus-blur-resolve" />diff --git a/content/docs/typography/hand-count.mdx b/content/docs/typography/hand-count.mdxindex 9464d838..243b933a 100644--- a/content/docs/typography/hand-count.mdx+++ b/content/docs/typography/hand-count.mdx@@ -1,6 +1,17 @@---title: Hand Countdescription: A number that counts up in stop-motion poses, rewritten by hand at every pose+component: hand-count+vibe: paper+length: 54+useWhen:+ - "A stat, price, or count belongs in a hand-made scene — the number should arrive by being written, not by rolling."+ - "A paper pricing reveal or year-in-review needs its figure in the same voice as the rest of the shot."+ - "You want a unit or currency written in the same hand as the digits — `prefix` and `suffix` jitter along with them."+avoidWhen:+ - "The scene is a slick product UI or a dashboard metric — use `rolling-number` or `number-wheel`, which glide a mechanical typeface."+ - "You need per-digit odometer choreography — that is `number-wheel`'s job."+ - "You need locale grouping separators (`1,000`) or full currency formatting; `prefix` and `decimals` are the whole surface here."---<ComponentPreview name="hand-count" />diff --git a/content/docs/typography/handwrite.mdx b/content/docs/typography/handwrite.mdxindex da89e946..f6a9fd38 100644--- a/content/docs/typography/handwrite.mdx+++ b/content/docs/typography/handwrite.mdx@@ -1,6 +1,17 @@---title: Handwritedescription: Handwritten text laid down letter by letter on a quantized stop-motion clock+component: handwrite+vibe: paper+length: 120+useWhen:+ - "Captions, labels, and headlines should read as pen-written on paper — the core text voice of stop-motion scrapbook scenes."+ - "The scene already ticks on the stop-motion clock and the text must share its tempo rather than glide against it."+ - "You need the writing time up front: `handwriteDuration` sizes the `<Sequence>` exactly."+avoidWhen:+ - "You are simulating a terminal or an input being typed into — use `typewriter`."+ - "The reveal should be smooth on the real 30fps clock — use `soft-blur-in` or `per-character-rise`."+ - "The whole sheet should wobble too: that is `paper-wobble` wrapped around this, not a prop here."---<ComponentPreview name="handwrite" />diff --git a/content/docs/typography/infinite-marquee.mdx b/content/docs/typography/infinite-marquee.mdxindex eab58203..9994e92c 100644--- a/content/docs/typography/infinite-marquee.mdx+++ b/content/docs/typography/infinite-marquee.mdx@@ -1,6 +1,17 @@---title: Infinite Marqueedescription: A continuously scrolling horizontal text strip that loops seamlessly+component: infinite-marquee+vibe: clean+length: 180+useWhen:+ - "A scene needs ambient motion in the background or as a decorative band between sections."+ - "Looping brand words, feature names, or a tagline should scroll continuously without a defined start/end."+ - "A ticker-style lower-third or full-bleed text treatment is required for the full clip duration."+avoidWhen:+ - "The text should enter, hold, then exit — that is a reveal animation, not a ticker; use `blur-out-up` or `mask-reveal-up` instead."+ - "You need 3D perspective depth on the scrolling strip — use `perspective-marquee` for a tilted, depth-of-field version."+ - "The marquee should stop or snap to a specific word — this component loops forever with no hold state; compose a `Sequence` with a static slide instead."---<ComponentPreview name="infinite-marquee" />diff --git a/content/docs/typography/ink-underline.mdx b/content/docs/typography/ink-underline.mdxindex 946b6df9..dea81e64 100644--- a/content/docs/typography/ink-underline.mdx+++ b/content/docs/typography/ink-underline.mdx@@ -1,6 +1,15 @@---title: Ink Underlinedescription: A hand-dragged ink stroke that draws itself across in a few stop-motion poses+component: ink-underline+vibe: paper+length: 120+useWhen:+ - "A hand-dragged ink underline belongs beneath a written headline, URL, or stat — pairs with `handwrite`, with `delay` set from `handwriteDuration`."+ - "The scene already runs on the stop-motion clock and the stroke should arrive in the same discrete poses."+avoidWhen:+ - "You are painting a highlight behind a word inside a sentence — use `marker-highlight`."+ - "You want to circle or strike through something: neither is this component."---<ComponentPreview name="ink-underline" />diff --git a/content/docs/typography/inline-highlight.mdx b/content/docs/typography/inline-highlight.mdxindex 3a62f4db..f9d7f765 100644--- a/content/docs/typography/inline-highlight.mdx+++ b/content/docs/typography/inline-highlight.mdx@@ -1,6 +1,17 @@---title: Inline Highlightdescription: Animate one word inside a sentence from a base color to a brand color+component: inline-highlight+vibe: clean+length: 90+useWhen:+ - "One keyword inside a sentence needs to draw attention through a color shift without any background decoration."+ - "The text is already visible and a subtle emphasis beat is needed mid-scene, not a full entrance."+ - "Clean, minimal brand-color callout is required — no physical marker, no underline, just the color pop."+avoidWhen:+ - "You want a physical drawn marker or filled background behind the word — use `marker-highlight` for a visible paint-stroke effect instead."+ - "The entire sentence is new and needs to enter — this component is for emphasis within existing text, not a reveal; use `mask-reveal-up` or `per-word-crossfade` for full entrances."+ - "Multiple words across the sentence need to highlight in sequence — this highlights one span; compose multiple `Sequence`-wrapped instances or use `kinetic-center-build` for a word-by-word build."---<ComponentPreview name="inline-highlight" />diff --git a/content/docs/typography/kinetic-center-build.mdx b/content/docs/typography/kinetic-center-build.mdxindex 4f61da01..60d10a1e 100644--- a/content/docs/typography/kinetic-center-build.mdx+++ b/content/docs/typography/kinetic-center-build.mdx@@ -1,6 +1,17 @@---title: Kinetic Center Builddescription: Words enter from the right and push the line until the full phrase locks centered+component: kinetic-center-build+vibe: premium+length: 60+useWhen:+ - "A short headline should build word by word with satisfying kinetic momentum, locking centered at the end."+ - "The reveal itself is the hero moment — the growing centered line carries visual weight through motion."+ - "Premium product or brand video needs a high-energy entrance for a 3–6 word phrase."+avoidWhen:+ - "The text is long (7+ words) — the centering re-balance on each word becomes distracting; use `line-by-line-slide` for multi-word or multi-line phrases."+ - "The entrance should feel calm and neutral rather than kinetic — use `micro-scale-fade` or `mask-reveal-up` for composed, quiet reveals."+ - "Words should fade in sequentially with a vertical drift rather than push from the right — use `per-word-crossfade` for that calm keynote rhythm."---<ComponentPreview name="kinetic-center-build" />diff --git a/content/docs/typography/line-by-line-slide.mdx b/content/docs/typography/line-by-line-slide.mdxindex e99d1022..e582453b 100644--- a/content/docs/typography/line-by-line-slide.mdx+++ b/content/docs/typography/line-by-line-slide.mdx@@ -1,6 +1,17 @@---title: Line-by-Line Slidedescription: Each line slides in from the left with a staggered flow then exits to the right+component: line-by-line-slide+vibe: clean+length: 90+useWhen:+ - "A multi-line headline or short paragraph needs a flowing, line-by-line entrance with a matching exit."+ - "Directional slide motion (left-in / right-out) should underscore the reading rhythm of the text."+ - "A body-copy-style reveal is needed for bullet points or list items staged as stacked lines."+avoidWhen:+ - "The text is a single short phrase — the stagger has nothing to stage; use `mask-reveal-up` or `per-character-rise` for single-line reveals instead."+ - "The reveal should move upward rather than slide horizontally — use `mask-reveal-up` (upward, masked) or `blur-out-up` (upward, blurred exit)."+ - "The lines should not exit — this component slides lines out to the right; for a hold-in-place reveal, use `mask-reveal-up`."---<ComponentPreview name="line-by-line-slide" />diff --git a/content/docs/typography/marker-highlight.mdx b/content/docs/typography/marker-highlight.mdxindex e20b0a84..1c3c283c 100644--- a/content/docs/typography/marker-highlight.mdx+++ b/content/docs/typography/marker-highlight.mdx@@ -1,6 +1,17 @@---title: Marker Highlightdescription: A colored marker block draws behind a phrase while the text color shifts+component: marker-highlight+vibe: playful+length: 90+useWhen:+ - "A key phrase inside a sentence needs a physical, hand-drawn-feeling highlight that visually underscores the word."+ - "A playful or educational tone is appropriate and the visible paint stroke adds expressive energy."+ - "The brand color should appear as a background fill rather than a text color shift."+avoidWhen:+ - "You want a subtle color-only emphasis with no visible background — use `inline-highlight` for a clean color-shift with no marker block."+ - "The entire sentence is new text that needs to enter the scene — both highlight components are emphasis tools, not entrances; use `mask-reveal-up` or `per-word-crossfade` for full reveals."+ - "The scene tone is minimal or premium and a bold painted marker would clash — use `inline-highlight` for a quieter callout."---<ComponentPreview name="marker-highlight" />diff --git a/content/docs/typography/mask-reveal-up.mdx b/content/docs/typography/mask-reveal-up.mdxindex b359c749..484047d3 100644--- a/content/docs/typography/mask-reveal-up.mdx+++ b/content/docs/typography/mask-reveal-up.mdx@@ -1,6 +1,17 @@---title: Mask Reveal Updescription: Lines reveal upward with a soft masked feel and compact stagger+component: mask-reveal-up+vibe: clean+length: 90+useWhen:+ - "A multi-line headline or stacked list needs a clean, contained upward reveal that holds on screen."+ - "The reveal should feel composed and intentional — no overshooting, no blur, no lateral movement."+ - "A neutral entrance is needed that works across tones (product, editorial, corporate) without imposing personality."+avoidWhen:+ - "You need an exit animation too — `mask-reveal-up` holds in place after reveal; use `line-by-line-slide` for a reveal that also exits to the right."+ - "The reveal should be character-level rather than line-level — use `per-character-rise` (clean, sharp) or `bottom-up-letters` (staircase, dramatic) for letter-by-letter entrances."+ - "Blur or atmospheric softness should accompany the upward motion — use `blur-out-up` (blurred exit) or `focus-blur-resolve` (blurred entrance) instead."---<ComponentPreview name="mask-reveal-up" />diff --git a/content/docs/typography/matrix-decode.mdx b/content/docs/typography/matrix-decode.mdxindex 2c7da346..e9ce9802 100644--- a/content/docs/typography/matrix-decode.mdx+++ b/content/docs/typography/matrix-decode.mdx@@ -1,6 +1,17 @@---title: Matrix Decodedescription: Random scramble resolves left-to-right into target text+component: matrix-decode+vibe: tech+length: 90+useWhen:+ - "A hacker, terminal, or cyberpunk aesthetic is required and the scramble-to-reveal glyph effect is on-brand."+ - "A short code, token, or technical label should appear as if being deciphered in real time."+ - "The scene needs a reveal that feels procedural and data-driven rather than designed."+avoidWhen:+ - "The content is a human sentence or marketing copy — the glitchy scramble reads as broken text to non-technical audiences; use `typewriter` for a clean character-by-character reveal with a more legible progression."+ - "The tone is premium or editorial — use `focus-blur-resolve` or `blur-out-up` for atmospheric reveals without the glitch aesthetic."+ - "The text is long — the left-to-right lock is designed for short labels and codes; long strings extend `revealDuration` to an uncomfortable length."---<ComponentPreview name="matrix-decode" />diff --git a/content/docs/typography/micro-scale-fade.mdx b/content/docs/typography/micro-scale-fade.mdxindex 55e6e702..001f8687 100644--- a/content/docs/typography/micro-scale-fade.mdx+++ b/content/docs/typography/micro-scale-fade.mdx@@ -1,6 +1,17 @@---title: Micro Scale Fadedescription: A calm, tiny scale pop for subtle premium polish on labels and headings+component: micro-scale-fade+vibe: clean+length: 60+useWhen:+ - "A label, subheading, or supporting text needs an entrance that feels polished without drawing attention to itself."+ - "The scene already has a hero animation and supporting text should enter quietly underneath it."+ - "A single block of text needs to appear in a neutral, cross-tone way that works for product, SaaS, or corporate video."+avoidWhen:+ - "The reveal should be the hero moment with visible kinetic weight — use `kinetic-center-build` or `per-character-rise` for entrances that command attention."+ - "Text should enter per-character or per-word rather than as a unified block — use `bottom-up-letters`, `per-character-rise`, or `per-word-crossfade` for staged reveals."+ - "The text needs to also exit — `micro-scale-fade` is entrance-only; use `blur-out-up` or `fade-through` when an exit arc is required."---<ComponentPreview name="micro-scale-fade" />diff --git a/content/docs/typography/number-wheel.mdx b/content/docs/typography/number-wheel.mdxindex 3d70ec81..36a86d42 100644--- a/content/docs/typography/number-wheel.mdx+++ b/content/docs/typography/number-wheel.mdx@@ -1,6 +1,18 @@---title: Number Wheeldescription: Odometer that rolls a number from one value to another with direction inferred from the values+component: number-wheel+vibe: data+length: 112+useWhen:+ - "A metric, stat, or count should animate to its value in a satisfying odometer roll."+ - "A data-driven scene needs a number to tick up (or down) to convey growth, reduction, or change."+ - "Dashboard-style video content requires a numeric reveal with clear direction and mechanical rhythm."+avoidWhen:+ - "The value is not an integer — this component is designed for whole numbers; format decimals upstream before passing them in."+ - "The number should appear all at once without rolling — use `micro-scale-fade` for a static entrance of a pre-formatted number string."+ - "The scene requires text alongside the number to animate together — compose `NumberWheel` with a static text node in a flex container rather than embedding units in the `to` value."+ - "The value carries a prefix or suffix like `$99` or `1.2M` — use `slot-machine-roll` (accepts arbitrary strings); for very large multi-digit metrics counting up, `rolling-number` is purpose-tuned."---<ComponentPreview name="number-wheel" />diff --git a/content/docs/typography/per-character-rise.mdx b/content/docs/typography/per-character-rise.mdxindex c38a7162..89462e7b 100644--- a/content/docs/typography/per-character-rise.mdx+++ b/content/docs/typography/per-character-rise.mdx@@ -1,6 +1,17 @@---title: Per Character Risedescription: Letters slide up from below with no blur - crisp and kinetic+component: per-character-rise+vibe: clean+length: 60+useWhen:+ - "A short word or phrase needs a crisp, sharp character-by-character entrance with even, readable stagger."+ - "The tone is clean and precise — no blur, no dramatic staircase, just steady letters rising into position."+ - "A heading needs more kinetic energy than `micro-scale-fade` but less theatrical drama than `bottom-up-letters`."+avoidWhen:+ - "You want a dramatic staircase effect where each letter visibly lags the previous — use `bottom-up-letters` for the pronounced, wide-gap stagger instead."+ - "The text is multiple lines and should reveal line-by-line — use `mask-reveal-up` (upward, masked) or `line-by-line-slide` (directional) for line-level reveals."+ - "The reveal should include blur or atmospheric softness — use `focus-blur-resolve` (blurred entrance) or `blur-out-up` (blurred exit) when sharpness is not the goal."---<ComponentPreview name="per-character-rise" />diff --git a/content/docs/typography/per-word-crossfade.mdx b/content/docs/typography/per-word-crossfade.mdxindex 038bc58f..1b4a4563 100644--- a/content/docs/typography/per-word-crossfade.mdx+++ b/content/docs/typography/per-word-crossfade.mdx@@ -1,6 +1,17 @@---title: Per-Word Crossfadedescription: One phrase fades out as the next fades in, word by word+component: per-word-crossfade+vibe: clean+length: 90+useWhen:+ - "Two short phrases need to swap with a soft, word-by-word transition that reads as calm and composed."+ - "A keynote-style slide replacement is needed — the sequential word drift matches presentation pacing."+ - "The A→B content change should feel deliberate but unhurried, with the crossfade reinforcing continuity."+avoidWhen:+ - "The transition should be a single-block fade with no word-level staging — use `fade-through` for a unified opacity swap instead."+ - "You want the incoming words to build upward or slide in rather than drift-and-fade — use `line-by-line-slide` or `mask-reveal-up` for directional entrances."+ - "There is no outgoing text (first entrance only) — use `micro-scale-fade` or `per-character-rise` for a standalone reveal without a `fromText`."---<ComponentPreview name="per-word-crossfade" />diff --git a/content/docs/typography/perspective-marquee.mdx b/content/docs/typography/perspective-marquee.mdxindex d28309d8..897580fc 100644--- a/content/docs/typography/perspective-marquee.mdx+++ b/content/docs/typography/perspective-marquee.mdx@@ -1,6 +1,17 @@---title: Perspective Marqueedescription: A 3D-tilted infinite marquee with depth-of-field blur on items rolling toward the horizon+component: perspective-marquee+vibe: premium+length: 240+useWhen:+ - "A dark, cinematic background treatment is needed with text rolling into a 3D vanishing point."+ - "Feature names, brand words, or a tagline list should scroll with depth and atmosphere rather than flat."+ - "The scene calls for a premium looping background element that holds for 4–8 seconds without feeling static."+avoidWhen:+ - "A flat, 2D looping ticker is sufficient — use `infinite-marquee` for a simpler, lighter strip with no perspective transform."+ - "The marquee should stop or the words should land on a specific item — both marquee components loop indefinitely; compose a `Sequence` with a static component for a hold state."+ - "The background is light-colored — the default `fadeColor=\"#050505\"` creates edge fades tuned for dark scenes; adapt carefully or use `infinite-marquee` on light backgrounds."---<ComponentPreview name="perspective-marquee" />diff --git a/content/docs/typography/rgb-glitch-text.mdx b/content/docs/typography/rgb-glitch-text.mdxindex 8dcbbc43..29ca7646 100644--- a/content/docs/typography/rgb-glitch-text.mdx+++ b/content/docs/typography/rgb-glitch-text.mdx@@ -1,6 +1,17 @@---title: RGB Glitch Textdescription: Three RGB-offset text copies jitter for a few frames to create a chromatic aberration glitch+component: rgb-glitch-text+vibe: tech+length: 90+useWhen:+ - "A tech, hacker, or cyberpunk scene needs a moment of digital corruption on a title."+ - "You want a deterministic glitch that renders identically every time (use `seed` to vary it per clip)."+ - "The entrance is already complete and you want a brief mid-scene disruption rather than a full reveal animation."+avoidWhen:+ - "You need a full text entrance animation — the glitch is a momentary effect, not a reveal; use `tracking-in` or `soft-blur-in` to bring text in."+ - "The brand aesthetic is clean or premium — RGB splits read as intentionally broken; use `shimmer-sweep` for a high-end shimmer moment instead."+ - "The text is long — offset copies of a full paragraph are illegible during the glitch window; keep it to a short word or phrase."---<ComponentPreview name="rgb-glitch-text" />diff --git a/content/docs/typography/rolling-number.mdx b/content/docs/typography/rolling-number.mdxindex d8157d70..b36b993c 100644--- a/content/docs/typography/rolling-number.mdx+++ b/content/docs/typography/rolling-number.mdx@@ -1,6 +1,18 @@---title: Rolling Numberdescription: Odometer where every place rolls at its own speed, new places rising into view, settling exactly on the target value+component: rolling-number+vibe: data+length: 150+useWhen:+ - "Animating a large integer metric on a stats or milestone slide (revenue, signups, impressions)."+ - "You need each digit place to animate independently so the viewer can read the number building up."+ - "The `from`/`to` values are pure numbers with no currency symbol or unit mixed into the string."+avoidWhen:+ - "The value includes a prefix or suffix like `$99` or `1.2M` — use `slot-machine-roll` which accepts arbitrary strings instead."+ - "The number change is small or decorative and you want a playful reel feel rather than a data-serious odometer; `slot-machine-roll` reads friendlier."+ - "The counter is a secondary UI element that should feel lightweight — 150f is a long animation; shorten with `speed` or pick a simpler fade."+ - "The value is a small integer or needs to count DOWN — use `number-wheel` (direction inferred from `from`/`to`, lighter 112f); `rolling-number` is tuned for large multi-digit metrics counting up."---<ComponentPreview name="rolling-number" />diff --git a/content/docs/typography/rolodex-flip.mdx b/content/docs/typography/rolodex-flip.mdxindex 6472eea1..c3d874d4 100644--- a/content/docs/typography/rolodex-flip.mdx+++ b/content/docs/typography/rolodex-flip.mdx@@ -1,6 +1,16 @@---title: Rolodex Flipdescription: Cycle a word through a list of values with a 3D rolodex card flip+component: rolodex-flip+vibe: tech+length: 110+useWhen:+ - "Cycling package, feature, or value names inside a held line — install commands, \"works with X\" beats, plan-name cycling."+ - "The canonical \"any component, same command\" bit."+avoidWhen:+ - "The values are numbers with a counting narrative — use `number-wheel` or `rolling-number`."+ - "Only two values swap once — `value-swap`, `shared-axis-y`, or `per-word-crossfade` is lighter."+ - "The line reflows per value — the fixed sizer width shows a gap next to short values."---<ComponentPreview name="rolodex-flip" />diff --git a/content/docs/typography/scale-down-fade.mdx b/content/docs/typography/scale-down-fade.mdxindex 67b8a365..3ebedc7c 100644--- a/content/docs/typography/scale-down-fade.mdx+++ b/content/docs/typography/scale-down-fade.mdx@@ -1,6 +1,17 @@---title: Scale Down Fadedescription: Subtle premium settle-in with a restrained scale-down fade on exit+component: scale-down-fade+vibe: clean+length: 90+useWhen:+ - "A headline needs a confident, minimal entrance without any kinetic exaggeration."+ - "The surrounding content is already in motion and you need one element to settle calmly into focus."+ - "The brand is clean or corporate and bounce or blur would feel off-brand."+avoidWhen:+ - "You want energy or playfulness — the scale-down reads as composed, not exciting; use `spring-scale-in` for an overshoot bounce instead."+ - "The text should feel like it is being revealed rather than settling in — use `staggered-fade-up` or `soft-blur-in` for a character-by-character or word-by-word reveal."+ - "You need an exit animation — scale-down-fade is an entrance only; compose with a separate exit primitive inside a `<Sequence>`."---<ComponentPreview name="scale-down-fade" />diff --git a/content/docs/typography/shared-axis-y.mdx b/content/docs/typography/shared-axis-y.mdxindex 8050dde0..b2fdcb66 100644--- a/content/docs/typography/shared-axis-y.mdx+++ b/content/docs/typography/shared-axis-y.mdx@@ -1,6 +1,17 @@---title: Shared Axis Ydescription: Per-word hard-cut staircase transition for sharp editorial phrase swaps+component: shared-axis-y+vibe: clean+length: 90+useWhen:+ - "Swapping two text values in a slide-deck style transition (A → B → C chained in `<Sequence>`)."+ - "You want a crisp, editorial replacement without blur or scale — vertical word-by-word staircase reads as confident."+ - "The outgoing and incoming phrases are thematically related (before/after, old/new, step N / step N+1)."+avoidWhen:+ - "You only need to bring text in for the first time with no outgoing content — use `short-slide-down` or `staggered-fade-up` for a clean entrance instead."+ - "You want a depth or focus-shift feel between two contexts — use `shared-axis-z` which scales rather than slides for that spatial metaphor."+ - "The transition should feel playful or bouncy — the hard-cut staircase is intentionally sharp; use `spring-scale-in` for a springy swap."---<ComponentPreview name="shared-axis-y" />diff --git a/content/docs/typography/shared-axis-z.mdx b/content/docs/typography/shared-axis-z.mdxindex 9ee8855e..89048fb9 100644--- a/content/docs/typography/shared-axis-z.mdx+++ b/content/docs/typography/shared-axis-z.mdx@@ -1,6 +1,17 @@---title: Shared Axis Zdescription: Scale-based shared-axis transition for focus shifts and context depth+component: shared-axis-z+vibe: clean+length: 90+useWhen:+ - "Conveying a zoom-in narrative: moving from a broad context to a focused point."+ - "Transitioning between two text values where the second is a more specific or deeper layer of the first."+ - "Chaining multiple topic shifts in a `<Sequence>` where each swap should feel like a camera push forward."+avoidWhen:+ - "The swap is a lateral topic change with no depth relationship — use `shared-axis-y` for a horizontal-edit-style cut instead."+ - "You only need to bring text in for the first time with no outgoing content — use `scale-down-fade` or `soft-blur-in` for a single-text entrance."+ - "The scene already has a lot of scale motion and you need variety — mix in `shared-axis-y` to alternate the spatial grammar."---<ComponentPreview name="shared-axis-z" />diff --git a/content/docs/typography/shimmer-sweep.mdx b/content/docs/typography/shimmer-sweep.mdxindex 1f84067d..e1ae30f3 100644--- a/content/docs/typography/shimmer-sweep.mdx+++ b/content/docs/typography/shimmer-sweep.mdx@@ -1,6 +1,17 @@---title: Shimmer Sweepdescription: A bright shine travels across muted text to draw attention+component: shimmer-sweep+vibe: premium+length: 120+useWhen:+ - "Highlighting a product name or pricing tier with a refined, metallic gleam — luxury SaaS, pricing slides."+ - "The text is already visible and you want a continuous or looped attention effect rather than an entrance."+ - "The design calls for a dark background where a light sweep across dark text creates contrast without a harsh cut."+avoidWhen:+ - "You need the text to enter the scene — shimmer-sweep does not animate the text in; use `tracking-in` or `soft-blur-in` for the entrance, then layer a shimmer if needed."+ - "The brand aesthetic is casual or energetic — the metallic sweep reads as premium/luxury; use `spring-scale-in` or `staggered-fade-up` for a lighter feel."+ - "You want per-character color or gradient control — `shimmer-sweep` sweeps a single shine beam; use `rgb-glitch-text` for character-level color splitting."---<ComponentPreview name="shimmer-sweep" />diff --git a/content/docs/typography/short-slide-down.mdx b/content/docs/typography/short-slide-down.mdxindex a48b144d..e74a959d 100644--- a/content/docs/typography/short-slide-down.mdx+++ b/content/docs/typography/short-slide-down.mdx@@ -1,6 +1,17 @@---title: Short Slide Downdescription: Words drop in from above and stack into a centered multi-line composition+component: short-slide-down+vibe: clean+length: 60+useWhen:+ - "A multi-word headline should build its layout visibly — each word stacking to create a composed block."+ - "The scene is short and you need a fast (60f) entrance that still feels structured."+ - "You want vertical motion on entrance without a transition between two different texts."+avoidWhen:+ - "You are swapping between two text values — use `shared-axis-y` which handles the outgoing text exit properly."+ - "The text is a single word or short phrase that doesn't benefit from a stacking effect — use `scale-down-fade` or `soft-blur-in` for a cleaner single-unit entrance."+ - "You want horizontal entry motion — use `short-slide-right` for a left-to-right glide instead."---<ComponentPreview name="short-slide-down" />diff --git a/content/docs/typography/short-slide-right.mdx b/content/docs/typography/short-slide-right.mdxindex d22c6883..c1df5045 100644--- a/content/docs/typography/short-slide-right.mdx+++ b/content/docs/typography/short-slide-right.mdx@@ -1,6 +1,17 @@---title: Short Slide Rightdescription: The whole phrase glides in from the left while words reveal in sequence through opacity+component: short-slide-right+vibe: clean+length: 60+useWhen:+ - "A short headline should enter with horizontal momentum — reads as forward motion or progress."+ - "You want word-level opacity stagger layered on top of a single group translation, giving depth without complexity."+ - "The composition requires a fast (60f) entrance that feels purposeful and directional."+avoidWhen:+ - "You are transitioning between two texts — use `shared-axis-z` (depth) or `shared-axis-y` (vertical swap) which handle the outgoing content."+ - "You want vertical stacking motion — use `short-slide-down` where each word drops onto its own line to build a layout."+ - "The slide distance needs to be large or cinematic — `short-slide-right` is intentionally compact (default 24px); use a custom composition for a wide pan."---<ComponentPreview name="short-slide-right" />diff --git a/content/docs/typography/slot-machine-roll.mdx b/content/docs/typography/slot-machine-roll.mdxindex eb0f0210..83783e62 100644--- a/content/docs/typography/slot-machine-roll.mdx+++ b/content/docs/typography/slot-machine-roll.mdx@@ -1,6 +1,17 @@---title: Slot Machine Rolldescription: Vertical reel scrolls each character from an old value to a new value+component: slot-machine-roll+vibe: playful+length: 90+useWhen:+ - "Revealing a price change, plan upgrade, or before/after value where the string includes symbols (`$`, `%`, `×`)."+ - "You want a playful, casino-reel feel on a pricing or comparison slide."+ - "The values are short (1–6 characters) and the character-by-character drum motion will be legible."+avoidWhen:+ - "The value is a large pure integer like `1,240,000` — use `rolling-number` which animates each decimal place independently and reads as a serious data metric."+ - "The text is more than ~6 characters — long strings become hard to read while the reel spins; use `staggered-fade-up` to reveal a longer phrase."+ - "The brand tone is formal or data-driven — the slot machine metaphor is inherently playful; use `rolling-number` for a composed odometer feel."---<ComponentPreview name="slot-machine-roll" />diff --git a/content/docs/typography/soft-blur-in.mdx b/content/docs/typography/soft-blur-in.mdxindex a2fc5c5e..dce0c2a5 100644--- a/content/docs/typography/soft-blur-in.mdx+++ b/content/docs/typography/soft-blur-in.mdx@@ -1,6 +1,17 @@---title: Soft Blur Indescription: Per-character fade-in with a gentle blur and upward motion+component: soft-blur-in+vibe: premium+length: 60+useWhen:+ - "A hero headline needs the Apple-style per-character soft reveal — premium, airy, cinematic."+ - "The text is long enough that a word-by-word stagger would take too long; per-character stagger with blur reads faster."+ - "The overall scene is clean and bright, letting the blur-clear motion read clearly against the background."+avoidWhen:+ - "You want a hard exit animation — `soft-blur-in` is an entrance only; pair with `blur-out-up` in a `<Sequence>` for a matching exit."+ - "The vibe is tech, gritty, or high-energy — the soft blur reads as refined and calm; use `rgb-glitch-text` or `tracking-in` for a sharper feel."+ - "You are swapping between two texts — use `shared-axis-z` or `shared-axis-y` which handle both the outgoing and incoming content."---<ComponentPreview name="soft-blur-in" />diff --git a/content/docs/typography/spring-scale-in.mdx b/content/docs/typography/spring-scale-in.mdxindex 3c70e4b7..05584e1c 100644--- a/content/docs/typography/spring-scale-in.mdx+++ b/content/docs/typography/spring-scale-in.mdx@@ -1,6 +1,17 @@---title: Spring Scale Indescription: Words pop in with a soft overshoot scale, like a spring settling into place+component: spring-scale-in+vibe: playful+length: 60+useWhen:+ - "The scene calls for energy and bounce — product launches, celebration moments, fun CTAs."+ - "You want each word to feel like it physically snaps into place, giving kinetic weight to short phrases."+ - "The audience is consumer-facing and a playful entrance matches the brand tone."+avoidWhen:+ - "The brand is serious, corporate, or premium — spring bounce reads as casual; use `scale-down-fade` or `soft-blur-in` for a composed entrance instead."+ - "The text is long — many words bouncing in rapid succession becomes visually noisy; use `staggered-fade-up` for a calmer word-by-word reveal."+ - "You need precise timing for a word to land on a beat — spring physics are frame-accurate but the overshoot makes the visual \"land\" slightly after the spring resolves."---<ComponentPreview name="spring-scale-in" />diff --git a/content/docs/typography/staggered-fade-up.mdx b/content/docs/typography/staggered-fade-up.mdxindex 7738eef1..bc41eb76 100644--- a/content/docs/typography/staggered-fade-up.mdx+++ b/content/docs/typography/staggered-fade-up.mdx@@ -1,6 +1,17 @@---title: Staggered Fade Updescription: Words slide up and fade in sequentially with a wave-like cascade+component: staggered-fade-up+vibe: clean+length: 90+useWhen:+ - "A headline or body sentence is long and a simpler single-unit entrance would feel flat."+ - "You want a neutral, versatile word-by-word reveal that works across any brand tone."+ - "You need the text fully on screen by a known frame — `staggerDelay` × word count gives a predictable total duration."+avoidWhen:+ - "The text is very short (1–2 words) and the stagger has nothing to reveal gradually — use `scale-down-fade` or `spring-scale-in` for a single-unit entrance with more impact."+ - "You want a per-character (not per-word) reveal — use `soft-blur-in` for character-level stagger with a premium blur feel."+ - "The scene needs an exit animation — staggered-fade-up is entrance only; compose with a separate exit primitive inside a `<Sequence>`."---<ComponentPreview name="staggered-fade-up" />diff --git a/content/docs/typography/top-down-letters.mdx b/content/docs/typography/top-down-letters.mdxindex 80136c79..86e511fa 100644--- a/content/docs/typography/top-down-letters.mdx+++ b/content/docs/typography/top-down-letters.mdx@@ -1,6 +1,18 @@---title: Top-Down Lettersdescription: Letters descend from above in a pronounced staircase, one symbol at a time+component: top-down-letters+vibe: clean+length: 60+useWhen:+ - "A single uppercase word or short acronym should enter with structural weight — each letter landing like a stamp."+ - "The scene calls for a sharp, graphic title card where the sequential drop reinforces the word's rhythm."+ - "You want per-letter stagger with a pronounced vertical distance (default 46px) that reads clearly at large font sizes."+avoidWhen:+ - "The text is more than ~8 characters — many letters dropping sequentially stretches the animation and the last letters feel delayed; use `staggered-fade-up` for longer phrases."+ - "You want blur or softness on entry — `top-down-letters` is zero-blur by design; use `soft-blur-in` for the Apple-style per-character blur reveal."+ - "The stagger direction should be horizontal or spatial — use `short-slide-right` for a left-to-right group glide or `tracking-in` for a letter-spacing collapse instead."+ - "The letters should rise from below rather than drop from above — use `bottom-up-letters`, the identical-cadence upward mirror."---<ComponentPreview name="top-down-letters" />diff --git a/content/docs/typography/tracking-in.mdx b/content/docs/typography/tracking-in.mdxindex 1b2969b2..690e54db 100644--- a/content/docs/typography/tracking-in.mdx+++ b/content/docs/typography/tracking-in.mdx@@ -1,6 +1,17 @@---title: Tracking Indescription: Letter-spacing collapses and blur clears with a springy entrance+component: tracking-in+vibe: premium+length: 90+useWhen:+ - "A title word or brand name should feel like it is focusing into place — tracking collapse is the right metaphor for clarity, precision, or sharpness."+ - "The design is typographically driven and the letter-spacing motion is the centerpiece of the entrance."+ - "A premium or cinematic tone is required — the spring-driven collapse reads as designed and intentional, not incidental."+avoidWhen:+ - "You want per-character stagger — `tracking-in` moves all letters as one unit; use `soft-blur-in` for a per-character blur-and-rise stagger instead."+ - "The text is a sentence rather than a single bold word — wide initial tracking on a long phrase is illegible until it collapses; use `staggered-fade-up` for multi-word body text."+ - "The scene is playful or casual — the typographic tracking motion reads as serious and editorial; use `spring-scale-in` for a bouncy entrance instead."---<ComponentPreview name="tracking-in" />diff --git a/content/docs/typography/typewriter.mdx b/content/docs/typography/typewriter.mdxindex ad79883e..4ef64b44 100644--- a/content/docs/typography/typewriter.mdx+++ b/content/docs/typography/typewriter.mdx@@ -1,6 +1,17 @@---title: Typewriterdescription: Character-by-character text reveal with a deterministic blinking cursor+component: typewriter+vibe: clean+length: 120+useWhen:+ - "Simulating a command being typed into a terminal or input — pairs with `terminal-simulator`."+ - "A title should feel \"authored live\" rather than appearing all at once."+ - "You need the reveal duration to track text length predictably (`charsPerSecond` makes it deterministic)."+avoidWhen:+ - "The text is long — typing a paragraph at a readable speed eats far more frames than a viewer will wait; use `staggered-fade-up` or `blur-out-up` instead."+ - "You want a designed, weighted entrance (springy, blurred, kinetic) — typing reads as plain/utilitarian; reach for `tracking-in` or `kinetic-center-build`."+ - "Multiple lines should reveal together — typing is inherently sequential and single-stream."---<ComponentPreview name="typewriter" />diff --git a/content/docs/typography/value-swap.mdx b/content/docs/typography/value-swap.mdxindex 83c955e6..8e2059ab 100644--- a/content/docs/typography/value-swap.mdx+++ b/content/docs/typography/value-swap.mdx@@ -1,6 +1,15 @@---title: Value Swapdescription: Swap a value in place with a vertical slide so the layout never shifts+component: value-swap+vibe: clean+length: 100+useWhen:+ - "A value changes at a specific story beat — before/after price, status promotion, a hex/token flip."+ - "You control the exact swap frames."+avoidWhen:+ - "Values should cycle continuously as a montage — use `rolodex-flip` with its own rhythm instead."+ - "The value is a large pure number counting up — `rolling-number` or `number-wheel` reads as data."---<ComponentPreview name="value-swap" />diff --git a/content/docs/ui-blocks/animated-bar-chart.mdx b/content/docs/ui-blocks/animated-bar-chart.mdxindex 97eb40f9..4e7f23f9 100644--- a/content/docs/ui-blocks/animated-bar-chart.mdx+++ b/content/docs/ui-blocks/animated-bar-chart.mdx@@ -1,6 +1,17 @@---title: Animated Bar Chartdescription: Bars spring up from the baseline with a staggered cascade+component: animated-bar-chart+vibe: data+length: 90+useWhen:+ - "Showing comparative categorical metrics in a product demo — feature usage, plan distribution, benchmark scores."+ - "A business KPI or results slide needs a \"data revealed\" moment rather than a static screenshot."+ - "The dataset has a clear winner bar to build to (stagger naturally draws attention to the tallest last)."+avoidWhen:+ - "The data represents change over time — continuous trends belong in `animated-line-chart`, not bars."+ - "You want to visualize a sequential workflow or pipeline stages — use `progress-steps` instead."+ - "You have a single data point; one bar springing up looks degenerate — embed a number counter or use a text animation."---<ComponentPreview name="animated-bar-chart" />diff --git a/content/docs/ui-blocks/animated-line-chart.mdx b/content/docs/ui-blocks/animated-line-chart.mdxindex 94257b96..0ff0aa9b 100644--- a/content/docs/ui-blocks/animated-line-chart.mdx+++ b/content/docs/ui-blocks/animated-line-chart.mdx@@ -1,6 +1,17 @@---title: Animated Line Chartdescription: A line chart whose path draws on from left to right+component: animated-line-chart+vibe: data+length: 90+useWhen:+ - "Showing growth or trend over time — revenue curve, DAU climb, error-rate drop."+ - "A SaaS demo needs a \"hockey stick\" moment where the line visibly inflects upward."+ - "You want a single continuous reveal motion rather than per-bar stagger."+avoidWhen:+ - "The data is categorical (not time-ordered) — use `animated-bar-chart` to compare discrete values side by side."+ - "You have only 2–3 data points; a near-straight line adds little; use a number counter or a headline stat instead."+ - "You need to show pipeline or workflow stages — use `progress-steps` instead."---<ComponentPreview name="animated-line-chart" />diff --git a/content/docs/ui-blocks/check-list.mdx b/content/docs/ui-blocks/check-list.mdxindex bb5e98c7..adb14b88 100644--- a/content/docs/ui-blocks/check-list.mdx+++ b/content/docs/ui-blocks/check-list.mdx@@ -1,6 +1,17 @@---title: Check Listdescription: A handwritten checklist that writes itself out, then ticks and strikes through every done item+component: check-list+vibe: paper+length: 123+useWhen:+ - "A list of features, steps, or done-items should be read in full and then crossed off in a hand-made scene."+ - "A feature-announcement beat needs the ticking and crossing-off gesture as its payoff."+ - "One line in the list has not landed yet — mark it `checked: false` and it stays clean."+avoidWhen:+ - "You need a live progress indicator or a stepper with state — use `progress-steps`."+ - "Labels need to wrap across lines, or the list needs numbering or nesting. One label, one line."+ - "The list should sit at an angle or wobble — this component has no jitter and no positioning. Wrap it in `paper-wobble`."---<ComponentPreview name="check-list" />diff --git a/content/docs/ui-blocks/data-flow-pipes.mdx b/content/docs/ui-blocks/data-flow-pipes.mdxindex baa38a64..990c47ed 100644--- a/content/docs/ui-blocks/data-flow-pipes.mdx+++ b/content/docs/ui-blocks/data-flow-pipes.mdx@@ -1,6 +1,17 @@---title: Data Flow Pipesdescription: Glowing data packets travel along SVG bezier pipes between system nodes, leaving fading trails+component: data-flow-pipes+vibe: tech+length: 180+useWhen:+ - "Visualizing a microservices or event-driven architecture where data moves between labeled services."+ - "A platform or infra product demo needs to show \"live\" data routing without a real dashboard."+ - "An explainer scene needs to trace a request path through API → database → cache → client."+avoidWhen:+ - "The workflow is sequential with discrete pass/fail steps — use `progress-steps` instead, which shows status clearly."+ - "You only have two nodes; a single pipe with a pulse looks sparse — use an animated arrow instead."+ - "The audience needs to read specific data values — pipes convey motion/topology, not data content; use `animated-line-chart` or `animated-bar-chart` for values."---<ComponentPreview name="data-flow-pipes" />diff --git a/content/docs/ui-blocks/glass-code-block.mdx b/content/docs/ui-blocks/glass-code-block.mdxindex e1f0726c..10031349 100644--- a/content/docs/ui-blocks/glass-code-block.mdx+++ b/content/docs/ui-blocks/glass-code-block.mdx@@ -1,6 +1,15 @@---title: Glass Code Blockdescription: A premium frosted-glass code editor window with a regex tokenizer and line-by-line stagger reveal+component: glass-code-block+vibe: tech+length: 180+useWhen:+ - "A landing or hero scene needs an animated code backdrop that reads as \"premium dev tool.\""+ - "You want to showcase a code snippet with a styled editor chrome and no interactive narrative."+ - "The backdrop must stay transparent so the panel composites over a custom background."+avoidWhen:+ - "The scene requires the code to be visibly typed out character by character — use `terminal-simulator` or `typewriter` instead."---<ComponentPreview name="glass-code-block" />diff --git a/content/docs/ui-blocks/glass-code-walk.mdx b/content/docs/ui-blocks/glass-code-walk.mdxindex b406fc5d..9ba0772d 100644--- a/content/docs/ui-blocks/glass-code-walk.mdx+++ b/content/docs/ui-blocks/glass-code-walk.mdx@@ -1,6 +1,17 @@---title: Glass Code Walkdescription: A camera that scans a glass code block top to bottom as it types, then pulls back to a centered hold+component: glass-code-walk+vibe: tech+length: 150+useWhen:+ - "A code reveal needs camera motion — the frame stays pinned to the line currently typing, then pulls back so the whole file lands as the payoff."+ - "The snippet is too small to read at full frame and you want it magnified (2.6× by default) while it types."+ - "The scene already has a background image or shader and the glass panel should refract it while the camera moves over it."+avoidWhen:+ - "The code panel should sit still in frame with no camera move — use `glass-code-block`, which this component wraps and animates."+ - "The point is code producing live UI side by side — use `live-code-compilation`, which types styles and applies them to a rendered button."+ - "The content is shell commands and output rather than a source file — use `terminal-simulator`, or `terminal-cursor-zoom` for the same camera treatment on a single command."---<ComponentPreview name="glass-code-walk" />diff --git a/content/docs/ui-blocks/paper-sticker.mdx b/content/docs/ui-blocks/paper-sticker.mdxindex 16f45a82..5b1fdfd1 100644--- a/content/docs/ui-blocks/paper-sticker.mdx+++ b/content/docs/ui-blocks/paper-sticker.mdx@@ -1,6 +1,16 @@---title: Paper Stickerdescription: A taped paper chip that slaps onto the scene over two stop-motion poses+component: paper-sticker+vibe: paper+length: 120+useWhen:+ - "Short labels, chips, or callout notes should exist as physical taped paper on a stop-motion scene."+ - "A group of tags should land one after another — stagger `at` by the index, give each its own `seed`."+avoidWhen:+ - "The content is long text or looks like interactive UI — this is a paper prop, not a component sim."+ - "You need a media frame with a caption underneath — use `polaroid`."+ - "You were going to add `paper-wobble` on top: the wobble is already here."---<ComponentPreview name="paper-sticker" />diff --git a/content/docs/ui-blocks/polaroid.mdx b/content/docs/ui-blocks/polaroid.mdxindex 8da8f4af..496c6baa 100644--- a/content/docs/ui-blocks/polaroid.mdx+++ b/content/docs/ui-blocks/polaroid.mdx@@ -1,6 +1,16 @@---title: Polaroiddescription: An instant-photo frame with a handwritten caption for video, images, or live compositions+component: polaroid+vibe: paper+length: 150+useWhen:+ - "Media belongs in a hand-placed instant-photo frame with a handwritten caption."+ - "You want a live composition to keep playing inside a stop-motion scene, with no pre-rendered file."+ - "The photograph should stop being live at some point — wrap the child in Remotion's `<Freeze>`."+avoidWhen:+ - "You just need a plain rounded video frame with no paper story — use `backdrop` with padding."+ - "The card needs to wobble or sit at an angle: this component has no jitter and no positioning. Wrap it in `paper-wobble` and place it yourself."---<ComponentPreview name="polaroid" />diff --git a/content/docs/ui-blocks/progress-steps.mdx b/content/docs/ui-blocks/progress-steps.mdxindex 46bfdf91..df17088f 100644--- a/content/docs/ui-blocks/progress-steps.mdx+++ b/content/docs/ui-blocks/progress-steps.mdx@@ -1,6 +1,17 @@---title: Progress Stepsdescription: Multi-step pipeline with nodes lighting up sequentially+component: progress-steps+vibe: data+length: 150+useWhen:+ - "Showing a CI/CD pipeline, onboarding checklist, or multi-phase workflow completing step by step."+ - "A SaaS demo needs to convey \"how it works in 3 steps\" with a visual progress metaphor."+ - "Vertical orientation fits a feature list reveal; horizontal fits a timeline or funnel."+avoidWhen:+ - "The data is quantitative and you need to show magnitudes — use `animated-bar-chart` or `animated-line-chart` instead."+ - "The relationship between nodes is a graph/mesh rather than a linear chain — use `data-flow-pipes` instead."+ - "You have only one step; a single activated node conveys nothing; use a text animation or icon pop-in instead."---<ComponentPreview name="progress-steps" />diff --git a/content/docs/ui-blocks/reel.mdx b/content/docs/ui-blocks/reel.mdxindex 1c0c7612..a5d43ed3 100644--- a/content/docs/ui-blocks/reel.mdx+++ b/content/docs/ui-blocks/reel.mdx@@ -1,6 +1,16 @@---title: Reeldescription: A fixed centered card where images stack on the z-axis and each blooms open over the last+component: reel+vibe: clean+length: 160+useWhen:+ - "Showing a sequence of screenshots or product shots that should bloom open one over the last in a fixed frame."+ - "The story is \"here's what the product looks like\" across several views without a camera move."+ - "You want the reveal itself (the centre-out mask) to be the only motion in the scene."+avoidWhen:+ - "You need a single framed photo rather than a sequence — use `polaroid` instead."+ - "You want a scrolling wall of items rather than a stacked reveal — use `infinite-marquee` or `perspective-marquee` instead."---<ComponentPreview name="reel" />diff --git a/content/docs/ui-blocks/terminal-cursor-zoom.mdx b/content/docs/ui-blocks/terminal-cursor-zoom.mdxindex 6d90c577..35de77de 100644--- a/content/docs/ui-blocks/terminal-cursor-zoom.mdx+++ b/content/docs/ui-blocks/terminal-cursor-zoom.mdx@@ -1,6 +1,17 @@---title: Terminal Cursor Zoomdescription: Camera locked to the typing cursor, dollying across a terminal as a command types at high zoom+component: terminal-cursor-zoom+vibe: tech+length: 90+useWhen:+ - "One install command is the whole beat and it must stay legible in a vertical or small-screen crop — the camera holds the cursor at frame center at 2.8× zoom."+ - "A short social clip needs kinetic energy from the typing itself rather than from a full terminal session."+ - "An install or CTA card should end on the command still under the cursor, with no output lines to distract from it."+avoidWhen:+ - "The session has multiple lines, logs, or success output — use `terminal-simulator`; this component types exactly one command line and the camera never leaves it."+ - "The terminal window should stay statically framed — use `terminal-simulator` on its own, since this is only a camera rig around it."+ - "The content is source code in an editor rather than a shell command — use `glass-code-walk` for the same tracking camera over a code panel."---<ComponentPreview name="terminal-cursor-zoom" />diff --git a/content/docs/ui-blocks/terminal-simulator.mdx b/content/docs/ui-blocks/terminal-simulator.mdxindex c903c943..4aa4c950 100644--- a/content/docs/ui-blocks/terminal-simulator.mdx+++ b/content/docs/ui-blocks/terminal-simulator.mdx@@ -1,6 +1,16 @@---title: Terminal Simulatordescription: A console window that types out commands and rolls older lines off the top+component: terminal-simulator+vibe: tech+length: 240+useWhen:+ - "Demoing a CLI tool install sequence (`npm install`, `npx shadcn add`, build output)."+ - "Showing an AI agent or script executing a multi-step task in a terminal session."+ - "A developer tool launch video needs the authentic feel of commands running and output streaming."+avoidWhen:+ - "You only need to type a single short string — use `typewriter` instead, which is lighter and pairs with any layout."+ - "The code should be displayed as a formatted, highlighted editor window — use `glass-code-block` instead."---<ComponentPreview name="terminal-simulator" />diff --git a/content/docs/ui/blocks/chat-flow.mdx b/content/docs/ui/blocks/chat-flow.mdxindex 9875cc8f..5f8e8171 100644--- a/content/docs/ui/blocks/chat-flow.mdx+++ b/content/docs/ui/blocks/chat-flow.mdx@@ -1,6 +1,17 @@---title: Chat Flowdescription: A messaging conversation that types outgoing messages, shows typing indicators, and pops in incoming replies with reactions+component: chat-flow+vibe: social+length: 360+useWhen:+ - "A scene needs a messaging conversation that carries your own brand tokens instead of a real platform's chrome."+ - "The whole beat should be scripted from a `messages` array — outgoing text types into the composer, dots precede replies, reactions pop in."+ - "Other scene elements must sync to the conversation — `chatFlowSchedule` and `chatFlowDuration` expose the per-message frame offsets."+avoidWhen:+ - "The video must read as Telegram — use `telegram-chat-flow`, which owns the tailed bubbles, in-bubble timestamps, and double-check marks."+ - "The video must read as iMessage — use `imessage-chat-flow`, which owns the gray/blue tailed bubbles, the Delivered label, and tapback badges."+ - "You only need one message landing on a beat you time yourself — use `message-bubble` with `useMessageBubbleTransition`."---<BlockPreview name="chat-flow" />diff --git a/content/docs/ui/blocks/checkout-flow.mdx b/content/docs/ui/blocks/checkout-flow.mdxindex 74f86b81..6ba6e8c6 100644--- a/content/docs/ui/blocks/checkout-flow.mdx+++ b/content/docs/ui/blocks/checkout-flow.mdx@@ -1,6 +1,17 @@---title: CheckoutFlowdescription: A cursor-driven checkout card with a pricing toggle, card input, terms checkbox, and payment confirmation+component: checkout-flow+vibe: clean+length: "state-driven"+useWhen:+ - "Demoing a SaaS payment or upgrade UX end-to-end with cursor navigation and toast confirmation."+ - "A product video needs a complete purchase journey (plan select → card entry → pay → success) in one scene."+ - "Showing the full checkout funnel without assembling the individual primitives manually."+avoidWhen:+ - "You only need a payment form without cursor animation — compose `field`, `input`, `button` manually."+ - "The flow is a multi-step onboarding (not payment) — use `onboarding-stepper-flow` instead."+ - "You need custom timing control over individual steps — orchestrate the primitives directly."---<BlockPreview name="checkout-flow" />diff --git a/content/docs/ui/blocks/imessage-chat-flow.mdx b/content/docs/ui/blocks/imessage-chat-flow.mdxindex 6e78c654..4fcc1e4b 100644--- a/content/docs/ui/blocks/imessage-chat-flow.mdx+++ b/content/docs/ui/blocks/imessage-chat-flow.mdx@@ -1,6 +1,17 @@---title: iMessage Chat Flowdescription: iMessage-styled conversation with gray incoming and blue outgoing bubbles, typing indicator, Delivered label, and tapback reactions+component: imessage-chat-flow+vibe: social+length: 360+useWhen:+ - "The scene must read as iMessage — gray incoming and blue outgoing tailed bubbles with tapback badges at the outer top corner."+ - "You want the reply preceded by a gray bubble of bouncing dots rather than a status line in the header."+ - "An Apple-audience demo needs the native composer bar and a \"Delivered\" label under the closing outgoing message."+avoidWhen:+ - "The scene must read as Telegram — use `telegram-chat-flow` for in-bubble timestamps, double-check marks, and reaction chips."+ - "The thread has to follow your brand tokens — use `chat-flow`; this block's palette is a fixed iMessage skin apart from `accentColor`."+ - "You only need the bouncing dots on their own — use `typing-indicator`, which this block composes."---<BlockPreview name="imessage-chat-flow" />diff --git a/content/docs/ui/blocks/settings-toggle-flow.mdx b/content/docs/ui/blocks/settings-toggle-flow.mdxindex bd62ec13..22d4bf79 100644--- a/content/docs/ui/blocks/settings-toggle-flow.mdx+++ b/content/docs/ui/blocks/settings-toggle-flow.mdx@@ -1,6 +1,17 @@---title: SettingsToggleFlowdescription: Two-column settings card with a blur-in entrance and a cursor-driven switch, select, slider, and save+component: settings-toggle-flow+vibe: clean+length: "state-driven"+useWhen:+ - "Showing a complete settings interaction walkthrough for a product demo — zero assembly required."+ - "Demonstrating multiple UI primitives orchestrated in sequence: switch, select, slider, then toast."+ - "You need a production-ready settings scene and the default layout matches your content."+avoidWhen:+ - "You need only one control type — use `switch`, `select`, or `slider` individually instead."+ - "Your settings layout differs from the default two-column card — compose primitives manually for full control."+ - "You need custom cursor timing or interaction order — wire `cursor` directly with individual primitives instead."---<BlockPreview name="settings-toggle-flow" />diff --git a/content/docs/ui/blocks/signup-flow.mdx b/content/docs/ui/blocks/signup-flow.mdxindex 1571a74a..c4fa973f 100644--- a/content/docs/ui/blocks/signup-flow.mdx+++ b/content/docs/ui/blocks/signup-flow.mdx@@ -1,6 +1,17 @@---title: SignupFlowdescription: A cursor-driven signup card — labeled fields fill top-to-bottom, then submit with success feedback+component: signup-flow+vibe: clean+length: "state-driven"+useWhen:+ - "Showing a full onboarding or signup flow in a product launch or demo video."+ - "Demonstrating a realistic form-fill interaction with animated cursor and field progression."+ - "You need a production-ready auth scene with zero assembly and the default field layout fits."+avoidWhen:+ - "You need a generic form with custom fields — compose `input` + `button` + `cursor` manually instead."+ - "You only need the success notification — use `toast` directly."+ - "You need a settings interaction walkthrough — use `settings-toggle-flow` instead."---<BlockPreview name="signup-flow" />diff --git a/content/docs/ui/blocks/telegram-chat-flow.mdx b/content/docs/ui/blocks/telegram-chat-flow.mdxindex 48fa7b3c..294b1004 100644--- a/content/docs/ui/blocks/telegram-chat-flow.mdx+++ b/content/docs/ui/blocks/telegram-chat-flow.mdx@@ -1,6 +1,17 @@---title: Telegram Chat Flowdescription: Telegram-styled conversation with tailed bubbles, delivery checks, typing status, and reaction chips+component: telegram-chat-flow+vibe: social+length: 360+useWhen:+ - "The scene must read as Telegram — blue tailed bubbles, in-bubble timestamps, and double-check delivery marks."+ - "You want the reply beat announced as an italic \"typing…\" status in the header rather than a bubble of dots."+ - "The demo needs the Telegram composer pill, where the mic button swaps to a paper plane the moment text is typed."+avoidWhen:+ - "The scene must read as iMessage — use `imessage-chat-flow` for gray incoming bubbles, the Delivered label, and tapback badges."+ - "The conversation has to follow your brand tokens — use `chat-flow`; this block's chrome is a fixed light Telegram skin and only `accentColor` is overridable."+ - "You only need a single bubble or the dots on their own — use `message-bubble` or `typing-indicator`."---<BlockPreview name="telegram-chat-flow" />diff --git a/content/docs/ui/components/accordion.mdx b/content/docs/ui/components/accordion.mdxindex 62cea9d1..94b426df 100644--- a/content/docs/ui/components/accordion.mdx+++ b/content/docs/ui/components/accordion.mdx@@ -1,6 +1,17 @@---title: Accordiondescription: An accordion panel whose open/closed state is a pure function of the timeline+component: accordion+vibe: clean+length: 120+useWhen:+ - "Showing a collapsible FAQ or settings section expanding on a timeline cue."+ - "Demonstrating the open/close interaction of a disclosure pattern in a product demo."+ - "Composing multiple staggered reveals where each panel opens at a different `from` frame."+avoidWhen:+ - "The content is always visible — there is no collapse state; lay it out statically instead."+ - "You need a flyout triggered from a button — use `dropdown-menu` instead."+ - "The reveal wraps arbitrary JSX children rather than a string — use `blur-in` to wrap any node."---<UiComponentPreview name="accordion" />diff --git a/content/docs/ui/components/alert-dialog.mdx b/content/docs/ui/components/alert-dialog.mdxindex aab58c70..e48c790a 100644--- a/content/docs/ui/components/alert-dialog.mdx+++ b/content/docs/ui/components/alert-dialog.mdx@@ -1,6 +1,17 @@---title: AlertDialogdescription: A modal alert dialog whose opened/closed state is a pure function of the timeline+component: alert-dialog+vibe: clean+length: 120+useWhen:+ - "Showing a destructive confirmation dialog (delete, reset, revoke) in a product demo."+ - "Demonstrating the \"are you sure?\" UX pattern with a backdrop dim and zoom entrance."+ - "A modal must block the rest of the composition until dismissed by the timeline."+avoidWhen:+ - "The action is non-destructive or form-based — use `dialog` instead."+ - "You need a non-modal contextual overlay — use `dropdown-menu` or `context-menu` instead."+ - "The overlay should slide from the bottom edge — use `drawer` instead."---<UiComponentPreview name="alert-dialog" />diff --git a/content/docs/ui/components/blur-in.mdx b/content/docs/ui/components/blur-in.mdxindex e4cd505a..44e4ba7c 100644--- a/content/docs/ui/components/blur-in.mdx+++ b/content/docs/ui/components/blur-in.mdx@@ -1,6 +1,17 @@---title: Blur Indescription: A wrapper that reveals a single child with blur, opacity, and a directional offset+component: blur-in+vibe: premium+length: 120+useWhen:+ - "Revealing an arbitrary JSX subtree (card, image, composed scene) with a premium blur entrance."+ - "Wrapping a UI primitive whose own `state` prop doesn't expose blur-in as an option."+ - "Staggering multiple child elements into view by rendering each in its own `<BlurIn>` at offset frames."+avoidWhen:+ - "You're animating a text-only line — use a purpose-built text reveal (`soft-blur-in`, `staggered-fade-up`) instead of wrapping raw text."+ - "The child is a remocn-ui primitive that already exposes a `state` prop with its own entrance — animate via `state` directly."+ - "You need a full-opacity slide with no blur — use the component's own directional offset or a translation interpolation."---<UiComponentPreview name="blur-in" />diff --git a/content/docs/ui/components/button.mdx b/content/docs/ui/components/button.mdxindex a9863f0b..5486cfcd 100644--- a/content/docs/ui/components/button.mdx+++ b/content/docs/ui/components/button.mdx@@ -1,6 +1,17 @@---title: Buttondescription: A button whose visual state is a pure function of the timeline+component: button+vibe: clean+length: 120+useWhen:+ - "Showing the full interactive lifecycle of a CTA — hover → press → loading → success — on the timeline."+ - "A composition needs a trigger visual for a modal-layer primitive (`dialog`, `alert-dialog`, `drawer`)."+ - "Demonstrating a loading/submit state with a spinner inline inside the button."+avoidWhen:+ - "You need a selectable row inside a menu — use `dropdown-menu-item` or `command-menu-item` instead."+ - "The button must open a searchable dropdown — use `combobox` (which uses an input trigger) instead."+ - "You only need a static label with no interactive state — render plain text in the composition."---<UiComponentPreview name="button" />diff --git a/content/docs/ui/components/caret.mdx b/content/docs/ui/components/caret.mdxindex d2f2602b..9ad13591 100644--- a/content/docs/ui/components/caret.mdx+++ b/content/docs/ui/components/caret.mdx@@ -1,6 +1,17 @@---title: Caretdescription: A blinking text caret — a pure motion atom or a fully controlled bar+component: caret+vibe: tech+length: 120+useWhen:+ - "Placing a blinking insertion cursor beside a text node or at the end of a typed string."+ - "Composing inside a custom typewriter or terminal scene where `typewriter` is too opinionated."+ - "Indicating an active input position before the `input` primitive's focus ring animation starts."+avoidWhen:+ - "You need the full input UX (focus ring, border, value reveal) — use `input` instead, which owns its own caret."+ - "The typewriter effect is needed — use `typewriter`, which composes `caret` internally."+ - "You need a text selection highlight rather than an insertion point."---<ComponentPreview name="caret" />diff --git a/content/docs/ui/components/checkbox.mdx b/content/docs/ui/components/checkbox.mdxindex d4466a7e..cf8b903c 100644--- a/content/docs/ui/components/checkbox.mdx+++ b/content/docs/ui/components/checkbox.mdx@@ -1,6 +1,17 @@---title: Checkboxdescription: A checkbox whose checked/unchecked state is a pure function of the timeline+component: checkbox+vibe: clean+length: 120+useWhen:+ - "Showing a task being checked off in a to-do or onboarding list."+ - "Demonstrating a boolean form option toggling on (or off) at a timeline-driven moment."+ - "Composing inside `checkout-flow` or `onboarding-stepper-flow` for a terms-acceptance step."+avoidWhen:+ - "The choice is mutually exclusive within a group — use `radio` instead."+ - "You need a toggle switch metaphor — use `switch` instead."+ - "The user picks one option from a long or searchable list — use `combobox` instead (a checkbox group already is the multi-select metaphor)."---<UiComponentPreview name="checkbox" />diff --git a/content/docs/ui/components/combobox.mdx b/content/docs/ui/components/combobox.mdxindex a6a19ff6..f888d8d9 100644--- a/content/docs/ui/components/combobox.mdx+++ b/content/docs/ui/components/combobox.mdx@@ -1,6 +1,17 @@---title: Comboboxdescription: A searchable select with a typed-query input, filtered panel, and row selection+component: combobox+vibe: clean+length: 120+useWhen:+ - "Showing a searchable/filterable dropdown with a typed query narrowing the list on the timeline."+ - "Demoing autocomplete or type-ahead selection UX in a product walkthrough."+ - "A form field needs a constrained set of options but with search, not free-form text."+avoidWhen:+ - "The list is not filterable and selection is direct — use `select` (non-filterable dropdown) instead."+ - "The overlay is a command palette with icons and keyboard shortcuts — use `command-menu` instead."+ - "The input is free-form text entry with no list — use `input` instead."---<UiComponentPreview name="combobox" />diff --git a/content/docs/ui/components/command-menu.mdx b/content/docs/ui/components/command-menu.mdxindex 46748acf..870900a5 100644--- a/content/docs/ui/components/command-menu.mdx+++ b/content/docs/ui/components/command-menu.mdx@@ -1,6 +1,17 @@---title: Command Menudescription: A keyboard-driven command palette with backdrop, typing animation, and row selection+component: command-menu+vibe: tech+length: 120+useWhen:+ - "Demoing a ⌘K palette opening with a typed query filtering icon-labeled commands."+ - "Showing keyboard-first navigation UX in a developer or power-user product video."+ - "Demonstrating item hover/press states with trailing keyboard shortcuts in a command palette."+avoidWhen:+ - "The list has no icons or keyboard shortcuts and is triggered from a button — use `dropdown-menu` instead."+ - "The overlay is a right-click contextual menu — use `context-menu` instead."+ - "You only need a filterable input without a modal overlay — use `combobox` instead."---<UiComponentPreview name="command-menu" />diff --git a/content/docs/ui/components/context-menu.mdx b/content/docs/ui/components/context-menu.mdxindex 5115b224..063e1362 100644--- a/content/docs/ui/components/context-menu.mdx+++ b/content/docs/ui/components/context-menu.mdx@@ -1,6 +1,17 @@---title: Context Menudescription: A right-click menu panel that opens at the cursor point with no built-in trigger+component: context-menu+vibe: clean+length: 120+useWhen:+ - "Showing a right-click menu appearing at a cursor position over content in a product demo."+ - "Demonstrating browser-like or OS-like contextual actions (Back, Reload, Inspect)."+ - "A cursor composition needs a pop-up menu that originates from a click point, not a button."+avoidWhen:+ - "The menu is triggered from a button in the UI — use `dropdown-menu` instead."+ - "The overlay is a searchable command palette — use `command-menu` instead."+ - "The overlay is a modal that blocks the rest of the scene — use `dialog` or `alert-dialog` instead."---<UiComponentPreview name="context-menu" />diff --git a/content/docs/ui/components/cursor.mdx b/content/docs/ui/components/cursor.mdxindex 267bfcd5..686d970a 100644--- a/content/docs/ui/components/cursor.mdx+++ b/content/docs/ui/components/cursor.mdx@@ -1,6 +1,17 @@---title: Cursordescription: An animated cursor that follows a scripted path with click ripple and press effects+component: cursor+vibe: clean+length: 120+useWhen:+ - "Guiding the viewer's attention through a UI by animating a pointer between elements."+ - "Showing click, hover, and drag interactions in a product demo without real interactivity."+ - "Composing inside `checkout-flow` or a custom orchestrator where the cursor drives the narrative."+avoidWhen:+ - "You need a blinking text insertion cursor — use `caret` instead."+ - "There is no interaction to demonstrate and the cursor would be visual noise."+ - "You need a crosshair or custom SVG cursor — the variant set is `arrow` / `pointer`; extend or render custom SVG directly."---<UiComponentPreview name="cursor" />diff --git a/content/docs/ui/components/dialog.mdx b/content/docs/ui/components/dialog.mdxindex 5a925d89..57cbc027 100644--- a/content/docs/ui/components/dialog.mdx+++ b/content/docs/ui/components/dialog.mdx@@ -1,6 +1,17 @@---title: Dialogdescription: A modal dialog whose opened/closed state is a pure function of the timeline+component: dialog+vibe: clean+length: 120+useWhen:+ - "Showing a non-destructive modal (edit form, settings, profile update) opening and closing on the timeline."+ - "A centered overlay needs a title, description, and primary/cancel actions."+ - "Composing a trigger-to-modal sequence: `button` state=\"press\" → `dialog` state=\"open\"."+avoidWhen:+ - "The action is irreversible or destructive — use `alert-dialog` instead."+ - "The panel should slide from the bottom edge — use `drawer` instead."+ - "The overlay is non-modal and contextual — use `dropdown-menu` or `context-menu` instead."---<UiComponentPreview name="dialog" />diff --git a/content/docs/ui/components/drawer.mdx b/content/docs/ui/components/drawer.mdxindex 718bd1fe..a22f663d 100644--- a/content/docs/ui/components/drawer.mdx+++ b/content/docs/ui/components/drawer.mdx@@ -1,6 +1,17 @@---title: Drawerdescription: A bottom panel whose opened/closed state is a pure function of the timeline+component: drawer+vibe: clean+length: 120+useWhen:+ - "Showing a mobile-style bottom sheet sliding up from the edge of the frame."+ - "Demonstrating a sheet/tray pattern typical of mobile or bottom-anchored desktop UX."+ - "Composing a trigger-to-sheet sequence: `button` state=\"press\" → `drawer` state=\"open\"."+avoidWhen:+ - "The overlay should be a centered modal — use `dialog` instead."+ - "The action is destructive and needs an explicit confirmation — use `alert-dialog` instead."+ - "The overlay is non-modal and contextual — use `dropdown-menu` or `context-menu` instead."---<UiComponentPreview name="drawer" />diff --git a/content/docs/ui/components/dropdown-menu.mdx b/content/docs/ui/components/dropdown-menu.mdxindex 19452d67..3d04ba2c 100644--- a/content/docs/ui/components/dropdown-menu.mdx+++ b/content/docs/ui/components/dropdown-menu.mdx@@ -1,6 +1,17 @@---title: DropdownMenudescription: A dropdown menu container with opened/closed states and action rows+component: dropdown-menu+vibe: clean+length: 120+useWhen:+ - "Showing a button that opens an action list — the classic \"Options\" or account menu pattern."+ - "Demonstrating hover/press states on individual menu items after the panel opens."+ - "Composing inside a nav bar or toolbar where a trigger button owns a small action list."+avoidWhen:+ - "The menu is invoked by right-click at a cursor position — use `context-menu` instead."+ - "The list is searchable or filterable — use `combobox` instead."+ - "The overlay is a modal that blocks the scene — use `dialog` or `alert-dialog` instead."---<UiComponentPreview name="dropdown-menu" />diff --git a/content/docs/ui/components/input.mdx b/content/docs/ui/components/input.mdxindex 0d951a8e..4fa01263 100644--- a/content/docs/ui/components/input.mdx+++ b/content/docs/ui/components/input.mdx@@ -1,6 +1,17 @@---title: Inputdescription: An input field whose visual state is a pure function of the timeline+component: input+vibe: clean+length: 120+useWhen:+ - "Showing a text field being focused, typed into, or validated at a specific frame."+ - "Composing inside `field` for a labeled email/name/card input in a form scene."+ - "Demonstrating the invalid state (red border, shake) to highlight an error condition."+avoidWhen:+ - "The trigger needs to open a searchable list — use `combobox` instead (which wraps input internally)."+ - "You only need a blinking cursor with no field chrome — use `caret` instead."+ - "The control is a button-style CTA, not a text entry — use `button` instead."---<UiComponentPreview name="input" />diff --git a/content/docs/ui/components/message-bubble.mdx b/content/docs/ui/components/message-bubble.mdxindex c1698e6f..5fc8f927 100644--- a/content/docs/ui/components/message-bubble.mdx+++ b/content/docs/ui/components/message-bubble.mdx@@ -1,6 +1,17 @@---title: Message Bubbledescription: A state-driven speech bubble with incoming and outgoing variants and an optional reaction badge+component: message-bubble+vibe: clean+length: "state-driven"+useWhen:+ - "You are hand-timing a single message landing on a beat you control, driving `style` from `useMessageBubbleTransition`."+ - "A scene needs a themed speech bubble around arbitrary content — text, an image, or a `typing-indicator`."+ - "The conversation must carry your own `RemocnTheme` tokens rather than a real messenger's palette."+avoidWhen:+ - "You want a whole scripted conversation with a composer, typing beats, and reactions — use `chat-flow`, which schedules bubbles for you."+ - "The bubble must read as a specific messenger with a tail, timestamp, or tapback — use `telegram-chat-flow` or `imessage-chat-flow`, which own those bubble shapes."+ - "You need the bouncing dots themselves rather than the container around them — use `typing-indicator`."---<UiComponentPreview name="message-bubble" />diff --git a/content/docs/ui/components/popover.mdx b/content/docs/ui/components/popover.mdxindex 3f2b2fe3..7b2ad5be 100644--- a/content/docs/ui/components/popover.mdx+++ b/content/docs/ui/components/popover.mdx@@ -1,6 +1,17 @@---title: Popoverdescription: A floating card that appears beside an anchor with arbitrary content+component: popover+vibe: clean+length: 120+useWhen:+ - "Showing a hover-card with richer content (title + description) than a single-line tooltip label allows."+ - "Demonstrating a popover animation keyed to the timeline — open and close sequenced across frames."+ - "The overlay should enter from a specific axis (`side` prop controls translate direction)."+avoidWhen:+ - "You only need a single-line label — use `tooltip` instead (lighter, no title/description structure)."+ - "You need a persistent side panel with a close button and action — use `sheet` instead."+ - "The overlay needs full blocking modal behavior — use `alert-dialog` instead."---<UiComponentPreview name="popover" />diff --git a/content/docs/ui/components/progress.mdx b/content/docs/ui/components/progress.mdxindex e80c1723..c4bf41a4 100644--- a/content/docs/ui/components/progress.mdx+++ b/content/docs/ui/components/progress.mdx@@ -1,6 +1,17 @@---title: Progressdescription: A progress bar that fills along a scripted numeric value timeline+component: progress+vibe: data+length: 120+useWhen:+ - "Showing a loading, upload, or completion bar animating to a target value."+ - "Visualizing progression through a multi-step flow as a single continuous bar."+ - "You need a labeled percentage readout alongside the fill indicator."+avoidWhen:+ - "The state is binary (done/not done) — use `switch` instead."+ - "You need segmented, numbered step-by-step progress — use `stepper` instead (connectors + check marks)."+ - "You need a range input the user can drag — use `slider` instead (thumb + grab-ring interaction)."---<UiComponentPreview name="progress" />diff --git a/content/docs/ui/components/radio.mdx b/content/docs/ui/components/radio.mdxindex 22cb158d..2ab8d4fd 100644--- a/content/docs/ui/components/radio.mdx+++ b/content/docs/ui/components/radio.mdx@@ -1,6 +1,17 @@---title: Radiodescription: A radio whose checked/unchecked state is a pure function of the timeline+component: radio+vibe: clean+length: 120+useWhen:+ - "Demonstrating a single-choice selection moment in a form walkthrough."+ - "Animating a user choosing between two or more mutually exclusive options."+ - "Pairing with `cursor` to show a click-and-select interaction on the timeline."+avoidWhen:+ - "The control is binary on/off — use `switch` instead (sliding thumb reads more naturally for toggles)."+ - "You need a multi-select where several options can be active — use `checkbox` instead."+ - "Options switch with a continuous sliding indicator between segments — use `toggle-group` instead."---<UiComponentPreview name="radio" />diff --git a/content/docs/ui/components/resizable.mdx b/content/docs/ui/components/resizable.mdxindex 5782754e..a1d55ae2 100644--- a/content/docs/ui/components/resizable.mdx+++ b/content/docs/ui/components/resizable.mdx@@ -1,6 +1,17 @@---title: Resizabledescription: A two-panel split container whose divider ratio and handle state are driven by a scripted dual-channel timeline+component: resizable+vibe: clean+length: 120+useWhen:+ - "Demonstrating a code/preview split pane layout with its ratio animating across frames."+ - "Showing a drag-to-resize UI interaction in a product walkthrough with handle hover/press states."+ - "Visualizing before/after content that morphs its split point on the timeline."+avoidWhen:+ - "You need fixed-width layout panels — plain CSS grid or flex avoids the drag-state overhead entirely."+ - "The split is purely decorative — `resizable` implies an interactive drag metaphor; use a plain container instead."+ - "You need more than two panels — `resizable` is two-panel only; compose multiple instances."---<UiComponentPreview name="resizable" />diff --git a/content/docs/ui/components/select.mdx b/content/docs/ui/components/select.mdxindex a00d7184..b6da802b 100644--- a/content/docs/ui/components/select.mdx+++ b/content/docs/ui/components/select.mdx@@ -1,6 +1,18 @@---title: Selectdescription: A dropdown select container with opened/closed states and item panel+component: select+vibe: clean+length: 120+useWhen:+ - "Demonstrating a dropdown menu opening and an option being highlighted or selected on the timeline."+ - "Showing a form field interaction with animated open/close in a product walkthrough."+ - "Composing a settings scene where one control is a dropdown — pairs naturally with `switch` and `slider`."+avoidWhen:+ - "You only need to show one item row in isolation — use `select-item` directly without the panel overhead."+ - "The choice is binary — use `switch` instead (simpler, no dropdown)."+ - "You need a compact segmented control without a dropdown — use `toggle-group` instead."+ - "The items are actions or commands rather than a value being stored — use `dropdown-menu` (or `context-menu`); for a long, type-to-filter list use `combobox`."---<UiComponentPreview name="select" />diff --git a/content/docs/ui/components/sheet.mdx b/content/docs/ui/components/sheet.mdxindex d30b904f..64e391b0 100644--- a/content/docs/ui/components/sheet.mdx+++ b/content/docs/ui/components/sheet.mdx@@ -1,6 +1,18 @@---title: Sheetdescription: A side panel whose opened/closed state is a pure function of the timeline+component: sheet+vibe: clean+length: 120+useWhen:+ - "Showing a slide-in edit panel or settings drawer with backdrop dim in a product demo."+ - "Demonstrating an offcanvas overlay opening from the right edge of the frame."+ - "Pairing with a `button` trigger to animate open → interact → close across the timeline."+avoidWhen:+ - "You need a full blocking modal with centered placement — use `alert-dialog` instead."+ - "The overlay is a floating contextual card near a target element — use `popover` instead."+ - "You only need a brief notification — use `toast` instead (no backdrop, no action panel)."+ - "The panel should slide up from the bottom edge — use `drawer` instead; `sheet` enters from a side edge."---<UiComponentPreview name="sheet" />diff --git a/content/docs/ui/components/skeleton.mdx b/content/docs/ui/components/skeleton.mdxindex cc6d7475..2c7a865e 100644--- a/content/docs/ui/components/skeleton.mdx+++ b/content/docs/ui/components/skeleton.mdx@@ -1,6 +1,17 @@---title: Skeletondescription: A shimmer placeholder that crossfades to real content when loaded+component: skeleton+vibe: clean+length: 120+useWhen:+ - "Showing a loading state resolving to real content — the skeleton fades out as real UI fades in."+ - "Demonstrating content that \"loads in\" as a crossfade moment in a product walkthrough."+ - "You need a full skeleton layout (lines or card) wrapping real children, not just a single shimmer block."+avoidWhen:+ - "You only need a single shimmer rectangle — use `skeleton-block` directly (no state API, no crossfade overhead)."+ - "Content has no loading state — render children directly without a wrapper."+ - "You need a spinner-style loading indicator — use `spinner` instead (arc, no placeholder layout)."---<UiComponentPreview name="skeleton" />diff --git a/content/docs/ui/components/slider.mdx b/content/docs/ui/components/slider.mdxindex b598cd5b..d9cf7198 100644--- a/content/docs/ui/components/slider.mdx+++ b/content/docs/ui/components/slider.mdx@@ -1,6 +1,17 @@---title: Sliderdescription: A range slider with a draggable thumb driven by a scripted value and thumb-state timeline+component: slider+vibe: clean+length: 120+useWhen:+ - "Demonstrating a range control being dragged to a target value with hover/press thumb states."+ - "Showing an audio, video, or settings slider animating in a product walkthrough."+ - "Composing a settings scene alongside `switch` and `select` (used in `settings-toggle-flow`)."+avoidWhen:+ - "You need to show completion percentage with no thumb — use `progress` instead (fill-only, no interaction states)."+ - "The value is binary — use `switch` instead."+ - "You need step-by-step progress with connectors and check marks — use `stepper` instead."---<UiComponentPreview name="slider" />diff --git a/content/docs/ui/components/spinner.mdx b/content/docs/ui/components/spinner.mdxindex 86d2861a..4ddd3412 100644--- a/content/docs/ui/components/spinner.mdx+++ b/content/docs/ui/components/spinner.mdx@@ -1,6 +1,17 @@---title: Spinnerdescription: A deterministic spinning arc — pure function of the Remotion frame+component: spinner+vibe: clean+length: 120+useWhen:+ - "Showing a loading indicator inside a button after a click (hover → press → loading state)."+ - "Adding an inline async-operation indicator to any scene without layout overhead."+ - "Composing with `skeleton` or `button` to illustrate a loading-state moment in a flow."+avoidWhen:+ - "You need a full-width loading bar with a track — use `progress` instead."+ - "You need a shimmer placeholder block — use `skeleton-block` instead."+ - "The loading state resolves to real content — use `skeleton` for the crossfade (spinner has no loaded state)."---<ComponentPreview name="spinner" />diff --git a/content/docs/ui/components/stepper.mdx b/content/docs/ui/components/stepper.mdxindex 2297dff7..44f46332 100644--- a/content/docs/ui/components/stepper.mdx+++ b/content/docs/ui/components/stepper.mdx@@ -1,6 +1,17 @@---title: Stepperdescription: A multi-step progress indicator that advances along a scripted numeric position timeline+component: stepper+vibe: clean+length: 120+useWhen:+ - "Showing a multi-step onboarding, checkout, or wizard flow advancing through numbered steps."+ - "Demonstrating step completion with animated check marks, circle fills, and connector fills."+ - "Visualizing a user's progress through a sequential workflow with discrete labeled stages."+avoidWhen:+ - "Steps have no sequential order — use `tabs` instead (tab switching without numbered connectors)."+ - "You need a continuous fill bar without numbered steps — use `progress` instead."+ - "You need a compact segmented control that switches view modes — use `toggle-group` instead."---<UiComponentPreview name="stepper" />diff --git a/content/docs/ui/components/switch.mdx b/content/docs/ui/components/switch.mdxindex 733d8ce2..a86e71d3 100644--- a/content/docs/ui/components/switch.mdx+++ b/content/docs/ui/components/switch.mdx@@ -1,6 +1,17 @@---title: Switchdescription: A switch whose checked/unchecked state is a pure function of the timeline+component: switch+vibe: clean+length: 120+useWhen:+ - "Showing a toggle being flipped in a settings panel walkthrough."+ - "Demonstrating a binary on/off control with an animated thumb slide and track fill."+ - "Composing a settings scene alongside `select` and `slider` (used in `settings-toggle-flow`)."+avoidWhen:+ - "The choice is one of multiple mutually exclusive options — use `radio` or `select` instead."+ - "You need a compact segmented control — use `toggle-group` instead (continuous sliding indicator between segments)."+ - "The state is a range value — use `slider` instead."---<UiComponentPreview name="switch" />diff --git a/content/docs/ui/components/tabs.mdx b/content/docs/ui/components/tabs.mdxindex 487e259a..1c08ace8 100644--- a/content/docs/ui/components/tabs.mdx+++ b/content/docs/ui/components/tabs.mdx@@ -1,6 +1,17 @@---title: Tabsdescription: A tabs widget whose active-tab state is a pure function of the timeline+component: tabs+vibe: clean+length: 120+useWhen:+ - "Showing a tabbed UI switching between content panels in a product demo."+ - "Demonstrating a pill or underline tab indicator sliding between sections."+ - "Showing a content crossfade between different sections of a layout."+avoidWhen:+ - "Steps are sequential and ordered — use `stepper` instead (numbered connectors + check marks)."+ - "You need a compact segmented control without content panels — use `toggle-group` instead (no panel area)."+ - "You need a sidebar or vertical navigation structure — compose a nav layout directly instead."---<UiComponentPreview name="tabs" />diff --git a/content/docs/ui/components/toast.mdx b/content/docs/ui/components/toast.mdxindex 922b12f7..3132d37f 100644--- a/content/docs/ui/components/toast.mdx+++ b/content/docs/ui/components/toast.mdx@@ -1,6 +1,17 @@---title: Toastdescription: A notification that slides in from below, holds, then auto-dismisses+component: toast+vibe: clean+length: 120+useWhen:+ - "Showing a success/error notification appear after an action (form submit, save, API call)."+ - "Ending a flow composition with a confirmation sliding in — used as the final beat in `signup-flow` and `settings-toggle-flow`."+ - "Demonstrating auto-dismiss feedback in a product walkthrough with a `hidden → visible → hidden` sequence."+avoidWhen:+ - "The feedback is persistent and must not auto-dismiss — use a banner or inline alert component instead."+ - "You need a blocking confirmation with actions — use `alert-dialog` instead."+ - "You need a persistent side panel — use `sheet` instead."---<UiComponentPreview name="toast" />diff --git a/content/docs/ui/components/toggle-group.mdx b/content/docs/ui/components/toggle-group.mdxindex 8dd54bf6..82123baf 100644--- a/content/docs/ui/components/toggle-group.mdx+++ b/content/docs/ui/components/toggle-group.mdx@@ -1,6 +1,17 @@---title: Toggle Groupdescription: A segmented control whose active value slides a thumb indicator between segments+component: toggle-group+vibe: clean+length: 120+useWhen:+ - "Showing a segmented control switching between view modes, time ranges, or mutually exclusive options."+ - "Demonstrating a smooth continuous thumb-slide animation between compact segments."+ - "Replacing a radio group where options are co-located and a sliding-thumb metaphor reads better than individual dots."+avoidWhen:+ - "You need content panels that crossfade below the control — use `tabs` instead (full panel area + indicator)."+ - "Options are sequential numbered steps — use `stepper` instead (connectors + check marks)."+ - "You need a full dropdown with a reveal panel — use `select` instead."---<UiComponentPreview name="toggle-group" />diff --git a/content/docs/ui/components/tooltip.mdx b/content/docs/ui/components/tooltip.mdxindex 325df11c..dbaed39e 100644--- a/content/docs/ui/components/tooltip.mdx+++ b/content/docs/ui/components/tooltip.mdx@@ -1,6 +1,17 @@---title: Tooltipdescription: A small floating label that appears above an anchor on hover+component: tooltip+vibe: clean+length: 120+useWhen:+ - "Showing a hover tooltip appearing next to a UI element in a product walkthrough."+ - "Demonstrating a contextual label that explains an icon or action on the timeline."+ - "Sequencing a show → read → hide moment — `side` controls which axis the tooltip enters from."+avoidWhen:+ - "You need title + description in the overlay — use `popover` instead (richer two-field content with optional children)."+ - "You need a persistent side panel with actions — use `sheet` instead."+ - "You need a blocking confirmation — use `alert-dialog` instead."---<UiComponentPreview name="tooltip" />diff --git a/content/docs/ui/components/typing-indicator.mdx b/content/docs/ui/components/typing-indicator.mdxindex 86de0d08..e05cfb60 100644--- a/content/docs/ui/components/typing-indicator.mdx+++ b/content/docs/ui/components/typing-indicator.mdx@@ -1,6 +1,17 @@---title: Typing Indicatordescription: A motion atom that renders N bouncing dots driven directly by useCurrentFrame+component: typing-indicator+vibe: clean+length: 90+useWhen:+ - "Signalling that a reply or an answer is being composed — drop it inside a `message-bubble` or any container."+ - "You need a small continuous \"working on it\" motion that never resolves, tinted through `color`."+ - "You are timing the typing beat yourself in a `<Sequence>` instead of letting a flow block schedule it."+avoidWhen:+ - "The wait is an async operation rather than a conversation — use `spinner`, or `skeleton` when the placeholder resolves to content."+ - "The dots should appear and disappear on a scripted conversation timeline — `chat-flow` and `imessage-chat-flow` already sequence them."+ - "You want a caret blinking at the end of typed text in a composer — use `caret`."---<UiComponentPreview name="typing-indicator" />diff --git a/lib/docs-meta.test.ts b/lib/docs-meta.test.tsnew file mode 100644index 00000000..7dd9e24f--- /dev/null+++ b/lib/docs-meta.test.ts@@ -0,0 +1,207 @@+import { describe, expect, it } from "bun:test";+import { readFileSync } from "node:fs";+import { basename } from "node:path";+import { Glob } from "bun";+import { VIBES } from "./docs-schema";++const REGISTRIES = ["remocn", "remocn-ui", "remocn-icons"] as const;++const UNDOCUMENTED: Record<string, string> = {+ "remocn-ui": "shared core lib, not installed directly",+ "stop-motion": "shared lib behind the paper tier",+ "scene-motion": "shared motion vocabulary lib",+ brush: "ribbon primitive consumed by the ink marks, not used on its own",+ "select-item": "folds into the select page",+ "dropdown-menu-item": "folds into the dropdown-menu page",+ "command-menu-item": "folds into the command-menu page",+ "icons-core": "shared icon runtime",+};++function isIcon(name: string): boolean {+ return name.startsWith("icon-");+}++interface Page {+ file: string;+ frontmatter: Record<string, unknown>;+}++function loadPages(): Page[] {+ const pages: Page[] = [];+ for (const file of new Glob("content/docs/**/*.mdx").scanSync(".")) {+ const src = readFileSync(file, "utf8");+ const end = src.indexOf("\n---", 3);+ if (!src.startsWith("---") || end === -1) {+ throw new Error(`${file} has no frontmatter`);+ }+ pages.push({+ file,+ frontmatter: (Bun.YAML.parse(src.slice(4, end)) ?? {}) as Record<+ string,+ unknown+ >,+ });+ }+ return pages;+}++function registryItems(): { name: string; registry: string }[] {+ return REGISTRIES.flatMap((registry) => {+ const reg = JSON.parse(+ readFileSync(`registry/${registry}/registry.json`, "utf8"),+ );+ return (reg.items as { name: string }[]).map((item) => ({+ name: item.name,+ registry,+ }));+ });+}++const pages = loadPages();+const items = registryItems();+const documented = new Map<string, string>();+for (const page of pages) {+ const name = page.frontmatter.component;+ if (typeof name === "string") documented.set(name, page.file);+}++describe("docs cover the registry", () => {+ it("every installable component has a docs page declaring it", () => {+ const missing = items+ .filter(({ name }) => !isIcon(name) && !(name in UNDOCUMENTED))+ .filter(({ name }) => !documented.has(name))+ .map(({ registry, name }) => `${registry}/${name}`);++ expect(missing).toEqual([]);+ });++ it("the undocumented allowlist has no stale entries", () => {+ const known = new Set(items.map((i) => i.name));+ const stale = Object.keys(UNDOCUMENTED).filter((name) => !known.has(name));++ expect(stale).toEqual([]);+ });++ it("no allowlisted component secretly has a page", () => {+ const contradictions = Object.keys(UNDOCUMENTED).filter((name) =>+ documented.has(name),+ );++ expect(contradictions).toEqual([]);+ });++ it("icons are documented through the gallery", () => {+ const gallery = readFileSync("content/docs/icons/gallery.mdx", "utf8");++ expect(gallery).toContain("<IconsGallery");+ });+});++describe("component pages carry selection metadata", () => {+ const componentPages = pages.filter(+ (p) => typeof p.frontmatter.component === "string",+ );++ it("declares a component name that exists in a registry", () => {+ const known = new Set(items.map((i) => i.name));+ const unknown = componentPages+ .filter((p) => !known.has(p.frontmatter.component as string))+ .map((p) => `${p.file} -> ${p.frontmatter.component}`);++ expect(unknown).toEqual([]);+ });++ it("declares each component on exactly one page", () => {+ const seen = new Map<string, string[]>();+ for (const page of componentPages) {+ const name = page.frontmatter.component as string;+ seen.set(name, [...(seen.get(name) ?? []), page.file]);+ }+ const duplicated = [...seen.entries()]+ .filter(([, files]) => files.length > 1)+ .map(([name, files]) => `${name}: ${files.join(", ")}`);++ expect(duplicated).toEqual([]);+ });++ it("carries a canonical vibe", () => {+ const offenders = componentPages+ .filter(+ (p) => !VIBES.includes(p.frontmatter.vibe as (typeof VIBES)[number]),+ )+ .map((p) => `${p.file} -> ${p.frontmatter.vibe}`);++ expect(offenders).toEqual([]);+ });++ it("carries a natural length", () => {+ const offenders = componentPages+ .filter((p) => {+ const length = p.frontmatter.length;+ if (length === "state-driven") return false;+ return !(+ typeof length === "number" &&+ Number.isInteger(length) &&+ length > 0+ );+ })+ .map((p) => `${p.file} -> ${p.frontmatter.length}`);++ expect(offenders).toEqual([]);+ });++ it("carries non-empty useWhen and avoidWhen entries", () => {+ const offenders: string[] = [];+ for (const page of componentPages) {+ for (const key of ["useWhen", "avoidWhen"] as const) {+ const value = page.frontmatter[key];+ const ok =+ Array.isArray(value) &&+ value.length > 0 &&+ value.every(+ (entry) => typeof entry === "string" && entry.trim().length > 0,+ );+ if (!ok) offenders.push(`${page.file} -> ${key}`);+ }+ }++ expect(offenders).toEqual([]);+ });++ it("only cites components that exist", () => {+ const known = new Set(items.map((i) => i.name));+ const offenders: string[] = [];+ for (const page of componentPages) {+ const bullets = [+ ...((page.frontmatter.useWhen as string[]) ?? []),+ ...((page.frontmatter.avoidWhen as string[]) ?? []),+ ];+ for (const bullet of bullets) {+ for (const [, token] of bullet.matchAll(+ /`([a-z][a-z0-9]*(?:-[a-z0-9]+)+)`/g,+ )) {+ if (known.has(token)) continue;+ if (bullet.includes(`not shipped`)) continue;+ offenders.push(`${page.file} cites \`${token}\``);+ }+ }+ }++ expect(offenders).toEqual([]);+ });+});++describe("navigation lists every page", () => {+ it("each component page appears in its section meta.json", () => {+ const missing: string[] = [];+ for (const page of pages) {+ if (typeof page.frontmatter.component !== "string") continue;+ const dir = page.file.slice(0, page.file.lastIndexOf("/"));+ const meta = JSON.parse(readFileSync(`${dir}/meta.json`, "utf8"));+ const slug = basename(page.file, ".mdx");+ if (!(meta.pages as string[]).includes(slug)) missing.push(page.file);+ }++ expect(missing).toEqual([]);+ });+});