TL;DR — AI diagram generation fails not because models are weak, but because there's no production discipline. Fact graph first, a frozen label whitelist, literal label audits, branch degradation, and provenance files. Packaged as a Claude Code skill, this passed audit on the first candidate in two consecutive projects. Fully open source.
Why "looks right" is not a bar for technical diagrams
Prompt an image model for "a RAG architecture diagram" and you get something pretty, convincing, and wrong:
- arrows reversed (data flow drawn as control flow)
- typos and duplicated labels
- nodes that don't exist in your system, invented anyway
- worst of all: globally plausible, locally false
For a mood image, close enough is fine. A technical diagram is a promise — readers treat it as the truth of the system. One reversed arrow is worse than no diagram.
So the acceptance bar is not aesthetics. It's verbatim correctness. And verbatim correctness can't be eyeballed, and definitely can't be gambled on.
The method: four steps of pure discipline
I distilled the pipeline into a Claude Code skill, anycap-architecture-diagrams:
1. Fact graph first, sanitized first. Before any prompt, structure what the figure must say: nodes, edges, exact edge labels. Teaching figures use synthetic systems — never feed a real architecture to a model. A diagram is a condensed system map; it leaks what scanners can't see.
2. Freeze the contract. Node list, edge list, and a verbatim label whitelist — frozen before generation. Nothing outside the whitelist may appear in pixels.
3. Three branches, chosen by difficulty.
- T1 full-generation: the model owns all pixels — viable up to ~6 nodes / 6 edges
- Hybrid: the model paints a no-text plate; labels and connectors are overlaid deterministically
- Deterministic retreat: hand-authored SVG/Mermaid; the model touches zero semantics
4. Literal audit via image-read, not vibes. After generation, a vision model checks the whitelist word by word: every label present, every arrow direction correct, zero extra text. Any miss is a FAIL.
The rule: one failure → regenerate naming the defect; two failures → switch branches. Never keep pulling the slot machine on the same branch.
Measured results — and the ceiling
Two real projects produced hard data:
A RAG reference architecture (synthetic, 6 nodes / 6 edges): T1 passed the full audit on the first candidate — every label verbatim, every arrow correct. Full provenance.
A diagram grammar gallery: one synthetic system (a PR review bot), five grammars chosen by viewer question — context, sequence, state machine, data flow, control loop. All five passed first-candidate audits. Gallery.
The ceiling is real too: past ~6×6, T1 enters a fix-one-break-another carousel. Repair label A and label B drifts. An 8-node/8-edge figure never converged in our tests. So the skill hard-codes it: complex figures go hybrid or deterministic immediately.
Style breakout: from "themed Mermaid" to editorial
Correct is the floor. The first version of every figure passed label audit and was still rejected:
"No different from Mermaid, and the colors are ugly."
Dark dashboard backgrounds, rainbow card walls — the default AI aesthetic. The fix was an editorial language: warm-white canvas (#FAFAF7), navy (#1E3A5F) structure, one or two restrained accents, a bold title top-left, a one-line takeaway caption at the bottom.
Notably, the style upgrade shipped via the deterministic branch — hand-authored SVG, zero model involvement. Which is exactly why branches exist: when T1 can't get you there, you don't give up; you deliver deterministically.
One more lesson: models improvise logos. One context figure came back with an invented GitHub octocat and an OpenAI-ish swirl. The prompt now states flatly: text only inside cards, no brand logos, no icons.
Provenance: evidence as an asset
Every figure ships with a .prompt.md sidecar: frozen prompt, model + request ID, the literal audit instruction, audit result, rejected directions. Anyone can reproduce, review, or challenge.
The figure stops being "a PNG" and becomes an auditable production record. Revisiting it two months later doesn't require archaeology; defending it doesn't require memory.
Try it
ln -s "$PWD/skills/anycap-architecture-diagrams" ~/.claude/skills/
- Method skills: convergeai-labs/anycap-skills — 7 skills: brand marks, architecture diagrams, media, research, human-in-the-loop, access, content
- Evidence: convergeai-labs/anycap-examples — 5 entries, all with full provenance
FAQ
Why not just use Mermaid?
Do. Mermaid/deterministic SVG is a first-class branch, not a consolation prize. The generation branch owns the explanatory layer's expressiveness; exact topology always belongs to the deterministic layer.
Why freeze labels?
Because models will improvise them, every time. Improvisation in a technical figure isn't creativity — it's a defect. The whitelist confines creativity to composition and style, and locks semantics.
What about CJK labels?
Short labels can be generated but must pass the verbatim image-read audit; past ~18 labels, go no-text plate + deterministic overlay. Don't burn generations on it.
Is this diagram-specific?
The gates + audit + provenance skeleton is generic. The brand-mark skill (32px decision boards, i2i color-preserving recolors) and a music bake-off (decided on contract adherence, not vibes) in the same org run on the same discipline.
All work produced with Claude Code + AnyCap. Skills MIT, examples CC-BY.
Top comments (1)
The deterministic retreat is the part many generation pipelines omit. Two failed repairs should change the method, not just the prompt. I would also treat the rendered image as the final artifact: run OCR plus pixel inspection after export, because a correct SVG source can still clip a label or hide an arrow at the target size.