Skip to content

Production-ready animations, transitions, backgrounds, and scenes for Remotion

docs: add craft section and the six undocumented components

kapishdima7a0a6f57411c
diff --git a/content/changelog/2026-07-25-docs-for-agents.mdx b/content/changelog/2026-07-25-docs-for-agents.mdx
new file mode 100644
index 00000000..9bd16386
--- /dev/null
+++ b/content/changelog/2026-07-25-docs-for-agents.mdx
@@ -0,0 +1,47 @@
+---
+title: Docs your agent can actually read
+date: 2026-07-25
+---
+
+The docs are becoming the single source of truth for both people and coding agents. Every page now
+renders to clean Markdown, a new Craft section holds the house rules that used to live only inside
+the agent skill, and six components that shipped without a page finally have one.
+
+### New pages
+
+Six components were installable from the registry but had no documentation. They do now.
+
+- [Simulated Cursor](/docs/effects/simulated-cursor) — a synthetic cursor that travels between
+ waypoints and fires a click ripple, for narrating a UI on screen
+- [Strikethrough Replace](/docs/typography/strikethrough-replace) — strikes through the old text and
+ fades the new text in beneath it
+- [AI Prompt Flow](/docs/ui/blocks/ai-prompt-flow) — a full prompt-to-answer scene, from typing
+ through loading skeleton to the ready toast
+- [Onboarding Stepper Flow](/docs/ui/blocks/onboarding-stepper-flow) — a stepper advancing through
+ three form panels to a success state
+- [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`
+
+<ChangelogPreview name="simulated-cursor" />
+
+### New section
+
+[Craft](/docs/craft) collects the rules that decide whether a generated video looks machine-made:
+
+- [Design defaults](/docs/craft/design-defaults) — restraint rules for the text and chrome you add
+ yourself, plus the palette and fonts the library already uses
+- [Motion principles](/docs/craft/motion-principles) — the eight classic principles that matter when
+ you assemble scenes from prebuilt blocks
+- [Anti-patterns](/docs/craft/anti-patterns) — the dozen recurring mistakes with the fix beside each
+
+### Improvements
+
+- Appending `.md` to any docs URL now returns real Markdown. Install commands, prop tables and
+ callouts were previously emitted as raw JSX — the install command was invisible entirely, and
+ heading levels were lost. All of it now renders as headings, fenced code blocks, Markdown tables
+ and blockquotes.
+- New [`/llms-components.txt`](https://remocn.dev/llms-components.txt) — every installable component
+ in one table with its use and avoid signal, natural length, vibe, tier and dependencies, linking
+ to 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.
diff --git a/content/docs/craft/anti-patterns.mdx b/content/docs/craft/anti-patterns.mdx
new file mode 100644
index 00000000..e886fa56
--- /dev/null
+++ b/content/docs/craft/anti-patterns.mdx
@@ -0,0 +1,118 @@
+---
+title: Anti-patterns
+description: The dozen mistakes that recur when a video is generated, each with the fix beside it
+---
+
+Common mistakes when generating remocn videos. Each is something a model tends to get wrong.
+
+## Clipping a component by under-budgeting its Sequence
+
+Every component has a natural length. Budget the `Sequence` around it — under-budgeting cuts the
+animation off mid-motion, over-budgeting leaves dead air.
+
+```tsx
+// ❌ blur-out-up needs ~90f, gets cut at 30
+<Sequence durationInFrames={30}><BlurOutUp text="Launch" /></Sequence>
+// ✅
+<Sequence durationInFrames={90}><BlurOutUp text="Launch" /></Sequence>
+```
+
+Natural lengths for every component are listed in
+[`/llms-components.txt`](https://remocn.dev/llms-components.txt).
+
+## Mounting a transition as a component
+
+Transitions are presentations for `@remotion/transitions` — pass them to
+`TransitionSeries.Transition`, never mount them directly.
+
+```tsx
+// ❌
+<WhipPan />
+<SceneB />
+// ✅
+<TransitionSeries>
+ <TransitionSeries.Sequence durationInFrames={70}><SceneA /></TransitionSeries.Sequence>
+ <TransitionSeries.Transition
+ timing={linearTiming({ durationInFrames: 26 })}
+ presentation={whipPan()}
+ />
+ <TransitionSeries.Sequence durationInFrames={70}><SceneB /></TransitionSeries.Sequence>
+</TransitionSeries>
+```
+
+## Animation-tier props on a UI primitive
+
+Primitives (`remocn-ui`) are state-based and have **no `speed`**. Drive them with `state`.
+
+```tsx
+// ❌
+<Dialog speed={2} />
+// ✅
+<Dialog state="open" />
+```
+
+## Wrong canvas size
+
+The standard composition is `1280×720 @ 30fps`. Components are laid out for it. Don't invent
+`1920×1080` and wonder why things are off-center.
+
+## Animating layout properties
+
+Animate `transform` (and individual `translate` / `scale`), never `top` / `left` / `width` /
+`height` — layout animation reflows every frame and breaks split layouts.
+
+```tsx
+// ❌ left: interpolate(frame, [0,30], [0,200])
+// ✅ transform: `translateX(${interpolate(frame,[0,30],[0,200])}px)`
+```
+
+## Non-deterministic code
+
+Renders are multi-pass — `Math.random()`, `setInterval` / `setTimeout` and `Date.now()` all produce
+flicker or diverging frames.
+
+```tsx
+// ❌ const x = Math.random();
+// ✅ import { random } from "@remotion/random"; const x = random(`seed-${frame}`);
+```
+
+## Mishandling registryDependencies
+
+Dependencies install **automatically** — don't tell the user to add them manually, and don't
+inline-copy a dependency's code. Also don't import deeper than one path segment
+(`@/components/remocn/<name>`); the tsconfig glob doesn't resolve `<name>/helpers`.
+
+## Loading fonts mid-render
+
+Load fonts once before render via `@remotion/google-fonts` (`loadFont()`), not inside a component
+body per frame. Unloaded fonts flash a fallback in the export.
+
+## Hardcoding a background on a component
+
+remocn components render **transparent** — they don't own a background. Set the scene background
+with [`backdrop`](/docs/layout/backdrop) or your own container, not by hardcoding a fill into the
+component.
+
+## Slop styling on your own additions
+
+ALL-CAPS plus wide tracking plus gradient text plus glow shadows on text *you* add. See
+[Design defaults](/docs/craft/design-defaults).
+
+## Everything enters on one frame
+
+Stagger sibling entrances by 3–6 frames. Landing a whole group simultaneously reads robotic. See
+[Motion principles](/docs/craft/motion-principles) → follow-through and overlapping action.
+
+## Promoting the wrong layer under a slow zoom
+
+Text under [`drift`](/docs/layout/drift) trembles — glyph rasters snap to whole device pixels while
+the zoom keeps them in sub-pixel motion. The fix is one `willChange: "transform"` layer per **text
+container**. Never promote per-word or per-character spans (many small text layers shimmer even at
+rest) and never `Drift` itself (borders become resampled texture, so 1px lines pulse between sharp
+and blurry as the scale creeps).
+
+```tsx
+// ❌ <Drift><div style={{ willChange: "transform" }}>{scene}</div></Drift> — borders pulse
+// ❌ chars.map((c) => <span style={{ willChange: "transform" }}>{c}</span>) — shimmer at rest
+// ✅ bordered card unpromoted; inner text block gets willChange: "transform"
+```
diff --git a/content/docs/craft/design-defaults.mdx b/content/docs/craft/design-defaults.mdx
new file mode 100644
index 00000000..ae6501b6
--- /dev/null
+++ b/content/docs/craft/design-defaults.mdx
@@ -0,0 +1,125 @@
+---
+title: Design defaults
+description: Restraint rules for the text, chrome and cards you add yourself, plus the palette and fonts the library already uses
+---
+
+These are defaults for content **you author** — your own text, scene chrome, cards, and overlays.
+They keep output from reading as generic AI-slop. They are **not** retroactive rules for the
+prebuilt remocn components.
+
+<Note title="Scope and exception">
+ Never strip these traits from a component whose essence *is* the effect. `tracking-in` is
+ letter-spacing; the shader backdrops and the social cards are gradients; some primitives use
+ subtle elevation. The rules govern your additions, not the library.
+</Note>
+
+## No decorative letter-spacing
+
+Don't widen tracking on text you add. It reads as "designed by AI".
+
+```tsx
+// ✅ default tracking
+<div style={{ fontSize: 64, fontWeight: 600 }}>Ship faster</div>
+
+// ❌ decorative wide tracking
+<div style={{ letterSpacing: "0.3em", textTransform: "uppercase" }}>SHIP FASTER</div>
+```
+
+**Exception:** [`tracking-in`](/docs/typography/tracking-in) animates letter-spacing as its whole
+effect — that's intentional.
+
+## No uppercase or ALL-CAPS defaults
+
+Prefer sentence case. Don't `text-transform: uppercase` and don't write ALL-CAPS string literals
+as defaults.
+
+```tsx
+// ✅
+<BlurOutUp text="Launch week" />
+
+// ❌
+<BlurOutUp text="LAUNCH WEEK" />
+```
+
+Use ALL-CAPS only when the design genuinely calls for it (e.g. a glitch/tech label), not as a
+reflex for emphasis.
+
+## No gradient text-fills or decorative washes
+
+Gradients belong on **backgrounds** that are meant to be gradients — not as text fills or
+decorative overlays sprinkled on cards.
+
+```tsx
+// ✅ gradient as an intentional background
+<ShaderMeshGradient colors={["#0ea5e9", "#9333ea"]} />
+<div style={{ color: "#fafafa" }}>Clear, solid text on top</div>
+
+// ❌ gradient-clipped text + decorative wash
+<h1 style={{
+ background: "linear-gradient(90deg,#0ea5e9,#9333ea)",
+ WebkitBackgroundClip: "text",
+ color: "transparent",
+}}>Slop headline</h1>
+```
+
+**Exception:** [`shimmer-sweep`](/docs/typography/shimmer-sweep) uses `background-clip: text`
+deliberately; social-card cover and avatar fallbacks render gradients by design.
+
+## No glow or heavy shadows
+
+No colored glows, no large blur radii, no multi-layer drop-shadows. Use a 1px border or a small,
+neutral elevation if you need separation.
+
+```tsx
+// ✅ subtle elevation
+boxShadow: "0 1px 2px rgba(0,0,0,0.08)"
+border: "1px solid #e5e5e5"
+
+// ❌ glow / oversized shadow
+boxShadow: "0 0 80px 20px rgba(14,165,233,0.6)"
+filter: "blur(60px)" // decorative glow blob
+```
+
+Threshold to avoid: shadow or `filter` blur `> ~24px`, any `spread`, any colored/glow shadow,
+stacked shadow layers. Decorative radial-gradient or blur "glow blobs" are never acceptable.
+
+**Exception:** components that intentionally model real UI elevation (cards, modals) keep their
+designed shadow — don't flatten them.
+
+## Design tokens
+
+When you author your own text, surfaces, or chrome, pull from the palette the library already
+uses so your additions don't clash with the components.
+
+### Canvas
+
+`1280×720 @ 30fps`. Font weights in use: `400 · 500 · 600 · 700`.
+
+### Palette
+
+| Role | Hex |
+|---|---|
+| Primary text (on light) | `#171717` |
+| Text on dark | `#fafafa` / `#ffffff` |
+| Background — near-black | `#0a0a0a` / `#050505` |
+| Surface — zinc | `#27272a` |
+| Accent — green / success | `#22c55e` |
+| Accent — sky | `#0ea5e9` |
+| Accent — violet | `#a855f7` / `#7c3aed` |
+| Brand — warm (Claude) | `#D97757` |
+
+Stay within this set for your own elements. Brand cards (`claude-chat`, `claude-code`, `v0`,
+`chat-gpt`) carry their own brand hex — don't override it.
+
+### Fonts
+
+Loaded through `@remotion/google-fonts`.
+
+| Use | Font |
+|---|---|
+| UI / body | `Inter` |
+| Display | `Manrope` |
+| Serif display | `Fraunces` |
+| Code / mono | `JetBrainsMono` / `GeistMono` |
+
+Load fonts before render (`@remotion/google-fonts/Inter` → `loadFont()`), never mid-frame.
diff --git a/content/docs/craft/index.mdx b/content/docs/craft/index.mdx
new file mode 100644
index 00000000..e97b38d5
--- /dev/null
+++ b/content/docs/craft/index.mdx
@@ -0,0 +1,24 @@
+---
+title: Craft
+description: The house rules behind a remocn video — restraint in design, intent in motion, and the mistakes that give a generated video away
+---
+
+The component pages tell you what each block does. This section tells you how to put them together
+without the result reading as machine-made.
+
+Three pages, in the order they bite:
+
+- [Design defaults](/docs/craft/design-defaults) — what your **own** additions should look like.
+ Sentence case, default tracking, solid text, no glow. The library's components are exempt where
+ the effect *is* the point.
+- [Motion principles](/docs/craft/motion-principles) — the classic animation principles reduced to
+ the eight that matter when you assemble scenes from prebuilt blocks, each mapped to a Remotion
+ mechanic and a component that demonstrates it.
+- [Anti-patterns](/docs/craft/anti-patterns) — the dozen mistakes that recur, with the fix beside
+ each one. Clipped sequences, transitions mounted as components, `speed` on a primitive.
+
+<Note title="Writing for an agent">
+ These pages are written to be read by coding agents as much as by people. Each is served as raw
+ Markdown at the same URL with `.md` appended, and the
+ [remocn skill](/docs/getting-started/agent-skill) points agents here.
+</Note>
diff --git a/content/docs/craft/meta.json b/content/docs/craft/meta.json
new file mode 100644
index 00000000..b3bfe890
--- /dev/null
+++ b/content/docs/craft/meta.json
@@ -0,0 +1,5 @@
+{
+ "title": "Craft",
+ "collapsible": false,
+ "pages": ["index", "design-defaults", "motion-principles", "anti-patterns"]
+}
diff --git a/content/docs/craft/motion-principles.mdx b/content/docs/craft/motion-principles.mdx
new file mode 100644
index 00000000..bb3a3537
--- /dev/null
+++ b/content/docs/craft/motion-principles.mdx
@@ -0,0 +1,115 @@
+---
+title: Motion principles
+description: The classic animation principles reduced to the eight that matter when you assemble scenes from prebuilt blocks
+---
+
+The 12 classic animation principles, adapted to **composing Remotion videos from remocn blocks**.
+Each entry gives the principle, the Remotion mechanic that expresses it, a remocn component that
+demonstrates it, and a do/avoid tuned to remocn's restraint.
+
+This page is about **which** principle and **when** — intent. For **how** the APIs work (easing
+curves, sequencing, spring config), read the Remotion docs. Where a principle pushes toward
+boldness (squash, exaggeration), the cap in [Design defaults](/docs/craft/design-defaults) always
+wins.
+
+remocn components drive motion with `spring()` and `interpolate()` + `Easing`; the examples below
+use that same idiom.
+
+The eight principles here are routinely useful when assembling scenes. The remaining four are
+character-animation territory and are compressed at the end.
+
+## Anticipation
+
+A short wind-up before the action makes it feel intentional: a drawer dips before it expands.
+
+- **Mechanic:** `spring()` with light overshoot, or a brief reverse `interpolate` (e.g. `−4px`)
+ for 1–3 frames before the main move.
+- **remocn:** [`spring-scale-in`](/docs/typography/spring-scale-in).
+- **Do/Avoid:** keep the wind-up to 1–3 frames, ≤110% scale. ❌ No bouncy cartoon recoil.
+
+## Staging
+
+Direct the eye: one clear idea per scene. Clear the stage before introducing the next element.
+
+- **Mechanic:** `<Sequence>` / `<Series>` to isolate beats; stagger entrances so only one focal
+ element moves at a time; dim or scale down what's leaving.
+- **remocn:** most [compositions](/docs/compositions).
+- **Do/Avoid:** one focal action per beat. ❌ Don't enter five elements on the same frame.
+
+## Follow-through and overlapping action
+
+Nothing stops at once; elements arrive staggered. Lighter things lead, heavier lag.
+
+- **Mechanic:** per-element delay offsets (`frame - index * stagger`) on the same animation.
+- **remocn:** [`staggered-fade-up`](/docs/typography/staggered-fade-up),
+ [`short-slide-right`](/docs/typography/short-slide-right).
+- **Do/Avoid:** stagger 3–6 frames between siblings. ❌ Don't land a whole group on one frame
+ (reads robotic) and don't over-stagger (feels sluggish).
+
+## Slow in and slow out
+
+Ease into and out of poses — almost nothing should move linearly.
+
+- **Mechanic:** `interpolate(..., { easing: Easing.out(Easing.cubic) })`; a sharp curve reads
+ snappy, a gentle one graceful.
+- **remocn:** transitions ([`whip-pan`](/docs/transitions/whip-pan),
+ [`focus-pull`](/docs/transitions/focus-pull)), most text reveals.
+- **Do/Avoid:** default to ease-out for entrances. ❌ Linear `interpolate` for visible motion
+ unless it's a constant drift (e.g. marquee, grid pan).
+
+## Arc
+
+Living motion follows curves, not straight lines — especially cursors and gestures.
+
+- **Mechanic:** drive `x` and `y` from separate eased interpolations, or a bezier path.
+- **remocn:** [`cursor`](/docs/ui/components/cursor) and `useCursorPath`, the social cards' cursor
+ travel to the Follow button.
+- **Do/Avoid:** curve cursor and hand paths. ❌ No straight diagonal cursor jumps.
+
+## Secondary action
+
+Supporting motion that reinforces the primary action without stealing focus.
+
+- **Mechanic:** a small parallel channel — a cursor ripple on click, a shadow that breathes as a
+ card opens, a caret blink under typing.
+- **remocn:** [`x-follow-card`](/docs/social/x-follow-card) (ripple at click),
+ [`typewriter`](/docs/typography/typewriter) (caret blink).
+- **Do/Avoid:** secondary motion stays subtle and on-theme. ❌ Don't add competing animation that
+ splits attention.
+
+## Timing
+
+Frame counts set weight: fast reads light, slow reads heavy. Vary timing for contrast.
+
+- **Mechanic:** budget in frames at the composition fps (remocn defaults to 30fps; component
+ durations run ~90–300 frames). The `speed` prop scales the animation tier.
+- **remocn:** every animation-tier component (`speed`); composition `durationInFrames`.
+- **Do/Avoid:** match duration to weight — a heavy hero assemble is slower than a toast. ❌ Don't
+ reuse one duration for everything; it kills rhythm.
+
+## Exaggeration, capped
+
+Push slightly past literal reality for clarity — but remocn's house style is restraint.
+
+- **Mechanic:** a touch of overshoot on `spring()`, a brief ≤110% scale peak.
+- **remocn:** [`spring-scale-in`](/docs/typography/spring-scale-in),
+ [`micro-scale-fade`](/docs/typography/micro-scale-fade).
+- **Do/Avoid:** subtle UI exaggeration only (≤110%, gentle overshoot). ❌ No stretched or cartoon
+ exaggeration. This is the principle most likely to collide with
+ [Design defaults](/docs/craft/design-defaults); the cap wins.
+
+## Rarely needed when composing blocks
+
+Character-animation territory — reach for these only when hand-drawing motion, not when
+assembling catalog components.
+
+- **Squash and stretch** — at most a 2–4% `scaleX`/`scaleY` volume trade on a hard landing
+ (`spring-scale-in`, `confetti`); rubber-band squash on text or cards fights the design defaults.
+- **Straight-ahead vs pose-to-pose** — remocn is pose-to-pose by construction:
+ `interpolate(frame, [k0, k1, k2], [v0, v1, v2])` keyframes are your poses. Straight-ahead
+ (frame-by-frame) is for hand-drawn organic effects.
+- **Solid drawing** — keep one `perspective` and vanishing point per scene when stacking 3D layers
+ ([`push-through`](/docs/transitions/push-through),
+ [`perspective-marquee`](/docs/typography/perspective-marquee)).
+- **Appeal** — emergent from staging, timing and restraint, not a knob. More motion is not more
+ appeal.
diff --git a/content/docs/effects/meta.json b/content/docs/effects/meta.json
index 37300bc4..29b21011 100644
--- a/content/docs/effects/meta.json
+++ b/content/docs/effects/meta.json
@@ -7,6 +7,7 @@
"paper-wobble",
"ink-arrow",
"scribble-circle",
- "crumple-toss"
+ "crumple-toss",
+ "simulated-cursor"
]
}
diff --git a/content/docs/effects/simulated-cursor.mdx b/content/docs/effects/simulated-cursor.mdx
new file mode 100644
index 00000000..f5577b42
--- /dev/null
+++ b/content/docs/effects/simulated-cursor.mdx
@@ -0,0 +1,156 @@
+---
+title: Simulated Cursor
+description: A synthetic mouse cursor that travels between waypoints and fires a click ripple, for narrating a UI on screen
+component: simulated-cursor
+vibe: clean
+length: 150
+useWhen:
+ - "You are narrating a screen demo and need a synthetic cursor that moves predictably over a UI screenshot or recording"
+ - "You want to direct attention to a specific element by having the cursor travel to it and click"
+ - "You are pairing it with `typewriter` to simulate a user typing into a field the cursor just landed on"
+avoidWhen:
+ - "You need a real screen recording — this draws a synthetic overlay, not a capture of actual mouse movement"
+ - "The video is abstract or non-UI (motion graphics, product reveal, pure text) — a floating arrow reads as a tutorial and breaks the mood"
+ - "The underlying layout shifts between scenes — waypoints are absolute canvas pixels, so the cursor will land in the wrong place"
+---
+
+<ComponentPreview name="simulated-cursor" />
+
+## Installation
+
+<InstallBlock name="simulated-cursor" />
+
+## Usage
+
+The cursor walks the `points` array in order. Each leg takes a fixed 24 frames of travel, then rests
+for that point's `hold` (default `15`). A point marked `click` fires a ripple when the cursor
+arrives.
+
+```tsx
+// src/Root.tsx
+import { Composition } from "remotion";
+import { SimulatedCursor } from "@/components/remocn/simulated-cursor";
+
+const CursorScene = () => (
+ <SimulatedCursor
+ points={[
+ { x: 200, y: 150, hold: 20 },
+ { x: 800, y: 360, hold: 25, click: true },
+ { x: 1050, y: 560, hold: 20 },
+ ]}
+ color="#171717"
+ size={28}
+ />
+);
+
+export const RemotionRoot = () => (
+ <Composition
+ id="SimulatedCursor"
+ component={CursorScene}
+ durationInFrames={150}
+ fps={30}
+ width={1280}
+ height={720}
+ />
+);
+```
+
+<Note title="Coordinates are canvas pixels">
+ `x` and `y` are absolute pixels on the composition canvas, not normalized `0–1` values. On the
+ standard `1280×720` canvas, `{ x: 640, y: 360 }` is dead center. Change the canvas size and the
+ waypoints move with it.
+</Note>
+
+### Over a screenshot
+
+The component renders transparent, so layer it above whatever it is pointing at.
+
+```tsx
+import { AbsoluteFill, Img, staticFile } from "remotion";
+import { SimulatedCursor } from "@/components/remocn/simulated-cursor";
+
+const DemoScene = () => (
+ <AbsoluteFill>
+ <Img src={staticFile("dashboard.png")} style={{ width: "100%", height: "100%" }} />
+ <SimulatedCursor
+ points={[
+ { x: 320, y: 210, hold: 18 },
+ { x: 760, y: 420, hold: 24, click: true },
+ ]}
+ color="#171717"
+ />
+ </AbsoluteFill>
+);
+```
+
+## Timing
+
+Budget the `Sequence` from the waypoints: `24` frames per leg plus each point's `hold`. The default
+three-point path runs about `93` frames; leave headroom for the click ripple to finish.
+
+## Props
+
+<PropsTable
+ rows={[
+ {
+ name: "points",
+ type: "CursorPoint[]",
+ default: "DEFAULT_POINTS",
+ description: "Waypoints the cursor travels through, in order. Each is { x, y, hold?, click? } in absolute canvas pixels.",
+ },
+ {
+ name: "color",
+ type: "string",
+ default: "\"#ffffff\"",
+ description: "Fill color of the cursor arrow. Use a dark value over light UI screenshots.",
+ },
+ {
+ name: "size",
+ type: "number",
+ default: "32",
+ description: "Height of the cursor arrow in pixels.",
+ },
+ {
+ name: "speed",
+ type: "number",
+ default: "1",
+ description: "Time multiplier applied as frame × speed. Above 1 the cursor completes its path sooner.",
+ },
+ {
+ name: "className",
+ type: "string",
+ description: "Optional className passed to the wrapper element.",
+ },
+ ]}
+/>
+
+### CursorPoint
+
+<PropsTable
+ rows={[
+ {
+ name: "x",
+ type: "number",
+ required: true,
+ description: "Horizontal position in canvas pixels.",
+ },
+ {
+ name: "y",
+ type: "number",
+ required: true,
+ description: "Vertical position in canvas pixels.",
+ },
+ {
+ name: "hold",
+ type: "number",
+ default: "15",
+ description: "Frames the cursor rests at this point after arriving, before starting the next leg.",
+ },
+ {
+ name: "click",
+ type: "boolean",
+ default: "false",
+ description: "Fires a click ripple when the cursor arrives at this point.",
+ },
+ ]}
+/>
diff --git a/content/docs/meta.json b/content/docs/meta.json
index f84b303a..56c4ad36 100644
--- a/content/docs/meta.json
+++ b/content/docs/meta.json
@@ -3,6 +3,7 @@
"pages": [
"getting-started",
"guides",
+ "craft",
"layout",
"typography",
"ui",
diff --git a/content/docs/typography/meta.json b/content/docs/typography/meta.json
index 74af0a85..172aaf40 100644
--- a/content/docs/typography/meta.json
+++ b/content/docs/typography/meta.json
@@ -17,6 +17,7 @@
"fade-through",
"shared-axis-y",
"shared-axis-z",
+ "strikethrough-replace",
"short-slide-right",
"kinetic-center-build",
"short-slide-down",
diff --git a/content/docs/typography/strikethrough-replace.mdx b/content/docs/typography/strikethrough-replace.mdx
new file mode 100644
index 00000000..eb7b4778
--- /dev/null
+++ b/content/docs/typography/strikethrough-replace.mdx
@@ -0,0 +1,120 @@
+---
+title: Strikethrough Replace
+description: Draws a strike line through the old text, then fades the new text in beneath it for an editorial correction
+component: strikethrough-replace
+vibe: clean
+length: 120
+useWhen:
+ - "Showing a problem being replaced by a solution — the strike says you are crossing this out on purpose"
+ - "A pricing or comparison beat needs the old value visibly struck out before the new one appears"
+ - "You want editorial correction grammar — old thinking struck through, new thinking revealed below"
+avoidWhen:
+ - "There is no old text to cross out and you just need an entrance — use `staggered-fade-up` or `soft-blur-in`"
+ - "The swap should feel smooth and spatial rather than editorial — use `shared-axis-y` or `shared-axis-z`"
+ - "Both strings are long — the struck line gets hard to read and the full animation runs 120 frames"
+---
+
+<ComponentPreview name="strikethrough-replace" />
+
+## Installation
+
+<InstallBlock name="strikethrough-replace" />
+
+## Usage
+
+Keep `from` and `to` short. The strike reads as a deliberate edit, and a long struck-out line is
+hard to parse at speed.
+
+```tsx
+// src/Root.tsx
+import { Composition } from "remotion";
+import { StrikethroughReplace } from "@/components/remocn/strikethrough-replace";
+
+const StrikethroughScene = () => (
+ <StrikethroughReplace from="Manual video editing" to="One-click export" fontSize={48} />
+);
+
+export const RemotionRoot = () => (
+ <Composition
+ id="StrikethroughReplace"
+ component={StrikethroughScene}
+ durationInFrames={120}
+ fps={30}
+ width={1280}
+ height={720}
+ />
+);
+```
+
+The line draws across `from` first, then `to` fades in beneath it — so the composition needs room
+for both phases. Under-budgeting cuts the reveal.
+
+### With Backdrop
+
+The component renders transparent — supply the background via `Backdrop`.
+
+```tsx
+import { Composition } from "remotion";
+import { Backdrop } from "@/components/remocn/backdrop";
+import { StrikethroughReplace } from "@/components/remocn/strikethrough-replace";
+
+const StrikethroughScene = () => (
+ <Backdrop fill={{ type: "color", value: "#ffffff" }}>
+ <StrikethroughReplace from="$99 / month" to="$29 / month" lineColor="#ff5e3a" />
+ </Backdrop>
+);
+```
+
+## Props
+
+<PropsTable
+ rows={[
+ {
+ name: "from",
+ type: "string",
+ required: true,
+ description: "The old text — the line is drawn across this string.",
+ },
+ {
+ name: "to",
+ type: "string",
+ required: true,
+ description: "The replacement text, revealed beneath the struck-out line.",
+ },
+ {
+ name: "lineColor",
+ type: "string",
+ default: "\"#ff5e3a\"",
+ description: "Color of the strike line. Defaults to a red-orange for maximum contrast against the text.",
+ },
+ {
+ name: "fontSize",
+ type: "number",
+ default: "48",
+ description: "Font size in pixels, applied to both strings.",
+ },
+ {
+ name: "color",
+ type: "string",
+ default: "\"#171717\"",
+ description: "Text color (any valid CSS color).",
+ },
+ {
+ name: "fontWeight",
+ type: "number",
+ default: "600",
+ description: "CSS font-weight.",
+ },
+ {
+ name: "speed",
+ type: "number",
+ default: "1",
+ description: "Time multiplier applied as frame × speed.",
+ },
+ {
+ name: "className",
+ type: "string",
+ description: "Optional className passed to the root element.",
+ },
+ ]}
+/>
diff --git a/content/docs/ui/blocks/ai-prompt-flow.mdx b/content/docs/ui/blocks/ai-prompt-flow.mdx
new file mode 100644
index 00000000..382487e0
--- /dev/null
+++ b/content/docs/ui/blocks/ai-prompt-flow.mdx
@@ -0,0 +1,109 @@
+---
+title: AI Prompt Flow
+description: A full prompt-to-answer scene — the prompt types itself, the button runs to loading, a skeleton reveals, and the answer crossfades in
+component: ai-prompt-flow
+vibe: clean
+length: 230
+useWhen:
+ - "Demoing an AI product's whole prompt-to-answer experience in one self-contained scene"
+ - "Showing the generation lifecycle end to end — typing, loading, answer reveal, confirmation toast"
+ - "A product walkthrough needs a polished AI workflow beat with no custom timing work"
+avoidWhen:
+ - "You only need a button press with a loading state — use `button` with `state=\"loading\"`"
+ - "You only need a field that types — use `input` directly"
+ - "You need custom orchestration or step control across scenes — compose the primitives manually"
+---
+
+<BlockPreview name="ai-prompt-flow" />
+
+A composition scene that plays the full lifecycle of an AI generation: the prompt types into the
+field, the Generate button runs hover → press → loading, a skeleton shimmer stands in for the
+response, then crossfades into the generated answer, and a ready toast slides in. It is a pure
+orchestrator — every channel comes from a composed primitive's transition hook, so nothing is
+hand-timed.
+
+## Installation
+
+<InstallBlock name="ai-prompt-flow" />
+
+<Note>
+Installing `ai-prompt-flow` automatically installs the shared `remocn-ui` core and all composed primitives via `registryDependencies`: `input`, `button`, `skeleton`, `skeleton-block`, and `toast`. You do not need to install them separately.
+</Note>
+
+## Composed primitives
+
+- **Input** — the prompt field; the prompt reveals character by character while the field sits in its active state
+- **Button** — the Generate action, driven through hover, press, and loading states
+- **Skeleton** and **SkeletonBlock** — the shimmer placeholder standing in for the pending response
+- **Toast** — the confirmation that slides in once the answer has landed
+
+## Timeline narrative
+
+The scene opens with the prompt field active and empty. The prompt types itself in, the Generate
+button picks up hover then press, and drops into its loading state. The answer area swaps to a
+skeleton shimmer while generation is pending, then crossfades from shimmer to the real answer lines.
+A toast slides in to confirm the response is ready and dismisses near frame 220, leaving a short
+settle before the scene ends at 230.
+
+## Usage
+
+```tsx
+// src/Root.tsx
+import { Composition } from "remotion";
+import { AiPromptFlow } from "@/components/remocn/ai-prompt-flow";
+
+const PromptScene = () => (
+ <AiPromptFlow
+ prompt="Summarize this thread"
+ buttonLabel="Generate"
+ toastTitle="Response ready"
+ />
+);
+
+export const RemotionRoot = () => (
+ <Composition
+ id="AiPromptFlow"
+ component={PromptScene}
+ durationInFrames={230}
+ fps={30}
+ width={1280}
+ height={720}
+ />
+);
+```
+
+## Props
+
+<PropsTable
+ rows={[
+ {
+ name: "prompt",
+ type: "string",
+ default: "\"Summarize this thread\"",
+ description: "The prompt text typed into the input field.",
+ },
+ {
+ name: "buttonLabel",
+ type: "string",
+ default: "\"Generate\"",
+ description: "Label on the action button that runs to its loading state.",
+ },
+ {
+ name: "answerLines",
+ type: "string[]",
+ default: "DEFAULT_ANSWER",
+ description: "Lines of the generated answer revealed after the skeleton crossfade.",
+ },
+ {
+ name: "toastTitle",
+ type: "string",
+ default: "\"Response ready\"",
+ description: "Title of the toast that slides in once the answer has landed.",
+ },
+ {
+ name: "theme",
+ type: "Partial<RemocnTheme>",
+ description: "Theme overrides forwarded to every composed primitive.",
+ },
+ ]}
+/>
diff --git a/content/docs/ui/blocks/meta.json b/content/docs/ui/blocks/meta.json
index bf5d342a..83d048f1 100644
--- a/content/docs/ui/blocks/meta.json
+++ b/content/docs/ui/blocks/meta.json
@@ -8,6 +8,8 @@
"imessage-chat-flow",
"signup-flow",
"checkout-flow",
+ "onboarding-stepper-flow",
+ "ai-prompt-flow",
"settings-toggle-flow"
]
}
diff --git a/content/docs/ui/blocks/onboarding-stepper-flow.mdx b/content/docs/ui/blocks/onboarding-stepper-flow.mdx
new file mode 100644
index 00000000..62e4b9c8
--- /dev/null
+++ b/content/docs/ui/blocks/onboarding-stepper-flow.mdx
@@ -0,0 +1,120 @@
+---
+title: Onboarding Stepper Flow
+description: A multi-step onboarding scene where a stepper advances through form panels and finishes on a success state
+component: onboarding-stepper-flow
+vibe: clean
+length: 175
+useWhen:
+ - "Demoing a multi-step onboarding experience — account setup, plan choice, preferences — in one scene"
+ - "Showing progressive form completion with a stepper indicator advancing across panels"
+ - "A product video needs a complete new-user flow from first input to success without custom orchestration"
+avoidWhen:
+ - "The flow is a payment checkout — use `checkout-flow`, which is cursor-driven with card entry and a toast"
+ - "It is a single account sign-up (email and password, then success) — use `signup-flow`"
+ - "You need custom panel content like images or code blocks — the panels render fixed primitives, so orchestrate manually"
+---
+
+<BlockPreview name="onboarding-stepper-flow" />
+
+A composition scene that walks a new user through three onboarding steps. A horizontal stepper
+advances across panels of input, radio, and switch fields, finishing on a Finish button that runs to
+success. The panel crossfade derives linearly from the stepper's exposed position channel; every
+other channel comes from a composed primitive's hook.
+
+## Installation
+
+<InstallBlock name="onboarding-stepper-flow" />
+
+<Note>
+Installing `onboarding-stepper-flow` automatically installs the shared `remocn-ui` core and all composed primitives via `registryDependencies`: `stepper`, `input`, `radio`, `switch`, and `button`. You do not need to install them separately.
+</Note>
+
+## Composed primitives
+
+- **Stepper** — the horizontal progress indicator; its position channel also drives the panel crossfade
+- **Input** — the account panel's email field, which types itself in
+- **Radio** — the plan selection panel
+- **Switch** — the preferences panel toggles
+- **Button** — the Next and Finish actions, with Finish running through to success
+
+## Timeline narrative
+
+The scene opens on step one with the email typing into the input. The stepper advances to step two
+around frame 64, crossfading to the plan panel where a radio option is selected. It advances again
+around frame 104 to the preferences panel and its switches. The Finish button then runs to its
+success state at 156, leaving about 20 frames of settle before the scene ends at 175.
+
+## Usage
+
+```tsx
+// src/Root.tsx
+import { Composition } from "remotion";
+import { OnboardingStepperFlow } from "@/components/remocn/onboarding-stepper-flow";
+
+const OnboardingScene = () => (
+ <OnboardingStepperFlow
+ steps={["Account", "Plan", "Settings"]}
+ finishLabel="Finish"
+ />
+);
+
+export const RemotionRoot = () => (
+ <Composition
+ id="OnboardingStepperFlow"
+ component={OnboardingScene}
+ durationInFrames={175}
+ fps={30}
+ width={1280}
+ height={720}
+ />
+);
+```
+
+<Note title="Step count is fixed at three">
+ The internal schedule advances the stepper at frames 64 and 104, so `steps` renames the three
+ panels rather than adding or removing them. For a different number of steps, compose `stepper`
+ with your own panels directly.
+</Note>
+
+## Props
+
+<PropsTable
+ rows={[
+ {
+ name: "steps",
+ type: "string[]",
+ default: "DEFAULT_STEPS",
+ description: "Labels for the three stepper positions.",
+ },
+ {
+ name: "name",
+ type: "string",
+ default: "\"[email protected]\"",
+ description: "Value typed into the account panel's input field.",
+ },
+ {
+ name: "plans",
+ type: "string[]",
+ default: "DEFAULT_PLANS",
+ description: "Options rendered as radio choices in the plan panel.",
+ },
+ {
+ name: "nextLabel",
+ type: "string",
+ default: "\"Next\"",
+ description: "Label on the advance button shown on the first two panels.",
+ },
+ {
+ name: "finishLabel",
+ type: "string",
+ default: "\"Finish\"",
+ description: "Label on the final button that runs through to its success state.",
+ },
+ {
+ name: "theme",
+ type: "Partial<RemocnTheme>",
+ description: "Theme overrides forwarded to every composed primitive.",
+ },
+ ]}
+/>
diff --git a/content/docs/ui/components/field.mdx b/content/docs/ui/components/field.mdx
new file mode 100644
index 00000000..c3a3eb6e
--- /dev/null
+++ b/content/docs/ui/components/field.mdx
@@ -0,0 +1,203 @@
+---
+title: Field
+description: A static layout family for composing labeled form controls with consistent vertical spacing
+component: field
+vibe: clean
+length: state-driven
+useWhen:
+ - "Laying out labeled form controls — label, animated control, description hint — with consistent spacing"
+ - "Composing a form scene inside `checkout-flow` or `onboarding-stepper-flow` where several inputs need to align"
+ - "Wrapping any remocn-ui control that needs a visible label above it without hardcoding layout math"
+avoidWhen:
+ - "You need the control itself to animate — `field` is layout only; put `input` or `button` inside it"
+ - "There is a single unlabeled control — use the primitive directly"
+ - "The layout is horizontal or a grid — `FieldGroup` only stacks vertically"
+---
+
+A static layout family for composing labeled form controls, modeled on shadcn's Field. It reads no
+frame and holds no state — colors come from the resolved theme, and all motion belongs to whatever
+you place inside it.
+
+The nesting order is `FieldGroup` ▸ `Field` ▸ `FieldLabel` / `FieldControl` / `FieldDescription`.
+
+## Installation
+
+<InstallBlock name="field" />
+
+<Note>
+Installing `field` automatically installs the shared `remocn-ui` core (`lib/remocn-ui/`) via `registryDependencies`. You do not need to install it separately.
+</Note>
+
+## Usage
+
+`FieldControl` is a relative, fixed-height slot. The remocn-ui controls position themselves
+absolutely, so they need that slot to sit in — put `input` and `button` inside `FieldControl` rather
+than directly inside `Field`.
+
+```tsx
+// src/Root.tsx
+import { Composition } from "remotion";
+import {
+ Field,
+ FieldControl,
+ FieldDescription,
+ FieldGroup,
+ FieldLabel,
+} from "@/components/remocn/field";
+import { Input } from "@/components/remocn/input";
+
+const FormScene = () => (
+ <FieldGroup gap={16}>
+ <Field>
+ <FieldLabel>Email</FieldLabel>
+ <FieldControl>
+ <Input state="idle" value="[email protected]" />
+ </FieldControl>
+ <FieldDescription>We'll never share your email.</FieldDescription>
+ </Field>
+ </FieldGroup>
+);
+
+export const RemotionRoot = () => (
+ <Composition
+ id="Field"
+ component={FormScene}
+ durationInFrames={120}
+ fps={30}
+ width={1280}
+ height={720}
+ />
+);
+```
+
+## Props
+
+### FieldGroup
+
+Stacks fields vertically.
+
+<PropsTable
+ rows={[
+ {
+ name: "children",
+ type: "ReactNode",
+ required: true,
+ description: "The Field elements to stack.",
+ },
+ {
+ name: "gap",
+ type: "number",
+ default: "16",
+ description: "Vertical gap between fields in pixels.",
+ },
+ {
+ name: "style",
+ type: "CSSProperties",
+ description: "Style overrides merged onto the group container.",
+ },
+ ]}
+/>
+
+### Field
+
+One label, control, and description grouped together.
+
+<PropsTable
+ rows={[
+ {
+ name: "children",
+ type: "ReactNode",
+ required: true,
+ description: "Typically a FieldLabel, a FieldControl, and an optional FieldDescription.",
+ },
+ {
+ name: "gap",
+ type: "number",
+ default: "6",
+ description: "Vertical gap between the label, control, and description in pixels.",
+ },
+ {
+ name: "style",
+ type: "CSSProperties",
+ description: "Style overrides merged onto the field container.",
+ },
+ ]}
+/>
+
+### FieldLabel
+
+<PropsTable
+ rows={[
+ {
+ name: "children",
+ type: "ReactNode",
+ required: true,
+ description: "Label text shown above the control.",
+ },
+ {
+ name: "theme",
+ type: "Partial<RemocnTheme>",
+ description: "Theme overrides for the label's color.",
+ },
+ {
+ name: "style",
+ type: "CSSProperties",
+ description: "Style overrides merged onto the label.",
+ },
+ ]}
+/>
+
+### FieldControl
+
+The relative, fixed-height slot the absolutely positioned controls live in.
+
+<PropsTable
+ rows={[
+ {
+ name: "children",
+ type: "ReactNode",
+ required: true,
+ description: "The remocn-ui control to host, such as input or button.",
+ },
+ {
+ name: "height",
+ type: "number",
+ default: "40",
+ description: "Height of the slot in pixels. Match it to the control you are placing inside.",
+ },
+ {
+ name: "style",
+ type: "CSSProperties",
+ description: "Style overrides merged onto the slot.",
+ },
+ ]}
+/>
+
+### FieldDescription
+
+<PropsTable
+ rows={[
+ {
+ name: "children",
+ type: "ReactNode",
+ required: true,
+ description: "Hint text shown beneath the control.",
+ },
+ {
+ name: "align",
+ type: "\"start\" | \"center\"",
+ default: "\"start\"",
+ description: "Horizontal alignment of the description text.",
+ },
+ {
+ name: "theme",
+ type: "Partial<RemocnTheme>",
+ description: "Theme overrides for the description's color.",
+ },
+ {
+ name: "style",
+ type: "CSSProperties",
+ description: "Style overrides merged onto the description.",
+ },
+ ]}
+/>
diff --git a/content/docs/ui/components/meta.json b/content/docs/ui/components/meta.json
index deccace4..e1413f10 100644
--- a/content/docs/ui/components/meta.json
+++ b/content/docs/ui/components/meta.json
@@ -16,6 +16,7 @@
"drawer",
"sheet",
"dropdown-menu",
+ "field",
"input",
"message-bubble",
"popover",
@@ -24,6 +25,7 @@
"resizable",
"select",
"skeleton",
+ "skeleton-block",
"slider",
"spinner",
"stepper",
diff --git a/content/docs/ui/components/skeleton-block.mdx b/content/docs/ui/components/skeleton-block.mdx
new file mode 100644
index 00000000..e2b746c4
--- /dev/null
+++ b/content/docs/ui/components/skeleton-block.mdx
@@ -0,0 +1,124 @@
+---
+title: Skeleton Block
+description: A single shimmer placeholder rectangle whose highlight sweep is a pure function of the frame
+component: skeleton-block
+vibe: clean
+length: 120
+useWhen:
+ - "Building a custom skeleton layout by composing individual shimmer rectangles at precise dimensions"
+ - "Adding one loading placeholder inside another component or composition"
+ - "You need per-rectangle control over size, radius, speed, and colors"
+avoidWhen:
+ - "You want shimmer and real content to crossfade automatically — use `skeleton`, which takes a loading/loaded state and children"
+ - "You need a spinning arc loader rather than a rectangle — use `spinner`"
+ - "The placeholder is a whole layout of card, avatar, and lines — use `skeleton` with its `layout` prop instead of assembling blocks by hand"
+---
+
+The motion atom underneath [`skeleton`](/docs/ui/components/skeleton). A directional highlight
+gradient sweeps across the block deterministically from `useCurrentFrame()` and loops seamlessly, so
+any number of blocks stay in phase without coordination.
+
+Unlike most primitives in this tier it has no `state` — it is always shimmering. Reach for it when
+you are laying out a placeholder yourself; reach for `skeleton` when you want the loading-to-loaded
+crossfade handled for you.
+
+## Installation
+
+<InstallBlock name="skeleton-block" />
+
+<Note>
+Installing `skeleton-block` automatically installs the shared `remocn-ui` core (`lib/remocn-ui/`) via `registryDependencies`. You do not need to install it separately.
+</Note>
+
+## Usage
+
+```tsx
+// src/Root.tsx
+import { Composition } from "remotion";
+import { SkeletonBlock } from "@/components/remocn/skeleton-block";
+
+const LoadingCard = () => (
+ <div style={{ display: "flex", flexDirection: "column", gap: 10 }}>
+ <SkeletonBlock width={240} height={20} radius={4} />
+ <SkeletonBlock width={180} height={16} />
+ <SkeletonBlock width={200} height={16} />
+ </div>
+);
+
+export const RemotionRoot = () => (
+ <Composition
+ id="SkeletonBlock"
+ component={LoadingCard}
+ durationInFrames={120}
+ fps={30}
+ width={1280}
+ height={720}
+ />
+);
+```
+
+The sweep loops, so `durationInFrames` only needs to cover as long as you want the placeholder on
+screen — there is no entrance or exit to budget for.
+
+### Inside a flex row
+
+`width` accepts a string, so a block can fill remaining space. Pair it with `flexShrink` when a
+fixed-width block sits next to a flexible one.
+
+```tsx
+<div style={{ display: "flex", alignItems: "center", gap: 12 }}>
+ <SkeletonBlock width={40} height={40} radius={20} flexShrink={0} />
+ <SkeletonBlock width="100%" height={16} />
+</div>
+```
+
+## Props
+
+<PropsTable
+ rows={[
+ {
+ name: "width",
+ type: "number | string",
+ default: "120",
+ description: "Block width. A number is pixels; a string passes through as a CSS width, so \"100%\" fills the container.",
+ },
+ {
+ name: "height",
+ type: "number",
+ default: "16",
+ description: "Block height in pixels.",
+ },
+ {
+ name: "radius",
+ type: "number",
+ default: "6",
+ description: "Corner radius in pixels. Match half the height for a pill or avatar circle.",
+ },
+ {
+ name: "speed",
+ type: "number",
+ default: "1",
+ description: "Time multiplier for the highlight sweep, applied as frame × speed.",
+ },
+ {
+ name: "baseColor",
+ type: "string",
+ description: "Base fill of the block. Falls back to the resolved theme's muted surface.",
+ },
+ {
+ name: "highlightColor",
+ type: "string",
+ description: "Color of the sweeping highlight. Falls back to the resolved theme.",
+ },
+ {
+ name: "flexShrink",
+ type: "number",
+ description: "CSS flex-shrink on the block. Set to 0 to stop a fixed-width block collapsing inside a flex row.",
+ },
+ {
+ name: "className",
+ type: "string",
+ description: "Optional className passed to the block element.",
+ },
+ ]}
+/>