Why your LLM keeps drawing bad diagrams.

If you have ever asked ChatGPT for a system diagram and got back a jumble of overlapping boxes wedged into the top-left corner of a mostly empty page, this post is for you. That is not your prompt failing. It is the diagram format failing at the boundary between an LLM and a page.

1. The problem is not the model. It is the target format.

Most LLM-generated diagrams today come out as Mermaid code. Mermaid was built for humans writing small charts in Markdown, not for a language model rendering a fifty-node architecture. As one commenter put it on a Hacker News thread about ChatGPT's diagram output, ChatGPT is "hilariously bad at drawing diagrams — universally producing something the size of a postage stamp on the corner of an A4 page." (Hacker News, 2025) That description keeps showing up because it is what the tooling produces. The model writes correct-ish syntax. The renderer honours the syntax. The output is unreadable.

2. Mermaid was not built for LLM-native rendering.

Look at the open bug reports on the Mermaid repository this year and a pattern emerges. Mindmap rendering breaks past eleven level-two nodes. Sequence-diagram titles cannot be resized. Architecture-diagram layouts regressed in version 11.5.0. Class-diagram method signatures with more than two generic parameters throw an error. (Mermaid weekly report, April 2025) Each individual bug is fixable. Together they tell you one thing — the syntax was designed for a diagram of a size a human would draw. Nothing about it assumes an autoregressive model that will happily emit sixty nodes and forty edges when you ask it to sketch your microservice topology.

3. The tiny-diagram-on-huge-page complaint.

The page-fill problem is not an aesthetic gripe. It is a legibility failure. A diagram that fills seven per cent of the canvas cannot be read on a phone, cannot be pasted into a slide, cannot be printed at A4 without a magnifying glass. When we surveyed the LLM-diagram threads on Hacker News and developer forums, the same three complaints came up every time:

• The diagram renders in the top-left and leaves eighty per cent of the page empty.
• Boxes overlap or connectors cross where they should not.
• Labels are cut off, especially on long service names.

4. Consultants pay for this in hours.

The people who feel this most are the ones who cannot ship a bad diagram — consultants, technical architects, and engineers building slide decks for stakeholders. As one workflow write-up put it, "consultant days can quickly disappear when stuck redrawing diagrams — what seems like a five-minute tweak often snowballs into hours of alignment fixes, shape adjustments and visual clean-ups." (Dev.to, 2025) The alternative — dropping into Lucidchart or draw.io — has its own tax. Both tools stutter on large diagrams and lag under concurrent edits, per verified 2025 reviews. (Software Advice, 2025) You end up dragging boxes around manually just to fit a canvas that should have filled itself.

The best diagram tool is the one where the first render is the one you ship.

5. What Aquaman changes.

Aquaman is CALEL's LLM-native diagram engine. Instead of asking a model to write Mermaid, it asks the model to describe the diagram, then hands the description to a layout pass that treats the canvas as a first-class constraint. Page-fill is measured. Overlaps are resolved. Labels stretch or wrap to the space available. The first render is the one you drop into your document.

It is dull engineering. Dull engineering is what separates a demo from a tool you use every Monday.

The trade.

You give up the "just paste Mermaid" workflow. In exchange, the diagram you get back is the diagram you meant to draw. If you spend any part of your week formatting boxes for a slide, that trade is worth making.

Sources.

1. Hacker News — ChatGPT is also still hilariously bad at drawing diagrams (2025).
2. Buttondown — Weekly GitHub Report for Mermaid, April 2025 (2025).
3. Buttondown — Weekly GitHub Report for Mermaid, September 2025 (2025).
4. Dev.to — Strategies to Avoid Redrawing Diagrams in Technical Work (2025).
5. Software Advice — draw.io vs Lucidchart (2025).