---
name: code-directed-animation
description: Create and revise code-driven animations for tutorials, product demonstrations, CRO proposals, marketing creatives, and explainers. Use for editable HTML/CSS/SVG or canvas scenes, deterministic video rendering, and synchronized optional narration, music, and interaction sound effects. Includes a reusable brand-neutral starter project when no animation framework exists.
---

# Code-directed animation

Turn a specific viewer need into a fluent, legible visual sequence. Build editable scenes with HTML/CSS/SVG, canvas, or an existing animation framework; use supplied imagery, footage, and audio where they serve the story. Prefer the native browser approach for UI, typography, diagrams, and precise interactions when no framework is established.

## Start with intent and evidence

Identify audience, desired understanding/action, placement, aspect ratio, duration, language, brand, references, and delivery format. Infer routine choices from the request; ask only for missing decisions that materially affect the result. Do not assume every video is a tutorial or every brand is Levely.

Choose the story around its purpose:

Treat CRO demonstrations and performance ads as separate deliverables. For CRO, reconstruct the observed web UI, preserve a baseline, and demonstrate a specific proposed improvement with a testable hypothesis. For an ad, take the product and build an attention-to-benefit-to-CTA animation appropriate to its placement; ecommerce chrome is optional and should appear only when the brief calls for it. When both are requested, create separate storyboards, sources, previews, and exports. A page-to-product transition alone does not demonstrate a CRO improvement.

| Purpose | What the sequence needs to demonstrate |
| --- | --- |
| Tutorial | Explain → allow reading → perform action → show result. Preserve prerequisites and causal order. |
| CRO proposal | Observed friction → proposed change → resulting interaction. Label the proposal and state the testable hypothesis. |
| Performance creative | Recognizable need → product mechanism or demonstration → supported benefit → relevant call to action. |
| Concept illustration | Establish objects → show their relationship changing → hold the resulting explanation. |

For an existing site, use [browser reconstruction](references/browser-reconstruction.md). Record what was observed, inferred, and proposed. For factual claims and instructional commands, check the relevant current source before publication. A recreated screen is not evidence that a workflow was executed or a conversion improvement measured.

Present a timed storyboard before writing new animation code: scene purpose, composition/state, on-screen copy, action, narration, transition, and duration. The originating user asked to review storyboards before building; honor that preference unless the current request already approves the direction or explicitly asks to proceed. Continue reference analysis and preparation while awaiting any required creative decision. Revisions within an approved direction do not need repeated approval.

## Visual and motion direction

- Give each beat one primary focus. Align typography, visual demonstration, pointer, and narration around it.
- Reproduce the details that make an interface recognizable: typography, spacing, window chrome, icons, active states, scrolling, and input behavior. Use source assets when available.
- Keep explanatory copy in a stable readable area with intentional whitespace. Use boxes where they have a functional role; avoid wrapping every label in a panel.
- Keep moving image bounds—including opaque image padding—clear of visible text and CTAs. Check entry, hold, and exit frames; reposition or resize the image, or finish fading the copy before its path crosses the text area.
- Use brand accents semantically: an action, selection, or changed feature. Keep interface status colors understandable.
- Prefer clear, natural, direct language. For Spanish, write idiomatic instructions. Avoid exaggerated promises and unnecessary negative comparisons. Keep long commands in the demonstrated interface; describe their purpose in surrounding copy.
- Animate cause and effect: pointer approaches a control, presses it, then the state changes. Show window closing, confirmation, navigation, and prerequisite steps when they matter to comprehension.
- Separate human action from system waiting. Make input and selection readable; compress passive waits and label acceleration when elapsed time matters.
- Coordinate movement through a small easing vocabulary, gentle stagger, and clear settling periods. Camera movement directs attention; it must preserve readable text and context. Background drift, blur, grain, and bounce are optional treatments.
- Maintain continuity between states. A cut is useful when it clearly marks a new context; use continuous transitions where they help the viewer follow a change.

For concrete techniques and export checks, read [production](references/production.md). For the evidence behind these preferences and the optional Levely palette, read [session lessons](references/session-lessons.md).

When starting a new browser-rendered project with no established framework, copy [the starter project](assets/starter/) into the new workspace and read its README. Its example interface is a disposable demonstration of the timeline contract, not a mandated visual style. Adapt composition, duration, format, typography, and actions to the approved storyboard. If a project already has a renderer, adapt the same timeline and cue principles rather than replacing working code with the starter.

For performance ads, read [performance creative](references/performance-ads.md) to develop the buyer situation, visual hook, contextual asset plan and purposeful motion. Connect product identity with relevant use, texture or outcome imagery when the concept needs it. A visually attractive sequence still needs an intelligible product, benefit, and next action.

## Build and verify

Use one explicit timeline for scene state, instructions, action cues, camera, and audio. Rendering the same timestamp must yield the same frame, including after seeking backward. Keep brand tokens, content, timing, and drawing logic separate enough to revise independently. Export a cue manifest from the visual timeline so text edits and revised durations do not leave audio on stale timestamps.

Review representative stills and the actual motion at risky transitions. Inspect every scene, longest text, command wrapping, overlaps, pointer targeting, and the final encoded output. Check the intended viewing size. Recompose for vertical/square output instead of cropping essential content. Fix identified problems, then stop optional testing when the deliverable is sufficiently verified.

For requested narration, music, or sound effects, read [audio production](references/audio.md). If using ElevenLabs, use the installed `elevenlabs-creator` and `elevenlabs-usage` skills when available. Prepare prompts, scripts, cues, costs, and paths locally first; obtain explicit approval before each chargeable batch. Use existing or locally made clips when appropriate. Audio is optional; preserve a useful silent picture master with appropriate on-screen information.

Deliver editable source, a preview, the requested export, and a short account of what was verified and what remains simulated or proposed. Include captions and audio when requested. Keep the approved final export obvious and move older renders into a clearly named archive without deleting source assets or breaking render paths. For multiple marketing variants, identify the changed hook, message, demonstration, or CTA so the comparison remains interpretable.

## Portability

Use this folder as ordinary skill instructions in any compatible harness. Resolve resources relative to this file. Browser inspection may use Playwright, a browser connector, or another available automation tool; obey that tool's access rules. Rendering may use a local browser and FFmpeg or the project's existing renderer. Do not hard-code a model, tool namespace, home directory, credentials, or a particular harness's approval mechanism.

If a capability is missing, complete the independent work and state the specific missing dependency. Screenshot references can support a recreation when live inspection is unavailable; describe the resulting fidelity limit. Narration generation requires the audio provider capability and its applicable approval, even when visual work is already authorized.