---
name: remotion-template-composition
description: How to compose the editable elements of a FlatRender template — text, logo, image/media, and supporting copy — into a clear, well-paced presentation. Use when laying out what goes where, deciding the visual hierarchy, wiring editable fields, or timing the reveal sequence of a template.
---

# Composing a template (text / logo / image / copy)

A template is not just a nice animation — it's a *fill-in-the-blanks* product. Users edit a few fields and it must look great with THEIR text/logo. Design for editability + clarity.

## The binding model (how editable fields work)
Editable elements live in the DB and bind to Remotion props by KEY (see `../remotion-svg-colors/SKILL.md` for the full pipeline):
- **Text** → `content.scene_content_elements` of type `Text`; the element `key` MUST equal the composition's Zod schema field (e.g. `headline`, `tagline`). Studio shows a text input.
- **Logo / image / media** → a `scene_content_elements` of type `Media`; key = a `z.string()` prop (e.g. `logoUrl`). Studio shows upload/replace. In the composition: `logoUrl ? <Img src={logoUrl}> : <DefaultMark/>`. See `GlitterReveal.tsx`.
- **Colors** → `shared_colors` / `scene_color_elements`, key = a `colorSchema` prop.
- Seed all of these via `scripts/seed_remotion_templates.py` (it has a `MEDIA` dict for image fields).

**Rule:** every visible piece of copy or media a user would want to change MUST be a prop + a seeded element. Don't hardcode the brand name, date, price, etc.

## Visual hierarchy (most templates need 2-4 tiers)
1. **Primary** — the logo OR the headline/hero. Biggest, highest contrast, center of attention.
2. **Secondary** — tagline / subtitle. ~35-45% of primary size.
3. **Tertiary** — CTA, date, price badge, handle. Small but distinct (pill, badge, accent color).
4. **Ambient** — decorative scene (particles, 3D, characters) — supports, never competes.

Size ratios that read well: primary `vmin(80-110)`, secondary `vmin(26-40)`, tertiary `vmin(24-32)`. Weight: primary 800-900, secondary 500-700, tertiary 600-900.

## Text legibility (critical over busy/3D backgrounds)
- Add a scrim or shadow: `textShadow: 0 0 vmin(20) rgba(0,0,0,.7)`, or a semi-transparent panel behind text.
- Persian is RTL: set `direction: "rtl"`, use `FONT` (Vazirmatn) from `lib/fonts.ts`. See `../persian-fonts/SKILL.md`.
- Keep line length comfortable (`maxWidth ~ 86%`); never let text touch frame edges (see `../remotion-aspect-ratios/SKILL.md`).
- For gradient text use `backgroundClip: text` + a `drop-shadow` for separation.

## Logo placement
- Center-stage for logo reveals; corner/lockup for promos.
- Always provide a branded DEFAULT (the FlatRender mark) so the template looks finished before the user uploads.
- Constrain with `maxWidth/maxHeight` + `objectFit: contain` so any uploaded logo fits without distortion.

## Image / media
- `objectFit: cover` for fullscreen backdrops (with a gradient scrim for text), `contain` for product/logo.
- Add motion: slow Ken-Burns (`scale 1→1.08` + slight pan) so stills feel alive.
- Mask into shapes (rounded rect, circle) for polish.

## Timing & pacing (the reveal sequence)
Stagger — never reveal everything at frame 0. A typical 6s (180f @30) beat sheet:
- 0-30: scene/background establishes, ambient starts.
- 20-55: hero/logo springs in (`spring()`), optional flash/impact.
- 55-90: headline rises/fades in.
- 90-120: tagline fades, letter-spacing settles.
- 120-160: CTA/date pops (`spring`, glow pulse).
- last ~30f: hold everything still for readability.
Give each text element ~0.6-0.8s on screen minimum before the next competes.

## Editability checklist
- [ ] Every changeable text/logo/image/color is a prop + seeded element (key == schema field).
- [ ] Branded default for logo + sensible default copy.
- [ ] Clear 2-4 tier hierarchy; text legible over the background.
- [ ] Staggered, eased reveal with a final hold.
- [ ] Looks good with long Persian text and a tall logo (test it).

Related: `../remotion-svg-colors/SKILL.md`, `../remotion-aspect-ratios/SKILL.md`, `../persian-fonts/SKILL.md`, `../remotion-design-styles/SKILL.md`.