How to Automate Diagram Generation with Diagram Design: A Complete Guide for AI Agents

Diagram Design is a self-contained skill that lets AI agents produce editorial-quality diagrams without any build step or external assets by following a three-layer architecture of skill core, references, and templates.

The Diagram Design skill enables Claude Code, Codex, Factory Droid, and Pi to generate professional diagrams programmatically. According to the cathrynlavery/diagram-design source code, the system supports 38 visual types through a declarative, single-file HTML output format. This guide covers how to automate diagram generation with Diagram Design using command-line interfaces, programmatic workflows, and CI validation.

How Diagram Design Works: The Three-Layer Architecture

The architecture consists of three distinct layers that agents navigate automatically when processing a diagram request.

Skill Core: Metadata and Decision Flow

The entry point is skills/diagram-design/SKILL.md, which defines:

• Skill metadata and capabilities
• All 38 visual types (flowcharts, architectures, quadrants, sequence diagrams, etc.)
• The decision flow: semantic pattern → visual type → layout → output

Agents load this file first to understand how to route any diagram request.

References: Lazy-Loaded Specifications

Individual specifications live under skills/diagram-design/references/ and are loaded only when needed:

• semantic-patterns.md — behavioral routing logic for selecting layouts based on what the diagram does rather than just how it looks
• type-<type>.md files (e.g., type-flowchart.md, type-architecture.md) — layout grammars for each visual type
• style-guide.md — design system tokens for colors, typography, and spacing
• animation.md — motion specification for interactive diagrams

Templates & Assets: Static Scaffolds

Three static HTML templates provide the foundation for all outputs:

Template	Purpose
assets/template.html	Minimal light variant
assets/template-dark.html	Minimal dark variant
assets/template-full.html	Full-editorial variant with summary cards
assets/template-motion.html	Motion-enabled with playback controls (reveal, step, loop)

All diagram examples (example-<type>.html) derive from these templates.

Quick Start: Generate Your First Diagram

View the Complete Gallery Locally

# macOS

open skills/diagram-design/assets/index.html

# Linux

xdg-open skills/diagram-design/assets/index.html

This opens all 38 diagram types in your browser for reference.

Generate with Claude Code

/diagram-design:make "architecture diagram of my app: frontend, backend, database, Redis cache"

Claude Code automatically loads SKILL.md, resolves to type-architecture.md, and outputs a single HTML file with inline SVG.

Generate with Codex

codex plugin add diagram-design@diagram-design
codex ask "make me a quadrant showing Q2 projects by impact vs effort"

Generate with Pi

pi install https://github.com/cathrynlavery/diagram-design
/pi ask "export a sequence diagram of a bearer call with token refresh on 401"

Import and Convert Existing Diagrams

Diagram Design includes extractors for migrating from other formats.

From Draw.io Files

# Extract structured intermediate representation

python3 scripts/drawio_extract.py path/to/platform.drawio

# Import with custom styling parameters

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

The drawio_extract.py script parses .drawio XML into a structured IR that any agent can then redraw using Diagram Design's design system.

From Mermaid Files

python3 scripts/mermaid_extract.py path/to/diagram.mmd

The mermaid_extract.py extractor handles Mermaid .mmd files with the same IR-based approach.

Export Formats and Motion Features

Export to SVG or PNG

After generating HTML, use Pi's export commands:

# SVG only

export-diagram path/to/diagram.html --svg-only

# High-resolution PNG (3x scale)

export-diagram path/to/diagram.html --png-only --scale=3

Add Motion and Interactivity

# Copy the motion scaffold

cp skills/diagram-design/assets/template-motion.html my-diagram.html

Edit the file to set <title>, <desc>, and diagram body. When opened, the diagram includes playback controls for reveal, step, and loop animations. The animation.md reference specifies timing, easing, and accessibility requirements for motion.

Design System Compliance and Validation

All generated diagrams follow strict rules defined in references/style-guide.md:

• Connectors: Rounded right-angle elbows only
• Label gaps: 6-10px spacing
• Accessibility: ARIA-compliant <title> and <desc> elements in every SVG

Automated Quality Checks

The scripts/self_check.py runtime validator agents can invoke on generated diagrams verifies compliance before final output.

CI Pipeline Verification

The .github/workflows/ci.yml pipeline runs on every push:

# Individual verifier scripts

python3 scripts/verify-geometry.py    # Geometric correctness

python3 scripts/verify-motion.py      # Animation validity

python3 scripts/lint-skin.py          # Design token compliance

Key Files Reference

File	Purpose
SKILL.md	Core skill metadata, visual-type guide, pre-output checklist
references/style-guide.md	Design system tokens (colors, typography, spacing)
references/semantic-patterns.md	Behavioral patterns for layout selection
references/type-flowchart.md	Layout grammar example (one of 38 type files)
scripts/drawio_extract.py	Draw.io to IR extractor
scripts/mermaid_extract.py	Mermaid to IR extractor
scripts/self_check.py	Runtime compliance checker

Summary

• Diagram Design is a zero-build skill for AI agents to generate editorial-quality diagrams
• The three-layer architecture (skill core → references → templates) enables lazy loading and precise control
• 38 visual types are supported through type-<type>.md specifications in references/
• Command-line integration works with Claude Code (/diagram-design:make), Codex, and Pi
• Import converters exist for Draw.io (drawio_extract.py) and Mermaid (mermaid_extract.py)
• All outputs follow strict accessibility and geometric rules validated by CI checks

Frequently Asked Questions

What AI agents support Diagram Design?

Claude Code, OpenAI Codex, Factory Droid, and Pi all support Diagram Design through native skill loading or plugin installation. Each agent loads SKILL.md as the entry point and follows the same decision flow to generate diagrams.

Can I customize colors and fonts in generated diagrams?

Yes. The references/style-guide.md defines all design tokens, and the three template variants (template.html, template-dark.html, template-full.html) provide starting points. Modify the CSS custom properties in any template scaffold before diagram generation.

How do I add animations to a diagram?

Use assets/template-motion.html as your scaffold. This template includes the motion system defined in references/animation.md, with JavaScript controls for reveal, step, and loop playback. The animation reference specifies timing curves and accessibility requirements for reduced-motion preferences.

What's the difference between importing and making a diagram?

Making (:make) generates from a natural language description using the semantic pattern router. Importing (:import-drawio, mermaid_extract.py) extracts structure from existing files into Diagram Design's intermediate representation, then redraws with full design system compliance.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}