# How to Create a Flowchart Using Diagram-Design: A Complete Guide

> Learn to create a flowchart using diagram-design. Follow this guide to generate flowcharts with AI or by editing HTML templates. Get started easily today.

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

---

**To create a flowchart using diagram-design, request one through a supported AI agent (Claude Code, Codex, or Pi) with a natural language prompt, or manually edit the HTML scaffold in [`assets/template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template.html) following the conventions defined in [`references/type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/type-flowchart.md).**

The **diagram-design** repository by Cathryn Lavery is an **Agent Skill** that generates clean, editorial-quality diagrams. When you ask for a flowchart, the system loads only the files it needs—keeping the runtime footprint minimal while producing accessible, export-ready visualizations.

---

## How the Flowchart Skill Works

The flowchart generation follows a **lazy-loading architecture** that pulls exactly three files per request:

1. **[`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md)** — the main dispatcher that routes "flowchart" requests
2. **[`references/type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/type-flowchart.md)** — the visual grammar and layout rules
3. **`assets/template*.html`** — the HTML scaffold (light, dark, or full-editorial theme)

Optional **brand onboarding** replaces default colors with tokens from [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md).

| Shape | Usage | Source Convention |
|-------|-------|-------------------|
| Oval | Start/end nodes | [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md) shape palette |
| Rectangle | Process steps | Standard flow element |
| Diamond | Decision points | Branching logic indicator |

The resulting output is a **self-contained HTML file** with an embedded SVG featuring ARIA `role="img"` and proper `<title>`/`<desc>` elements for accessibility.

---

## Method 1: Request a Flowchart from an AI Agent

The fastest way to **create a flowchart using diagram-design** is through a supported agent.

### Claude Code, Codex, or Pi Prompt

```text
Make me a flowchart of my onboarding funnel:
- Sign-up page → Email verification → Profile setup → Dashboard

```

The agent processes your request through [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), loads [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md) for layout conventions, renders the SVG, and returns [`onboarding-flowchart.html`](https://github.com/cathrynlavery/diagram-design/blob/main/onboarding-flowchart.html).

---

## Method 2: Export and Convert Your Flowchart

Once you have an HTML flowchart, use the **export commands** to extract SVG or generate PNG files.

### Using the Pi Slash-Command

```bash

# Extract raw SVG

/export-diagram path/to/onboarding-flowchart.html --svg-only

# Generate high-resolution PNG

/export-diagram path/to/onboarding-flowchart.html --png-only --scale=3

# Export both formats

/export-diagram path/to/onboarding-flowchart.html

```

These commands use **Playwright** to rasterize the diagram. See the *Export* section in [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) (lines 74-88) for full details.

---

## Method 3: Build a Flowchart Manually from Template

For full control, copy the HTML scaffold and edit the SVG directly.

### Step-by-Step Manual Creation

```bash

# Clone the repository

git clone https://github.com/cathrynlavery/diagram-design.git
cd diagram-design

# Copy the minimal light template

cp skills/diagram-design/assets/template.html my-flowchart.html

```

### SVG Structure to Insert

Replace the comment `"Replace with your content."` in [`my-flowchart.html`](https://github.com/cathrynlavery/diagram-design/blob/main/my-flowchart.html) with valid SVG elements:

```html
<svg width="400" height="400" viewBox="0 0 400 400">
  <!-- Arrow marker definition (already in template) -->
  
  <!-- Start node: oval -->
  <ellipse cx="200" cy="80" rx="40" ry="20" 
           fill="var(--color-paper)" 
           stroke="var(--color-ink)"/>
  <text x="200" y="85" text-anchor="middle" 
        font-family="var(--font-sans)" font-size="14">Start</text>
  
  <!-- Arrow down -->
  <path d="M200 100 L200 140" 
        marker-end="url(#arrow-accent)" 
        stroke="var(--color-accent)" 
        stroke-width="2"/>
  
  <!-- Process step: rectangle -->
  <rect x="150" y="140" width="100" height="40" 
        fill="var(--color-paper)" 
        stroke="var(--color-ink)"/>
  <text x="200" y="165" text-anchor="middle" 
        font-family="var(--font-sans)" font-size="14">Process</text>
  
  <!-- Arrow down -->
  <path d="M200 180 L200 220" 
        marker-end="url(#arrow-accent)" 
        stroke="var(--color-accent)" 
        stroke-width="2"/>
  
  <!-- Decision: diamond -->
  <polygon points="200,220 240,260 200,300 160,260" 
           fill="var(--color-paper)" 
           stroke="var(--color-ink)"/>
  <text x="200" y="265" text-anchor="middle" 
        font-family="var(--font-sans)" font-size="12">Decision?</text>
</svg>

```

Open [`my-flowchart.html`](https://github.com/cathrynlavery/diagram-design/blob/main/my-flowchart.html) in any browser to preview. The **CSS custom properties** (`--color-paper`, `--color-ink`, `--color-accent`, `--font-sans`) ensure consistent theming.

---

## Key Configuration Files

Understanding these files helps you customize and debug flowchart generation:

| File Path | Purpose |
|-----------|---------|
| [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | Request dispatcher; matches "flowchart" to [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md) |
| [`skills/diagram-design/references/type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-flowchart.md) | **Visual grammar**: oval/rectangle/diamond semantics, top-to-bottom flow rules, anti-patterns |
| [`skills/diagram-design/assets/template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template.html) | Minimal light-themed scaffold |
| [`skills/diagram-design/assets/template-dark.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-dark.html) | Dark mode variant |
| [`skills/diagram-design/assets/template-full.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-full.html) | Full editorial layout |
| [`skills/diagram-design/assets/example-flowchart.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-flowchart.html) | Complete working example |
| [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) | Brand tokens (post-onboarding) |

The **default color palette** (defined in the templates) uses:
- Paper: `#f5f5f5`
- Ink: `#2d3142`  
- Accent: `#eb6c36`

---

## Design Rules from type-flowchart.md

When creating or editing flowcharts manually, follow these **layout conventions**:

- **Flow direction**: Top-to-bottom, left-to-right for branches
- **Shape meaning**: Never use color alone to convey information—shape carries semantic weight
- **Accent usage**: Reserve the accent color (`#eb6c36` by default) for primary paths and arrows
- **Anti-patterns**: Avoid crossing lines; use consistent spacing between nodes

The [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md) reference enforces these rules when agents generate diagrams automatically.

---

## Summary

**Creating a flowchart using diagram-design** works three ways:

- **Agent-driven**: Natural language request to Claude Code, Codex, or Pi
- **Export pipeline**: HTML → SVG/PNG via slash-commands
- **Manual construction**: Edit [`assets/template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template.html) with standard SVG shapes

The skill's **modular architecture**—routing through [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) → [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md) → templates—keeps generation fast and maintainable. All outputs are **accessible, self-contained HTML** with clean SVG internals ready for documentation or presentation use.

---

## Frequently Asked Questions

### Which agents support the diagram-design flowchart skill?

Claude Code, GitHub Copilot/Codex, and Pi can access the skill when the `skills/diagram-design/` folder is present in your environment. The agent reads [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) to determine available diagram types and routes flowchart requests to [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md) automatically.

### Can I use diagram-design without an AI agent?

Yes. Copy any template from `assets/template*.html`, manually construct your SVG using the shape conventions in [`references/type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/type-flowchart.md), and open the file in a browser. No build step or agent is required for static diagram creation.

### How do I apply my brand colors to flowcharts?

Run the **onboarding flow** once to generate [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) with your tokens. On subsequent requests, the skill substitutes your brand colors and fonts for the defaults. Without onboarding, diagrams use the neutral palette: paper `#f5f5f5`, ink `#2d3142`, accent `#eb6c36`.

### What export formats are available?

Diagram-design outputs **self-contained HTML** natively. Use `/export-diagram` with `--svg-only` to extract the raw SVG markup, or `--png-only --scale=N` to generate raster images at 1x, 2x, or higher resolutions via Playwright.