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

> Automate diagram generation with Diagram Design. This guide shows AI agents how to create editorial-quality diagrams using a three-layer architecture. Learn more now.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md), [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md)) — layout grammars for each visual type
- [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) — design system tokens for colors, typography, and spacing
- [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template.html) | Minimal light variant |
| [`assets/template-dark.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template-dark.html) | Minimal dark variant |
| [`assets/template-full.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template-full.html) | Full-editorial variant with summary cards |
| [`assets/template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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

```bash

# 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

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

```

Claude Code automatically loads [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), resolves to [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md), and outputs a single HTML file with inline SVG.

### Generate with Codex

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

```

### Generate with Pi

```bash
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

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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

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

```

The [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```bash

# 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

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/.github/workflows/ci.yml) pipeline runs on every push:

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) | Core skill metadata, visual-type guide, pre-output checklist |
| [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) | Design system tokens (colors, typography, spacing) |
| [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md) | Behavioral patterns for layout selection |
| [`references/type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/type-flowchart.md) | Layout grammar example (one of 38 type files) |
| [`scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/drawio_extract.py) | Draw.io to IR extractor |
| [`scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/mermaid_extract.py) | Mermaid to IR extractor |
| [`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py)) and **Mermaid** ([`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) defines all design tokens, and the three template variants ([`template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template.html), [`template-dark.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-dark.html), [`template-full.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template-motion.html) as your scaffold. This template includes the motion system defined in [`references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py)) extracts structure from existing files into Diagram Design's intermediate representation, then redraws with full design system compliance.