{"id":78686,"plugin_id":"plugin_asdk_app_6a18d4c190a0819186e6b129a09e931e","kind":"skill","collection_source":"plugin_package","comparison_source":"plugin_package","observed_at":"2026-11-03T18:14:00.523Z","digest":"a94a63ada3ca1de426f9b62611028143f90aeb96c23842ee68f30cc47eba3666","against":65243,"payload":{"description":"Bring a design or static assets into a scene as LAYERS, not flat frames, whenever they are going to move — Figma frames for an ad or reel, or a Figma design, logo, UI screen or screenshot that animates inside a tutorial, promo or explainer — each layer in its native format (live text, vector or raster) on a fetchable hosted URL, with flat frames only as a fallback. Stage 1 of the `animate-design` skill's pipeline, and used before the motion-design-craft skill by any flow that animates a design.","included_files":[],"name":"design-layer-import","skill_md_contents":"---\nname: design-layer-import\ndescription: Bring a design or static assets into a scene as LAYERS, not flat frames, whenever they are going to move — Figma frames for an ad or reel, or a Figma design, logo, UI screen or screenshot that animates inside a tutorial, promo or explainer — each layer in its native format (live text, vector or raster) on a fetchable hosted URL, with flat frames only as a fallback. Stage 1 of the `animate-design` skill's pipeline, and used before the motion-design-craft skill by any flow that animates a design.\nmetadata:\n  owner: motion-designer\n---\n\n# Stage 1 — Import: the design in as layers\n\nMotion design animates *elements*, so the import's whole job is to bring the design in as\n**layers, not flat frames**. A frame delivered as one sealed PNG can only ever\ncross-dissolve; a frame delivered as its layers — panels, headline, buttons, the image,\nthe list — is a thing whose elements can slide, scroll, type on, parallax and\nsmart-animate. **Everything downstream is gated on this**: if the layers are lost here,\nno amount of tuning later can recover the ad; it stays a slideshow.\n\n## Pull the layer tree, per frame\n\nBefore reading Figma, post the one-line progress message the `animate-design` skill describes\n(\"Reading your layers…\").\n\n**With the Figma connector present**, read structure before pixels: `get_metadata` /\n`get_design_context` to walk each frame's node tree, then export each animatable node as\nits own asset. For every layer capture:\n\n> **AUDIT EVERY NESTED LAYER — never compose from Figma's simplified, frame-level output.** The\n> single biggest way items go missing from the ad: Figma's frame-level / summarized read (a shallow\n> `get_design_context`, or a `get_metadata` that stops at the top level) **collapses nested children**\n> — groups, component instances, auto-layout children, masked contents — into a summary. Take that at\n> face value and **every nested element is silently dropped**, so the composed frame is missing pieces\n> that were plainly in the design. **Recursively expand each frame's FULL tree** (`get_metadata` on the\n> frame node with its children expanded, or `use_figma` to walk *all* descendants) and audit it\n> **node by node** — do not trust a frame-level layer list to be complete. **Completeness check:** the\n> layers you capture must match the count of leaf/animatable nodes in the *fully-expanded* tree, not\n> the handful the frame-level view showed. If a group or instance shows as one node, open it — its\n> children are the layers. (Downstream this is the Stage-2 \"layer count ≈ node count\" gate; catch it\n> here, at the read, not after a frame composes short.)\n\n\n- **id** and **name/role** (what it is — `chrome`, `headline`, `cta`, `image`, `list`, `fx`)\n- **type** — `text`, `vector` (icon/logo/shape), or `raster` (photo/complex image); plus `group`\n- **transform** — `x, y, w, h, rotation, opacity`, and **z-order** (front-to-back)\n- **parent/group** — so a group can move as one: record the group (card, control, grid cell) each\n  layer belongs to, and which member is its backing. Compose turns it into one group that carries\n  the motion (motion-design-craft skill, `references/AUTHORING-FLOW.md` §6); without it the members are\n  keyframed one by one and drift apart\n- **for an image fill, its `scaleMode`** (`FILL` / `FIT` / `CROP` / `TILE`), and for `CROP` its\n  `imageTransform` — they decide the layer's `fit` and `crop`; a raw image placed without them is\n  stretched to the box\n- **for a text layer, also the type properties** — the **string**, resolved **font URL** + size,\n  **horizontal alignment** (read Figma's `textAlignHorizontal` — `left`/`center`/`right`; *never*\n  guess it from position or from \"it's a big headline\"), and the **box sizing/wrap**: a Figma\n  **fixed-width** text box that runs past the frame **clips, it does not wrap** — record the box\n  width and that it clips, or the renderer soft-wraps the line into two downstream.\n\n### Export each layer *as what it is* — PNG is the fallback, not the default\n\nThe layer's **source type** decides the export format. Deciding this per layer is the job;\nreaching for PNG on every element is the freelance-default that quietly wrecks quality —\n**stop and ask \"is this layer actually raster?\" before you export a PNG.**\n\n- **Text** → keep as **live text** (the string + resolved font URL), *never* an image. This is\n  what makes type-on, per-line and per-character animation possible; baking text to PNG kills\n  all of it and can't reflow.\n- **Vector** — icons, logos, line art, panels, pills, flat shapes → a **shape layer**, no asset\n  at all, built in two steps. **First create the layer**: `picsart_scene_patch` adds a\n  layer whose `content.kind` is `\"shape\"`, with a `rect` (or `ellipse`) item sized to the node's\n  box and the node's placement in the layer's `transform`; for a non-rectangular vector (an icon,\n  a logo, a boolean), add the shape layer and append its outline with\n  `picsart_scene_import_svg_path` (the node's path data as `d`). **Then paint it**:\n  `picsart_scene_import_figma_paint` takes the `scene` and that layer's `layerId`, plus the\n  node's CSS from `get_design_context` — `fill`, `boxShadow`, `gradient` (with the element\n  `size`), and `gradientPaint: \"stroke\"` (+ `gradientStrokeWidth`) for a gradient outline. A\n  solid stroke is not a paint it takes: it comes in with a path outline (`import_svg_path`'s\n  `stroke` + `width`), or, on a `rect`/`ellipse` layer, as a stroke item added with\n  `picsart_scene_patch`.\n  `import_svg_path` reads every SVG path command, absolute and relative (M L H V C S Q T A Z,\n  repeated coordinate sets included): quadratics are elevated to cubics, arcs decomposed into\n  cubic beziers, and the smooth shorthands reflect the previous control point. Each subpath\n  becomes one `path` item spelled the Lottie/AE way (`{ closed, vertices: [{ point, inTangent,\n  outTangent }] }`, tangents relative to their point, content-local px); a closed subpath folds its\n  closing tangent onto the start vertex. A gradient is a top-level paint and cannot reach paths\n  nested inside the import's paint group, which is why a gradient outline is imported geometry-only\n  onto its own shape layer and painted after.\n  A shape layer stays crisp at any scale and keeps every motion a shape has — radius and size\n  tweens, recolour, draw-on — where an SVG image only moves as a whole. Whatever the paint tool\n  lists in `skipped` (an inset shadow) is the one part to bring in another way; rasterize\n  **only** a node that is not a shape.\n- **Raster / photographic** — the hero image, a photo, a gradient/blur that won't survive as\n  vector → **PNG with transparency** so the layer floats over what's behind it. Take the image\n  fill's original bitmap from `download_assets` → `rawImages` (the largest), **never the node\n  `export` or `get_screenshot`**: both draw the node over its frame's background colour, so a\n  cutout photo on a dark frame comes back on an opaque black box. The raw bitmap is framed as\n  uploaded, not as the layer shows it: place it by the fill's `scaleMode` (`FILL` → `fit:\n  \"cover\"`, `FIT` → `\"contain\"`, `CROP` → `\"cover\"` plus `crop = [tx·W, ty·H, a·W, d·H]` from its `imageTransform`\n  `[[a, 0, tx], [0, d, ty]]` on a W×H bitmap).\n\nIf you're about to export a PNG of an icon, logo, or shape, that's the tell you *defaulted*\ninstead of decided — go back and take it as vector.\n\n**Settle output scale in the first five minutes, not the fiftieth.** Whether the ad ships at\none size or several (multiple ratios/resolutions, or any later up-scale) is what makes vector\nthe *normal* case, not an edge case — a PNG baked at one scale is soft or jagged at any other,\nwhile vector is resolution-free. Decide this up front (see *Set the format* below); don't\ndiscover the constraint at export time and re-import. And when you do capture\na vector layer, **declare it `type: \"vector\"`** — silently recording a shape as `type: \"image\"`\nis the same defaulting mistake wearing a different hat.\n\n**Format doesn't excuse hosting:** a shape layer carries no asset, but every raster you export\nstill has to be lifted onto a **Picsart-hosted `https://` URL** (below). A `figma.com` URL is\nCSP-blocked in the preview — export → upload → author the returned Picsart URL.\n\n### Granularity — split to what moves\n\nNot every node, and not one blob. **A layer is anything that either moves independently or\npersists across frames.** Group the rest.\n\n- Split out: the headline, each CTA, the hero image, a scrollable list, a tap target,\n  anything that will animate on its own.\n- Keep grouped: static decoration, a card's fixed internals, backgrounds.\n- Over-splitting (hundreds of nodes) is noise the designer must wrangle; under-splitting\n  (the whole screen as one image) is the slideshow trap in disguise. When unsure, split\n  by what the reference ad would animate.\n\n### Import every element the design shows — visibility is the design's call, not yours\n\nImport **every element the design renders**. A layer is dropped for exactly one reason: the\n**design itself hides it** (Figma `visible:false` / a `hidden` node) — that is the designer's\nsignal, and even then a *prominent* hidden layer is worth a note, since it may be meant to appear\nmid-animation. **Never drop a layer because *you* judged it \"won't be seen\":**\n\n- **Partially on-frame** (clipped by the frame edge) is **on screen** — it shows in the very first\n  hold, so omitting it is a visible hole against the design. This is the frame-6 tell: the search\n  pill and the tag row are *clipped, not absent*, and dropping them leaves the composed frame\n  missing content the mockup plainly shows.\n- **Fully off-frame is not a licence to drop it either.** In motion a wide row or an off-edge\n  element is usually there to **scroll or pan into view** — import it and let choreography decide,\n  don't pre-empt the motion by deleting it (that is how a design's intended scroll becomes a\n  static gap).\n\nA judgment call to leave something out is **surfaced to the designer, never silent** — same rule\nas a missing font. The Stage-2 `get_screenshot` compare is what catches a dropped element, as a\nhole where the design has content.\n\n## Tag matched elements across frames\n\nThe thing that makes an interface *move* between screens instead of dissolving is a\n**matched element** — a layer present in consecutive frames that should animate from its\nstate in A to its state in B. So as you import, give any recurring layer a stable\n**`matchKey`** (the same key on the header in every frame it appears in). Match by\nname/role first, geometry second. `motion.json.matched[]` is built from these keys, and\nStage 2 keeps each matched element as **one continuous layer**, not a fresh copy per\nframe. Miss this and the compose step can only cross-dissolve — the biggest \"slideshow\"\ntell there is.\n\n**A recurring element keeps its `matchKey` even when it is transformed or its content changed** —\na title that moves and shrinks, a headline whose wording grows (`AI` → `AI Effects`), a button that\nrecolours. Match by **semantic role** (\"the title\", \"the CTA\"), *never* by exact string or position:\n`AI` and `AI Effects` are the same title. The fact that the same element is **present in both frames\nbut different** is the *strongest* match signal there is — it means the element should **animate from\nA to B**, and it is precisely the case where matching must not fail. A same-role text or object that\nis merely repositioned/resized/reworded must **never** be tagged as one element leaving and a\ndifferent one arriving; that misread is what makes it disappear-and-reappear (or get papered over\nwith a transition) downstream instead of moving.\n\n**Matching is at the layer level — so an assembling sentence needs the layers split to match.**\nThe rule \"a header in frames 1–4 is one layer with four transform states\" is right for chrome, but\nit breaks for text that *grows*: frames whose text reads `AI` → `AI Effects` → `AI Effects made\neasy.` are usually **one whole-string text node each**, i.e. three differently-named layers — so\nnothing marks `AI` as persisting; the thing that actually persists is a **substring**. Capture it\nthat way: split the shared words into their **own layer** carried by one `matchKey` across the\nframes, and each added clause into its own layer that `enter`s. A single whole-string node per\nframe gives the diff three different strings and no persisting layer, and the assembling effect\ncollapses to a cut. (This is the import half of `MOTION-PATTERNS.md` *\"Progressive text build.\"*)\n\nThe A→B **delta** itself (how far a matched layer moved, what actually changed) is not judged\nby eye at motion time — it is **read with `picsart_scene_diff_layouts`** (which resolves both\nframes through `query_layout` and returns the classified delta; `query_layout`-on-both is the\nfallback when the tool is unavailable). The `matchKey` you set here is exactly what that diff\ntakes as its `matchHints` to pair the layers up — a dropped key becomes a missed match there.\nThe full frame-diff procedure is in\n`references/MOTION-PRINCIPLES.md` in the motion-design-craft skill §1.\n\n## Get every asset onto a real URL\n\nA Figma export and a `file://` path are both **unfetchable by the renderer**. So each\nlayer asset that is not already an `https://` URL must be lifted onto one: `picsart_drive_upload_ask`\n(the drag-and-drop panel) or `picsart_drive_upload`, then **read back the resulting `https://` URL and\nauthor *that*.** Text and fills carry no asset and need no lift.\n\n**A scene asset's `uri` must be a Picsart-hosted `https://` URL (`pastatic`/`gcdn`, from\n`picsart_drive_upload_ask` / `picsart_drive_upload`) — never a base64 `data:` URI, and never a `figma.com`\nURL.** The interactive **preview engine runs in a browser with a Content-Security-Policy** whose\n`connect-src` allowlist excludes both — they get **blocked → blank** in the editor preview\n(`csp: blocked connect-src … figma.com/….svg`), even though the scene *validates* and the\nserver-side `export`/`contact_sheet` render them fine. That server/browser split is the trap: a\n`figma.com` URL or a `data:` URI is only ever an **intermediate** — hand it to `upload`/`drive` and\nauthor the **Picsart-hosted URL it returns**. **`validate_scene` and a clean `contact_sheet` do NOT\nprove it renders in the preview** (both are lenient server-side paths) — the only reliable proof is\nthe editor preview itself, so default to Picsart-hosted URLs and it's fine everywhere.\n\n**Drive full (`failure_space_limit_reached`) is status, not a retry.** Every file in the batch fails\nthe same way, so stop at the first one — don't send the rest or the next batch. Tell the designer\ntheir Drive is full and how many assets still need a home, then:\n\n- **Shrink the upload first.** Shapes, text and flat fills need no asset; only true rasters do.\n  A batch full of icons and panels is the vector rule above being skipped.\n- **Offer cleanup, never do it blind.** `picsart_drive_list` (`flat: true`) shows what is there;\n  move only the files the designer names to trash (`picsart_drive_delete` without `permanent` — recoverable),\n  after their explicit yes.\n- **Never route around it** with a `blob:`, `data:` or `figma.com` URL: that is the blank preview\n  (`csp: blocked img-src … blob:`), just later.\n\n## When layers cannot be had — the honest fallback\n\nTwo cases force flat-frame ingest, and both are a **degrade, announced**:\n\n- **No Figma connector.** Suggest it once, and offer the fallback in the same turn —\n  never block, never re-ask, and you cannot connect it for them:\n  > Connecting the Figma connector (Settings → Connectors → Figma) lets me pull your\n  > design's layers, which is what makes real motion design possible. Without it I can\n  > only animate whole flat frames — a slideshow. Share the Figma file, or paste flat\n  > frame images to do the simpler version.\n- **Figma export quota'd out.** Figma export is metered **per Figma seat** and can quota\n  out mid-batch — that is **status, not an error**: continue on the upload path for the\n  remaining assets, and if only flats are reachable, say the result will be a slideshow\n  and offer to resume layered when the seat's quota returns.\n\nA flat frame is imported as a single `image` layer filling the composition — the montage\nfallback in the `animate-design` skill. Say plainly what is lost: *\"without the layers this is a\nslideshow, not motion design.\"*\n\n## Order — take Figma's, never ask for it\n\nThe running order is **Figma's own** — the frame/artboard sequence in the file (or, for\npasted images, the order they were given in). **Take it as authoritative, record it, and\nmove on — do not ask the designer to confirm it.** A question the source already answers is\nnoise — the house rule: *\"don't turn something the pipeline\nalready knows into a user choice.\"*\n\nReordering is **optional and designer-initiated**: it happens on the storyboard board\n(shown for a glance and a drag, never a mandatory confirm) or when the designer explicitly\nsays \"swap 2 and 3.\" Absent that, Figma order stands, silently. Never open an\nASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) to confirm the running order.\n\n## Set the format — ask the ratio and fps\n\nAsk the designer **once, at the start**, in one ASK with two choices, each prefilled with your\npick from the material so they confirm in one reply:\n\n- **ratio** — one of **9:16, 16:9, 1:1, 4:3, 3:4**. Suggest the frames' own aspect (1080×1920 →\n  9:16 at 1080×1920).\n- **fps** — one of **24, 30, 60**. Suggest 30 unless the design says otherwise.\n\nDo not ask anything else here: not the running order (take the design's own), not a total\nduration (it derives from the motion), not the energy. Read the **energy** from the design (see\nbelow), as `calm`, `standard` or `energetic`, and state it in the same message so the designer can\noverrule it. Store the answers as the project's output target (ratio → width/height, fps) and\nuse the default hold and seam.\n\nAlso:\n\n- **output scale/sizes** — not part of that ASK, so default to a single size, but\n  **surface the question when it's genuinely open**: will this ship at one size or several (multiple ratios/resolutions, or a later up-scale)?\n  The answer decides raster-vs-vector for every layer above, and \"multiple sizes\" makes vector the\n  norm — cheap to settle now, expensive to discover at export. When it isn't obvious, a plain\n  an ASK is the right surface; otherwise state the single-size default and move on.\n\nOnce set, the designer can still adjust the format\nin plain conversation (\"make it square\", \"60fps\", \"more energetic\") — a normal message.\n\n**`energy` is a productive↔expressive dial**, not just \"fast vs slow\": *productive* =\nsubtle, efficient motion for routine beats; *expressive* = vibrant, highly-visible motion for\nsignificant moments (an opening, a primary CTA, a hero reveal). It scales the motion's duration\nand easing register downstream — see\n`references/MOTION-PRINCIPLES.md` in the motion-design-craft skill §6.\n\nTwo things are never asked: **order** (taken from Figma silently, above) and **total duration**\n(derived from the motion by default; a soft target is the designer's own pick, and\na designer who wants it tighter says \"punchier\").\n\n## Output → `motion.json`\n\nWrite frames-of-layers and the target (schema in the `animate-design` skill). Each frame carries\na `layers[]` with `id`, `role`, `type`, `transform`, `asset`/`content`, and `matchKey`\nwhere it recurs; `matched[]` is assembled from the keys.\n\n## Gate to pass Stage 1\n\nPrint it with ✓/✗ before compose:\n\n- Every frame imported as **layers** (or consciously flagged flat-fallback with the\n  reason recorded).\n- Every animatable layer has an **asset at a real `https://` URL** (or live text/fill)\n  **and a transform** with z-order.\n- **Every element the design shows is imported** — nothing dropped on a self-made \"won't be\n  visible\" call; a partially-clipped or off-frame layer is still imported. Only designer-hidden\n  layers (`visible:false`) are omitted, and a prominent one is noted.\n- **Matched elements tagged** with `matchKey` across the frames they appear in.\n- **Groups recorded** — every card/control/cell member names its group, so it moves as one.\n- Each layer captured **in its native format** — text is live text, icons/logos/shapes are\n  `type: \"vector\"` (a shape layer), only genuinely raster content is PNG. No vector or text baked to\n  PNG by default.\n- **Order** recorded, **target format** set, and **output scale/sizes** settled.\n\nA frame that came in flat while its layers were available is a **gate failure, not a\nshortcut** — the whole pipeline's value is here.\n\n## Mistakes\n\n- Exporting flat frames when the Figma layers were right there — the slideshow trap at\n  its source.\n- **Silently dropping a design element because you judged it \"won't be visible.\"** A\n  partially-clipped element is *on screen now*; a fully off-frame one usually *scrolls in*. Only a\n  designer-hidden layer is a legitimate skip — and even that is surfaced if prominent, never a\n  silent judgment call.\n- Losing transforms/z-order, so composed layers stack or land wrong.\n- Not tagging matched elements, forcing cross-dissolves later.\n- Over- or under-splitting: hundreds of nodes to wrangle, or one blob that cannot move.\n- **Flattening a vector or text layer to PNG by default** — text should stay live, icons/logos/\n  shapes stay vector; PNG is only for genuinely raster content. Reaching for PNG per element is\n  the freelance-default that softens the ad at any other scale.\n- **Taking a raster from the node `export`** — it flattens transparency onto the frame's\n  background, so a cutout lands on a black box. Use the fill's `rawImages` bitmap.\n- **Declaring a shape layer `type: \"image\"`** — recording vector as raster is the same default\n  wearing a different hat; it loses the resolution-free path.\n- **Dropping a text layer's alignment or box behaviour** — capturing only `x/y/w/h` and then\n  guessing `center`, or losing the fixed-width-clip box so the line soft-wraps to two downstream.\n  Read `textAlignHorizontal` and the box sizing from Figma; don't infer them from position.\n- **Not settling output scale up front** — discovering \"it ships at three sizes\" after baking\n  single-scale PNGs means a re-import; ask it with the ratio and fps in the first five minutes.\n- Binding a Figma link or local path directly — unfetchable; lift to a Picsart-hosted URL first\n  (a `figma.com` SVG is CSP-blocked in preview just like any figma.com asset).\n- Nagging about the Figma connector after the designer already chose the flat path.\n"},"changes":[{"path":"/skill_md_contents","type":"changed","before":"---\nname: design-layer-import\ndescription: Bring a design or static assets into a scene as LAYERS, not flat frames, whenever they are going to move — Figma frames for an ad or reel, or a Figma design, logo, UI screen or screenshot that animates inside a tutorial, promo or explainer — each layer in its native format (live text, vector or raster) on a fetchable hosted URL, with flat frames only as a fallback. Stage 1 of the `animate-design` skill's pipeline, and used before the motion-design-craft skill by any flow that animates a design.\nmetadata:\n  owner: motion-designer\n---\n\n# Stage 1 — Import: the design in as layers\n\nMotion design animates *elements*, so the import's whole job is to bring the design in as\n**layers, not flat frames**. A frame delivered as one sealed PNG can only ever\ncross-dissolve; a frame delivered as its layers — panels, headline, buttons, the image,\nthe list — is a thing whose elements can slide, scroll, type on, parallax and\nsmart-animate. **Everything downstream is gated on this**: if the layers are lost here,\nno amount of tuning later can recover the ad; it stays a slideshow.\n\n## Pull the layer tree, per frame\n\nBefore reading Figma, post the one-line progress message the `animate-design` skill describes\n(\"Reading your layers…\").\n\n**With the Figma connector present**, read structure before pixels: `get_metadata` /\n`get_design_context` to walk each frame's node tree, then export each animatable node as\nits own asset. For every layer capture:\n\n> **AUDIT EVERY NESTED LAYER — never compose from Figma's simplified, frame-level output.** The\n> single biggest way items go missing from the ad: Figma's frame-level / summarized read (a shallow\n> `get_design_context`, or a `get_metadata` that stops at the top level) **collapses nested children**\n> — groups, component instances, auto-layout children, masked contents — into a summary. Take that at\n> face value and **every nested element is silently dropped**, so the composed frame is missing pieces\n> that were plainly in the design. **Recursively expand each frame's FULL tree** (`get_metadata` on the\n> frame node with its children expanded, or `use_figma` to walk *all* descendants) and audit it\n> **node by node** — do not trust a frame-level layer list to be complete. **Completeness check:** the\n> layers you capture must match the count of leaf/animatable nodes in the *fully-expanded* tree, not\n> the handful the frame-level view showed. If a group or instance shows as one node, open it — its\n> children are the layers. (Downstream this is the Stage-2 \"layer count ≈ node count\" gate; catch it\n> here, at the read, not after a frame composes short.)\n\n\n- **id** and **name/role** (what it is — `chrome`, `headline`, `cta`, `image`, `list`, `fx`)\n- **type** — `text`, `vector` (icon/logo/shape), or `raster` (photo/complex image); plus `group`\n- **transform** — `x, y, w, h, rotation, opacity`, and **z-order** (front-to-back)\n- **parent/group** — so a group can move as one: record the group (card, control, grid cell) each\n  layer belongs to, and which member is its backing. Compose turns it into one group that carries\n  the motion (motion-design-craft skill, `references/AUTHORING-FLOW.md` §6); without it the members are\n  keyframed one by one and drift apart\n- **for an image fill, its `scaleMode`** (`FILL` / `FIT` / `CROP` / `TILE`), and for `CROP` its\n  `imageTransform` — they decide the layer's `fit` and `crop`; a raw image placed without them is\n  stretched to the box\n- **for a text layer, also the type properties** — the **string**, resolved **font URL** + size,\n  **horizontal alignment** (read Figma's `textAlignHorizontal` — `left`/`center`/`right`; *never*\n  guess it from position or from \"it's a big headline\"), and the **box sizing/wrap**: a Figma\n  **fixed-width** text box that runs past the frame **clips, it does not wrap** — record the box\n  width and that it clips, or the renderer soft-wraps the line into two downstream.\n\n### Export each layer *as what it is* — PNG is the fallback, not the default\n\nThe layer's **source type** decides the export format. Deciding this per layer is the job;\nreaching for PNG on every element is the freelance-default that quietly wrecks quality —\n**stop and ask \"is this layer actually raster?\" before you export a PNG.**\n\n- **Text** → keep as **live text** (the string + resolved font URL), *never* an image. This is\n  what makes type-on, per-line and per-character animation possible; baking text to PNG kills\n  all of it and can't reflow.\n- **Vector** — icons, logos, line art, panels, pills, flat shapes → a **shape layer**, no asset\n  at all, built in two steps. **First create the layer**: `picsart_scene_patch` adds a\n  layer whose `content.kind` is `\"shape\"`, with a `rect` (or `ellipse`) item sized to the node's\n  box and the node's placement in the layer's `transform`; for a non-rectangular vector (an icon,\n  a logo, a boolean), add the shape layer and append its outline with\n  `picsart_scene_import_svg_path` (the node's path data as `d`). **Then paint it**:\n  `picsart_scene_import_figma_paint` takes the `scene` and that layer's `layerId`, plus the\n  node's CSS from `get_design_context` — `fill`, `boxShadow`, `gradient` (with the element\n  `size`), and `gradientPaint: \"stroke\"` (+ `gradientStrokeWidth`) for a gradient outline. A\n  solid stroke is not a paint it takes: it comes in with a path outline (`import_svg_path`'s\n  `stroke` + `width`), or, on a `rect`/`ellipse` layer, as a stroke item added with\n  `picsart_scene_patch`.\n  `import_svg_path` reads every SVG path command, absolute and relative (M L H V C S Q T A Z,\n  repeated coordinate sets included): quadratics are elevated to cubics, arcs decomposed into\n  cubic beziers, and the smooth shorthands reflect the previous control point. Each subpath\n  becomes one `path` item spelled the Lottie/AE way (`{ closed, vertices: [{ point, inTangent,\n  outTangent }] }`, tangents relative to their point, content-local px); a closed subpath folds its\n  closing tangent onto the start vertex. A gradient is a top-level paint and cannot reach paths\n  nested inside the import's paint group, which is why a gradient outline is imported geometry-only\n  onto its own shape layer and painted after.\n  A shape layer stays crisp at any scale and keeps every motion a shape has — radius and size\n  tweens, recolour, draw-on — where an SVG image only moves as a whole. Whatever the paint tool\n  lists in `skipped` (an inset shadow) is the one part to bring in another way; rasterize\n  **only** a node that is not a shape.\n- **Raster / photographic** — the hero image, a photo, a gradient/blur that won't survive as\n  vector → **PNG with transparency** so the layer floats over what's behind it. Take the image\n  fill's original bitmap from `download_assets` → `rawImages` (the largest), **never the node\n  `export` or `get_screenshot`**: both draw the node over its frame's background colour, so a\n  cutout photo on a dark frame comes back on an opaque black box. The raw bitmap is framed as\n  uploaded, not as the layer shows it: place it by the fill's `scaleMode` (`FILL` → `fit:\n  \"cover\"`, `FIT` → `\"contain\"`, `CROP` → `\"cover\"` plus `crop = [tx·W, ty·H, a·W, d·H]` from its `imageTransform`\n  `[[a, 0, tx], [0, d, ty]]` on a W×H bitmap).\n\nIf you're about to export a PNG of an icon, logo, or shape, that's the tell you *defaulted*\ninstead of decided — go back and take it as vector.\n\n**Settle output scale in the first five minutes, not the fiftieth.** Whether the ad ships at\none size or several (multiple ratios/resolutions, or any later up-scale) is what makes vector\nthe *normal* case, not an edge case — a PNG baked at one scale is soft or jagged at any other,\nwhile vector is resolution-free. Decide this up front (see *Set the format* below); don't\ndiscover the constraint at export time and re-import. And when you do capture\na vector layer, **declare it `type: \"vector\"`** — silently recording a shape as `type: \"image\"`\nis the same defaulting mistake wearing a different hat.\n\n**Format doesn't excuse hosting:** a shape layer carries no asset, but every raster you export\nstill has to be lifted onto a **Picsart-hosted `https://` URL** (below). A `figma.com` URL is\nCSP-blocked in the preview — export → upload → author the returned Picsart URL.\n\n### Granularity — split to what moves\n\nNot every node, and not one blob. **A layer is anything that either moves independently or\npersists across frames.** Group the rest.\n\n- Split out: the headline, each CTA, the hero image, a scrollable list, a tap target,\n  anything that will animate on its own.\n- Keep grouped: static decoration, a card's fixed internals, backgrounds.\n- Over-splitting (hundreds of nodes) is noise the designer must wrangle; under-splitting\n  (the whole screen as one image) is the slideshow trap in disguise. When unsure, split\n  by what the reference ad would animate.\n\n### Import every element the design shows — visibility is the design's call, not yours\n\nImport **every element the design renders**. A layer is dropped for exactly one reason: the\n**design itself hides it** (Figma `visible:false` / a `hidden` node) — that is the designer's\nsignal, and even then a *prominent* hidden layer is worth a note, since it may be meant to appear\nmid-animation. **Never drop a layer because *you* judged it \"won't be seen\":**\n\n- **Partially on-frame** (clipped by the frame edge) is **on screen** — it shows in the very first\n  hold, so omitting it is a visible hole against the design. This is the frame-6 tell: the search\n  pill and the tag row are *clipped, not absent*, and dropping them leaves the composed frame\n  missing content the mockup plainly shows.\n- **Fully off-frame is not a licence to drop it either.** In motion a wide row or an off-edge\n  element is usually there to **scroll or pan into view** — import it and let choreography decide,\n  don't pre-empt the motion by deleting it (that is how a design's intended scroll becomes a\n  static gap).\n\nA judgment call to leave something out is **surfaced to the designer, never silent** — same rule\nas a missing font. The Stage-2 `get_screenshot` compare is what catches a dropped element, as a\nhole where the design has content.\n\n## Tag matched elements across frames\n\nThe thing that makes an interface *move* between screens instead of dissolving is a\n**matched element** — a layer present in consecutive frames that should animate from its\nstate in A to its state in B. So as you import, give any recurring layer a stable\n**`matchKey`** (the same key on the header in every frame it appears in). Match by\nname/role first, geometry second. `motion.json.matched[]` is built from these keys, and\nStage 2 keeps each matched element as **one continuous layer**, not a fresh copy per\nframe. Miss this and the compose step can only cross-dissolve — the biggest \"slideshow\"\ntell there is.\n\n**A recurring element keeps its `matchKey` even when it is transformed or its content changed** —\na title that moves and shrinks, a headline whose wording grows (`AI` → `AI Effects`), a button that\nrecolours. Match by **semantic role** (\"the title\", \"the CTA\"), *never* by exact string or position:\n`AI` and `AI Effects` are the same title. The fact that the same element is **present in both frames\nbut different** is the *strongest* match signal there is — it means the element should **animate from\nA to B**, and it is precisely the case where matching must not fail. A same-role text or object that\nis merely repositioned/resized/reworded must **never** be tagged as one element leaving and a\ndifferent one arriving; that misread is what makes it disappear-and-reappear (or get papered over\nwith a transition) downstream instead of moving.\n\n**Matching is at the layer level — so an assembling sentence needs the layers split to match.**\nThe rule \"a header in frames 1–4 is one layer with four transform states\" is right for chrome, but\nit breaks for text that *grows*: frames whose text reads `AI` → `AI Effects` → `AI Effects made\neasy.` are usually **one whole-string text node each**, i.e. three differently-named layers — so\nnothing marks `AI` as persisting; the thing that actually persists is a **substring**. Capture it\nthat way: split the shared words into their **own layer** carried by one `matchKey` across the\nframes, and each added clause into its own layer that `enter`s. A single whole-string node per\nframe gives the diff three different strings and no persisting layer, and the assembling effect\ncollapses to a cut. (This is the import half of `MOTION-PATTERNS.md` *\"Progressive text build.\"*)\n\nThe A→B **delta** itself (how far a matched layer moved, what actually changed) is not judged\nby eye at motion time — it is **read with `picsart_scene_diff_layouts`** (which resolves both\nframes through `query_layout` and returns the classified delta; `query_layout`-on-both is the\nfallback when the tool is unavailable). The `matchKey` you set here is exactly what that diff\ntakes as its `matchHints` to pair the layers up — a dropped key becomes a missed match there.\nThe full frame-diff procedure is in\n`references/MOTION-PRINCIPLES.md` in the motion-design-craft skill §1.\n\n## Get every asset onto a real URL\n\nA Figma export and a `file://` path are both **unfetchable by the renderer**. So each\nlayer asset that is not already an `https://` URL must be lifted onto one: `picsart_drive_upload_ask`\n(the drag-and-drop panel) or `picsart_drive_upload`, then **read back the resulting `https://` URL and\nauthor *that*.** Text and fills carry no asset and need no lift.\n\n**A scene asset's `uri` must be a Picsart-hosted `https://` URL (`pastatic`/`gcdn`, from\n`picsart_drive_upload_ask` / `picsart_drive_upload`) — never a base64 `data:` URI, and never a `figma.com`\nURL.** The interactive **preview engine runs in a browser with a Content-Security-Policy** whose\n`connect-src` allowlist excludes both — they get **blocked → blank** in the editor preview\n(`csp: blocked connect-src … figma.com/….svg`), even though the scene *validates* and the\nserver-side `export`/`contact_sheet` render them fine. That server/browser split is the trap: a\n`figma.com` URL or a `data:` URI is only ever an **intermediate** — hand it to `upload`/`drive` and\nauthor the **Picsart-hosted URL it returns**. **`validate_scene` and a clean `contact_sheet` do NOT\nprove it renders in the preview** (both are lenient server-side paths) — the only reliable proof is\nthe editor preview itself, so default to Picsart-hosted URLs and it's fine everywhere.\n\n**Drive full (`failure_space_limit_reached`) is status, not a retry.** Every file in the batch fails\nthe same way, so stop at the first one — don't send the rest or the next batch. Tell the designer\ntheir Drive is full and how many assets still need a home, then:\n\n- **Shrink the upload first.** Shapes, text and flat fills need no asset; only true rasters do.\n  A batch full of icons and panels is the vector rule above being skipped.\n- **Offer cleanup, never do it blind.** `picsart_drive_list` (`flat: true`) shows what is there;\n  move only the files the designer names to trash (`picsart_drive_delete` without `permanent` — recoverable),\n  after their explicit yes.\n- **Never route around it** with a `blob:`, `data:` or `figma.com` URL: that is the blank preview\n  (`csp: blocked img-src … blob:`), just later.\n\n## When layers cannot be had — the honest fallback\n\nTwo cases force flat-frame ingest, and both are a **degrade, announced**:\n\n- **No Figma connector.** Suggest it once, and offer the fallback in the same turn —\n  never block, never re-ask, and you cannot connect it for them:\n  > Connecting the Figma connector (Settings → Connectors → Figma) lets me pull your\n  > design's layers, which is what makes real motion design possible. Without it I can\n  > only animate whole flat frames — a slideshow. Share the Figma file, or paste flat\n  > frame images to do the simpler version.\n- **Figma export quota'd out.** Figma export is metered **per Figma seat** and can quota\n  out mid-batch — that is **status, not an error**: continue on the upload path for the\n  remaining assets, and if only flats are reachable, say the result will be a slideshow\n  and offer to resume layered when the seat's quota returns.\n\nA flat frame is imported as a single `image` layer filling the composition — the montage\nfallback in the `animate-design` skill. Say plainly what is lost: *\"without the layers this is a\nslideshow, not motion design.\"*\n\n## Order — take Figma's, never ask for it\n\nThe running order is **Figma's own** — the frame/artboard sequence in the file (or, for\npasted images, the order they were given in). **Take it as authoritative, record it, and\nmove on — do not ask the designer to confirm it.** A question the source already answers is\nnoise — the house rule: *\"don't turn something the pipeline\nalready knows into a user choice.\"*\n\nReordering is **optional and designer-initiated**: it happens on the storyboard board\n(shown for a glance and a drag, never a mandatory confirm) or when the designer explicitly\nsays \"swap 2 and 3.\" Absent that, Figma order stands, silently. Never open an\nASK to confirm the running order.\n\n## Set the format — the Motion Setup console\n\nOpen **`picsart_scene_setup` once, at the start**, prefilled so it opens on the design rather\nthan a blank form (it is free and read-only):\n\n- **`frames`** — the design frames in running order (Figma's own, above), each with its `id`, a\n  **Picsart-hosted** `url` (a `figma.com` export is saved with `picsart_drive_upload` first) and its\n  `w`/`h`.\n- **`suggested.selections`** — always the **ratio** from the frames' own aspect (1080×1920 →\n  9:16) and the **energy** read from the design (see below), as one of the console's own values:\n  `calm`, `standard` or `energetic` (any other value is dropped); fps 30 unless the design says\n  otherwise. **Never prefill a total duration** — it derives from the motion.\n- **`current`** — only when reopening a setup the designer already locked.\n\nDo not ask the designer for the running order (take the design's own) or for a total\nduration (it derives from the motion). Opening it is the whole turn; wait for the lock. Its reply, `motion_setup_feedback`, is read as\nthe motion-design-craft skill's `references/WIDGET-FEEDBACK.md` says: store `selections` as the target\nand the hold/seam defaults, and quote `summary` verbatim.\n\n**When `picsart_scene_setup` is not in your list or errors**, decide the format yourself from\nthe material — **infer it, state it, and proceed**:\n\n- **ratio / resolution** — from the frames' own aspect (1080×1920 → 9:16 at 1080×1920). Take what\n  the design already is.\n- **fps** — 30 by default.\n- **energy** — read from the design (see below); pick the register the ad calls for.\n\nEither way:\n\n- **output scale/sizes** — the console does not carry it, so default to a single size, but\n  **surface the question when it's genuinely open**: will this ship at one size or several (multiple ratios/resolutions, or a later up-scale)?\n  The answer decides raster-vs-vector for every layer above, and \"multiple sizes\" makes vector the\n  norm — cheap to settle now, expensive to discover at export. When it isn't obvious, a plain\n  an ASK is the right surface; otherwise state the single-size default and move on.\n\nWithout the console, state the chosen ratio/fps/energy to the designer in one line and let them\nadjust in plain conversation (\"make it square\", \"60fps\", \"more energetic\") — a normal message.\n\n**`energy` is a productive↔expressive dial**, not just \"fast vs slow\": *productive* =\nsubtle, efficient motion for routine beats; *expressive* = vibrant, highly-visible motion for\nsignificant moments (an opening, a primary CTA, a hero reveal). It scales the motion's duration\nand easing register downstream — see\n`references/MOTION-PRINCIPLES.md` in the motion-design-craft skill §6.\n\nTwo things are never asked: **order** (taken from Figma silently, above) and **total duration**\n(derived from the motion by default; a soft target is the designer's own pick on the console, and\na designer who wants it tighter says \"punchier\").\n\n## Output → `motion.json`\n\nWrite frames-of-layers and the target (schema in the `animate-design` skill). Each frame carries\na `layers[]` with `id`, `role`, `type`, `transform`, `asset`/`content`, and `matchKey`\nwhere it recurs; `matched[]` is assembled from the keys.\n\n## Gate to pass Stage 1\n\nPrint it with ✓/✗ before compose:\n\n- Every frame imported as **layers** (or consciously flagged flat-fallback with the\n  reason recorded).\n- Every animatable layer has an **asset at a real `https://` URL** (or live text/fill)\n  **and a transform** with z-order.\n- **Every element the design shows is imported** — nothing dropped on a self-made \"won't be\n  visible\" call; a partially-clipped or off-frame layer is still imported. Only designer-hidden\n  layers (`visible:false`) are omitted, and a prominent one is noted.\n- **Matched elements tagged** with `matchKey` across the frames they appear in.\n- **Groups recorded** — every card/control/cell member names its group, so it moves as one.\n- Each layer captured **in its native format** — text is live text, icons/logos/shapes are\n  `type: \"vector\"` (a shape layer), only genuinely raster content is PNG. No vector or text baked to\n  PNG by default.\n- **Order** recorded, **target format** set, and **output scale/sizes** settled.\n\nA frame that came in flat while its layers were available is a **gate failure, not a\nshortcut** — the whole pipeline's value is here.\n\n## Mistakes\n\n- Exporting flat frames when the Figma layers were right there — the slideshow trap at\n  its source.\n- **Silently dropping a design element because you judged it \"won't be visible.\"** A\n  partially-clipped element is *on screen now*; a fully off-frame one usually *scrolls in*. Only a\n  designer-hidden layer is a legitimate skip — and even that is surfaced if prominent, never a\n  silent judgment call.\n- Losing transforms/z-order, so composed layers stack or land wrong.\n- Not tagging matched elements, forcing cross-dissolves later.\n- Over- or under-splitting: hundreds of nodes to wrangle, or one blob that cannot move.\n- **Flattening a vector or text layer to PNG by default** — text should stay live, icons/logos/\n  shapes stay vector; PNG is only for genuinely raster content. Reaching for PNG per element is\n  the freelance-default that softens the ad at any other scale.\n- **Taking a raster from the node `export`** — it flattens transparency onto the frame's\n  background, so a cutout lands on a black box. Use the fill's `rawImages` bitmap.\n- **Declaring a shape layer `type: \"image\"`** — recording vector as raster is the same default\n  wearing a different hat; it loses the resolution-free path.\n- **Dropping a text layer's alignment or box behaviour** — capturing only `x/y/w/h` and then\n  guessing `center`, or losing the fixed-width-clip box so the line soft-wraps to two downstream.\n  Read `textAlignHorizontal` and the box sizing from Figma; don't infer them from position.\n- **Not settling output scale up front** — discovering \"it ships at three sizes\" after baking\n  single-scale PNGs means a re-import; ask it on the setup panel in the first five minutes.\n- Binding a Figma link or local path directly — unfetchable; lift to a Picsart-hosted URL first\n  (a `figma.com` SVG is CSP-blocked in preview just like any figma.com asset).\n- Nagging about the Figma connector after the designer already chose the flat path.\n","after":"---\nname: design-layer-import\ndescription: Bring a design or static assets into a scene as LAYERS, not flat frames, whenever they are going to move — Figma frames for an ad or reel, or a Figma design, logo, UI screen or screenshot that animates inside a tutorial, promo or explainer — each layer in its native format (live text, vector or raster) on a fetchable hosted URL, with flat frames only as a fallback. Stage 1 of the `animate-design` skill's pipeline, and used before the motion-design-craft skill by any flow that animates a design.\nmetadata:\n  owner: motion-designer\n---\n\n# Stage 1 — Import: the design in as layers\n\nMotion design animates *elements*, so the import's whole job is to bring the design in as\n**layers, not flat frames**. A frame delivered as one sealed PNG can only ever\ncross-dissolve; a frame delivered as its layers — panels, headline, buttons, the image,\nthe list — is a thing whose elements can slide, scroll, type on, parallax and\nsmart-animate. **Everything downstream is gated on this**: if the layers are lost here,\nno amount of tuning later can recover the ad; it stays a slideshow.\n\n## Pull the layer tree, per frame\n\nBefore reading Figma, post the one-line progress message the `animate-design` skill describes\n(\"Reading your layers…\").\n\n**With the Figma connector present**, read structure before pixels: `get_metadata` /\n`get_design_context` to walk each frame's node tree, then export each animatable node as\nits own asset. For every layer capture:\n\n> **AUDIT EVERY NESTED LAYER — never compose from Figma's simplified, frame-level output.** The\n> single biggest way items go missing from the ad: Figma's frame-level / summarized read (a shallow\n> `get_design_context`, or a `get_metadata` that stops at the top level) **collapses nested children**\n> — groups, component instances, auto-layout children, masked contents — into a summary. Take that at\n> face value and **every nested element is silently dropped**, so the composed frame is missing pieces\n> that were plainly in the design. **Recursively expand each frame's FULL tree** (`get_metadata` on the\n> frame node with its children expanded, or `use_figma` to walk *all* descendants) and audit it\n> **node by node** — do not trust a frame-level layer list to be complete. **Completeness check:** the\n> layers you capture must match the count of leaf/animatable nodes in the *fully-expanded* tree, not\n> the handful the frame-level view showed. If a group or instance shows as one node, open it — its\n> children are the layers. (Downstream this is the Stage-2 \"layer count ≈ node count\" gate; catch it\n> here, at the read, not after a frame composes short.)\n\n\n- **id** and **name/role** (what it is — `chrome`, `headline`, `cta`, `image`, `list`, `fx`)\n- **type** — `text`, `vector` (icon/logo/shape), or `raster` (photo/complex image); plus `group`\n- **transform** — `x, y, w, h, rotation, opacity`, and **z-order** (front-to-back)\n- **parent/group** — so a group can move as one: record the group (card, control, grid cell) each\n  layer belongs to, and which member is its backing. Compose turns it into one group that carries\n  the motion (motion-design-craft skill, `references/AUTHORING-FLOW.md` §6); without it the members are\n  keyframed one by one and drift apart\n- **for an image fill, its `scaleMode`** (`FILL` / `FIT` / `CROP` / `TILE`), and for `CROP` its\n  `imageTransform` — they decide the layer's `fit` and `crop`; a raw image placed without them is\n  stretched to the box\n- **for a text layer, also the type properties** — the **string**, resolved **font URL** + size,\n  **horizontal alignment** (read Figma's `textAlignHorizontal` — `left`/`center`/`right`; *never*\n  guess it from position or from \"it's a big headline\"), and the **box sizing/wrap**: a Figma\n  **fixed-width** text box that runs past the frame **clips, it does not wrap** — record the box\n  width and that it clips, or the renderer soft-wraps the line into two downstream.\n\n### Export each layer *as what it is* — PNG is the fallback, not the default\n\nThe layer's **source type** decides the export format. Deciding this per layer is the job;\nreaching for PNG on every element is the freelance-default that quietly wrecks quality —\n**stop and ask \"is this layer actually raster?\" before you export a PNG.**\n\n- **Text** → keep as **live text** (the string + resolved font URL), *never* an image. This is\n  what makes type-on, per-line and per-character animation possible; baking text to PNG kills\n  all of it and can't reflow.\n- **Vector** — icons, logos, line art, panels, pills, flat shapes → a **shape layer**, no asset\n  at all, built in two steps. **First create the layer**: `picsart_scene_patch` adds a\n  layer whose `content.kind` is `\"shape\"`, with a `rect` (or `ellipse`) item sized to the node's\n  box and the node's placement in the layer's `transform`; for a non-rectangular vector (an icon,\n  a logo, a boolean), add the shape layer and append its outline with\n  `picsart_scene_import_svg_path` (the node's path data as `d`). **Then paint it**:\n  `picsart_scene_import_figma_paint` takes the `scene` and that layer's `layerId`, plus the\n  node's CSS from `get_design_context` — `fill`, `boxShadow`, `gradient` (with the element\n  `size`), and `gradientPaint: \"stroke\"` (+ `gradientStrokeWidth`) for a gradient outline. A\n  solid stroke is not a paint it takes: it comes in with a path outline (`import_svg_path`'s\n  `stroke` + `width`), or, on a `rect`/`ellipse` layer, as a stroke item added with\n  `picsart_scene_patch`.\n  `import_svg_path` reads every SVG path command, absolute and relative (M L H V C S Q T A Z,\n  repeated coordinate sets included): quadratics are elevated to cubics, arcs decomposed into\n  cubic beziers, and the smooth shorthands reflect the previous control point. Each subpath\n  becomes one `path` item spelled the Lottie/AE way (`{ closed, vertices: [{ point, inTangent,\n  outTangent }] }`, tangents relative to their point, content-local px); a closed subpath folds its\n  closing tangent onto the start vertex. A gradient is a top-level paint and cannot reach paths\n  nested inside the import's paint group, which is why a gradient outline is imported geometry-only\n  onto its own shape layer and painted after.\n  A shape layer stays crisp at any scale and keeps every motion a shape has — radius and size\n  tweens, recolour, draw-on — where an SVG image only moves as a whole. Whatever the paint tool\n  lists in `skipped` (an inset shadow) is the one part to bring in another way; rasterize\n  **only** a node that is not a shape.\n- **Raster / photographic** — the hero image, a photo, a gradient/blur that won't survive as\n  vector → **PNG with transparency** so the layer floats over what's behind it. Take the image\n  fill's original bitmap from `download_assets` → `rawImages` (the largest), **never the node\n  `export` or `get_screenshot`**: both draw the node over its frame's background colour, so a\n  cutout photo on a dark frame comes back on an opaque black box. The raw bitmap is framed as\n  uploaded, not as the layer shows it: place it by the fill's `scaleMode` (`FILL` → `fit:\n  \"cover\"`, `FIT` → `\"contain\"`, `CROP` → `\"cover\"` plus `crop = [tx·W, ty·H, a·W, d·H]` from its `imageTransform`\n  `[[a, 0, tx], [0, d, ty]]` on a W×H bitmap).\n\nIf you're about to export a PNG of an icon, logo, or shape, that's the tell you *defaulted*\ninstead of decided — go back and take it as vector.\n\n**Settle output scale in the first five minutes, not the fiftieth.** Whether the ad ships at\none size or several (multiple ratios/resolutions, or any later up-scale) is what makes vector\nthe *normal* case, not an edge case — a PNG baked at one scale is soft or jagged at any other,\nwhile vector is resolution-free. Decide this up front (see *Set the format* below); don't\ndiscover the constraint at export time and re-import. And when you do capture\na vector layer, **declare it `type: \"vector\"`** — silently recording a shape as `type: \"image\"`\nis the same defaulting mistake wearing a different hat.\n\n**Format doesn't excuse hosting:** a shape layer carries no asset, but every raster you export\nstill has to be lifted onto a **Picsart-hosted `https://` URL** (below). A `figma.com` URL is\nCSP-blocked in the preview — export → upload → author the returned Picsart URL.\n\n### Granularity — split to what moves\n\nNot every node, and not one blob. **A layer is anything that either moves independently or\npersists across frames.** Group the rest.\n\n- Split out: the headline, each CTA, the hero image, a scrollable list, a tap target,\n  anything that will animate on its own.\n- Keep grouped: static decoration, a card's fixed internals, backgrounds.\n- Over-splitting (hundreds of nodes) is noise the designer must wrangle; under-splitting\n  (the whole screen as one image) is the slideshow trap in disguise. When unsure, split\n  by what the reference ad would animate.\n\n### Import every element the design shows — visibility is the design's call, not yours\n\nImport **every element the design renders**. A layer is dropped for exactly one reason: the\n**design itself hides it** (Figma `visible:false` / a `hidden` node) — that is the designer's\nsignal, and even then a *prominent* hidden layer is worth a note, since it may be meant to appear\nmid-animation. **Never drop a layer because *you* judged it \"won't be seen\":**\n\n- **Partially on-frame** (clipped by the frame edge) is **on screen** — it shows in the very first\n  hold, so omitting it is a visible hole against the design. This is the frame-6 tell: the search\n  pill and the tag row are *clipped, not absent*, and dropping them leaves the composed frame\n  missing content the mockup plainly shows.\n- **Fully off-frame is not a licence to drop it either.** In motion a wide row or an off-edge\n  element is usually there to **scroll or pan into view** — import it and let choreography decide,\n  don't pre-empt the motion by deleting it (that is how a design's intended scroll becomes a\n  static gap).\n\nA judgment call to leave something out is **surfaced to the designer, never silent** — same rule\nas a missing font. The Stage-2 `get_screenshot` compare is what catches a dropped element, as a\nhole where the design has content.\n\n## Tag matched elements across frames\n\nThe thing that makes an interface *move* between screens instead of dissolving is a\n**matched element** — a layer present in consecutive frames that should animate from its\nstate in A to its state in B. So as you import, give any recurring layer a stable\n**`matchKey`** (the same key on the header in every frame it appears in). Match by\nname/role first, geometry second. `motion.json.matched[]` is built from these keys, and\nStage 2 keeps each matched element as **one continuous layer**, not a fresh copy per\nframe. Miss this and the compose step can only cross-dissolve — the biggest \"slideshow\"\ntell there is.\n\n**A recurring element keeps its `matchKey` even when it is transformed or its content changed** —\na title that moves and shrinks, a headline whose wording grows (`AI` → `AI Effects`), a button that\nrecolours. Match by **semantic role** (\"the title\", \"the CTA\"), *never* by exact string or position:\n`AI` and `AI Effects` are the same title. The fact that the same element is **present in both frames\nbut different** is the *strongest* match signal there is — it means the element should **animate from\nA to B**, and it is precisely the case where matching must not fail. A same-role text or object that\nis merely repositioned/resized/reworded must **never** be tagged as one element leaving and a\ndifferent one arriving; that misread is what makes it disappear-and-reappear (or get papered over\nwith a transition) downstream instead of moving.\n\n**Matching is at the layer level — so an assembling sentence needs the layers split to match.**\nThe rule \"a header in frames 1–4 is one layer with four transform states\" is right for chrome, but\nit breaks for text that *grows*: frames whose text reads `AI` → `AI Effects` → `AI Effects made\neasy.` are usually **one whole-string text node each**, i.e. three differently-named layers — so\nnothing marks `AI` as persisting; the thing that actually persists is a **substring**. Capture it\nthat way: split the shared words into their **own layer** carried by one `matchKey` across the\nframes, and each added clause into its own layer that `enter`s. A single whole-string node per\nframe gives the diff three different strings and no persisting layer, and the assembling effect\ncollapses to a cut. (This is the import half of `MOTION-PATTERNS.md` *\"Progressive text build.\"*)\n\nThe A→B **delta** itself (how far a matched layer moved, what actually changed) is not judged\nby eye at motion time — it is **read with `picsart_scene_diff_layouts`** (which resolves both\nframes through `query_layout` and returns the classified delta; `query_layout`-on-both is the\nfallback when the tool is unavailable). The `matchKey` you set here is exactly what that diff\ntakes as its `matchHints` to pair the layers up — a dropped key becomes a missed match there.\nThe full frame-diff procedure is in\n`references/MOTION-PRINCIPLES.md` in the motion-design-craft skill §1.\n\n## Get every asset onto a real URL\n\nA Figma export and a `file://` path are both **unfetchable by the renderer**. So each\nlayer asset that is not already an `https://` URL must be lifted onto one: `picsart_drive_upload_ask`\n(the drag-and-drop panel) or `picsart_drive_upload`, then **read back the resulting `https://` URL and\nauthor *that*.** Text and fills carry no asset and need no lift.\n\n**A scene asset's `uri` must be a Picsart-hosted `https://` URL (`pastatic`/`gcdn`, from\n`picsart_drive_upload_ask` / `picsart_drive_upload`) — never a base64 `data:` URI, and never a `figma.com`\nURL.** The interactive **preview engine runs in a browser with a Content-Security-Policy** whose\n`connect-src` allowlist excludes both — they get **blocked → blank** in the editor preview\n(`csp: blocked connect-src … figma.com/….svg`), even though the scene *validates* and the\nserver-side `export`/`contact_sheet` render them fine. That server/browser split is the trap: a\n`figma.com` URL or a `data:` URI is only ever an **intermediate** — hand it to `upload`/`drive` and\nauthor the **Picsart-hosted URL it returns**. **`validate_scene` and a clean `contact_sheet` do NOT\nprove it renders in the preview** (both are lenient server-side paths) — the only reliable proof is\nthe editor preview itself, so default to Picsart-hosted URLs and it's fine everywhere.\n\n**Drive full (`failure_space_limit_reached`) is status, not a retry.** Every file in the batch fails\nthe same way, so stop at the first one — don't send the rest or the next batch. Tell the designer\ntheir Drive is full and how many assets still need a home, then:\n\n- **Shrink the upload first.** Shapes, text and flat fills need no asset; only true rasters do.\n  A batch full of icons and panels is the vector rule above being skipped.\n- **Offer cleanup, never do it blind.** `picsart_drive_list` (`flat: true`) shows what is there;\n  move only the files the designer names to trash (`picsart_drive_delete` without `permanent` — recoverable),\n  after their explicit yes.\n- **Never route around it** with a `blob:`, `data:` or `figma.com` URL: that is the blank preview\n  (`csp: blocked img-src … blob:`), just later.\n\n## When layers cannot be had — the honest fallback\n\nTwo cases force flat-frame ingest, and both are a **degrade, announced**:\n\n- **No Figma connector.** Suggest it once, and offer the fallback in the same turn —\n  never block, never re-ask, and you cannot connect it for them:\n  > Connecting the Figma connector (Settings → Connectors → Figma) lets me pull your\n  > design's layers, which is what makes real motion design possible. Without it I can\n  > only animate whole flat frames — a slideshow. Share the Figma file, or paste flat\n  > frame images to do the simpler version.\n- **Figma export quota'd out.** Figma export is metered **per Figma seat** and can quota\n  out mid-batch — that is **status, not an error**: continue on the upload path for the\n  remaining assets, and if only flats are reachable, say the result will be a slideshow\n  and offer to resume layered when the seat's quota returns.\n\nA flat frame is imported as a single `image` layer filling the composition — the montage\nfallback in the `animate-design` skill. Say plainly what is lost: *\"without the layers this is a\nslideshow, not motion design.\"*\n\n## Order — take Figma's, never ask for it\n\nThe running order is **Figma's own** — the frame/artboard sequence in the file (or, for\npasted images, the order they were given in). **Take it as authoritative, record it, and\nmove on — do not ask the designer to confirm it.** A question the source already answers is\nnoise — the house rule: *\"don't turn something the pipeline\nalready knows into a user choice.\"*\n\nReordering is **optional and designer-initiated**: it happens on the storyboard board\n(shown for a glance and a drag, never a mandatory confirm) or when the designer explicitly\nsays \"swap 2 and 3.\" Absent that, Figma order stands, silently. Never open an\nASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) to confirm the running order.\n\n## Set the format — ask the ratio and fps\n\nAsk the designer **once, at the start**, in one ASK with two choices, each prefilled with your\npick from the material so they confirm in one reply:\n\n- **ratio** — one of **9:16, 16:9, 1:1, 4:3, 3:4**. Suggest the frames' own aspect (1080×1920 →\n  9:16 at 1080×1920).\n- **fps** — one of **24, 30, 60**. Suggest 30 unless the design says otherwise.\n\nDo not ask anything else here: not the running order (take the design's own), not a total\nduration (it derives from the motion), not the energy. Read the **energy** from the design (see\nbelow), as `calm`, `standard` or `energetic`, and state it in the same message so the designer can\noverrule it. Store the answers as the project's output target (ratio → width/height, fps) and\nuse the default hold and seam.\n\nAlso:\n\n- **output scale/sizes** — not part of that ASK, so default to a single size, but\n  **surface the question when it's genuinely open**: will this ship at one size or several (multiple ratios/resolutions, or a later up-scale)?\n  The answer decides raster-vs-vector for every layer above, and \"multiple sizes\" makes vector the\n  norm — cheap to settle now, expensive to discover at export. When it isn't obvious, a plain\n  an ASK is the right surface; otherwise state the single-size default and move on.\n\nOnce set, the designer can still adjust the format\nin plain conversation (\"make it square\", \"60fps\", \"more energetic\") — a normal message.\n\n**`energy` is a productive↔expressive dial**, not just \"fast vs slow\": *productive* =\nsubtle, efficient motion for routine beats; *expressive* = vibrant, highly-visible motion for\nsignificant moments (an opening, a primary CTA, a hero reveal). It scales the motion's duration\nand easing register downstream — see\n`references/MOTION-PRINCIPLES.md` in the motion-design-craft skill §6.\n\nTwo things are never asked: **order** (taken from Figma silently, above) and **total duration**\n(derived from the motion by default; a soft target is the designer's own pick, and\na designer who wants it tighter says \"punchier\").\n\n## Output → `motion.json`\n\nWrite frames-of-layers and the target (schema in the `animate-design` skill). Each frame carries\na `layers[]` with `id`, `role`, `type`, `transform`, `asset`/`content`, and `matchKey`\nwhere it recurs; `matched[]` is assembled from the keys.\n\n## Gate to pass Stage 1\n\nPrint it with ✓/✗ before compose:\n\n- Every frame imported as **layers** (or consciously flagged flat-fallback with the\n  reason recorded).\n- Every animatable layer has an **asset at a real `https://` URL** (or live text/fill)\n  **and a transform** with z-order.\n- **Every element the design shows is imported** — nothing dropped on a self-made \"won't be\n  visible\" call; a partially-clipped or off-frame layer is still imported. Only designer-hidden\n  layers (`visible:false`) are omitted, and a prominent one is noted.\n- **Matched elements tagged** with `matchKey` across the frames they appear in.\n- **Groups recorded** — every card/control/cell member names its group, so it moves as one.\n- Each layer captured **in its native format** — text is live text, icons/logos/shapes are\n  `type: \"vector\"` (a shape layer), only genuinely raster content is PNG. No vector or text baked to\n  PNG by default.\n- **Order** recorded, **target format** set, and **output scale/sizes** settled.\n\nA frame that came in flat while its layers were available is a **gate failure, not a\nshortcut** — the whole pipeline's value is here.\n\n## Mistakes\n\n- Exporting flat frames when the Figma layers were right there — the slideshow trap at\n  its source.\n- **Silently dropping a design element because you judged it \"won't be visible.\"** A\n  partially-clipped element is *on screen now*; a fully off-frame one usually *scrolls in*. Only a\n  designer-hidden layer is a legitimate skip — and even that is surfaced if prominent, never a\n  silent judgment call.\n- Losing transforms/z-order, so composed layers stack or land wrong.\n- Not tagging matched elements, forcing cross-dissolves later.\n- Over- or under-splitting: hundreds of nodes to wrangle, or one blob that cannot move.\n- **Flattening a vector or text layer to PNG by default** — text should stay live, icons/logos/\n  shapes stay vector; PNG is only for genuinely raster content. Reaching for PNG per element is\n  the freelance-default that softens the ad at any other scale.\n- **Taking a raster from the node `export`** — it flattens transparency onto the frame's\n  background, so a cutout lands on a black box. Use the fill's `rawImages` bitmap.\n- **Declaring a shape layer `type: \"image\"`** — recording vector as raster is the same default\n  wearing a different hat; it loses the resolution-free path.\n- **Dropping a text layer's alignment or box behaviour** — capturing only `x/y/w/h` and then\n  guessing `center`, or losing the fixed-width-clip box so the line soft-wraps to two downstream.\n  Read `textAlignHorizontal` and the box sizing from Figma; don't infer them from position.\n- **Not settling output scale up front** — discovering \"it ships at three sizes\" after baking\n  single-scale PNGs means a re-import; ask it with the ratio and fps in the first five minutes.\n- Binding a Figma link or local path directly — unfetchable; lift to a Picsart-hosted URL first\n  (a `figma.com` SVG is CSP-blocked in preview just like any figma.com asset).\n- Nagging about the Figma connector after the designer already chose the flat path.\n"}],"summary":"Fields changed: 1. /skill_md_contents.","summary_kind":"deterministic","summary_metadata":{}}