Text To Lottie

Text To Lottie

Author production-ready Lottie JSON for the official local Skia Skottie player. The deliverable is a renderable scene in the player, not isolated JSON.

Operating Model

• Use the official player project and verify in Skia Skottie. Do not hand-roll a

custom viewer or switch renderers for verification.

• Keep the skill portable across Agent Skills clients. Avoid host-specific

commands, command modes, or orchestration conventions in skill instructions.

• Prefer fewer questions and stronger defaults. Ask only when a decision changes

the output materially, such as transparent vs full-frame background, brand constraints, target format, or supplied source assets.

• Prioritize clean, intentional, professional motion over merely satisfying the

literal prompt.

Reference Loading

This SKILL.md is the thin control plane. Load only one-level references that match the task. Do not open the whole reference library.

Always read references/player-contract.md before creating, editing, fixing, or verifying a scene. If a routed reference is unavailable, continue using the inline rules in this file.

For mixed prompts, choose one primary recipe from the main deliverable, then add secondary references for source format or visual treatment. Examples: SVG logo with glow uses logo as primary plus SVG compatibility and visual effects; product launch with pan/zoom uses product promo plus camera scene motion; technical SVG diagram tracing uses diagram/technical plus SVG compatibility; kinetic title with glass sweep uses typography plus visual effects.

Workflow

1. Route the task using the table above. Read only the relevant references that exist. 2. Locate the official player project and resolve the target scene using the target precedence below. Before editing, verify the resolved path is public/projects/<project>/<scene-N>/lottie.json; re-read that current file immediately before overwriting because the UI can write slot edits back to source. 3. Decide the background policy before authoring. 4. Write or update public/projects/<project>/<scene-N>/lottie.json and, when useful, controls.json. 5. Validate JSON, run or reuse the dev server, inspect exact frames with ?frame=N, and fix render/design/motion issues before finishing.

Inline Rules

Design Defaults (always apply)

These few defaults are non-negotiable and apply to every designed scene. Load references/design-taste.md for the full reasoning, especially for any "premium", "clean", "minimal", "modern", or "card" prompt.

• Premium means subtract, not add. When a prompt says premium, clean, minimal,

modern, sleek, or sophisticated, default to restraint: remove chrome before adding it. Premium is carried by scale, weight, brightness, spacing, and timing, never by cards, borders, dividers, shadows, glow, or stacked tints.

• Chrome/container budget is 0 by default. Do not add a framing card,

container, border, or divider unless it does a job that whitespace and alignment cannot. Separate grids and columns with negative space and alignment first, a single hairline second, and a filled or bordered card last and only when explicitly warranted.

• One surface tone. Use one background tone. Do not stack two near-black or two

near-white tints to fake a "surface"; it reads muddy. If a card surface must differ from the background, make it one deliberate step with a clear purpose.

• One divider treatment, one color. If dividers are truly needed, use one weight

and one color for all of them, title rule and column rules included. Never use slightly different colors or weights per divider.

Scene Rules

• Scene files live at public/projects/<project>/<scene-N>/lottie.json.
• Resolve target scenes by authority: an explicit file path wins; a browser URL

route like /<project>/<scene> wins next; an already-known project/scene for the task wins next; otherwise create a new safe scene. Use /__context only for discovery, verification, or playback state unless the task explicitly says to edit what is currently on screen and no more specific target exists. Do not let /__context.live override a known file path, URL, or project/scene. Overwrite main-project/scene-1 only if it is still the untouched placeholder; otherwise create a new scene.

• Full-frame standalone compositions should include a visible background layer

with a bgColor slot and controls.json entry.

• Transparent-by-default outputs include logos, icons, loaders, overlays, lower

thirds, and SVG-derived assets unless the user asks for a background.

• Include top-level v, fr, ip, op, w, h, nm, assets, and

layers. Treat op as exclusive.

• Use purposeful easing and staging. Avoid defaulting to linear motion. Derive

easing from the behavior-based anchors in motion-taste.md (chosen by motion behavior, focal element strongest); do not fall back to one uniform ease for every layer.

• Use slots for important editable values and add controls.json labels/ranges

when they improve the properties panel.

• For SVG input, preserve the viewBox, normalize styling, watch fill rules and

intersections, and verify the result in Skottie.

• Native Lottie text/text slots are unreliable in this player unless font blobs

are supplied to Skottie. The current scene loader discovers image assets only, so author fixed prompt text as vector/shape text immediately. Use native text slots only when editable text is explicitly required and font loading has been implemented and verified.

Verification

Before finishing:

1. Confirm the intended target file path is public/projects/<project>/<scene-N>/lottie.json. 2. Validate JSON:

   node -e "JSON.parse(require('fs').readFileSync('public/projects/<project>/<scene-N>/lottie.json','utf8'))"

3. Confirm the official player is running and the scene appears in GET /__context. 4. Inspect pinned frames in the browser. For new scenes, check frame 0, midpoint, and op - 1. 5. Confirm the background policy matches the use case. 6. Check for blank canvas, missing assets, unstyled shapes, wrong layer order, bad easing, awkward timing, cropped content, text overflow, and visible SVG artifacts. 7. Finish only when the animation renders cleanly and feels intentional.

Maintenance Evals

Do not read eval files during normal animation work. Use them only when testing or changing this skill:

• evals/trigger-prompts.json
• evals/routing-prompts.json
• evals/reference-loading-prompts.json
• evals/output-rubric.md

Output Rubric

Use this rubric when maintaining or evaluating the skill. Do not load it during normal animation work.

Activation And Routing

• The skill triggers for Lottie/Bodymovin, Skottie, logo animation, SVG

animation, typography, lower thirds, loaders, icons, state feedback, UI microinteractions, diagrams, product promos, scene/camera motion, visual effects, and scene-debug prompts.

• The skill does not trigger for unrelated design critique, SVG optimization

without animation, After Effects advice, video/GIF-only work, or abstract motion theory.

• The agent reads player-contract.md for scene work.
• Mixed prompts choose one primary recipe by deliverable and only add relevant

secondary references for source format or treatment.

• The agent avoids opening the whole reference library.

Scene Correctness

• The scene is written to public/projects/<project>/<scene-N>/lottie.json.
• Existing user scenes are not overwritten accidentally.
• JSON parses successfully.
• The official Skottie player renders the scene.
• Assets are colocated with the scene and referenced by bare filename.

Controls And Background

• Full-frame scenes have a bgColor slot and matching controls.json entry.
• Logos, icons, loaders, overlays, lower thirds, and SVG-derived assets default

to transparent output unless the user asks for a background.

• Slots are type-compatible with their referenced properties.
• Controls expose useful edits without cluttering the panel.
• Fixed prompt text is authored as vector/shape artwork without first spending

time on native text-slot experiments.

• Native text slots are reserved for explicitly editable copy after font asset

loading has been implemented and verified in the local player.

Motion And Design Quality

• Frame 0, midpoint, and op - 1 are visually intentional.
• First, midpoint, and final frames are the minimum still-frame check, not the

full motion review.

• Motion work also inspects playback and pinned key beat frames: early reveal,

midpoint, settle or near-final, final frame, loop seam if looping, and semantic beats where text, data, logo, chart, CTA, or camera motion resolves.

• Final frame works as a still composition or poster frame.
• Design quality is a completion blocker. A scene that parses and renders still

fails if hierarchy, spacing, color restraint, object necessity, or final-frame composition is weak.

• Complex diagram and product scenes include a concept pass before authoring:

visual system, focal point, node/detail strategy, hierarchy, final-frame goal, and decoration purpose.

• Designed scenes use an object budget: one focal subject, one support layer,

and one accent system unless the concept clearly needs more.

• The agent chooses an appropriate taste mode instead of treating "premium" as

one style: restrained product, institutional data, bold social, expressive primitive, playful character, or ambient field.

• Motion uses purposeful easing, readable staging, and clear choreography.
• Motion reinforces the same hierarchy as the final frame.
• UI and state feedback feel responsive rather than slow or theatrical.
• Product and promo scenes keep the product/message as the hero.
• Effects support the primary message and do not become noise.
• Typography is legible and not clipped.
• Kinetic typography uses type-driven, semantic choreography rather than a

uniform entrance applied to every word.

• Kinetic typography assigns anchor, support, and active text roles so the

active word or phrase carries the main motion.

• Simpler title cards, quote reveals, and editorial text reveals remain valid

when the prompt asks for restrained text animation.

• SVG-derived shapes preserve viewBox, fills, holes, masks, and intersections.
• Settled SVG-derived Lottie frames are compared against the source artwork.
• Final output feels production-ready rather than placeholder-like.

Design Judgment Blockers

• Fail outputs that render correctly but have no clear focal subject.
• Fail outputs that rely on first/last-frame inspection when the animation has

meaningful motion, stagger, camera movement, looping, or semantic beat changes.

• Fail crowded compositions, even when individual details appear meaningful.
• Fail scenes where support elements compete with the main message.
• Fail weak final frames that feel like accidental stopping points.
• Fail typography with accidental line breaks, unstable placement, weak

hierarchy, or crowded spacing.

• Fail mixed-size text rows aligned on a shared baseline instead of cap-center,

single runs not optically centered in their container, or stacked title/subline blocks with tight or arbitrary vertical spacing.

• Fail color/effect overload where accents compete or "premium" means more

glow, glass, gradient, or noise.

• Fail product/content scenes where believability comes from density rather

than coherent state, workflow, copy, and hierarchy.

• Fail decorative color that does not teach category, state, comparison, brand,

or hierarchy.

• Fail scenes where hierarchy depends on cards, shadows, glow, or chrome before

scale, weight, brightness, spacing, and timing have been resolved.

• Fail an unnecessary outer framing card or border around a stat group or column

set when whitespace and alignment would carry it.

• Fail dividers that use more than one color or weight (for example a title rule

that does not match the column rules).

• Fail two stacked near-black or near-white tints that read as a muddy surface

instead of one clean background tone.

• Fail "premium", "clean", or "minimal" prompts answered by adding chrome (a

card, border, divider, or second surface tint) instead of by subtracting.

• If design QA fails, the agent should simplify and revise before calling the

task complete.

Data And Chart Quality

• Data/stat scenes choose a clear archetype: hero figure, KPI grid, stat-card

triad, comparison chart, progress card, dashboard metric, social proof, or heat map.

• Headline states the insight, not only the topic.
• Values are direct-labeled; viewers should not need axis or legend decoding in

a short Lottie.

• Figures count up with baked keyframes, tabular numerals, and labels/units

arriving after the number resolves.

• Row label and value are cap-center aligned and optically centered in the pill,

card, or row; row and block spacing follow a consistent vertical rhythm.

• Chart geometry reveals by chart logic: bars grow, lines draw, segments widen,

dots populate, rings nest or emanate, and labels sync to geometry.

• Serious data uses calm ease-out and no bounce.
• Chartjunk, decorative 3D, rainbow series, and incoherent dashboard density are

blockers unless the prompt explicitly asks for them.

• Stat triads default to borderless figures or even self-contained cards

separated by whitespace: no outer framing card, one surface tone, and at most a single hairline of one color between equal columns.

Motion And Loop Quality

• Repeated elements use reading-order stagger or phase offsets unless lockstep

is intentional.

• Reveals follow build, settle, hold, with support arriving after the hero.
• Beat order, stagger origin, timing, easing, settle/hold, camera/framing, and

readability are reviewed by scrubbing playback, not only by checking static endpoints.

• Loops have engineered seams: matched endpoints, integer cycles, wrapped drift,

closed rotation, or recycled emanation.

• Loop seams are inspected when applicable; semantic beat frames are inspected

when numbers resolve, words land, logo lockups form, charts complete, CTAs appear, or camera moves settle.

• Ambient/generative motion has one conceptual beat and remains subordinate

unless the field itself is the deliverable.

• Motion reveals value and meaning; it does not animate chrome to compensate for

weak composition.

Render And Construction Risk

• No live expressions are assumed in Skottie; counters, particles, orbits,

physics, noise, and expression-like systems are baked.

• Path morphs use compatible vertex structures or a safer mask/replacement

strategy.

• Blur, bloom, glass, chrome, dither, true 3D, displacement, and frame-by-frame

smears are approximated with vector-safe layers, simplified, or baked as assets.

• Dense fields are capped or rasterized when needed for performance.
• Brand-specific marks, protected palettes, UI chrome, logos, headshots, and

compliance badges are supplied, placeholdered, or omitted; they are not restyled or copied from references.

Anti-Generic Quality

• Fail diagrams that default to dark grid, blue arrows, empty rounded cards,

monospaced labels, or decorative circles unless the prompt explicitly asks for that style.

• Fail product scenes where the product signal is missing, too small, blank, or

replaceable with any generic app.

• Fail effects that exist only as decoration and do not reveal, emphasize,

transition, show state, or communicate material.

• Pass "clean", "technical", "premium", "modern", and "polished" prompts only

when those terms produce concrete design decisions, not stock visual tropes.

• Prefer content-rich nodes, balanced topology, strong type hierarchy, optical

alignment, and intentional negative space.

• Prefer fewer stronger objects over many meaningful-looking details.
• Prefer color quarantine, semantic accents, warm neutrals, hairlines, tonal

depth, and whitespace before adding decorative effects.

Prompt Robustness Cases

• "Create a clean technical architecture diagram animation for a checkout flow."
• "Make a premium product explainer showing three steps and a final CTA."
• "Animate a technical SVG diagram with callouts, but keep it polished and

presentation-ready."

• "Create a clean data pipeline Lottie without making it look like a dark cyber

grid."

• "Create kinetic typography for 'fall fast, rise stronger'."
• "Make the word SNAP hit sharply, then settle."
• "Create a premium product feature animation without decorative filler."
• "Make a clean technical workflow explainer with only meaningful visual

detail."

• "Create a polished title scene with strong hierarchy and restrained color."
• "Create a text-heavy pricing comparison card with fixed Inter typography and

exact Skottie rendering."

• "Animate a product UI flow that feels believable, not crowded."
• "Animate these three KPIs into a premium stat card."
• "Create a premium KPI stat card with three metrics and restrained motion."

(Regression: a terse "premium" prompt must subtract chrome, not add a framing card, mismatched dividers, or stacked muddy tints.)

• "Create a pitch-slide chart showing revenue growing 11% month over month."
• "Make a generative loader from one repeated dot primitive."
• "Create a clean ambient background behind a headline, no generic particles."

Chapterization And Transition Grammar

Use this when a prompt is dense or naturally multi-part. It decides whether to split into chapters, what each chapter does, and how to move between them. Easing anchors (see motion-taste.md → "Easing Anchors") are supporting tools here, not the transition itself.

When To Chapter

Split into chapters when the prompt carries more than one idea: long text, multiple claims, feature list, multiple stats, timeline, before/after, problem/solution, quote+proof, setup/payoff, product walkthrough, recap/social story, or multi-language / repeating content variations. One readable idea per chapter.

When Not To Chapter

Keep one beat for a single logo lockup, one CTA, one icon animation, one simple stat card, one UI microinteraction, a legal/read-critical block, or a calm hero moment whose final settle is the payoff. Let it land and settle.

Chapter Roles

Give each chapter one readable job: hook, setup, claim, proof, contrast, detail, payoff, CTA / final lockup, or loop bridge.

Split By Meaning, Not Length

Rewrite long text into short authored beats or reveal it progressively. Never place a paragraph at once, and do not just chop it into smaller paragraph blocks. Each chapter carries one idea.

Structure Modes

• Repeated armature: same layout and motion path, content changes. Best for

lists, stats, languages, recaps, supercuts.

• Evolving story layout: objects/text carry into new positions and the

composition changes across chapters. Best for product walkthroughs, explainers, process, setup/payoff, and narrative motion.

Readable Window

Each chapter's main message gets a coast, hold, or stable moment before the seam. Fast transitions are fine, but never at the cost of the read.

Transition Grammar (pick one per seam)

• hard cut on action: cut while the focal motion is still moving.
• jump cut: hard cut with matched direction/velocity across the seam.
• motion-masked swap: outgoing motion becomes the next beat's reveal/mask.
• continuous carry: an object/text travels into its next location across chapters.
• occlusion wipe: a large shape covers frame, then reveals the next chapter.
• hold/settle cut: only when the beat must land clearly first.
• loop reset: when the cadence intentionally repeats.

Choosing Transitions (message + tone)

• Energetic list/supercut/recap → repeated armature + hard cut / jump cut on motion.
• Narrative / product walkthrough → continuous carry or motion-masked swap.
• Contrast or palette/world change → occlusion wipe or hard cut.
• Premium / stat / proof → restrained mask or hold/settle cut.
• Read-critical → hold longer; never cut before it is understood.
• Every seam needs a reason — preserve continuity, create contrast, reset rhythm,

or land a point. Do not vary transition types randomly.

Seam Mechanics

A transition is chapter role + timing + direction + cut point + masking + easing — not easing alone; anchors only support it. Carry across seams: cut during motion for cut-on-action (never after a settle); match direction and perceived velocity across jump cuts; a readable coast/hold must precede any fast exit; and interrupted motion only reads as intentional under repeated rhythm (an armature of ~3–4+ beats), not as a one-off.

Author cut-on-motion exits so the natural endpoint lives beyond the visible cut: the visible chapter is a window into a longer arc (e.g. it ends at frame 100 but the move would resolve toward ~120–140), and the seam interrupts the move while velocity is still active, often rising, before the motion settles. The core rule is active continuation, not necessarily acceleration: velocity may be rising (kinetic exit), steady (a constant pan), or already high and steady (a fast object pass) — what matters is it is not settled and would continue if the chapter were extended.

Seam Plan (before authoring)

Decide, per seam, before keyframing:

• chapter role — what this beat does
• readable window — where the message coasts/holds
• outgoing motion — what's moving at the end (direction + speed)
• transition type — from the grammar
• incoming motion — what's moving at the start
• easing anchor — the supporting curve
• cut/hold frame — the exact seam frame; in-motion vs at-rest
• reason for the seam — continuity / contrast / rhythm reset / land a point

Seam Verification

Inspect the two boundary frames per seam:

• Render the outgoing last frame and the incoming first frame; confirm each meets

its row's two frame conditions above.

• Cut-on-action / jump cut: outgoing last frame is still moving (not settled);

direction + perceived velocity match on the incoming first frame. Check the outgoing motion would continue if the chapter were extended — if the object reaches its final target on the seam, it is a settle cut, not cut-on-motion.

• Masked swap / occlusion wipe: no gap frame where neither chapter is composed;

the mask/cover fully occludes at the swap.

• Continuous carry: the carried element's position + velocity match across the

seam, or the motion logic is visibly continuous enough that the eye can follow it (related element / transform is fine).

• Hold/settle cut: the message is readable and at rest before the cut.
• Loop reset: first and last frames match (position, color, velocity) unless the

reset is intentional.

Guardrails

• Jump/hard cuts need repeated rhythm or a clear editorial reason; one isolated

interrupted move can look broken.

• Cut-on-motion should usually match direction/velocity across the cut.
• Avoid high-energy chapter cuts for calm luxury/institutional tone, final logo

lockups, legal text, or anything that must settle to be understood.

Design Taste

Use this reference when composition, typography, layout, color, or brand polish matters.

Contents

• Design Decision Loop
• Taste Modes
• Simplify Before Adding
• Composition Defaults
• Primitive Systems
• Anti-Generic Replacements
• Placement And Framing
• Typography
• Color And Material
• Data And Figures
• Brand-System Grammar
• Background And Generative Fields
• Production Polish
• Final Design Review

Design Decision Loop

Before authoring a designed scene, define the message, focal subject, support layer, accent system, and final-frame composition goal. If those choices are not clear, the design will usually drift toward generic shapes.

• Translate "clean", "technical", or "premium" into a specific system: editorial

light, product UI, schematic minimal, branded system map, dense dashboard detail, or presentation-grade explainer.

• Choose the taste mode before authoring: restrained product, institutional

data, bold social, expressive primitive, playful character, or ambient field.

• Start with the fewest objects needed. A strong default is one focal subject,

one support layer, and one accent system.

• Choose the main still image first. Motion should reveal and clarify that

composition, not rescue a weak final frame.

• Decide which elements carry meaning. Decoration should either group content,

show state, direct attention, reinforce brand, or be removed.

• Separate believability from density. Product or content detail is believable

when state, workflow, labels, and hierarchy are internally consistent, not when the scene simply contains more interface fragments.

• If hierarchy, spacing, color restraint, object necessity, or final-frame

quality fails, simplify and revise before finishing.

Taste Modes

• Restraint-premium: neutral or one-hue palette, generous space, one functional

accent, calm easing. Use for product, enterprise, technical, finance, and serious data.

• Commitment-premium: one word, number, mark, or object at full focus; two-tone

or brand-locked color; beat-driven energy. Use for brand, social, title, and launch moments that need impact.

• Expressive primitive: one repeated shape, stroke, dot, glyph, cursor, or mark

carries the idea. Use arrangement and gestalt before literal illustration.

• Ambient/generative: one anchor, one derived field, one ground. Keep the field

quiet enough to host foreground content.

• Playful/character: use one emotional signature, such as blink, look, bounce,

or squash. Keep the rest disciplined so charm does not become clutter.

Simplify Before Adding

• Prefer fewer stronger objects over many meaningful-looking details.
• Remove, merge, resize, clarify, or rebalance existing elements before adding

a new object, badge, line, glow, or texture.

• Treat a detail as valid only when it improves comprehension, hierarchy,

workflow clarity, state, brand signal, or reading rhythm.

• A detail can have a role and still fail if the composition becomes crowded,

evenly weighted, or hard to read.

• When the scene feels generic, first strengthen the focal subject, spacing,

typography, and color roles. Add effects only after the composition holds.

• "Premium" most often fails by adding chrome: a framing card, a border, column

dividers, a second surface tint, or a gradient. Treat the word as a cue to subtract. Strengthen scale, weight, brightness, and spacing first; reach for a container only if removing it would lose meaning.

Primitive Systems

• Build richness from one primitive repeated or varied by scale, density,

position, value, or timing.

• A single stroke, dot, ring, capsule, glyph, or geometric mark can become logo,

texture, diagram, loader, or accent when used consistently.

• Density is acceptable when it is one motif multiplied. Many unrelated motifs

read as clutter.

• If using an expressive primitive, make the arrangement carry meaning:

overlap, orbit, chain, bracket, grid, radial order, or figure/ground.

• Avoid literal clip-art when an abstract relationship can explain the message

more clearly.

Composition Defaults

• Start with a clear hierarchy: primary subject, supporting detail, accent.
• Keep the object budget visible while designing: focal subject first, support

second, accent last.

• Compose the first and final frames as intentional still designs.
• Use visual center, not only mathematical center. Round shapes, tall marks, and

asymmetric logos may need optical nudging.

• Keep safe margins around text, logos, and overlays. Leave extra room for

motion overshoot and blur-like effects.

• Use negative space as an active design element; do not fill every empty area.
• Align to a simple grid, baseline, or optical axis. Break alignment only when

the concept clearly benefits.

Anti-Generic Replacements

• Do not default to dark grids, blue arrows, empty cards, monospaced labels, or

decorative circles for technical work. Use a chosen visual system with clear information hierarchy.

• Replace empty rounded cards with meaningful node details: icons, mini UI

fragments, step numbers, labels, thumbnails, status marks, metrics, or data hints.

• Replace arbitrary accent circles with ports, badges, state indicators,

handles, highlights, or remove them.

• Replace decorative grid wallpaper with structural alignment, section bands,

subtle dividers, real axes, or whitespace.

• Replace generic glow with a focal halo, active-state emphasis, masked material

pass, or no effect.

Placement And Framing

• For transparent assets, frame the artwork tightly enough to feel usable but

leave breathing room for motion.

• For full-frame scenes, keep the subject away from edges unless edge contact is

part of the design.

• Preserve logo lockups. Do not change mark/wordmark proportions, spacing,

rotation, or final alignment unless explicitly asked.

• Check whether the animation's final resting pose is the intended exported

asset, not an in-between state.

Typography

• Use one main type idea per composition: editorial, utilitarian, kinetic,

playful, or premium.

• Decide the focal line or phrase before styling support text.
• Choose type for voice: serif for human/editorial authority, grotesque for

product/function, monospace for technical labels, expressive type only when the words are the subject.

• Large light-weight type can feel more premium than heavy bold in restrained

institutional scenes; heavy bold suits loud social and title work.

• Keep text readable at the intended size. Avoid crowding edges.
• Split long text into deliberate lines; do not let line breaks feel accidental.
• Establish type hierarchy with size, weight, case, and spacing before adding

effects.

• Balance text blocks optically: line length, rag, weight, and spacing should

feel stable in the final frame.

• When two text runs of different sizes share a row (label and value, name and

number, icon and caption), align them by their cap-height centers, not by a shared baseline. A shared baseline makes the smaller run appear to sink. Center a single run inside a container by its cap-height box, not the em box or the baseline. See player-contract.md "Vector Text Vertical Placement" for the formula, since vector text has no auto-centering.

• Set vertical spacing between stacked text blocks relative to type size, not by

eyeballed pixels. A workable default for a headline and the line directly below it is a gap of about 0.5 to 0.8 of the headline cap height; keep one consistent spacing step between sibling blocks so the rhythm reads deliberate.

• Use monospaced type only for code, data, terminals, or system-like content.
• Use weight, size, and timing before adding decorative elements.
• Convert to paths when exact font rendering matters and font support is

uncertain.

Color And Material

• Start from source/brand colors when provided.
• When no brand system is provided, prefer a premium pure black/white

(000/fff) contrast or another deliberate premium palette; use warm near-black and cream/off-white tones only when the user asks for them.

• Use one dominant neutral or background, one primary color, and one accent

unless the concept demands more.

• Assign color roles before adding new colors: background/neutral, focal

subject, accent, and optional semantic state.

• Quarantine saturation to one expressive element, or make every color teach a

category, state, comparison, or brand role.

• Do not let multiple accents compete for the same level of attention.
• Use tonal steps, hairlines, and brightness ramps for depth before shadows,

glow, glass, or blur.

• Chrome/container budget is 0 by default. A framing card, container, border,

or divider must do a job that whitespace and alignment cannot, or it is removed. Separate grids and columns with negative space and alignment first, a single hairline second, and a filled or bordered card last. Carry hierarchy with type weight, scale, brightness, and grouping, not with chrome.

• Use one surface tone. Do not stack two near-black or two near-white tints to

fake a "surface"; layered low-contrast darks (or lights) read as a muddy box. If a card surface must differ from the background, make it one deliberate step with a clear purpose, not an arbitrary second tint.

• If dividers are genuinely needed, use one weight and one color for all of them,

the title rule and any column rules included. Slightly different divider or border colors per element is a classic low-taste tell.

• Avoid muddy gradients, arbitrary glows, and decorative effects that reduce

legibility.

• When using glass/metal/glow effects, keep the base composition readable with

the effect removed.

• Verify color contrast on the intended background or transparent preview.

Data And Figures

• The headline should state the insight; the chart or number confirms it.
• Pick the layout by the data job: hero figure, KPI grid, stat-card triad,

comparison chart, progress card, dashboard metric, social proof, or heat map.

• Big figures should lead with extreme figure-to-label scale contrast.
• Default a stat triad to either even self-contained cards or borderless figures

floating in negative space, separated by whitespace. Do not wrap the group in an extra outer framing card, and do not put dividers between the columns unless whitespace alone fails; if they are needed, use one hairline of one color between equal columns only.

• Direct-label values. Avoid forcing viewers to decode axes, legends, or chart

clutter.

• Use one semantic accent against neutral, two values of one hue, or one

saturated hue per card. Do not use rainbow color decoratively.

• Encode magnitude spatially when useful: size, bar height, strip width, ring

nesting, heat rank, or actual-vs-goal contrast.

• Credibility comes from concrete scope signals: counts, source totals,

outcome-tied logos, named people, or transparent caveats.

Brand-System Grammar

• For multi-scene work, lock one layout skeleton, type system, and accent rule

before designing variants.

• Use polarity flips, saturated-card variants, or theme slots for rhythm without

inventing a new design language per scene.

• Apply the same restraint to utility content: timelines, address cards,

event rows, and labels should use the same grid, hairlines, and type system.

• A recurring signature device can make a system ownable, but it must stay

tonal or semantic instead of competing with the focal subject.

Background And Generative Fields

• Build ambient fields from one anchor plus one derived field on one ground.
• Prefer fields generated from the subject, such as ripples, contours, or

orbiting points, over generic motif scatter.

• Keep background fields type-free, low-contrast, and still-frame-clean unless

the field itself is the deliverable.

• Use one motion archetype that fits the content: color cycle, path morph,

drift and twinkle, staggered draw-on, radial emanation, or phase-offset wave.

• Make loops seamless and quiet enough that foreground content remains the

hierarchy.

Production Polish

• Check frame 0, midpoint, and the final frame as design compositions.
• Treat first, midpoint, and final frames as the minimum still-frame check. For

scenes with major semantic beats, also inspect the frames where a word lands, number resolves, logo locks up, chart completes, CTA appears, or camera move settles.

• The final frame should have one clear focal subject, readable support, and

intentional negative space.

• The final frame should feel visually finished, not merely like the last

rendered frame.

• Remove temporary construction shapes, debug colors, and placeholder names.
• Confirm no text, stroke, glow, or reveal mask clips during motion.
• Ensure the motion path and visual hierarchy point to the same subject.
• Prefer fewer, better elements over many weak accents.
• Reject placeholder-looking scenes even when they render correctly. If a node,

label, or accent does not communicate meaning, refine it or remove it.

• Treat unresolved hierarchy, crowded detail, weak typography, color overload,

or a poor final still as blockers. Revise the scene before considering it complete.

Final Design Review

• Check focal point first: the viewer should know where to look before reading

support labels or noticing accents.

• Check placement and spacing: margins, optical centering, baseline alignment,

line breaks, and object spacing should feel deliberate at rest and during motion.

• Check hierarchy: scale, weight, brightness, spacing, and timing should make

primary, support, and accent roles obvious.

• Check typography: line breaks, rag, casing, weight, tracking, and label

placement should support the message rather than fill available space.

• Check vertical alignment and rhythm: mixed-size runs sharing a row should be

cap-center aligned, single runs should be optically centered in their containers, and the spacing between a title and its subline (or any stacked blocks) should look intentional rather than tight or arbitrary. Inspect rows zoomed in, since small misalignments hide at full-frame scale.

• Check color roles: each saturated or high-contrast color should indicate

brand, state, category, comparison, or focus.

• Check object necessity: remove, merge, resize, clarify, or rebalance weak

elements before adding decoration, cards, glow, or extra detail.

• If the review fails, revise the composition and recheck the affected frames

before finishing.

Premium Restraint Checklist

Run this scan on any premium/clean/minimal/card scene before finishing:

• Zero unnecessary chrome: no framing card, border, or divider that whitespace

and alignment could replace.

• Exactly one surface tone: no two stacked near-black or near-white tints.
• One divider treatment and one color, if any divider exists at all.
• Hierarchy reads from scale, weight, brightness, and spacing with all chrome

removed.

• For each card, border, or divider present: would removing it lose meaning? If

not, remove it.

Lottie Spec Map

Use this reference when authoring or debugging Lottie JSON structure. It is a curated map of the upstream spec for this project, not a replacement for it.

Upstream specs:

• https://github.com/lottie/lottie-spec/tree/main/docs/specs

Core Structure

• Top-level documents should include v, fr, ip, op, w, h, nm,

assets, and layers.

• ip is inclusive and op is exclusive. ip: 0, op: 90, fr: 60 renders

frames 0..89.

• Prefer a meaningful top-level nm; the player shows it as the canvas label.
• Keep assets local to the scene folder and reference images by bare filename in

assets[].p.

Properties And Keyframes

• Static properties use { "a": 0, "k": value }.
• Animated properties use { "a": 1, "k": [keyframes] }.
• Keyframes must be sorted by ascending t.
• Non-hold interpolation should put o on the start keyframe and i on the

destination keyframe; the final keyframe does not need an outgoing o.

• Scalar animated values use arrays in keyframes, for example "s": [45] for

rotation or opacity.

• Color values are RGB or RGBA floats in 0..1; opacity values are 0..100.
• Easing handle x values are 0..1; y values may exceed that range for

controlled overshoot.

• A cubic-bezier (x1,y1,x2,y2) splits across two keyframes: it is the

outgoing handle of the start keyframe o:{x:[x1],y:[y1]} and the incoming handle of the end keyframe i:{x:[x2],y:[y2]}.

• Overshoot: prefer a short settle-back keyframe past the target; the compact

alternative is pushing the end i.y above 1. Anticipation: push the start o.y below 0.

Layers

• Shape layers use ty: 4.
• Image layers reference entries in assets.
• Layer visibility is ip <= frame < op.
• Parent transforms compose through parent references. Avoid cycles.
• Mattes, masks, precomps, and time remap are valid but more fragile; use them

only when simpler shape/layer structure will not produce the result.

Shapes

• Group related shapes with ty: "gr" and put the group transform

ty: "tr" last in the group's it array.

• Styles apply to shapes that precede them within the current scope. A shape

without an applicable fill or stroke will not render.

• Shapes render in reverse stack order inside groups. Verify visually when layer

order matters.

• Common primitive types:
• rectangle: ty: "rc"
• ellipse: ty: "el"
• path: ty: "sh"
• polystar: ty: "sr"
• fill: ty: "fl"
• stroke: ty: "st"
• trim path: ty: "tm"
• group transform: ty: "tr"

Slots

• Define reusable values in top-level slots.
• Reference a slot with sid on a compatible property.
• Slot type is inferred from the slot value. Keep slot values compatible with

every property that references that sid.

• If a property has a missing sid, renderers may fall back to the inline value

or a type default. Do not rely on missing slots.

Asset And Renderer Notes

• Image asset dimensions should match the expected w and h bounds when

possible.

• SVG, masks, gradients, blend modes, and intersections can differ between

renderers. Verify in Skottie.

• Avoid expressions or renderer-specific extensions unless the player explicitly

supports them.

Motion Taste

Use this reference when choosing pacing, easings, staging, or animation style.

Contents

• Principles
• Timing Defaults
• Easing Anchors
• Choreography
• Reveal Grammar
• Chapterization And Transition Grammar
• Motion Economy
• Typography Choreography
• Data And Figure Motion
• Camera, Parallax, And Scene Motion
• Path Reveals And Loops
• Loop And Generative Motion
• Style Presets
• Render-Aware Motion
• Final Motion Review
• Checks

Principles

• Stage motion in readable beats: anticipation, action/reveal, settle.
• Give the primary subject the clearest timing. Secondary elements should support

it, not compete.

• Match easing to intent. Functional UI needs speed and clarity; brand motion can

hold longer; playful effects can overshoot more.

• Avoid linear interpolation unless mechanical motion is the intent.
• Avoid generic easing where every property shares the same timing by default.

Use locked timing for rigid/UI-stable motion, and offset opacity, position, scale, or trim timing only when it improves choreography.

Timing Defaults

• UI microinteractions: 12-30 frames at 60 fps.
• State feedback icons: 30-75 frames, usually with a short hold.
• Logo marks: 45-120 frames depending on complexity.
• Lower thirds: 45-90 frames in, optional 30-60 frames out.
• Typography reveals: 45-150 frames depending on text length.
• Product/social promos: 90-180 frames for one clear message.
• Loaders/icons: loop cleanly over 60-120 frames.

Easing Anchors

Known-good defaults to derive from, not a closed preset list. Anchors describe motion behavior (entering, settling, traveling, exiting, looping, cut companion), not layer type: a logo, hero, title, card, or accent each picks by what it is doing this beat. Bezier is x1,y1,x2,y2.

• Derive, don't invent: start from the nearest anchor and adjust one quality —

acceleration, coast, landing softness, exit speed, overshoot. Reach for a new curve only when no anchor fits.

• Per-property orchestration: choose how properties coordinate, not just which

easing each uses — match the method to the motion character. Locked (start/end together) for UI, panels, buttons, mechanical/synced state. Lead/follow (one property leads a few frames, another follows) for logo/hero/organic, where position, scale, rotation, opacity, masks, trim, or number changes may use different curves, start/end frames, or durations. Primary/secondary (one property carries the motion, others support subtly). Early-opacity/late-settle (opacity resolves fast while position/scale keeps settling, for readability). Single-property overshoot (only scale or rotation overshoots, position stays controlled).

• Hierarchy: only the focal element gets the strongest personality

(expressive-pop, overshoot, snap); support uses quieter anchors (settle-soft, travel-balanced).

• Distance/duration: large travel → smoother acceleration and more time (don't

snap); tiny UI → short, not theatrical; camera → calmer than the objects in it.

• Typography: support settle-soft; active word expressive-pop/entrance-sharp.

Count-up: near-linear digits, settle-soft landing. Mask-wipe: entrance-sharp, revealed content settle-soft.

• Hard cut / jump cut / chapter transition: outgoing exit-accelerate (or

travel-cut for long travel), cut before it settles; pair with a motion-masked swap when continuity matters — see Chapterization And Transition Grammar.

• Loop reset: match first/last velocity; use a visible reset only via

exit-accelerate+cut.

• Overshoot: small, premium-off by default. Prefer a settle-back keyframe (past

the target, then ease back — Skottie-safe); end i.y ~1.08 to 1.2 is the compact alternative.

• Also useful: anticipate (pull slightly opposite before a fast reveal),

steps/holds (typewriter, counters, scans, technical beats), and continuous linear (rotations, scanners, progress loops, mechanical seams).

Choreography

• Decide the lead element, then delay supporting elements by 2-8 frames for

compact UI and 4-14 frames for expressive scenes.

• Stagger from the meaningful origin: first, center, last, path direction, or

focal point.

• Let opacity often start after movement begins and finish before the settle.
• Do not animate every property on every layer. Stillness gives motion contrast.
• Scrub around the settle. The final 10-20 percent of motion should feel

intentional, not like a numerical drift.

Reveal Grammar

• Use build, settle, hold as the default reveal spine. The hold is where the

message or brand registers.

• Reveal in reading or importance order. Hero/focal subject lands first;

labels, stats, metadata, and support arrive after.

• Stagger repeated items by about 3-6 frames for compact motion or 50-80 ms for

scene-level beats.

• Prefer mask-wipes, marker sweeps, trim-path draw-ons, and purposeful cuts over

uniform opacity fades for premium scenes.

• One scene or beat should have one main flourish. Too many reveals in the same

beat weakens hierarchy.

Chapterization And Transition Grammar

• Gate: if the prompt carries more than one idea (long text, lists, multiple

stats, timeline, before/after, problem/solution, quote+proof, walkthrough, recap/story, multi-language or repeating variations), split it into chapters instead of cramming one scene. A single-purpose beat (logo lockup, one CTA, one stat, legal/read-critical, calm hero that must settle) stays one beat and lands.

• Give each chapter one readable job, and let the main message get a coast or

hold before any seam.

• Choose each transition by seam purpose — preserve continuity, create contrast,

reset rhythm, or land a point — not at random. A transition is chapter role + timing + direction + cut point + masking + easing, not easing alone.

• For dense/multi-part prompts, read

references/chapterization-transition-grammar.md for the full when/when-not, roles, structure modes, transition grammar, selection, cut-on-action mechanics, easing-anchor support, and guardrails.

Motion Economy

• Motion should reinforce the same hierarchy as the final frame: focal subject

strongest, support calmer, accents lowest priority.

• Animate fewer properties when that produces a clearer read.
• If movement makes the scene feel busy, crowded, or unfocused, simplify the

visual structure before adding more motion.

• Effects, camera moves, and staggers should never compensate for weak layout.

Revise the composition first.

Typography Choreography

• Treat kinetic typography as phrase performance, not uniform text entrance.
• Assign anchor, support, and active text. Let the active word or phrase carry

the strongest motion while support text stays calmer.

• Use semantic easing and spacing: sharp words can hit harder, soft words can

settle gently, heavy words can land lower, and flowing words can travel continuously.

• Offset position, scale, mask, opacity, and layout timing so words relate to

the phrase instead of sharing identical keyframes.

• Preserve reading order. Expressive motion should make the phrase clearer, not

harder to parse.

Data And Figure Motion

• Animate data by its own logic: bars grow from baseline, lines draw left to

right, segments widen to proportion, dots populate, rings nest or emanate, and Sankey-like flows route from source to target.

• Count figures up with baked keyframes, tabular numerals, and an ease-out

settle. Let labels or units arrive after the number resolves.

• Sync labels to geometry. A point label should resolve as the line reaches it;

a bar value should count while the bar grows.

• Use mask-wipes for insight headlines and trim paths for hairlines, axes,

connectors, rules, and chart strokes.

• Serious data needs calm ease-out and no bounce. Small pops are acceptable only

for badges, consumer/wellness warmth, or bold social panels.

Camera, Parallax, And Scene Motion

• Treat camera motion as the viewer's attention, not decoration.
• Use one dominant camera move: push in, pull out, pan, follow, or parallax.
• Move foreground, subject, and background at different rates only when it

clarifies depth.

• Keep camera easing smoother than object easing. Abrupt camera stops feel cheap.
• Avoid pan/zoom that makes text unreadable or crops the hero subject.

Path Reveals And Loops

• Path drawing should follow the natural reading or construction order.
• Keep trim-path speed visually even; short segments may need shorter durations.
• For handwriting/path reveals, add a slight follow-through or ink settle only

if it suits the style.

• For loops, match first and last frames in position, opacity, color, and

perceived velocity.

Loop And Generative Motion

• Repeated fields need phase offsets by index, distance, row, or path position.

Lockstep pulsing reads mechanical unless the prompt asks for it.

• Engineer loop seams with identical first/last frames, integer wave cycles,

closed rotations, wrapped drift, or recycled emanation rings.

• Give ambient loops one conceptual beat: pulse, mirror, morph, inversion,

density build, or recovery to order.

• Use one repeated primitive and one main animated property where possible.
• Rich motion is licensed when the animated abstract element carries the

message. Keep surrounding type, UI, and support calmer.

• Morph the same objects between states instead of spawning unrelated new

objects when continuity is important.

Style Presets

• premium-settle: slower reveal, low overshoot, elegant final ease.
• kinetic-snap: fast stagger, strong contrast, crisp settles.
• soft-interface: small distances, low overshoot, short duration.
• technical-trace: trim paths, precise timing, minimal flourish.
• ambient-loop: no visible seam, constant perceived energy.
• playful-pop: larger scale contrast, friendly overshoot, quick recovery.
• data-confirm: insight headline, geometry reveal, synced count-up, calm hold.
• phase-field: repeated primitive with baked offsets and seamless loop.

Render-Aware Motion

• Bake counters, particle offsets, orbit math, physics, and expression-like

systems to keyframes before relying on Skottie.

• Fake velocity with offset duplicate layers instead of motion blur.
• Treat blur, bloom, glass, chrome, dither, true 3D, and displacement as

renderer-risky. Approximate with vector shapes, stacked tonal fills, or baked raster assets.

• Path morphs require compatible vertex structures. If not safe, use masks,

replacements, or crossfades.

• Cap dense fields and verify performance. Repeater-based fields cannot assume

independent per-instance animation.

Final Motion Review

• Scrub playback. First and last frames alone are not enough to judge timing,

stagger, readability, or settle quality.

• Inspect key beat frames: frame 0, early reveal or first meaningful beat,

midpoint, settle or near-final, op - 1, loop seam if looping, and semantic beats where a number resolves, word lands, logo lockup forms, chart finishes drawing, CTA appears, or camera move settles.

• Check beat order: the focal subject should lead, support should follow, and

accents should not steal the read.

• Check stagger origin and spacing: repeated elements should begin from the

meaningful source, path direction, reading order, or focal point.

• Check timing and easing: entrances should feel intentional, not uniform;

settles should land cleanly without drift, snap-back, or accidental float.

• Check readability during motion: text, data, icons, and UI states should be

parseable at the moments they matter.

• If motion feels busy or hides weak layout, simplify the visual structure or

reduce animated properties before adding more choreography.

Checks

• Midpoint should communicate what is happening, not only look like transition

blur.

• The final settle should land in the strongest composition, not only stop on a

valid frame.

• Loop start/end should be invisible unless a reset is intentional.
• Secondary motion should never distract from the requested message.
• If an animation feels generic, adjust stagger origin, easing intent, or the

final settle before adding more effects.

• For kinetic typography, reject motion where every word uses the same entrance

timing and property changes unless the prompt asks for a minimal reveal.

Player Contract

Use this reference before creating, editing, fixing, or verifying any scene.

Setup

Use the official player project. Do not verify through a custom page, lottie-web, or another renderer.

If the player project is missing:

npx degit diffusionstudio/lottie my-animation
cd my-animation
npm install
npm run dev

The dev server defaults to port 3030, but never assume it. On npm run dev, Vite prints the URL it bound to (Local: http://localhost:<port>/) and falls back to the next free port when 3030 is taken — e.g. when another project folder is already serving. Treat that printed port as the source of truth and use it as <port> in every curl and navigation below; a second folder's server answers on a different port, so a blind request to 3030 will hit the wrong project.

If the project already exists, use its existing setup and start npm run dev when browser verification is needed.

Scene Layout

Every renderable scene lives under public/projects/:

public/
  canvaskit.wasm
  projects/
    <project-slug>/
      <scene-N>/
        lottie.json
        controls.json
        <image files>

• lottie.json is required. A scene without it is ignored.
• Project and scene slugs become URL segments: /<project>/<scene>.
• Scene ordering comes from the trailing number in scene-<N>.
• Put image assets next to the scene and reference them by bare filename in

assets[].p, for example "p": "logo.svg".

Target Scene Policy

• Resolve target scenes by authority. A user-provided file path wins. A browser

URL route like /<project>/<scene> wins next and maps to public/projects/<project>/<scene>/lottie.json. An already-known project/scene for the task wins next.

• Do not let the active scene from GET /__context, the live block in

/__context, or /__context.live override a known file path, URL, or project/scene.

• If project/scene is known, navigate directly to

http://localhost:<port>/<project>/<scene> and inspect frames there with ?frame=<N>.

• Use the active project/scene from GET /__context only when the task is

explicitly to edit what is currently on screen and no more specific target exists.

• If creating new work without a target, create a new project/scene or the next

available scene-<N>.

• For dropped, uploaded, or imported Lottie JSON, work on the generated scene

under public/projects/<imported-project>/<scene>/lottie.json, not the original dropped/uploaded JSON context.

• Before editing, verify the resolved file is the intended

public/projects/<project>/<scene>/lottie.json; before overwriting an existing lottie.json, re-read the current file from disk.

• Overwrite public/projects/main-project/scene-1/lottie.json only when it is

still the untouched placeholder. If unsure, create a new scene.

Treat main-project/scene-1 as safe to overwrite only if it has one simple background layer, no meaningful assets, no custom controls, and a generic name such as Scene 1 - 512x512.

Live Editor Behavior

• The scene tree watches folders and updates live.
• Editing an existing lottie.json may require reload or re-navigation.
• Slot edits in the UI are written back through /__scenes/lottie, so re-read

source before applying another edit.

Context Endpoint

Use the context endpoint for project-tree discovery, last-modified checks, and observational playback state:

curl -s http://localhost:<port>/__context

It reports the project tree, active project/scene, frame, total frames, fps, and last-modified times. Treat that active scene as observational unless the task is explicitly to edit what is currently on screen and no path, URL route, or known project/scene target exists.

Frame Pinning

Inspect exact frames by navigating to:

http://localhost:<port>/<project>/<scene>?frame=<N>

?frame=N seeks and pauses on load. Use frame 0, midpoint, and op - 1 for new scenes; use focused frames for small edits. The canvas is <canvas id="main-canvas">.

Slots And Controls

Use slots for user-editable values that should appear in the player properties panel. The player discovers slots automatically through Skottie.

Top-level slot pattern:

{
  "slots": {
    "accentColor": { "p": { "a": 0, "k": [0.2, 0.5, 1, 1] } },
    "scaleAmount": { "p": { "a": 0, "k": 100 } }
  }
}

Reference a slot with sid on a compatible property:

{ "c": { "sid": "accentColor" } }

Add controls.json next to lottie.json when labels or numeric ranges matter:

{
  "controls": [
    { "sid": "accentColor", "label": "Accent color" },
    { "sid": "scaleAmount", "label": "Scale", "min": 40, "max": 160, "step": 1 }
  ]
}

Slot value types map to controls:

Slot types must match the properties that reference them.

Text Rendering Fast Path

• Native Lottie text layers and text slots are not reliable in this player by

default. CanvasKit exposes text slots, but text still needs font data at Skottie animation creation time.

• The current scene loader passes discovered image assets to

MakeManagedAnimation; it does not discover or pass scene font files.

• Local CanvasKit verification showed native text renders transparent without a

font blob and renders once the matching font blob is supplied.

• For fixed prompt text, do not spend time trying native text first. Author text

as vector/shape artwork immediately.

• Use native text slots only when editable text is explicitly required and font

asset loading has been implemented and verified in the official player.

Vector Text Vertical Placement

Vector text has no line-height or auto-centering. You place every glyph by hand, so compute the baseline from the font's cap height instead of eyeballing it.

• Derive cap height from the font, not a guessed number:

capEm = sCapHeight / unitsPerEm, then cap = capEm * size. If the font lacks the metric, fall back to capEm ≈ 0.7 (use x-height ≈ 0.52em for all-lowercase runs).

• To vertically center a run in a container whose center is cy:

baseline = cy + cap / 2.

• For a row holding two runs of different sizes (for example a small label and a

large value), center each run on the shared center line using its own cap height. A shared baseline makes the smaller run sink below the larger one.

Background Policy

• Full-frame standalone compositions should include a visible background layer

with a bgColor slot and a controls.json entry.

• Transparent-by-default outputs include logos, icons, loaders, overlays, lower

thirds, and SVG-derived assets unless the user asks for a background.

• Do not add an opaque rectangle just to fill the canvas.
• If a transparent animation needs preview contrast, use the player/canvas

environment for verification instead of baking unwanted pixels into the JSON.

Verification

• Validate JSON before browser verification.
• Confirm the scene appears in /__context.
• Inspect pinned frames in the browser. New scenes need frame 0, midpoint, and

op - 1.

• Fix blank canvas, missing assets, unstyled shapes, wrong layer order, bad

easing, cropped content, text overflow, and SVG artifacts before finishing.

Final Review Passes

Run lightweight render, design, and motion reviews before calling a scene complete. First, midpoint, and final frames are the minimum still-frame check, not a substitute for motion review.

• Render review: validate JSON, confirm /__context, verify assets load, and

inspect pinned frames in the official player.

• Design review: inspect frame 0, midpoint, op - 1, and any major semantic

still. Check focal point, placement, spacing, hierarchy, typography, color roles, object necessity, and final-frame strength.

• Text alignment review: inspect text rows zoomed in, not only at full-frame. A

few pixels of vertical misalignment are invisible at composition scale. Confirm that mixed-size runs sharing a row are cap-center aligned, that single runs are optically centered in their container, and that stacked blocks (such as a headline and its subline) follow an intentional vertical rhythm.

• Motion review: scrub playback and inspect key beat frames: frame 0, early

reveal, midpoint, settle or near-final, op - 1, loop seam if looping, and semantic beats where a number resolves, word lands, logo lockup forms, chart finishes drawing, CTA appears, or camera move settles.

• Check beat order, stagger origin, timing, easing, settle/hold, loop seam,

camera/framing, and readability during motion.

• If design or motion review fails, simplify and revise before finishing. A

valid render is not enough.

Recipe: Camera And Scene Motion

Use for camera-following motion, pan, zoom, parallax, layered scene movement, hero pushes, product screenshot tours, and animated scene framing.

User-Language Aliases

• "pan across this", "zoom into the product", "camera follow"
• "parallax scene", "Ken Burns style", "move through the interface"
• "push in", "pull back", "follow the path", "scene motion"

Defaults

• Choose one dominant camera idea: push, pull, pan, follow, or parallax.
• Keep the main subject readable throughout the move.
• Use full-frame background policy unless the result is a transparent asset.
• Treat camera motion as attention direction, not decoration.
• Use camera motion to improve attention and final-frame framing, not to hide a

weak composition.

Presets

• premium-push: slow push-in with subtle foreground/background separation.
• guided-pan: horizontal or vertical pan revealing steps in order.
• focus-follow: camera follows one hero object or path.
• layered-parallax: foreground/midground/background move at different rates.
• product-tour: screenshot/product card moves through 2-3 feature beats.

Timing And Easing

• Compact camera move: 60-120 frames.
• Product or scene tour: 120-240 frames.
• Use smoother easing than object motion; abrupt camera stops feel cheap.
• Hold briefly after the camera arrives so the final message lands.

Ask Only When Needed

• Ask which subject to follow if the scene has multiple heroes.
• Ask output size/platform if framing depends on aspect ratio.
• Ask whether text must remain readable throughout the move when uncertain.

Construction Notes

• Prefer grouped/parented transforms over animating every child independently.
• Keep scale changes modest unless the move is the concept.
• Counter-animate text or labels if camera motion makes them hard to read.
• Use parallax only when layered depth exists or can be built cleanly.
• If the final frame feels like an accidental crop, revise the layout or camera

endpoint before adding more movement.

Common Failure Modes

• Camera crops the hero subject or text.
• Parallax layers move without a clear depth hierarchy.
• Motion sickness from too much scale/position change.
• Final frame feels like an accidental crop.
• Camera motion adds energy but does not improve hierarchy or framing.

Acceptance Checks

• The viewer's eye follows the intended subject.
• Important text remains readable or resolves quickly.
• First and final frames are clean compositions.
• Camera motion enhances the message instead of hiding weak layout.
• Final camera position lands on the strongest still frame.

Recipe: Data, Stats, And Charts

Use for KPI cards, stat reveals, big-number scenes, pitch-slide charts, dashboard metrics, progress/goal cards, social-proof rows, data-derived textures, and simple chart animations.

User-Language Aliases

• "animate these KPIs", "stat card", "big number reveal", "metric animation"
• "pitch chart", "growth chart", "bar chart", "line chart", "data slide"
• "dashboard metric", "progress card", "results row", "social proof"

Defaults

• Choose one data archetype before authoring. Do not improvise a layout for a

number.

• The headline should state the insight; the chart or figure confirms it.
• Use one semantic accent against neutral, two values of one hue, or one

saturated hue per card.

• Default to borderless figures in negative space, or even self-contained cards.

Do not wrap a stat triad in an extra outer framing card or border unless the user asks. Use exactly one surface tone; never stack two near-black or near-white tints. If columns need separation, use one hairline of one color between equal columns only, and prefer whitespace first.

• Count up figures with baked keyframes and tabular numerals unless the prompt

asks for static text.

• Use slotted background for full-frame data scenes; transparent only when the

user asks for overlay/asset output.

Archetype Picker

• Hero figure: one emotional metric, extreme figure-to-label contrast.
• KPI grid or stat-card triad: several parallel proofs using one repeated

template.

• Results rows: hairline label/value rows for credible outcomes.
• Comparison chart: one accent-vs-neutral bar, line, strip, or scale graphic.
• Progress/goal card: actual vs target, goal line, weekly bars, or ring nesting.
• Dashboard metric mock: one hero metric, one chart, and light supporting state.
• Social proof: outcome-tied logo/name row, metric, and attribution.
• Data-derived texture: heat map, mosaic, or dot/ring field where the pattern

is data, not decoration.

Timing And Easing

• Compact stat card: 60-120 frames.
• Multi-card/grid/chart reveal: 120-210 frames.
• Use calm ease-out and no bounce for finance, research, enterprise, and serious

data.

• Small pops are acceptable for badges, consumer/wellness warmth, or bold social

panels.

• Support text arrives after the figure or geometry resolves.

Construction Notes

• Bake counters and odometer rolls. Do not rely on live expressions in Skottie.
• Use tabular or fixed-width numeral shapes so digits do not jitter.
• Sync counts to geometry: line reaches point, bar reaches height, segment

reaches width, or ring reaches target.

• Direct-label values on points, bars, cards, rows, or panels. Avoid axis

decoding when the scene is short.

• Use trim paths for lines, hairlines, axes, callout arrows, rules, and flows.
• Use masks or clip reveals for rounded bars/cards so radii do not distort.
• Use slots for insight/headline text, key values, accent color, background

color, and optional chart colors when useful.

• Placeholder third-party logos, compliance marks, or headshots unless the user

supplied rights-safe assets.

Common Failure Modes

• Title names the topic but not the insight.
• Static number appears with a fade instead of a count-up.
• Values require axis/legend decoding.
• Rainbow chart color decorates instead of teaching.
• Too many metrics compete in one beat.
• Serious data uses bouncy or theatrical motion.
• An unnecessary outer framing card or border wraps the stat group when

whitespace and alignment would carry it.

• Multiple dividers use slightly different colors or weights (for example a title

underline plus column rules that do not match).

• Two stacked near-black or near-white tints read as a muddy box instead of one

clean surface.

• Dashboard mock looks dense but the state is incoherent.
• Rounded bars/cards stretch because they were scaled instead of revealed.
• Label and value in a row share a baseline, so the smaller label sinks below the

larger value instead of reading as one aligned row.

• Label/figure spacing or row spacing is eyeballed, so the vertical rhythm looks

uneven.

Acceptance Checks

• The data archetype matches the metric's job.
• The headline states the point and the data confirms it.
• Figures are direct-labeled, counted up, and readable.
• Label and value in each row are cap-center aligned and optically centered in the

pill, card, or row, and the value stays centered through the count-up.

• Stacked label/figure spacing and row-to-row spacing follow a consistent rhythm.
• Chart geometry and numeric labels resolve together.
• Palette uses semantic color, not decorative color.
• No outer framing card or border unless it does a job whitespace cannot; any

dividers are a single hairline and one color between equal columns; exactly one surface tone is used; hierarchy still reads with all chrome removed.

• Final frame works as a clear still data slide.
• Motion adds comprehension and does not overdramatize serious data.
• Counters, masks, trim paths, and rounded reveals are Skottie-safe.

Recipe: Diagram And Technical Animation

Use for technical diagrams, flow traces, line animations, callouts, architecture explainer graphics, process steps, and data/connection reveals.

User-Language Aliases

• "trace this diagram", "animate the flow", "show the pipeline"
• "technical line animation", "callout animation", "draw the connection"
• "architecture explainer", "step-by-step diagram", "network/path reveal"

Defaults

• Prioritize clarity over decoration.
• Follow the object budget in design-taste.md: start with the smallest set of

nodes, paths, labels, and accents that explains the system.

• Reveal in the order the viewer should understand the system.
• Do not treat "technical" as dark grid, blue arrows, empty rounded cards, and

decorative circles. Pick a concrete visual system.

• Use transparent background for overlays/assets; use slotted background for

full-frame explainers.

• Read svg-compatibility.md when the source diagram is SVG.

Before Authoring

• Define the final-frame topology: primary path, supporting clusters, callout

positions, and strongest still-frame read.

• Choose a visual system: editorial light, product UI, schematic minimal,

branded system map, dense dashboard detail, or presentation-grade explainer.

• Choose the structural relationship: chain for sequence, bracket for

part-whole, orbit for convergence, radial for system, grid for comparison, or hairline rows for evidence.

• Decide the node/detail strategy. Each node should communicate role, state,

sequence, metric, UI fragment, icon, or label.

• Decide what the lines mean: data flow, dependency, sequence, ownership, or

state transition.

• Keep believability separate from density: use coherent system states and

clear workflow labels instead of fake technical micro-detail.

Presets

• flow-trace: lines draw in path order, nodes activate after connection.
• callout-pop: labels or badges enter after their target is visible.
• scan-highlight: highlight travels across a path or system segment.
• node-network: nodes appear in clusters, connections follow.
• step-build: diagram builds one logical step at a time.
• orbit-system: radial nodes draw in, orbit subtly, and counter-rotate labels

to keep them upright.

Timing And Easing

• Simple diagram: 75-150 frames.
• Multi-step explainer: 150-300 frames.
• Use linear or near-linear trim for technical traces, with eased activation for

nodes and labels.

• Hold after each major step long enough for comprehension.

Ask Only When Needed

• Ask for the intended reading order if it is not clear from the diagram.
• Ask whether labels should be editable when text is prominent.
• Ask full-frame vs transparent only if destination is unclear.

Construction Notes

• Separate paths, nodes, labels, and highlights.
• Use trim paths for lines and small opacity/scale settles for nodes.
• Avoid path morphing; technical diagrams need stable geometry.
• Keep labels aligned and readable throughout the trace.
• Give each node useful interior detail: icon, number, small label, status dot,

mini UI row, thumbnail, metric, or port.

• Use arrows only when direction is ambiguous. Vary line weight, opacity, or

style to show primary and secondary flow.

• Use grids as alignment structure or axes, not decorative wallpaper.
• Turn floating circles into ports, status indicators, badges, or remove them.
• Use tonal rings, hairlines, halftone-like dots, or subtle value steps for

depth before glow or shadows.

• For orbit/radial systems, counter-rotate text/icons if the parent rotates.
• If the final frame feels crowded, reduce nodes, merge labels, or emphasize the

primary path before adding more detail.

Common Failure Modes

• Everything reveals at once, losing the explanation.
• Lines draw opposite the intended flow.
• Labels overlap or appear before their target.
• Decorative effects reduce technical clarity.
• Empty rounded rectangles make the diagram feel placeholder-like.
• Dark grid plus blue arrow chains make the scene feel generic unless requested.
• Generic node mesh suggests "technical" without explaining a relationship.
• Large blank regions weaken the final poster frame.
• Fake complexity adds visual noise without explaining the system.
• Dense meaningful-looking detail makes the system harder to understand.

Acceptance Checks

• The reveal order explains the system.
• Final frame is a clean, accurate diagram.
• Lines, arrows, labels, and callouts stay readable.
• Nodes contain enough information to be meaningful without the animation.
• The final topology feels balanced, with intentional negative space.
• Decoration has a job: grouping, state, brand, attention, or structure.
• Diagram structure communicates the relationship without relying on labels

alone.

• Detail improves comprehension without crowding the final composition.
• SVG source diagrams preserve holes, clipping, and intersections.

Recipe: Loaders, Icons, And State Feedback

Use for loaders, spinners, progress loops, badges, simple icons, success/error states, warning alerts, empty states, and compact status animations.

User-Language Aliases

• "loading spinner", "looping loader", "progress ring", "animated icon"
• "success check", "error x", "warning triangle", "complete animation"
• "toast icon", "empty state", "status badge", "done indicator"

Defaults

• Transparent background.
• Loop cleanly for loaders/spinners/progress.
• Play once and settle for success/error/warning states unless looping is asked.
• Keep geometry crisp and readable at small sizes.
• Prefer one primitive or icon idea repeated with phase offsets over unrelated

moving parts.

• Add only one charm gesture, such as blink, bounce, pulse, or draw-on, when it

fits the brand tone.

Presets

• orbital-loader: rotating dots or marks with seamless timing.
• stroke-trace: icon stroke draws, holds briefly, then resets or loops.
• pulse-badge: compact scale/opacity pulse around a status symbol.
• check-complete: path draw plus short settle for success states.
• error-shake: brief x/alert emphasis, controlled and not frantic.
• warning-pulse: triangle/badge reveal with restrained attention pulse.
• scan-progress: linear or radial progress sweep with controlled repetition.
• phase-dots: repeated dots or marks animate with offset timing and a matched

loop seam.

Timing And Easing

• State feedback: 30-75 frames with a stable final pose.
• Loaders: 60-120 frame seamless loops.
• Use continuous linear only for rotational/progress loops.
• Use short ease-out or low-bounce spring-like settles for success states.

Ask Only When Needed

• Ask loop vs one-shot only if the request is ambiguous.
• Ask target size if the icon must fit a specific UI slot.
• Ask brand/accent color if no source style exists.

Construction Notes

• Use trim paths for strokes, checks, rings, and circular loaders.
• Match first and last frames for loops.
• Engineer loop seams with identical first/last state or a period-locked cycle.
• Avoid excessive detail below small-icon sizes.
• Expose slots for accent color, stroke width, and background only if full-frame.

Common Failure Modes

• Loop seam is visible.
• Repeated parts move in lockstep and feel mechanical.
• Icon becomes unrecognizable during motion.
• State animation feels too playful for an error/warning.
• Stroke caps or joins render differently than expected.

Acceptance Checks

• Loop seam is invisible when looping.
• Repeated motion uses phase offset unless lockstep is intentional.
• Icon remains recognizable during motion.
• Timing feels useful, not frantic.
• Transparent output has no unwanted background layer.

Recipe: Logo Animation

Use for brand marks, wordmarks, logo reveals, intro/outro marks, app splash marks, and SVG logo sources.

User-Language Aliases

• "make my logo move", "logo reveal", "animate our mark", "app splash"
• "draw in this logo", "intro logo", "outro bug", "wordmark animation"

Defaults

• Preserve brand shape, color, spacing, and final lockup unless asked to

redesign.

• Default to transparent background.
• Build toward a clean lockup, settle, then hold. The held lockup is where the

brand registers.

• Ask for brand constraints only when the source does not imply them or when the

user asks for a specific style.

• Read svg-compatibility.md when the logo source is SVG.

Presets

• mark-draw: trim-path or mask reveal for line/outline logos.
• assemble-settle: pieces enter from nearby offsets and settle into the mark.
• premium-fade: soft opacity/scale reveal with subtle final polish.
• accent-sweep: brand accent passes across the mark, then disappears.
• wordmark-cascade: letters or word groups reveal in restrained stagger.
• splash-pop: compact app/splash reveal with a short hold.
• shape-vocabulary-build: brand shapes assemble first; wordmark lands as the

payoff.

Timing And Easing

• Simple mark: 45-75 frames.
• Mark plus wordmark: 75-120 frames.
• Use low-overshoot premium settles unless the brand is explicitly playful.
• Keep final 10-20 frames stable enough for a clean logo lockup.

Ask Only When Needed

• Ask for transparent vs full-frame if the intended use is unclear.
• Ask for brand adjectives only when the prompt gives no style direction.
• Ask whether to animate the full lockup or mark-only when both are present and

the requested use is ambiguous.

Construction Notes

• Separate mark, wordmark, and accent layers when possible.
• Keep final pose exactly aligned to the source logo.
• If the logo has distinctive modules, strokes, or brand shapes, animate those

before revealing the wordmark. Do not show the full answer too early.

• Avoid distorting brand geometry through squash, bounce, rotation, or blur-like

effects unless the user requests that personality.

• If a background is requested, expose bgColor and keep logo colors editable

only when useful.

Common Failure Modes

• Final frame does not match the source lockup.
• Wordmark letter spacing drifts during or after motion.
• Decorative effects overpower brand recognition.
• Wordmark appears before the build earns it.
• Transparent output accidentally includes background pixels.

Acceptance Checks

• Final frame is a faithful logo lockup.
• Lockup holds long enough to read after the reveal.
• Transparent output contains no unintended background pixels.
• Motion feels brand-appropriate, not generic.
• SVG intersections, holes, masks, and strokes render correctly in Skottie.

Recipe: Lower Thirds

Use for lower thirds, name tags, chyron, caption straps, speaker IDs, social handles, labels, and transparent overlay text.

User-Language Aliases

• "lower third", "speaker label", "name and title", "caption bar"
• "social handle overlay", "YouTube tag", "news chyron", "name strap"

Defaults

• Transparent background.
• Keep within safe margins and avoid the canvas edges.
• Prioritize legibility and quick comprehension.
• Ask for name/title/copy if missing; otherwise create editable slots when text

editing is expected.

Presets

• clean-slide: bar or text slides in, content fades, soft settle.
• broadcast-snap: fast blocks with crisp stagger and confident exit.
• minimal-line: thin accent line draws, text follows.
• pill-reveal: rounded container scales/masks open around text.
• social-tag: icon/handle enters with compact bounce and hold.
• caption-strap: understated bar with strong text legibility.

Timing And Easing

• Entry: 45-90 frames.
• Exit: 30-60 frames when requested.
• Use snappy ease-out for bars and softer ease for text.
• Keep the held state stable for reuse in editing timelines.

Ask Only When Needed

• Ask for exact name/title/handle if absent.
• Ask whether an exit animation is needed if the user says "reusable" or

"broadcast".

• Ask for placement only if bottom-left/default safe placement conflicts with

the request.

Construction Notes

• Expose slots for name, subtitle, accent color, and optional bar color.
• Keep lower-third elements grouped for easy positioning.
• Use masks for clean container reveals rather than clipping through the canvas.
• Leave safe margins for broadcast/video overlays.

Common Failure Modes

• Text is too small to read over real footage.
• Overlay occupies too much of the frame.
• Entry motion distracts from the speaker/content.
• Background is accidentally opaque.

Acceptance Checks

• Text is readable over varied backgrounds.
• The animation is transparent unless a background is explicitly requested.
• Entry and exit do not obscure too much of the frame.
• Final held state feels balanced and broadcast-ready.

Recipe: Product, Launch, And Social Promo

Use for product launches, feature announcements, app/product card reveals, release notes visuals, social promos, and short marketing-style Lottie scenes.

User-Language Aliases

• "product launch animation", "feature announcement", "new feature promo"
• "social post animation", "app screenshot reveal", "launch card"
• "show off this product", "announcement banner", "release animation"

Defaults

• Treat the product/feature as the hero.
• Use full-frame composition unless the user asks for a transparent asset.
• Keep copy short and readable; animate one message clearly.
• Pair one claim with one product-proof object. Avoid screenshot collages.
• Avoid generic launch-card layouts when no product signal is visible.
• Follow the object budget in design-taste.md: hero first, support detail

second, accent system last.

• Expose slots for headline, subhead, accent color, and background color when

useful.

Before Authoring

• Define the hero: product screenshot, feature surface, logo, object, or single

message.

• Define the product signal: UI fragment, thumbnail, feature callout, data chip,

branded shape, or recognizable workflow step.

• Define the proof: screenshot detail, believable UI state, metric, workflow

step, customer result, or capability demo.

• Define the final poster frame: headline position, product scale, CTA/message

focus, and supporting detail.

• Define believability through coherent product state, workflow, copy, and

hierarchy, not by adding more interface fragments.

• Decide which accents support the offer. Remove decoration that does not frame,

reveal, or emphasize the product.

Presets

• hero-card-reveal: product card/screenshot enters, headline follows.
• feature-spotlight: one feature area highlights with label/callout.
• launch-burst: title/product reveal with restrained celebratory accents.
• social-loop: short looping promo with clear first/final frame.
• update-stack: multiple feature chips/cards stagger into place.
• proof-object: claim enters, one product proof animates, support copy follows.

Timing And Easing

• Single announcement: 90-150 frames.
• Multi-beat product scene: 150-240 frames.
• Use premium ease-out for hero elements and small staggers for supporting

copy/chips.

• Keep any loop subtle enough for social/product contexts.

Ask Only When Needed

• Ask for exact headline/subhead if missing.
• Ask for product asset/screenshot if the prompt expects one but none exists.
• Ask aspect ratio only if platform is unclear and it changes composition.

Construction Notes

• Build around a hero layer, copy group, accent layer, and optional background.
• Use camera scene motion as secondary when the prompt asks for pan/zoom/tour.
• Use visual effects as secondary for glow, glass, sweep, or burst treatments.
• Use one contained gradient or idle loop at most unless the prompt is

effect-led.

• Demonstrate the claim with a believable artifact; do not only assert "fast",

"easy", or "trusted".

• Avoid stuffing too many feature points into one short scene.
• Replace empty cards with screenshot detail, mini UI rows, product thumbnails,

feature labels, metric chips, or branded placeholders with clear meaning.

• Use supporting chips or callouts only when they clarify the feature or offer.
• If the scene feels crowded, simplify the offer, enlarge the hero, or merge

support details before adding more product chrome.

• Keep the final frame strong enough to work as a static product graphic.

Common Failure Modes

• Looks like a generic ad rather than the user's product.
• Claim is not backed by a visible product proof.
• Too much copy appears too fast.
• Effects compete with the product.
• Final frame lacks a clear offer or feature focus.
• Product surface is too small, blank, or abstract to identify.
• Empty cards and decorative accents make the scene feel template-like.
• Believable-looking UI detail is dense but does not explain the product.

Acceptance Checks

• Product/feature is unmistakably the hero.
• Claim, product proof, and final message agree.
• The scene includes product-specific visual information, not only generic

containers.

• Product/content detail is coherent and readable without becoming crowded.
• Copy is readable and not overcrowded.
• Final frame works as a poster frame.
• Motion feels polished, not like a template dump.

Recipe: Starter Projects

Use when the user wants to start from a type of animation rather than provide a specific scene. Starters are briefs and defaults, not prebuilt JSON templates.

User-Language Aliases

• "start a project for X", "make me a template", "give me a starting point"
• "create a reusable animation pack", "make a launch animation from scratch"

Starter Types

• brand-logo-pack: transparent logo reveal, optional short/long variants.
• kinetic-title-card: full-frame typography with slotted background/accent.
• broadcast-lower-third: reusable transparent overlay with name/title slots.
• product-ui-feedback: compact UI success/error/loading microinteractions.
• icon-loader-set: small transparent loopable icons and loaders.
• svg-illustration-reveal: SVG-derived vector reveal with compatibility pass.
• product-launch-card: feature/product announcement with title, media, accent.
• diagram-explainer: technical line trace with labels and callouts.
• data-stat-card: KPI/stat/chart scene with count-up and direct labels.
• brand-card-system: reusable layout skeleton, type system, and accent rule.
• parallax-scene: layered pan/zoom or camera-follow composition.
• ambient-field: two-tone background from one anchor plus one derived field.
• generative-loader: one repeated primitive with phase offsets and clean loop.
• effects-led-promo: title/product scene with glow, glass, sweep, or burst.

Briefing Defaults

If the user does not provide details, choose sensible defaults:

• Canvas: 512x512 for icons/logos/loaders, 1920x1080 for broadcast/title/promo

work, or match the source SVG/viewBox when supplied.

• Frame rate: 60 fps.
• Duration: 60-120 frames for compact work, 120-180 frames for title/promo/story

work.

• Background: transparent for reusable overlays/assets, slotted background for

full-frame compositions.

• Controls: expose only values the user is likely to edit.

Ask Only When Needed

• Ask for exact copy/assets if the starter cannot be meaningful without them.
• Ask intended placement/platform only when size/background policy is unclear.
• Ask whether the starter should include an exit animation for overlays.

Acceptance Checks

• The starter produces a concrete scene direction, not a generic list of ideas.
• The selected primary recipe is clear before JSON authoring starts.
• The background policy and output size match the intended use.
• Any starter with stats, charts, loops, particles, or fields has a Skottie-safe

construction plan before authoring.

Recipe: SVG Animation

Use for generic "animate this SVG", SVG-to-Lottie, vector illustration reveals, and SVG assets that are not clearly logo/icon/UI/lower-third/product/diagram work.

Always read svg-compatibility.md with this recipe.

User-Language Aliases

• "turn this SVG into Lottie", "animate this vector", "SVG reveal"
• "make this illustration move", "draw this SVG", "bring this SVG to life"

Defaults

• Keep output transparent unless the SVG is clearly a full-frame illustration or

the user requests a background.

• Preserve the source composition and viewBox.
• Animate meaningful structure: groups, paths, strokes, accents, labels, or

visual flow.

• Route technical diagrams, product promos, and effect-led requests to their

specific recipes when those are the main deliverable.

Presets

• path-draw: strokes draw on with trim paths, then settle/fill.
• layer-unfold: grouped elements reveal in depth or reading order.
• fill-sweep: solid regions receive a directional color or opacity reveal.
• illustration-drift: tiny grouped parallax/position motion after reveal.
• morph-lite: small shape/position changes, only when source paths are safe.

Timing And Easing

• Simple SVG/icon: 45-90 frames.
• Complex illustration: 90-180 frames.
• Use trim-path pacing based on perceived length, not raw segment count.
• Use calm ease-out for assembly and avoid morphing unless geometry is safe.

Ask Only When Needed

• Ask what part should move if the SVG is complex and no intent is given.
• Ask transparent vs full-frame only when source framing is ambiguous.
• Ask whether exact final fidelity matters if the prompt invites creative

transformation.

Construction Notes

• Inspect groups and paths before deciding animation units.
• Resolve SVG styling and transforms enough that Lottie output is predictable.
• Use masks/reveals for complex filled shapes; use trim paths for clean strokes.
• Avoid path morphing unless paths have compatible vertex structure.
• Expose slots for accent color, background color when used, and optional scale

or emphasis controls when useful.

Common Failure Modes

• Final frame no longer matches the source.
• Hidden CSS styling disappears after conversion.
• Fill rules or masks break holes/intersections.
• Arbitrary path fragments move without a readable idea.

Acceptance Checks

• Final frame matches the SVG source visually unless creative change was asked.
• No holes, clips, masks, gradients, or intersections break in Skottie.
• The animation has a clear reading order or reveal logic.
• Transparent/full-frame background policy is intentional.

Recipe: Typography Animation

Use for titles, title cards, quotes, kinetic typography, text reveals, captions, handwritten/path reveals, text morphs, counters, and short message-led scenes.

User-Language Aliases

• "animate this headline", "make a title card", "kinetic type", "quote reveal"
• "handwritten text", "draw this word on", "typewriter", "morph this text"
• "add text for X", "caption this", "animated number/stat"

Defaults

• Ask for exact copy only if missing.
• Default to transparent background for overlay/title elements; use a slotted

background for full-frame title cards.

• Prefer readable hierarchy over novelty.
• Establish type hierarchy, line composition, and final-frame balance before

adding accents or effects.

• Choose the type voice deliberately: serif for human/editorial authority,

grotesque for product/function, monospace for technical labels, expressive display type when the word itself is the subject.

• Convert fixed prompt text to vector/shape artwork immediately. In the current

player, native Lottie text and text slots render reliably only when matching font blobs are supplied to Skottie, and the scene loader does not pass font files by default.

Category Distinctions

• Title card: strong final still, clear hierarchy, restrained reveal.
• Quote reveal: reading pace, line rhythm, attribution after the main idea.
• Editorial text reveal: polished line breaks, masks, layout, and negative

space.

• Handwritten/path reveal: natural stroke order, trim timing, and ink hold.
• Kinetic typography: type-driven choreography tied to meaning, not only a text

entrance.

• Text morph: compatible paths only; otherwise use mask, crossfade, replacement,

or layout change.

• Text-on-path or camera-follow text: typography remains primary; use camera

scene motion as secondary only when framing movement is requested.

Typography Roles

• Anchor text stabilizes the composition and may stay still or move subtly.
• Support text provides context and should usually be calmer than the main

phrase.

• Active text carries the main motion idea. For kinetic typography, choose at

least one active word or phrase before authoring.

Kinetic Quality Bar

• For "kinetic typography", animate at least one major word or phrase with

meaning-driven position, scale, masking, layout change, framing/camera movement, rhythmic timing, or emphasis.

• Slide, fade, scale, and stagger are valid tools, but uniform entrance motion

applied to every word is not enough for kinetic typography.

• Preserve readability. Kinetic type needs contrast between active motion and

stillness; not every word should compete for attention.

• Let semantic words influence motion: fall drops, rise lifts, snap hits

sharply, break separates, flow travels smoothly, soft eases gently, heavy lands with weight, loud expands or hits harder, quiet recedes, fast compresses timing, and slow holds longer.

Presets

• title-clean: restrained title reveal with strong final still.
• editorial-reveal: calm mask reveal, line rhythm, slight position settle.
• quote-lift: quote enters by line, attribution follows after a readable beat.
• kinetic-word-choreography: one active word drives layout, scale, or rhythm.
• kinetic-snap: semantic active word hits sharply, support text stays calmer.
• statement-mask: line-by-line mask reveal with strong still-frame hierarchy.
• word-per-beat: one word or phrase owns each beat, then resolves to a held

lockup.

• typewriter-clean: stepped character/word reveal with a soft cursor/accent.
• handwritten-trace: path reveal following writing direction, subtle ink hold.
• text-morph-lite: crossfade/mask/position replacement unless paths are safe.
• text-path-follow: text follows a curve or camera-framed path while readable.
• numeric-pop: numbers scale or count in, supporting labels settle softly.

Timing And Easing

• Short title/card: 60-120 frames.
• Longer quote: 90-180 frames.
• Typewriter/handwritten: pace by readability, not constant path length alone.
• Use ease-out for entrances, stepped timing for typewriter, and low overshoot

only for kinetic/playful styles.

• Kinetic typography: build around phrase-level beats; active words can move

more strongly while anchor/support text holds the composition.

Ask Only When Needed

• Ask for exact text if absent.
• Ask for brand/font constraints when source context is missing and typography is

central.

• Ask whether output should be full-frame or transparent if ambiguous.

Construction Notes

• Break text into semantic lines, words, or glyph groups based on the preset.
• Keep line lengths short enough for the canvas and target use.
• Keep one focal line or phrase dominant; support text should clarify rather

than compete.

• Use masks or shape reveals for premium title work; use opacity/position

stagger for simpler captions.

• Use per-line mask reveals and meaning-based line breaks for statement/title

work. Avoid random per-letter motion unless the prompt asks for it.

• For kinetic typography, define anchor, support, and active text roles before

keyframing.

• Avoid applying the same opacity/position/scale entrance to every word. Offset

properties and timing according to meaning, reading order, and emphasis.

• Use lines, dots, dividers, glows, and ornaments only when they guide reading

order, reveal text, emphasize a word, support rhythm, or reinforce semantic motion.

• Use path morphing only with compatible path structures; otherwise use

replacement, reveal, or crossfade.

• Expose useful slots: text content when supported, accent color, background

color for full-frame cards, and timing/scale only when user editing matters.

• Use native text slots only when editable text is explicitly required and font

asset loading has been implemented and verified in the official player.

Common Failure Modes

• Text becomes unreadable mid-animation.
• Line breaks feel accidental.
• The final frame is visually weaker than the motion.
• Handwritten reveals move against the natural stroke direction.
• Text morphs warp because path structures are incompatible.
• Kinetic typography is only a uniform word-by-word entrance.
• Every word moves equally, so no active phrase leads the viewer.
• Decorative accents fill space but do not guide reading or meaning.
• Type accents or effects arrive before the hierarchy and line breaks are

resolved.

• Typeface choice does not match the message tone.

Acceptance Checks

• First and final frames are clean still compositions.
• Text is readable at all inspected frames.
• Staggering supports meaning instead of making words hard to follow.
• Kinetic prompts have an active word or phrase with semantic, type-driven

motion.

• Anchor/support text stabilizes the composition and does not compete with the

active phrase.

• Accents support reading rhythm, reveal, emphasis, or semantic motion.
• Type hierarchy, line breaks, and optical placement pass before effects are

considered polish.

• If type is the subject, each major beat is readable as a strong still frame.
• No text touches unsafe edges or clips during motion.

Recipe: UI Microinteractions

Use for button states, toggles, feedback ticks, hover/click affordances, notifications, progress states, onboarding hints, empty-state feedback, and compact product UI motion.

User-Language Aliases

• "button press", "hover animation", "toggle switch", "tap feedback"
• "toast notification", "progress bar", "confirmation feedback"
• "empty state motion", "form success", "small UI interaction"

Defaults

• Short, responsive motion.
• Preserve the user's UI style if source context exists.
• Use subtle distances and clear state changes.
• Make the state change the climax. Everything before it is setup; everything

after it is confirmation.

• Believability comes from coherent state, not dense UI detail.
• Transparent background unless demonstrating a full component card.

Presets

• soft-confirm: success tick or status icon draws and settles.
• toggle-shift: knob slides with color/opacity state change.
• button-press: scale/brightness press and quick release.
• notification-pop: small card/icon enters, holds, exits.
• progress-fill: determinate bar/ring fill with readable easing.
• empty-nudge: small illustration or icon prompts action without noise.

Timing And Easing

• Press/hover feedback: 8-18 frames.
• Toggle/progress/state transition: 18-45 frames.
• Notification enter/exit: 30-75 frames.
• Use low-distance ease-out. Avoid large overshoot in functional UI.

Ask Only When Needed

• Ask for the UI state pair if not clear.
• Ask whether the animation is one-shot, reversible, or looped if ambiguous.
• Ask for exact label/copy only when text appears in the animation.

Construction Notes

• Keep state transitions reversible when practical.
• Use consistent timing across related states.
• When one value drives multiple properties, keep them synchronized: handle

position, fill amount, color, label, and dash style should agree.

• Expose slots for accent color, label text, and progress value when useful.
• Avoid large brand-intro motion in functional UI contexts.

Common Failure Modes

• Animation feels slow after a user action.
• Motion is too large for the component's size.
• State change is unclear without reading surrounding UI.
• Active state, label, and geometry disagree.
• Final state does not align to the component geometry.

Acceptance Checks

• Motion communicates the state change immediately.
• UI state is coherent and readable without extra surrounding context.
• No element jumps, clips, or overshoots awkwardly.
• The animation still reads when viewed small.
• Timing feels responsive at 60 fps.