# How to Generate an Architecture Diagram Using Diagram Design: A Complete Guide

> Learn how to generate an architecture diagram with Diagram Design. Install the skill, prepare your source file, and use simple commands for a clear visualization. Get the complete guide now.

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

---

**You can generate an architecture diagram using Diagram Design by installing the skill into your AI agent, preparing a Mermaid (.mmd) or draw.io source file, and executing the `/import-mermaid` or `/import-drawio` command with the `--type=architecture` flag.**

Diagram Design is a Claude-Code/Factory-Droid skill that transforms structured diagram sources into publication-ready visualizations across 39 supported types. When you need to generate an architecture diagram using Diagram Design, the tool parses your source components, applies architectural layout conventions, and emits self-contained HTML, SVG, or PNG outputs.

## Prerequisites: Installing the Skill

Before generating diagrams, you must install the Diagram Design plugin in your agent environment. The skill resides in the `skills/diagram-design` directory and integrates with Claude Code, Codex, Factory Droid, or Pi.

Install via your agent's plugin marketplace:

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

```

*Reference:* See the installation section in [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md)【/cache/repos/github.com/cathrynlavery/diagram-design/main/README.md#L11-L22】.

## Step-by-Step Workflow to Generate Architecture Diagrams

### Step 1: Prepare Your Source File

Create a source file containing your logical components. Diagram Design accepts either **Mermaid** files (`.mmd` or `.mermaid`) or **draw.io** files (`.drawio`).

For Mermaid, define your architecture using flowchart syntax with subgraphs to represent system zones:

```mermaid
flowchart LR
    subgraph Frontend
        UI[UI]
    end
    subgraph Backend
        API[API]
        DB[(Database)]
    end
    UI --> API
    API --> DB

```

Save this content as `architecture.mmd` in your working directory.

### Step 2: Invoke the Import Command

Use the appropriate import command based on your source format. The system resolves the skill directory automatically—**never assume the skill lives in the current working directory**【/cache/repos/github.com/cathrynlavery/diagram-design/main/commands/import-mermaid.md#L41-L44】.

**For Mermaid sources:**

```bash
import-mermaid architecture.mmd --type=architecture --size=slide-16x9 --detail=balanced --variant=dark

```

**For draw.io sources:**

```bash
import-drawio system.drawio --type=architecture --size=doc-wide --detail=faithful --variant=light

```

The `--type=architecture` flag explicitly sets the diagram type, though the skill can infer architecture from flowcharts containing service boxes and directional arrows.

### Step 3: Retrieve Your Generated Files

By default, the command writes a self-contained HTML file (e.g., [`architecture.html`](https://github.com/cathrynlavery/diagram-design/blob/main/architecture.html)) adjacent to your source file. You can request alternative formats using the `--format` flag:

- `--format=svg` for scalable vector graphics
- `--format=png` for rasterized images
- `--format=html+png` for both formats simultaneously

Non-HTML formats are derived from the HTML base via the export pipeline defined in [`references/export.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/export.md)【/cache/repos/github.com/cathrynlavery/diagram-design/main/commands/export-diagram.md#L30-L31】.

## Understanding the Architecture Rendering Pipeline

### Source Extraction and Digest Creation

When you execute an import command, the skill runs internal extractor scripts—[`scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/mermaid_extract.py) for Mermaid files or [`scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/drawio_extract.py) for draw.io files. These parsers build a **digest** containing nodes, edges, and optional zone definitions.

If extraction fails with a non-zero exit code, the error is reported verbatim to aid debugging【/cache/repos/github.com/cathrynlavery/diagram-design/main/commands/import-drawio.md#L41-L44】.

### Type Inference and Style Application

The digest's "type candidates" field ranks possible diagram types based on content structure. Architecture diagrams are selected when the grammar matches service-oriented patterns, though you can override this with explicit flags.

The **Architecture** layout conventions defined in [`skills/diagram-design/references/type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-architecture.md) enforce:
- **Orthogonal connectors** with rounded right-angle bends (mandatory per the style guide)【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/type-architecture.md#L14-L16】
- **Zone rectangles** for grouping related components
- **Bridge/hop primitives** for intersecting lines

### Output Generation and Fidelity Reporting

After rendering, the command prints a **fidelity ledger** showing what elements were merged, collapsed, or dropped during the transformation. This transparency helps you assess how closely the output matches your source intent【/cache/repos/github.com/cathrynlavery/diagram-design/main/commands/import-mermaid.md#L49-L52】.

## Programmatic Usage: Direct Python Invocation

For advanced workflows, invoke the extractor directly from Python without the CLI wrapper:

```python
import subprocess
import pathlib

skill_dir = pathlib.Path(__file__).parent / "skills" / "diagram-design"
mermaid_src = pathlib.Path("architecture.mmd")

cmd = [
    "python", str(skill_dir / "scripts" / "mermaid_extract.py"),
    "--input", str(mermaid_src),
    "--type", "architecture",
    "--size", "slide-16x9",
    "--detail", "balanced",
    "--variant", "dark"
]

subprocess.run(cmd, check=True)

```

This approach writes the output HTML to the same directory as your input source file.

## Key Configuration Files

The following files govern architecture diagram generation in the `cathrynlavery/diagram-design` repository:

| File | Purpose |
|------|---------|
| [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) | CLI specification, flags (`--type`, `--size`, `--detail`), and required behavior for Mermaid sources |
| [`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md) | CLI specification for draw.io import workflows |
| [`skills/diagram-design/references/type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-architecture.md) | Comprehensive style guide covering layout conventions, connector rules, and zone handling |
| [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) | Parser that converts Mermaid syntax into the internal digest format |
| [`skills/diagram-design/scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py) | Parser handling compressed draw.io formats |

## Summary

- **Diagram Design** is an AI agent skill that converts Mermaid or draw.io sources into high-quality architecture diagrams.
- Use **`/import-mermaid`** or **`/import-drawio`** commands with **`--type=architecture`** to trigger the rendering pipeline.
- The system enforces **rounded right-angle connectors** and orthogonal layouts as mandatory architectural standards.
- Output defaults to HTML but supports SVG and PNG via the export pipeline.
- The **fidelity ledger** provides transparency about structural transformations applied to your source.

## Frequently Asked Questions

### What file formats does Diagram Design support for architecture diagrams?

Diagram Design accepts **Mermaid** files (`.mmd` or `.mermaid`) and **draw.io** files (`.drawio`) as input sources. The output can be generated as self-contained HTML, SVG, PNG, or a combination of HTML and PNG formats.

### Can I override the automatic diagram type detection?

Yes. While the skill infers diagram types from content patterns (such as service boxes and arrows for architecture), you can explicitly set the type using the **`--type=architecture`** flag in your import command【/cache/repos/github.com/cathrynlavery/diagram-design/main/commands/import-mermaid.md#L25-L27】.

### Where are the generated files saved?

By default, the skill writes output files (e.g., [`architecture.html`](https://github.com/cathrynlavery/diagram-design/blob/main/architecture.html)) to the same directory as your source file. You can specify alternative formats like SVG or PNG using the `--format` flag, which derives the final output from the HTML base.

### How do I customize the visual style of the architecture diagram?

Customize the output using three dial parameters: **`--size`** (e.g., `slide-16x9`, `doc-wide`), **`--detail`** (e.g., `balanced`, `faithful`), and **`--variant`** (e.g., `dark`, `light`). The specific architectural styling—including orthogonal connectors and zone rectangles—is governed by the rules in [`references/type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/type-architecture.md).