Post / Aug 22, 2026
Interactive diagrams should earn their place
A practical pattern for adding explorable system diagrams to technical writing without turning every article into a JavaScript application.
Most architecture diagrams are read, not operated. A reader follows a line, finds a boundary, and returns to the argument. A static image is often the right tool for that job.
Interactivity becomes useful when the reader needs to inspect relationships rather than merely see them. A dense service map benefits from pan and zoom. A node that can be moved out of a cluster can reveal the edge hidden behind it. A large flow can stay legible on a small screen because the reader controls the viewport.
The important design decision is not how to make every diagram interactive. It is how to keep interactivity optional.
Keep the document static
This site is generated by Astro. Every post begins as MDX, passes through a validated content collection, and becomes static HTML. A normal article sends no React runtime to the browser.
That default matters. Long-form reading should not pay the startup cost of an interface framework simply because one article, somewhere in the collection, contains a node graph.
Astro’s island model gives the diagram a narrow boundary:
<figure class="flow-figure">
<FlowCanvas client:visible diagram={diagram} />
<noscript>{diagram.summary}</noscript>
</figure>client:visible delays hydration until the diagram approaches the viewport. The prose, metadata, navigation, and code examples remain ordinary HTML. React and React Flow enter only where they provide a capability that HTML cannot.
Author the meaning as data
The diagram below is not drawn in a visual editor and exported as an opaque file. Its nodes and edges are a typed TypeScript object. That keeps labels reviewable, relationships diffable, and the component reusable.
From an idea to a published page
Drag nodes to explore. Drag the canvas to pan. Use the controls to zoom.
The node data describes meaning: an eyebrow, a label, a short detail, and an optional visual tone. The renderer owns borders, handles, spacing, and theme behavior. This division lets the visual system evolve without rewriting every diagram.
It also makes the content easier to test. The build can reject a diagram that points an edge at a missing node. A code review can see when a connection changes. A future renderer could produce a static SVG or a printable version from the same data.
Give readers freedom, not authorship
The published diagram permits four actions:
- Pan the canvas.
- Zoom the viewport.
- Select a node.
- Drag a node to inspect the graph.
It deliberately prevents connection creation and edge reconnection. Readers can rearrange the view for understanding, but they cannot accidentally imply a new system relationship. The positions reset on reload because the interaction is exploratory, not an editing workflow.
Those rules are explicit in the component rather than left to library defaults:
export const FLOW_INTERACTION = {
nodesDraggable: true,
nodesConnectable: false,
edgesReconnectable: false,
connectOnClick: false,
} as const;This is a small example of a broader interface principle: make the allowed behavior legible in code. A maintainer should not have to reconstruct the product decision from four distant component props.
Preserve a reading path
An interactive canvas can fail in more ways than an image. JavaScript may be blocked. A screen may be too narrow for comfortable manipulation. A reader may use assistive technology that is better served by structured prose.
The component therefore carries a title, a caption, and a plain-language summary. The surrounding article explains the conclusion that the diagram supports. The canvas is an additional route through the material, not the only route.
The same restraint applies visually. Diagram colors come from the publication theme. Controls use the same borders and type as the rest of the page. Motion follows the reader’s reduced-motion preference. On small screens, the minimap disappears before the labels become cramped.
A useful test
Before adding an interactive diagram, ask one question:
What can the reader understand by manipulating this view that would be difficult to understand from a static figure?
If the answer is only “it looks more technical,” use an image. If the answer involves scale, overlap, alternate focus, or spatial inspection, a small interactive island may earn its place.
The result is not a site made of React Flow. It is a publication that can call on React Flow when the argument needs it, while everything else stays as durable as a static page.