# How to Set Up Diagram Design Locally: A Complete Installation Guide

> Install Diagram Design locally to generate diagrams offline. Clone the repo, register with your agent, and verify the installation with the HTML gallery.

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

---

**Clone the repository, register the local checkout with your agent (Pi or Claude Code), and verify the install by opening the bundled HTML gallery to start generating diagrams offline.**

Diagram Design is a self-contained AI skill for creating editorial-quality diagrams. Setting it up locally lets you customize the style guide, add new diagram types, and integrate the skill into private CI pipelines. This guide walks through the complete local installation process using the official `cathrynlavery/diagram-design` repository.

## Prerequisites and Repository Overview

Diagram Design lives under `skills/diagram-design/` and uses a **progressive disclosure** architecture—only files required for the current request load at runtime, minimizing memory footprint.

| Component | Purpose | Location |
|-----------|---------|----------|
| **Skill core** | Entry point routing requests to diagram types | [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) |
| **References** | Color tokens, fonts, semantic patterns, animation contracts | `skills/diagram-design/references/` |
| **Assets** | HTML templates and offline preview gallery | `skills/diagram-design/assets/` |
| **Scripts** | Utilities for draw.io/Mermaid extraction, versioning, screenshots | `scripts/` |
| **CI/Docs** | ADRs, screenshots, workflow validations | `docs/adr/`, `.github/workflows/` |

A simple flowchart request loads only [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) plus [`references/type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/type-flowchart.md), keeping the agent responsive.

## Step 1: Clone the Repository

Start with a local checkout of the full repository:

```bash
git clone https://github.com/cathrynlavery/diagram-design.git ~/code/diagram-design

```

This gives you access to all 38 diagram types, the style guide, and helper scripts.

## Step 2: Register with Your Agent

The registration method depends on which AI host you're using.

### Pi Installation

Tell Pi to treat the folder as a local package:

```bash
pi install ~/code/diagram-design

```

### Claude Code Installation

Create a symlink so the skill appears in Claude's skill directory:

```bash
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design

```

After creating the symlink, **restart Claude Code** or run the host-specific reload command to discover the new skill.

## Step 3: Verify the Local Setup

Open the bundled gallery to confirm all HTML assets are accessible:

```bash

# macOS

open skills/diagram-design/assets/index.html

# Linux

xdgd-open skills/diagram-design/assets/index.html

```

The gallery displays **38 diagram types** across three visual variants: light, dark, and full-editorial. If the page loads correctly, your local Diagram Design setup is functional.

## Step 4: Customize the Style Guide (Optional)

Edit [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) to replace default color and font tokens with your brand's palette:

```bash

# Edit the style guide

code skills/diagram-design/references/style-guide.md

```

Changes take effect immediately for newly generated diagrams—no restart required.

## Using Diagram Design Locally

### Generate Diagrams from Command Line (Pi)

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

```

### Use Slash Commands in Claude Code or Codex

```text
/diagram-design:make

```

Then enter a natural language request:

> "I need a quadrant showing Q2 projects by impact vs effort."

The agent selects the *quadrant* type, applies default size/detail settings, and returns a self-contained HTML file.

### Import and Re-render draw.io Files

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

```

The command uses [`scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/drawio_extract.py) to parse the draw.io IR and produce a fresh diagram following your current style guide.

### Export to SVG and PNG

```bash

# SVG only

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

# High-resolution PNG

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

```

PNG export requires Playwright. Run this once:

```bash
pip install playwright && playwright install chromium

```

## Key Files for Local Development

| File | Role |
|------|------|
| [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | Main routing logic and type-selection guide |
| [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) | Single source of truth for brand tokens |
| [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md) | Behavioral patterns independent of visual layout |
| [`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md) | Motion and accessibility contracts |
| `skills/diagram-design/references/type-*.md` | One file per diagram type (e.g., [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md), [`type-quadrant.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-quadrant.md)) |
| [`skills/diagram-design/assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/index.html) | Live gallery for offline preview |
| [`scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/drawio_extract.py) | Parses draw.io files to structured IR |
| [`scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/mermaid_extract.py) | Parses Mermaid source to same IR |
| [`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py) | Runtime validator for generated diagrams |

## Running CI Checks Locally

The repository includes a full CI pipeline in [`.github/workflows/ci.yml`](https://github.com/cathrynlavery/diagram-design/blob/main/.github/workflows/ci.yml) that validates geometry, accessibility, and consistency. You can run checks manually:

```bash
python skills/diagram-design/scripts/self_check.py path/to/generated-diagram.html

```

This ensures your customizations don't break existing diagram types.

## Summary

- **Clone** the repository to `~/code/diagram-design` or your preferred path
- **Register** with Pi via `pi install` or with Claude Code via symlink to `~/.claude/skills/`
- **Verify** by opening [`skills/diagram-design/assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/index.html) to see all 38 diagram types
- **Customize** brand tokens in [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) for immediate effect
- **Generate** diagrams via natural language, slash commands, or file imports
- **Validate** changes using the built-in [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) script

## Frequently Asked Questions

### Can I run Diagram Design without an AI agent?

No. Diagram Design is implemented as an AI skill that requires a compatible host (Pi, Claude Code, Codex, or Factory Droid) to interpret [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) and route requests. The local setup gives you control over the skill's files, but you still need an agent to execute generation commands.

### How do I add a new diagram type?

Create a new file in `skills/diagram-design/references/` following the naming convention `type-{yourtype}.md`. Model it after existing type files like [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md). Include the diagram's purpose, use cases, data schema, and example prompts. The skill automatically discovers new types at runtime.

### Will local changes survive a `git pull`?

Yes, with caveats. Your modifications to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) and new type files will persist unless they conflict with upstream changes. Stash or commit your customizations before pulling updates, then reapply them. Consider maintaining a fork with your brand-specific overrides in a separate branch.

### Does the local setup support team collaboration?

Yes. Since Diagram Design is a standard Git repository, you can fork it, apply team-specific customizations, and share the fork internally. Team members clone your fork instead of the upstream repo. The CI workflows in [`.github/workflows/ci.yml`](https://github.com/cathrynlavery/diagram-design/blob/main/.github/workflows/ci.yml) run on any clone, enforcing consistency standards across your organization.