flatrender/.claude/skills/flat-artist/remotion-template-composition/SKILL.md

name, description

name	description
remotion-template-composition	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.