How to Use Diagram Design for Software Architecture Diagrams: A Complete Guide

Diagram Design lets you generate editorial‑quality software architecture diagrams directly from AI agents like Claude Code, Codex, Factory Droid, or Pi by installing a skill plugin, selecting the Architecture type, and exporting to HTML, SVG, or PNG.

Diagram Design is an open-source skill plugin that transforms natural language requests into production-ready software architecture diagrams. This guide walks you through the complete workflow—from installation to export—using the actual source code from the cathrynlavery/diagram-design repository.

---

Installing the Diagram Design Skill

To begin using Diagram Design for software architecture, you must first add the plugin to your agent's marketplace.

/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design
/plugin reload

These commands register the skill in your agent environment and enable auto-updates. According to the README install section, this is a one-time setup step.

---

Generating Your First Software Architecture Diagram

Once installed, request an architecture diagram using natural language. The agent loads SKILL.md and automatically routes to the Architecture type reference defined in skills/diagram-design/SKILL.md around line 85.

Example prompt:

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

The agent responds with:

• Selected type (Architecture)
• Size, Detail, and Audience settings
• Output file path (my-diagram.html)

---

Understanding the Architecture Type Specification

The Architecture diagram type enforces strict visual rules defined in skills/diagram-design/references/type-architecture.md. These rules ensure editorial quality across all outputs.

Connector Rules (Section 6 of SKILL.md)

• Rounded orthogonal elbows — All edges use quarter-arcs with r=8 radius
• No diagonal lines — Forbidden by the specification
• Bridge/hop primitive — Automatically triggered when connectors overlap

Layout Constraints

All measurements follow a 4-pixel grid system:

• Node dimensions: multiples of 4px
• Gaps and padding: multiples of 4px
• Line thickness: multiples of 4px

This guarantees pixel-perfect alignment across light, dark, and full-editorial variants.

Semantic Patterns vs. Visual Types

When behavior matters—such as tracing a policy flow—Diagram Design first selects a semantic pattern from semantic-patterns.md, then applies the Architecture visual type. This separation preserves meaning while enforcing consistent aesthetics.

---

Brand Onboarding for Corporate Diagrams

Run the onboarding flow to import your corporate identity:

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

This extracts your brand colors and fonts, writing tokens to references/style-guide.md. All subsequent software architecture diagrams automatically apply your corporate palette without manual configuration.

---

Importing Existing Diagram Files

Diagram Design can redraw existing diagrams using the Architecture type, stripping original palettes and normalizing layouts.

From draw.io

/diagram-design:import-drawio path/to/architecture.drawio --size=slide-16x9 --detail=balanced

From Mermaid

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

Both commands accept the four dials that control output tailoring:

Dial	Purpose	Typical Values
Format	Output file type	HTML, SVG, PNG
Size	Canvas dimensions	slide-16x9, a4-portrait, square
Detail	Information density	minimal, balanced, exhaustive
Audience	Styling emphasis	executive, technical, public

These dials are documented in the "four dials" table of the README.

---

Exporting Software Architecture Diagrams

Generated diagrams are self-contained HTML files. Convert them to static assets using the export commands documented in skills/diagram-design/references/export.md.

Export as SVG

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

Export as High-Resolution PNG

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

The --scale parameter multiplies base resolution for print-quality output.

---

Validating Output Quality

Verify accessibility and structural integrity with the bundled validator:

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

A healthy diagram prints OK. This script checks:

• Color contrast ratios (WCAG compliance)
• Geometry validity (no overlapping nodes)
• Motion sanity (for animated variants)

---

Complete Workflow Example

# 1. Install (once)

/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

# 2. Onboard brand (optional)

onboard diagram-design to https://company.com

# 3. Generate architecture diagram

# In agent: "Architecture diagram: API gateway, auth service, user DB, notification queue"

# 4. Import legacy draw.io file and modernize

/diagram-design:import-drawio legacy-system.drawio --size=slide-16x9 --detail=balanced

# 5. Export for presentation

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

# 6. Validate

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

---

Key Source Files Reference

File	Role
skills/diagram-design/SKILL.md	Core skill manifest; routes requests to the Architecture type
skills/diagram-design/references/type-architecture.md	Full Architecture specification (elbow formula, bridge primitive, 4px grid)
skills/diagram-design/references/import-drawio.md	draw.io import procedure with Architecture mapping
skills/diagram-design/references/import-mermaid.md	Mermaid block import and Architecture conversion
skills/diagram-design/references/export.md	SVG/PNG export commands and options
skills/diagram-design/scripts/self_check.py	Output validator for accessibility and geometry
skills/diagram-design/assets/template.html	Base HTML scaffold for all generated diagrams

---

Summary

• Install once via /plugin install to enable Diagram Design in Claude Code, Codex, Factory Droid, or Pi agents
• Request naturally — the skill auto-detects Architecture requests and loads type-architecture.md
• Enforce quality through 4px grid alignment, rounded orthogonal elbows, and automatic bridge primitives
• Import existing draw.io or Mermaid files to modernize legacy diagrams
• Export flexibly to self-contained HTML, SVG, or scaled PNG
• Validate with self_check.py before publishing

---

Frequently Asked Questions

What AI agents support Diagram Design for software architecture?

Diagram Design supports Claude Code, Codex, Factory Droid, and Pi agents. The skill installs via the standard plugin marketplace interface shared across these environments.

Can I customize colors and fonts in architecture diagrams?

Yes. Run onboard diagram-design to <your-site-url> to extract your brand palette and typography. The skill writes tokens to references/style-guide.md and applies them automatically to all future diagrams.

How do I convert an existing Mermaid diagram to Diagram Design format?

Use the import command: /diagram-design:import-mermaid <file> --diagram=all. The skill parses Mermaid syntax, strips the original styling, normalizes the layout to 4px grid alignment, and redraws using the Architecture type specifications from type-architecture.md.

What makes Diagram Design architecture diagrams "editorial quality"?

The Architecture type enforces strict design rules: rounded orthogonal elbows with 8px radius (no diagonals), 4-pixel grid alignment for all elements, automatic bridge/hop primitives for overlapping connectors, and semantic pattern separation. These rules derive from professional editorial standards implemented in SKILL.md section 6 and type-architecture.md.

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