← PicsartCONTENT HISTORY

Update to Picsart

Snapshot Nov 7, 2026 · 00:09 UTC · version 2.4.0

Collection source: downloaded plugin package.

WHAT CHANGED

Instructions updated for motion-design-craft

Skill instructions — Now says: ## Tuning by hand — `picsart_scene_tune` **When:** one rule, here only. A declared knob goes to the tuner at the first taste complaint ("too much glow",...

Observed in instructions or declared skills. Runtime behavior has not been tested.

Save Picsart and check future changes in Following.

Up to 3 plugins free · no card required.

All fields and original values.

Skill instructions

Before

Nov 3, 2026 · 18:14 UTC

No removed lines (ordering may have changed)

After

Nov 7, 2026 · 00:09 UTC

## Tuning by hand — `picsart_scene_tune` **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...

Supporting files

Before

Nov 3, 2026 · 18:14 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":...

After

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":...

Compare saved observations

Download comparison JSON

SKILL.md text changes

− removed · + added

--- before
+++ after
@@ -262,6 +262,41 @@
 "approved"` advances the conveyor. When `edited` is true, patch onto the returned `documentUrl`
 (the inline `document` only when it could not be stored), not your prior copy.
 
+## Tuning by hand — `picsart_scene_tune`
+
+**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.
+
+**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.
+
+**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.
+
+- `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.
+- `title` names what is tuned; `note` is at most 120 characters, in the user's language.
+- 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.
+- 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).
+- 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.
+- Where the tool is not offered (`hiddenFrom: google`), keep iterating by chat.
+
+### Make it tunable when you struggle
+
+The 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).
+
+**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.
+
+**Extract:**
+1. 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.
+2. Declare its knobs as `scene-building-basics` "Reusable parts" says, bound into the part's properties with `{"$eval": "<name>"}`.
+3. 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`.
+4. Open `picsart_scene_tune` on the host with `focus.primary` the knob that matches the complaint, and continue from what comes back.
+
+A scene that already declares its parameters needs only step 3.
+
+**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>"}`.
+
+Any 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).
+
+Extracted parts follow the `character-rigging` skill (placement, clipping).
+
 ## Suggesting motion
 
 When you propose candidates, choose by **role × energy**, not a fixed list: a headline at
Full technical diff · 2 changed fields

changed /included_files

BEFORE
[
  {
    "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": 7138
  },
  {
    "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": 23702
  },
  {
    "relative_path": "references/TRANSITIONS.md",
    "size_in_bytes": 17883
  },
  {
    "relative_path": "references/WIDGET-FEEDBACK.md",
    "size_in_bytes": 4854
  }
]
AFTER
[
  {
    "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
  }
]

changed /skill_md_contents

BEFORE
"---\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## 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"
AFTER
"---\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"
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": 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
    }
  ],
  "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## 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: 177dd5a478f1cf6d67fb496b559435bb889804438bef2358a72dab795915a0cc