cyxj-remotion-overlay

cyxj-remotion-overlay

This is this workspace's Remotion private rule layer. First implement correctly according to the official Remotion skill and the engineering red lines, then apply your own visual and voiceover design system.

Required reading order

1. Official Remotion skill (remotion-best-practices)。
2. docs/HARD_RULES.md(engineering red lines: frame-driven / interpolate with clamp / deterministic rendering / assets into public/…single source of truth)
3. Your own design system (color semantics / composition / face no-go zones / annotations) — this repo provides a kit/theme.ts placeholder palette; replace it with your own.

The author's complete design spec (two theme sets / composition standards / motion feel / audio-visual rhythm / acceptance checklist) is private accumulation,not included in this repo; accumulate your own versions through the same mechanism.

Starting posture: build the image for this moment, don't dig through the library first

Before making any segment of visuals,the default action is "build the visuals this moment needs with official native Remotion", not "first see what's in the library that can be used." The shot library isa fallback + brand building-block supply, not a catalog you have to dig through to start.

But this doesn't mean you hand-craft standard repeated content too — for voiceover beds, standard content cards, data cards, the kind the library does well, reuse quickly when reuse applies. "Native first" targets:there are creative choices / the user explicitly asked for something new / the library has nothing that fits exactly— those moments.

Reuse isan active choice after judgment, not a reflex at the start of work:

• ✅ Reasonable reuse — this momenttruly is standard repeated content(voiceover bed, standard content card…), and the library shotis exactly what does this action, and its quality meets the bar. You can say "why it's this one."
• ❌ Procrustean fitting — for the sake of "the library has something close enough," changing the visuals you originally wantedinto the shape of that shot. This isn't reuse, it's using reuse as an excuse to be lazy and making the creativity disappear.

Iron rule: when the user says they want "a new shot / new effect / a different approach," the default isactually build it. You're not allowed to dig through the library first and talk the user back with "the library has something similar." To reuse, first state clearly that ittruly is repeated content + the library one fits exactly— if you can't state it clearly, it should be built.

How to decide how a segment of visuals is made

Short-circuit first, then decide — don't go through the whole process right away:

• ▸ clearly standard repeated content, the library has a shot that fits exactly, and this moment the user hasn't asked to change to something new → reuse directly, skip the 5 steps below.
• ▸ Everything else(the user asked for something new / the library has nothing that fits exactly / you're trying to "bend" it into some ready-made shot) → go through the full 5 steps below, native first.

5 steps (for the semantic unit / beat you need to decide):

1. Intent — what should the audience get from this line (information / emotion / reversal / emphasis). Do semantic association by timecode + verbatim transcript.
2. Visual action — what does this intent pair withVisual verb(approach / skyrocket / converge / strike through / slam down / pan…).Define the action first, don't start by thinking "which shot to use".
3. Benchmarks & references — how similar intents were done in finished pieces, where the quality bar is; align to it and don't fall below it.When you hit "new card / want a premium feel / brand-new visual direction", don't just do it based on taste: first search online for how official / professional designs handle it (color × background blending, effects, layout) before starting. Tuning by feel over and over = getting overturned repeatedly.
4. How to build it —— Default: official native (interpolate / spring / Sequence) + kit/theme.ts tokens, directly build out that action from step 2. Only if the library happens to have one that does exactly this action and meets the bar → use it. Whether the official way can do it, which API to use — follow the official skill / remotion-documentation MCP, don't rely on memory.
5. Supplement & distill — not satisfied / missing brand pieces → pull the library'sbuilding blocksto supplement (glass card GlassCards / subtitles SrtCaptions / talking-head track SpeakerTrack / camera poses poses). If what you make is genuinely useful and will repeat across videos → go throughcomponent promotion(see kit/CLAUDE.md the component promotion section) and distill it back into the kit.

Follow the framework red lines (frame-driven, interpolate with clamp, deterministic rendering, assets in public/… see docs/HARD_RULES.md)——Native hand-written code is more error-prone, so watch it even more closely。

Assets and templates

kit/           # 共享层:引擎级组件 + 5 个基础镜头 + 占位色板
template/      # 起手模板(复制它开新片)

Key discipline

• Don't run the CLI in the repo root (no package.json); always first cd template/ or the project you copied out.
• Don't hand-modify the official Remotion skill.
• Reusing the shot library's "building blocks" (glass card / subtitles / camera poses…) is correct, don't misread it as "rewriting even the building blocks"; build new natively when you should, reuse blocks when you should, following "how to decide how to do a shot" above.