TL;DR

Diagram Design (cathrynlavery/diagram-design) is an agent skill that makes your coding agent draw diagrams the way a magazine designer would. You describe the diagram in plain words. The agent picks a type, states its plan, and writes one self-contained HTML file with inline SVG. The style is fixed and opinionated: one accent color, 1px hairlines, no shadows, every coordinate on a 4px grid. It can also pull your website’s colors and fonts so every diagram matches your brand.

Facts as of October 14, 2026:

  • 54,903 GitHub stars, 3,462 forks, MIT license. GitHub Trending lists it with 9,867 stars this week.
  • Created April 16, 2026. Last commit on main: October 13, 2026.
  • No GitHub releases. Versions live in the plugin manifests; the Claude plugin manifest reads 2.6.98.
  • 17 open issues and 29 open pull requests. Five of the open issues were filed on October 13, all about SVG export and the verifiers.
  • 44 numbered diagram types in the gallery (the README intro and SKILL.md say 45; the changelog says the gallery uses “one number per diagram type, 44 in total”).

Not run by us: our hands-on lab could not start today because the GitHub Actions job behind it was blocked by a billing limit on the account. Everything below comes from the repository, its changelog, reference files and privacy policy. We did not install the skill or generate a diagram with it.

Our verdict: this is the best-designed diagram skill we have read. It does not add a renderer or a layout engine. It writes the author’s taste down as rules and ships checkers that enforce them. That works well for diagrams you are going to publish: blog posts, decks, docs that rarely change. It is the wrong tool for diagrams that live in Git and change every sprint, and the README says so itself.

What it actually does

Ask most coding agents for an architecture diagram and you get Mermaid in the renderer’s default theme. Cathryn Lavery wanted diagrams for her blog at littlemight.com, and every request to Claude returned “a generic rounded-box thing that looked nothing like the rest of the site.” Her diagnosis: “The model already understood the content. What it was missing was taste, so I wrote the taste down.”

The skill is that written-down taste, plus tools to check it:

PartWhat it is
SKILL.mdPhilosophy, type selection guide, pre-draw checklist
references/One file per diagram type, a style guide, onboarding, import and export procedures, layout budgets
assets/HTML templates and three variants of every type example (minimal light, minimal dark, full editorial)
scripts/Python with no third-party dependencies: self_check.py, export_svg.py, and extractors for draw.io, Mermaid and Excalidraw

The output is a single .html file that opens with a double click. It has no build step and no JavaScript (except for the optional motion controller). The only network request is a Google Fonts stylesheet, and you can switch that off.

The design rules

The rules are short and strict. From the README and SKILL.md:

  • One accent color, on one or two focal elements. “Coral is editorial, not a flag. 1–2 focal nodes per diagram. Using it on 5 nodes erases the signal.”
  • 1px hairline borders, no shadows, border radius at most 10px.
  • Every coordinate, width and gap divisible by 4. The README calls this non-negotiable: “it’s what keeps the diagrams from feeling AI-generated.”
  • Three fonts: Instrument Serif for titles and italic callouts, Geist for node names, Geist Mono for technical sublabels such as ports and field types.
  • Target density 4/10. “Above 9 nodes, it’s probably two diagrams.”

The philosophy section opens with “The highest-quality move is usually deletion,” and the skill tells the agent when not to draw: lists belong in tables, and a one-shape diagram should just be a sentence.

The 44 types

The type list grew fast. Lavery’s launch post on X (April 16) announced 13 types. Version 2.0 (July 14) merged twelve more from a curated fork. Version 2.5 (August 18) added ten in one release, including Sankey, fishbone, Wardley map, kanban, user journey and database schema. Version 2.6 brought waterfall, heatmap, architecture delta, exploded axonometric and axonometric plan. This is why third-party listings still say 13, 27 or 29 types: they were written at different points in that climb.

Grouped roughly:

GroupTypes
SystemsArchitecture, architecture delta, IT current-state, high-level, deployment, dependency graph, layer stack, nested
Process and behaviorFlowchart, sequence, state machine, swimlane, process, user journey, service blueprint, story map, kanban, Gantt, timeline
DataER / data model, database schema, UML class, medallion, data flow, DP integration, DP security matrix, Sankey
ChartsBar, line, scatter, treemap, heatmap, waterfall, radar, polar
Strategy and conceptQuadrant, Venn, pyramid / funnel, loop / flywheel, fishbone, Wardley map, tree, org chart
Objects and spacesExploded axonometric, axonometric plan

Line, scatter and treemap also have named variants (slopegraph, ridgeline, bubble, beeswarm, marimekko and more). The live gallery shows every one in light, dark and editorial versions.

Pattern first, then type

When a diagram is about behavior rather than layout, the skill picks a semantic pattern before a visual type. SKILL.md lists nine; five examples:

TriggerPattern → nearest type
Fan-in, queue depth, bottleneckFan-in queue → Data flow
Two rule traces with pass/fail and first divergencePaired policy-evaluation traces → Flowchart
Trust boundaries plus permitted and forbidden pathsSecure paved road → Architecture
Controls grouped by where they are enforcedGovernance / control catalog → Layer stack
A subject moving through phases, retries and cancellationLifecycle phase map → State machine

The pattern sets the vocabulary and a tighter node budget; the type sets the layout grammar. For security or platform diagrams, this is worth reading even if you never install the skill.

Install

The fastest route works in any host that reads Agent Skills:

npx skills add cathrynlavery/diagram-design

This uses Vercel’s cross-agent skills CLI, which installs the whole skill folder into each host you select. It installs the skill only; the slash commands (/export-diagram, /import-mermaid, /profile, /doctor) come with the native marketplace packages.

Claude Code, through the plugin marketplace:

/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

Claude Code turns auto-update off by default for third-party marketplaces; the README shows how to turn it on. Codex (codex plugin marketplace add), Copilot, Factory Droid, Pi, Kiro and OpenCode each have a short README section. If you plan to edit the style guide, clone the repo and symlink skills/diagram-design: managed installs can overwrite references/style-guide.md on update.

Then ask in plain words, for example: “Make me an architecture diagram of my app: frontend, backend, database, Redis cache.”

Brand onboarding

The default skin is white-smoke paper, jet-black ink and a burnt-tangerine accent (#bf4520). It looks fine. But the point of the project is diagrams in your style, and onboarding is the feature that delivers it:

You:   "onboard diagram-design to https://yoursite.com"
Agent: fetches the homepage
       extracts the dominant palette + font stack
       maps them to roles: paper, ink, muted, accent, link
       shows a proposed diff
       writes the tokens to references/style-guide.md
You:   "yes, apply it"

Your page background becomes paper and your call-to-action color becomes accent. The skill checks WCAG AA contrast first; if a brand color fails at diagram text sizes (9–12px), it proposes an adjusted value. It also writes a “fidelity receipt” listing what it sampled and mapped.

The skill will not quietly ship default-styled diagrams into a branded project: on the first diagram in a new project it asks whether to onboard, paste tokens, load a saved profile or keep the default. Named profiles in ~/.diagram-design/profiles/ let a consultant keep several brands, with a .diagram-design marker file in each client repo naming the profile.

That first-run question has a downside for automation. Open issue #262 proposes an explicit path through the style gate for unattended runs. Until that lands, put a marker file or a customized style guide in place before you use the skill from a scheduled job or a CI agent.

Import: redraw Mermaid, draw.io and Excalidraw

If you already have diagrams, the skill can redraw them. The extractors are plain Python that parse text into an intermediate representation; the Mermaid extractor’s docstring says it “never evaluates, renders, fetches, or executes Mermaid, JavaScript, URLs, directives, or label content.”

/diagram-design:import-drawio platform.drawio --size=slide-16x9 --detail=simplified --audience=executive

Four dials shape the result:

DialOptions
Formathtml, svg, png, html+png
Sizedoc-inline, doc-wide, slide-16x9, slide-4x3, social-og, social-square, three print sizes, fit
Detailfaithful (≤24 nodes), balanced (≤12), simplified (≤7)
Audienceengineer, mixed, executive

The audience dial changes wording, not node count: “Auth Service / JWT · RS256 · :8443” becomes “Sign-in” for executives. Every import ends with a fidelity ledger of what was merged, collapsed or dropped; in the README’s example a 12-node draw.io file becomes 8 drawn nodes. Supported Mermaid grammars are flowchart, sequence, stateDiagram-v2 and erDiagram; a PlantUML import is an open feature request (#357).

Export and the self-check

export_svg.py turns a diagram into a standalone SVG for Figma or slides: it embeds a scoped copy of the page CSS, prefixes <defs> IDs so several figures can share one page, and --system-fonts drops the Google Fonts import. PNG export renders through Playwright at 2x.

self_check.py ships inside the installed skill so the agent can check its own output (python3 scripts/self_check.py my-diagram.html, plus --offline to fail on the Google Fonts link). Per its docstring, it checks the accessible-SVG contract (role="img", <title>, <desc>), single-file safety (no remote assets or scripts beyond the approved ones) and content staying inside the viewBox. CI runs far more: a palette linter, a Chromium layout checker, a geometry verifier for labels and connectors, and a WCAG contrast check.

How it compares

Diagram DesignArchifyMermaidExcalidraw / draw.io
Who lays it outThe agent, on a 4px grid, checked by scriptsThe agent writes typed JSON; a compiler rendersAutomatic layout engineYou, by hand
Diagram types445 at our September review, architecture-focusedMany built-in grammarsAnything you draw
OutputOne HTML file with inline SVG; SVG/PNG exportOne HTML file with an interactive viewerText that GitHub rendersEditable canvas file
Diffs in a PRNoThe JSON source doesYesPoorly
Brand matchingBuilt in, from a URLThemesTheme variablesManual
Same prompt, same resultNoCloser, because a deterministic compiler rendersYesn/a

Archify keeps a typed source of truth and compiles it deterministically; Diagram Design lets the model draw the SVG and relies on rules and checkers. The README is honest about this trade-off: “Output quality depends on the model you run it with, and the same prompt can lay out differently twice. The result is not an editable source format… For docs that live in Git and change every sprint, Mermaid is still the better fit. Diagram Design is for the diagram you are going to publish.”

Community reaction

The repository passed 50,000 stars within six months of launch and is on GitHub’s daily and weekly trending lists this week. Skill directories such as skills.sh and Skillselion list it.

The changelog shows where the work goes: since version 2.3, mostly into verifiers and export correctness rather than new styles. The five issues filed on October 13 are typical edge cases (CSS-escaped paint references lost in SVG export, a containment verifier that ignores !important), and fixes land in batches. The privacy policy (effective October 1) says the skill “has no server, no accounts, no analytics, and no telemetry.”

Honest limitations

  • Model-dependent quality. The skill gives the model rules and checks. A weaker model will still produce weaker layouts, and the same prompt can produce a different layout twice.
  • No editable source. You get SVG, not a diagram language. To change a diagram you ask the agent again or edit SVG by hand.
  • Not for living docs. No text diff in pull requests, and GitHub will not render the HTML inline. Use Mermaid there.
  • Fonts phone home by default. Opening a diagram requests Google Fonts. The privacy policy says Google receives the viewer’s IP address and may receive the page address. Use system fonts for internal or offline material.
  • The first-run gate blocks automation until a style guide or profile is in place (#262).
  • Stale example skin. The style guide notes that the pre-built examples in assets/ “were built under an earlier skin”, so the gallery does not always show the current tokens.
  • Install routes differ. npx skills add skips the slash commands and marketplace updates.

FAQ

Is Diagram Design free?

Yes. It is MIT-licensed and has no server, account or paid tier. You pay only for the model your coding agent uses to draw the diagram.

Which agents does Diagram Design work with?

Any host that reads Agent Skills. The README documents Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, Pi, Gemini CLI, Cline, Windsurf, Amp, Kiro and OpenCode.

Can Diagram Design replace Mermaid?

Not for diagrams that live in a repository and change often. Mermaid is text, so it diffs in pull requests and GitHub renders it. Diagram Design produces a finished HTML/SVG file. Use it to redraw a Mermaid diagram for a blog post, deck or report, and keep the Mermaid source in the repo.

Does it work offline?

Yes, with system fonts. By default a diagram loads three fonts from Google Fonts. Ask for system fonts (or use export_svg.py --system-fonts) and the file makes no network requests.

How does brand onboarding work?

You ask the agent to “onboard diagram-design to” your site’s URL. It fetches the homepage, extracts colors and fonts, maps them to roles (paper, ink, muted, accent, link), checks contrast, shows you a diff, and writes the tokens to the style guide after you approve. Save the result as a named profile to reuse it across projects.

Verdict

Diagram Design is not a renderer. It is a style guide, a type library and a set of checks, written carefully enough that a good model produces diagrams you would put in front of readers. If you publish diagrams in posts, decks or reports, install it and run onboarding once. If your diagrams live next to the code and change every week, keep using Mermaid and use this skill only for the published version.

Sources