diagram-design: Making Claude Code Draw Editor-Grade Diagrams

Have you ever asked an AI to draw an architecture diagram? If so, you probably know the scene: you describe a microservices architecture with data flows and a permission layer, and Claude or GPT hands back a Mermaid chart—rounded boxes, gray arrows, mushy font sizes. Show it to a designer and watch them wince. Then you open Figma, and 30 minutes later the diagram still isn't done.

cathrynlavery/diagram-design was born from exactly that moment. It's a Claude Code skill offering 27 diagram types, all as self-contained HTML+SVG—no external dependencies, no JS, viewable directly in a browser. It pulled in 2,951 stars in a single day. This isn't another "awesome-xxx" list; it's a real pain point actually solved.

27 Diagram Types, Not 27 Templates

The key distinction: most tools give you templates—change colors, text, and connectors; it's still fill-in-the-blank. diagram-design gives you grammar—each type has its own structural rules, and the skill knows when to use swimlanes, a pyramid, or a flywheel.

The 27 types include:

• Architecture: Components, Flowchart, Sequence, State machine, ER model
• Hierarchy: Tree, Org chart, Nested, Pyramid, Layer stack
• Positioning: Quadrant, Radar, Venn
• Process: Swimlane, Process, Timeline, Gantt
• Data: Bar, Line, Scatter, Medallion, Data flow
• Special: Loop (flywheel), IT current-state, Consultant 2×2, DP integration, DP security matrix

The most interesting 2.0 addition is Loop—a flywheel diagram with a "shared memory hub," where dashed lines represent write-back. This isn't a traditional chart; it's a modeling tool for dynamic systems.

Brand Adaptation in 60 Seconds

This is what actually delivers the "editor-grade" feel.

Feed the skill your website URL. It reads your CSS, extracts primary colors, secondary colors, and fonts, then maps them onto every node, connector, and label across all 27 diagram types. Sixty seconds later, your architecture diagram speaks the same design language as your website.

This step kills the root cause of "AI diagrams looking AI-generated": mismatched colors and fonts. The diagram itself isn't ugly—it just doesn't harmonize with its context. diagram-design automates that harmonization.

Why a Claude Code Skill, Not a Standalone Tool

This is the project's most thought-provoking design decision.

It's not a SaaS, a Figma plugin, or a desktop app. It's an Agent Skill—installed into Claude Code, Codex, or Pi, invoked at the agent's own discretion.

What does that mean?

• You tell Claude in conversation, "draw a microservices architecture," and Claude calls the skill itself, picks the diagram type itself, generates the SVG itself
• No tool switching, no separate app, no copy-pasting
• Diagram generation becomes part of the conversation flow, not a separate "rendering task"

This is a new paradigm for tool design in the AI era: tools are no longer invoked by people; they're invoked by agents. Skills are the agent's hands.

"Deletion Is the Highest-Quality Move"

Author Cathryn Lavery wrote a line in the README worth remembering:

> The highest-quality move is usually deletion. Every node earns its place.

It's anti-Mermaid, anti-PowerPoint, anti-"more is better." Editor-grade quality comes from restraint—accent color reserved for only the 1–2 elements readers should see first, a target density of 4/10, and every node must earn its place.

This aligns perfectly with classic design principles: Dieter Rams' "less but better," John Maeda's *Laws of Simplicity*, Edward Tufte's data-ink ratio. diagram-design encodes these principles into the skill's default behavior.

Three Variants: From Draft to Delivery

Every diagram type ships in three versions:

1. Minimal Light: white background, black lines, one accent color 2. Minimal Dark: dark theme, suited for embedding in docs 3. Full Editorial: full brand colors, suited for blogs and presentations

So you can sketch a minimal version in conversation for quick discussion, then generate the full editorial version for publication once finalized. One skill covers the whole draft-to-delivery pipeline.

Installation Reveals the Ecosystem Landscape

diagram-design supports four platforms, each with different installation:

• Pi: pi install https://github.com/cathrynlavery/diagram-design
• Claude Code: /plugin marketplace add cathrynlavery/diagram-design
• Codex: npx skills add https://github.com/cathrynlavery/diagram-design
• Claude Cowork: manually paste the URL

These four platforms represent the current state of the "Agent Skill ecosystem"—no unified standard, each platform with its own package manager, but all compatible with the same skill file format. It looks a lot like the early days of npm/pip/gem fragmentation.

diagram-design's value isn't just "pretty diagrams"—it's one of the first reference implementations of a cross-platform agent skill. If you want to know what plugins look like in the agent era, this is a living specimen.

The Numbers

• +2,951 stars today—No. 1 on GitHub Trending, far ahead of second place
• 27 diagram types × 3 variants = 81 deliverables
• 0 external dependencies—pure HTML+SVG, no JS, no build step
• 60-second brand adaptation—reads website CSS and maps automatically
• 4 agent platforms supported—Pi, Claude Code, Codex, Claude Cowork

A Deeper Observation

diagram-design going viral isn't just a tool getting popular—it marks the maturation of a new form: the agent skill as an independent product.

Over the past two years, AI tooling has evolved through three stages:

1. Prompt templates (2023–2024): a written prompt, copy-paste to use 2. GPTs / Custom Agents (2024–2025): packaged system prompts with tool calling 3. Agent Skills (2025–2026): cross-platform, composable capability packages with their own workflows

diagram-design is a typical representative of the third stage—it's not "teaching AI to draw," it's "giving AI a drawing workflow." The model understands what you want; the skill delivers to an editorial standard.

That division of labor is the right way to design tools in the AI era: let the model be the poet, let the skill be the accountant. It's the same principle as Euclid-MCP's "reasoning offloading": leave strengths to the model, outsource weaknesses to specialized tools.

---

Repo: cathrynlavery/diagram-design Language: HTML Today's growth: +2,951 stars Install: /plugin marketplace add cathrynlavery/diagram-design (Claude Code)