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

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 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 — system architecture diagrams
• type-flowchart.md — process flows and decision trees
• type-sequence.md — UML sequence diagrams
• 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.

# 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 to select type-architecture.md and render the diagram. No manual template selection required.

To browse all available types:

# 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:

"Create a simplified executive summary architecture as a PNG"

Equivalent flag-based command:

/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

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

The 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

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

The 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:

# 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:

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

This populates 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 script validates generated diagrams for accessibility, motion compliance, and syntax integrity:

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:

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

# 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	Core routing logic and skill manifest
commands/import-mermaid.md	Mermaid import command specification
commands/import-drawio.md	draw.io import command specification
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	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, 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 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) and self-check script run standalone. However, the natural-language generation and type selection require an agent that can parse 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 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 validator confirms that motion implementations remain accessible across all output formats.

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