Diagram-Design: The Open-Source Tool With 7,900+ GitHub Stars That Turns AI Coding Agents Into Editorial Designers

If you've ever asked an AI coding agent to create a diagram, you probably got back something that looked like a generic box-and-arrow mess — rounded rectangles in random colors, no visual hierarchy, nothing that matches your brand. You'd either spend 30 minutes wrestling with Figma, or skip the diagram entirely.

Diagram-Design solves this. It's an open-source agent skill that turns AI coding assistants — Claude Code, Codex, and Pi — into diagram generators that produce editorial-quality visuals. Think architecture diagrams, flowcharts, sequence diagrams, state machines, Gantt charts, and 24 more types — all as self-contained HTML+SVG files that you can open directly in a browser.

With 7,900+ GitHub stars and 1,616 stars gained in a single day, Diagram-Design has become one of the fastest-growing tools in the AI developer ecosystem. Here's why developers are paying attention.

What Is Diagram-Design and How Does It Work?

Diagram-Design is a Claude Code skill (also compatible with Codex and Pi) created by Cathryn Lavery. It ships with 29 pre-built diagram types, each rendered as a self-contained HTML file with inline SVG — no build step, no JavaScript, no external images, no dependencies.

The skill works by combining a design system (with semantic color tokens and typography rules) with type-specific templates for each diagram kind. When you ask your AI agent to create a diagram, it picks the right type, builds the HTML, and saves it. The result looks like something a professional designer made — not a generic AI output.

Here's how to install it for Claude Code:

# Claude Code
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

# Codex
npx skills add https://github.com/cathrynlavery/diagram-design --skill diagram-design

# Pi
pi install https://github.com/cathrynlavery/diagram-design

Once installed, you simply describe what you need in natural language:

"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 right diagram type, applies your brand colors, and produces a publication-ready file.

The 29 Diagram Types: From Architecture to Data Flow

What sets Diagram-Design apart is the breadth of diagram types it supports. Here's the complete catalog:

Core Technical Diagrams:

• Architecture — Components and connections in your system
• Flowchart — Decision logic with branching paths
• Sequence — Messages between actors over time (with ALT combined-fragment grammar)
• State Machine — States and transitions for stateful systems
• ER / Data Model — Entities, fields, and relationships
• Timeline — Events plotted on a time axis
• Swimlane — Cross-functional process flows
• Data Flow — Role-scoped pipeline steps

Strategic & Analytical Diagrams:

• Quadrant — Two-axis positioning (impact vs. effort, risk vs. reward)
• Pyramid / Funnel — Ranked hierarchy or conversion drop-off
• Radar / Spider — Multi-axis comparison across dimensions
• Loop — Flywheel diagrams with stations around a shared-memory hub
• Consultant 2×2 — Scenario matrix with named cells
• Venn — Set overlap visualization

Organizational & Planning:

• Tree — Parent-child hierarchies
• Org Chart — Ownership and routing structures
• Nested — Hierarchy by containment
• Layer Stack — Stacked abstractions (infrastructure → application → user)
• Gantt — Tasks and phases on a timeline
• Process — Multi-actor sequential workflows

Data & Charts:

• Bar Chart — Categorical comparison
• Line Chart — Trends over time
• Scatter Plot — Distribution and correlation
• High-Level — End-to-end stack on a cluster

Data Platform Specific:

• Medallion — Multi-tier data storage (bronze → silver → gold)
• DP Integration — Sources → core → consumers
• DP Security Matrix — Per-role access permissions
• IT Current-State — Legacy landscape and modernization planning

Each type ships in three variants: minimal light, minimal dark, and full-editorial. You can browse them all by opening the included gallery HTML file.

Brand Matching in 60 Seconds

This is where Diagram-Design really shines. Out of the box, diagrams render in a clean default palette (jet-black ink, white-smoke paper, atomic-tangerine accent). But the real power is the automatic brand onboarding.

Here's how it works:

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

Agent: → fetches the homepage
      → extracts the dominant palette + font stack
      → maps detected values to semantic roles:
        paper, ink, muted, accent, link
      → shows a proposed diff
      → writes your tokens to references/style-guide.md

You: "yes, apply it"

The skill maps your website's colors to semantic roles:

• <body> background → paper token
• Primary text color → ink token
• Secondary/caption text → muted token
• Most-used brand color (CTA, links) → accent token
• <h1> font family → title font
• <body> font family → node-name font

It even verifies WCAG AA contrast on ink-over-paper colors. If your site has a color that fails contrast at diagram font sizes (9–12px), it proposes an adjusted value and explains why.

After onboarding, every diagram you generate uses your brand colors. Your website's background becomes the diagram background. Your CTA color becomes the focal accent. No manual color-picking, no Figma sessions.

Importing Existing Diagrams from Draw.io and Mermaid

Already have diagrams in draw.io or Mermaid? Diagram-Design can redraw them in the editorial style — same content, better design, at whatever size and detail level your audience needs.

# Import from draw.io
/diagram-design:import platform.drawio
/diagram-design:import platform.drawio --size=slide-16x9 --detail=simplified --audience=executive

# Import from Mermaid
/diagram-design:import-mermaid README.md --diagram=all
/diagram-design:import-mermaid architecture.mmd --size=slide-16x9 --detail=simplified

The import system reads common draw.io containers (.drawio, .drawio.xml, .drawio.png with embedded diagrams, .drawio.svg) including compressed base64 payloads. For Mermaid, it accepts .mmd, .mermaid, and fenced Mermaid blocks in Markdown files.

Detail levels include:

• faithful — preserves all nodes and connections
• balanced — smart reduction for blog posts and documentation
• simplified — executive-summary level for presentations

Real-World Example: Documenting a Microservices Architecture

Let's say you're a developer writing documentation for a microservices architecture. You need an architecture diagram showing your API gateway, three services, a PostgreSQL database, Redis cache, and a message queue.

Without Diagram-Design: You'd open Figma or draw.io, spend 20-30 minutes placing boxes, drawing arrows, picking colors, and aligning elements. Or you'd ask Claude and get back a generic SVG that doesn't match your documentation's style.

With Diagram-Design:

"Make me an architecture diagram of our e-commerce platform:
- API Gateway (Kong) at the top
- Three services: User Service, Order Service, Payment Service
- PostgreSQL for User Service and Order Service
- Redis cache for Order Service
- RabbitMQ connecting Order Service to Payment Service
- External: Stripe API connected to Payment Service"

In seconds, the agent generates a clean, branded architecture diagram. The accent color highlights the critical path (API Gateway → Order Service → Payment Service → Stripe). Muted colors show supporting infrastructure. The diagram is self-contained HTML — you can screenshot it for your README, embed it in your docs, or open it in a browser for a full-page view.

If you need the same diagram for different audiences:

# For your engineering team (full detail)
/diagram-design:import platform.drawio --detail=faithful

# For your blog post (balanced)
/diagram-design:import platform.drawio --detail=balanced

# For your investor deck (simplified, slide format)
/diagram-design:import platform.drawio --size=slide-16x9 --detail=simplified --audience=executive

Key Benefits

• 29 diagram types — Covers virtually every diagram need: technical, strategic, organizational, and data visualization
• Brand matching in 60 seconds — Reads your website and automatically applies your colors, fonts, and visual identity
• Self-contained output — HTML+SVG files with zero dependencies. No build step, no JS, no external images
• Three variants per type — Minimal light, minimal dark, and full-editorial for different contexts
• Draw.io and Mermaid import — Redraw existing diagrams at the format and detail level your audience needs
• Accessibility built-in — WCAG AA contrast verification, proper ARIA labels, semantic SVG structure
• Multi-agent compatible — Works with Claude Code, Codex, and Pi through the standard Agent Skills interface
• No design tools required — Eliminates the need for Figma, draw.io, or manual SVG editing
• Open source — Full source code available, customizable style guide, MIT license

Design Philosophy: Density 4/10

One of Diagram-Design's core principles is what the creator calls "density 4 out of 10." The highest-quality move is usually deletion. Every node earns its place. The accent color is reserved for the 1–2 things the reader should look at first.

This is the opposite of most diagram tools, which encourage you to add more elements, more colors, more decorations. Diagram-Design enforces restraint — the result is diagrams that communicate clearly and look professional.

The skill also won't silently ship default-skinned diagrams into a branded project. On first use in a new project, it checks if the style guide has been customized and asks: "This is your first diagram in this project. The style guide is still at the default. Want to run onboarding, paste tokens manually, or proceed with default?"

FAQ

Q: Is Diagram-Design free to use?
A: Yes. Diagram-Design is completely open source and free to use. You can install it via the plugin marketplace for Claude Code, via npx for Codex, or via Pi's package manager. The source code is available on GitHub under an open license.

Q: Which AI coding agents does Diagram-Design work with?
A: Diagram-Design is compatible with Claude Code, Codex (via Agent Skills), and Pi. It uses the standard Agent Skills interface, so any tool that supports this format can potentially use it. Installation takes about 30 seconds per agent.

Q: Can I customize the diagram colors and fonts?
A: Yes. You can customize everything through the automatic brand onboarding (which reads your website), or manually edit the style-guide.md file. All 29 diagrams, the annotation system, and the gallery inherit from the same semantic token names — change the accent token once, and every diagram updates.

Q: Do I need to know HTML or SVG to use Diagram-Design?
A: No. You describe what you need in natural language ("Make me a flowchart of our user registration process"), and the AI agent generates the HTML+SVG file. You can open it directly in any browser. If you want to customize templates, basic HTML knowledge helps but isn't required.

Q: Can I import my existing draw.io or Mermaid diagrams?
A: Yes. Diagram-Design can import from draw.io (.drawio, .drawio.xml, .drawio.png, .drawio.svg) and Mermaid (.mmd, .mermaid, Markdown fenced blocks). It redraws them in the editorial style at your chosen size, detail level, and audience focus.

Q: What output format does Diagram-Design produce?
A: Diagram-Design produces self-contained HTML files with inline SVG. These can be opened directly in any browser, embedded in documentation, screenshotted for presentations, or converted to PNG/PDF using browser print functionality. There are no external dependencies — the file works standalone.

Q: How does the brand onboarding work?
A: You tell the agent your website URL. It fetches the homepage, extracts the dominant color palette and font stack, maps them to semantic roles (paper, ink, accent, muted, link), verifies WCAG AA contrast, and shows you a proposed diff. You approve, and every future diagram uses your brand identity automatically.

Q: Are the diagrams accessible?
A: Yes. Every diagram template includes proper accessibility markup: role="img", resolving aria-labelledby, first-child <title> and <desc> slots, and prefixed IDs to prevent conflicts when multiple SVGs are inlined on one page. Decorative elements are hidden from assistive technology.

Ready to level up your documentation? Explore CoddyKit's courses to master AI-powered development workflows and modern tooling.