# Diagram Design **Editorial diagrams your designer won't hate.** ![Content site architecture](docs/screenshots/architecture.png) ![The self-improving loop](docs/screenshots/loop.png) *New in 2.0 — the Loop: flywheels with a shared-memory hub. The dashed lines are the write-backs.* 27 types. One agent skill for Claude Code, Codex, and Pi. Your brand in 60 seconds — the skill reads your website and maps colors + fonts to every diagram. No Figma. No generic rounded boxes. No 30-minute color-picking sessions. --- ## Why I built it I write at [littlemight.com](https://littlemight.com?utm_source=diagram-design&utm_medium=readme&utm_campaign=github&utm_content=intro) (and run [BestSelf.co](https://bestself.co?utm_source=diagram-design&utm_medium=readme&utm_campaign=github&utm_content=intro) on the side). Every time I needed a diagram — an architecture sketch, a flowchart, a pyramid of what matters most — I'd ask Claude and get back a generic rounded-box thing that looked nothing like the rest of the site. I'd either fight with Figma for 30 minutes or just skip the diagram. So I built a Claude Code skill for it. Twenty-seven types, editorial quality, matches your brand in 60 seconds by reading your website. > *The highest-quality move is usually deletion.* Every node earns its place. The accent color is reserved for the 1–2 things the reader should look at first. Target density: 4/10. --- ## What it makes All 27 diagrams ship in three variants: minimal light, minimal dark, and full-editorial. Open any of them directly in a browser — no build step, no JS, no external images.

Architecture _{Components + connections}	Flowchart _{Decision logic}	Sequence _{Messages over time}
State machine _{States + transitions}	ER / data model _{Entities + fields}	Timeline _{Events on an axis}
Swimlane _{Cross-functional flow}	Quadrant _{Two-axis positioning}	Nested _{Hierarchy by containment}
Tree _{Parent → children}	Org chart _{Ownership + routing}	Venn _{Set overlap}
Layer stack _{Stacked abstractions}	Pyramid / funnel _{Ranked hierarchy or drop-off}	Consultant 2×2 _{Scenario matrix · named cells}
Radar / Spider _{Multi-axis comparison}	Loop _{Flywheel · stations around a hub}	IT current-state _{Legacy landscape · modernization}
High-Level _{End-to-end stack on a cluster}	Bar chart _{Categorical comparison}	Line chart _{Trends over time}
Gantt _{Tasks and phases on a timeline}	Scatter plot _{Distribution and correlation}	Process _{Multi-actor sequential workflow}
Medallion _{Multi-tier data storage}	Data flow _{Role-scoped pipeline steps}	DP integration _{Sources → core → consumers}
DP security matrix _{Per-role access permissions}

**Browse the live gallery:** open [`skills/diagram-design/assets/index.html`](skills/diagram-design/assets/index.html) in your browser to flip through all 27 diagrams with light / dark / full-editorial tabs. --- ## Install **Pi:** ```bash pi install https://github.com/cathrynlavery/diagram-design ``` Run `/reload` in an open Pi session. Pi makes the skill available for matching diagram requests; use `/skill:diagram-design` to invoke it explicitly. Pi also loads the `/export-diagram` prompt template. **Claude Code:** ``` /plugin marketplace add cathrynlavery/diagram-design /plugin install diagram-design@diagram-design ``` **Claude Cowork:** Customize → Directory → Plugins → **+** → paste `cathrynlavery/diagram-design` → Sync, then install from the Personal list. **Codex:** ``` npx skills add https://github.com/cathrynlavery/diagram-design --skill diagram-design ``` ### Editable install Managed installs are convenient, but changes to `references/style-guide.md` may be replaced by package updates. Clone the repo and install the local path if you plan to customize the style guide: ```bash git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design # Pi: register the checkout as a local package pi install ~/code/diagram-design # Claude Code: symlink the inner skill ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design ``` The shared skill lives at `skills/diagram-design/`. Pi discovers it through the repo's standard `skills/` package directory; Claude Code, Codex, and other Agent Skills-compatible tools use the same files. --- ## Onboarding — make it look like *your* brand The whole point: ship editorial-quality diagrams in **your** colors and typography, not a generic template. Out of the box, diagrams render in a clean **jet-black + atomic-tangerine** palette (white-smoke paper, jet-black ink, atomic-tangerine accent, blue-slate muted, silver hairlines). Good enough to screenshot straight away. But 60 seconds of onboarding is better — the skill will pull your brand from your website and apply it across every diagram. ### The flow ``` You: "onboard diagram-design to https://yoursite.com" Agent: → fetches the homepage → extracts the dominant palette + font stack → maps detected values to semantic roles: paper, ink, muted, accent, link → shows a proposed diff → writes your tokens to references/style-guide.md You: "yes, apply it" ``` Every new diagram now uses your colors. Your website's paper color becomes the diagram background. Your CTA color becomes the focal accent. Your body font stack becomes the node label family. ### What gets extracted | Detected from your site | Becomes | |---|---| | `` background | `paper` token | | Primary text color | `ink` token | | Secondary / caption text | `muted` token | | Cards or containers | `paper-2` token | | Most-used brand color (CTA, link, heading) | `accent` token | | `

` / `` font | `sublabel` font |

### Contrast checks happen automatically

Before writing tokens, the skill verifies WCAG AA contrast on `ink` over `paper`. If your site has a color that fails contrast at diagram sizes (9–12px), it proposes an adjusted value and explains why.

### Manual override

Prefer to set tokens by hand? Open [`skills/diagram-design/references/style-guide.md`](skills/diagram-design/references/style-guide.md) and edit the table. Everything downstream reads from there — all 27 diagrams, the annotation primitive, and the gallery all inherit semantic role names (`accent`, not `#eb6c36`).

### First-run gate

The skill won't silently ship default-skinned diagrams into a branded project. On first use in a new project, it checks if `style-guide.md` has been customized. If not, it pauses and asks:

> *"This is your first diagram in this project. The style guide is still at the default. Want to run onboarding, paste tokens manually, or proceed with default?"*

See [`skills/diagram-design/references/onboarding.md`](skills/diagram-design/references/onboarding.md) for the full spec.

---

## Quickstart

```bash
# From a cloned checkout, open the gallery to see all 27 diagrams
open skills/diagram-design/assets/index.html       # macOS
xdg-open skills/diagram-design/assets/index.html  # Linux

# In Claude Code, Codex, or Pi, ask:
# "Make me an architecture diagram of my app: frontend, backend, database, Redis cache."
# "I need a quadrant showing Q2 projects by impact vs effort."
# "Give me a sequence of a bearer call with token refresh on 401."
# (branching refresh uses the ALT combined-fragment grammar in type-sequence.md;
#  see skills/diagram-design/assets/example-sequence-oauth.html — not a full authorize-code handshake)
```

Your agent will pick the right type, build the HTML, and save it. You can also start from a template directly:

```bash
cp skills/diagram-design/assets/template.html my-diagram.html        # minimal light
cp skills/diagram-design/assets/template-full.html my-diagram.html   # editorial with summary cards
```

---

## Export to PNG / SVG

Diagrams ship as self-contained HTML, but you can export the diagram itself for Figma, slides, or social cards. Use the slash command for your agent:

**Pi:**

```
/export-diagram path/to/diagram.html
/export-diagram path/to/diagram.html --svg-only
/export-diagram path/to/diagram.html --png-only --scale=3
```

**Claude Code:**

```
/diagram-design:export path/to/diagram.html
/diagram-design:export path/to/diagram.html --svg-only
/diagram-design:export path/to/diagram.html --png-only --scale=3
```

Or just ask in natural language:

```
"Export this diagram as SVG and PNG."
"Save my-diagram.html as PNG."
```

- **SVG** — extracts the `