Hermes Wiki
TechResearch/TechConcepts_Explanatory_Animations/excalidraw

Excalidraw + excalidraw-animate — Setup Reference

Use this for: static architecture diagrams and "watch it get drawn" reveals. Not suited for state changes, data-driven layout, or precise icons — see the code-based doc for those.

1. Excalidraw itself

No install needed for normal use — it's a browser app: excalidraw.com. Draw, then File → Save to export a .excalidraw JSON scene file.

Self-hosting / embedding (only needed if you want it inside your own app, e.g. an internal tool):

  • Repo: github.com/excalidraw/excalidraw
  • It's a React component (@excalidraw/excalidraw on npm) — npm install @excalidraw/excalidraw, drop <Excalidraw /> into a React app. Only worth this route if you're building an editor experience, not for one-off diagrams.

Generating scenes programmatically (what we did for the Kafka diagrams): the .excalidraw file is just JSON — { type, version, source, elements: [...], appState, files }. Each element (rectangle, text, ellipse, arrow) needs a specific set of fields (id, x, y, width, height, strokeColor, seed, version, versionNonce, etc.). Write a small Node script with helper functions (rect(), text(), arrow()) rather than hand-writing JSON — see build-excalidraw-scene.js from this thread as a working template.

Watch for: negative width/height on any element — OOXML-style renderers tolerate it, Excalidraw itself is fine, but it's worth keeping positive on principle since it's bitten us before (PPTX). Always open the generated file in excalidraw.com first to sanity-check positions before animating — there's no offline renderer to QA it with.

2. excalidraw-animate

Web tool (no setup): dai-shi.github.io/excalidraw-animate — click Load File, pick your .excalidraw, hit play.

Repo: github.com/dai-shi/excalidraw-animate

How it actually works: animates each element's stroke path from 0% to 100% length, in element-creation order — i.e., whatever order you drew things (or pushed them in your generator script) is the playback order. It cannot move, restyle, or replace an existing element — only reveal new ones. Plan your script's element order as your narration order.

npm package exists (excalidraw-animate on npm) but its programmatic API isn't publicly documented — stick to the Load File web workflow rather than guessing at function calls.

Export options: SVG export is reliable. WebM export is flakier per the project's own README — screen-record the web playback if WebM output looks off.

Timeline you'll see in the exported SVG: SMIL <animate> tags per stroke, fill="freeze" (drawn strokes stay drawn), roughly 500ms per stroke with a small stagger. A ~10-15 element diagram runs about 10-12 seconds full playback — budget accordingly against a 60-second reel.

3. Fonts — getting the hand-drawn look right

  • Virgil is Excalidraw's default font and what gives it the signature look. No action needed — it's built in.
  • Excalifont is Excalidraw's newer, more polished hand-drawn font (used in recent versions). If you want it standalone (e.g., as a CSS font-face in the code-based pipeline for consistency), it's open and embeddable — check the Excalidraw repo's packages/excalidraw/fonts directory for the font files directly.

4. Icons and logos

Excalidraw only draws primitive shapes (rectangle, ellipse, arrow, freedraw, text) — anything more specific (a Kubernetes wheel, an AWS service icon) has to be imported as an image, which means it renders as one flat block on reveal (can't be stroke-animated). Sources, roughly in order of fit:

  • Simple Icons — ~3000 brand/product SVG icons (single color, MIT-licensed), the most common source for "Docker/K8s/AWS logo in a diagram." Copy the SVG path directly.
  • Iconify — aggregates Simple Icons plus dozens of other sets (including official Kubernetes icons, AWS Architecture Icons, Devicons) under one consistent API — better if you want icon sets rather than one-offs.
  • Official brand/architecture icon kits — worth using directly when precision matters: Kubernetes icons, AWS Architecture Icons, Docker's brand guidelines page. These are the actual source-of-truth assets the polished reels are using.
  • Devicon — language/tool logos (Python, Node, Postgres, etc.) in consistent style, useful for "tech stack" diagrams.
  • To drop one into Excalidraw: File → Insert Image (or drag-drop the SVG/PNG onto the canvas), resize, then leave it out of the "stroke reveal" story or accept it fades in as one block — see the tracing-pipeline doc for why this became a hard limit on Excalidraw entirely once icons + data + highlighting all needed to coexist.
Hermes Wiki