Hermes Wiki
TechResearch/TechConcepts_Explanatory_Animations/code_based_animation_setup

Code-Based Animation — Setup Reference

Use this for: anything with real state — a value lagging then catching up, a node highlighting because of data, a bar whose width represents a number, or any diagram with more than a handful of repeated components. If the video is "watch this get drawn once," use the Excalidraw doc instead.

Three tiers, escalate only when the previous one genuinely can't do the job — see the "when to escalate" note under each.

Tier 1 — Plain HTML + CSS + SVG + vanilla JS

Setup: none. Literally one .html file, opens directly in a browser, zero build step, zero dependencies. This was kafka-demo.html from this thread — the whole interactive producer/partition/consumer demo, timers included, in one file you can screen-record.

What it's good for: anything where the "shapes" are simple enough to hand-position (boxes, lines, a handful of labeled nodes) and the animation is CSS transitions/keyframes plus setInterval/setTimeout for timing, or direct DOM manipulation (document.createElementNS for SVG elements) for things appearing/moving.

Core techniques used so far:

  • CSS @keyframes + transform: translate(var(--dx), var(--dy)) for "fly in" effects
  • CSS transition: transform .6s ease on an element, then just changing its style.transform in JS — the browser handles the interpolation
  • setInterval for anything that should happen on its own timer, independent of user clicks (this is what made the Kafka "consumer catches up on its own pace" effect work)

Stay here until: you're hand-writing the same box/label/icon pattern more than ~4-5 times per diagram, or a value in the diagram needs to be computed from real data rather than eyeballed into a CSS value.

Tier 2 — React Flow + Framer Motion (add only when needed)

When this tier actually earns its cost (per the tracing-pipeline case): repeated node/edge components (~10+), programmatic highlighting/state changes on existing elements, or data-driven bar widths / layout.

Setup:

npm create vite@latest my-diagram -- --template react
cd my-diagram
npm install reactflow framer-motion
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
  • React Flow — the actual node/edge diagram engine. You define nodes (with data) and edges; it handles layout, connections, and re-renders when data changes. This is what makes "highlight the bottleneck node" trivial — it's just a state update, not a redraw.
  • Framer Motion — for the pulse-along-an-edge, glow-on-highlight, staggered reveal effects. <motion.div animate={{...}}> with a transition prop covers most of what we saw in the tracing reel (the traveling red dot, the orange glow ramp on Cart/Catalog).
  • Tailwind — only pays for itself once you're styling the same card/node shape many times consistently. For one or two custom elements, plain CSS is less overhead — don't reach for Tailwind by default, reach for it once you notice you're copy-pasting the same class list across nodes.

Recording: run npm run dev, open the local URL, full-screen the tab, screen-record — same workflow as Tier 1, just a dev server in front of it instead of a static file.

Bridging the two visual styles

If you want the Excalidraw hand-drawn feel on top of a precisely engineered React/CSS diagram (icons, data bars, highlighting) without actually using Excalidraw:

  • Embed Excalifont (Excalidraw's own open font) as a plain @font-face in your CSS, and apply it only to the casual annotation text ("a customer," "TRACE ID," titles) — not the structured labels. This is the trick that keeps the creator-style consistency across a cut between an Excalidraw-drawn opener and a code-driven data segment.
  • rough.js (the library Excalidraw itself uses for the wobbly-line look) is standalone and npm-installable if you ever want the hand-drawn stroke look on a shape that also needs to be data-driven — a genuinely advanced move, only worth it if the mixed aesthetic becomes a recurring need across videos.

Icons and logos

Same sources as the Excalidraw doc, but here they're used as proper SVG components (crisp, not flattened into one block) since React can import and style them directly:

  • Simple Icons — npm package simple-icons gives you every brand SVG as an importable React-friendly path; good for company/product logos in a diagram.
  • Iconify — npm install @iconify/react, then <Icon icon="logos:kubernetes" /> style usage — covers Kubernetes, AWS, GCP, and hundreds of icon sets under one API. Almost certainly the fastest path for the service-mesh-style hexagon icons seen in the tracing reel.
  • Lucide (lucide-react) — general-purpose UI icons (arrows, status dots, checkmarks) for the chrome around your diagram, not brand logos.
  • Official kits when precision matters for a specific platform: Kubernetes icons, AWS Architecture Icons — download the official SVGs rather than an approximation from an aggregator when the diagram is about that platform specifically.
Hermes Wiki