Mermaid, hand-drawn, or AI-generated: which diagram should you reach for?

If you've ever written a Mermaid diagram, you know the two feelings. The first is delight: four lines of text and you have a sequence diagram, versioned in Git, rendered in your README. The second comes about twenty nodes later, when the auto-layout drops a box exactly where you don't want it and there is nothing you can do about it.

That whiplash is the whole topic. There are three ways to get a diagram today — write it as text, draw it by hand, or have an AI generate it — and they are good at different things. Reaching for the wrong one is why diagrams feel like a chore. Here's how to pick.

1. Text-based (Mermaid): when the structure is the diagram

Mermaid turns text into diagrams. Its superpower is that the diagram is code: it diffs in a pull request, it lives next to the thing it documents, and for certain shapes it's simply the fastest way to get a correct picture.

Reach for it when:

• The diagram is a known type with a standard layout — a sequence diagram, a state machine, an entity-relationship diagram, a Gantt chart. Mermaid has a grammar for these, and the auto-layout is usually right because the shape is conventional.
• It belongs in the repo and should change when the code changes. A sequence diagram of an auth flow that lives in the README and diffs with the handler is worth its weight.
• You want zero visual fuss — no dragging, no alignment, just the facts.

It fights you when:

• You need control over layout. Mermaid decides where nodes go; past medium complexity you're fighting the layout engine, adding invisible nodes and direction hints to coerce it.
• The diagram is freeform — a system architecture with a particular spatial story, a design sketch, anything where where things sit carries meaning.
• You want to annotate and discuss on top of it. Mermaid is render-only; there's no sticky note, no "why is this here?" in the margin.

2. Hand-drawn on a canvas: when layout and annotation matter

A whiteboard canvas — boxes you place, connectors you route, sticky notes you drop — is the opposite trade. You give up diffability and gain total control.

Reach for it when:

• Position is part of the meaning. Cloud architecture, network topology, a seating chart, a service map — anything where the spatial arrangement is information, not decoration.
• You're thinking, not documenting. Early design is messy: you move things, group them, cross them out. A canvas is built for that; a grammar isn't.
• The artifact is for people to work on together — annotate, present, hand off. A board has a URL you share; it isn't trapped in one chat or one file.

It fights you when:

• You want it versioned and diffable — a canvas is a visual artifact, not a text diff (export to SVG or .drawly helps, but it's not a code review).
• The diagram is a standard type Mermaid would nail in four lines — hand-placing a sequence diagram is busywork.

3. AI-generated: when you want a first draft in seconds

The newest option: describe the diagram and let an AI agent draft it. Done well — for example, an agent that builds boards over MCP — this collapses the blank-canvas problem. You say "three-tier web app on AWS," and you get boxes and connectors already placed, ready to refine.

Reach for it when:

• You want to skip the blank page. The agent's first pass gets you 80% of a layout to react to, which is far faster than starting from nothing.
• The diagram is tedious but not subtle — lots of boxes, obvious connections, the kind of thing you'd draw correctly but slowly.

It fights you when:

• Correctness matters more than speed. The agent places what you said; it doesn't know your system is wrong. Every generated diagram needs a human read.
• You need it exactly right the first time — generation is a draft tool, not an authority.

The decision table

The real answer: you shouldn't have to choose per diagram

The trap in every "X vs. Y" comparison is the word "vs." Real documents mix diagram types: the architecture is spatial, the auth flow is a sequence diagram, and half the boxes are the same ones you'd have drawn by hand. Picking one tool for the whole document means the wrong tool for half of it.

The version that actually works is one surface that holds all three. On DrawlyHub, a Mermaid diagram renders as a container on the same board as hand-placed boxes, Markdown notes, and a frame an AI agent drafted over MCP. Text where text wins; boxes where layout wins; generation where you just want a head start — and all of it on one canvas with one URL, organized into frames you can present.

The honest caveats

• Mermaid containers render Mermaid — they don't fix Mermaid's layout. If a diagram is a layout fight in a .md file, it's the same fight on a canvas. The point is that it can sit next to the freeform parts, not that the grammar changes.
• AI generation is a draft, not an architect. Treat every generated frame as a first pass to review, not a source of truth.
• Building boards from an agent is a Pro feature, with a two-week no-card trial if you want to try the whole flow.

Try it

Open the demo board and look at how a Mermaid diagram, a few hand-placed boxes, and a Markdown note share one canvas — no account needed. Then pick the right tool for each part of your next diagram, instead of forcing one tool onto all of it.