Diagram Design

Open source project by Cathryn Lavery (cathrynlavery/diagram-design, MIT).

Why use it?

The README explains why Cathryn Lavery built it: “I wanted diagrams I actually liked for my blog posts on littlemight.com. 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.”

“The model already understood the content. What it was missing was taste, so I wrote the taste down: one accent color for the one or two things that matter, 1px hairlines, no shadows, every coordinate on a 4px grid.”

What you can make

Ask your agent in plain words. The README’s examples:

Make me an architecture diagram of my app: frontend, backend, database, Redis cache.
I need a quadrant showing Q2 projects by impact vs effort.
Give me a sequence of a bearer call with token refresh on 401.

The agent picks the type, states its plan, and writes one .html file you can open by double-clicking.

The README lists 45 diagram types, each in three static variants: minimal light, minimal dark, and full-editorial. Some of them:

Browse every type in the live gallery.

Key features

• One opinionated editorial style

  One accent color, 1 or 2 focal elements per diagram. 1px hairline borders, no shadows. Every coordinate, width, and gap is divisible by 4: “That rule is non-negotiable; it’s what keeps the diagrams from feeling AI-generated.”

• Onboarding: make it look like your brand

  Out of the box, diagrams render in a jet-black + tangerine palette. With onboarding, the skill fetches your homepage, extracts the dominant palette and font stack, maps detected values to semantic roles (paper, ink, muted, accent, link), shows a proposed diff, and writes your tokens to the style guide. Every new diagram then uses your colors. Before writing tokens, the skill verifies WCAG AA contrast on ink over paper; if a color fails contrast at diagram sizes, it proposes an adjusted value and explains why.

• Import from draw.io, Mermaid, or Excalidraw

  Point the skill at the source and it redraws them: same content, this design system, at whatever size the destination needs. Four dials set the format, size, detail, and audience. Every import ends with a fidelity ledger listing what got merged, collapsed, or dropped. Components, relationships, grouping, and direction always carry over; source coordinates, palette, and fonts never do.

• Export to PNG / SVG

  Diagrams ship as self-contained HTML, but you can export the diagram itself for Figma, slides, or social cards. In Claude Code, use /diagram-design:export-diagram, or just ask: “Export this diagram as SVG and PNG.”

• Named profiles for multiple clients

  Onboard a brand once, save the result as a named profile, then add a .diagram-design marker containing the profile name to each client project. Profiles live in ~/.diagram-design/profiles/, so parallel workspaces can use different brands.

• Accessible by default

  Every diagram template gives the inline SVG an accessible name and description. Motion is optional; the default is none, and ordinary output remains static and script-free.

How to use

In Claude Code, the plugin marketplace gets you updates and the slash commands:

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

On any other host that reads Agent Skills, including Cursor, Codex, GitHub Copilot and Gemini CLI:

npx skills add cathrynlavery/diagram-design

Then ask your agent for a diagram. On first use in a new project, the skill checks if style-guide.md has been customized. If not, it pauses and asks whether you want to run onboarding, paste tokens manually, or proceed with default.

To match your brand:

Onboard diagram-design to https://yoursite.com

To redraw or export an existing diagram in Claude Code:

/diagram-design:import-mermaid README.md --diagram=all
/diagram-design:import-drawio platform.drawio --size=slide-16x9 --detail=simplified --audience=executive
/diagram-design:export-diagram path/to/diagram.html --png-only --scale=3

Notes

• The downsides, in the README’s words — “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: there is no text to diff in a pull request and no canvas to drag a box on. 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.”
• When not to use this skill — The README points lists of anything and before/after comparisons to a table or bullets, and a single box with a label to a sentence. “Before drawing, ask: would a reader learn more from this than from a well-written paragraph? If no, don’t draw.”
• No telemetry — Per PRIVACY.md, “It has no server, no accounts, no analytics, and no telemetry.” Your prompts and files are processed by the agent you use under that provider’s own privacy policy.
• Google Fonts — By default a diagram loads Instrument Serif, Geist and Geist Mono from Google Fonts, the only network request it makes. Ask for system fonts and the file makes no network requests at all.
• PNG export needs Playwright — PNG rasterizes the diagram via Playwright. One-time setup: pip install playwright && playwright install chromium. SVG export doesn’t need it.
• npx skills add installs the Agent Skill only — The /export-diagram, /import-mermaid, /profile, and /doctor command surfaces stay with the native packages, and a standalone install does not follow marketplace updates automatically. Pull updates with npx skills update diagram-design. On a host that has one of the marketplaces, the README says to prefer the marketplace.
• Turn on auto-update yourself — Claude Code disables auto-update by default for third-party marketplaces. Run /plugin, open Marketplaces, select diagram-design, and choose Enable auto-update.
• Type count — The README body says 45 diagram types, while the repository description and the gallery numbering say 44. This page follows the README body.
• Install count source — The install number above is from skills.sh npx skills telemetry. It is not listed on claude.com/plugins.
• Official builds — “Official builds come only from this repository”; per the README, a listing under any other name is an unofficial copy.
• Source — cathrynlavery/diagram-design (MIT). Website: diagramdesign.dev.