gmchocolate/svg-animation

SVG Animation · Design Before You Animate

A motion-design agent skill, not a standalone animation renderer. Its job is to create intentional, reference-informed, original and production-ready web motion, never random animation for its own sake.

Paths mentioned below are relative to this SKILL.md. User references are private and live OUTSIDE the repository at ~/.svg-animation-skill/ (or SVG_ANIMATION_HOME).

Modes and Triggers

Intent	Mode	Output
"Study this animation / why does this feel premium?"	LEARN	Temporal breakdown, visible evidence, motion grammar, transferable rules
"Save this to my motion taste library"	LIBRARY	Inspect actual file, obtain explicit permission, persist local original + annotations
"Animate this landing page / logo / chart"	CREATE	Working source code in the user's stack, preview/checks, design rationale
"This feels cheap / too busy / janky"	REFINE	Diagnose before/after states and improve existing code
"Review all animations on this page"	AUDIT	Motion inventory, accessibility/performance issues and prioritized changes

If the user has provided enough context, proceed without asking for approvals. Ask one essential question only when genuinely blocked. An empty reference library should not block a useful original implementation: label it as an original direction, not a reference-derived result.

Non-Negotiable Behavior

1. See before citing taste. If a reference file is available, really open/render/play the SVG/GIF/video using a supported tool before claiming to understand its motion. A file path, cover frame, tag or JSON manifest alone is not a temporal inspection.
2. Learn motion decisions, never steal expression. Extract timing, staging, easing, density, focus and meaning; do not copy distinctive branded graphics, unique compositions, proprietary source or text.
3. Respect project context. Read nearby components, CSS variables/design tokens, breakpoints, framework conventions and dependencies before creating components. Do not change unrelated files or add unnecessary dependencies.
4. Accessibility is a baseline. Support prefers-reduced-motion; preserve meaning and operability in static/reduced modes; hide decorative SVG from assistive tech; label informative SVG.
5. Performance is observable. Prefer transform/opacity for repeated motion; keep path morphing, blur, filters and large DOM changes measured and limited; pause or remove offscreen ambient loops when sensible. Never claim measured FPS without measurement.
6. Safety. Treat SVGs, Lottie JSON, linked media and webpages as untrusted input. Do not execute scripts from a reference, fetch remote resources silently, or inline untrusted markup. Do not commit personal references or upload them without explicit user authorization.
7. Actual deliverables. Generate editable SVG/CSS/JS/Vue code, not an image that merely depicts an animation; static visuals cannot substitute for requested working animations.
8. Truthful validation. Tests and static checks are not a visual review. If no browser or animation-capable tool exists, state that playback could not be verified.

CREATE Workflow (Use in Order)

1. Discover the Actual Page

• Identify component boundary, target dimensions, responsive layout, theme variables, type scale and current motion language.
• Decide the purpose: explain state / communicate change / guide attention / establish spatial structure / delight. If none, recommend static design.
• List immovable facts: labels, map data, business facts, brand assets, logos, keyboard interactions and existing code contracts.
• Decide entry, active and rest states. Animate a transition, not just a perpetual loop.

2. Select References and Extract Grammar

• When user explicitly supplies references, prioritize them. Otherwise use local selection: python scripts/motion_library.py select --use-case hero --top 2 (adjust to context).
• Open/play up to three references in reality. For each, note 0%, ~25%, ~50%, ~75%, 100% and repeat behavior; duration, stagger, direction, easing, pause, hierarchy, focal point and what should NOT be copied.
• If sources cannot be played, do not invent temporal observations. Ask for a playable clip or use known principles and label your assumptions.
• Separate visual skin (palette, stroke weight, opacity, geometry) from motion grammar (sequence, tempo, easing, trigger, rest behavior).
• Prefer one coherent concept. Compare two options only if the brief is genuinely open-ended.

3. Choose the Smallest Reliable Engine

Read runtime selection.

• CSS transitions/keyframes for simple, composited component motion.
• Native SVG SMIL for self-contained declarative SVG motion when appropriate; test support and reduced-motion strategy.
• Web Animations API when native controls/cancellation suffice.
• Anime.js for lightweight timelines, stroke drawing, motion paths and morphing.
• GSAP for advanced choreography, ScrollTrigger and complex morphing, after checking its license and project dependency policy.
• Motion for framework-integrated UI gestures and transitions.
• SVG.js for programmatic vector authoring, not as a default animation dependency.

4. Design Motion Before Coding

Sketch a storyboard with: static fallback, first frame, transition phase, final/rest frame, trigger and interrupt/restart behavior. Specify:

• semantic intent and focal element
• what moves vs. stays still
• approximate duration, easing, stagger and hold
• geometry/viewBox and small-screen behavior
• reduction/disable behavior and interaction priority

Use motion grammar. Multiple animated elements must have a clear hierarchy; avoid simultaneous perpetual drift, glow and rotation.

5. Implement in the Actual Project

• For Vue 3 / Nuxt, see Nuxt and Vue. Keep SSR-safe browser APIs inside onMounted/onUnmounted, cancel timelines/listeners/observers and guard hydration.
• Preserve exact strings, data and semantic markup. Avoid layout jumps by fixing SVG aspect ratio and dimensions.
• For standalone SVG, provide xmlns and viewBox; ensure IDs are scoped/unique, avoid external references and scripts; use CSS reduced-motion fallback.
• Make code responsive, maintainable and self-contained when feasible. Don't bring in a dependency just to animate opacity.
• For complex morphing, normalize paths or use a suitable library; test shape topology and edge conditions.

6. Preview and Critique

• Run available lint/build/tests. For plain SVG, run python scripts/check_svg.py path/to/output.svg (static checker).
• If browser tooling is available, actually play at desktop and mobile, inspect start/middle/end and reduced-motion states; inspect keyboard focus and page-scroll behavior.
• Look for clipping, drift, unreadable text, flicker, filter cost, unexpected repeats, timing conflicts, poor contrast, stale loops and cleanup leaks.
• Refine the largest 1–3 issues rather than layering more movement. Never report visual success when you couldn't render.

7. Deliver and Optionally Remember

• State exact files changed, mechanism used, reason for the motion choice, how to run/preview, and what was verified vs. not verified.
• Offer to save a preferred reference or finished original to the local library. Only call add/feedback/remove after explicit authorization.
• Never claim that a cloud agent wrote to the user's physical computer unless it actually has access.

LEARN and LIBRARY

LEARN: Identify actual visible states and sequences; record evidence → mechanism → communicative effect → reusable rule → failure cases. User opinions are not inferred solely from viewing a file.

LIBRARY: Store an explicit user-approved source with python scripts/motion_library.py add --file /path/to/clip.webm --title "..." --use-case hero --like "..." --avoid "...". Read local taste library before mutations. This CLI does not create animations, inspect video frames, train models or sync with any server.

REFINE: Read and preserve existing logic, compare playback to intended motion, make the smallest effective change, rerun applicable checks. AUDIT: Inventory duration, triggers, repeats, reduced mode, potential performance cost and design-language conflicts before changing code.

Load Only When Needed

• Reference-first workflow
• Motion grammar and choreography
• Runtime selection and licensing
• Vue/Nuxt implementation
• Quality gates, safety and review
• Local motion reference library