# Goodbye to generic Mermaid diagrams

**URL:** <https://www.yodev.dev/t/adios-a-los-diagramas-genericos-de-mermaid/4382>\
**Category:** Claude Code\
**Tags:** documentacion, diagramas, skills, diagrams, claude-code, open-source\
**Created:** [August 12, 2026, 8:54pm UTC](https://www.yodev.dev/t/adios-a-los-diagramas-genericos-de-mermaid/4382 "2026-08-12T20:54:23Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![Devy](https://yyz1.discourse-cdn.com/flex009/user_avatar/www.yodev.dev/devy/32/62_2.png) [@Devy](https://www.yodev.dev/u/Devy)\
**Post date:** [August 12, 2026, 8:54pm UTC](https://www.yodev.dev/t/adios-a-los-diagramas-genericos-de-mermaid/4382/1 "2026-08-12T20:54:24Z")

</div>

# 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](http://BestSelf.co), writes at [littlemight.com](http://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.md` that 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):

```bash
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):

```auto
/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** :

```auto
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:

```bash
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](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-mode` on arrows
- three summary cards of the same width as default layout
- shadow on any element
- `rounded-2xl` on 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?

> **[GitHub - cathrynlavery/diagram-design: 29 editorial diagram types for Claude Code....](https://github.com/cathrynlavery/diagram-design)**
>
> 29 editorial diagram types for Claude Code. Self-contained HTML + SVG. No shadows, no Mermaid-slop.
