How to Make Diagrams with AI: A Guide to Mermaid

Ask any AI assistant to “draw a flowchart of our onboarding” and it will. Not a description of one — an actual diagram, boxes and arrows, in about four seconds.

Most people don’t know this. They’ve been using these tools for years to write and summarize, and never once asked for a picture, because nothing advertised that it could. There’s no button.

What comes back is Mermaid: a text format for diagrams that models write natively. This guide walks the whole job — what you can ask for, how to get a draft worth keeping, what it costs to keep it, and the point where a picture stops being enough.

Try it in sixty seconds

Paste this into whatever assistant you already use:

Draw a Mermaid flowchart of what a new customer does, from first hearing about us to completing a first purchase. Each box is an action the person takes. Six to ten boxes.

You’ll get back a block of text starting with flowchart:

flowchart LR
    A[Hear about us] --> B[Visit site]
    B --> C[Browse products]
    C --> D{Convinced?}
    D -->|Yes| E[Add to cart]
    D -->|No| F[Leave and forget]
    E --> G[Check out]
    G --> H[First purchase]

That’s the diagram. To see it as a picture, paste it into any tool that renders Mermaid — GitHub comments, Notion, Obsidian, ChatGPT and Claude’s own canvases, or mermaid.live in a browser. Most places you already write will draw it without being asked.

You now know the thing most people don’t: you can get a diagram out of a conversation.

And you can read that block without having learned anything. flowchart LR is the kind and the direction — left to right, where TD would be top-down. Square brackets make a box, curly braces a diamond, --> an arrow, |Yes| a label on one. That covers most of what a flowchart uses, and it’s enough to make the edits you’ll actually want: flip the direction, change a shape, relabel an arrow. One trap, before it bites you: a node reading lowercase end breaks the diagram. Capitalize it.

What you can produce

Mermaid supports 21 diagram types. Most guides list them alphabetically, which doesn’t help you choose. Here they are by what you’re trying to show.

Something that happens in an order

How things relate

Time and plans

Numbers and comparisons

There are a few more — requirement diagrams, packet diagrams — that are specialist enough you’ll know if you need them.

Where to start: flowchart, mindmap, sequence, and quadrant will cover most of what a non-engineer wants. Learn to recognize those four and you can ask for the right thing instead of accepting whatever you get.

The loop you’ll actually run

Nobody gets a usable diagram on the first ask. The work is a short loop — ask, read, repair — and each turn has a cost.

Ask so the draft lands close

Three habits do most of the work.

Say whose point of view. Left to itself, a model will diagram the system — services, endpoints, database writes — because that’s what most diagrams in its training data show. If you want the customer’s experience, say so explicitly.

Each node is an action the person takes, in their words. No system components.

Ask for the happy path first. Ask for everything and you get every branch and error state at once. Nobody reads that.

Only the path where everything goes right. No error handling, no edge cases. Six to ten nodes.

Six to ten isn’t arbitrary — it’s what a person can take in at a glance. Add the exceptions on a second pass, once the shape is right.

Name the altitude.

Every node should be the same size of step — something the person would recognize as one thing they did. If two nodes are really parts of one step, combine them.

And one that costs nothing: ask it which type to use. “I want to show how a support ticket moves from open to closed, including who touches it — which Mermaid diagram type fits best, and why?” It’s genuinely good at that, and you’ll learn the catalog faster by asking than by reading a table.

Read it for what it can’t know

The model is good at shape and bad at substance, and the split is predictable enough to check against deliberately.

Trust it on structure. Turning four paragraphs of meeting notes into a mindmap is the strongest thing it does and the one people discover last. It remembers syntax so you don’t have to, it changes its mind for free — “same diagram, but as a sequence diagram” — and it will produce eight diagrams in one house style, which is more than most humans manage.

Don’t trust it on any of this:

• Your business. You’ll get a confident, plausible, generic version of your process. The steps that make yours yours — the manual approval, the spreadsheet somebody maintains, the customer call that gates everything — are exactly what it doesn’t know.
• What’s missing. It completes patterns. It won’t say “you haven’t accounted for refunds,” because nothing in the prompt suggested refunds exist.
• A consistent altitude. One box reads “Check out” and the next reads “Validate the CVV against the issuer.” This is the single most common defect.
• When to stop. Ask for a full process and you’ll get forty nodes, unreadable and impossible to prioritize.

So read the draft as a question rather than an answer. Once a diagram has your corrections in it, it’s worth more than anything the model can produce cold — which makes the next step the hard one.

Fix it when it won’t draw

If something won’t render, it’s almost never you. Mermaid gains diagram types over time and models blend versions, so now and then you’ll get something confidently written that no renderer will draw — usually a newer type, or a feature the place you’re pasting into doesn’t support yet.

This is the one moment in the whole exercise where people conclude they’re doing it wrong and stop, so learn the repair before you need it. Paste the diagram into mermaid.live — it names the line it choked on, which beats staring at the text. Then check that diagram type against the syntax reference. If the feature isn’t there, the model either invented it or borrowed it from a newer release; tell it so and ask for the plainest version of that diagram type. That clears it nearly every time.

Change it without starting over

This is where the loop breaks.

You have a diagram with three corrections in it that the model could never have made. Now you want one box moved and two renamed. Your options are to edit the syntax by hand, or to describe the change and let it regenerate — which returns a clean new diagram that has quietly dropped the other fixes. Most people try the second, lose the work, and go back to doing it by hand.

What you wanted was to touch it. Grab the box, drag it, retype the label, and have the next question you ask still be about the same diagram. Nothing described in this guide lets you do that, which is why nearly everyone converges on the same workaround: screenshot the rendered picture, paste the image back into the chat, and ask about that.

What it costs to keep

Everything above is close to free now, and that’s the real change. The expensive part of diagramming used to be making one.

What isn’t free is owning it. A Mermaid diagram is text, which is its best property: it diffs, it reviews, it sits next to the thing it describes, and nobody needs a license to open it. That’s why it beat drawing tools for documentation in the first place.

But text has no status. Nobody is assigned to it, nothing notifies you when the process it describes changes, and it will never tell you it’s out of date. The failure mode isn’t a wrong diagram — it’s a confident one, six months stale, that somebody builds from.

For an explanation living beside the code, that’s usually survivable: the change that alters the process tends to touch the file too. For anything that changes weekly, it isn’t.

Where a picture stops being enough

That screenshot is the tell, because it’s the whole problem in one gesture. You want to point at something. The model wants to read something. Right now those are two different artifacts, and you’re the one converting between them by hand, several times an hour.

Mermaid sits firmly on the machine side of that split, and that’s its real advantage over a whiteboard. Ask an AI about a board full of shapes and something first has to turn that canvas back into meaning — a re-interpretation, on every prompt, of a picture that was never written down. Ask it about Mermaid and it’s reading exactly what you wrote, with nothing inferred. The price is that you can’t grab a box — the one thing a whiteboard is great at.

Neither side gives you both, and the gap gets wider when the diagram is a plan rather than an explanation.

You can’t slice a picture into releases. You can’t mark which box is essential and which is a nice-to-have. You can’t give half of it to a team and track the other half, or hang the acceptance criteria off a box, or see at a glance what’s already done. To do any of that, people retype every box as a real task and guess at sequence and scope — which takes an afternoon and loses most of what made the diagram worth having.

Generation got cheap. Structuring stayed manual.

This is where a diagram and a map part company. A map keeps the sequence a diagram gives you and adds the things a picture can’t hold: a vertical axis for priority, horizontal slices for what ships first, and detail behind each card. Because a Mermaid diagram declares its own kind in its first word, that conversion doesn’t have to guess — paste it into CardBoard and it restructures into a typed map instead of a flat sketch.

It also closes the split. The cards are there to be dragged, renamed, and rearranged by hand, and the structure underneath stays something a model can read without being handed a screenshot. That’s the whole bet — one plan, drawn for people and typed for machines — and it’s the reason you stop having to choose between an artifact you can touch and an artifact your AI understands.

Which diagrams become maps

Not all of them, and it’s better to know which before you spend an afternoon on the wrong one. CardBoard’s Mermaid import is in beta, and this is what it does today:

The flowchart case has one nice piece of behavior. After parsing, it checks whether any node has more than one arrow pointing at it. If none does, the thing you drew is a hierarchy rather than a process, and you get a sitemap instead of a flow — which is usually what you meant.

The rest — sequenceDiagram, journey, gantt, timeline, block, the C4 family, treemap, xychart, radar, quadrantChart, and pie — are recognized and declined by name. That’s deliberate: a pie chart isn’t a map shape, and turning one into cards would produce something worse than nothing. You get told what happened instead of handed a mangled board.

Two honest caveats. First, the freeform bucket is best-effort. Those diagrams go through the flowchart tokenizer, not a parser built for each grammar, so a class diagram arrives as its boxes and arrows, not as a modeled class hierarchy — a starting point to arrange, not a faithful translation. Second, two of the four types I recommended above, sequence and quadrant, aren’t in the accepted list. They’re still the right diagrams for their jobs. They just aren’t the ones that carry through to a plan today.

One convenience: the importer strips ```mermaid fences, so you can paste what the assistant gave you without cleaning it up first.

From there it’s the story mapping method: fix the sequence, add what the model didn’t know, prioritize down each column, slice. And because the result is typed, an agent can read it and propose into it — see CardBoard for agents, or spec mapping for the same route starting from a chat or a spec instead of a diagram.

Try it on something you own

Run the prompt at the top of this guide against a process you’re actually responsible for. Sixty seconds, and you’ll know whether the model’s version of your process matches yours — which you want to know either way.

Then the fork this guide has been building toward. If what you drew is an explanation, you’re done: keep the text next to the thing it describes and let the diff tell you when it drifts. If it’s work someone has to do, the picture is the first ten minutes of a longer job, and the rest of that job needs somewhere that holds priority, ownership, and detail. The user story mapping tool page shows what that looks like, and you can open a free workspace to paste a diagram in — three boards, no credit card, guests included.

Frequently asked questions

Can AI make diagrams?

Yes. Ask any modern assistant for a flowchart, mindmap, or sequence diagram and it will return one as Mermaid — a text format for diagrams — usually in seconds. You don’t need a drawing tool or a plugin, and most places you already write will render the result.

What is Mermaid?

Mermaid is a text syntax for diagrams. You write a few lines of plain text and a renderer draws the picture, which means diagrams can live in documents and version control instead of in binary drawing files. It’s the format AI models produce because it’s text, and text is what they generate.

What kinds of diagrams can AI create?

Mermaid supports 21 types. The most useful for non-engineers are flowcharts (processes with decisions), mindmaps (opening up a topic), sequence diagrams (handoffs between people or systems), and quadrant charts (prioritization). It also covers timelines, Gantt charts, entity relationship diagrams, Sankey flows, and more.

What is AI bad at when making diagrams?

Substance rather than shape. It doesn’t know your business, so it produces a plausible generic version of your process. It won’t tell you what’s missing, it mixes levels of detail unless you ask it not to, and it will happily return forty nodes when ten would be readable.

Why does my diagram work in the Mermaid live editor but not where I pasted it?

Almost always a version gap. Mermaid adds diagram types and features over time, and the places that render it — documentation tools, wikis, code hosts — update on their own schedules, so a newer feature can draw in one and fail in another. Ask the model for the plainest version of that diagram type and it will usually render everywhere.

Where can I view a Mermaid diagram?

GitHub, Notion, Obsidian, many documentation tools, and the assistants themselves render Mermaid natively. For a quick look, paste it into mermaid.live in a browser.

How do I edit an AI-generated diagram without regenerating it?

By hand, in the text — the honest answer, and the reason people don’t. Asking the model to make the change returns a fresh diagram that usually drops the corrections you’d already made, so the choice is editing syntax or losing work. Direct manipulation, where you drag a box and the change sticks, needs a tool built around the structure, not around the picture.

Is a diagram the same as a plan?

No. A diagram shows sequence and branching. A plan also carries priority, what ships first, who owns each piece, and enough detail behind each item to build it. Turning a diagram into a plan means putting it somewhere that understands structure rather than shapes.

Which Mermaid diagrams can I turn into a map?

Flowcharts become process maps, or sitemaps when the shape is a hierarchy, and mindmaps become mind maps. Class, ER, state, sankey, architecture, gitgraph, packet, and requirement diagrams land on a freeform canvas as nodes and arrows. Sequence diagrams, journeys, Gantt charts, timelines, C4 diagrams, and the chart types are declined by name instead of converted badly.

Written by Josh Colter, who owns and builds CardBoard — the story mapping tool featured in Jeff Patton’s User Story Mapping, now built around a theory of maps: one plan, drawn for people and typed for machines.

Last updated 16 August 2026.