What Is Mermaid Slop? The Generic AI Diagram Problem, Explained

Ask a coding agent for a diagram and you already know what you're getting back before it finishes generating: a handful of rounded rectangles, a default color palette, arrows an auto-layout algorithm decided looked tidiest, and zero relationship to whatever document it's about to sit in. That specific, extremely recognizable output has a name now — Mermaid slop — and the fact that it needed one says something about how reflexively AI agents reach for Mermaid the moment a diagram gets requested.

TL;DR

The term, and where it actually comes from

"Mermaid slop" isn't marketing copy or a meme with an untraceable origin — it shows up in a specific, citable place: the GitHub description of Diagram Design, a free Claude Code, Codex, and Pi skill built by Cathryn Lavery, founder of BestSelf.co. explainx.ai covered the skill in detail on August 13, 2026, and the project positions itself explicitly against the term in its own pitch: "no Figma, no generic rounded boxes, no Mermaid-slop."

Lavery's own account of why she built it is the clearest definition available: every time she needed a diagram for her blog — an architecture sketch, a flowchart, a "what matters most" pyramid — she'd ask Claude and get back the same generic rounded-box thing that looked nothing like the rest of her site. The alternative was a 30-minute manual Figma session just to make it match. That gap — between "technically renders correctly" and "actually belongs in this document" — is the entire complaint packed into two words. You'll also see it called diagram slop, AI diagram slop, or flowchart slop in the wild — same complaint, less specific about which tool produced it, since the underlying pattern (reflexive, judgment-free generation) isn't unique to Mermaid.

What makes a diagram "slop" specifically

AI slop, broadly, is defined as generative content that's low-effort, low-meaning, and produced in high volume — a term that spread through text and images first. Mermaid slop is that same failure mode applied to diagrams, but it manifests in a particular, recognizable way:

• Same shape regardless of content. A request to compare two architectures and a request to explain a single data flow both come back as boxes-and-arrows flowcharts, because Mermaid's layout engine picks a generic arrangement without knowing what the diagram is actually trying to argue.
• No relationship to the surrounding document. Default theme colors, default fonts, no connection to your site's brand or your document's visual system — because Mermaid's renderer has no way to know either exists.
• Unlabeled or vaguely labeled arrows. "Connects to," "relates to," or nothing at all — an arrow that says "related somehow" instead of what actually happens (writes, invalidates, polls every 30s).
• Reflexive generation. The diagram gets produced because a diagram was requested, not because the argument genuinely needed one — the "when a sentence says it faster, write the sentence" test that a slop-producing default has no mechanism to apply.

It's worth being precise about what's not the target here. A related, earlier strand of "AI diagram slop" criticism — laid out in a widely shared piece on AI-generated raster diagrams — is actually an argument for Mermaid, not against it: image-generated diagrams add decorative flourishes (the author's example: asking for a neural network diagram and getting back "a steampunk contraption with brass gears, Victorian-era valves, tiny people operating levers, and copper pipes"), produce meaningless binary diffs in git, and can't be edited without full regeneration. Mermaid solves all four of those problems by being text. Mermaid slop is the next-order problem: once everyone's diagram-generation defaults to Mermaid, the failure mode shifts from "decorative and unreadable" to "correct syntax, zero judgment about what to draw."

Why agents converge on this by default

There's a structural reason coding agents reach for Mermaid specifically, and it's not laziness on the model's part. Mermaid's syntax is small, it's heavily represented in training data — READMEs, GitHub issues, documentation sites — and it renders correctly on the first try more often than hand-authored SVG. Ask a model to "diagram this," and Mermaid is close to the path of least resistance for getting something that compiles.

The problem is what happens next: Mermaid's own layout engine auto-arranges nodes with zero awareness of your document's design system, your brand, or — critically — what the diagram is actually supposed to help a reader understand. Every agent, on every request, converges on the same visual output because the tool has no lever for "match this to the argument" or "match this to the site it's going into." Community discussion of agent-generated Mermaid has separately noted that agents are good at writing Mermaid diagrams but not especially good at reading them back — the generation side is fluent; the judgment side isn't built in.

What the fix actually looks like

There are two separate answers here, and they're not the same thing.

The tool-level fix is what Diagram Design ships: 27 named, purpose-built diagram types instead of one generic flowchart shape, a 60-second onboarding flow that reads your actual website and extracts your colors and fonts, a non-negotiable 4px coordinate grid the project says explicitly is "what keeps the diagrams from feeling AI-generated," and — notably — the ability to import and redraw an existing Mermaid or draw.io diagram into that same editorial system rather than requiring a restart. It's free, MIT-licensed, and sits at over 11,000 GitHub stars, which is itself a signal for how many people were tired of the same rounded boxes.

The judgment-level fix is a discipline, not a tool, and it applies whether you're using Mermaid, Diagram Design, or hand-drawn SVG:

1. Depict the mechanism, not its name. A box labeled "cache" says less than a sentence would. The path a request takes through it, the two stores it sits between, the arrow that disappears if the cache is removed — that's what a diagram can say that prose can't.
2. If you're comparing options, draw the difference — not two disconnected boxes with nothing linking them, which is a restated list, not a comparison.
3. Match complexity to the stakes. A one-hop question is a three-box diagram. A migration that reroutes writes through a queue needs the queue, the writer, the reader, and the ordering arrow — no more, no less.
4. Label every arrow with what it does, not that it exists.
5. Skip it when a sentence says it faster. Diagram Design's own documentation lists exactly this as a "when not to use this skill" case — quick sketches, plain lists, before/after comparisons, or any single labeled box a sentence would explain better. A tool that documents when not to produce its output is a rarer and more useful signal than one that always says yes.

That five-point discipline is the actual antidote to Mermaid slop — not a different rendering engine, but the judgment about what a diagram is for that the reflexive "agent sees 'diagram,' outputs Mermaid" pattern skips entirely.

Related reading

• What Is "Seamslop"? Matt Pocock's Term for AI Writing That's Technically Right But Feels Off — the same slop-naming pattern, applied to AI prose instead of diagrams
• Diagram Design: The Claude Code Skill That Ends Generic AI Diagrams
• What Is AI Slop? A Practical Definition
• What Are Agent Skills? A Complete Guide
• DESIGN.md Templates: The Professional UI Blueprint for AI Agents
• MCP Security Guide (2026)
• Mermaid Slop dictionary entry
• AI Slop dictionary entry

Official source: Diagram Design on GitHub · Diagram Design on explainx.ai's skill directory

Term origin and project details reflect public repository content as of this post's publication date.