The Diagrams Stopped Shipping JavaScript

Here's how I'd have shipped diagrams on a docs site: pull in the Mermaid library, let it render the flowchart in the reader's browser, call it done. It works, it's a few kilobytes of someone else's JavaScript running on every visitor's machine, nobody complains. I've literally done exactly this.

This week the agents did something quieter and much better. Now each diagram is rendered once, at authoring time, into a plain SVG picture that gets committed straight into the repo. The visitor's browser fetches zero bytes of Mermaid — the library isn't even a runtime dependency anymore, it got demoted to a build-only tool. The page just paints a static image.

Except — and this is the part I keep re-reading — it's not really static. A pre-rendered picture normally means frozen colors, which would break dark mode. So when they render it, they don't paint the real colors at all: they paint deliberately obvious placeholder colors, then find-and-replace each placeholder with a CSS variable reference. (The renderer has to draw with some literal color, so they feed it ones they can reliably spot and swap afterward.) The result is frozen geometry with live colors — the committed image still recolors itself when you flip to dark mode, or move between the site's separate sections, each of which has its own palette. The commit message even records the proof: one node's fill going from rgb(236,240,230) in light to rgb(31,37,28) in dark, same file on disk, nothing re-rendered.

And then the parts I'd definitely have skipped. Each diagram is keyed by a hash of its source, so a stale picture can't silently drift out of sync with the text that made it — and there's a build check that fails the whole build if a diagram's source changed but its committed picture didn't. There's an automated browser test asserting the page shows the SVG and that no Mermaid code gets fetched — a test whose entire job is to prove the library really is gone. There's even a short written decision note (they keep these for anything load-bearing) explaining exactly where the baked picture gets slotted back into the page.

That's the thing that gets me. The idea — "just render it at build time" — I might have gotten to on a good day. The recoloring trick, the drift check, the test that proves the dependency vanished, all the little invariants that make it actually correct instead of merely working? That's the gap between me and the thing writing these commits, and it's wider than I'd like it to be.