Create hand-crafted, dependency-free animated SVGs: self-drawing paths and signatures, loading spinners, morphing shapes, motion along a path, animated gradients, waves, pulses, and animated logos, icons, and badges — up to complex layered scenes with choreographed build-ins, particle fields, and parallax — choosing the right technique (CSS vs SMIL) for how the SVG is delivered (inline HTML, <img>, CSS background, GitHub README, favicon). Use when the user wants any animated SVG, asks to animate an existing SVG, icon, logo, or favicon, wants an animated scene, illustration, hero background, or banner, or mentions SMIL, stroke drawing, dashoffset, path or shape morphing, motion path, loader, spinner, animated checkmark, particles, parallax, or a "draws itself" effect.
Create hand-crafted, dependency-free animated SVGs: self-drawing paths and signatures, loading spinners, morphing shapes, motion along a path, animated gradients, waves, pulses, and animated logos, icons, and badges — up to complex layered scenes with choreographed build-ins, particle fields, and parallax — choosing the right technique (CSS vs SMIL) for how the SVG is delivered (inline HTML, <img>, CSS background, GitHub README, favicon). Use when the user wants any animated SVG, asks to animate an existing SVG, icon, logo, or favicon, wants an animated scene, illustration, hero background, or banner, or mentions SMIL, stroke drawing, dashoffset, path or shape morphing, motion path, loader, spinner, animated checkmark, particles, parallax, or a "draws itself" effect.
Animate SVG
Hand-craft SVG animations with nothing but markup — no JS libraries, no build step. Every SVG element is a DOM node you can animate with CSS or native SMIL.
Workflow
Pick the technique for the delivery context (table below). This decides everything else.
Build the static artwork first and confirm it renders. Need path/shape/gradient/filter syntax? Read references/paths-and-shapes.md.
Add animation. For SMIL (<animate>, timing chains, easing, morphing) read references/smil.md. For ready-made patterns (spinner, checkmark, morphing menu icon, waves, shimmer, orbits) read references/recipes.md and adapt. For complex multi-element pieces — layered scenes, hero art, particles, parallax, choreographed build-ins — read references/complex-scenes.md and follow its storyboard-first method.
Accessibility pass (below) — every deliverable.
Verify (below) — open it, watch it, check reduced motion.
<style>inside the file and SMIL. No JS, no external CSS/fonts/images, no pointer events
CSS-in-SVG for simple loops; SMIL for chained, timed sequences
Needs interaction (hover, click-to-toggle)
Only inline SVG (or <object>) receives events
CSS :hover or SMIL begin="click"
The most portable form is a single .svg file animating itself via an internal <style> block or SMIL — it works everywhere except where JS is required.
Non-negotiables
pathLength="100" on anything you stroke-animate. It normalizes the geometric length so stroke-dasharray/stroke-dashoffset work in 0–100 units. Never guess lengths, never reach for getTotalLength(). Works on <path>, <circle>, <rect>, <line>, <polyline>, <polygon> in every evergreen browser — do not hand-compute circumferences "for legacy Safari". On closed shapes, make the dash slightly longer than the path (stroke-dasharray: 101) — an exact-length dash leaves a visible seam at the path start.
Author the resting state as the FINAL state; keyframes supply the start. Base styles show the finished artwork; the animation's from/0% moves it back to the beginning. Then disabling animation (reduced motion, ancient renderer) shows the art — not a blank.
CSS transforms on SVG children need transform-box: fill-box; transform-origin: center; — otherwise center means the viewBox origin/center and your "spin in place" orbits the whole canvas. SMIL rotation takes the center inline instead: from="0 25 25" to="360 25 25".
Hold the end state: CSS animation-fill-mode: both (or forwards); SMIL fill="freeze". Staggered starts need both/backwards so delayed elements sit at their from state during the delay.
viewBox always; add width/height attributes only to give an intrinsic size for <img>/favicon use.
Stay on the compositor: animate transform and opacity freely; animating d, geometry attributes, gradients, or filters repaints every frame — keep those elements small and few.
Morphing d interpolates only between paths with the same command sequence (same count, types, order).
Seamless loops: first value equals last value (values="A;B;A"), and easing splits symmetrically across the segments.
Stagger, don't dogpile: chain with animation-delay / begin="id.end" so the eye follows one motion at a time.
stroke-linecap="round" makes drawing effects look finished.
Accessibility
Meaningful graphic: role="img" on the <svg> plus a first-child <title> (add <desc> for detail). Decorative: aria-hidden="true".
Delivered via <img>, the internal <title> is not announced — tell the user to also set alt="…" on the <img>/Markdown embed.
Ship reduced-motion handling inside the file so it travels with it. Because base styles are the final state (rule 2), this is just:
SMIL cannot be media-queried. When reduced-motion support matters and the target is <img>-like, prefer CSS-in-SVG; if SMIL is unavoidable, keep the motion gentle (opacity fades, slow drifts — no spinning or flashing).
Canonical example — house style in one file
Self-drawing "success" badge for a README (<img>-safe, reduced-motion-safe, accessible):
Note the pattern: pathLength="100" (no measured lengths), dash 101 (no seam on the closed circle), base state = finished, from keyframe = start, both makes the delayed check invisible until its turn, reduced-motion shows the final art.
Verify before delivering
Save the file and open it in a real browser: open out.svg (macOS) / xdg-open out.svg (Linux).
Watch a full cycle: end state holds (no snap-back), loops have no visible seam, nothing orbits off-center.
Reduced motion: DevTools → Rendering → emulate prefers-reduced-motion: reduce → the finished artwork must be visible, not a blank canvas.
For <img>/README targets, confirm the file is self-contained: no <script>, no external href/url() references, and interactivity-dependent triggers (begin="click", :hover) aren't load-bearing.
