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

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 following the conventions defined in 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 — the main dispatcher that routes "flowchart" requests
2. 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.

Shape	Usage	Source Convention
Oval	Start/end nodes	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

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

The agent processes your request through SKILL.md, loads type-flowchart.md for layout conventions, renders the SVG, and returns 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

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

# 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 with valid SVG elements:

<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 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	Request dispatcher; matches "flowchart" to type-flowchart.md
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	Minimal light-themed scaffold
skills/diagram-design/assets/template-dark.html	Dark mode variant
skills/diagram-design/assets/template-full.html	Full editorial layout
skills/diagram-design/assets/example-flowchart.html	Complete working example
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 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 with standard SVG shapes

The skill's modular architecture—routing through SKILL.md → 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 to determine available diagram types and routes flowchart requests to 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, 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 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.

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