Claude Code diagram-design Skill: Editorial Diagrams

diagram-design is a diagram-generation skill that runs as a Claude Code plugin. Built by developer Cathryn Lavery and published as open source, its tagline is "Editorial diagrams your designer won't hate." Give Claude Code a plain-language instruction like "make an architecture diagram" and it applies a set of design rules on the fly to produce a single self-contained HTML file with the diagram drawn as inline SVG. There's no external image dependency, no build step, and no JavaScript library requirement — the generated HTML opens and renders correctly in any browser as-is.

It's distributed through the same Agent Skills mechanism that powers plugins for Claude Code, but both its generation method and its visual philosophy differ substantially from "code-to-diagram" tools like Mermaid. Below we walk through what it can do, how to install it, how to use it, its design philosophy, and how it compares to other diagramming tools.

Both the repository README and the skill definition file itself, skills/diagram-design/SKILL.md, list 28 visual types (GitHub's repository About blurb shows some inconsistency, citing 27 or 29 in different places — this article follows the README and SKILL.md, which agree on 28). Here are the main types:

Architecture
Flowchart
Sequence
State Machine
ER / Data Model
Timeline
Swimlane
Quadrant
Nested
Tree
Org Chart
Venn
Layer Stack
Pyramid / Funnel
Consultant 2x2
Radar / Spider
Loop
IT Current-State
High-Level
Bar Chart / Line Chart / Gantt / Scatter Plot
Process
Medallion
Data Flow
DP Integration / DP Security Matrix
Treemap

Every output is a single self-contained .html file. CSS is embedded inline, and the only external resource is Google Fonts. There's inline SVG, no build step, and no JavaScript required — animation is optional, and diagrams are designed to render correctly even in a static state with no JS running. You get three visual variants to choose from: minimal light (the default), minimal dark, and full-editorial, which adds card layouts and a hero section.

The other standout feature is brand application. Pass it a company website URL and it extracts the dominant color palette and font stack, then maps them to semantic roles: paper, ink, muted, accent, and link. Crucially, the skill is designed to present a diff before applying any brand changes — it never silently finalizes output using the default skin. It can also redraw existing draw.io or Mermaid diagrams using the same design system.

In Claude Code, install it through the plugin marketplace.

Codex supports the same marketplace mechanism.

For Pi (a separate agent CLI), you install directly from the GitHub URL.

No minimum Claude Code version is documented in the repository. Since the plugin system itself is a relatively recent Claude Code feature, it's worth making sure your local Claude Code install is up to date before adding the plugin.

Usage is straightforward. Once installed, just ask in plain language — "draw an architecture diagram" or "make a sequence diagram for this API" — and Claude Code infers the right semantic pattern from your prompt and generates the diagram. If you want to invoke the skill explicitly, Claude Code supports a /diagram-design: prefix command, and Pi uses /skill:diagram-design.

To apply your own branding, include your company's website URL in the request. The skill extracts colors and fonts from that site and presents a proposed diff for you to review before it's finalized. The output is a single .html file, so you can open it directly in a browser, drop it into a wiki or Notion page, or host it on a static site — no build step and virtually no external dependencies, which makes it easy to embed in documentation. If you want to wire diagram generation into your own workflow, invoking the skill through the Agent SDK is another option worth considering.

The part of SKILL.md that gets the most attention is its rules for avoiding the mass-produced look that AI-generated diagrams often have. The guiding principle stated up front is: "The highest-quality move is usually deletion." Every node should carry independent meaning, and every connection should carry information — nothing gets added just because it can be.

One especially concrete rule is a target density of 4 out of 10, defined as the sweet spot where a diagram is understandable without a legend while still being technically accurate. There's also a hard complexity ceiling: by default, 9 nodes and 12 arrows per diagram. Beyond that, the skill is instructed to split into an overview diagram plus detail diagrams rather than cramming everything into one. On top of that, the accent color (coral) is capped at two focal points per diagram, sequence diagram fragments are capped at two, and swimlane lanes are capped at five.

The styling rules are just as strict: one accent color only, at most three font families, 1px hairline borders, no shadows, border-radius capped at 10px — and, most notably, every coordinate, width, and spacing value must be divisible by 4. SKILL.md states plainly that this is what removes the "AI-generated" feel. Snapping everything to a 4-point grid produces the tidy, deliberate look of something a human designer laid out by hand, eliminating the subtle jitter and inconsistency that tends to give away AI-generated layouts. All of these design tokens live in a style-guide.md file, with the default palette built from three colors: white-smoke (paper), jet-black (ink), and atomic-tangerine (accent).

There's also a clear method for choosing which diagram type to use: first identify the semantic pattern (the behavior you're trying to show), then map that to the closest visual type. Components and their connections map to Architecture; decision logic maps to Flowchart; a sequence of messages over time maps to Sequence, and so on. This is a good example of what Agent Skills makes possible — embedding rule-based judgment directly into a prompt-driven workflow.

Since "avoiding the Mermaid look" is the main reason to reach for diagram-design, here's how it stacks up against the usual alternatives.

The short version: Mermaid trades a uniform look for text-based version control and easy updates, while diagram-design trades regenerating the whole diagram each time for automatic visual polish and brand fit. If you need a system diagram that updates automatically and often, Mermaid is the better fit; if you want a carefully composed single image for a document or blog post, diagram-design is the better fit. For a broader look at how tools in this space compare, see the Claude Code vs. Codex vs. Cursor vs. Copilot comparison.

Good fit: explanatory single-image diagrams for blog posts or documentation
Good fit: consultant-style 2x2 matrices or pyramid diagrams for proposals and executive presentations
Good fit: redrawing existing draw.io or Mermaid diagrams into one consistent design system
Good fit: quickly producing diagrams matched to your own site's brand colors and fonts
Poor fit: design documents that must strictly conform to UML notation
Poor fit: large system diagrams that need to auto-update continuously alongside code (text-based Mermaid is better suited to diffable version control)
Poor fit: lightweight diagrams meant to be embedded as text directly inside a README or codebase
Poor fit: pixel-precise product design work with interactions, at the level Figma handles