@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/text-to-lottie/references/player-contract.md

@@ -0,0 +1,325 @@
+# Player Contract
+
+Use this reference before creating, editing, fixing, or verifying any scene.
+
+## Setup
+
+Use the official player project. Do not verify through a custom page,
+`lottie-web`, or another renderer.
+
+If the player project is missing:
+
+```bash
+npx degit diffusionstudio/lottie my-animation
+cd my-animation
+npm install
+npm run dev
+```
+
+The dev server defaults to port `3030`, but never assume it. On `npm run dev`,
+Vite prints the URL it bound to (`Local: http://localhost:<port>/`) and falls
+back to the next free port when `3030` is taken — e.g. when another project
+folder is already serving. Treat that printed port as the source of truth and
+use it as `<port>` in every curl and navigation below; a second folder's server
+answers on a different port, so a blind request to `3030` will hit the wrong
+project.
+
+If the project already exists, use its existing setup and start `npm run dev`
+when browser verification is needed.
+
+## Scene Layout
+
+Every renderable scene lives under `public/projects/`:
+
+```text
+public/
+  canvaskit.wasm
+  projects/
+    <project-slug>/
+      <scene-N>/
+        lottie.json
+        controls.json
+        <image files>
+        <font files>
+```
+
+- `lottie.json` is required. A scene without it is ignored.
+- Project and scene slugs become URL segments: `/<project>/<scene>`.
+- Scene ordering comes from the trailing number in `scene-<N>`.
+- Put image assets next to the scene and reference them by bare filename in
+  `assets[].p`, for example `"p": "logo.svg"`.
+- Put font files (`.ttf`, `.otf`, `.ttc`) next to the scene to render native text.
+  The loader passes every scene font to Skottie; see "Native Text" below.
+
+## Target Scene Policy
+
+- Resolve target scenes by authority. A user-provided file path wins. A browser
+  URL route like `/<project>/<scene>` wins next and maps to
+  `public/projects/<project>/<scene>/lottie.json`. An already-known
+  project/scene for the task wins next.
+- Do not let the active scene from `GET /__context`, the `live` block in
+  `/__context`, or `/__context.live` override a known file path, URL, or
+  project/scene.
+- If project/scene is known, navigate directly to
+  `http://localhost:<port>/<project>/<scene>` and inspect frames there with
+  `?frame=<N>`.
+- Use the active project/scene from `GET /__context` only when the task is
+  explicitly to edit what is currently on screen and no more specific target
+  exists.
+- If creating new work without a target, create a new project/scene or the next
+  available `scene-<N>`.
+- For dropped, uploaded, or imported Lottie JSON, work on the generated scene
+  under `public/projects/<imported-project>/<scene>/lottie.json`, not the
+  original dropped/uploaded JSON context.
+- Before editing, verify the resolved file is the intended
+  `public/projects/<project>/<scene>/lottie.json`; before overwriting an
+  existing `lottie.json`, re-read the current file from disk.
+- Overwrite `public/projects/main-project/scene-1/lottie.json` only when it is
+  still the untouched placeholder. If unsure, create a new scene.
+
+Treat `main-project/scene-1` as safe to overwrite only if it has one simple
+background layer, no meaningful assets, no custom controls, and a generic name
+such as `Scene 1 - 512x512`.
+
+## Live Editor Behavior
+
+- The scene tree watches folders and updates live.
+- Editing an existing `lottie.json` may require reload or re-navigation.
+- Slot edits in the UI are written back through `/__scenes/lottie`, so re-read
+  source before applying another edit.
+
+## Context Endpoint
+
+Use the context endpoint for project-tree discovery, last-modified checks, and
+observational playback state:
+
+```bash
+curl -s http://localhost:<port>/__context
+```
+
+It reports the project tree, active project/scene, frame, total frames, fps, and
+last-modified times. Treat that active scene as observational unless the task is
+explicitly to edit what is currently on screen and no path, URL route, or known
+project/scene target exists.
+
+## Frame Pinning
+
+Inspect exact frames by navigating to:
+
+```text
+http://localhost:<port>/<project>/<scene>?frame=<N>
+```
+
+`?frame=N` seeks and pauses on load. Use frame `0`, midpoint, and `op - 1` for
+new scenes; use focused frames for small edits. The canvas is
+`<canvas id="main-canvas">`.
+
+## Slots And Controls
+
+Use slots for user-editable values that should appear in the player properties
+panel. The player discovers slots automatically through Skottie.
+
+Top-level slot pattern:
+
+```json
+{
+  "slots": {
+    "accentColor": { "p": { "a": 0, "k": [0.2, 0.5, 1, 1] } },
+    "scaleAmount": { "p": { "a": 0, "k": 100 } }
+  }
+}
+```
+
+Reference a slot with `sid` on a compatible property:
+
+```json
+{ "c": { "sid": "accentColor" } }
+```
+
+Add `controls.json` next to `lottie.json` when labels or numeric ranges matter:
+
+```json
+{
+  "controls": [
+    { "sid": "accentColor", "label": "Accent color" },
+    { "sid": "scaleAmount", "label": "Scale", "min": 40, "max": 160, "step": 1 }
+  ]
+}
+```
+
+Slot value types map to controls:
+
+| Slot value | Control |
+| --- | --- |
+| number | slider |
+| RGBA array `0..1` | color picker |
+| two-number array | two number inputs |
+| string text slot | text input |
+
+Slot types must match the properties that reference them.
+
+### One control, many slots (`targetSids`)
+
+When one value appears in several slots, first prefer a **single shared slot**:
+reference the same `sid` from every property; one control drives them all, nothing
+else needed.
+
+Use `targetSids` only when the value cannot share one slot. The control writes to its
+own `sid` plus every id in `targetSids`, and those targeted slots are hidden from the
+panel. List extra targets only, never repeat the primary `sid`; the primary and every
+target must be the same type.
+
+In practice that means native text: a text slot carries the whole text document (font,
+size, fill, stroke), so the same string at different sizes or styles cannot share one
+slot — give each copy its own slot and drive them with one control. Same-type non-text
+values (a color, a size) should usually share a single slot, so they rarely need this.
+
+```json
+{
+  "controls": [
+    { "sid": "brandName", "label": "Brand Name", "targetSids": ["heroBrandName", "lowerThirdBrandName", "endCardBrandName"] },
+    { "sid": "eventDate", "label": "Event Date", "targetSids": ["heroDate", "agendaDate", "endCardDate"] }
+  ]
+}
+```
+
+## Native Text
+
+Native Lottie text layers (`ty:5`) and text slots render in this player, as long
+as the scene supplies the font. The loader discovers every `.ttf`/`.otf`/`.ttc`
+file in the scene folder and hands all of them to `MakeManagedAnimation`
+alongside images. Skottie loads those bytes into a font manager and resolves each
+text layer by the font's **embedded family name** — so the contract is:
+
+1. Drop the font file in the scene folder (next to `lottie.json`).
+2. Declare it in the Lottie's top-level `fonts.list`, e.g.
+   `{ "fName": "Inter", "fFamily": "Inter", "fStyle": "Regular", "ascent": 75 }`.
+   `fFamily` must equal the font's real embedded family name (not the filename).
+3. Reference that font from text documents via `f` (matching `fName`).
+
+The font's **filename is irrelevant** to resolution — Skottie matches on the
+embedded family name, not the asset key — but keep it unique within the folder so
+it does not collide with an image. If no matching font is present, the text layer
+renders transparent (the classic "blank text" failure).
+
+- Text slots (editable text in the properties panel) work the same way — the slot
+  still needs the font present. Use them by default for primary scene copy:
+  headlines, hooks, titles, taglines, CTAs, closing lockups, product/feature
+  names, and short status/result callouts. Centered, self-contained copy is
+  slot-safe; let it re-center after string edits.
+- Decide slotting per text layer. Leave a layer unslotted only when that layer's
+  exact string controls layout or timing: code/terminal rows, hand-spaced lists,
+  cursor/token offsets, masks, path/morph/per-character reveals, or tiny
+  incidental labels.
+- Native editable text slots must use the keyframed text-document shape: layer
+  fallback at `layers[].t.d.k[0].s`, slot binding via `layers[].t.d.sid`, and
+  top-level slot document at `slots[id].p.k[0].s`. The editable string lives at
+  `slots[id].p.k[0].s.t`. Do not author new text slots as `slots[id].p.p.t` or as
+  a direct `slots[id].p.k` text object.
+- For keyframed text slots, the slot property must use `"a": 1`:
+  `slots[id].p = { "a": 1, "k": [{ "t": 0, "s": { ...textDocument } }] }`. With
+  `"a": 0` or a missing `a` next to a text-document keyframe array, Skottie can
+  render the text slot blank. Color/scalar slots still use `"a": 0` with a plain
+  `k` value.
+- If a text slot renders blank, check: (1) slot property is `"a": 1`; (2) font
+  file is present and `fFamily` matches the embedded family name; (3) top-level
+  slot document matches the layer fallback document.
+- Vector/shape text (baking glyphs to `ty:"sh"` outlines) is no longer required
+  for text to render. Use it only when you deliberately want path-level control
+  (stroke-on reveals, glyph morphs, handwritten traces) — not as a font
+  workaround.
+
+### Point Text vs Box Text
+
+A text document is **point text** by default (no `sz`): the box hugs the glyphs, so
+the layer grows horizontally as the string gets longer and only breaks at a literal
+`\r`. Keep point text where exact glyph or string placement is the design — single
+glyphs, tiles, countdown digits, per-character or choreographed type,
+mask/path/morph text, logos, terminal/code rows, and hand-tuned manual layouts; box
+text would fight their baseline and centering.
+
+Make it **box (paragraph) text** by adding to the text document:
+
+- `sz: [w, h]` — box size. Its presence is what switches the shaper to word-wrap.
+- `ps: [x, y]` — box origin (top-left), relative to the layer anchor.
+- `lh` — line height, i.e. spacing between the wrapped lines.
+
+The shaper wraps words automatically at the `sz[0]` width. Use box text for
+**editable multi-word slots** (headlines, subtitles, quotes, CTAs) so a longer edit
+reflows onto new lines instead of overflowing the frame. Slotted box text must carry
+the identical text document — including `sz`/`ps`/`lh` — in **both** the layer
+fallback (`layers[].t.d.k[0].s`) and the slot document (`slots[id].p.k[0].s`), same
+rule as the string itself. A slot edit changes **only** `.t`; the rest of the
+document shape (box fields, `j`, `lh`, and the slot's own `p.a`/`p.k`) is preserved
+on save.
+
+Verified in canvaskit-wasm 0.41.1: box text wraps on initial load **and re-wraps on
+live slot edits**; `j` maps `0`/`1`/`2` to left/right/center alignment within the
+box; and edit+save preserves the box fields. Two caveats are part of the contract:
+
+- **Top-aligned, no vertical-centering.** Text starts at the box top and grows
+  downward; the box does not center it vertically. Set `ps` to the intended box
+  *top-left*. To visually center a known block, offset `ps.y` by hand (≈
+  `(sz[1] - blockHeight) / 2`).
+- **Height does not clip.** Only `sz[0]` (width) governs wrapping; `sz[1]` (height)
+  neither clips nor constrains — text taller than the box spills past its bottom
+  edge. Size the height generously, or expect bottom overflow on long edits.
+
+## Vector Text Vertical Placement
+
+Vector text has no line-height or auto-centering. You place every glyph by hand,
+so compute the baseline from the font's cap height instead of eyeballing it.
+
+- Derive cap height from the font, not a guessed number:
+  `capEm = sCapHeight / unitsPerEm`, then `cap = capEm * size`. If the font lacks
+  the metric, fall back to `capEm ≈ 0.7` (use x-height `≈ 0.52em` for all-lowercase
+  runs).
+- To vertically center a run in a container whose center is `cy`:
+  `baseline = cy + cap / 2`.
+- For a row holding two runs of different sizes (for example a small label and a
+  large value), center each run on the shared center line using its **own** cap
+  height. A shared baseline makes the smaller run sink below the larger one.
+
+## Background Policy
+
+- Full-frame standalone compositions should include a visible background layer
+  with a `bgColor` slot and a `controls.json` entry.
+- Transparent-by-default outputs include logos, icons, loaders, overlays, lower
+  thirds, and SVG-derived assets unless the user asks for a background.
+- Do not add an opaque rectangle just to fill the canvas.
+- If a transparent animation needs preview contrast, use the player/canvas
+  environment for verification instead of baking unwanted pixels into the JSON.
+
+## Verification
+
+- Validate JSON before browser verification.
+- Confirm the scene appears in `/__context`.
+- Inspect pinned frames in the browser. New scenes need frame `0`, midpoint, and
+  `op - 1`.
+- Fix blank canvas, missing assets, unstyled shapes, wrong layer order, bad
+  easing, cropped content, text overflow, and SVG artifacts before finishing.
+
+## Final Review Passes
+
+Run lightweight render, design, and motion reviews before calling a scene
+complete. First, midpoint, and final frames are the minimum still-frame check,
+not a substitute for motion review.
+
+- Render review: validate JSON, confirm `/__context`, verify assets load, and
+  inspect pinned frames in the official player.
+- Design review: inspect frame `0`, midpoint, `op - 1`, and any major semantic
+  still. Check focal point, placement, spacing, hierarchy, typography, color
+  roles, object necessity, and final-frame strength.
+- Text alignment review: inspect text rows zoomed in, not only at full-frame. A
+  few pixels of vertical misalignment are invisible at composition scale. Confirm
+  that mixed-size runs sharing a row are cap-center aligned, that single runs are
+  optically centered in their container, and that stacked blocks (such as a
+  headline and its subline) follow an intentional vertical rhythm.
+- Motion review: scrub playback and inspect key beat frames: frame `0`, early
+  reveal, midpoint, settle or near-final, `op - 1`, loop seam if looping, and
+  semantic beats where a number resolves, word lands, logo lockup forms, chart
+  finishes drawing, CTA appears, or camera move settles.
+- Check beat order, stagger origin, timing, easing, settle/hold, loop seam,
+  camera/framing, and readability during motion.
+- If design or motion review fails, simplify and revise before finishing. A
+  valid render is not enough.

package/skills/text-to-lottie/references/recipe-camera-scene-motion.md

@@ -0,0 +1,65 @@
+# Recipe: Camera And Scene Motion
+
+Use for camera-following motion, pan, zoom, parallax, layered scene movement,
+hero pushes, product screenshot tours, and animated scene framing.
+
+## User-Language Aliases
+
+- "pan across this", "zoom into the product", "camera follow"
+- "parallax scene", "Ken Burns style", "move through the interface"
+- "push in", "pull back", "follow the path", "scene motion"
+
+## Defaults
+
+- Choose one dominant camera idea: push, pull, pan, follow, or parallax.
+- Keep the main subject readable throughout the move.
+- Use full-frame background policy unless the result is a transparent asset.
+- Treat camera motion as attention direction, not decoration.
+- Use camera motion to improve attention and final-frame framing, not to hide a
+  weak composition.
+
+## Presets
+
+- `premium-push`: slow push-in with subtle foreground/background separation.
+- `guided-pan`: horizontal or vertical pan revealing steps in order.
+- `focus-follow`: camera follows one hero object or path.
+- `layered-parallax`: foreground/midground/background move at different rates.
+- `product-tour`: screenshot/product card moves through 2-3 feature beats.
+
+## Timing And Easing
+
+- Compact camera move: 60-120 frames.
+- Product or scene tour: 120-240 frames.
+- Use smoother easing than object motion; abrupt camera stops feel cheap.
+- Hold briefly after the camera arrives so the final message lands.
+
+## Ask Only When Needed
+
+- Ask which subject to follow if the scene has multiple heroes.
+- Ask output size/platform if framing depends on aspect ratio.
+- Ask whether text must remain readable throughout the move when uncertain.
+
+## Construction Notes
+
+- Prefer grouped/parented transforms over animating every child independently.
+- Keep scale changes modest unless the move is the concept.
+- Counter-animate text or labels if camera motion makes them hard to read.
+- Use parallax only when layered depth exists or can be built cleanly.
+- If the final frame feels like an accidental crop, revise the layout or camera
+  endpoint before adding more movement.
+
+## Common Failure Modes
+
+- Camera crops the hero subject or text.
+- Parallax layers move without a clear depth hierarchy.
+- Motion sickness from too much scale/position change.
+- Final frame feels like an accidental crop.
+- Camera motion adds energy but does not improve hierarchy or framing.
+
+## Acceptance Checks
+
+- The viewer's eye follows the intended subject.
+- Important text remains readable or resolves quickly.
+- First and final frames are clean compositions.
+- Camera motion enhances the message instead of hiding weak layout.
+- Final camera position lands on the strongest still frame.

package/skills/text-to-lottie/references/recipe-data-stats.md

@@ -0,0 +1,104 @@
+# Recipe: Data, Stats, And Charts
+
+Use for KPI cards, stat reveals, big-number scenes, pitch-slide charts,
+dashboard metrics, progress/goal cards, social-proof rows, data-derived
+textures, and simple chart animations.
+
+## User-Language Aliases
+
+- "animate these KPIs", "stat card", "big number reveal", "metric animation"
+- "pitch chart", "growth chart", "bar chart", "line chart", "data slide"
+- "dashboard metric", "progress card", "results row", "social proof"
+
+## Defaults
+
+- Choose one data archetype before authoring. Do not improvise a layout for a
+  number.
+- The headline should state the insight; the chart or figure confirms it.
+- Use one semantic accent against neutral, two values of one hue, or one
+  saturated hue per card.
+- Default to borderless figures in negative space, or even self-contained cards.
+  Do not wrap a stat triad in an extra outer framing card or border unless the
+  user asks. Use exactly one surface tone; never stack two near-black or
+  near-white tints. If columns need separation, use one hairline of one color
+  between equal columns only, and prefer whitespace first.
+- Count up figures with baked keyframes and tabular numerals unless the prompt
+  asks for static text.
+- Use slotted background for full-frame data scenes; transparent only when the
+  user asks for overlay/asset output.
+
+## Archetype Picker
+
+- Hero figure: one emotional metric, extreme figure-to-label contrast.
+- KPI grid or stat-card triad: several parallel proofs using one repeated
+  template.
+- Results rows: hairline label/value rows for credible outcomes.
+- Comparison chart: one accent-vs-neutral bar, line, strip, or scale graphic.
+- Progress/goal card: actual vs target, goal line, weekly bars, or ring nesting.
+- Dashboard metric mock: one hero metric, one chart, and light supporting state.
+- Social proof: outcome-tied logo/name row, metric, and attribution.
+- Data-derived texture: heat map, mosaic, or dot/ring field where the pattern
+  is data, not decoration.
+
+## Timing And Easing
+
+- Compact stat card: 60-120 frames.
+- Multi-card/grid/chart reveal: 120-210 frames.
+- Use calm ease-out and no bounce for finance, research, enterprise, and serious
+  data.
+- Small pops are acceptable for badges, consumer/wellness warmth, or bold social
+  panels.
+- Support text arrives after the figure or geometry resolves.
+
+## Construction Notes
+
+- Bake counters and odometer rolls. Do not rely on live expressions in Skottie.
+- Use tabular or fixed-width numeral shapes so digits do not jitter.
+- Sync counts to geometry: line reaches point, bar reaches height, segment
+  reaches width, or ring reaches target.
+- Direct-label values on points, bars, cards, rows, or panels. Avoid axis
+  decoding when the scene is short.
+- Use trim paths for lines, hairlines, axes, callout arrows, rules, and flows.
+- Use masks or clip reveals for rounded bars/cards so radii do not distort.
+- Use slots for insight/headline text, key values, accent color, background
+  color, and optional chart colors when useful.
+- Placeholder third-party logos, compliance marks, or headshots unless the user
+  supplied rights-safe assets.
+
+## Common Failure Modes
+
+- Title names the topic but not the insight.
+- Static number appears with a fade instead of a count-up.
+- Values require axis/legend decoding.
+- Rainbow chart color decorates instead of teaching.
+- Too many metrics compete in one beat.
+- Serious data uses bouncy or theatrical motion.
+- An unnecessary outer framing card or border wraps the stat group when
+  whitespace and alignment would carry it.
+- Multiple dividers use slightly different colors or weights (for example a title
+  underline plus column rules that do not match).
+- Two stacked near-black or near-white tints read as a muddy box instead of one
+  clean surface.
+- Dashboard mock looks dense but the state is incoherent.
+- Rounded bars/cards stretch because they were scaled instead of revealed.
+- Label and value in a row share a baseline, so the smaller label sinks below the
+  larger value instead of reading as one aligned row.
+- Label/figure spacing or row spacing is eyeballed, so the vertical rhythm looks
+  uneven.
+
+## Acceptance Checks
+
+- The data archetype matches the metric's job.
+- The headline states the point and the data confirms it.
+- Figures are direct-labeled, counted up, and readable.
+- Label and value in each row are cap-center aligned and optically centered in the
+  pill, card, or row, and the value stays centered through the count-up.
+- Stacked label/figure spacing and row-to-row spacing follow a consistent rhythm.
+- Chart geometry and numeric labels resolve together.
+- Palette uses semantic color, not decorative color.
+- No outer framing card or border unless it does a job whitespace cannot; any
+  dividers are a single hairline and one color between equal columns; exactly one
+  surface tone is used; hierarchy still reads with all chrome removed.
+- Final frame works as a clear still data slide.
+- Motion adds comprehension and does not overdramatize serious data.
+- Counters, masks, trim paths, and rounded reveals are Skottie-safe.

package/skills/text-to-lottie/references/recipe-diagram-technical.md

@@ -0,0 +1,106 @@
+# Recipe: Diagram And Technical Animation
+
+Use for technical diagrams, flow traces, line animations, callouts, architecture
+explainer graphics, process steps, and data/connection reveals.
+
+## User-Language Aliases
+
+- "trace this diagram", "animate the flow", "show the pipeline"
+- "technical line animation", "callout animation", "draw the connection"
+- "architecture explainer", "step-by-step diagram", "network/path reveal"
+
+## Defaults
+
+- Prioritize clarity over decoration.
+- Follow the object budget in `design-taste.md`: start with the smallest set of
+  nodes, paths, labels, and accents that explains the system.
+- Reveal in the order the viewer should understand the system.
+- Do not treat "technical" as dark grid, blue arrows, empty rounded cards, and
+  decorative circles. Pick a concrete visual system.
+- Use transparent background for overlays/assets; use slotted background for
+  full-frame explainers.
+- Read `svg-compatibility.md` when the source diagram is SVG.
+
+## Before Authoring
+
+- Define the final-frame topology: primary path, supporting clusters, callout
+  positions, and strongest still-frame read.
+- Choose a visual system: editorial light, product UI, schematic minimal,
+  branded system map, dense dashboard detail, or presentation-grade explainer.
+- Choose the structural relationship: chain for sequence, bracket for
+  part-whole, orbit for convergence, radial for system, grid for comparison,
+  or hairline rows for evidence.
+- Decide the node/detail strategy. Each node should communicate role, state,
+  sequence, metric, UI fragment, icon, or label.
+- Decide what the lines mean: data flow, dependency, sequence, ownership, or
+  state transition.
+- Keep believability separate from density: use coherent system states and
+  clear workflow labels instead of fake technical micro-detail.
+
+## Presets
+
+- `flow-trace`: lines draw in path order, nodes activate after connection.
+- `callout-pop`: labels or badges enter after their target is visible.
+- `scan-highlight`: highlight travels across a path or system segment.
+- `node-network`: nodes appear in clusters, connections follow.
+- `step-build`: diagram builds one logical step at a time.
+- `orbit-system`: radial nodes draw in, orbit subtly, and counter-rotate labels
+  to keep them upright.
+
+## Timing And Easing
+
+- Simple diagram: 75-150 frames.
+- Multi-step explainer: 150-300 frames.
+- Use linear or near-linear trim for technical traces, with eased activation for
+  nodes and labels.
+- Hold after each major step long enough for comprehension.
+
+## Ask Only When Needed
+
+- Ask for the intended reading order if it is not clear from the diagram.
+- Ask whether labels should be editable when text is prominent.
+- Ask full-frame vs transparent only if destination is unclear.
+
+## Construction Notes
+
+- Separate paths, nodes, labels, and highlights.
+- Use trim paths for lines and small opacity/scale settles for nodes.
+- Avoid path morphing; technical diagrams need stable geometry.
+- Keep labels aligned and readable throughout the trace.
+- Give each node useful interior detail: icon, number, small label, status dot,
+  mini UI row, thumbnail, metric, or port.
+- Use arrows only when direction is ambiguous. Vary line weight, opacity, or
+  style to show primary and secondary flow.
+- Use grids as alignment structure or axes, not decorative wallpaper.
+- Turn floating circles into ports, status indicators, badges, or remove them.
+- Use tonal rings, hairlines, halftone-like dots, or subtle value steps for
+  depth before glow or shadows.
+- For orbit/radial systems, counter-rotate text/icons if the parent rotates.
+- If the final frame feels crowded, reduce nodes, merge labels, or emphasize the
+  primary path before adding more detail.
+
+## Common Failure Modes
+
+- Everything reveals at once, losing the explanation.
+- Lines draw opposite the intended flow.
+- Labels overlap or appear before their target.
+- Decorative effects reduce technical clarity.
+- Empty rounded rectangles make the diagram feel placeholder-like.
+- Dark grid plus blue arrow chains make the scene feel generic unless requested.
+- Generic node mesh suggests "technical" without explaining a relationship.
+- Large blank regions weaken the final poster frame.
+- Fake complexity adds visual noise without explaining the system.
+- Dense meaningful-looking detail makes the system harder to understand.
+
+## Acceptance Checks
+
+- The reveal order explains the system.
+- Final frame is a clean, accurate diagram.
+- Lines, arrows, labels, and callouts stay readable.
+- Nodes contain enough information to be meaningful without the animation.
+- The final topology feels balanced, with intentional negative space.
+- Decoration has a job: grouping, state, brand, attention, or structure.
+- Diagram structure communicates the relationship without relying on labels
+  alone.
+- Detail improves comprehension without crowding the final composition.
+- SVG source diagrams preserve holes, clipping, and intersections.

package/skills/text-to-lottie/references/recipe-loaders-icons.md

@@ -0,0 +1,70 @@
+# Recipe: Loaders, Icons, And State Feedback
+
+Use for loaders, spinners, progress loops, badges, simple icons, success/error
+states, warning alerts, empty states, and compact status animations.
+
+## User-Language Aliases
+
+- "loading spinner", "looping loader", "progress ring", "animated icon"
+- "success check", "error x", "warning triangle", "complete animation"
+- "toast icon", "empty state", "status badge", "done indicator"
+
+## Defaults
+
+- Transparent background.
+- Loop cleanly for loaders/spinners/progress.
+- Play once and settle for success/error/warning states unless looping is asked.
+- Keep geometry crisp and readable at small sizes.
+- Prefer one primitive or icon idea repeated with phase offsets over unrelated
+  moving parts.
+- Add only one charm gesture, such as blink, bounce, pulse, or draw-on, when it
+  fits the brand tone.
+
+## Presets
+
+- `orbital-loader`: rotating dots or marks with seamless timing.
+- `stroke-trace`: icon stroke draws, holds briefly, then resets or loops.
+- `pulse-badge`: compact scale/opacity pulse around a status symbol.
+- `check-complete`: path draw plus short settle for success states.
+- `error-shake`: brief x/alert emphasis, controlled and not frantic.
+- `warning-pulse`: triangle/badge reveal with restrained attention pulse.
+- `scan-progress`: linear or radial progress sweep with controlled repetition.
+- `phase-dots`: repeated dots or marks animate with offset timing and a matched
+  loop seam.
+
+## Timing And Easing
+
+- State feedback: 30-75 frames with a stable final pose.
+- Loaders: 60-120 frame seamless loops.
+- Use continuous linear only for rotational/progress loops.
+- Use short ease-out or low-bounce spring-like settles for success states.
+
+## Ask Only When Needed
+
+- Ask loop vs one-shot only if the request is ambiguous.
+- Ask target size if the icon must fit a specific UI slot.
+- Ask brand/accent color if no source style exists.
+
+## Construction Notes
+
+- Use trim paths for strokes, checks, rings, and circular loaders.
+- Match first and last frames for loops.
+- Engineer loop seams with identical first/last state or a period-locked cycle.
+- Avoid excessive detail below small-icon sizes.
+- Expose slots for accent color, stroke width, and background only if full-frame.
+
+## Common Failure Modes
+
+- Loop seam is visible.
+- Repeated parts move in lockstep and feel mechanical.
+- Icon becomes unrecognizable during motion.
+- State animation feels too playful for an error/warning.
+- Stroke caps or joins render differently than expected.
+
+## Acceptance Checks
+
+- Loop seam is invisible when looping.
+- Repeated motion uses phase offset unless lockstep is intentional.
+- Icon remains recognizable during motion.
+- Timing feels useful, not frantic.
+- Transparent output has no unwanted background layer.