remotion-best-practices

version	1.1.0
name	remotion-best-practices
description	Best practices for Remotion video creation in React — scaffolding, compositions, animations, transitions — PLUS hard-won rules for high-fidelity product-demo videos: real logos/icons, precise YouTube-reference matching, full-screen camera zooms, click-targets that actually hit, content-tight rectangle highlights, voiceover regeneration discipline, audio-level normalization (no double-boost), per-scene voice-sync math, Studio detail-page mirror patterns, bold-not-subtle connection lines, and the YouTube publication kit (chapters, description, thumbnail, hashtags) that turns a render into a shipped video.
metadata	{"tags":"remotion, video, react, animation, composition, demo-videos, product-demos, voiceover, audio-normalization, youtube-publishing"}

/remotion-best-practices

Use this skill any time you are writing a Remotion composition — animated demo videos, product walkthroughs, hackathon submissions, narrated presentations — anything rendered to MP4 via npx remotion render.

The skill bundles two layers of knowledge:

1. Remotion fundamentals — the upstream rule files maintained by the Remotion team at github.com/remotion-dev/skills (compositions, animations, fonts, audio, transitions, FFmpeg, captions, etc.).
2. Demo-video craft rules — lessons captured from a long iteration cycle building the vskill / Skill Studio hackathon demo. These are the rules that, when broken, produce a "slideshow" instead of a believable product walkthrough.

Read both layers before authoring.

---

Scope and applicability

The Layer 2 craft rules below were derived from one specific project: the vskill / Skill Studio hackathon demo (Anthropic / Claude Code "Built with Opus" hackathon, April 2026). They reflect the look-and-feel of that product — Studio chrome with breadcrumb header, sidebar tree, dark verified-skill.com pages with mono fonts, terminal scenes, an editorial "Inter is AI-slop, distinctive serif is excellence" thesis.

Do not apply these rules verbatim to unrelated demos. A consumer-mobile, a finance dashboard, a game, or a B2B SaaS pitch will have its own visual language, its own pacing, and its own audience expectations. A Save-then-Publish flow, a verified-skill.com/queue page, or a Studio sidebar with PROJECT/PERSONAL/PLUGINS counts is content, not craft.

Use this layer as a reference for the underlying technique: the camera-zoom pattern, the cursor-targeting discipline, the content-tight highlight rectangle, the in-place state transitions, the voiceover/script.ts coupling, the render+audio-boost pipeline — those generalize. The exact constants (1.72× zoom, x=1488 button center, v1.0.0 → v1.0.1 version pill, "Tier-1 patterns · Tier-2 LLM · Socket" attribution) are Skill Studio specifics — translate, do not copy.

---

Layer 1 — Remotion fundamentals

Mirrors the upstream remotion-best-practices skill at https://github.com/remotion-dev/skills/blob/HEAD/skills/remotion/SKILL.md.

New project setup

When in an empty folder or workspace with no existing Remotion project, scaffold one using:

npx create-video@latest --yes --blank --no-tailwind my-video

Starting preview

Start the Remotion Studio to preview a video. Studio HMR live-reloads as files change — you do NOT need a separate preview_start mechanism, and Bash run_in_background is the right way to keep it alive across edits.

npx remotion studio --port=3030

Rendering

# Entry point must be the file that calls registerRoot() (usually src/remotion/index.ts)
npx remotion render src/remotion/index.ts <CompositionId> out/video.mp4 --concurrency=8 --log=info

Common gotchas:

• Passing Root.tsx as entry → error: "this file does not contain registerRoot". Use index.ts.
• TransitionSeries does prop introspection on direct children; do not wrap children in <React.Fragment>. Use flatMap returning a flat array of <TransitionSeries.Sequence> and <TransitionSeries.Transition> elements.
• interpolate(frame, [a, b], …) requires a < b strictly. If you derive b from constants, sanity-check at scene-budget design time — Remotion throws "inputRange must be strictly monotonically increasing" on the very first evaluated frame and the whole composition fails to load.

One-frame render check

npx remotion still <composition-id> --scale=0.25 --frame=30

Subjects covered by the upstream rule files

(Load on demand from the upstream skill repo — github.com/remotion-dev/skills/tree/HEAD/skills/remotion/rules/.)

• compositions.md — Defining compositions, stills, folders, default props, dynamic metadata
• animations.md — interpolate, spring, easing, frame-based math
• transitions.md — @remotion/transitions (fade, slide, wipe), how to chain them inside TransitionSeries
• assets.md — staticFile(), Img, Audio, Video, font loading
• fonts.md — @remotion/google-fonts and local font registration
• audio.md — Importing, trimming, volume, speed, pitch
• captions.md, subtitles.md — Caption tracks and sync
• ffmpeg.md — Trimming, concat, audio operations via FFmpeg shell-out
• silence-detection.md, extract-frames.md, get-audio-duration.md, get-video-duration.md — Mediabunny utilities
• charts.md, gifs.md, light-leaks.md, 3d.md — Specialized rendering recipes

---

Layer 2 — Demo-video craft rules

These are the rules earned over a long iteration cycle. Treat them as defaults, not optional polish — most of them came from "this looks weird, fix it" feedback that took multiple rounds to resolve.

A. Reference fidelity

A1. Always pull the real reference

If the user says "make it look like 2:43 of this YouTube video," extract the frame and study it. Don't approximate from memory.

SOURCE="/Users/antonabyzov/Movies/.../Source.mov"
DEST_DIR=".specweave/.../assets/keyframes"
for t in 102 105 108 110 112; do
  ffmpeg -y -ss "$t" -i "$SOURCE" -frames:v 1 -q:v 2 "$DEST_DIR/at-${t}s.jpg" -loglevel error
done

Then Read each JPG and design from what's actually on screen — typography, exact button labels, badge colors, sidebar tree layout, search-input positioning, count values (e.g. PROJECT (1), PERSONAL (0 of 12), PLUGINS (0 of 50), AVAILABLE (62)).

A2. Use real logos and icons, not approximations

• Bell-badge skill-studio-logo.png — copy into every Studio scene as <Img src={staticFile("...")} />. Don't render a ✷ glyph and call it a logo.
• Provider icons — fetch the real SVG/PNG for Claude, Anthropic, OpenAI, OpenRouter, Ollama, LM Studio (e.g., from lobehub/static-png). Don't substitute emoji.
• Mascots — draw with styled divs to match shape exactly. The Claude Code mascot is a peach-#e08160 body with two square eyes, two side hand-nubs at mid-body, and two pairs of legs underneath (▪ ▪ ▪ ▪). Not ASCII art.
• App-window chrome — when showing a website in a "Chrome browser", render a real Chrome browser frame: rounded corners, traffic-light dots, ‹ › ↻ nav, locked-padlock URL bar with a real URL (localhost:3000/hero, no extra spaces, no middle dot).

A3. Match YouTube reference layouts pixel-for-pixel

Before redesigning a scene from imagination, list the visible elements in the reference frame and check each one against your output:

• Banner text — exact wording (Submit skills for verification, not Submit a Skill)
• Tab order — Overview · Edit · Tests · Run · Trigger · Versions
• Trust badges — T1 UNSCANNED, Security-Scanned —, Trusted Publisher
• Filter input — always above AVAILABLE in the sidebar
• Counts — keep them consistent across slides (PERSONAL (0 of 12) everywhere, not (11) on one slide and (0 of 12) on another)
• Header right-side controls (in this order): 🔍 Find skills [⌘K] · + New Skill · ● Model selector · 🔔 bell

B. Camera zoom

B1. Camera zoom is full-canvas, not section-scaled

Do not scale a single panel inside the chrome. Wrap the entire chrome (top bar + body) in a transform div and scale + translate that:

<div
  style={{
    width: "100%",
    height: "100%",
    transform: `translate(${cameraTx}px, ${cameraTy}px) scale(${cameraScale})`,
    transformOrigin: "50% 50%",
    willChange: "transform",
  }}
>
  {/* TOP BAR + BODY */}
</div>

Cursor + click-ripple SVGs go inside this wrapper so they scale with the chrome and stay glued to their target.

B2. Click first, then zoom

The viewer needs to see the click target in context, then be transported in for the consequence. Ordering:

frame 130   cursor approaches button
frame 174   click ripple
frame 184   button shows "Running…"
frame 188   camera zoom-in starts (1.0 → 1.55+ over ~30 frames)
frame 220+  zoom held — pass cascade / results / scroll-up reveal happens here

Zooming first then clicking feels like a presentation slide. Clicking first then zooming feels like the user did the action and the camera followed.

B3. Pick a scale that actually pushes chrome off canvas

A modest 1.1× barely changes anything. For "the top bar leaves the canvas top," you need ≥ 1.5× combined with a translate that brings the focal point to canvas center. Compute target ≥ (canvasHalfHeight) / (distance from focal point to top bar) — for a row at y=540 and a 64-px top bar, that's ≥ ~1.5×. Use 1.55–1.85× as defaults for "fill the viewport."

C. Cursor click targets

C1. Hit the actual element

When the cursor lands on the wrong button (+ New Skill vs the model-selector pill), the viewer thinks the demo is broken. Re-derive the target from the layout each time — don't guess pixel values.

For a flex right-aligned controls strip with padding: "0 22px":

// Right edge → 22 pad → bell (32) → 14 → model (~290) → 14 → New Skill (~120) → 14 → Find skills (~150)
NEW_SKILL_PILL_X = 1920 - 22 - 32 - 14 - 290 - 14 - 60   // = 1488 (button center)
FIND_PILL_X      = 1920 - 22 - 32 - 14 - 290 - 14 - 120 - 14 - 75  // = 1339

Once you have the constant, use it from both the cursor approach interpolation and the cursor leave interpolation so the click ripple lands exactly on the pill, not 200 px to the right of it.

C2. Highlight the target as the cursor approaches

Add a *Active prop on shared header components (e.g., findActive, newSkillActive on StudioHeader) that the cursor scene flips on for the approach + click window. The button gets:

• 1.08× scale
• Soft indigo or purple ring via box-shadow: 0 0 0 4px rgba(99,102,241,0.30)
• transition: all 0.15s ease

D. Highlights and rectangles

D1. Highlight rectangles are content-width, not full-line

When the user wants a red rectangle around two terminal lines, do not wrap the parent flex column — that stretches across the row. Use:

<div
  style={{
    display: "inline-flex",
    flexDirection: "column",
    alignSelf: "flex-start",
    width: "fit-content",
    border: "2px solid #dc2626",
    borderRadius: 6,
    padding: "10px 16px",
    backgroundColor: "transparent",
  }}
>
  {/* the two lines, nothing more */}
</div>

Anything that should be outside the rectangle (e.g., the third "Generating component…" line) must be a sibling, not a child.

D2. Annotations: prefer rectangles over ellipses

A hand-drawn-style rectangle stroke around a row reads as "highlighter on the canvas," which is what most users mean by "highlight this." An ellipse can feel decorative.

<svg viewBox="0 0 1000 100" preserveAspectRatio="none">
  <rect
    x="6" y="6" width="988" height="88" rx="6" ry="6"
    fill="none"
    stroke="#ea580c"
    strokeWidth="3.6"
    strokeDasharray="2160"
    strokeDashoffset={2160 * (1 - progress)}
  />
</svg>

D3. Use orange (#ea580c) for "this is what's new" and red (#dc2626) for "this is the bug"

The same demo can carry both. Don't mix.

E. Layout patterns for product chrome

E1. Studio header is a single shared component

Use one StudioHeader.tsx with this canonical layout, called from every Studio scene:

• Left: logo image (40 × 40 PNG) + "Skill Studio" wordmark + breadcrumb [Authoring|Available] / [scope] / [folder] / [skill]
• Right: 🔍 Find skills [⌘K] · ✦ + New Skill · ● Model selector · 🔔 Bell

Pass breadcrumb, bellBadge, findActive, newSkillActive as props. Every scene's header is then pixel-stable.

E2. Sidebar has a constant filter input above AVAILABLE

Every Studio sidebar — Browse, Update, AuthorEvals, ConsumeInstall, AuthorEditAndPublish — gets the same Filter skills… input above the AVAILABLE tree. Pre-fill with the in-context query (frontend-design) on slides where the user has already searched.

E3. Sidebar widths and typography

• Width: 400 px (or 460 px on slides with deep nested trees)
• Outer padding: 24–30 px
• Group headers (AVAILABLE, AUTHORING): 18–19 pt, letter-spacing 1.6, weight 700
• Sub-headers (SKILLS, .CLAUDE): 15–16 pt, letter-spacing 1.4
• Row text: 17–19 pt
• Version pill: 13–14 pt mono with 1 px border, padded 3/10
• Vertical gaps: 12–14 px between sections, 22–36 px above section headers

Skinny dense sidebars feel like Settings panels. Wide-open sidebars feel like real product UI.

F. State transitions in-place

F1. Don't slide-left between scenes that should feel like one screen

If "click Install → tree updates with new skill" should read as one continuous interaction:

• Set transitionType: null on the next scene or merge the two scenes into one
• Keep the chrome identical between the scenes
• Animate the changing element (counter flip, chevron rotate, row slide-in) — don't full-fade

F2. Highlight new items strongly

A peach background + 2 px solid orange ring + drop-shadow + ✓ Just installed callout pill is the right intensity for "this just landed." A subtle background tint reads as default-state and the viewer doesn't notice.

backgroundColor: "#fff5ee",
boxShadow: `0 0 0 2px ${ORANGE}, 0 8px 22px rgba(234,88,12,0.22)`,

F3. Counter flips: pulse halo + chevron rotation

When a count changes (PROJECT (0) → (1)):

• Rotate the chevron ▸ → ▼ (200 ms transition)
• Render a brief orange halo behind the count: opacity 0.45 → 0, scale 0.4 → 2.2 over 18 frames
• Slide in the new children rows from translateY: -12 → 0 over 24 frames

G. Editor / SKILL.md edit patterns

G1. Replace, never remove, required fields

A skill must always have a description. To upgrade the description: strikethrough the primitive line in red, slide the new description in below in green. The skill is never description-less, even mid-animation.

G2. Keep version metadata out of editor content

version lives in two places only:

1. The sidebar pill on the skill row (with optional ↑ sync indicator)
2. The top-right pill in the main-pane skill-detail header

Do not render version: "..." inside the SKILL.md editor view — that's not where versions are stored, and showing it both there and in the pills creates "which one is real?" confusion.

G3. Save before Publish, with explanation

Always: Save first → version bumps locally → ↑ sync indicator appears in sidebar → user clicks Publish → ✓ replaces ↑.

After the Publish click, render an explanation toast (bottom-right) so the viewer knows what Publish actually does:

✓ Publishing — what this does:

1. git push → github.com/<owner>/<repo>
2. Opens verified-skill.com / Submit — same repo, re-runs the scan pipeline
3. v1.0.1 published — registry will index in ~30 s

Stagger the lines: line 2 fades in ~1 s after the click, line 3 ~2 s.

H. Terminal scenes

H1. Real prompt format

antonabyzov@Mac-1255 frontend-design % claude

No (base) conda prefix. Hostname is fine to keep. Use the user's actual workdir name — ~/Projects/TestLab/frontend-design — not a placeholder.

H2. Claude Code section cards

Real Claude Code groups tool-call output in subtle cards. Use the canonical style:

●  Skill(frontend-design)
       ⌐ Successfully loaded skill

Wrapped in a content-width rectangle (width: fit-content, align-self: flex-start) — do not stretch the rectangle to the full row width.

H3. Show the rendered output, not just the code

After Claude finishes typing the markup, fade in a Chrome browser overlay showing what that markup actually renders to. Use the existing site-good.png / site-excellent.png assets and a verdict ribbon: ● v1.0.0 output — good, but not excellent. The "what does AI-slop actually look like" payoff is the rendered page, not the code block.

H4. Larger window, larger type

Default terminal-window size: 1620–1720 px wide, 30 pt mono body text, 44 / 48 / 72 / 48 padding. Title bar: 17 pt. Traffic dots: 14 px. Cursor block: 14 × 32 px. Anything smaller and the viewer can't read prompts at video distance.

I. Voiceover discipline

I1. Regenerate voiceover whenever script.ts changes

The voiceover is generated from the joined voiceText fields of HACKATHON_SCRIPT. If you edit any voiceText, run the generator again before the next render:

ELEVENLABS_API_KEY=... node scripts/generate-hackathon-voiceover.mjs --voice sarah
ffmpeg -y -i public/hackathon-demo/voiceover-raw.mp3 \
  -af "loudnorm=I=-16:TP=-1.5:LRA=11" \
  -codec:a libmp3lame -b:a 192k \
  public/hackathon-demo/voiceover.mp3

Forgetting this step → the rendered MP4's narration doesn't match what's on screen.

I2. Voice: Sarah for ElevenLabs

Sarah (EXAVITQu4vr4xnSDxMaL) reads tech demos cleanly. Stable across long voiceovers. Lock it in:

const VOICES = {
  sarah: { id: "EXAVITQu4vr4xnSDxMaL", name: "Sarah" },
  // ...
};

I3. Audio levels — normalize to −16 LUFS, do NOT double-boost

The trap: it's tempting to apply loudnorm AND volume=+8dB to the voiceover.mp3, then ALSO apply volume=+8dB to the rendered MP4 "to be safe". That's ~16 dB of stacked boost on top of normalization — the result is harsh, peaks clip, and the user will tell you it's "too loud."

Correct pipeline (single normalization pass on the voiceover, no post-render boost):

# 1. Generate voiceover-raw.mp3 from ElevenLabs
# 2. Normalize ONLY (target -16 LUFS, the YouTube/podcast standard):
ffmpeg -y -i voiceover-raw.mp3 \
  -af "loudnorm=I=-16:TP=-1.5:LRA=11" \
  -ar 44100 -b:a 128k voiceover.mp3
# 3. Render with Remotion — voiceover plays at volume:1.0 in the composition,
#    bgm at volume:0.08. Mix sounds natural at -16 LUFS reference.
# 4. Do NOT post-process the rendered MP4 with volume=+8dB.
#    Just copy it to public/hackathon-demo/out/.

If you used to apply +8dB on the voiceover.mp3 AND +8dB on the rendered MP4, drop both. The single loudnorm pass is the correct level.

Target: voice mean ~−16 LUFS, max ~−1.5 dBTP. Music bed at 0.08 volume in Remotion. If the user says "too loud", you double-boosted — re-process voiceover.mp3 with loudnorm only and re-render (or just copy the un-boosted MP4).

I4. Voice end-sync with video — calculate from words, not vibes

The other voice trap: voice that overflows scenes (drift) or under-fills the video (silent tail). Both feel wrong.

The math for ElevenLabs Sarah on eleven_v3 with em-dash-heavy narration:

sarah_wpm ≈ 122           # measured from prior renders, em-dashes slow it
target_voice_seconds = video_seconds − 5  # 5s buffer at end for clean fade
target_words = target_voice_seconds × sarah_wpm / 60

For a 184.5s video: target voice ~179s = ~365 words. Distribute proportionally per scene:

scene_word_budget = scene_seconds × sarah_wpm / 60
                  = scene_seconds × 2.04

A 12s scene gets ~24 words, a 24s scene gets ~49 words. Stay UNDER budget per scene — voice that ends slightly early in a scene reads as breathing room; voice that overflows into the NEXT scene reads as broken.

After regenerating, ElevenLabs reports [done] duration=Xs. Compare against video duration:

• If voice > video: you over-wrote. Trim 10-15 words and regen.
• If voice < video − 8s: you under-wrote. Voice will end too early. Add 10-15 words to the closing scenes.
• If voice within [video − 8s, video − 2s]: you're in the sweet spot.

Per-scene drift detection: if the user says "voice is way behind by AuthorPublish" or any mid-video scene, your earlier scenes have too many words. Voice text per scene must each fit within its visual scene duration — no scene's text should take longer to speak than that scene plays.

J. Render workflow

J1. Background-render with a wait-loop

A full-length 1920×1080 demo at 30 fps takes 2–4 minutes. Don't busy-wait inside the agent:

nohup npx remotion render src/remotion/index.ts <Comp> out/video.mp4 \
  --concurrency=8 --log=info > /tmp/render.log 2>&1 &

Then a polling wait-loop in another Bash run_in_background: true:

until [ -f out/video.mp4 ] && ! pgrep -f "remotion render" > /dev/null; do sleep 5; done
echo "RENDER DONE"

Inside the wait-loop, immediately apply the audio boost so the next status report has the final levels.

J2. Always type-check after edits

npx tsc --noEmit --jsx preserve --target esnext --module esnext \
  --moduleResolution bundler --skipLibCheck --allowSyntheticDefaultImports \
  src/remotion/scenes/<edited-files>.tsx

A clean tsc run is cheaper than a 4-minute render that then crashes at frame 286 because of an inverted interpolate range.

K. Things that cost time when skipped

• Letting interpolate(frame, [a, b], …) end up with a > b from constant arithmetic
• Setting position: sticky on a flex-column child without width: 100% (it collapses to content width and the nav looks centered mid-canvas)
• Forgetting to Img import + use staticFile() for image assets — direct src="/..." paths break in production renders
• Using transform-origin: 50% 50% on a scaled element when 50% 0% would have been the right anchor for "grow toward viewer's eye"
• Editing script.ts without regenerating the voiceover
• Adding a new scene without updating HackathonDemo.tsx's SCENE_COMPONENTS map (renders crash at runtime: no component registered for scene id "X")
• Forgetting to swap ConsumeInstalled (or any mid-flow scene) transitionType to null when it's meant to feel continuous with the previous scene

---

L. Workflow discipline (render budget)

L1. Render only when the user asks for it (HARD RULE)

A full 1920×1080 30 fps demo costs 3–5 minutes of wall-clock + ~5,000 frames of compute + nontrivial tokens for status updates, frame extractions, and re-verification. Do NOT render after every edit. The user pays for every render.

The rule:

• Edit → type-check (npx tsc --noEmit) → batch more edits → STOP.
• Render only when the user explicitly says "render", "let's see it", "make a new video", or similar.
• During a long iteration, expect to make 5–15 edits between renders. This is normal.

Why this isn't optional: Studio HMR (npx remotion studio) live-reloads in the browser, so the user can preview specific frames or scenes at zero cost. The full-length render exists for delivery, not for verification of every micro-change.

The signals to watch for:

• ✅ "render it", "render the video", "let's see it", "ship it", "make a new MP4" → render now.
• ✅ A long batch of changes lands, tests pass, the user says "ok" or moves on → ask before rendering ("Render now?").
• ❌ "Add another rule to the skill" → do NOT render. Edit only.
• ❌ "Fix the cursor position" → do NOT render until they ask. Studio HMR shows the fix immediately in their browser.
• ❌ Any time the user explicitly says "don't render", "save tokens", "I'll ask when I'm ready" → respect it for the rest of the session.

Anti-pattern:

User: "Move the popup 20px to the left."
You: <edit + render full 167s video>

This burns minutes and tokens for a 1-pixel adjustment that the user could have verified in Studio in 1 second.

Correct pattern:

User: "Move the popup 20px to the left."
You: <edit + tsc + done — wait for next instruction>

L2. Batch edits between renders

When the user dictates several changes in a row, hold all of them in queue. Land them as edits, type-check, and render once at the end of the batch (and only if the user asks). A typical good cadence:

edit edit edit edit  →  tsc  →  user says "render"  →  render once  →  show results

L3. Voiceover regeneration is also a "render" — only when asked

Regenerating the ElevenLabs voiceover costs API credits and takes ~30s. Same rule applies: only when the user is ready for a new render or explicitly asks to refresh narration.

If the user makes a script.ts change that affects narration timing, note in the response "voiceover will need regeneration before next render" — but do not call ElevenLabs yet.

---

M. Demo arc — before/after with the same prompt

The strongest demo shape is same prompt, different output, mediated by a state change in your product. For Skill Studio that's:

Slide N    : terminal — prompt "design a hero" → skill v1.0.0 → AI-slop output
Slide N+1  : browser — site-good.png with verdict "v1.0.0 — good, but not excellent"
…author edits + publishes v1.0.1…
Slide M    : terminal — SAME prompt → skill v1.0.1 → editorial output
Slide M+1  : browser — site-excellent.png with verdict "v1.0.1 — design has taste"

Rules for the after-pair (M, M+1):

1. Pixel-mirror the chrome from the before-pair. Same MacOsMenuBar, same window size, same title-bar tabs, same browser frame dimensions, same URL pattern (localhost:3000/hero). The viewer should read "this is the same page from earlier" — only the content should differ.

2. Flip the highlight color. Where the before-pair had border: 2px solid #dc2626 (red, "this is the bug"), the after-pair uses border: 2px solid #16a34a (green, "this is the fix"). Keep the rectangle the same shape — content-tight, display: inline-flex, width: fit-content — so the geometry feels unchanged.

3. Highlight the new version chip. The new version (v1.0.1) gets a pulsing green pill next to the skill name. Use a slow sine-wave glow boxShadow: 0 0 ${20 * pulse}px rgba(22,163,74,${0.5 * pulse}) so it reads as "this is what changed" without being shouty.

4. Skip the typing animation for the prompt on the second take. The viewer recognizes the prompt; making them watch it type a second time is wasted seconds. Render it pre-typed in the highlight block.

5. Pair with a green verdict ribbon on the browser slide. Match the red ribbon from the before-state position (bottom-center, pill shape, same typography). Just flip it to green and update the copy: "v1.0.1 output — design has taste". The visual rhyme with the earlier ribbon is what makes the payoff land.

6. Editorial reply tokens get a green underline pulse, the inverse of the red AI-slop pulse. Pick 3-5 design-system tokens from the new code (font-serif, tracking-widest, bg-stone-50, font-light) and pulse them in green — same animation pattern as the bug-red pulse, opposite color, opposite meaning.

The whole arc reads in one beat: same prompt + new version → completely different product. That's the whole product, condensed.

---

N. Outro polish — feature pills should not look like a bullet list

A flat row of pills with single-glyph icons (❤ ⌂ ⛨) reads as "PowerPoint slide." Make them look like a product page:

1. Inline SVG icons, not unicode glyphs. Custom 44×44 line-art SVGs in a 84×84 round-square tile. Examples:

   • Open Source → git-branch (two circles connected by a curved path)
   • 100% Local → shield with a checkmark
   • Enterprise-Ready → three stacked diamonds (SSO + audit + scoped)

2. Each tile gets a colored gradient + glow halo that pulses. Slow sine wave, slightly out of phase per pill, so they don't bob in unison.

   const glowPhase = (frame / 75 + i * 0.4) * Math.PI * 2;
   const glowAmount = (Math.sin(glowPhase) + 1) / 2;
   boxShadow: `0 0 ${24 * glowAmount}px ${color}66, 0 0 ${48 * glowAmount}px ${color}33`;
   

3. Hairline accent stripe at the top edge of each card in the brand color, fading to transparent at both ends with linear-gradient(90deg, transparent 0%, ${color} 18%, ${color} 82%, transparent 100%). This makes the card feel "tagged" rather than generic.

4. Continuous gentle float on each card. A 3-pixel sine bob with phase offset:

   const floatY = Math.sin((frame / 90 + i * 0.5) * Math.PI * 2) * 3;
   

   This animation alone makes a static slide feel premium.

5. Soft outer halo ring behind the icon tile — radial-gradient(circle, ${color}22, transparent 70%) at inset: -8, opacity tied to the same glow pulse. Subtle but the eye reads it as "this is real."

6. Bigger, heavier label typography. fontSize: 26, fontWeight: 800, letterSpacing: -0.4 — the label should feel as confident as the wordmark above it.

The trap to avoid: animations that distract from the wordmark and tagline above. Keep the float amplitude ≤ 4px and the glow 0.3 → 1.0 (don't go to zero — it reads as flicker). The pills are a closing reassurance, not the focal point.

---

O. Reference verification — the screenshot wins over the timestamp

When the user says "make it like at 3:40 of the YouTube video" AND attaches a screenshot in the same message, the screenshot is the authoritative reference, not the YouTube timestamp.

In one session: the user said "use like it was displayed here — on 3:40 on YouTube" and pasted a screenshot of their actual Skill Studio detail page. The agent extracted YouTube at 3:40 and got a "Claude Managed Agents" slide from a totally unrelated talk — and faithfully copied THAT slide's labels and bullets into the demo. The user was furious: "Stop hallucinating. You see the image? Or grab the same image from the YouTube video on 3:40."

The rule:

1. If the user pasted/attached an image in the message, that's the reference. Read it carefully (Read tool on the temp file path).
2. If the user only gave a timestamp, extract that frame from the source video with ffmpeg -ss N -i ... -frames:v 1 -update 1 -y out.png.
3. If both — the image they pasted wins. The timestamp may be approximate / a different video / mis-remembered.
4. If you're unsure which is right, ASK — don't pick the wrong one and copy faithfully.

This single mistake cost ~15 minutes of round-tripping and one section that had to be completely rewritten. Always check the actual image before adopting "reference content".

---

P. Studio detail-page mirror — the 8-card stats grid pattern

Real product demos benefit from showing the actual product UI as the user sees it. For Skill Studio, that means the detail page of an installed skill — not a presentation slide. The pattern (verified against the user's screenshot of the live product):

Top section (above tabs):

.claude › ● PROJECT
frontend-design                                      v1.0.0
anton-abyzov  SKILL.md ↗
INSTALL METHOD  Copied (independent)
[ /Users/antonabyzov/.claude/skills/frontend-design  📋 Copy ]
🔒 This is an installed copy of the skill. Editing, …  Uninstall
Check now

Tab strip: Overview · Trigger · Versions (only three on this consumer view; the authoring view adds Tests · Run).

Overview content:

frontend-design  v1.0.0  COPIED
— frontend-design · Updated just now

Stats grid — 4 columns × 2 rows = 8 cards:

BENCHMARK	TESTS	ACTIVATIONS	LAST RUN
—	0	0	—
Never run	0 assertions	Never

MCP DEPS	SKILL DEPS	SIZE	LAST MODIFIED
0	0	1.9 KB	just now
None	None		2026-04-27T02:11:22.424Z

Each card: tracked-uppercase label (11pt, +1.4 letter-spacing) · mono value (26pt, 700 weight) · sub-line (12pt, muted). LAST MODIFIED uses mono for the timestamp sub-line. Card padding "16px 18px", radius 10, surface bg, 1px border, min-height 110.

This is "the product, not a slide" — the viewer sees a real Studio page they could navigate to themselves. Use this pattern any time the user shows you a screenshot of the live product they want mirrored.

---

Q. Cursor-meets-button geometry — re-derive, don't guess

Cursor click moments fail visually when the cursor floats near but doesn't TOUCH the button. The fix is geometry, not iteration:

1. Derive button position from layout, not from a render.

Layout math example (Generate Skill button in AuthorCreate, behind a 1.18× camera zoom anchored at bottom-center):

sidebar_width = 320
main_pane_padding_left = 36
button_left_unzoomed   = 320 + 36 = 356
button_width           = 244       # padding(22) + ✨(20) + gap(8) + text + padding(22)
button_center_unzoomed_x = 356 + 122 = 478

# Camera transform: scale(1.18) transformOrigin: 50% 100%
button_center_x_zoomed = 960 + (478 − 960) × 1.18 = 391
button_center_y_zoomed = 1080 + (button_y_unzoomed − 1080) × 1.18

2. Account for the cursor SVG tip offset.

The standard arrow-cursor SVG has its visible tip at offset (3, 2) within its 26×32 bounding box. To land the tip ON the button center, the SVG top-left must be at (button_cx − 3, button_cy − 2).

3. Rule of thumb for camera-zoomed scenes: put the cursor OUTSIDE the camera-zoom wrapper (so its coordinates are canvas-space), and apply the inverse-of-zoom math above to find the canvas-space landing target.

4. Verify with one frame extraction, not a full render. Once you've placed the cursor:

ffmpeg -ss <click_seconds> -i video.mp4 -frames:v 1 -update 1 -y check.png

Read the PNG. If cursor isn't ON the button, fix the math BEFORE re-rendering the whole video.

---

R. Connection-line aesthetics — bold, not subtle

Lines that represent "X is connected to Y" (install arrows, sync indicators, anything edge-like) should be bold and energized when active, not 1-2 pixels of 50% alpha. Subtle reads as "this might be a hairline gridline" — exactly the wrong message.

Active / connected (green):

• Height: 4px (not 2px)
• Color: rgba(34, 197, 94, 0.95) (not 0.55)
• borderRadius: 2
• Glow: double-stack boxShadow: 0 0 10px rgba(34, 197, 94, 0.65), 0 0 20px rgba(34, 197, 94, 0.35)

Broken / disconnected (red, dashed):

• Same height
• Repeating linear-gradient for dash effect: repeating-linear-gradient(90deg, rgba(239,68,68,0.6) 0 8px, transparent 8px 16px)
• Glow that grows with the break-progress: 0 0 8px rgba(239, 68, 68, 0.6)

The contrast between bold-green-active and dashed-red-broken is the visual story. If the active line is too thin, the break doesn't read as dramatic — it reads as "the line just got slightly redder."

---

S. YouTube publication kit — what to add when shipping a hackathon demo

When the demo is rendered, the next step is publishing. Before uploading, prepare:

S1. Chapter timestamps from script.ts

Compute chapters by walking HACKATHON_SCRIPT and accumulating effective frames (raw frames minus HACKATHON_TRANSITION_FRAMES per non-null transition):

let runningEffective = 0;
for (const scene of HACKATHON_SCRIPT) {
  const startSec = runningEffective / HACKATHON_FPS;
  // emit "M:SS  <chapter title from scene.caption or visualNotes>"
  runningEffective += scene.durationFrames;
  if (scene.transitionType !== null && !isLast) {
    runningEffective -= HACKATHON_TRANSITION_FRAMES;
  }
}

YouTube chapter rules:

• First chapter MUST be 0:00
• Minimum 3 chapters
• Each chapter ≥ 10 seconds — merge or drop short scenes (e.g., a 4s BrandReveal merges into the previous Hook chapter; an 8s Outro can be dropped from the chapter list since the description still ends with the CTA)
• Title format: action-oriented, present tense, ≤40 chars ("Edit, save, publish v1.0.1" beats "AuthorEditAndPublish scene")

S2. Description structure (1500–2500 chars)

[Hook line 1 — punchy problem statement, ≤80 chars]
[Hook line 2 — the fix, ≤80 chars]

[3-4 lines: what this is, why it matters]

Try it now:
$ npx vskill@latest studio
Web: https://verified-skill.com

🔗 Links
GitHub:        https://github.com/<owner>/<repo>
Registry:      https://verified-skill.com
…

⏱️ Chapters
0:00 …
0:21 …
…

🛠️ Built with
Anthropic Skills API · Claude Opus 4.7 · Remotion 4.0 · ElevenLabs · Next.js · Cloudflare Workers · Prisma

About the author
[1-line author bio]

#ClaudeCode #AnthropicSkills #DevTools #OpenSource #BuiltWithClaude

The first two lines must fit in YouTube's above-fold preview (~150 chars).

S3. Title, tags, hashtags

• Title ≤60 chars, dev-direct (not clickbait): I built a Claude Code Skills manager with Opus 4.7 works; 🤯 You won't BELIEVE what I made… doesn't.
• Tags (15-20): primary keyword first ("claude code"), then variants, then long-tail.
• Hashtags (3-5 above title): #ClaudeCode #Opus47 #BuiltWithClaude #AITools #OpenSource. Verify any hackathon-mandated hashtag from the official submission portal — don't invent.

S4. Thumbnail

• 1920×1080
• Left third: face (mid-expression, not exaggerated). Dev-tool demos with builder face still outperform faceless thumbnails in 2026.
• Right two-thirds: hero UI screenshot
• Primary text overlay ≤4 words, top-right, white with black stroke
• Brand color accent (e.g., Anthropic-adjacent #D97757) on a small badge
• Keep face + text out of the bottom 15% (player overlays cover that)

S5. Hackathon submission verification

Before submitting:

• Confirm the deadline UTC inside the official participant portal — don't trust third-party recaps
• Confirm any mandated hashtag (and use it verbatim in social posts)
• Verify judge handles before tagging — don't fabricate

If the hackathon page is gated to authenticated viewers, say so honestly in the publish kit and ask the user to copy details from their dashboard.

---

Appendix — File-shape cheat sheet for a hackathon demo

src/remotion/
  index.ts                   ← entry point (calls registerRoot)
  Root.tsx                   ← <Composition id="..." component={...} />
  HackathonDemo.tsx          ← top-level: TransitionSeries + Audio (bgm + voiceover)
  scenes/hackathon/
    script.ts                ← single source of truth: id, durationFrames,
                               transitionType, voiceText, caption, visualNotes
    StudioHeader.tsx         ← shared canonical Studio chrome
    Hook.tsx, Brand.tsx,
    Browse.tsx, AuthorCreate.tsx, AuthorEvals.tsx, AuthorPublish.tsx,
    ConsumeInstall.tsx, ConsumeBugSurface.tsx,
    AuthorEditAndPublish.tsx,
    Update.tsx (= UpdateButton scene with bell-popup prelude),
    ConsumeReuseUpdated.tsx, ConsumeBrowserExcellent.tsx, Outro.tsx
    uiTokens.ts              ← STUDIO_LIGHT, VERIFIED_DARK, TERMINAL_UI, FONTS
public/hackathon-demo/
  skill-studio-logo.png      ← bell-badge logo, used by every Studio scene
  bgm.mp3                    ← background music
  voiceover.mp3              ← normalized + boosted, generated from script.ts
  voiceover-raw.mp3          ← raw output from ElevenLabs (kept for re-normalization)
  site-good.png, site-excellent.png  ← rendered-page screenshots for browser overlays
  provider-icons/*.png       ← real Claude/Anthropic/OpenAI/etc. icons
scripts/
  generate-hackathon-voiceover.mjs   ← reads script.ts voiceTexts, joins them,
                                       calls ElevenLabs, writes voiceover-raw.mp3
out/
  hackathon-demo.mp4         ← final, audio-boosted MP4

The script.ts entry shape:

{
  id: "AuthorEditAndPublish",
  durationFrames: 450,        // 15 s @ 30 fps
  transitionType: "fade",     // "fade" | "slide-left" | "slide-right" | null
  voiceText:
    "The author opens the Edit tab on frontend-design, strikes the primitive description, and pastes real design rules…",
  caption: "Edit · Save (local) · Publish (registry)",
  visualNotes:
    "Mirrors at-243s. Studio chrome with breadcrumb Authoring/skills/frontend-design...",
}

Keep voiceText and visualNotes honest — they regenerate the audio and document the design intent. Future iterations rely on them.

---

Final reminder

The thing that turns a Remotion composition from "looks like a slideshow" into "looks like the product" is fidelity to references and consistency across scenes. Don't approximate. Pull the keyframe, study it, match it. Reuse the same StudioHeader, the same sidebar widths, the same counts, the same logo, the same red-for-bug / orange-for-new color discipline. When you do that, the viewer's brain stops noticing the video as a video and starts watching the product.