I Spent an Afternoon Replacing Mermaid Prompts with Hand-Built SVG Diagrams

A repository gaining 27,488 stars in a month deserves a skeptical test, so I dropped cathrynlavery/diagram-design into my usual Cursor and VS Code workflow. The pitch is unusually specific: 38 editorial diagram types for Claude Code, Codex, and Pi, delivered as self-contained HTML and SVG. No shadows, no Mermaid defaults, and no “boxes connected by whatever the renderer decided” look.

The first friction point is that this is not a conventional diagramming library. There is no runtime, component API, or visual editor to learn. The useful interface is the prompt and the generated artifact. That makes it a good fit for agent-assisted documentation, but less useful if I need interactive diagrams inside an application.

Where it beats Mermaid

Mermaid remains faster for a sequence diagram or a quick architecture sketch:

graph TD
  Browser --> API
  API --> Database

But diagram-design gives the agent stronger visual constraints. The output is a standalone HTML file containing inline SVG, which means I can open it directly, commit it, preview it in VS Code, or paste the markup into documentation without adding a rendering pipeline.

A minimal local check looked like this:

git clone https://github.com/cathrynlavery/diagram-design.git
cd diagram-design
find . -maxdepth 2 -type f | sort | head -40

I then asked my coding agent:

Read this repository's diagram guidance. Create a self-contained SVG
for a request lifecycle. Use an editorial composition, explicit labels,
no shadows, and no Mermaid. Save it as request-lifecycle.html.

The result was more art-directed than my normal generated diagrams, especially around hierarchy, spacing, and annotation. The trade-off is consistency: different agents may interpret the same diagram type differently, and editing generated SVG by hand is still tedious.

My decision rule

Use this when you want polished, embeddable diagrams generated from prompts, especially for READMEs, design notes, and architecture reviews.

Skip it if your team already has a Mermaid convention, needs diagrams generated from structured data, or expects live updates from source code. For my daily VS Code workflow, it complements Mermaid rather than replacing it: Mermaid for disposable structure, this repository for diagrams people will actually read.