Communitygithub.com

isometric-svg-animation

Isometric architecture diagrams generated as animated SVG by a build script. Use when asked for an isometric or 2.5D system, pipeline or architecture diagram, an animated SVG flow illustration for a website, or to revise a diagram built this way.

What is isometric-svg-animation?

isometric-svg-animation is a Claude Code agent skill that isometric architecture diagrams generated as animated SVG by a build script. Use when asked for an isometric or 2.5D system, pipeline or architecture diagram, an animated SVG flow illustration for a website, or to revise a diagram built this way.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/413ZERO/isometric-svg-animation/tree/HEAD

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Isometric SVG animation

One script (node build.mjs) places every shape in plan units, projects it to isometric, and writes a self-contained diagram.svg (CSS keyframes inside, plays as a plain <img>) plus preview.html (the same SVG inlined and scaled to the window). Nothing is drawn by hand: every fix is a code change and a rebuild.

Before writing the script, read references/generator.md: its sections, and the core code for projection, cards, ground text, routes, keyframes, platforms and assembly.

Steps

  1. Story. Read the system's own docs, then write the diagram's story as one line: what comes in, what processes it, what drives the work, what comes out. The flow reads bottom-left to top-right. Done when every stage in the line is a node you can name in one to three words and the user agrees with the line.
  2. Brief. Get one reference image for the feel (line weight, density, platform style); when the user has none, show the diagrams in references/examples.md and let them pick. Settle theme, aspect ratio (1.6:1 fits one browser window), and where the SVG will live. Done when all four sit in the script's header comment.
  3. Static build. Platforms, nodes, routes, labels; no motion yet. Done when the build's audit prints no overlaps and no tight corners, and the user has signed off a screenshot of the layout.
  4. Motion. Add the loop. Done when one loop plays the story once, in order, and reduced motion shows the finished state.
  5. Export. See Export below.

Each review round: take the user's notes one at a time, answer any question before changing anything, copy the current build into versions/ before a large change, and reply with a screenshot. When the user is choosing between names or icons, render the options side by side.

Principles

Content

  • One flow, few details. Each node is named for what it really does; when a name is contested, say which is accurate and why, then let the user pick.
  • Every label reads on its own to a stranger. A label that needs explaining is rewritten or cut.
  • A stack of plates only for a thing that really is a pile (the pages of a report); every other node is a single card.
  • Honest side paths stay drawn (inputs that skip a stage), even when they cost space.
  • External systems sit on platforms with the same fill as internal ones; a dashed edge alone marks them external.
  • Loose inputs lie flat on the ground, with no platform under them.

Geometry

  • Plan units everywhere: a runs along the flow (screen up-right), b across it (screen down-right), z up. Positions, sizes, gaps and routes are plan units; screen pixels exist only inside the projection.
  • A card is a top face plus a side band (the hull of its top and bottom outlines) with one stroke on the outer contour, and the face meets the thickness with no line. Platforms stroke their top face instead, since that face lies on the grid.
  • One thickness for every card and module pill. Name pills lie flat with no thickness.
  • Paint in layers (ground, platforms, wires, objects, labels), sorted by depth within each.

Text

  • Every label lies on the ground plane with its baseline along a. Glyphs are outlined to paths at build time, so the SVG renders the same as an <img> anywhere and loads no font.
  • Sizes come from one small table (pill, label, small, caption, title). Platform titles are spaced monospace capitals.

Layout

  • A ground grid at 2 units. Platform edges snap outward to grid lines; gaps between platforms and between rows are whole cells; a shared trunk line runs on a grid line centred in its gap.
  • Platforms size themselves: every node and label registers its footprint with its platform, and the platform is that box plus one uniform padding, snapped to the grid. Platforms in a row share their facing edges.
  • A platform title sits as far from the left edge as from the front edge (measured to the foot of its capitals), left-aligned with the content.
  • The grid runs past every edge of the frame and fades out through an ellipse with the frame's aspect, so the picture has no hard edge. The background is transparent.
  • Every build prints an audit: each platform's four margins, the gaps between platforms, label × label and label × card overlaps, and corners too tight for their radius. Read it before showing anything.

Lines

  • Every connection is one continuous path: orthogonal, with quarter-turn corners of one fixed radius, so routes that share a stretch share it exactly and a branch leaves its trunk along a tangent. Draw routes first and nodes on top; the result has no stubs, forks or gaps.
  • Line kinds differ by pattern: solid for the flow, dashed for an external rail, round dots for read-only access.

Tone

  • Tone is state. Neutrals only (R = G = B). Light = not reached yet, one step darker = its input is ready, darkest = done this run. Icons and outlines follow the same rule, so any "why is this one darker?" has a state for its answer. The darkest ink is a mid-dark grey; pure black and solid dark blocks stay out.
  • Lines rest very light and darken only after a light has run along them.
  • Colour means working right now: the card stays white while a hint of the brand gradient shows through from beneath it, with a faint glow around it. Lights take their colour from one gradient laid across the whole picture along the flow.
  • An accent for one phase (for example, inputs being picked up) shows only while lit, then returns to the grey it rested in.

Motion

  • SVG animation: CSS keyframes inside the SVG, no script, playing as an <img>. A rendered video only when asked for.
  • The resting style is the finished run; the keyframes start each loop from an untouched run. Reduced motion and a static export therefore show the finished diagram.
  • Time comes from geometry. Lights travel at one screen speed (about 400 px/s); each arrival is start + route length ÷ speed, and the next event is that arrival plus a pause. Move a node and the timeline follows. Compute the whole timeline, and the loop length with it, before writing any keyframe.
  • One loop tells the story once: inputs travel in, the driver runs top to bottom, the pieces gather and the output assembles, export, hold, clear, repeat. Slow enough to follow (about 20 s).
  • A light is a short dash run along its route with a softer, wider halo; a darker trace stays behind it until the loop clears. A working node lifts a few pixels, glows, and flashes its gradient face.

Render cost

As an <img>, any running animation makes the browser re-rasterise the whole picture every frame.

  • Masks, filters and groups stay small: the grid fades through its own stroke gradient, and a mask hugs the path it reveals.
  • Anything that cannot be seen is visibility: hidden (opacity 0 and a dash parked off its path still get painted).
  • Identical keyframes are written once.

Export

  • Static PNG: open the SVG document itself with reduced motion emulated and screenshot it. Inside an <img> the emulation never reaches the SVG, and you capture the first frame of the loop instead.
  • Previews live in a standalone page served locally, outside the user's site, until the user places the SVG.

Related Skills