` groups; a `

` does NOT — pick hint-bearing names for every semantic unit. (Also needs: ≥100×32 px, not near-full-frame, ≥2 child layers.) - **Opt out** only for a deliberately flat single-element frame: pass `usePrecomps:false`. - **If the auto-grouping missed a unit** (non-hint class, too small), or you need to (re)group AFTER the build, do it explicitly with `ae_precompose_layers({ compositionName, layerNames: [...the card's layers], name: "card-revenue", moveAttributes: true })` — a 2-layer pill/badge is NOT too small to bother. One precomp per semantic container; name each precomp clearly (`card-revenue`, `nav-bar`, `chart-panel`). - **Order:** build + verify the layers first, THEN precompose, THEN add group-level motion (the `data-anim` entrances still apply; precomps let you animate the whole group, not just leaves). --- ## When this pipeline is the right choice - **Consider `ae_build_scene_from_html`** for a whole layout/scene whose full structure is faster to write once as HTML/CSS than to place natively — title cards, lower-thirds, infographics, dashboards, stat cards, hero frames. - **The atomic `ae_*` tools** (`ae_create_composition`, `ae_add_shape_layer`, `ae_add_text_layer`, `ae_set_keyframe`, `ae_create_text_animator`, ...) are the default builder, and the only path for surgical edits to an EXISTING comp. - **Commit to one path per frame.** Do not hand-re-assemble with atomic tools what this pipeline already produced in one call. If `build_scene` fails, either fix the pipeline (most often: restart After Effects so the plugin reloads its jsx) or build that frame natively — do not interleave the two. --- ## Reference intake — ALWAYS measure with vision_analyze first **If the request carries a visual reference (an image URL/attachment or a website), you MUST run `vision_analyze` on it BEFORE authoring the HTML.** Eyeballed colors, radii, and positions are the #1 cause of "looks off" results — measure, don't guess. - **Image reference:** call `vision_analyze` with ONE image and ask for: every element's bounding box **as FRACTIONS (0..1) of the image** (vision is unreliable at absolute pixels, solid at fractions), exact **hex colors** (background, card fill, accents, text tiers — sampled, not named by eye), corner radii as fractions of width, font-size tiers as fractions of height, and an element inventory (icons named semantically: pencil / briefcase / ticket...). Multiply fractions by the comp size to get px for the HTML. - **Website reference:** screenshot it first (browser tool), then run the same `vision_analyze` measurement on the screenshot. - One image per call — arrays double-stringify and fail (see the vision_analyze note below). For a compare, composite first. - **Sample exact values when reachable:** `vision_analyze` is great for layout and an inventory, but for EXACT colours / corner radii / font sizes call `ae_measure_reference(url|key, ops:[…])` — it reads the actual pixels (returns `rgb:{r,g,b}` 0-1 ready for AE) when the reference is reachable as a URL/R2 key. Eyeballed/named values are the #1 cause of "looks off". - **Close the loop after the build (numbers, then eyes):** when a reference exists, run `ae_audit_frame(compositionName, reference_url|reference_key)` — it renders the settled frame and scores it against the reference cell-by-cell in CIE-Lab. `ok` is the deterministic gate (`flaggedPct ≤ 5%` & `meanDE ≤ 8`); `worstCells` localise the drift (render px + ref/render colour) and `scanlines`/`stripeCountMismatch` give exact repeating-geometry numbers. THEN also view `renderUrl` (or `vision_analyze` a side-by-side) for the semantic half — layout/copy/spacing the audit can't see. Fix the HTML and rebuild until the gate passes AND a designer wouldn't flag it. --- ## Figma / SVG reference -> faithful AE vectors Inline `` | the pipeline imports the image as a footage layer | | **Soft glow / bloom** | a `

` with `mix-blend-mode:screen` | renders as a screen-blended layer (no post effect needed) | | **Texture (dot-grid, hatch)** | inline SVG `` | becomes a tiled shape/footage layer | **After a SUCCESSFUL build you may ONLY tweak EXISTING layers** (nudge position, restyle, retime). **NEVER** `ae_add_shape_layer` / `ae_set_keyframe` / recolor- via-effect something the HTML could have expressed — if it's wrong, fix the HTML and rebuild. The HTML is the single source of truth for the frame. ### Icons = Lucide (https://lucide.dev — 1500+ icons, ISC) **Use the Lucide icon set — by name, with its real path data.** Never invent icon geometry. Write each icon as inline SVG in the canonical Lucide format and it comes through as smooth, stroked **bezier shape layers** (editable + animatable; recolor later via `ae_set_shape_fill` stroke/fill): ```html ``` Set `stroke` to an EXPLICIT color (not `currentColor`); size/position via `width`/`height` + absolute positioning. Real Lucide path data (v1.17.0) for common icons — paste the inner elements into the wrapper above: ```html ``` **Raster fallback** — for any Lucide icon whose exact path data you don't know, reference it by name and let the pipeline rasterize it into an image layer: ```html

``` Inline SVG is preferred (editable vector layers); the `` fallback is safe (the bridge downloads + rasterizes SVG to PNG — AE can't import SVG directly) but yields a raster layer you can't restroke. Pick names from the Lucide set: pencil, briefcase, ticket, arrow-right, check, x, settings, user, search, bell, home, heart, play, pause, plus, menu, chevron-right… --- ## `data-anim` contract (author entrances in HTML, never hand-keyframe) **Every element's entrance is authored as HTML attributes** — the plugin reads them during the DOM walk and emits the matching keyframes. **Animate via attrs; never hand-keyframe after the build.** This is the contract the plugin reads, so treat it as the authoring spec: | Attribute | Values | What it does | |---|---|---| | `data-anim` | `fadeUp` \| `fadeIn` \| `slideIn` \| `scaleIn` \| `chipBounce` \| `count` | the entrance verb for this element | | `data-anim-delay` | `` (e.g. `0.4`) or `stagger` | when it starts; `stagger` defers to the parent's sequence | | `data-anim-dur` | `` (e.g. `0.6`) | entrance duration | | `data-anim-stagger` | `0.06` (seconds) | put on a **parent** to sequence its children one after another | ```html

Row one

Row two

Row three

128

``` This is the structured complement to free-text `userText`: `userText` sets the overall mood; `data-anim` pins each element's exact entrance. Prefer attributes when you need per-element control. ### Figma Motion duration tokens -> `data-anim-dur` Figma's 2026 native **Motion** export ships **duration tokens** — read them off the reference instead of guessing entrance lengths. Map straight to `data-anim-dur` (seconds) and, on surgical retimes, to the `ae_set_keyframes` key times: | Figma token | Value | `data-anim-dur` | |---|---|---| | `duration/fast` | 150ms | `0.15` | | `duration/base` | 250ms | `0.25` | | `duration/slow` | 400ms | `0.4` | Use `fast` for chips/icons, `base` for cards/rows, `slow` for hero/headline reveals. When you instead retime an existing layer with `ae_set_keyframes`, set the out-key time = entrance start + token seconds (e.g. base = start + 0.25s); keep the house settle ease (in22/out75). --- ## Batch-then-render cadence Tight loop to keep renders cheap and avoid blind tweaking: 1. **Batch by category.** Apply ALL edits of one category first (all positions, then all colors, then all timings) — don't interleave categories. 2. **Verify a batch with ONE contact sheet.** One `ae_export_contact_sheet` at `maxWidth <= 768` to eyeball a whole batch — not one render per layer. 3. **Cap previews.** `<= 5` preview renders per rebuild. If you need more, the HTML is wrong — fix it and rebuild. 4. **Full-res only the final frame.** Everything before final approval stays at preview resolution. 5. **ALWAYS render at a NON-ZERO time.** `t=0` is pre-entrance / empty — elements haven't animated in yet. Render at e.g. `t = duration * 0.6` (after all entrances have settled) or you'll "see nothing" and chase a phantom bug. --- ## HTML authoring conventions - **One self-contained `` page sized EXACTLY to the comp** (e.g. 1920x1080), and **pass matching `compW`/`compH`**. Put the size on ``: ``. **If the body has no explicit height the walk sizes the comp to the CONTENT bounding box** — a `position:relative` wrapper with no body height collapses the comp (observed: **1920×544** instead of 1080). Always set body width+height AND pass `compW`/`compH`. Author the frame as you'd mock it in a browser. - **Absolute positioning, explicit px** `left`/`top`/`width`/`height`. Avoid layouts that depend on runtime JS — the walk reads computed layout after `fonts.ready`. - **Background:** set it on `` to colour the comp bg (this also pins the comp size — see above). Otherwise the comp bg defaults to black and a full-frame stage rect carries the colour. - **Verified (A/B test, 2026-06-27):** for mappable CSS the builder produces real EDITABLE layers — 2-stop gradient → Gradient Ramp, `box-shadow` → Drop Shadow, text → editable Text layers (NOT a baked PNG). It only rasterizes the un-mappable parts (3+-stop/mesh gradients, `filter`, images) — exactly the DRAW-vs-GENERATE line below. So this IS the default builder for mappable layouts; reserve the granular `ae_*` tools for surgical edits. - **Fonts:** Web fonts are fine — the panel waits for `fonts.ready`. - **Supported + mapped CSS/SVG:** | CSS / element | Becomes in AE | |---|---| | solid fill | shape/text fill | | linear / radial gradient | Gradient Ramp effect — **2 stops only** (see Gradients note below) | | `border-radius` | rounded shape corners | | `box-shadow` | Drop Shadow effect | | `filter: blur()` | Gaussian Blur effect | | `letter-spacing` | tracking | | font weight / size / color | text layer props | | SVG `` | shape layer | | plain text | text layer | > **Gradients — BUILD them natively with `ae_apply_gradient`; GENERATE only truly painterly art.** Apply EVERY gradient with **`ae_apply_gradient`** (reliable native Gradient Ramp for 2 stops / 4-Color for 3–4, from **measured** stops, with colour read-back — call it BY NAME even if it's not in your visible tool list). Decide per gradient: > - **2-stop, 3–4-stop, radial, or 4-corner blend** → **BUILD it natively** with `ae_apply_gradient`. This is virtually every card / plate / pill / background gradient. Do NOT generate it, do NOT "stack 2–3 Ramp solids", and do NOT bake a PNG. > - **ONLY genuinely painterly artwork** with no clean stop structure — mesh / conic / organic-textured / illustrative (a *rendered* surface, not a colour ramp) — generate-and-cut as a raster ``. That's the single case where generation beats building. > > **Do NOT bake a plate/card gradient as a PNG — and do NOT pre-bake it "to rebuild natively later" (build native from the START).** Don't reach for generation when `ae_apply_gradient` would do. The connector now HAS a reliable native gradient engine (`ae_apply_gradient`, with read-back) — the old "no native multi-stop / stack Ramps / generate the rich ones" guidance is **obsolete**. ### Keep text EDITABLE — never nest it inside a rasterized container The connector build keeps text and gradients **EDITABLE** — it does **NOT** slice or rasterize complex containers (no html2canvas, no slicer). Every text node → an editable **Text layer**; every gradient (2-stop, 3–4-stop, radial) → a **native** Gradient Ramp / 4-Color via `ae_apply_gradient`; shapes → shape layers; a blur/glow → a native effect (Box Blur / Glow). The **only** thing that becomes a flat image is an actual picture you supplied: an `` tag or a `background-image: url(...)`. **There is NO "3+-stop gradient / glow / blur container bakes"** — that was the AE-Vibecode bundle's slicer, which **this connector does not have**. So to keep text editable: 1. **Build the surface natively** — a shape + `ae_apply_gradient` (ANY stop count), plus border / shadow / blur / glow as native effects. The plate AND its text come back as editable layers (grouped into the precomp). A rich/multi-stop/rotated gradient does NOT need splitting or baking. 2. **The one real bake risk = a GENERATED picture.** Never put editable text INSIDE an `` / `background-image:url(...)` — it becomes part of that picture. If you genuinely need a photographic/painterly background, make it its OWN image element and put the text as a **separate sibling OVER it**, never wrapped inside it. (DRAW-vs-GENERATE: build chrome + real text on top; generate only the wordless graphic.) 2a. **STYLE LOCK for generated pictures:** every image generated for one build shares ONE style — write a single style descriptor (render style, palette, lighting, materials, background) once and prepend it verbatim to each generation prompt; regenerate off-style results. **The lock fixes palette/typography/motion tone — NOT layout:** vary each element's form, placement, and scale with its job in the frame; an identical plate on an identical anchor everywhere is uniform but dead. So text only comes back baked if it was nested inside a GENERATED image — never from a gradient, blur, or glow, which the connector builds natively. 3. **NO EMOJI in the HTML text — they land as no-ink text layers.** AE does not rasterize colour-emoji fonts: the layer builds but paints NOTHING (verified in the field — pixel probe shows "no ink" where the face should be). Avatars/memoji/decorative emoji must be `` elements (e.g. DiceBear `https://api.dicebear.com/9.x/big-smile/png?seed=&size=256`), which import as image layers. Same trap for exotic glyphs (→ ↑ ↓): keep them in a font that has them (ArialMT) or draw a small shape — and pixel-check the zones after render (see the text-layer notes above). ### Large/dense designs — pass the HTML INLINE The connector takes the HTML as the **inline `html` string only** — there is **no `htmlPath`/file parameter** (the AE plugin reads `input.html`; a path is silently ignored). So always pass the full markup in `html`. For a big frame (dashboard, multi-phone app shot, 3+ dense panels): author the complete HTML and pass it inline in one `ae_build_scene_from_html` call. If the frame is too large/complex to emit reliably in one shot, split the WORK, not the file — build the main layout from HTML first, then add or refine pieces with the atomic `ae_*` tools (`ae_add_text_layer`, `ae_add_shape_layer`, `ae_import_image`, `ae_precompose_layers`) on the resulting comp. (`ae_html_to_spec` likewise takes inline `html`; use it to preview the spec before committing a build.) --- ## userText animation intent Free text describing the motion you want; it drives per-layer animation marks: | Say this | Effect | |---|---| | "kinetic" / "kinetic typography" | kineticBeat on headings | | "typewriter" / "type on" | typewriter on text | | "count" / "counter" / numeric values | number counters | | "reveal" / "fade up" / "appear" | fadeUp | | "grow" / "growing bar" / "chart" | chartGrow / trimPath | | chips / buttons | chipBounce | `duration` (seconds) bounds the comp; it auto-extends if the animation needs more time. --- ## Result envelope + what "healthy" looks like `ae_build_scene_from_html` returns: ``` { success: bool, layersCreated: int, effectsApplied: int, keyframesSet: int, errors: [] } ``` - **Healthy:** `success: true`, `errors: []`, and `layersCreated = 1 (BG) + N spec layers`. - `effectsApplied: 0` is **normal** when the HTML has no gradients, shadows, or filters — it is not a failure. - **`errors` non-empty = the build is NOT clean.** Even if `success: true` and a comp was created, per-layer failures mean some layers/keyframes are wrong. REPORT the errors verbatim to the user and treat the result as a partial failure — re-inspect with `ae_list_compositions` / `ae_export_frame` and fix the HTML, then rebuild. **NEVER** claim layers/keyframes were "set correctly" or that the comp is complete while `errors` is non-empty. --- ## Mandatory post-build passes - **AUTO-GLOW:** the builder auto-applies Deep Glow/Glow to every "vivid accent" rect (saturated fill sat ≥ 0.45, alpha ≥ 0.7, size 100–700px), and the glow SHIFTS that plate's rendered colour away from the passport. Correct for neon scenes, WRONG for flat design. On a flat reference, immediately after the build sweep the saturated plates (`ae_list_effects` per flagged layer → `ae_remove_effect` in one `ae_batch`) and re-verify those colours against the passport. - **Non-Latin text (CJK, hangul) can arrive MANGLED through the HTML build** — encoding issue in the pipeline; the native path is unaffected. After building a frame with non-Latin copy, check those strings on the render; if broken, delete and rebuild them with `ae_add_text_layer`. - **Placeholder avatars/people (pairs with STYLE LOCK):** DiceBear PNG via `ae_import_image`: `personas` (stylised people) · `open-peeps` (illustrative, supports glasses: `accessoriesProbability=100`) · `bottts` (robot/NFT) · `big-smile` (emoji-style faces) — `https://api.dicebear.com/9.x/