# How to Use Diagram Design for Code Visualization: A Complete Guide to AI-Powered Technical Diagrams

> Visualize your code with Diagram Design. This guide shows how to generate AI-powered technical diagrams from natural language or existing sources for clear, engaging documentation.

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

---

**Diagram Design is a Claude Code, Codex, Factory Droid, and Pi skill that generates editorial-quality diagrams from natural-language prompts or existing Mermaid and draw.io sources, outputting self-contained HTML files with optional motion and brand customization.**

This open-source tool from the `cathrynlavery/diagram-design` repository transforms how developers create architecture diagrams, flowcharts, sequence diagrams, and more. Instead of manual diagramming tools, you describe what you need and Diagram Design handles the rendering, styling, and export.

## Overview of the Diagram Design Workflow

Diagram Design operates through a **semantic pattern** that separates behavior from layout. The core workflow in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) routes your request to the appropriate **diagram type reference**, applies styling parameters, and renders the output.

The skill supports **38 distinct diagram types**, each defined in `skills/diagram-design/references/type-*.md` files. Common types include:

- [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md) — system architecture diagrams
- [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md) — process flows and decision trees  
- [`type-sequence.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-sequence.md) — UML sequence diagrams
- [`type-quadrant.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-quadrant.md) — 2×2 matrices for prioritization

## Step 1: Choose Your Diagram Type

Start with a natural-language prompt. The skill automatically loads the relevant type reference.

```bash

# Example prompt to any supported AI agent (Claude Code, Codex, etc.)

"Make me an architecture diagram of my app: frontend, backend, database, Redis cache."

```

This triggers [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) to select [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md) and render the diagram. No manual template selection required.

To browse all available types:

```bash

# macOS

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

# Linux  

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

```

This gallery displays all 38 diagram types with live previews.

## Step 2: Configure Size, Detail, and Audience

Diagram Design uses **four control dials** passed as command-line flags or natural-language modifiers:

| Parameter | Options | Purpose |
|-----------|---------|---------|
| Format | `html`, `svg`, `png` | Output file type |
| Viewport | `slide-16x9`, `doc-wide`, `social-1x1` | Canvas dimensions |
| Detail level | `faithful`, `balanced`, `simplified` | Abstraction depth |
| Wording | `engineer`, `mixed`, `executive` | Audience sophistication |

Example natural-language modifiers:

```bash
"Create a simplified executive summary architecture as a PNG"

```

Equivalent flag-based command:

```bash
/diagram-design:generate --type=architecture --detail=simplified --wording=executive --format=png

```

## Step 3: Import Existing Diagrams

Diagram Design can **redraw** existing Mermaid and draw.io files with its style system. This strips layout-specific attributes and applies consistent branding.

### Import Mermaid Files

```bash
/diagram-design:import-mermaid README.md --diagram=all

```

The [`import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-mermaid.md) reference file handles parsing `.mmd` syntax, extracting graph structure, and re-rendering. Use `--diagram=all` to convert every Mermaid block in a file, or specify individual diagram names.

### Import draw.io Files

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

```

The [`import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-drawio.md) reference converts XML-based `.drawio` sources. This is useful for migrating legacy diagrams to Diagram Design's cleaner output format.

## Step 4: Export to Production Formats

After generation, convert diagrams to embeddable formats using `/export-diagram` as specified in [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md):

```bash

# Export as SVG only

/export-diagram my-diagram.html --svg-only

# Export high-resolution PNG (3x scale for retina displays)

/export-diagram my-diagram.html --png-only --scale=3

```

The `--scale` parameter controls DPI multiplication for PNG outputs. SVG exports remain resolution-independent.

## Step 5: Apply Brand Customization

Run the **onboarding flow** to extract colors and fonts from your website:

```bash
/diagram-design:onboard --url=https://yourcompany.com

```

This populates [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) with your brand palette and typography. All subsequent diagrams automatically adopt these settings without manual intervention.

## Step 6: Validate with Self-Check

The [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) script validates generated diagrams for accessibility, motion compliance, and syntax integrity:

```bash
python3 skills/diagram-design/scripts/self_check.py output.html

```

This checker runs three validation suites:

1. **Accessibility** — color contrast ratios, alt text presence, ARIA labels
2. **Motion compliance** — respects `prefers-reduced-motion` settings
3. **Syntax integrity** — valid HTML structure, no broken references

## Working with Motion and Animation

Diagram Design supports **optional, accessible motion** through reveal animations. To enable:

1. Copy the motion template:

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

```

2. Edit the template to define animation sequences
3. Render — motion controllers persist even in static SVG exports

The motion system respects user accessibility preferences and degrades gracefully when animations are disabled.

## Complete Workflow Example

```bash

# 1. Browse diagram types

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

# 2. Generate from natural language (via AI agent)

"Make me a quadrant showing Q2 projects by impact vs effort"

# 3. Import existing Mermaid and re-render

/diagram-design:import-mermaid architecture.mmd --size=slide-16x9 --detail=balanced

# 4. Export for presentation

/export-diagram architecture.html --png-only --scale=2

# 5. Validate output

python3 skills/diagram-design/scripts/self_check.py architecture.html

```

## Key Files Reference

| File Path | Purpose |
|-----------|---------|
| [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | Core routing logic and skill manifest |
| [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) | Mermaid import command specification |
| [`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md) | draw.io import command specification |
| [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) | Export format and flag definitions |
| `skills/diagram-design/references/type-*.md` | Per-diagram-type specifications |
| `skills/diagram-design/assets/template-*.html` | Starter templates (light, full-editorial, motion) |
| [`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py) | Automated validation script |

## Summary

- **Diagram Design** turns natural language into production-ready diagrams through AI agent integration
- **38 diagram types** cover architecture, flowcharts, sequences, quadrants, and more
- **Import commands** ([`import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-mermaid.md), [`import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-drawio.md)) convert existing diagrams to the system's clean style
- **Four control dials** — format, viewport, detail, wording — tailor output to specific audiences and contexts
- **Self-check validation** ensures accessibility and compliance before publication
- **Brand onboarding** automates style guide creation from existing websites

## Frequently Asked Questions

### What AI agents support Diagram Design?

Diagram Design works with Claude Code, OpenAI Codex, Factory Droid, and Pi. The skill manifest in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) provides the routing logic these agents use to interpret diagram requests and select appropriate type references.

### Can I use Diagram Design without an AI agent?

Partially. The gallery viewer ([`assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/index.html)) and self-check script run standalone. However, the natural-language generation and type selection require an agent that can parse [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) and route to the appropriate reference files.

### How do I add a custom diagram type?

Create a new `type-{name}.md` file in `skills/diagram-design/references/` following the structure of existing type references. Define the visual grammar, layout rules, and example prompts. The [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) router will automatically detect and use new types on agent restart.

### What happens to animations in static exports?

Motion controllers remain embedded in SVG exports but respect `prefers-reduced-motion` settings. PNG exports capture a single static frame. The [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) validator confirms that motion implementations remain accessible across all output formats.