Skip to content

Editorial diagram design for Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, Qoder, and Pi. 45 diagram types. Self-contained HTML + SVG. No shadows. No Mermaid slop.

13.2 KB
Raw Blame

Diagram Design cookbook

Operator recipes for this repository. The design system still lives in skills/diagram-design/SKILL.md; this file is the runbook: what to say, which files to load, and which commands to run.

Use it from an editable clone (this checkout). Managed marketplace installs can still follow the recipes, but do not edit references/style-guide.md inside a package that updates will replace — save a client profile instead.


Map

I want to… Jump
Wire this clone into Claude, Codex, Cursor, Cline, Kiro, OpenCode, or Copilot R0
Confirm Python, Playwright, PNG export R1
Draw the first diagram in a real project R2
Match a brand R3
Choose type / pattern / size without rereading the whole skill R4
Browse shipped examples R5
Redraw draw.io or Mermaid R6
Hand off SVG or PNG R7
Check a generated HTML file R8
Paste a request to an agent R9

R0. Editable install

The canonical skill root is skills/diagram-design/ (SKILL.md + references/ + assets/). Point skill hosts at that inner directory. Pi and the repository's native marketplace packages are the exceptions because they already resolve the skills/ directory from the repository root.

This repository does not duplicate SKILL.md into host-specific loader stubs. For an editable install, symlink or junction the canonical inner directory into one discovery root used by your host.

Host matrix

Host How it finds the skill What you do
Claude Code Marketplace plugin, ~/.claude/skills/, or project .claude/skills/ Use /plugin install for managed updates or link the inner skill for editable work.
Codex Marketplace plugin or ~/.agents/skills/ Use the marketplace for managed updates or link the inner skill for editable work.
Cursor ~/.cursor/skills/, ~/.agents/skills/, project .cursor/skills/, or project .agents/skills/ Link the inner skill, then ask in Agent chat.
Cline CLI / VS Code ~/.cline/skills/, ~/.agents/skills/, workspace .cline/skills/, or workspace .agents/skills/ Link the inner skill and enable it from the Skills view when needed.
Kiro Workspace .kiro/skills/ or global ~/.kiro/skills/ Link the inner skill, or import its GitHub subdirectory URL; imported skills are copied and must be re-imported to update.
OpenCode Project .opencode/skills/ or global ~/.config/opencode/skills/ Link or copy the inner skill; copied installs must be replaced to update.
GitHub Copilot Marketplace plugin; project .github/skills/, .agents/skills/, or .claude/skills/; user ~/.copilot/skills/, ~/.agents/skills/, or ~/.claude/skills/ Use the marketplace for managed updates or link the inner skill for editable work.

Marketplace installs (Claude /plugin, copilot plugin install, codex plugin add, droid plugin install) stay the right path if you do not need to edit style-guide.md in-tree. Use profiles instead. For the hosts in the matrix that have no marketplace package, npx skills add cathrynlavery/diagram-design does the same job in one command - it installs the inner skill into every root you select, symlinking them to one canonical copy by default and copying independently under --copy. That install is standalone: it belongs to the CLI rather than to your checkout or to any marketplace, so it does not follow marketplace updates automatically. Refresh it with npx skills update diagram-design.

Unix (user-global inner skill)

git clone https://github.com/cathrynlavery/diagram-design.git ~/code/diagram-design
DIAGRAM_SKILL=~/code/diagram-design/skills/diagram-design
mkdir -p ~/.claude/skills ~/.cursor/skills ~/.agents/skills ~/.cline/skills \
  ~/.kiro/skills ~/.config/opencode/skills ~/.copilot/skills
ln -s "$DIAGRAM_SKILL" ~/.claude/skills/diagram-design
ln -s "$DIAGRAM_SKILL" ~/.cursor/skills/diagram-design
ln -s "$DIAGRAM_SKILL" ~/.agents/skills/diagram-design
ln -s "$DIAGRAM_SKILL" ~/.cline/skills/diagram-design
ln -s "$DIAGRAM_SKILL" ~/.kiro/skills/diagram-design
ln -s "$DIAGRAM_SKILL" ~/.config/opencode/skills/diagram-design
ln -s "$DIAGRAM_SKILL" ~/.copilot/skills/diagram-design

Create only the destinations for the hosts you use. When a host scans both its native root and .agents/skills/, choose one so it does not discover the same skill twice.

Windows (directory junction — not a file symlink)

$src = "E:\diagram-design\skills\diagram-design"
foreach ($t in @(
  "$env:USERPROFILE\.claude\skills\diagram-design",
  "$env:USERPROFILE\.cursor\skills\diagram-design",
  "$env:USERPROFILE\.agents\skills\diagram-design",
  "$env:USERPROFILE\.cline\skills\diagram-design",
  "$env:USERPROFILE\.kiro\skills\diagram-design",
  "$env:USERPROFILE\.config\opencode\skills\diagram-design",
  "$env:USERPROFILE\.copilot\skills\diagram-design"
)) {
  $parent = Split-Path $t -Parent
  if (-not (Test-Path $parent)) { New-Item -ItemType Directory -Path $parent -Force | Out-Null }
  if (-not (Test-Path $t)) { cmd /c mklink /J "$t" "$src" }
}

Replace E:\diagram-design with your clone path. If a junction already exists, leave it; do not copy the skill over a managed plugin folder.

Pi still registers the repo root: pi install <clone-path>.


R1. Doctor

Ask in any host: run diagram-design doctor or /diagram-design:doctor / /doctor.

The procedure is references/doctor.md. It must not install packages. Typical local setup for PNG export:

python -m pip install playwright
python -m playwright install chromium

On Windows, python is the usual interpreter; the skill also accepts python3 when that is what the host has.


R2. First diagram in a project

Work in the project that will own the HTML, not inside skills/diagram-design/assets/ unless you are contributing an example.

  1. Style-guide gate (SKILL.md §0). If the working copy is still shipped defaults (paper #f5f5f5, ink #2d3142, accent #bf4520), the agent must pause and offer onboarding, a profile, or an explicit default. Skip the gate when a valid .diagram-design marker selects a profile (including profile: default).
  2. Confirm before drawing (SKILL.md §3): visual type, optional semantic pattern, size preset, and what the complexity budget will cut.
  3. Load the matching references/type-*.md before writing SVG. If a semantic pattern applies, load semantic-patterns.md first.
  4. Write a self-contained HTML file in the project (for example docs/diagrams/<name>.html). Do not silently overwrite gallery examples.
  5. Run the pre-output checklist (SKILL.md §9). Orthogonal connectors, 4px grid, ≤9 nodes unless you split, accent on ≤2 focals.

Marker file at the project root, entire file:

profile: <slug>

See profiles.md. Profiles live in ~/.diagram-design/profiles/, not in this clone.


R3. Onboard a skin

Full flow: onboarding.md.

Say one of:

  • Onboard diagram-design to https://example.com
  • Extract diagram-design tokens from the local design-system folder <path>
  • Use these tokens: paper … ink … accent … (manual)
  • Proceed with the default skin (optionally write profile: default with consent)

Then: propose the style-guide diff, wait for approval, write references/style-guide.md or save a named profile and point the project marker at it. Prefer profiles when this clone is shared or when plugin updates would clobber a customized working copy.


R4. Selection cheat sheet

Do not duplicate the 40-type table here. Open SKILL.md §3 and pick one layout grammar.

Behavior first (then nearest type):

If the story is… Pattern → type
Fan-in, queues, bottlenecks Fan-in queue → Data flow
Repeated stage slots Stage framework → Process
Messy input becomes a durable artifact Unstructured → structured → Data flow
Two policy traces, first divergence Paired traces → Flowchart
Trust boundaries / paved road Secure paved road → Architecture
Controls by enforcement layer Governance catalog → Layer stack
Compensating defenses, residual risk Compensating layers → Layer stack

Hard stops: if a table or paragraph is clearer, do not draw. If you are over the complexity budget (9 nodes / 12 arrows as the default ceiling), split overview + detail.

Size (output-spec.md): doc-inline for docs, slide-16x9 for decks, social-og for cards, fit for Figma SVG. Size changes type ramp, not just viewBox.

Motion: default is static. Load animation.md only when the user asked for motion or ordered change is otherwise unclear.


R5. Gallery and templates

From the clone root:

# macOS / Linux
open skills/diagram-design/assets/index.html
xdg-open skills/diagram-design/assets/index.html

# Windows
start skills/diagram-design/assets/index.html

Copy a scaffold, then replace the SVG:

cp skills/diagram-design/assets/template.html my-diagram.html
cp skills/diagram-design/assets/template-full.html my-diagram.html
cp skills/diagram-design/assets/template-motion.html my-diagram.html

Shipped examples are assets/example-<type>.html plus -dark and -full variants. Treat them as specimens, not scratch files.


R6. Import

Load import-drawio.md, import-mermaid.md, or import-excalidraw.md and set the four dials before redrawing (output-spec.md):

Dial Typical values
Format html · svg · png · html+png
Size doc-inline · slide-16x9 · social-og · fit · …
Detail faithful · balanced · simplified
Audience engineer · mixed · executive

Slash forms (Claude): /diagram-design:import-drawio <file>, /diagram-design:import-mermaid <file-or-md>, and /diagram-design:import-excalidraw <file>. Always report a fidelity ledger (merged, collapsed, dropped). Source coordinates, source palette, Mermaid auto-layout, and Excalidraw hand-drawn geometry do not carry over.

Extractors in this checkout: skills/diagram-design/scripts/drawio_extract.py, mermaid_extract.py, excalidraw_extract.py.


R7. Export

Never export unprompted. Procedure: export.md.

  • SVG: first <svg> only, XML-escaped Google Fonts @import, diagram-only (no full-page cards).
  • PNG: Playwright screenshot of that SVG box, transparent background. Motion HTML: ?motion=static, wait for document.fonts.ready, data-frame="static".
/diagram-design:export-diagram path/to/diagram.html
/diagram-design:export-diagram path/to/diagram.html --png-only --scale=2

R8. Taste and geometry gates

After generating HTML in this clone (examples or a file you are contributing):

python skills/diagram-design/scripts/self_check.py path/to/diagram.html
python scripts/lint-skin.py path/to/diagram.html
python scripts/verify-geometry.py path/to/diagram.html

Full contributor gates: CONTRIBUTING.md. Docs/routing: python scripts/verify-docs-sync.py.


R9. Prompt pack

Copy and fill. Keep one type, one size, one destination.

Architecture (docs):

Draw an architecture diagram of [system]. Nodes: [list ≤9]. Focal: [1–2]. Size doc-inline, format HTML. Use the diagram-design skill. Confirm type and cuts before drawing. Save to [path].html.

Deck:

Redraw [file].drawio for a 16:9 slide, detail simplified, audience executive, format PNG.

Mermaid in a README:

Import every Mermaid block in [file].md, size doc-wide, detail balanced, audience mixed. Report the fidelity ledger.

Brand, then diagram:

Onboard diagram-design from https://[site]. If I approve the tokens, save profile [slug] and write .diagram-design with profile: [slug]. Then draw [type] of [topic].

Do not:

Make it look like Mermaid / add shadows / coral every box / diagonal connectors / more than nine nodes in one figure.


Pointers

Topic File
Philosophy, types, checklist SKILL.md
Tokens style-guide.md
Settled design decisions docs/adr/
Maintainer validation CONTRIBUTING.md