From Claude to Mermaid: turning AI-generated diagrams into living diagrams
• 4 mins
For most of their history, diagrams have had one job: help a human understand something.
The first era was individual. One person, one screen, one document — a way to externalize thinking, make complexity visible, get clarity before moving on. Mermaid was built in this era, for a specific reason: stay in context, stay in text, don’t break the flow to open a diagramming tool. Content over aesthetics. The initial scope turned out to be a superpower.
The second era was collaborative. Real-time, multiplayer, graphical-first. Tools that let teams build shared understanding across distance. The diagram became a medium for human-to-human communication — something you made together, something you handed off, something you presented.
Both eras assumed the same thing: the reader is a person. But that assumption is quietly unraveling.
The new reader
AI doesn’t just generate diagrams now. It reads them. It executes against them. It uses them as specifications: inputs to a process, not outputs of one.
Claude’s native diagram support is one signal of this shift. But the more significant thing isn’t that Claude can produce a diagram on request. It’s that the diagram Claude produces enters a world where machines are participants in the workflow, not just observers of it.
A diagram made only for human eyes is now, in a meaningful sense, incomplete. Not because it’s missing information — but because it’s missing structure. Structure that a machine can parse, act on, and maintain over time.
This is a different requirement than “does it look right.” It’s: is it right in a way that’s legible beyond the moment it was made?
What that demands from the format
Not every diagram format can meet that requirement. GUIs built for visual output — drag, drop, export, done — weren’t designed with machine readability as a constraint. The output is a picture. Pictures are hard to version, hard to parse, and hard to keep in sync with the systems they describe.
Text-based diagrams are different. They’re versionable the same way code is. They’re portable: they render natively in GitHub, Notion, VS Code, and dozens of other tools without an export step. They’re editable by anyone who can read the syntax, which increasingly includes AI. And they’re executable: a text-based diagram isn’t just a picture of a system, it’s a description of one that machines can parse and act on.
When Claude generates a Mermaid diagram, it’s not producing an image. It’s producing a specification. That distinction matters more than it sounds.
The diagram problem
Generation is now instant. That’s genuinely useful. But it also surfaces a problem that didn’t feel urgent when diagrams took an hour to make: what happens to them after?
A diagram in a chat window is frozen. You can’t update it when the system changes. You can’t share it with a link, version it, or hand it to someone else to build on. It was useful in the moment it was generated. It doesn’t compound.
The same logic applies beyond the individual. Every diagram a team creates is a piece of organizational memory — a record of how a system worked, how a process was designed, what a decision looked like at the time it was made. When those diagrams live in chat windows and screenshot folders, that memory doesn’t accumulate. It evaporates.
The generation problem is solved. The diagram problem isn’t.
Where diagrams go next
Mermaid was built as a format. What it’s becoming is a home — the place where a diagram stops being a generated artifact and starts being a maintained one.
Whether a diagram starts in Claude, Cursor, GitHub, or a conversation with an AI, it needs somewhere to live after the generation moment. Somewhere it can be edited visually or in code, refined with AI, shared with a link, kept in sync as the underlying system evolves, and accumulated into something larger than any single diagram.
Claude’s announcement on native diagram generation isn’t the story. It’s the starting point – more diagrams will be created in the next two years than in the previous twenty. Most of them will be generated by AI. The more interesting question is what the diagram becomes after.
The tools that answer that question are the ones that matter in this era.