sui-motion-graphic-reel · Making Design-Driven Animation with Code
Author: Sui Yang (IG @asksui.ai). This skill was distilled from seven rounds of revision on a 15-second animation: each principle behind it is backed by a rejected version. Compare images in
examples/, and the full revision history inreferences/case-0099.md.
In one sentence: Nine-tenths of a good animation depends on the design language and camera set before you start, not on how many effects you use. This skill controls "how to think, how to tell an AI, and how to review yourself"—regardless of which engine you use.
The pipeline: Find a design system (§1: use the user's if available; if not, have a design agent produce options for the user to choose) → Script & audio (§2) → Show storyboard to the user (§3) → Lock design language, build scene by scene (§4 with nine principles) → Pre-render review (§5) → Self-review after rendering (§6) → Delivery and revision (§7).
Two separate things (the most important design of this skill):
| Lives where | Can be changed? | |
|---|---|---|
| Taste: colors, gradients, fonts, speech pace, characters | Design system (references/design-system.md, one per project) | The user decides. The examples in the design system are just starters; the whole thing can be swapped. |
| Craft: unified look, different technique per scene, multiple layers, camera motion, one focus per beat, self-review | This SKILL.md §§4–6 | Unrelated to taste; holds true for any style. |
When a rule conflicts with the user's preferred style: Taste follows the user; craft follows the principles. Example: If the user wants neon gradients — fine, then the entire reel uses that single neon language (craft: unified look), not a neon first scene and a Swiss grid second scene.
1. Start by Finding the Design System
Without a design system (colors, fonts, layout skeleton, signature elements, motion personality, a "don't" list), the AI will fall back to its defaults: purple-pink gradients, glow, fade-in + scale-up per scene. So the first step is always this, and find first, then ask, finally create yourself.
Existing design system?
├─ Yes → Use the user's (1A)
└─ No → User answers a few questions, or provides references (1B) → Design agent goes to work, produces a few options for the user to choose (1C) → User picks one → Use that
1A. Look First: Does the User Have Their Own
- Search the project:
design-system.md, brand guidelines, design tokens, CSS variables from the website, Figma exports, logos, previously created images or videos. - If nothing found, ask: "Do you have an existing design system or brand guide? If so, send it over, and I'll work from it."
- Yes → Use the user's. Transcribe it into the project's
design-system.md(fields are inreferences/design-system.md). Don't change anything that's already defined. For fields the design system lacks that the reel needs (motion personality, signature elements, platform safe zones), supply them, marking each addition as "AI-supplied" and ask the user to confirm.
1B. No Design System: User Answers Questions or Provides References
Two paths—walk one or both:
- Questions: Ask all at once, max four questions, each with options.
- Mood: Calm & premium / Lively / Techy / Handcrafted / User describes
- Color: Any must-use colors? If not, pick just one accent color.
- Character or mascot needed? Voiceover needed?
- Who is this for, and on which platform?
- References: An inspiring video, website, poster, or brand. For each reference, ask "What do you like about it?" Learn its language (color, grid, typography, motion style), not its exact imagery.
1C. Design Agent at Work: Produce Options for the User to Choose
Pass the answers and references from 1B to a separate agent (design agent). It does only one thing: produce design system proposals. The brief and return format are in references/design-agent.md.
- Produce 3 options that are clearly different (not the same system with a swapped accent color).
- Each option comes with a real rendered sample: all three options use the same title and same content, laid out side-by-side in a single image. The user chooses with their eyes, not by reading hex codes.
- The user can pick one option or mix-and-match ("A's colors with B's typography"). If they dislike all, ask what's wrong and produce another round.
- The chosen option is written into the project's
design-system.md. Every subsequent scene uses only items from this file; to add a color, font, or technique, first modify this file.
Why a separate agent? The agent building the reel already has the script and visuals in its mind; if it creates the proposals, all three will look very similar. A separate agent, looking only at the requirements and references, produces more divergent directions. If you can't spawn a second agent in your environment, follow the same brief yourself—still deliver three options with samples.
When the User Is Not Present
Scheduled jobs, night shifts, or the user says "you decide": don't stall. The design agent still produces three options; pick the one that best fits the requirements, mark it as "AI-chosen" in the design-system.md, attach the other two option samples, and ask the user to confirm or swap upon delivery.
Fields and four examples are in references/design-system.md.
2. Script and Audio: Audio First
- Write the script as a spoken monologue, connected with conversational phrases ("You see," "and also," "plus"). Not a list of bullet points. It should sound like talking to a friend, not reading taglines.
- Generate the entire voiceover in one pass, not sentence by sentence and then stitched together. Individually generated sentences sound like slogans; stitched together, they lack natural tone. Get a per-word timestamp (most TTS services provide this via timestamped APIs).
- Visuals follow the words: Each element arrives exactly at the moment its corresponding word is spoken. The total runtime = voiceover length + closing; don't pad to an even second. For actions, too: When the script says "the camera swoops in," the swoop should happen exactly at that word. If the action finishes before the word, the viewer sees a still image while hearing a description of motion. Print and align timestamps, don't guess.
- Don't insert silence in the voiceover to wait for visuals. If the visuals can't finish in time, simplify the visuals.
- For videos without voiceover, first write a beat sheet (what happens at each second), then build the visuals to match.
- After exporting, run speech-to-text on the final audio to confirm every line is intact and no half-sentence was cut off (a clipped voiceover is invisible in the visuals).
How to source voiceover and licensing concerns: references/engines.md "Voiceover."
3. Show Storyboard First, Then Animate
Finding out the direction is wrong after animation is the most expensive revision. Before starting animation, produce a storyboard table, one row per beat:
| Field | What to Write |
|---|---|
| Time / Spoken Words | From second X to second Y, which words are voiced |
| Focus | What the viewer's eyes should look at (only one thing per beat) |
| Four layers | Background · Midground/Character · Foreground · Info layer content (see §4 Principle 4) |
| Technique | Which animation technique this scene uses (§4 Principle 2); must differ from the previous scene |
| Camera | Camera path and movement |
| Rhythm | Dense or sparse? Bright or dark? (§4 Principle 9). After completing the table, read this column alone. |
| Transition to next beat | Which transition method |
If possible, draw one static keyframe per beat (using the design system's style), assemble them into a contact sheet for the user to review. Do not start animation until the user approves.
When the user is not present: still create and save the storyboard, check it against §4, then start. Include the storyboard with delivery.
4. Nine Principles
Each principle includes "why" and "what it looks like when done wrong." Names and descriptions of techniques are in references/techniques.md.
① Lock a Design Language, Use It for the Entire Reel
Before starting, freeze these items into a shared file (tokens) that every scene references: Color palette · Grid and safe zones · Fonts and typographic hierarchy · Title block positioning · A single "signature element" running through the whole film (e.g., Example A uses design tool annotations — selection handles, keyframe tracks, shape name labels — revealing the craft).
- Why: Viewers can't pinpoint what's off, but they can instantly tell "these scenes don't belong to the same film." Unity is the cheapest source of "premium feel."
- Wrong look: Only the criticized scene is fixed, while others keep their own colors (compare
examples/v3-only-first-scene-fixed.jpgvsexamples/v4-unified.jpg). Fix one scene, align the entire reel.
② Use a Different Technique per Scene, Not a Different Color Scheme
Richness comes from "how each scene moves," not from swapping colors. Alternate techniques across the film:
| Subject | Technique |
|---|---|
| Large text | Spring deformation (squash on landing, stretch on bounce) |
| Pixel / retro | Frame-by-frame jump, integer-pixel motion, no smooth interpolation |
| Particles | Physics simulation or flow field, scatter then coalesce |
| Handwriting | Follow real brush strokes, stroke by stroke |
| Interface / screen | 3D perspective; panels staggered along depth; camera orbits around |
| Numbers | Rolling counter, squashing at each increment |
- Wrong look: Every scene is just "fade in + scale up." Multiple scenes but only one motion type.
③ Words Must Be Truly Kinetic
When large text is the star, it must have weight: stretch as it drops, squash on landing, bounce back, stagger per character, stretch on entry, compress to a line on exit. Formulas and code examples in references/techniques.md "Text."
- Wrong look: Text only fades in or is pushed up by a mask.
④ Four Layers per Scene, One Focus at a Time
| Layer | What It Does |
|---|---|
| Background | Animated environment sets the scene; dark and slow |
| Midground | Only focus: the star or main object; clear, large, at center |
| Foreground | Objects passing just in front of the camera, creating depth |
| Info layer | Labels, counters, small UI, subtitles |
Many things can move simultaneously, but only one thing can be brightest, sharpest, and fastest-moving. Richness comes from the number of layers, not from competing focal points.
- When things stop: The subject (focus and readable text) must be completely still for the viewer to read, while the background and surroundings keep moving slowly: floating markers in the background, large background text, foreground objects at the edges of the frame, the character's subtle breathing. If everything stops, the frame is dead. Put motion outside the subject, never crossing over readable text.
- Layers must overlap front-to-back, not just top-to-bottom: The background sits behind the subject; the foreground sits in front of the subject's edge. Placing "background" and "foreground" into the empty space below the subject is just adding two more items, not creating depth; plus, the lower area of vertical video is often covered by platform UI.
- Wrong look: A single card on a solid color background (missing three layers, feels "dry"); or four things flashing simultaneously (no focus, feels "chaotic").
⑤ The Camera Must Move
Place everything in a single world (a canvas larger than the screen, or a 3D space), and have the camera navigate through it instead of cutting to a new scene.
- Opening: The camera flies in from a distance, passes through a few foreground layers, and the subject only acts at the moment it comes to rest.
- Two waves in the first 4 seconds: First wave: a large camera displacement (0–1s); a second wave at 1.5s (another camera move, a shift to a different area, or the text undergoes a major deformation). A single fly-in that stops is just a 1-second opening.
- Scene changes: The camera moves to a different area of the world. The three depth layers (far/mid/near) move at different speeds (parallax). Apply motion blur on fast-moving frames (but not to subtitles).
- Quiet-paced films still need a second wave, just in a different form: it could be a large deformation of the text (stretch, squash), a line sweeping through to bring in the next text block, or an action by the main object. "Slow" means a gentle easing curve, not stillness.
- When the camera moves, recheck safe zones: After a push-in or pan, small text that was within safe zones may be pushed outside. Export full-resolution frames at those moments to inspect the edges.
- Wrong look: The opening is a static image; scene changes are simple fades between full-screen images.
⑥ Use Real 3D for 3D
For 3D camera moves, build a real 3D scene with a real perspective camera (e.g., three.js): arc around the objects, with acceleration/deceleration, showing the sides of objects. Particles must have volume, depth blur, and trails.
- Wrong look: Zooming into a 2D image and calling it "push-in"; faking 3D with a few CSS cubes (missing faces, incorrect depth sorting—breaks on rotation); particles just being points on a plane.
- Real 3D segments must be checked frame by frame at full resolution (§6). 3D is the most prone to breaking while being hardest to spot in scaled-down thumbnails.
⑦ Transitions Are a Visual Attraction
Beyond camera flow, transitions between segments can use: Tunnel (camera pushes into an object in the current scene and emerges into the next) · Mask (the next scene reveals through a letterform or shape, or an iris open) · Match cut on shape (the end point of one scene's shape is the starting point of the next scene's pen tip) · Pull-back reveal (the previous scene was just one tiny screen among many).
- Place transitions in the breathing space between spoken sentences.
- For each transition, grab a few frames and check for breaks or jumps (
examples/v4-transitions.jpg).
⑧ Every Visual Is Calculated from the Frame Number
No matter which engine, export is generated frame by frame. Therefore, every position, size, and transparency must be a function of the frame number: given frame 137, it produces frame 137. Never use anything that runs on its own time (CSS animations / transitions, independent timers, the engine's own animation loop) — they won't align with frame captures and will cause flickers, jumps, or missing elements.
- Benefit: Any scene can be placed into a transition thumbnail, or into a recap at the end of the film and still animate, because it's simply given a different frame number.
- Data that requires computation time (text sampling points, particle target positions, character pixels) should be pre-computed and saved, not computed during export.
⑨ Score the Rhythm Like Music: Alternate Density and Brightness
If the entire film has the same density and the same background color, every beat may look fine in isolation, but together they quickly become monotonous. Treat the film as a musical composition: mix dense and sparse, dark and bright. Plan where to push up and where to pull back before you start.
- Write a rhythm score: In the storyboard, mark each beat with two ratings: dense / sparse and dark / bright. Read the sequence aloud: "dense-dense-sparse, dense-dense-sparse, dense" is right; four or five consecutive "dense, dark" beats need a sparse beat or a brightness change in between.
- Sparse = only one thing on screen: a phone, a single large word, a number, surrounded by blank space. A fast-cut montage is not sparse—it's the densest part of the film.
- A dense beat can start sparse, then get dense: present only the title first, then bring in other elements at the key word.
- Brightness change through swapping the background color: If the design system has more than one background color, swapping the entire beat's background is the most direct way to create contrast. Swap the full screen, not leaving a sliver of the old color.
- The most intense color is for a flash only: Filling the entire frame with the accent color for a quick swipe or overlay (about one second) is powerful; using it as a working background for an entire beat with readable text is visually harsh.
- Wrong look: Every beat is "the same background + large title + a box in the center"; or the first sparse beat appears only at the very end.
- How to self-check: Display all pause frames tiny in a single row, cover the text. If you can see distinct paragraphs and variations in brightness, the rhythm is good.
5. Pre-Render Review: Catch Issues Before Exporting
Rendering an entire film is slow. Most of the issues users will flag are visible before export, from just a few static screenshots. So after finishing the visuals, don't go straight to export. Pass through three layers, cheapest first:
| Layer | What It Checks | Catches |
|---|---|---|
| ① Paper review | Check storyboard against the review-habits file line by line | Repeated scene techniques, missing layers, more than one focus, no second wave in opening, drifting from the spoken message |
| ② Machine measurement | Grab a few static frames, run scripts/preflight.py | Text out of safe zones, two frames nearly identical, segments that should move but don't, empty frames |
| ③ Review agent | Another agent inspects only static frames against the review-habits file, acting as the user's eyes | Whether the subject is recognizable, whether it looks tacky, dry, broken objects, visual unity |
- Review-habits file (
review-habits.md) is the core of this step: it records every issue the user has pointed out in previous review sessions. First check if the project has one; if not, check if the user has one; if neither, copy the starter items fromreferences/review-habits.md. - Every time the user notes a flaw, log it back into the file. When logging, ask: "Could this have been caught before rendering?" If yes, record how. Over time, this file will become a close proxy for the user's eye.
- Pass all three layers before rendering. Do not render if a required fix from any layer is not addressed.
- These layers won't catch audio or continuous playback feel; those are for §6.
How each layer works and the review agent's brief: references/pre-render-review.md. Review-habits file format, starter items, and how it grows: references/review-habits.md.
6. Self-Review Before Delivery (Mandatory, Don't Wait for the User)
Don't say "it's done" the moment rendering finishes. Systematically go through the following steps, writing down what you saw and what you changed:
- Contact sheet: Every 0.5 seconds as a frame, review overall rhythm and whether each frame is readable.
python3 scripts/review.py sheet <exported_video> - Enlarged pause frames: At the moment each beat's subject comes to rest, extract and inspect the frame at full resolution. The shrunken contact sheet won't reveal text clipping, broken characters, or layer stacking errors.
python3 scripts/review.py frames <exported_video> 1.2 4.5 7.0 … - Dense burst on moving segments: Transitions, 3D camera moves, particles—every 0.1–0.2 seconds.
python3 scripts/review.py burst <exported_video> <start_sec> <end_sec> - Scan for freezes: Are there segments where nothing moves for more than 1 second? (Common cause: an element freezes the entire scene.)
python3 scripts/review.py freeze <exported_video> - Transcription: Run speech-to-text on the exported video's audio and cross-check against the script.
- Check against design system: Does any scene use colors, fonts, or techniques outside the design system?
- Compare with previous version: Is this version better than the last? If it's just "different" instead of "better," state that explicitly.
Per frame, ask:
- What is the focus of this frame? Can you identify it within one second?
- Is the text large enough? Blurry? Touching edges? Overlapped by another element?
- Are all four layers present? Name them: background, foreground, info layer items. If you can only name the subject, it's too thin. Compare density against any frame from
examples/v7-near-final.jpg. - Is the technique of this scene different from the previous one?
- Are there any items from the design system's "don't" list?
- Are two things doing the same action simultaneously?
Self-review tools can also mislead: a contact sheet where every frame is fine doesn't guarantee there are no freezes (need a separate scan); sampled frames being fine doesn't guarantee the motion is smooth (need dense bursts for 3D and transitions); speech-to-text may mishear homophones or brand names (that's a transcription issue, not a reason to change the audio).
Allow a maximum of three self-review rounds. A round = one full export + all seven steps above completed. Single-screenshot checks before export don't count as a round. For any issues remaining after three rounds, list them explicitly for the user—don't hide them.
7. Delivery, and When the User Says "Not Happy"
When delivering, state three things: what this version does · what the self-review found and changed · what issues remain.
User feedback often comes as a feeling. First translate that feeling into a visual diagnosis, then fix; if you can't translate, ask instead of guessing:
| User says | Most likely cause | First check |
|---|---|---|
| Tacky / AI-ish / not premium | Design language: too many colors, gradient glow, the style itself is too distracting | §4 Principle ① and the "don't" list in design system |
| Only partly fixed / not unified | Other scenes weren't updated to match the design language | §4 Principle ① |
| Monotonous / all the same | Same technique used in every scene | §4 Principle ② |
| Cloying / no variation / exhausting to watch all at once | No variation in density or brightness: every beat equally full, one background color throughout | §4 Principle ⑨; first lay out pause frames shrunken in a row |
| Dead when paused | When the subject stops, the background and surroundings also stop completely | §4 Principle ④ "When things stop" |
| Dry / empty / no depth | Missing background, foreground, or info layer; or the subject is too small | §4 Principle ④ |
| Chaotic / don't know where to look | Too many things competing for attention simultaneously | §4 Principle ④ |
| Static / lifeless / no spatial feel | Camera didn't move, or moved too little | §4 Principle ⑤ |
| Camera move feels fake / 3D looks weird | Using 2D scale as a substitute, or the 3D object is broken | §4 Principle ⑥ |
| Text has no feeling | Text only fades in | §4 Principle ③ |
| Sounds like slogans / slow pace | Voiceover was cut into sections with gaps inserted, or speech rate is too slow | §2 |
| Text and speech don't match | Elements are not bound to word-level timestamps | §2 |
| Suffocating / too full | The subject fills the entire frame with no breathing room, or no framing | Shrink the subject, add frames, leave space for titles and annotations |
When revising, follow two rules:
- Fix one, check the whole film: Does the same issue exist in other scenes?
- Don't touch parts the user specifically said they liked. Only adjust their color and grid for alignment; keep the technique exactly as is.
After every revision round, go back and re-read the film's core message. After multiple rounds, the most common accident is that every round fixed the named problems, but the film has drifted from its original message.
Appendix: Files
| File | What It Is |
|---|---|
references/design-system.md | Design system fields + four examples (starter; can be entirely replaced) |
references/design-agent.md | Design agent's brief and return format (produce 3 design systems + samples) |
references/pre-render-review.md | How to do the pre-render review in three layers + review agent's brief |
references/review-habits.md | Review-habits file: format, starter items, how to log each user's note |
references/techniques.md | Technique glossary: name, what it looks like, how to tell the AI, common mistakes |
references/engines.md | How to connect engines (HyperFrames · Remotion · others), true 3D, voiceover, sound effects, licensing |
references/case-0099.md | Full history of a 15-second reel from v1 to v7: what was said about each version, root cause, how it was fixed |
examples/ | Contact sheets for each version of the case study (good and bad); also a test reel in a different style (see design-system.md Example C) |
scripts/preflight.py | Pre-render measurement: takes static images, outputs stitched pause frames (with safe zone markers), burst frames, reminder checklist (requires Pillow) |
scripts/review.py | Self-review script: contact sheet, full-res frame extraction, dense burst, freeze scan (requires ffmpeg; output goes to review/<exported_video_filename>/ next to the export, one folder per version for easy comparison) |