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

> Learn to create stunning software architecture diagrams with Diagram Design. Install the plugin, select Architecture, and export to HTML, SVG, or PNG for editorial quality.

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

---

**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.

```bash
/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](https://github.com/cathrynlavery/diagram-design/blob/main/README.md#install), 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`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) and automatically routes to the **Architecture** type reference defined in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

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

```

This extracts your brand colors and fonts, writing tokens to [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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

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

```

### From Mermaid

```bash
/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md).

### Export as SVG

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

```

### Export as High-Resolution PNG

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

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

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | Core skill manifest; routes requests to the Architecture type |
| [`skills/diagram-design/references/type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-architecture.md) | Full Architecture specification (elbow formula, bridge primitive, 4px grid) |
| [`skills/diagram-design/references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-drawio.md) | draw.io import procedure with Architecture mapping |
| [`skills/diagram-design/references/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md) | Mermaid block import and Architecture conversion |
| [`skills/diagram-design/references/export.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md) | SVG/PNG export commands and options |
| [`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py) | Output validator for accessibility and geometry |
| [`skills/diagram-design/assets/template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) section 6 and [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md).