Update to Picsart
Snapshot Nov 11, 2026 · 00:08 UTC · version 2.5.0
Collection source: downloaded plugin package.
Instructions updated for motion-design-craft
Skill instructions — Now says: **When two or more could fit and it's taste, the designer picks.** Build 2–6 candidates on the real element and open them in `picsart_scene_picker` — one...
Observed in instructions or declared skills. Runtime behavior has not been tested.
Up to 3 plugins free · no card required.
All fields and original values.
Skill instructions
Nov 7, 2026 · 00:09 UTC
No removed lines (ordering may have changed)
Nov 11, 2026 · 00:08 UTC
**When two or more could fit and it's taste, the designer picks.** Build 2–6 candidates on the real element and open them in `picsart_scene_picker` — one `scenes` entry each, its document as `scene`, its `label` what the designer would c...
Supporting files
Nov 7, 2026 · 00:09 UTC
[{"relative_path":"docs/widget-specs/scene-editor.md","size_in_bytes":6578},{"relative_path":"references/ASSET-COMPOSITION.md","size_in_bytes":6194},{"relative_path":"references/AUTHORING-FLOW.md","size_in_bytes":21335},{"relative_path":...
Nov 11, 2026 · 00:08 UTC
[{"relative_path":"docs/widget-specs/scene-editor.md","size_in_bytes":6578},{"relative_path":"references/ASSET-COMPOSITION.md","size_in_bytes":6194},{"relative_path":"references/AUTHORING-FLOW.md","size_in_bytes":21335},{"relative_path":...
Compare saved observations
Download comparison JSONSKILL.md text changes
− removed · + added
--- before +++ after @@ -304,6 +304,13 @@ real element**, never as a named list of presets in prose — a designer judges motion by watching it, and a still or a word ("fade_in") approves things that are wrong. +**When two or more could fit and it's taste, the designer picks.** Build 2–6 candidates on the +real element and open them in `picsart_scene_picker` — one `scenes` entry each, its document as +`scene`, its `label` what the designer would call it ("fast word-stagger", "soft fade-up"), never +a preset id. Don't choose for them and don't describe the options in text. Carry on from the +card(s) in the reply's `selected` and say in one line which one you kept (picsart-video-rules, +*A choice made by eye*). With one clear best reading, step 0's single proposal stands. + ## Anti-patterns (the slideshow tells) - **A static first frame** — the reel holds on a frozen frame 1, then jumps into the 1→2 motion.
Full technical diff · 2 changed fields
changed /included_files
[
{
"relative_path": "docs/widget-specs/scene-editor.md",
"size_in_bytes": 6578
},
{
"relative_path": "references/ASSET-COMPOSITION.md",
"size_in_bytes": 6194
},
{
"relative_path": "references/AUTHORING-FLOW.md",
"size_in_bytes": 21335
},
{
"relative_path": "references/CHOREOGRAPHY.md",
"size_in_bytes": 5594
},
{
"relative_path": "references/COMPOSE-FUNDAMENTALS.md",
"size_in_bytes": 4483
},
{
"relative_path": "references/CRAFT-RULES.md",
"size_in_bytes": 8855
},
{
"relative_path": "references/ELEMENT-MOTION.md",
"size_in_bytes": 4679
},
{
"relative_path": "references/ENGINE-GOTCHAS.md",
"size_in_bytes": 5854
},
{
"relative_path": "references/MOTION-PATTERNS.md",
"size_in_bytes": 9577
},
{
"relative_path": "references/MOTION-PRINCIPLES.md",
"size_in_bytes": 31117
},
{
"relative_path": "references/MOTION-TROUBLESHOOTING.md",
"size_in_bytes": 10655
},
{
"relative_path": "references/SCENE-VALIDATION.md",
"size_in_bytes": 6579
},
{
"relative_path": "references/SCENE-VOCABULARY.md",
"size_in_bytes": 11726
},
{
"relative_path": "references/STUDYING-MOTION.md",
"size_in_bytes": 1479
},
{
"relative_path": "references/TOOL-ROUTING.md",
"size_in_bytes": 23846
},
{
"relative_path": "references/TRANSITIONS.md",
"size_in_bytes": 17883
},
{
"relative_path": "references/WIDGET-FEEDBACK.md",
"size_in_bytes": 4854
}
][
{
"relative_path": "docs/widget-specs/scene-editor.md",
"size_in_bytes": 6578
},
{
"relative_path": "references/ASSET-COMPOSITION.md",
"size_in_bytes": 6194
},
{
"relative_path": "references/AUTHORING-FLOW.md",
"size_in_bytes": 21335
},
{
"relative_path": "references/CHOREOGRAPHY.md",
"size_in_bytes": 5594
},
{
"relative_path": "references/COMPOSE-FUNDAMENTALS.md",
"size_in_bytes": 4483
},
{
"relative_path": "references/CRAFT-RULES.md",
"size_in_bytes": 8855
},
{
"relative_path": "references/ELEMENT-MOTION.md",
"size_in_bytes": 4679
},
{
"relative_path": "references/ENGINE-GOTCHAS.md",
"size_in_bytes": 5854
},
{
"relative_path": "references/MOTION-PATTERNS.md",
"size_in_bytes": 9569
},
{
"relative_path": "references/MOTION-PRINCIPLES.md",
"size_in_bytes": 31117
},
{
"relative_path": "references/MOTION-TROUBLESHOOTING.md",
"size_in_bytes": 10655
},
{
"relative_path": "references/SCENE-VALIDATION.md",
"size_in_bytes": 6579
},
{
"relative_path": "references/SCENE-VOCABULARY.md",
"size_in_bytes": 11726
},
{
"relative_path": "references/STUDYING-MOTION.md",
"size_in_bytes": 1479
},
{
"relative_path": "references/TOOL-ROUTING.md",
"size_in_bytes": 23846
},
{
"relative_path": "references/TRANSITIONS.md",
"size_in_bytes": 17876
},
{
"relative_path": "references/WIDGET-FEEDBACK.md",
"size_in_bytes": 4854
}
]changed /skill_md_contents
"---\nname: motion-design-craft\ndescription: The craft of adding motion to any scene, whatever the video — an ad or reel, a promo, a tutorial or walkthrough, an explainer, an intro, outro or title card, or one beat inside a longer edit — motion chosen per element by its role, smart-animate and morphs between frames, transitions, strokes and mask reveals, reviewed by eye in the scene editor pair by pair. Use whenever motion is added to or changed in a scene — elements animating in or out, a transition that looks wrong, a morph, a mask, an animated callout, highlight or zoom, a logo reveal, kinetic text — including inside another use case or a tutorial, not only in the `animate-design` skill's pipeline, where it is stage 3.\nmetadata:\n owner: motion-designer\n---\n\n# Stage 3 — authoring the motion\n\nA composed scene is a set of layered frames that render identical to the design and don't\nmove yet. This stage makes them move — and the gap between \"slideshow\" and \"ad\" lives\nentirely in the choices made here: **which elements move, how, and what carries between\nframes.** The design is authored as a scene throughout; every edit is a\n`patch_scene` that writes a new scene document (`sceneRef` moves — always edit the latest).\n\nThe rule under everything: **motion draws the eye, so it is spent, not sprayed.** A frame\nwhere everything animates at once reads as noise. Pick the focal element per beat, move\nit, let the rest support.\n\n## Motion in any scene, not only after an import\n\nThis craft is not limited to the `animate-design` pipeline. Use it wherever a scene gets motion: a\ntutorial's full-screen moments and the transitions between its parts, a promo's title card, an\nanimated callout or highlight over a screen recording, a logo reveal, a presenter bubble that grows\ninto a full frame, a morph from one clip's framing into the next. Open this skill **as soon as the\nmotion is being designed**, not after a first transition already looks wrong. Everything below\napplies; only the inputs differ:\n\n- **\"Frames\" are the two states either side of the motion.** A is the last settled state before it,\n B the first settled state after it: two beats, two parts or two layouts of the same scene. Author\n A→B pair by pair, exactly as below.\n- **No import, so tag the matched elements yourself.** An element present in both states (the same\n shape, logo, panel, bubble or recording) is matched. Diff the two states with\n `picsart_scene_diff_layouts`, passing those pairs as `matchHints`, or `picsart_scene_query_layout` on\n both, and read off the delta.\n- **Shape changes, borders, masks, camera moves and sound sync** follow *Craft for any motion*\n below; read [`references/ENGINE-GOTCHAS.md`](references/ENGINE-GOTCHAS.md) before the first mask.\n- **The motion lives in the scene that has the layers.** When the final video is a stitch of\n rendered parts, a rendered part can only cut or dissolve into the next. Author a transition that\n carries an element across the seam in the scene that still holds both sides as layers, before it\n is rendered.\n- **Recorded footage stays footage.** Animate the layers around and over a recording (its panel,\n mask, frame, callouts and text); never re-time the recording itself to fit a motion.\n- **Review still happens on the moving stretch**, in `picsart_scene_editor`, pair by pair. When\n another flow called this skill, that flow's review step is where the user approves.\n\n## Read the design before animating it\n\n**First, read what changed** — from tool facts, not by eye. Diff the pair with\n`picsart_scene_diff_layouts` (pass frame A, frame B, and the import `matchKey`s as `matchHints`);\nit classifies each layer as moved / resized / restyled / content-changed / entered / exited /\nunchanged with root-space deltas. If the tool is unavailable, fall back to `picsart_scene_query_layout`\non A *and* B and diff by hand. Either way, **check fades yourself** — the diff sees only `visible`,\nnot numeric opacity, so an opacity change reads as unchanged. **Animate only what\nchanged; leave unchanged layers still.** The full frame-diff procedure and the\nchange→motion/easing/duration/reduced-motion mapping live in\n[`references/MOTION-PRINCIPLES.md`](references/MOTION-PRINCIPLES.md).\n\nThen choose each moving element's motion by its **role**, not at random. This is the default\nmapping — a starting point the designer overrides in the panel, not a law:\n\n| Role (from import) | Default motion |\n|---|---|\n| headline / display text | **type-on**, or word/character **stagger** in |\n| body / label text | short fade + slide-up |\n| CTA / button | **scale/pop**, entering *late* (after its context), often with a tap-dot |\n| hero image | subtle **scale-in / push-in**, or a mask **reveal** |\n| list / feed | the content **scrolls**; rows **stagger** in |\n| card / panel | **slide** from the nearest edge + fade |\n| chrome (tabs, header, nav) | usually the **matched element** — persists and smart-animates; enters first, exits last |\n| icon / small accent | quick **pop**, subtle |\n| background | least motion — a slow **parallax** drift or gentle scale |\n\nThe design's own **hierarchy is the motion priority**: what the eye should hit first gets\nthe entrance; supporting elements follow.\n\n## How finely to split — respect the design's units, don't take a mark apart\n\n\"Split into pieces that move independently\" means **use the layers the design has** — not\nmanufacture finer structure inside a single element. Going finer than the design (splitting one\nvector/instance into sub-parts to animate them separately) is the same class of overreach as\ninventing a cursor or a ripple: you're adding structure the designer didn't author.\n\n**Default: animate each element as the one unit Figma authored** (one layer / instance / vector =\none unit). Sub-dividing that unit is a bigger claim — allow it **only when all three hold**:\n\n1. the sub-parts are **distinct content** — separate things — not the strokes/segments of one glyph\n or mark;\n2. the **concept calls for it** — a set, variety, or a progressive build the message depends on;\n3. it is **not the brand's identity** — a logo, wordmark, or **app icon** stays whole regardless of\n how separable its parts look.\n\n**When it's a judgment call, keep the unit whole and OFFER the split** — let the designer choose;\nnever impose decomposition. *Worked example:* an AI-Playground app icon whose mark is a square,\nsparkle, diamond and circle **fails #3** — it's the identity mark — so the open is a whole-icon\nreveal (fade/scale the tile+shapes in together), and \"the four shapes pop in one by one\" is offered\nas an option, not authored by default. Taking a brand mark apart on screen reads as *disassembling\nthe logo*, which is rarely what the designer meant.\n\n## The opening beat — frame 1 animates IN, it never just sits there\n\n**The reel opens with motion, not a frozen screen.** A static frame 1 that holds and then\nsuddenly jerks into the 1→2 transition reads as amateur — the viewer sees a still image, then a\njump. Instead, **frame 1's own elements animate in at t=0**, so the first thing on screen is the\ndesign *assembling itself*, and by the time the 1→2 motion fires the frame already feels alive.\n\n- **Entrances by role, staggered by hierarchy.** Same role×energy vocabulary as any entrance\n (`MOTION-PRINCIPLES.md`): background/chrome settle first, then the hero/headline, then the CTA\n last. What the eye should hit first enters first; siblings stagger ~0.05–0.12s, never in unison.\n- **It's an intro, not a showcase — keep it tight.** A quick, confident assemble (energy scales\n it: energetic → snappier and shorter; calm → a softer fade-up). Don't animate *everything*; a\n couple of focal entrances plus a gentle settle on the rest reads better than a busy cascade.\n- **Then hold, then transition.** Opening beat → the frame's content-derived hold (the \"no dead\n air\" rule still applies) → the 1→2 motion. The opening is a distinct beat *before* pair 1→2.\n- **Nothing is matched yet** (there's no frame before frame 1), so this beat is entrances only —\n no smart-animate, no exits.\n- **Don't manufacture parts to stagger.** A sparse open (one icon on a dark ground) tempts you to\n invent motion by taking the one element apart. Whether that's allowed is a real judgment — see\n *How finely to split* below — but the default on a brand/app icon is a **whole-icon reveal**, with\n a staggered build only **offered**, never imposed.\n- **Symmetric at the end:** the last frame shouldn't freeze-frame either — let it settle/hold on a\n deliberate final state (or a brand lockup) rather than snapping to a stop.\n\nAuthor this as frame 1's entrance animations at `t=0`, self-check it like any pair, and get it\napproved as the reel's open **before** you start pair 1→2.\n\n## Matched-element smart-animate — the technique that makes it an ad\n\nThis is the single thing that separates motion design from a slideshow. When a layer\ncarries a `matchKey` into the next frame (tagged at import), you do **not** cross-dissolve\nthe two screens — you **animate the shared layer from its state in A to its state in B**:\n\n- **Move the delta** — position, size, opacity, and content (a text string changing) from\n A→B, ~0.4–0.8s, **ease-in-out**.\n- **Keep matched layers on screen through the transition** — never fade the shared chrome;\n its staying put *is* the continuity.\n- **Elements only in A exit** (fade/slide out) as or just before the move.\n- **Elements only in B enter** *after* the matched layers have arrived, so the eye follows\n continuity into the new content rather than being asked to look everywhere at once.\n\nMiss this and shared chrome cross-dissolves — the biggest tell of \"slideshow, not ad.\"\n\n## Craft rules that make motion read as designed\n\nEasing, duration, staggering, the opening beat, holds and the rest: read\n[`CRAFT-RULES.md`](references/CRAFT-RULES.md) before you author the first pair.\n\n## Craft for any motion — continuity, containers, camera, sound, checking\n\nLearned on a narrated tutorial whose bubbles grew into full frames and shrank back; each rule fixed\na visible bug. They hold for any motion, in any scene.\n\n**Shape and continuity**\n\n- **A shape change is two copies, pixel-locked, cross-faded across the whole move.** When an\n element changes shape between states (a rectangle to a circle, a card to full screen), animate a\n copy in A's shape and a copy in B's shape together — shared position, scales derived from one\n fixed ratio — and cross-fade them over the full duration of the move. Never scale one shape into\n the other's footprint, and never do it in two steps (move, then reshape).\n- **One of each thing on screen.** While an element travels to where its destination version sits,\n hide the destination version and reveal it on landing. Two visible copies always read as a glitch.\n- **Pixel locking.** Layers that must move as one share keyframe times and derive their scales from\n one ratio, so nothing drifts against anything else mid-move. Parent them when the engine allows.\n\n**Containers, borders and masks**\n\n- **Borders follow their content.** A stroke, ring or frame fades in after its content lands and\n fades out as the content starts to move. A border fading at a fixed size while the content moves\n past it looks detached.\n- **Clip to the inner shape.** Content inside a rounded border is clipped to the border's inner\n edge — the size minus the stroke width, the radius minus half the stroke — and fills it exactly.\n Square corners or a gap at the edge give it away at once (stroke insets: `ENGINE-GOTCHAS.md`).\n- **Masks move with their layer.** An animated layer's mask carries the same transform animation, on\n the same time base. A mask is addressed through its owner (`ENGINE-GOTCHAS.md`); remember that a\n nested composition's children run on its local clock.\n\n**Camera and time**\n\n- **Move a camera, not the content.** For a push, pan or reframe, animate one parent transform and\n compute the framing from the size of the target region (the smart-animate zoom in\n `ENGINE-GOTCHAS.md`; a pure pan needs the empty \"world\" layer, since a pan-only camera does\n nothing). Every layer then stays consistent with every other. **The camera holds still while a\n caption or card is entering** — one focal move per beat.\n- **Nothing sits frozen.** A hold the content needs still gets a subtle drift — a few percent of\n scale over the hold — or ambient motion (`float`, `breathe`), so the frame stays alive without\n drawing the eye. This is not padding: the hold's length still comes from its content.\n- **Time is a design tool.** Compress what repeats, play at real speed what must be believed (a\n generation finishing, a real result), slow down what must be read. A starting speed map for\n footage: typing and waiting at 2–3×, a fast-forward through repetitive content at up to 3×, the\n payoff at 1–1.5×, and a moment the viewer must dwell on slowed to 0.3–0.5×.\n- **Procedural secondary motion.** For continuous ambient movement (sway, bob, flicker), use an\n ambient preset (`sway`, `float`, `glow_pulse`), or where none fits a small Lua expression on\n position or rotation — a sine, not hand keyframes — with amplitude, phase and period varied per\n copy so repeated elements don't move in lockstep. Expressions do not work on camera fields.\n\n**Camera on screen recordings**\n\n- **Frame a region, not a guess.** The zoom that frames a button, message or result comes from the\n region's size against the recording's fitted scale, and the position from the region's centre:\n the screen-recording-layouts skill's framing formula, which holds for any frame size. On a panel in a vertical\n promo, the screen-recording-zoom skill's house zoom sets the numbers.\n- **Push in on the payoff.** Start wide, hold a beat (~0.15 s), then push to the detail (~0.6 s on\n the house curve) so it lands just before the narrator names it.\n- **Keep what must not be seen off screen.** Cut ~0.3 s before a warning banner or error toast\n appears; frame out internal names, emails, tokens and other people's data. When a frame can't\n avoid them, cover them with a rectangle in the UI's background colour, locked to the recording's\n transform so it moves with it.\n- **Patterns** for type-on over a real screenshot, prompt cards, insets, a phone-frame pop and\n ambient depth: *Tutorial and screen-recording patterns* in\n [`references/MOTION-PATTERNS.md`](references/MOTION-PATTERNS.md).\n\n**Sound and sync**\n\n- **Motion lands on sound.** Anchor key moves and cuts to audio events: a narrated word (word times\n from `picsart_media_transcribe`), a beat or a hit (`beats` and `onsets` from\n `picsart_media_analyze_audio`). A move that lands with its sound feels intended; the same move\n 200 ms off feels sloppy. **Cut on the voice, not the picture:** over narration, every shot starts\n on a word time, so the picture changes as the narrator says the thing.\n- **Sync is local, not global.** When sound and picture drift, measure and fix each source on its\n own; one global offset fixes some sources and breaks others.\n\n**Checking**\n\n- **Check the middle, not just the ends.** Most motion bugs live mid-move: doubles, gaps, square\n corners, pops. For every move, look at frames at 25%, 50% and 75% of it — pass those times to\n `picsart_scene_contact_sheet` — and at a larger `resolution`, zoom into the edges and corners of\n those rendered frames, not only the editor's preview.\n\n## The authoring loop — pair by pair, in the panel\n\nAuthor one pair at a time (see the `animate-design` skill's pairwise rhythm). You **author** the motion\nthrough `patch_scene` / the apply tools, then open `picsart_scene_editor` **on the whole scene\nbuilt so far** (titled for the current pair) so the designer watches it play *in context* and scrubs\nto the pair — not a 2-frame sub-scene — rather than exporting a video every time; reserve\n`picsart_scene_export` for the final deliverable and the error fallback. Before each round of\npatches and each look at the frames by eye, post the one-line progress message the `animate-design` skill\ndescribes. For each pair A→B:\n\n0. **Propose first — don't ask up front.** Author the best role×energy suggestion for the pair\n (steps 1–4 below) and show it as a proposal; the designer then reacts with what to change. A\n rendered proposal is a better prompt than a blank \"how do you want this to move?\" question.\n (If the designer *has* stated an idea, author that instead — never impose your proposal over a\n stated one.)\n1. **Per element in A** — choose its motion by **role and the film's energy** (the vocabulary in\n this skill), authored through `apply_preset` / `patch_scene`. Lead with the simplest move\n that reads; tune params only when asked; raw keyframes only for what a preset can't express.\n2. **Author the matched-element smart-animate** for every shared layer (A→B delta).\n3. **B's new elements** — give them entrances, staggered, after the matched layers land.\n4. **Interaction sim** — where the transition reads as UI-driven, press the trigger element\n (`tap_pulse` on the element itself; a visible tap-dot only if the designer opts in).\n5. **Play the pair in the editor** (free), and let the designer **approve** — never\n self-approve by describing it. On approval, `approved: true` on that pair; advance.\n Open the editor **without asking first**: a free preview needs no go-ahead, so never\n stop at \"the render needs your approval\" or ask the designer to type \"go\" — show the\n result and let them react to it. Approval is for what they see, not for your next\n free tool call.\n\nEach edit is a `patch_scene` → a new `sceneRef`. Read the `scene_editor_feedback` payload\n(contract in `docs/widget-specs/scene-editor.md`): `verdict: \"needs_changes\"` carries\n`comments` / `timelineComments` — each with its own words (a pin's `instruction`, a stretch's\n`text`) and where it applies — which you fold into the motion via `patch_scene`; `verdict:\n\"approved\"` advances the conveyor. When `edited` is true, patch onto the returned `documentUrl`\n(the inline `document` only when it could not be stored), not your prior copy.\n\n## Tuning by hand — `picsart_scene_tune`\n\n**When:** one rule, here only. A declared knob goes to the tuner at the first taste complaint (\"too much glow\", \"colour's off\", \"more bounce\"). One named value (\"20% stronger\", \"0.3 s later\") is a `picsart_scene_patch`. With nothing declared, wait two chat rounds on the same thing, then extract it (below) and tune. Structural changes (adding a layer, a new action) stay with you.\n\n**How:** open `picsart_scene_tune` with `focus`. `primary` is the parameter the user's words point at. `related` holds the few that usually move with it (at most ~10). `note` is one line in the user's own terms (\"Try headTurn first, then the eyes\"). Never hide parameters; the rest stays under \"All\" and search.\n\n**After:** read back `changed`, `keys`, `order`, `layers` and `bindings`, continue from the returned `documentUrl` (inline `document` only when it could not be stored), and tell the user in one line what they changed.\n\n- `primary` and `related` also take a root layer id or a joint (a `vec2` parameter's name), not only a parameter name. Names must be exact ids; an unknown one is silently ignored.\n- `title` names what is tuned; `note` is at most 120 characters, in the user's language.\n- Nothing arrives until the user presses Accept; there is no close event. No `scene_tuner_feedback` means no change: keep the scene as it was and claim none.\n- Say which way in the `note`, never \"left\" alone: name the screen side or edge (on `rig-humanoid-front`, `+x` is the figure's left, the viewer's right).\n- Hand over the pair that moves together: a title and its subtitle are two layers; declare both positions (or parent one to the other) or the second stays behind.\n- Where the tool is not offered (`hiddenFrom: google`), keep iterating by chat.\n\n### Make it tunable when you struggle\n\nThe tuner moves what the scene declares (root `parameters`, and `actions` that animate them) and, with no declaration, a root layer's literal `transform.position`, its order, and its `animations.position` keys (`tab: \"layers\"`, `primary` a layer id).\n\n**Escalation:** the \"When\" rule above. A root layer's position, order or position keys count as declared; any other property of an undeclared part is extracted first.\n\n**Extract:**\n1. Move the part into its own scene (`assets: { <id>: { type: \"scene\", scene } }`) and place it with a `scene_ref` (`assetId`) at the same spot and window. The rest of the scene stays as it is.\n2. Declare its knobs as `scene-building-basics` \"Reusable parts\" says, bound into the part's properties with `{\"$eval\": \"<name>\"}`.\n3. The tuner reads only the root `parameters` of the scene it opens, so declare the same knobs on the host root and forward each: `scene_ref.parameters: { \"<inner>\": { \"$eval\": \"<outer>\" } }`. The `scene_ref` layer no longer has a position handle, so declare its placement as a host `vec2` parameter (`frame: \"composition\"`) and bind it into the layer's position the same way. Check with `picsart_scene_validate`.\n4. Open `picsart_scene_tune` on the host with `focus.primary` the knob that matches the complaint, and continue from what comes back.\n\nA scene that already declares its parameters needs only step 3.\n\n**Motion that has no knob yet.** A preset's numbers are literals in the layer's tracks, so there is nothing to tune: declare the knob and read it in that track's expression. \"Slower\" on a rig action is a knob too: declare it and bind `content.animation[i].speed` with `{\"$eval\":\"<knob>\"}`.\n\nAny scalar field takes `{\"$eval\":\"<knob>\"}`, so a knob can sit on timing, effects, colours or transitions. For a transition, offer its own params (`picsart_scene_capabilities` lists them).\n\nExtracted parts follow the `character-rigging` skill (placement, clipping).\n\n## Suggesting motion\n\nWhen you propose candidates, choose by **role × energy**, not a fixed list: a headline at\n`energetic` gets a fast word-stagger; at `calm`, a soft fade-up. Preview each **on the\nreal element**, never as a named list of presets in prose — a designer judges motion by\nwatching it, and a still or a word (\"fade_in\") approves things that are wrong.\n\n## Anti-patterns (the slideshow tells)\n\n- **A static first frame** — the reel holds on a frozen frame 1, then jumps into the 1→2 motion.\n The open should animate in (see *The opening beat*); a still that suddenly moves is a slideshow tell.\n- **Taking a mark apart** — splitting one vector/instance (a logo, an app icon) into sub-parts to\n stagger them, when the design authored it as one unit. Whole by default; offer the build (see\n *How finely to split*).\n- **Everything moving at once** — no focal point; reads as noise.\n- **Matched chrome cross-dissolving** instead of smart-animating — the headline tell.\n- **No depth** — every layer moves at the same rate, so it reads flat.\n- **Synchronized entrances** — siblings firing together look mechanical.\n- **Over-animation** — motion on elements that should stay still, fighting the design's\n hierarchy.\n- **Judging from a still** — a transition is invisible in one frame; always preview the\n moving stretch before approving, and check its 25/50/75% frames (see *Check the middle*).\n- **Two copies on screen, a border left behind, a mask off its layer** — the continuity and\n container tells (see *Craft for any motion*).\n""---\nname: motion-design-craft\ndescription: The craft of adding motion to any scene, whatever the video — an ad or reel, a promo, a tutorial or walkthrough, an explainer, an intro, outro or title card, or one beat inside a longer edit — motion chosen per element by its role, smart-animate and morphs between frames, transitions, strokes and mask reveals, reviewed by eye in the scene editor pair by pair. Use whenever motion is added to or changed in a scene — elements animating in or out, a transition that looks wrong, a morph, a mask, an animated callout, highlight or zoom, a logo reveal, kinetic text — including inside another use case or a tutorial, not only in the `animate-design` skill's pipeline, where it is stage 3.\nmetadata:\n owner: motion-designer\n---\n\n# Stage 3 — authoring the motion\n\nA composed scene is a set of layered frames that render identical to the design and don't\nmove yet. This stage makes them move — and the gap between \"slideshow\" and \"ad\" lives\nentirely in the choices made here: **which elements move, how, and what carries between\nframes.** The design is authored as a scene throughout; every edit is a\n`patch_scene` that writes a new scene document (`sceneRef` moves — always edit the latest).\n\nThe rule under everything: **motion draws the eye, so it is spent, not sprayed.** A frame\nwhere everything animates at once reads as noise. Pick the focal element per beat, move\nit, let the rest support.\n\n## Motion in any scene, not only after an import\n\nThis craft is not limited to the `animate-design` pipeline. Use it wherever a scene gets motion: a\ntutorial's full-screen moments and the transitions between its parts, a promo's title card, an\nanimated callout or highlight over a screen recording, a logo reveal, a presenter bubble that grows\ninto a full frame, a morph from one clip's framing into the next. Open this skill **as soon as the\nmotion is being designed**, not after a first transition already looks wrong. Everything below\napplies; only the inputs differ:\n\n- **\"Frames\" are the two states either side of the motion.** A is the last settled state before it,\n B the first settled state after it: two beats, two parts or two layouts of the same scene. Author\n A→B pair by pair, exactly as below.\n- **No import, so tag the matched elements yourself.** An element present in both states (the same\n shape, logo, panel, bubble or recording) is matched. Diff the two states with\n `picsart_scene_diff_layouts`, passing those pairs as `matchHints`, or `picsart_scene_query_layout` on\n both, and read off the delta.\n- **Shape changes, borders, masks, camera moves and sound sync** follow *Craft for any motion*\n below; read [`references/ENGINE-GOTCHAS.md`](references/ENGINE-GOTCHAS.md) before the first mask.\n- **The motion lives in the scene that has the layers.** When the final video is a stitch of\n rendered parts, a rendered part can only cut or dissolve into the next. Author a transition that\n carries an element across the seam in the scene that still holds both sides as layers, before it\n is rendered.\n- **Recorded footage stays footage.** Animate the layers around and over a recording (its panel,\n mask, frame, callouts and text); never re-time the recording itself to fit a motion.\n- **Review still happens on the moving stretch**, in `picsart_scene_editor`, pair by pair. When\n another flow called this skill, that flow's review step is where the user approves.\n\n## Read the design before animating it\n\n**First, read what changed** — from tool facts, not by eye. Diff the pair with\n`picsart_scene_diff_layouts` (pass frame A, frame B, and the import `matchKey`s as `matchHints`);\nit classifies each layer as moved / resized / restyled / content-changed / entered / exited /\nunchanged with root-space deltas. If the tool is unavailable, fall back to `picsart_scene_query_layout`\non A *and* B and diff by hand. Either way, **check fades yourself** — the diff sees only `visible`,\nnot numeric opacity, so an opacity change reads as unchanged. **Animate only what\nchanged; leave unchanged layers still.** The full frame-diff procedure and the\nchange→motion/easing/duration/reduced-motion mapping live in\n[`references/MOTION-PRINCIPLES.md`](references/MOTION-PRINCIPLES.md).\n\nThen choose each moving element's motion by its **role**, not at random. This is the default\nmapping — a starting point the designer overrides in the panel, not a law:\n\n| Role (from import) | Default motion |\n|---|---|\n| headline / display text | **type-on**, or word/character **stagger** in |\n| body / label text | short fade + slide-up |\n| CTA / button | **scale/pop**, entering *late* (after its context), often with a tap-dot |\n| hero image | subtle **scale-in / push-in**, or a mask **reveal** |\n| list / feed | the content **scrolls**; rows **stagger** in |\n| card / panel | **slide** from the nearest edge + fade |\n| chrome (tabs, header, nav) | usually the **matched element** — persists and smart-animates; enters first, exits last |\n| icon / small accent | quick **pop**, subtle |\n| background | least motion — a slow **parallax** drift or gentle scale |\n\nThe design's own **hierarchy is the motion priority**: what the eye should hit first gets\nthe entrance; supporting elements follow.\n\n## How finely to split — respect the design's units, don't take a mark apart\n\n\"Split into pieces that move independently\" means **use the layers the design has** — not\nmanufacture finer structure inside a single element. Going finer than the design (splitting one\nvector/instance into sub-parts to animate them separately) is the same class of overreach as\ninventing a cursor or a ripple: you're adding structure the designer didn't author.\n\n**Default: animate each element as the one unit Figma authored** (one layer / instance / vector =\none unit). Sub-dividing that unit is a bigger claim — allow it **only when all three hold**:\n\n1. the sub-parts are **distinct content** — separate things — not the strokes/segments of one glyph\n or mark;\n2. the **concept calls for it** — a set, variety, or a progressive build the message depends on;\n3. it is **not the brand's identity** — a logo, wordmark, or **app icon** stays whole regardless of\n how separable its parts look.\n\n**When it's a judgment call, keep the unit whole and OFFER the split** — let the designer choose;\nnever impose decomposition. *Worked example:* an AI-Playground app icon whose mark is a square,\nsparkle, diamond and circle **fails #3** — it's the identity mark — so the open is a whole-icon\nreveal (fade/scale the tile+shapes in together), and \"the four shapes pop in one by one\" is offered\nas an option, not authored by default. Taking a brand mark apart on screen reads as *disassembling\nthe logo*, which is rarely what the designer meant.\n\n## The opening beat — frame 1 animates IN, it never just sits there\n\n**The reel opens with motion, not a frozen screen.** A static frame 1 that holds and then\nsuddenly jerks into the 1→2 transition reads as amateur — the viewer sees a still image, then a\njump. Instead, **frame 1's own elements animate in at t=0**, so the first thing on screen is the\ndesign *assembling itself*, and by the time the 1→2 motion fires the frame already feels alive.\n\n- **Entrances by role, staggered by hierarchy.** Same role×energy vocabulary as any entrance\n (`MOTION-PRINCIPLES.md`): background/chrome settle first, then the hero/headline, then the CTA\n last. What the eye should hit first enters first; siblings stagger ~0.05–0.12s, never in unison.\n- **It's an intro, not a showcase — keep it tight.** A quick, confident assemble (energy scales\n it: energetic → snappier and shorter; calm → a softer fade-up). Don't animate *everything*; a\n couple of focal entrances plus a gentle settle on the rest reads better than a busy cascade.\n- **Then hold, then transition.** Opening beat → the frame's content-derived hold (the \"no dead\n air\" rule still applies) → the 1→2 motion. The opening is a distinct beat *before* pair 1→2.\n- **Nothing is matched yet** (there's no frame before frame 1), so this beat is entrances only —\n no smart-animate, no exits.\n- **Don't manufacture parts to stagger.** A sparse open (one icon on a dark ground) tempts you to\n invent motion by taking the one element apart. Whether that's allowed is a real judgment — see\n *How finely to split* below — but the default on a brand/app icon is a **whole-icon reveal**, with\n a staggered build only **offered**, never imposed.\n- **Symmetric at the end:** the last frame shouldn't freeze-frame either — let it settle/hold on a\n deliberate final state (or a brand lockup) rather than snapping to a stop.\n\nAuthor this as frame 1's entrance animations at `t=0`, self-check it like any pair, and get it\napproved as the reel's open **before** you start pair 1→2.\n\n## Matched-element smart-animate — the technique that makes it an ad\n\nThis is the single thing that separates motion design from a slideshow. When a layer\ncarries a `matchKey` into the next frame (tagged at import), you do **not** cross-dissolve\nthe two screens — you **animate the shared layer from its state in A to its state in B**:\n\n- **Move the delta** — position, size, opacity, and content (a text string changing) from\n A→B, ~0.4–0.8s, **ease-in-out**.\n- **Keep matched layers on screen through the transition** — never fade the shared chrome;\n its staying put *is* the continuity.\n- **Elements only in A exit** (fade/slide out) as or just before the move.\n- **Elements only in B enter** *after* the matched layers have arrived, so the eye follows\n continuity into the new content rather than being asked to look everywhere at once.\n\nMiss this and shared chrome cross-dissolves — the biggest tell of \"slideshow, not ad.\"\n\n## Craft rules that make motion read as designed\n\nEasing, duration, staggering, the opening beat, holds and the rest: read\n[`CRAFT-RULES.md`](references/CRAFT-RULES.md) before you author the first pair.\n\n## Craft for any motion — continuity, containers, camera, sound, checking\n\nLearned on a narrated tutorial whose bubbles grew into full frames and shrank back; each rule fixed\na visible bug. They hold for any motion, in any scene.\n\n**Shape and continuity**\n\n- **A shape change is two copies, pixel-locked, cross-faded across the whole move.** When an\n element changes shape between states (a rectangle to a circle, a card to full screen), animate a\n copy in A's shape and a copy in B's shape together — shared position, scales derived from one\n fixed ratio — and cross-fade them over the full duration of the move. Never scale one shape into\n the other's footprint, and never do it in two steps (move, then reshape).\n- **One of each thing on screen.** While an element travels to where its destination version sits,\n hide the destination version and reveal it on landing. Two visible copies always read as a glitch.\n- **Pixel locking.** Layers that must move as one share keyframe times and derive their scales from\n one ratio, so nothing drifts against anything else mid-move. Parent them when the engine allows.\n\n**Containers, borders and masks**\n\n- **Borders follow their content.** A stroke, ring or frame fades in after its content lands and\n fades out as the content starts to move. A border fading at a fixed size while the content moves\n past it looks detached.\n- **Clip to the inner shape.** Content inside a rounded border is clipped to the border's inner\n edge — the size minus the stroke width, the radius minus half the stroke — and fills it exactly.\n Square corners or a gap at the edge give it away at once (stroke insets: `ENGINE-GOTCHAS.md`).\n- **Masks move with their layer.** An animated layer's mask carries the same transform animation, on\n the same time base. A mask is addressed through its owner (`ENGINE-GOTCHAS.md`); remember that a\n nested composition's children run on its local clock.\n\n**Camera and time**\n\n- **Move a camera, not the content.** For a push, pan or reframe, animate one parent transform and\n compute the framing from the size of the target region (the smart-animate zoom in\n `ENGINE-GOTCHAS.md`; a pure pan needs the empty \"world\" layer, since a pan-only camera does\n nothing). Every layer then stays consistent with every other. **The camera holds still while a\n caption or card is entering** — one focal move per beat.\n- **Nothing sits frozen.** A hold the content needs still gets a subtle drift — a few percent of\n scale over the hold — or ambient motion (`float`, `breathe`), so the frame stays alive without\n drawing the eye. This is not padding: the hold's length still comes from its content.\n- **Time is a design tool.** Compress what repeats, play at real speed what must be believed (a\n generation finishing, a real result), slow down what must be read. A starting speed map for\n footage: typing and waiting at 2–3×, a fast-forward through repetitive content at up to 3×, the\n payoff at 1–1.5×, and a moment the viewer must dwell on slowed to 0.3–0.5×.\n- **Procedural secondary motion.** For continuous ambient movement (sway, bob, flicker), use an\n ambient preset (`sway`, `float`, `glow_pulse`), or where none fits a small Lua expression on\n position or rotation — a sine, not hand keyframes — with amplitude, phase and period varied per\n copy so repeated elements don't move in lockstep. Expressions do not work on camera fields.\n\n**Camera on screen recordings**\n\n- **Frame a region, not a guess.** The zoom that frames a button, message or result comes from the\n region's size against the recording's fitted scale, and the position from the region's centre:\n the screen-recording-layouts skill's framing formula, which holds for any frame size. On a panel in a vertical\n promo, the screen-recording-zoom skill's house zoom sets the numbers.\n- **Push in on the payoff.** Start wide, hold a beat (~0.15 s), then push to the detail (~0.6 s on\n the house curve) so it lands just before the narrator names it.\n- **Keep what must not be seen off screen.** Cut ~0.3 s before a warning banner or error toast\n appears; frame out internal names, emails, tokens and other people's data. When a frame can't\n avoid them, cover them with a rectangle in the UI's background colour, locked to the recording's\n transform so it moves with it.\n- **Patterns** for type-on over a real screenshot, prompt cards, insets, a phone-frame pop and\n ambient depth: *Tutorial and screen-recording patterns* in\n [`references/MOTION-PATTERNS.md`](references/MOTION-PATTERNS.md).\n\n**Sound and sync**\n\n- **Motion lands on sound.** Anchor key moves and cuts to audio events: a narrated word (word times\n from `picsart_media_transcribe`), a beat or a hit (`beats` and `onsets` from\n `picsart_media_analyze_audio`). A move that lands with its sound feels intended; the same move\n 200 ms off feels sloppy. **Cut on the voice, not the picture:** over narration, every shot starts\n on a word time, so the picture changes as the narrator says the thing.\n- **Sync is local, not global.** When sound and picture drift, measure and fix each source on its\n own; one global offset fixes some sources and breaks others.\n\n**Checking**\n\n- **Check the middle, not just the ends.** Most motion bugs live mid-move: doubles, gaps, square\n corners, pops. For every move, look at frames at 25%, 50% and 75% of it — pass those times to\n `picsart_scene_contact_sheet` — and at a larger `resolution`, zoom into the edges and corners of\n those rendered frames, not only the editor's preview.\n\n## The authoring loop — pair by pair, in the panel\n\nAuthor one pair at a time (see the `animate-design` skill's pairwise rhythm). You **author** the motion\nthrough `patch_scene` / the apply tools, then open `picsart_scene_editor` **on the whole scene\nbuilt so far** (titled for the current pair) so the designer watches it play *in context* and scrubs\nto the pair — not a 2-frame sub-scene — rather than exporting a video every time; reserve\n`picsart_scene_export` for the final deliverable and the error fallback. Before each round of\npatches and each look at the frames by eye, post the one-line progress message the `animate-design` skill\ndescribes. For each pair A→B:\n\n0. **Propose first — don't ask up front.** Author the best role×energy suggestion for the pair\n (steps 1–4 below) and show it as a proposal; the designer then reacts with what to change. A\n rendered proposal is a better prompt than a blank \"how do you want this to move?\" question.\n (If the designer *has* stated an idea, author that instead — never impose your proposal over a\n stated one.)\n1. **Per element in A** — choose its motion by **role and the film's energy** (the vocabulary in\n this skill), authored through `apply_preset` / `patch_scene`. Lead with the simplest move\n that reads; tune params only when asked; raw keyframes only for what a preset can't express.\n2. **Author the matched-element smart-animate** for every shared layer (A→B delta).\n3. **B's new elements** — give them entrances, staggered, after the matched layers land.\n4. **Interaction sim** — where the transition reads as UI-driven, press the trigger element\n (`tap_pulse` on the element itself; a visible tap-dot only if the designer opts in).\n5. **Play the pair in the editor** (free), and let the designer **approve** — never\n self-approve by describing it. On approval, `approved: true` on that pair; advance.\n Open the editor **without asking first**: a free preview needs no go-ahead, so never\n stop at \"the render needs your approval\" or ask the designer to type \"go\" — show the\n result and let them react to it. Approval is for what they see, not for your next\n free tool call.\n\nEach edit is a `patch_scene` → a new `sceneRef`. Read the `scene_editor_feedback` payload\n(contract in `docs/widget-specs/scene-editor.md`): `verdict: \"needs_changes\"` carries\n`comments` / `timelineComments` — each with its own words (a pin's `instruction`, a stretch's\n`text`) and where it applies — which you fold into the motion via `patch_scene`; `verdict:\n\"approved\"` advances the conveyor. When `edited` is true, patch onto the returned `documentUrl`\n(the inline `document` only when it could not be stored), not your prior copy.\n\n## Tuning by hand — `picsart_scene_tune`\n\n**When:** one rule, here only. A declared knob goes to the tuner at the first taste complaint (\"too much glow\", \"colour's off\", \"more bounce\"). One named value (\"20% stronger\", \"0.3 s later\") is a `picsart_scene_patch`. With nothing declared, wait two chat rounds on the same thing, then extract it (below) and tune. Structural changes (adding a layer, a new action) stay with you.\n\n**How:** open `picsart_scene_tune` with `focus`. `primary` is the parameter the user's words point at. `related` holds the few that usually move with it (at most ~10). `note` is one line in the user's own terms (\"Try headTurn first, then the eyes\"). Never hide parameters; the rest stays under \"All\" and search.\n\n**After:** read back `changed`, `keys`, `order`, `layers` and `bindings`, continue from the returned `documentUrl` (inline `document` only when it could not be stored), and tell the user in one line what they changed.\n\n- `primary` and `related` also take a root layer id or a joint (a `vec2` parameter's name), not only a parameter name. Names must be exact ids; an unknown one is silently ignored.\n- `title` names what is tuned; `note` is at most 120 characters, in the user's language.\n- Nothing arrives until the user presses Accept; there is no close event. No `scene_tuner_feedback` means no change: keep the scene as it was and claim none.\n- Say which way in the `note`, never \"left\" alone: name the screen side or edge (on `rig-humanoid-front`, `+x` is the figure's left, the viewer's right).\n- Hand over the pair that moves together: a title and its subtitle are two layers; declare both positions (or parent one to the other) or the second stays behind.\n- Where the tool is not offered (`hiddenFrom: google`), keep iterating by chat.\n\n### Make it tunable when you struggle\n\nThe tuner moves what the scene declares (root `parameters`, and `actions` that animate them) and, with no declaration, a root layer's literal `transform.position`, its order, and its `animations.position` keys (`tab: \"layers\"`, `primary` a layer id).\n\n**Escalation:** the \"When\" rule above. A root layer's position, order or position keys count as declared; any other property of an undeclared part is extracted first.\n\n**Extract:**\n1. Move the part into its own scene (`assets: { <id>: { type: \"scene\", scene } }`) and place it with a `scene_ref` (`assetId`) at the same spot and window. The rest of the scene stays as it is.\n2. Declare its knobs as `scene-building-basics` \"Reusable parts\" says, bound into the part's properties with `{\"$eval\": \"<name>\"}`.\n3. The tuner reads only the root `parameters` of the scene it opens, so declare the same knobs on the host root and forward each: `scene_ref.parameters: { \"<inner>\": { \"$eval\": \"<outer>\" } }`. The `scene_ref` layer no longer has a position handle, so declare its placement as a host `vec2` parameter (`frame: \"composition\"`) and bind it into the layer's position the same way. Check with `picsart_scene_validate`.\n4. Open `picsart_scene_tune` on the host with `focus.primary` the knob that matches the complaint, and continue from what comes back.\n\nA scene that already declares its parameters needs only step 3.\n\n**Motion that has no knob yet.** A preset's numbers are literals in the layer's tracks, so there is nothing to tune: declare the knob and read it in that track's expression. \"Slower\" on a rig action is a knob too: declare it and bind `content.animation[i].speed` with `{\"$eval\":\"<knob>\"}`.\n\nAny scalar field takes `{\"$eval\":\"<knob>\"}`, so a knob can sit on timing, effects, colours or transitions. For a transition, offer its own params (`picsart_scene_capabilities` lists them).\n\nExtracted parts follow the `character-rigging` skill (placement, clipping).\n\n## Suggesting motion\n\nWhen you propose candidates, choose by **role × energy**, not a fixed list: a headline at\n`energetic` gets a fast word-stagger; at `calm`, a soft fade-up. Preview each **on the\nreal element**, never as a named list of presets in prose — a designer judges motion by\nwatching it, and a still or a word (\"fade_in\") approves things that are wrong.\n\n**When two or more could fit and it's taste, the designer picks.** Build 2–6 candidates on the\nreal element and open them in `picsart_scene_picker` — one `scenes` entry each, its document as\n`scene`, its `label` what the designer would call it (\"fast word-stagger\", \"soft fade-up\"), never\na preset id. Don't choose for them and don't describe the options in text. Carry on from the\ncard(s) in the reply's `selected` and say in one line which one you kept (picsart-video-rules,\n*A choice made by eye*). With one clear best reading, step 0's single proposal stands.\n\n## Anti-patterns (the slideshow tells)\n\n- **A static first frame** — the reel holds on a frozen frame 1, then jumps into the 1→2 motion.\n The open should animate in (see *The opening beat*); a still that suddenly moves is a slideshow tell.\n- **Taking a mark apart** — splitting one vector/instance (a logo, an app icon) into sub-parts to\n stagger them, when the design authored it as one unit. Whole by default; offer the build (see\n *How finely to split*).\n- **Everything moving at once** — no focal point; reads as noise.\n- **Matched chrome cross-dissolving** instead of smart-animating — the headline tell.\n- **No depth** — every layer moves at the same rate, so it reads flat.\n- **Synchronized entrances** — siblings firing together look mechanical.\n- **Over-animation** — motion on elements that should stay still, fighting the design's\n hierarchy.\n- **Judging from a still** — a transition is invisible in one frame; always preview the\n moving stretch before approving, and check its 25/50/75% frames (see *Check the middle*).\n- **Two copies on screen, a border left behind, a mask off its layer** — the continuity and\n container tells (see *Craft for any motion*).\n"Full snapshot data
{
"description": "The craft of adding motion to any scene, whatever the video — an ad or reel, a promo, a tutorial or walkthrough, an explainer, an intro, outro or title card, or one beat inside a longer edit — motion chosen per element by its role, smart-animate and morphs between frames, transitions, strokes and mask reveals, reviewed by eye in the scene editor pair by pair. Use whenever motion is added to or changed in a scene — elements animating in or out, a transition that looks wrong, a morph, a mask, an animated callout, highlight or zoom, a logo reveal, kinetic text — including inside another use case or a tutorial, not only in the `animate-design` skill's pipeline, where it is stage 3.",
"included_files": [
{
"relative_path": "docs/widget-specs/scene-editor.md",
"size_in_bytes": 6578
},
{
"relative_path": "references/ASSET-COMPOSITION.md",
"size_in_bytes": 6194
},
{
"relative_path": "references/AUTHORING-FLOW.md",
"size_in_bytes": 21335
},
{
"relative_path": "references/CHOREOGRAPHY.md",
"size_in_bytes": 5594
},
{
"relative_path": "references/COMPOSE-FUNDAMENTALS.md",
"size_in_bytes": 4483
},
{
"relative_path": "references/CRAFT-RULES.md",
"size_in_bytes": 8855
},
{
"relative_path": "references/ELEMENT-MOTION.md",
"size_in_bytes": 4679
},
{
"relative_path": "references/ENGINE-GOTCHAS.md",
"size_in_bytes": 5854
},
{
"relative_path": "references/MOTION-PATTERNS.md",
"size_in_bytes": 9569
},
{
"relative_path": "references/MOTION-PRINCIPLES.md",
"size_in_bytes": 31117
},
{
"relative_path": "references/MOTION-TROUBLESHOOTING.md",
"size_in_bytes": 10655
},
{
"relative_path": "references/SCENE-VALIDATION.md",
"size_in_bytes": 6579
},
{
"relative_path": "references/SCENE-VOCABULARY.md",
"size_in_bytes": 11726
},
{
"relative_path": "references/STUDYING-MOTION.md",
"size_in_bytes": 1479
},
{
"relative_path": "references/TOOL-ROUTING.md",
"size_in_bytes": 23846
},
{
"relative_path": "references/TRANSITIONS.md",
"size_in_bytes": 17876
},
{
"relative_path": "references/WIDGET-FEEDBACK.md",
"size_in_bytes": 4854
}
],
"name": "motion-design-craft",
"skill_md_contents": "---\nname: motion-design-craft\ndescription: The craft of adding motion to any scene, whatever the video — an ad or reel, a promo, a tutorial or walkthrough, an explainer, an intro, outro or title card, or one beat inside a longer edit — motion chosen per element by its role, smart-animate and morphs between frames, transitions, strokes and mask reveals, reviewed by eye in the scene editor pair by pair. Use whenever motion is added to or changed in a scene — elements animating in or out, a transition that looks wrong, a morph, a mask, an animated callout, highlight or zoom, a logo reveal, kinetic text — including inside another use case or a tutorial, not only in the `animate-design` skill's pipeline, where it is stage 3.\nmetadata:\n owner: motion-designer\n---\n\n# Stage 3 — authoring the motion\n\nA composed scene is a set of layered frames that render identical to the design and don't\nmove yet. This stage makes them move — and the gap between \"slideshow\" and \"ad\" lives\nentirely in the choices made here: **which elements move, how, and what carries between\nframes.** The design is authored as a scene throughout; every edit is a\n`patch_scene` that writes a new scene document (`sceneRef` moves — always edit the latest).\n\nThe rule under everything: **motion draws the eye, so it is spent, not sprayed.** A frame\nwhere everything animates at once reads as noise. Pick the focal element per beat, move\nit, let the rest support.\n\n## Motion in any scene, not only after an import\n\nThis craft is not limited to the `animate-design` pipeline. Use it wherever a scene gets motion: a\ntutorial's full-screen moments and the transitions between its parts, a promo's title card, an\nanimated callout or highlight over a screen recording, a logo reveal, a presenter bubble that grows\ninto a full frame, a morph from one clip's framing into the next. Open this skill **as soon as the\nmotion is being designed**, not after a first transition already looks wrong. Everything below\napplies; only the inputs differ:\n\n- **\"Frames\" are the two states either side of the motion.** A is the last settled state before it,\n B the first settled state after it: two beats, two parts or two layouts of the same scene. Author\n A→B pair by pair, exactly as below.\n- **No import, so tag the matched elements yourself.** An element present in both states (the same\n shape, logo, panel, bubble or recording) is matched. Diff the two states with\n `picsart_scene_diff_layouts`, passing those pairs as `matchHints`, or `picsart_scene_query_layout` on\n both, and read off the delta.\n- **Shape changes, borders, masks, camera moves and sound sync** follow *Craft for any motion*\n below; read [`references/ENGINE-GOTCHAS.md`](references/ENGINE-GOTCHAS.md) before the first mask.\n- **The motion lives in the scene that has the layers.** When the final video is a stitch of\n rendered parts, a rendered part can only cut or dissolve into the next. Author a transition that\n carries an element across the seam in the scene that still holds both sides as layers, before it\n is rendered.\n- **Recorded footage stays footage.** Animate the layers around and over a recording (its panel,\n mask, frame, callouts and text); never re-time the recording itself to fit a motion.\n- **Review still happens on the moving stretch**, in `picsart_scene_editor`, pair by pair. When\n another flow called this skill, that flow's review step is where the user approves.\n\n## Read the design before animating it\n\n**First, read what changed** — from tool facts, not by eye. Diff the pair with\n`picsart_scene_diff_layouts` (pass frame A, frame B, and the import `matchKey`s as `matchHints`);\nit classifies each layer as moved / resized / restyled / content-changed / entered / exited /\nunchanged with root-space deltas. If the tool is unavailable, fall back to `picsart_scene_query_layout`\non A *and* B and diff by hand. Either way, **check fades yourself** — the diff sees only `visible`,\nnot numeric opacity, so an opacity change reads as unchanged. **Animate only what\nchanged; leave unchanged layers still.** The full frame-diff procedure and the\nchange→motion/easing/duration/reduced-motion mapping live in\n[`references/MOTION-PRINCIPLES.md`](references/MOTION-PRINCIPLES.md).\n\nThen choose each moving element's motion by its **role**, not at random. This is the default\nmapping — a starting point the designer overrides in the panel, not a law:\n\n| Role (from import) | Default motion |\n|---|---|\n| headline / display text | **type-on**, or word/character **stagger** in |\n| body / label text | short fade + slide-up |\n| CTA / button | **scale/pop**, entering *late* (after its context), often with a tap-dot |\n| hero image | subtle **scale-in / push-in**, or a mask **reveal** |\n| list / feed | the content **scrolls**; rows **stagger** in |\n| card / panel | **slide** from the nearest edge + fade |\n| chrome (tabs, header, nav) | usually the **matched element** — persists and smart-animates; enters first, exits last |\n| icon / small accent | quick **pop**, subtle |\n| background | least motion — a slow **parallax** drift or gentle scale |\n\nThe design's own **hierarchy is the motion priority**: what the eye should hit first gets\nthe entrance; supporting elements follow.\n\n## How finely to split — respect the design's units, don't take a mark apart\n\n\"Split into pieces that move independently\" means **use the layers the design has** — not\nmanufacture finer structure inside a single element. Going finer than the design (splitting one\nvector/instance into sub-parts to animate them separately) is the same class of overreach as\ninventing a cursor or a ripple: you're adding structure the designer didn't author.\n\n**Default: animate each element as the one unit Figma authored** (one layer / instance / vector =\none unit). Sub-dividing that unit is a bigger claim — allow it **only when all three hold**:\n\n1. the sub-parts are **distinct content** — separate things — not the strokes/segments of one glyph\n or mark;\n2. the **concept calls for it** — a set, variety, or a progressive build the message depends on;\n3. it is **not the brand's identity** — a logo, wordmark, or **app icon** stays whole regardless of\n how separable its parts look.\n\n**When it's a judgment call, keep the unit whole and OFFER the split** — let the designer choose;\nnever impose decomposition. *Worked example:* an AI-Playground app icon whose mark is a square,\nsparkle, diamond and circle **fails #3** — it's the identity mark — so the open is a whole-icon\nreveal (fade/scale the tile+shapes in together), and \"the four shapes pop in one by one\" is offered\nas an option, not authored by default. Taking a brand mark apart on screen reads as *disassembling\nthe logo*, which is rarely what the designer meant.\n\n## The opening beat — frame 1 animates IN, it never just sits there\n\n**The reel opens with motion, not a frozen screen.** A static frame 1 that holds and then\nsuddenly jerks into the 1→2 transition reads as amateur — the viewer sees a still image, then a\njump. Instead, **frame 1's own elements animate in at t=0**, so the first thing on screen is the\ndesign *assembling itself*, and by the time the 1→2 motion fires the frame already feels alive.\n\n- **Entrances by role, staggered by hierarchy.** Same role×energy vocabulary as any entrance\n (`MOTION-PRINCIPLES.md`): background/chrome settle first, then the hero/headline, then the CTA\n last. What the eye should hit first enters first; siblings stagger ~0.05–0.12s, never in unison.\n- **It's an intro, not a showcase — keep it tight.** A quick, confident assemble (energy scales\n it: energetic → snappier and shorter; calm → a softer fade-up). Don't animate *everything*; a\n couple of focal entrances plus a gentle settle on the rest reads better than a busy cascade.\n- **Then hold, then transition.** Opening beat → the frame's content-derived hold (the \"no dead\n air\" rule still applies) → the 1→2 motion. The opening is a distinct beat *before* pair 1→2.\n- **Nothing is matched yet** (there's no frame before frame 1), so this beat is entrances only —\n no smart-animate, no exits.\n- **Don't manufacture parts to stagger.** A sparse open (one icon on a dark ground) tempts you to\n invent motion by taking the one element apart. Whether that's allowed is a real judgment — see\n *How finely to split* below — but the default on a brand/app icon is a **whole-icon reveal**, with\n a staggered build only **offered**, never imposed.\n- **Symmetric at the end:** the last frame shouldn't freeze-frame either — let it settle/hold on a\n deliberate final state (or a brand lockup) rather than snapping to a stop.\n\nAuthor this as frame 1's entrance animations at `t=0`, self-check it like any pair, and get it\napproved as the reel's open **before** you start pair 1→2.\n\n## Matched-element smart-animate — the technique that makes it an ad\n\nThis is the single thing that separates motion design from a slideshow. When a layer\ncarries a `matchKey` into the next frame (tagged at import), you do **not** cross-dissolve\nthe two screens — you **animate the shared layer from its state in A to its state in B**:\n\n- **Move the delta** — position, size, opacity, and content (a text string changing) from\n A→B, ~0.4–0.8s, **ease-in-out**.\n- **Keep matched layers on screen through the transition** — never fade the shared chrome;\n its staying put *is* the continuity.\n- **Elements only in A exit** (fade/slide out) as or just before the move.\n- **Elements only in B enter** *after* the matched layers have arrived, so the eye follows\n continuity into the new content rather than being asked to look everywhere at once.\n\nMiss this and shared chrome cross-dissolves — the biggest tell of \"slideshow, not ad.\"\n\n## Craft rules that make motion read as designed\n\nEasing, duration, staggering, the opening beat, holds and the rest: read\n[`CRAFT-RULES.md`](references/CRAFT-RULES.md) before you author the first pair.\n\n## Craft for any motion — continuity, containers, camera, sound, checking\n\nLearned on a narrated tutorial whose bubbles grew into full frames and shrank back; each rule fixed\na visible bug. They hold for any motion, in any scene.\n\n**Shape and continuity**\n\n- **A shape change is two copies, pixel-locked, cross-faded across the whole move.** When an\n element changes shape between states (a rectangle to a circle, a card to full screen), animate a\n copy in A's shape and a copy in B's shape together — shared position, scales derived from one\n fixed ratio — and cross-fade them over the full duration of the move. Never scale one shape into\n the other's footprint, and never do it in two steps (move, then reshape).\n- **One of each thing on screen.** While an element travels to where its destination version sits,\n hide the destination version and reveal it on landing. Two visible copies always read as a glitch.\n- **Pixel locking.** Layers that must move as one share keyframe times and derive their scales from\n one ratio, so nothing drifts against anything else mid-move. Parent them when the engine allows.\n\n**Containers, borders and masks**\n\n- **Borders follow their content.** A stroke, ring or frame fades in after its content lands and\n fades out as the content starts to move. A border fading at a fixed size while the content moves\n past it looks detached.\n- **Clip to the inner shape.** Content inside a rounded border is clipped to the border's inner\n edge — the size minus the stroke width, the radius minus half the stroke — and fills it exactly.\n Square corners or a gap at the edge give it away at once (stroke insets: `ENGINE-GOTCHAS.md`).\n- **Masks move with their layer.** An animated layer's mask carries the same transform animation, on\n the same time base. A mask is addressed through its owner (`ENGINE-GOTCHAS.md`); remember that a\n nested composition's children run on its local clock.\n\n**Camera and time**\n\n- **Move a camera, not the content.** For a push, pan or reframe, animate one parent transform and\n compute the framing from the size of the target region (the smart-animate zoom in\n `ENGINE-GOTCHAS.md`; a pure pan needs the empty \"world\" layer, since a pan-only camera does\n nothing). Every layer then stays consistent with every other. **The camera holds still while a\n caption or card is entering** — one focal move per beat.\n- **Nothing sits frozen.** A hold the content needs still gets a subtle drift — a few percent of\n scale over the hold — or ambient motion (`float`, `breathe`), so the frame stays alive without\n drawing the eye. This is not padding: the hold's length still comes from its content.\n- **Time is a design tool.** Compress what repeats, play at real speed what must be believed (a\n generation finishing, a real result), slow down what must be read. A starting speed map for\n footage: typing and waiting at 2–3×, a fast-forward through repetitive content at up to 3×, the\n payoff at 1–1.5×, and a moment the viewer must dwell on slowed to 0.3–0.5×.\n- **Procedural secondary motion.** For continuous ambient movement (sway, bob, flicker), use an\n ambient preset (`sway`, `float`, `glow_pulse`), or where none fits a small Lua expression on\n position or rotation — a sine, not hand keyframes — with amplitude, phase and period varied per\n copy so repeated elements don't move in lockstep. Expressions do not work on camera fields.\n\n**Camera on screen recordings**\n\n- **Frame a region, not a guess.** The zoom that frames a button, message or result comes from the\n region's size against the recording's fitted scale, and the position from the region's centre:\n the screen-recording-layouts skill's framing formula, which holds for any frame size. On a panel in a vertical\n promo, the screen-recording-zoom skill's house zoom sets the numbers.\n- **Push in on the payoff.** Start wide, hold a beat (~0.15 s), then push to the detail (~0.6 s on\n the house curve) so it lands just before the narrator names it.\n- **Keep what must not be seen off screen.** Cut ~0.3 s before a warning banner or error toast\n appears; frame out internal names, emails, tokens and other people's data. When a frame can't\n avoid them, cover them with a rectangle in the UI's background colour, locked to the recording's\n transform so it moves with it.\n- **Patterns** for type-on over a real screenshot, prompt cards, insets, a phone-frame pop and\n ambient depth: *Tutorial and screen-recording patterns* in\n [`references/MOTION-PATTERNS.md`](references/MOTION-PATTERNS.md).\n\n**Sound and sync**\n\n- **Motion lands on sound.** Anchor key moves and cuts to audio events: a narrated word (word times\n from `picsart_media_transcribe`), a beat or a hit (`beats` and `onsets` from\n `picsart_media_analyze_audio`). A move that lands with its sound feels intended; the same move\n 200 ms off feels sloppy. **Cut on the voice, not the picture:** over narration, every shot starts\n on a word time, so the picture changes as the narrator says the thing.\n- **Sync is local, not global.** When sound and picture drift, measure and fix each source on its\n own; one global offset fixes some sources and breaks others.\n\n**Checking**\n\n- **Check the middle, not just the ends.** Most motion bugs live mid-move: doubles, gaps, square\n corners, pops. For every move, look at frames at 25%, 50% and 75% of it — pass those times to\n `picsart_scene_contact_sheet` — and at a larger `resolution`, zoom into the edges and corners of\n those rendered frames, not only the editor's preview.\n\n## The authoring loop — pair by pair, in the panel\n\nAuthor one pair at a time (see the `animate-design` skill's pairwise rhythm). You **author** the motion\nthrough `patch_scene` / the apply tools, then open `picsart_scene_editor` **on the whole scene\nbuilt so far** (titled for the current pair) so the designer watches it play *in context* and scrubs\nto the pair — not a 2-frame sub-scene — rather than exporting a video every time; reserve\n`picsart_scene_export` for the final deliverable and the error fallback. Before each round of\npatches and each look at the frames by eye, post the one-line progress message the `animate-design` skill\ndescribes. For each pair A→B:\n\n0. **Propose first — don't ask up front.** Author the best role×energy suggestion for the pair\n (steps 1–4 below) and show it as a proposal; the designer then reacts with what to change. A\n rendered proposal is a better prompt than a blank \"how do you want this to move?\" question.\n (If the designer *has* stated an idea, author that instead — never impose your proposal over a\n stated one.)\n1. **Per element in A** — choose its motion by **role and the film's energy** (the vocabulary in\n this skill), authored through `apply_preset` / `patch_scene`. Lead with the simplest move\n that reads; tune params only when asked; raw keyframes only for what a preset can't express.\n2. **Author the matched-element smart-animate** for every shared layer (A→B delta).\n3. **B's new elements** — give them entrances, staggered, after the matched layers land.\n4. **Interaction sim** — where the transition reads as UI-driven, press the trigger element\n (`tap_pulse` on the element itself; a visible tap-dot only if the designer opts in).\n5. **Play the pair in the editor** (free), and let the designer **approve** — never\n self-approve by describing it. On approval, `approved: true` on that pair; advance.\n Open the editor **without asking first**: a free preview needs no go-ahead, so never\n stop at \"the render needs your approval\" or ask the designer to type \"go\" — show the\n result and let them react to it. Approval is for what they see, not for your next\n free tool call.\n\nEach edit is a `patch_scene` → a new `sceneRef`. Read the `scene_editor_feedback` payload\n(contract in `docs/widget-specs/scene-editor.md`): `verdict: \"needs_changes\"` carries\n`comments` / `timelineComments` — each with its own words (a pin's `instruction`, a stretch's\n`text`) and where it applies — which you fold into the motion via `patch_scene`; `verdict:\n\"approved\"` advances the conveyor. When `edited` is true, patch onto the returned `documentUrl`\n(the inline `document` only when it could not be stored), not your prior copy.\n\n## Tuning by hand — `picsart_scene_tune`\n\n**When:** one rule, here only. A declared knob goes to the tuner at the first taste complaint (\"too much glow\", \"colour's off\", \"more bounce\"). One named value (\"20% stronger\", \"0.3 s later\") is a `picsart_scene_patch`. With nothing declared, wait two chat rounds on the same thing, then extract it (below) and tune. Structural changes (adding a layer, a new action) stay with you.\n\n**How:** open `picsart_scene_tune` with `focus`. `primary` is the parameter the user's words point at. `related` holds the few that usually move with it (at most ~10). `note` is one line in the user's own terms (\"Try headTurn first, then the eyes\"). Never hide parameters; the rest stays under \"All\" and search.\n\n**After:** read back `changed`, `keys`, `order`, `layers` and `bindings`, continue from the returned `documentUrl` (inline `document` only when it could not be stored), and tell the user in one line what they changed.\n\n- `primary` and `related` also take a root layer id or a joint (a `vec2` parameter's name), not only a parameter name. Names must be exact ids; an unknown one is silently ignored.\n- `title` names what is tuned; `note` is at most 120 characters, in the user's language.\n- Nothing arrives until the user presses Accept; there is no close event. No `scene_tuner_feedback` means no change: keep the scene as it was and claim none.\n- Say which way in the `note`, never \"left\" alone: name the screen side or edge (on `rig-humanoid-front`, `+x` is the figure's left, the viewer's right).\n- Hand over the pair that moves together: a title and its subtitle are two layers; declare both positions (or parent one to the other) or the second stays behind.\n- Where the tool is not offered (`hiddenFrom: google`), keep iterating by chat.\n\n### Make it tunable when you struggle\n\nThe tuner moves what the scene declares (root `parameters`, and `actions` that animate them) and, with no declaration, a root layer's literal `transform.position`, its order, and its `animations.position` keys (`tab: \"layers\"`, `primary` a layer id).\n\n**Escalation:** the \"When\" rule above. A root layer's position, order or position keys count as declared; any other property of an undeclared part is extracted first.\n\n**Extract:**\n1. Move the part into its own scene (`assets: { <id>: { type: \"scene\", scene } }`) and place it with a `scene_ref` (`assetId`) at the same spot and window. The rest of the scene stays as it is.\n2. Declare its knobs as `scene-building-basics` \"Reusable parts\" says, bound into the part's properties with `{\"$eval\": \"<name>\"}`.\n3. The tuner reads only the root `parameters` of the scene it opens, so declare the same knobs on the host root and forward each: `scene_ref.parameters: { \"<inner>\": { \"$eval\": \"<outer>\" } }`. The `scene_ref` layer no longer has a position handle, so declare its placement as a host `vec2` parameter (`frame: \"composition\"`) and bind it into the layer's position the same way. Check with `picsart_scene_validate`.\n4. Open `picsart_scene_tune` on the host with `focus.primary` the knob that matches the complaint, and continue from what comes back.\n\nA scene that already declares its parameters needs only step 3.\n\n**Motion that has no knob yet.** A preset's numbers are literals in the layer's tracks, so there is nothing to tune: declare the knob and read it in that track's expression. \"Slower\" on a rig action is a knob too: declare it and bind `content.animation[i].speed` with `{\"$eval\":\"<knob>\"}`.\n\nAny scalar field takes `{\"$eval\":\"<knob>\"}`, so a knob can sit on timing, effects, colours or transitions. For a transition, offer its own params (`picsart_scene_capabilities` lists them).\n\nExtracted parts follow the `character-rigging` skill (placement, clipping).\n\n## Suggesting motion\n\nWhen you propose candidates, choose by **role × energy**, not a fixed list: a headline at\n`energetic` gets a fast word-stagger; at `calm`, a soft fade-up. Preview each **on the\nreal element**, never as a named list of presets in prose — a designer judges motion by\nwatching it, and a still or a word (\"fade_in\") approves things that are wrong.\n\n**When two or more could fit and it's taste, the designer picks.** Build 2–6 candidates on the\nreal element and open them in `picsart_scene_picker` — one `scenes` entry each, its document as\n`scene`, its `label` what the designer would call it (\"fast word-stagger\", \"soft fade-up\"), never\na preset id. Don't choose for them and don't describe the options in text. Carry on from the\ncard(s) in the reply's `selected` and say in one line which one you kept (picsart-video-rules,\n*A choice made by eye*). With one clear best reading, step 0's single proposal stands.\n\n## Anti-patterns (the slideshow tells)\n\n- **A static first frame** — the reel holds on a frozen frame 1, then jumps into the 1→2 motion.\n The open should animate in (see *The opening beat*); a still that suddenly moves is a slideshow tell.\n- **Taking a mark apart** — splitting one vector/instance (a logo, an app icon) into sub-parts to\n stagger them, when the design authored it as one unit. Whole by default; offer the build (see\n *How finely to split*).\n- **Everything moving at once** — no focal point; reads as noise.\n- **Matched chrome cross-dissolving** instead of smart-animating — the headline tell.\n- **No depth** — every layer moves at the same rate, so it reads flat.\n- **Synchronized entrances** — siblings firing together look mechanical.\n- **Over-animation** — motion on elements that should stay still, fighting the design's\n hierarchy.\n- **Judging from a still** — a transition is invisible in one frame; always preview the\n moving stretch before approving, and check its 25/50/75% frames (see *Check the middle*).\n- **Two copies on screen, a border left behind, a mask off its layer** — the continuity and\n container tells (see *Craft for any motion*).\n"
}SHA-256 of public snapshot: 8e514c50fcf54d22f9b58c24a874835e596b8191e27f50fca5658013f8bfa42e