Goodbye to Generic Mermaid Diagrams: diagram-design Gives Claude Code a Design System (and Your Palette)
You ask Claude Code for an architecture diagram and you already know exactly what comes back: a Mermaid block that renders identical rounded boxes, diagonals crossing arrows, a purple palette on dark background nobody chose, and typography that doesn’t match anything else you publish. You get it. It’s also the visual equivalent of a stock photo — and if that diagram goes into your documentation, your README, or a post, you end up opening Figma thirty minutes later or just ditching the diagram altogether.
diagram-design is a Claude Code skill that attacks that exact gap. Instead of teaching the model a diagram syntax, it delivers a design system: what a diagram can contain, how many elements before it stops communicating, what color goes where, and a list of things it should never do. The output isn’t Mermaid: it’s a self-contained HTML file with SVG and inline CSS that you open straight in the browser.
Cathryn Lavery published it days ago (founder of BestSelf.co, writes at littlemight.com), it has an MIT license, and it hit #13 on Trendshift’s daily trending on August 9, 2026. Today (verified live on August 12, 2026) it’s at nearly 10,000 stars — for a repo this new, that’s a signal of strong traction, not a rounding number.
What It Actually Produces
The output unit is an .html file. No build step, no JavaScript, no external images: the SVG goes inline, the CSS goes inline, and the only external dependency is Google Fonts for three typefaces. You open it in the browser, screenshot it, or drop it into a docs site.
Each type comes in three variants: minimal light, minimal dark, and full-editorial (the latter adds summary cards around the diagram). The repo includes a gallery with tabs in skills/diagram-design/assets/index.html where you can browse all of them before installing anything — it’s worth opening first, because it’s the fastest way to decide if the aesthetic is yours.
How Many Types, Exactly
Here the project’s own documentation contradicts itself, and it’s worth knowing before you install:
- The README gallery shows 14 types with screenshots (architecture, flowchart, sequence, state machine, ER, timeline, swimlane, quadrant, nested, tree, org chart, Venn, layer stack, pyramid/funnel, plus a special “consultant 2×2”).
- The
SKILL.mdthat actually gets installed — the file Claude reads — lists a selection guide for 27 types. - The GitHub repository description says 29.
The three numbers aren’t so much a contradiction as a snapshot of a project shipping code faster than it documents. The types that exist in SKILL.md but aren’t in the README gallery are the analytical and data platform ones: radar/spider, loop/flywheel, bar chart, line chart, Gantt, scatter plot, IT current-state, high-level data stack, process, medallion (multi-layer storage with quality levels), data flow by role, data platform integration topology, and a security matrix by role. If you judged the skill by its README you’d conclude it doesn’t do charts or roadmaps. It does.
Practical consequence: read skills/diagram-design/SKILL.md, not the README, to know what you can ask for.
Installation
Two paths, and the choice matters more than it seems.
Path 1 — clone and symlink (recommended if you plan to customize):
git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design
Note that the symlink points to the internal directory. The repo root is a wrapper so the same tree works as a Claude Code plugin, Codex plugin, and standalone skill; the skill itself lives in skills/diagram-design/. Restart Claude Code and it registers as diagram-design.
Path 2 — as a plugin (faster, but the skill lands in the plugin cache, so hand edits to references/style-guide.md don’t survive a plugin update):
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design
In Claude Cowork: Customize → Directory → Plugins → + → paste cathrynlavery/diagram-design → Sync, then install it from the Personal list.
In Codex:
npx skills add https://github.com/cathrynlavery/diagram-design --skill diagram-design
If you’re going to touch the style guide by hand — and the next section argues you should — take path 1.
Your First Diagram
No command to memorize. The skill activates by intent:
“Make me an architecture diagram of my app: frontend, backend, PostgreSQL, and a Redis cache.”
“I need a quadrant of Q2 projects by impact vs. effort.”
“Give me a sequence diagram of the OAuth handshake.”
Claude picks the type, loads only the reference file for that type, builds the HTML, and saves it. You can also start from a scaffold and edit it by hand:
cp assets/template.html my-diagram.html # minimal light
cp assets/template-full.html my-diagram.html # editorial, with summary cards
The Part That Makes It Look Like Your Project
This is the feature that justifies the install. Out of the box diagrams render with the skill’s neutral palette. Sixty seconds of onboarding swaps it for yours:
“onboard diagram-design to https://yoursite.com”
Claude fetches your homepage, extracts the dominant palette and font stack, and maps what it found to semantic roles instead of raw hex values:
| Detected on Your Site | Becomes |
|---|---|
<body> background |
paper |
| Primary text color | ink |
| Secondary text / caption | muted |
| Cards or containers | paper-2 |
| Most-used brand color (CTA, link, heading) | accent |
<h1> typeface family |
|
Typeface for <body> |
font node-name |
Font for <code> / <pre> |
font sublabel |
It shows you the proposed diff before you write anything, and verifies WCAG AA contrast of ink against paper before confirming. That check isn’t decorative: diagram labels render at 9–12px, and a color that passes as body text on your site can fail at that size. If it fails, the skill proposes an adjusted value and explains why.
Everything that comes after — the 27 types, the annotation primitive, the gallery — reads from references/style-guide.md and refers to roles (accent), never to hex. You change one line there and all your diagrams follow suit.
There’s also a first-run gate so you don’t accidentally ship diagrams with the default palette to a branded project: on the first diagram of a new project, if the style guide is still untouched, the skill stops and offers you options (pull it from a URL, extract it from an installed skill, extract it from a local design system folder, paste tokens by hand, or proceed with the default).
A detail found while checking this note: the gate decides if it’s been personalized by comparing accent against the literal value #b5523a (the default “neutral stone + rust” described in SKILL.md), whereas the README describes the installed default as “jet-black + atomic-tangerine” with a different accent. If your project’s brand accent matches either of those values, or if you edit the palette without touching accent, the gate can read as already-personalized when it isn’t. It’s trivial to work around — run onboarding explicitly — but worth knowing it’s a value comparison, not a real check for “was this edited?”.
The design system, condensed
The rules are the product. Even if you never install the skill, this is a usable checklist:
- One accent color only, across a maximum of two focal elements per diagram. The accent tells the reader where to look first; on every node it tells them nothing.
- Three typefaces, each with its job: a serif for titles and italicized callouts, a sans for node names, and mono strictly for technical content (ports, URLs, field types) — not as generic “dev” aesthetics.
- 1px hairline borders, zero shadows, border radius capped at 10px.
- Every coordinate, width and gap divisible by 4. The style guide is explicit that that’s what keeps diagrams from reading like AI-generated.
- Target density 4/10: technically complete, no legend needed to understand it. The stated philosophy is that the diagram isn’t ready when you’ve added everything, but when you can’t remove anything anymore.
And it applies hard complexity budgets, which is exactly the rule most homegrown prompts are missing:
| Constraint | Limit |
|---|---|
| Nodes per diagram | 9 |
| Arrows / transitions | 12 |
| Elements with accent | 2 |
| Sequence lifelines | 5 |
| Swimlane lanes | 5 |
| Quadrant items | 12 |
| ER entities | 8 |
| Tree depth | 4 |
| Org chart nodes / depth | 12 / 4 |
| Layer stack layers | 6 |
| Venn circles | 3 |
| Gantt tasks | 12 |
| Scatter points | 30 |
| Annotation callouts | 2 |
The anti-patterns list is worth stealing on its own
SKILL.md comes with an explicit list of things you should never do. Read it as a diagnosis of why AI-generated diagrams look the way they do:
- dark mode with cyan/violet glow
- a monospace used as transversal “dev” aesthetics
- identical boxes for all nodes
- a legend floating inside the diagram area
- arrow labels without a mask rectangle
- vertical text with
writing-modeon arrows - three summary cards of the same width as default layout
- shadow on any element
rounded-2xlon boxes- accent on all “important” nodes
- diagonal connectors between off-axis nodes
- an arrow label touching its own connector
- two overlapping connectors or sharing a path
- two connectors sharing the same anchor point on a box
- a connector routed behind a box that isn’t its endpoint
Connectors have additional mandatory rules of their own: right-angle rounded paths, 6–10px margin around labels, and each arrow independently traceable.
Two primitives
- Annotation callout — a note in serif italics with a dotted Bézier guide line, for editorial marginalia. Capped at two per diagram.
- Sketchy filter — an SVG filter of turbulence + displacement map that gives a hand-drawn look. The skill explicitly recommends it for essays and advises against it for technical documentation.
When not to use it
The skill documents its own limits, which is rarer than it should be:
- Quick diagrams in unicode for a tweet or terminal output → use a lighter tool.
- A list of anything → use a table or bullets.
- Before/after comparisons → use a table.
- A single box with a label → just write the sentence.
Its own framing before drawing anything: would the reader learn more from this than from a well-written paragraph? If not, don’t draw it.
Where this leaves you
The value here isn’t the 27 types: it’s that someone wrote down the constraints. Most of us prompt “make me a nice architecture diagram” and end up rehashing spacing, color, and density every time. This skill turns that into a file: budgets that cap complexity, a list of anti-patterns that names the failure modes, and a token layer that makes “your brand” an edit instead of a search-and-replace across every diagram you’ve ever generated.
Install it via clone + symlink if you’re going to touch the style guide, read SKILL.md instead of the README to know the real type catalog, and run onboarding before your first diagram in any branded project.
And you — do you draw diagrams for your documentation, or skip them because making them presentable costs more than writing the paragraph?