Diagrams Inside the Document

There is a category of thing that prose handles badly. Dependencies between systems. State transitions. How a user moves through a flow. A sequence of events across services. You can write these out — many specs do — but the written version requires the reader to build a mental picture from scratch. A diagram hands them the picture already built.

The gap this creates is structural. The diagram lives in one place — a Figma file, a Miro board, a separate draw.io export — and the spec lives somewhere else. They reference each other loosely if at all. When the system changes, someone updates the spec but forgets the diagram, or updates the diagram but doesn’t touch the spec. Within a few weeks, they’re describing subtly different things.

Mermaid support in Stokik documents closes that gap by putting the diagram inside the document, as text you write and own.

What Mermaid is

Mermaid is a diagramming language: plain text that describes structure and renders as a visual diagram. A flowchart is a few lines. A sequence diagram is a few more. The source is readable on its own — it doesn’t require a special application to open, doesn’t lose fidelity if you copy it, and doesn’t need to be exported or screenshotted to share.

You can read more about the Mermaid syntax at mermaid.js.org.

That last point matters more than it sounds. An exported image of a diagram is a snapshot. The Mermaid source is the diagram. If the system changes, you edit the text and the visual updates automatically. There’s nothing to re-export, no version mismatch between the words and the picture.

How it works in practice

Inside any Stokik document, the toolbar now includes a diagram block. Insert one and you get a Mermaid source editor directly above the rendered output. The two update in sync: edit the source, and the diagram refreshes after a short pause.

The default is a simple flowchart, but Mermaid supports most diagram types you’d reach for in a spec: flowcharts, sequence diagrams, state diagrams, entity-relationship diagrams, and more. You write the type and structure directly in the editor, no configuration required.

In view mode, the source editor collapses and only the rendered diagram is visible. Readers see the diagram cleanly. Authors see the source when they need to change it.

If the source has a syntax error, the editor surfaces the problem immediately. The previous valid render stays in place until the source is corrected, so a mid-edit draft doesn’t break the document for anyone else viewing it.

Why it belongs in the spec

The version of this feature that doesn’t require Mermaid is: write the spec, link to the Figma file, maintain two documents, accept that they’ll drift.

That’s not a hypothetical. It’s what most teams do, and the drift is predictable. The spec gets updated because a spec review happens in the document. The diagram doesn’t get updated because there’s no natural prompt to open the Figma file — it lives in a different context, accessed by a different link, requiring a different tool. Friction compounds over time.

When the diagram is inside the document, the prompt is always there. You open the spec to update an acceptance criterion, and the flow diagram is right below it. If the flow has changed, the source is two clicks away. The diagram and the prose are in the same review, the same edit session, the same version history.

That version history is worth naming. Because Mermaid diagrams are stored as source text, every change to a diagram is tracked in the document’s revision history alongside changes to prose. You can see who changed the flow, when, and what it looked like before. An exported image can’t tell you any of that.

Specs that don’t lie

The most reliable spec isn’t the most detailed one. It’s the one that’s maintained — where the diagram matches the prose, and the prose matches what actually shipped.

The friction that prevents maintenance is usually physical: the pieces of a spec are scattered across tools, and updating any one of them requires visiting a different place. Mermaid diagrams in documents don’t eliminate that work, but they reduce the surface it has to cover. The diagram is here, in the same place as the words. It updates when you update. It’s readable in the same review session, versioned in the same history, accessible to the same people who have access to the document.

A spec that holds together over time isn’t a function of discipline. It’s a function of making the work of keeping it current as close to free as possible.