@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/text-to-lottie/references/design-taste.md

@@ -0,0 +1,292 @@
+# Design Taste
+
+Use this reference when composition, typography, layout, color, or brand polish
+matters.
+
+## Contents
+
+- Design Decision Loop
+- Taste Modes
+- Simplify Before Adding
+- Composition Defaults
+- Primitive Systems
+- Anti-Generic Replacements
+- Placement And Framing
+- Typography
+- Color And Material
+- Data And Figures
+- Brand-System Grammar
+- Background And Generative Fields
+- Production Polish
+- Final Design Review
+
+## Design Decision Loop
+
+Before authoring a designed scene, define the message, focal subject, support
+layer, accent system, and final-frame composition goal. If those choices are
+not clear, the design will usually drift toward generic shapes.
+
+- Translate "clean", "technical", or "premium" into a specific system: editorial
+  light, product UI, schematic minimal, branded system map, dense dashboard
+  detail, or presentation-grade explainer.
+- Choose the taste mode before authoring: restrained product, institutional
+  data, bold social, expressive primitive, playful character, or ambient field.
+- Start with the fewest objects needed. A strong default is one focal subject,
+  one support layer, and one accent system.
+- Choose the main still image first. Motion should reveal and clarify that
+  composition, not rescue a weak final frame.
+- Decide which elements carry meaning. Decoration should either group content,
+  show state, direct attention, reinforce brand, or be removed.
+- Separate believability from density. Product or content detail is believable
+  when state, workflow, labels, and hierarchy are internally consistent, not
+  when the scene simply contains more interface fragments.
+- If hierarchy, spacing, color restraint, object necessity, or final-frame
+  quality fails, simplify and revise before finishing.
+
+## Taste Modes
+
+- Restraint-premium: neutral or one-hue palette, generous space, one functional
+  accent, calm easing. Use for product, enterprise, technical, finance, and
+  serious data.
+- Commitment-premium: one word, number, mark, or object at full focus; two-tone
+  or brand-locked color; beat-driven energy. Use for brand, social, title, and
+  launch moments that need impact.
+- Expressive primitive: one repeated shape, stroke, dot, glyph, cursor, or mark
+  carries the idea. Use arrangement and gestalt before literal illustration.
+- Ambient/generative: one anchor, one derived field, one ground. Keep the field
+  quiet enough to host foreground content.
+- Playful/character: use one emotional signature, such as blink, look, bounce,
+  or squash. Keep the rest disciplined so charm does not become clutter.
+
+## Simplify Before Adding
+
+- Prefer fewer stronger objects over many meaningful-looking details.
+- Remove, merge, resize, clarify, or rebalance existing elements before adding
+  a new object, badge, line, glow, or texture.
+- Treat a detail as valid only when it improves comprehension, hierarchy,
+  workflow clarity, state, brand signal, or reading rhythm.
+- A detail can have a role and still fail if the composition becomes crowded,
+  evenly weighted, or hard to read.
+- When the scene feels generic, first strengthen the focal subject, spacing,
+  typography, and color roles. Add effects only after the composition holds.
+- "Premium" most often fails by adding chrome: a framing card, a border, column
+  dividers, a second surface tint, or a gradient. Treat the word as a cue to
+  subtract. Strengthen scale, weight, brightness, and spacing first; reach for a
+  container only if removing it would lose meaning.
+
+## Primitive Systems
+
+- Build richness from one primitive repeated or varied by scale, density,
+  position, value, or timing.
+- A single stroke, dot, ring, capsule, glyph, or geometric mark can become logo,
+  texture, diagram, loader, or accent when used consistently.
+- Density is acceptable when it is one motif multiplied. Many unrelated motifs
+  read as clutter.
+- If using an expressive primitive, make the arrangement carry meaning:
+  overlap, orbit, chain, bracket, grid, radial order, or figure/ground.
+- Avoid literal clip-art when an abstract relationship can explain the message
+  more clearly.
+
+## Composition Defaults
+
+- Start with a clear hierarchy: primary subject, supporting detail, accent.
+- Keep the object budget visible while designing: focal subject first, support
+  second, accent last.
+- Compose the first and final frames as intentional still designs.
+- Use visual center, not only mathematical center. Round shapes, tall marks, and
+  asymmetric logos may need optical nudging.
+- Keep safe margins around text, logos, and overlays. Leave extra room for
+  motion overshoot and blur-like effects.
+- Use negative space as an active design element; do not fill every empty area.
+- Align to a simple grid, baseline, or optical axis. Break alignment only when
+  the concept clearly benefits.
+
+## Anti-Generic Replacements
+
+- Do not default to dark grids, blue arrows, empty cards, monospaced labels, or
+  decorative circles for technical work. Use a chosen visual system with clear
+  information hierarchy.
+- Replace empty rounded cards with meaningful node details: icons, mini UI
+  fragments, step numbers, labels, thumbnails, status marks, metrics, or data
+  hints.
+- Replace arbitrary accent circles with ports, badges, state indicators,
+  handles, highlights, or remove them.
+- Replace decorative grid wallpaper with structural alignment, section bands,
+  subtle dividers, real axes, or whitespace.
+- Replace generic glow with a focal halo, active-state emphasis, masked material
+  pass, or no effect.
+
+## Placement And Framing
+
+- For transparent assets, frame the artwork tightly enough to feel usable but
+  leave breathing room for motion.
+- For full-frame scenes, keep the subject away from edges unless edge contact is
+  part of the design.
+- Preserve logo lockups. Do not change mark/wordmark proportions, spacing,
+  rotation, or final alignment unless explicitly asked.
+- Check whether the animation's final resting pose is the intended exported
+  asset, not an in-between state.
+
+## Typography
+
+- Use one main type idea per composition: editorial, utilitarian, kinetic,
+  playful, or premium.
+- Decide the focal line or phrase before styling support text.
+- Choose type for voice: serif for human/editorial authority, grotesque for
+  product/function, monospace for technical labels, expressive type only when
+  the words are the subject.
+- Large light-weight type can feel more premium than heavy bold in restrained
+  institutional scenes; heavy bold suits loud social and title work.
+- Keep text readable at the intended size. Avoid crowding edges.
+- Split long text into deliberate lines; do not let line breaks feel accidental.
+- Establish type hierarchy with size, weight, case, and spacing before adding
+  effects.
+- Balance text blocks optically: line length, rag, weight, and spacing should
+  feel stable in the final frame.
+- When two text runs of different sizes share a row (label and value, name and
+  number, icon and caption), align them by their cap-height centers, not by a
+  shared baseline. A shared baseline makes the smaller run appear to sink. Center
+  a single run inside a container by its cap-height box, not the em box or the
+  baseline. See `player-contract.md` "Vector Text Vertical Placement" for the
+  formula, since vector text has no auto-centering.
+- Set vertical spacing between stacked text blocks relative to type size, not by
+  eyeballed pixels. A workable default for a headline and the line directly below
+  it is a gap of about 0.5 to 0.8 of the headline cap height; keep one consistent
+  spacing step between sibling blocks so the rhythm reads deliberate.
+- Use monospaced type only for code, data, terminals, or system-like content.
+- Use weight, size, and timing before adding decorative elements.
+- Convert to paths when exact font rendering matters and font support is
+  uncertain.
+
+## Color And Material
+
+- Start from source/brand colors when provided.
+- When no brand system is provided, prefer a premium pure black/white
+  (`000`/`fff`) contrast or another deliberate premium palette; use warm
+  near-black and cream/off-white tones only when the user asks for them.
+- Use one dominant neutral or background, one primary color, and one accent
+  unless the concept demands more.
+- Assign color roles before adding new colors: background/neutral, focal
+  subject, accent, and optional semantic state.
+- Quarantine saturation to one expressive element, or make every color teach a
+  category, state, comparison, or brand role.
+- Do not let multiple accents compete for the same level of attention.
+- Use tonal steps, hairlines, and brightness ramps for depth before shadows,
+  glow, glass, or blur.
+- Chrome/container budget is `0` by default. A framing card, container, border,
+  or divider must do a job that whitespace and alignment cannot, or it is
+  removed. Separate grids and columns with negative space and alignment first, a
+  single hairline second, and a filled or bordered card last. Carry hierarchy
+  with type weight, scale, brightness, and grouping, not with chrome.
+- Use one surface tone. Do not stack two near-black or two near-white tints to
+  fake a "surface"; layered low-contrast darks (or lights) read as a muddy box.
+  If a card surface must differ from the background, make it one deliberate step
+  with a clear purpose, not an arbitrary second tint.
+- If dividers are genuinely needed, use one weight and one color for all of them,
+  the title rule and any column rules included. Slightly different divider or
+  border colors per element is a classic low-taste tell.
+- Avoid muddy gradients, arbitrary glows, and decorative effects that reduce
+  legibility.
+- When using glass/metal/glow effects, keep the base composition readable with
+  the effect removed.
+- Verify color contrast on the intended background or transparent preview.
+
+## Data And Figures
+
+- The headline should state the insight; the chart or number confirms it.
+- Pick the layout by the data job: hero figure, KPI grid, stat-card triad,
+  comparison chart, progress card, dashboard metric, social proof, or heat map.
+- Big figures should lead with extreme figure-to-label scale contrast.
+- Default a stat triad to either even self-contained cards or borderless figures
+  floating in negative space, separated by whitespace. Do not wrap the group in
+  an extra outer framing card, and do not put dividers between the columns unless
+  whitespace alone fails; if they are needed, use one hairline of one color
+  between equal columns only.
+- Direct-label values. Avoid forcing viewers to decode axes, legends, or chart
+  clutter.
+- Use one semantic accent against neutral, two values of one hue, or one
+  saturated hue per card. Do not use rainbow color decoratively.
+- Encode magnitude spatially when useful: size, bar height, strip width, ring
+  nesting, heat rank, or actual-vs-goal contrast.
+- Credibility comes from concrete scope signals: counts, source totals,
+  outcome-tied logos, named people, or transparent caveats.
+
+## Brand-System Grammar
+
+- For multi-scene work, lock one layout skeleton, type system, and accent rule
+  before designing variants.
+- Use polarity flips, saturated-card variants, or theme slots for rhythm without
+  inventing a new design language per scene.
+- Apply the same restraint to utility content: timelines, address cards,
+  event rows, and labels should use the same grid, hairlines, and type system.
+- A recurring signature device can make a system ownable, but it must stay
+  tonal or semantic instead of competing with the focal subject.
+
+## Background And Generative Fields
+
+- Build ambient fields from one anchor plus one derived field on one ground.
+- Prefer fields generated from the subject, such as ripples, contours, or
+  orbiting points, over generic motif scatter.
+- Keep background fields type-free, low-contrast, and still-frame-clean unless
+  the field itself is the deliverable.
+- Use one motion archetype that fits the content: color cycle, path morph,
+  drift and twinkle, staggered draw-on, radial emanation, or phase-offset wave.
+- Make loops seamless and quiet enough that foreground content remains the
+  hierarchy.
+
+## Production Polish
+
+- Check frame `0`, midpoint, and the final frame as design compositions.
+- Treat first, midpoint, and final frames as the minimum still-frame check. For
+  scenes with major semantic beats, also inspect the frames where a word lands,
+  number resolves, logo locks up, chart completes, CTA appears, or camera move
+  settles.
+- The final frame should have one clear focal subject, readable support, and
+  intentional negative space.
+- The final frame should feel visually finished, not merely like the last
+  rendered frame.
+- Remove temporary construction shapes, debug colors, and placeholder names.
+- Confirm no text, stroke, glow, or reveal mask clips during motion.
+- Ensure the motion path and visual hierarchy point to the same subject.
+- Prefer fewer, better elements over many weak accents.
+- Reject placeholder-looking scenes even when they render correctly. If a node,
+  label, or accent does not communicate meaning, refine it or remove it.
+- Treat unresolved hierarchy, crowded detail, weak typography, color overload,
+  or a poor final still as blockers. Revise the scene before considering it
+  complete.
+
+## Final Design Review
+
+- Check focal point first: the viewer should know where to look before reading
+  support labels or noticing accents.
+- Check placement and spacing: margins, optical centering, baseline alignment,
+  line breaks, and object spacing should feel deliberate at rest and during
+  motion.
+- Check hierarchy: scale, weight, brightness, spacing, and timing should make
+  primary, support, and accent roles obvious.
+- Check typography: line breaks, rag, casing, weight, tracking, and label
+  placement should support the message rather than fill available space.
+- Check vertical alignment and rhythm: mixed-size runs sharing a row should be
+  cap-center aligned, single runs should be optically centered in their
+  containers, and the spacing between a title and its subline (or any stacked
+  blocks) should look intentional rather than tight or arbitrary. Inspect rows
+  zoomed in, since small misalignments hide at full-frame scale.
+- Check color roles: each saturated or high-contrast color should indicate
+  brand, state, category, comparison, or focus.
+- Check object necessity: remove, merge, resize, clarify, or rebalance weak
+  elements before adding decoration, cards, glow, or extra detail.
+- If the review fails, revise the composition and recheck the affected frames
+  before finishing.
+
+### Premium Restraint Checklist
+
+Run this scan on any premium/clean/minimal/card scene before finishing:
+
+- Zero unnecessary chrome: no framing card, border, or divider that whitespace
+  and alignment could replace.
+- Exactly one surface tone: no two stacked near-black or near-white tints.
+- One divider treatment and one color, if any divider exists at all.
+- Hierarchy reads from scale, weight, brightness, and spacing with all chrome
+  removed.
+- For each card, border, or divider present: would removing it lose meaning? If
+  not, remove it.

package/skills/text-to-lottie/references/lottie-spec-map.md

@@ -0,0 +1,82 @@
+# Lottie Spec Map
+
+Use this reference when authoring or debugging Lottie JSON structure. It is a
+curated map of the upstream spec for this project, not a replacement for it.
+
+Upstream specs:
+
+- https://github.com/lottie/lottie-spec/tree/main/docs/specs
+
+## Core Structure
+
+- Top-level documents should include `v`, `fr`, `ip`, `op`, `w`, `h`, `nm`,
+  `assets`, and `layers`.
+- `ip` is inclusive and `op` is exclusive. `ip: 0`, `op: 90`, `fr: 60` renders
+  frames `0..89`.
+- Prefer a meaningful top-level `nm`; the player shows it as the canvas label.
+- Keep assets local to the scene folder and reference images by bare filename in
+  `assets[].p`.
+
+## Properties And Keyframes
+
+- Static properties use `{ "a": 0, "k": value }`.
+- Animated properties use `{ "a": 1, "k": [keyframes] }`.
+- Keyframes must be sorted by ascending `t`.
+- Non-hold interpolation should put `o` on the start keyframe and `i` on the
+  destination keyframe; the final keyframe does not need an outgoing `o`.
+- Scalar animated values use arrays in keyframes, for example `"s": [45]` for
+  rotation or opacity.
+- Color values are RGB or RGBA floats in `0..1`; opacity values are `0..100`.
+- Easing handle `x` values are `0..1`; `y` values may exceed that range for
+  controlled overshoot.
+- A cubic-bezier `(x1,y1,x2,y2)` splits across two keyframes: it is the
+  **outgoing** handle of the start keyframe `o:{x:[x1],y:[y1]}` and the
+  **incoming** handle of the end keyframe `i:{x:[x2],y:[y2]}`.
+- Overshoot: prefer a short settle-back keyframe past the target; the compact
+  alternative is pushing the end `i.y` above 1. Anticipation: push the start
+  `o.y` below 0.
+
+## Layers
+
+- Shape layers use `ty: 4`.
+- Image layers reference entries in `assets`.
+- Layer visibility is `ip <= frame < op`.
+- Parent transforms compose through `parent` references. Avoid cycles.
+- Mattes, masks, precomps, and time remap are valid but more fragile; use them
+  only when simpler shape/layer structure will not produce the result.
+
+## Shapes
+
+- Group related shapes with `ty: "gr"` and put the group transform
+  `ty: "tr"` last in the group's `it` array.
+- Styles apply to shapes that precede them within the current scope. A shape
+  without an applicable fill or stroke will not render.
+- Shapes render in reverse stack order inside groups. Verify visually when layer
+  order matters.
+- Common primitive types:
+  - rectangle: `ty: "rc"`
+  - ellipse: `ty: "el"`
+  - path: `ty: "sh"`
+  - polystar: `ty: "sr"`
+  - fill: `ty: "fl"`
+  - stroke: `ty: "st"`
+  - trim path: `ty: "tm"`
+  - group transform: `ty: "tr"`
+
+## Slots
+
+- Define reusable values in top-level `slots`.
+- Reference a slot with `sid` on a compatible property.
+- Slot type is inferred from the slot value. Keep slot values compatible with
+  every property that references that `sid`.
+- If a property has a missing `sid`, renderers may fall back to the inline value
+  or a type default. Do not rely on missing slots.
+
+## Asset And Renderer Notes
+
+- Image asset dimensions should match the expected `w` and `h` bounds when
+  possible.
+- SVG, masks, gradients, blend modes, and intersections can differ between
+  renderers. Verify in Skottie.
+- Avoid expressions or renderer-specific extensions unless the player explicitly
+  supports them.

package/skills/text-to-lottie/references/motion-taste.md

@@ -0,0 +1,260 @@
+# Motion Taste
+
+Use this reference when choosing pacing, easings, staging, or animation style.
+
+## Contents
+
+- Principles
+- Timing Defaults
+- Easing Anchors
+- Choreography
+- Reveal Grammar
+- Chapterization And Transition Grammar
+- Motion Economy
+- Typography Choreography
+- Data And Figure Motion
+- Camera, Parallax, And Scene Motion
+- Path Reveals And Loops
+- Loop And Generative Motion
+- Style Presets
+- Render-Aware Motion
+- Final Motion Review
+- Checks
+
+## Principles
+
+- Stage motion in readable beats: anticipation, action/reveal, settle.
+- Give the primary subject the clearest timing. Secondary elements should support
+  it, not compete.
+- Match easing to intent. Functional UI needs speed and clarity; brand motion can
+  hold longer; playful effects can overshoot more.
+- Avoid linear interpolation unless mechanical motion is the intent.
+- Avoid generic easing where every property shares the same timing by default.
+  Use locked timing for rigid/UI-stable motion, and offset opacity, position,
+  scale, or trim timing only when it improves choreography.
+
+## Timing Defaults
+
+- UI microinteractions: 12-30 frames at 60 fps.
+- State feedback icons: 30-75 frames, usually with a short hold.
+- Logo marks: 45-120 frames depending on complexity.
+- Lower thirds: 45-90 frames in, optional 30-60 frames out.
+- Typography reveals: 45-150 frames depending on text length.
+- Product/social promos: 90-180 frames for one clear message.
+- Loaders/icons: loop cleanly over 60-120 frames.
+
+## Easing Anchors
+
+Known-good defaults to **derive from**, not a closed preset list. Anchors
+describe motion **behavior** (entering, settling, traveling, exiting, looping,
+cut companion), not layer type: a logo, hero, title, card, or accent each picks
+by what it is doing this beat. Bezier is `x1,y1,x2,y2`.
+
+| anchor | behavior | cubic-bezier | feel |
+| --- | --- | --- | --- |
+| `entrance-sharp` | entering, mask-wipe decel | `.20,.75,.34,.94` | fast in, soft land |
+| `settle-soft` | settling, count-up landing, logo lockup | `.00,.65,.51,.99` | deep ease-out, no bounce |
+| `kinetic-ui` | expressive small state move (toggle, accent) | `.85,.46,.14,.53` | lively — not every UI move |
+| `expressive-pop` | active kinetic word, brand flourish | `.94,.75,.34,.94` | fast-out + soft settle (overshoot opt-in) |
+| `travel-balanced` | object travel, camera, state-to-state | `1.00,.49,.00,.55` | S-curve ease-in-out |
+| `exit-accelerate` | exiting, hard-cut companion | `1.00,.02,.54,.42` | slow start, fast end |
+| `travel-cut` | only interrupted / masked / cut-before-settle | `.15,.85,.95,.05` | fast-slow-fast, never settles |
+
+- Derive, don't invent: start from the nearest anchor and adjust one quality —
+  acceleration, coast, landing softness, exit speed, overshoot. Reach for a new
+  curve only when no anchor fits.
+- Per-property orchestration: choose *how* properties coordinate, not just which
+  easing each uses — match the method to the motion character. *Locked*
+  (start/end together) for UI, panels, buttons, mechanical/synced state.
+  *Lead/follow* (one property leads a few frames, another follows) for
+  logo/hero/organic, where position, scale, rotation, opacity, masks, trim, or
+  number changes may use different curves, start/end frames, or durations.
+  *Primary/secondary* (one property carries the motion, others support subtly).
+  *Early-opacity/late-settle* (opacity resolves fast while position/scale keeps
+  settling, for readability). *Single-property overshoot* (only scale or
+  rotation overshoots, position stays controlled).
+- Hierarchy: only the focal element gets the strongest personality
+  (`expressive-pop`, overshoot, snap); support uses quieter anchors
+  (`settle-soft`, `travel-balanced`).
+- Distance/duration: large travel → smoother acceleration and more time (don't
+  snap); tiny UI → short, not theatrical; camera → calmer than the objects in it.
+- Typography: support `settle-soft`; active word `expressive-pop`/`entrance-sharp`.
+  Count-up: near-linear digits, `settle-soft` landing. Mask-wipe: `entrance-sharp`,
+  revealed content `settle-soft`.
+- Hard cut / jump cut / chapter transition: outgoing `exit-accelerate` (or
+  `travel-cut` for long travel), cut before it settles; pair with a motion-masked
+  swap when continuity matters — see Chapterization And Transition Grammar.
+- Loop reset: match first/last velocity; use a visible reset only via
+  `exit-accelerate`+cut.
+- Overshoot: small, premium-off by default. Prefer a settle-back keyframe (past
+  the target, then ease back — Skottie-safe); end `i.y` ~1.08 to 1.2 is the
+  compact alternative.
+- Also useful: anticipate (pull slightly opposite before a fast reveal),
+  steps/holds (typewriter, counters, scans, technical beats), and continuous
+  linear (rotations, scanners, progress loops, mechanical seams).
+
+## Choreography
+
+- Decide the lead element, then delay supporting elements by 2-8 frames for
+  compact UI and 4-14 frames for expressive scenes.
+- Stagger from the meaningful origin: first, center, last, path direction, or
+  focal point.
+- Let opacity often start after movement begins and finish before the settle.
+- Do not animate every property on every layer. Stillness gives motion contrast.
+- Scrub around the settle. The final 10-20 percent of motion should feel
+  intentional, not like a numerical drift.
+
+## Reveal Grammar
+
+- Use build, settle, hold as the default reveal spine. The hold is where the
+  message or brand registers.
+- Reveal in reading or importance order. Hero/focal subject lands first;
+  labels, stats, metadata, and support arrive after.
+- Stagger repeated items by about 3-6 frames for compact motion or 50-80 ms for
+  scene-level beats.
+- Prefer mask-wipes, marker sweeps, trim-path draw-ons, and purposeful cuts over
+  uniform opacity fades for premium scenes.
+- One scene or beat should have one main flourish. Too many reveals in the same
+  beat weakens hierarchy.
+
+## Chapterization And Transition Grammar
+
+- Gate: if the prompt carries more than one idea (long text, lists, multiple
+  stats, timeline, before/after, problem/solution, quote+proof, walkthrough,
+  recap/story, multi-language or repeating variations), split it into chapters
+  instead of cramming one scene. A single-purpose beat (logo lockup, one CTA, one
+  stat, legal/read-critical, calm hero that must settle) stays one beat and lands.
+- Give each chapter one readable job, and let the main message get a coast or
+  hold before any seam.
+- Choose each transition by seam purpose — preserve continuity, create contrast,
+  reset rhythm, or land a point — not at random. A transition is chapter role +
+  timing + direction + cut point + masking + easing, not easing alone.
+- For dense/multi-part prompts, read
+  `references/chapterization-transition-grammar.md` for the full when/when-not,
+  roles, structure modes, transition grammar, selection, cut-on-action mechanics,
+  easing-anchor support, and guardrails.
+
+## Motion Economy
+
+- Motion should reinforce the same hierarchy as the final frame: focal subject
+  strongest, support calmer, accents lowest priority.
+- Animate fewer properties when that produces a clearer read.
+- If movement makes the scene feel busy, crowded, or unfocused, simplify the
+  visual structure before adding more motion.
+- Effects, camera moves, and staggers should never compensate for weak layout.
+  Revise the composition first.
+
+## Typography Choreography
+
+- Treat kinetic typography as phrase performance, not uniform text entrance.
+- Assign anchor, support, and active text. Let the active word or phrase carry
+  the strongest motion while support text stays calmer.
+- Use semantic easing and spacing: sharp words can hit harder, soft words can
+  settle gently, heavy words can land lower, and flowing words can travel
+  continuously.
+- Offset position, scale, mask, opacity, and layout timing so words relate to
+  the phrase instead of sharing identical keyframes.
+- Preserve reading order. Expressive motion should make the phrase clearer, not
+  harder to parse.
+
+## Data And Figure Motion
+
+- Animate data by its own logic: bars grow from baseline, lines draw left to
+  right, segments widen to proportion, dots populate, rings nest or emanate,
+  and Sankey-like flows route from source to target.
+- Count figures up with baked keyframes, tabular numerals, and an ease-out
+  settle. Let labels or units arrive after the number resolves.
+- Sync labels to geometry. A point label should resolve as the line reaches it;
+  a bar value should count while the bar grows.
+- Use mask-wipes for insight headlines and trim paths for hairlines, axes,
+  connectors, rules, and chart strokes.
+- Serious data needs calm ease-out and no bounce. Small pops are acceptable only
+  for badges, consumer/wellness warmth, or bold social panels.
+
+## Camera, Parallax, And Scene Motion
+
+- Treat camera motion as the viewer's attention, not decoration.
+- Use one dominant camera move: push in, pull out, pan, follow, or parallax.
+- Move foreground, subject, and background at different rates only when it
+  clarifies depth.
+- Keep camera easing smoother than object easing. Abrupt camera stops feel cheap.
+- Avoid pan/zoom that makes text unreadable or crops the hero subject.
+
+## Path Reveals And Loops
+
+- Path drawing should follow the natural reading or construction order.
+- Keep trim-path speed visually even; short segments may need shorter durations.
+- For handwriting/path reveals, add a slight follow-through or ink settle only
+  if it suits the style.
+- For loops, match first and last frames in position, opacity, color, and
+  perceived velocity.
+
+## Loop And Generative Motion
+
+- Repeated fields need phase offsets by index, distance, row, or path position.
+  Lockstep pulsing reads mechanical unless the prompt asks for it.
+- Engineer loop seams with identical first/last frames, integer wave cycles,
+  closed rotations, wrapped drift, or recycled emanation rings.
+- Give ambient loops one conceptual beat: pulse, mirror, morph, inversion,
+  density build, or recovery to order.
+- Use one repeated primitive and one main animated property where possible.
+- Rich motion is licensed when the animated abstract element carries the
+  message. Keep surrounding type, UI, and support calmer.
+- Morph the same objects between states instead of spawning unrelated new
+  objects when continuity is important.
+
+## Style Presets
+
+- `premium-settle`: slower reveal, low overshoot, elegant final ease.
+- `kinetic-snap`: fast stagger, strong contrast, crisp settles.
+- `soft-interface`: small distances, low overshoot, short duration.
+- `technical-trace`: trim paths, precise timing, minimal flourish.
+- `ambient-loop`: no visible seam, constant perceived energy.
+- `playful-pop`: larger scale contrast, friendly overshoot, quick recovery.
+- `data-confirm`: insight headline, geometry reveal, synced count-up, calm hold.
+- `phase-field`: repeated primitive with baked offsets and seamless loop.
+
+## Render-Aware Motion
+
+- Bake counters, particle offsets, orbit math, physics, and expression-like
+  systems to keyframes before relying on Skottie.
+- Fake velocity with offset duplicate layers instead of motion blur.
+- Treat blur, bloom, glass, chrome, dither, true 3D, and displacement as
+  renderer-risky. Approximate with vector shapes, stacked tonal fills, or baked
+  raster assets.
+- Path morphs require compatible vertex structures. If not safe, use masks,
+  replacements, or crossfades.
+- Cap dense fields and verify performance. Repeater-based fields cannot assume
+  independent per-instance animation.
+
+## Final Motion Review
+
+- Scrub playback. First and last frames alone are not enough to judge timing,
+  stagger, readability, or settle quality.
+- Inspect key beat frames: frame `0`, early reveal or first meaningful beat,
+  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: the focal subject should lead, support should follow, and
+  accents should not steal the read.
+- Check stagger origin and spacing: repeated elements should begin from the
+  meaningful source, path direction, reading order, or focal point.
+- Check timing and easing: entrances should feel intentional, not uniform;
+  settles should land cleanly without drift, snap-back, or accidental float.
+- Check readability during motion: text, data, icons, and UI states should be
+  parseable at the moments they matter.
+- If motion feels busy or hides weak layout, simplify the visual structure or
+  reduce animated properties before adding more choreography.
+
+## Checks
+
+- Midpoint should communicate what is happening, not only look like transition
+  blur.
+- The final settle should land in the strongest composition, not only stop on a
+  valid frame.
+- Loop start/end should be invisible unless a reset is intentional.
+- Secondary motion should never distract from the requested message.
+- If an animation feels generic, adjust stagger origin, easing intent, or the
+  final settle before adding more effects.
+- For kinetic typography, reject motion where every word uses the same entrance
+  timing and property changes unless the prompt asks for a minimal reveal.