Diagram Design: The Claude Code Skill That Writes Taste Down

Diagram Design is an Agent Skill. You install it into Claude Code, Codex, Cursor, GitHub Copilot, Factory Droid, Gemini CLI, Cline, Windsurf or Amp, then ask for a diagram in plain English, and the agent writes one .html file you open by double-clicking.

It crossed 53,000 stars, with 3,384 forks, in under six months. The repository was created in April 2026 and it is MIT licensed.

The GitHub language label says HTML, which is accurate and slightly misleading. There is no application here. What ships is a set of markdown reference files, a handful of Python extraction scripts, and a library of example HTML files. The whole thing is instructions for a model, plus the gates that check the model obeyed them.

That makes it a useful thing to study even if you never install it, because it is one of the clearest worked examples of the question every skill author eventually hits: how do you encode judgement, rather than just capability, in a file an agent reads?

The author, Cathryn Lavery, explains the origin in one paragraph that is worth quoting because it names the problem precisely:

I wanted diagrams I actually liked for my blog posts. Every time I needed one, whether an architecture sketch, a flowchart, or a pyramid of what matters most, I'd ask Claude and get back a generic rounded-box thing that looked nothing like the rest of the site. I'd either fight with Figma for 30 minutes or skip the diagram.

Then the key line: the model already understood the content. What it was missing was taste, so I wrote the taste down.

This is the part most people get wrong when they write skills. The instinct is to describe the capability, "you can draw diagrams", when the model could already do that. The gap was never capability. The gap is that a model with no constraints produces the statistical average of every diagram it has ever seen, and the statistical average of all diagrams is a grey rounded box with a drop shadow.

So the skill does not teach drawing. It removes options. One accent colour, reserved for the one or two things the reader should look at first. 1px hairline borders. No shadows at all. Maximum border radius of 10px. Target information density of 4 out of 10, with an explicit instruction that the highest-quality move is usually deletion.

Constraint, not instruction, is what produces the house style.

One rule in the design system is marked non-negotiable, and the README says exactly why:

Every coordinate, width, and gap is divisible by 4. That rule is non-negotiable; it's what keeps the diagrams from feeling AI-generated.

That is a sharper diagnosis than it first appears. When you look at a generated diagram and something feels off without being able to say what, you are usually reacting to near-misses: a node at x=247 next to one at x=250, a 13px gap beside an 11px gap. No single value is wrong. The accumulated irregularity is what reads as careless.

A human designer gets alignment for free because their tool snaps to a grid. A model emitting SVG coordinates as text has no snapping, so the grid has to become a stated rule it can check its own output against.

The type ramp works the same way, and it is tied to output size rather than fixed. A diagram built for a projected slide gets 16px node names where a doc-inline diagram gets 12px. If you are translating those sizes into a stylesheet of your own, an em to px converter saves the arithmetic, since the diagrams specify px while most design systems reason in em or rem.

Three font families carry the whole system: Instrument Serif for titles and italic callouts, Geist for node names, Geist Mono for technical sublabels. The monospace rule is specific and good: mono is for genuinely technical content such as ports, URLs and field types, not as a blanket "developer" aesthetic.

The skill covers 45 diagram types, each shipping in three static variants: minimal light, minimal dark, and full editorial.

The list runs well past the usual suspects. Alongside architecture, flowchart, sequence, state machine, ER, timeline, swimlane, quadrant and Gantt, there are types most diagram tools never offer: Wardley maps, service blueprints, fishbone cause analysis, medallion data tiers, story maps, waterfall bridges, polar charts, and exploded axonometric projections that pull a phone or a keyboard apart along one axis.

The interesting engineering is not the count, it is what the count costs. Forty-five type references, plus semantic patterns, animation contracts, primitives and import grammars, is far more than you want in an agent's context on every request.

The answer is progressive disclosure. At startup the agent sees only the skill's name and description. A matching request loads SKILL.md. Only then does it pull the one reference it needs:

The README states the property this buys in one line: no matter how many types exist, the agent only reads the one you need, so adding a type tomorrow changes nothing else.

That is the architectural lesson worth stealing. A skill's context cost should scale with the request, not with the size of the skill.

Out of the box, diagrams render in jet black and tangerine on white smoke. The README is honest that this is "good enough to screenshot straight away" and that sixty seconds of onboarding is better.

The onboarding flow is a single sentence to your agent:

"onboard diagram-design to https://yoursite.com"

The agent fetches your homepage, extracts the dominant palette and font stack, and maps what it found onto semantic roles rather than raw hex values:

Two details raise this above a colour-picker script.

First, contrast is checked before tokens are written. The skill verifies WCAG AA contrast of ink on paper at the sizes diagrams actually use, 9px to 12px, and if your brand colour fails there it proposes an adjusted value and explains why rather than silently shipping unreadable labels. The default skin is held to the same contract in CI: text roles clear 4.5:1 and essential marks clear 3:1 on both light and dark paper.

Second, brand matching emits a fidelity receipt: the URLs it sampled, the exact colour roles, font families and weights, font source URLs, and any fallback it had to take. Public site fonts are used directly and verified after rendering instead of being quietly swapped for a generic system stack. You get told what it could not match.

There is also a first-run gate. On the first diagram in a new project, if style-guide.md is still at defaults, the skill stops and asks whether to onboard, paste tokens manually, or proceed with the default. It will not silently ship default-skinned diagrams into a branded project.

If you juggle clients, onboard each brand once, save it as a named profile, and drop a .diagram-design marker containing profile: <slug> into each project. Parallel workspaces then use different brands without overwriting a shared install.

If you already have diagrams, the skill does not convert them. It redraws them: same content, its design system, sized for wherever the output is going.

It reads .drawio, .drawio.xml, .drawio.png with an embedded diagram, and .drawio.svg, including the compressed payloads that look like base64 noise in an editor. For Mermaid it takes .mmd, .mermaid, and fenced mermaid blocks inside Markdown. For Excalidraw it takes .excalidraw scene files, parsing text only with no rendering, JavaScript, browser or network access.

A draw.io file is XML underneath, and if you want to see what the extractor sees before handing it over, running the file through an XML to JSON converter makes the node and edge structure legible in a way the raw markup does not.

The point, as the README puts it, is not conversion but fitting the output to its destination. Four dials control that:

The detail ladder degrades in a stated order: decorations first, then duplicates, then leaf clusters, then infrastructure. You can predict what a simplified pass will drop.

The audience dial is the cleverest of the four, because it changes language while leaving structure alone. The same node reads Auth Service / JWT · RS256 · :8443 for an engineer, Auth Service / token check for a mixed room, and simply Sign-in for an executive.

Every import closes with a fidelity ledger:

Detail: balanced · 12 source nodes → 8 drawn
Collapsed: "Token valid?" decision → edge label on Gateway → Auth
Dropped:   1 sticky note ("legacy path, to be retired"), unconnected in source
Kept in full: the request path (Web/Mobile → Gateway → Orders → Postgres)

The reasoning behind that is sound: you know your own source diagram, so you would notice the omissions anyway. Being told is better than discovering it in a review.

What never carries over is also stated plainly: source coordinates, source palette, source fonts, draw.io's diagonal connector spaghetti, Mermaid's automatic layout, and Excalidraw's hand-drawn geometry. What always carries over is components, relationships, grouping and direction.

Every diagram is a single self-contained HTML file with inline SVG. No build step, no JavaScript, no external image dependency. Double-click it and it opens.

The only network request is Google Fonts, pulling Instrument Serif, Geist and Geist Mono. Ask for system fonts, or set the font source to system in your style guide, and the file makes no network requests at all, falling back to the platform's own serif, sans and mono faces. For anything going into an air-gapped environment or a PDF pipeline, that switch matters.

Accessibility is built into the template rather than bolted on. Each inline SVG gets role="img", a resolving aria-labelledby, and first-child <title> and <desc> elements. IDs are prefixed per diagram and variant, so several exported SVGs can be inlined on one page without colliding accessible-name IDs, which is the bug that usually appears the moment you put two generated SVGs in one document. Decorative icons are hidden from assistive technology instead of being announced.

Motion is optional, off by default, and constrained. The none, reveal, step and loop modes each require a complete static first frame and deterministic timing, prefers-reduced-motion renders the full static frame with playback controls hidden, and motion files must use the exact reviewed controller. Arbitrary inline scripts, remote assets, CSS imports and executable HTML attributes are rejected.

Because the output is one HTML file, publishing it to a docs site is a copy. If you are inlining many of them, an HTML minifier trims the per-file overhead without touching the SVG geometry, which is the part you cannot afford to have rewritten.

Exporting is a slash command or a sentence. SVG export extracts the <svg> node and injects the font imports so it renders standalone in browsers, Figma and Illustrator. PNG export rasterises through Playwright at 2x by default. Both are diagram-only: the editorial cards and headers from the -full variants are not included, so for a shot of the full layout you use print-to-PDF or a full-page screenshot.

The section that most raises confidence in the repo is the one that argues against itself. The README lists, specifically, when you should not reach for this skill:

• Diagrams that live in Git and change every sprint go to Mermaid, because Mermaid diffs and GitHub renders it.
• Quick unicode diagrams for a tweet or terminal output belong in a wiretext-style skill.
• Lists of anything should be a table or bullets.
• Before and after comparisons should be a table. If you are building those by hand, a markdown table generator is the faster path and the output diffs cleanly in review.
• One-shape diagrams, a single labelled box, should just be a sentence.

Then the question it tells you to ask before drawing anything: would a reader learn more from this than from a well-written paragraph? If no, do not draw.

The comparison table is equally frank about the trade-off. Output quality depends on the model you run it with, and the same prompt can lay out differently on two runs. The result is not an editable source format: there is no text to diff in a pull request and no canvas to drag a box on. Changing it later means asking the agent again or editing the SVG by hand.

So the honest positioning, which the repo states itself, is that Mermaid is still the better fit for docs that live in Git and change constantly. Diagram Design is for the diagram you are going to publish. That is a real and narrower claim than "replaces Mermaid", and it is the claim the project actually delivers on.

A skill that only writes instructions has no way to know whether the model followed them. This repo closes that loop with CI, and the gates are more specific than most:

• lint-skin.py checks palette, fonts, accessibility and single-file safety.
• lint-render.py loads the output in Chromium and inspects the rendered layout rather than the source.
• verify-geometry.py checks label, connector and port geometry.
• verify-docs-sync.py verifies that routing, the gallery, the README and the type counts still agree.

The render lint is the one worth noticing. Checking generated SVG by reading the markup tells you the coordinates are on the grid; it cannot tell you two labels overlap or a node clips its container at the viewBox you chose. Rendering it in a real browser and measuring catches the failures that only exist after layout. Every pull request runs these on Linux, Windows and macOS.

There is an end-user equivalent too. Running python3 skills/diagram-design/scripts/self_check.py <file> on any generated diagram prints OK when it passes, and --offline additionally fails the file if it still carries the Google Fonts link. That is a genuinely useful gate to put in your own docs pipeline.

The README also publishes an "it's working if" list, which doubles as a bug report template: a routine request should load SKILL.md, exactly one type reference and at most two core references; the agent should state its chosen type, pattern, size and planned cuts before drawing; the output should open offline; screen readers should announce the title and description. If any of those fail, it says, that is a bug worth filing.

Install it with one line, npx skills add cathrynlavery/diagram-design, or through the plugin marketplace of whichever agent you run.

It is worth your time if you publish diagrams: blog posts, docs sites, decks, README headers, anywhere the diagram is the artefact rather than a sketch in a pull request. The brand onboarding is the feature that justifies it over asking a model directly, because it is the difference between a diagram that sits on your page and one that looks pasted in from somewhere else.

It is not worth it if your diagrams live in version control and change every sprint. The repo says so itself, and Mermaid remains the right answer there.

The broader reason to read this repository, even if you never draw a diagram with it, is that it is a working answer to a question every agent skill eventually faces. Models are not short on capability. They are short on constraint. Diagram Design writes down a specific, opinionated, arguable set of constraints, then builds the CI to prove the model honoured them, and loads only the fraction of those constraints each request actually needs.

That pattern transfers to almost any skill you might write.