What this SOP solves
diagram-design is an open-source diagram skill pack by cathrynlavery under the MIT license. It reached number 2 on the GitHub weekly trending list for the week of 2026-09-14, with a verified 39,807 stars on 2026-09-15. It is a skill, not a vendor-private tool, that you drop into several AI coding hosts to produce brand-following diagrams.
Its most useful property is the output: a standalone HTML file that opens offline by double-clicking, with no network requests except Google Fonts, brandable to your site's paper, ink, accent, and fonts, and shipped with accessibility (screen readers read the title and description) plus its own validation script.
The boundary is clear: it draws structured, editable diagrams (architecture, flowchart, quadrant, sequence, state, 39 types total) but not illustrations or data visualization. Do not expect line, bar, or heatmaps that map numeric values; its job is to make architecture and flow legible, not data pretty.
It ships as both an Agent Skill and a plugin package, so Claude Code, Codex, Factory Droid, Pi, GitHub Copilot, Kiro, and OpenCode can consume it. But every host updates differently, so the real difficulty is not installation. It is the version-update path and the output boundary, and every section below makes both explicit.
For positioning versus similar tools see AI diagram tool roundup; for its place as a skill framework see AI coding skill framework roundup; the diagram-design project intro is also worth a read.
Install and update commands per host
Normal use needs no extra dependency; only PNG export requires a one-time dependency:
pip install playwright && playwright install chromiumSVG export needs none, so if you only embed in pages or import into Figma, you can skip it.
Pick one host and copy the commands verbatim; the table below is the most practical part of this article.
| Host | Install (verbatim) | Update | Auto-update |
|---|---|---|---|
| Claude Code | /plugin marketplace add cathrynlavery/diagram-design then /plugin install diagram-design@diagram-design | Manually enable auto-update in /plugin Marketplaces; /reload-plugins when prompted | Off by default, enable manually |
| Codex | codex plugin marketplace add cathrynlavery/diagram-design then codex plugin add diagram-design@diagram-design | codex plugin marketplace upgrade diagram-design, new session | Refreshes on start, can pull manually |
| GitHub Copilot | copilot plugin marketplace add cathrynlavery/diagram-design then copilot plugin install diagram-design@diagram-design | copilot plugin marketplace update diagram-design then copilot plugin update diagram-design@diagram-design | Manual |
| Factory Droid | droid plugin marketplace add https://github.com/cathrynlavery/diagram-design then droid plugin install diagram-design@diagram-design --scope user | droid plugin marketplace update diagram-design then droid plugin update diagram-design@diagram-design --scope user, new session | Tracks commits, manual |
| Pi | pi install https://github.com/cathrynlavery/diagram-design, /reload in session | pi update --extensions | No auto refresh at all |
| Kiro | Import subdirectory URL: https://github.com/cathrynlavery/diagram-design/tree/main/skills/diagram-design | Re-import the URL | Copy-based, re-import manually |
| OpenCode | Copy or symlink skills/diagram-design/ to .opencode/skills/diagram-design or ~/.config/opencode/skills/diagram-design | Replace directory manually | No marketplace, manual |
Confirm Copilot discovered the skill with copilot skill list (or /skills in an interactive session). After Pi installs it also loads /export-diagram, /import-mermaid, /import-excalidraw, /profile, and /doctor; invoke explicitly with /skill:diagram-design.
The next sections use Claude Code as the main line because it disables third-party marketplace auto-update by default, the easiest trap. If you run Codex, see Codex harness integration SOP.
First-run gate and brand onboarding
After install, the first time you draw in a project with no customized style guide, the skill will not silently use the default skin. It pauses and asks: "This is the first diagram for this project, and the style guide is still the default. Run onboarding, paste a token manually, or just use the default?" This gate is intentional; it forces you to decide on branding.
If you want diagrams that look like your brand, just say:
onboard diagram-design to https://your-siteIt fetches your homepage, extracts the primary color palette and font stack, maps colors to semantic roles (paper, ink, muted, accent, link, paper-2), shows a proposed diff, and writes references/style-guide.md only after you confirm.
Memorize the mapping: <body> background maps to paper; primary text color maps to ink; secondary or caption text maps to muted; cards or containers map to paper-2; the most-used brand color (CTA, links, headings) maps to accent; <h1> font maps to title; <body> font maps to node-name; <code> or <pre> font maps to sublabel.
Before writing it runs an automatic WCAG AA contrast check: if your brand color fails at 9 to 12px text inside the diagram, it proposes adjusted values and explains why. It also emits a fidelity receipt (sampled URL, exact color roles, font families and weights, font source URLs, any fallbacks). Public-site fonts are used directly and validated after render, never silently swapped for generic system fonts.
Prefer not to run it automatically? Edit the table in skills/diagram-design/references/style-guide.md by hand; everything downstream inherits the semantic role names (write accent, not #eb6c36), so rebranding touches one place.
Drawing and self-check
Draw with plain language; the official examples are safe to copy:
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.You can also start from a template, three options:
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 card
cp skills/diagram-design/assets/template-motion.html my-diagram.html # optional accessible motionThe repo ships a gallery of all 39 types: open skills/diagram-design/assets/index.html locally or view online at cathrynlavery.github.io/diagram-design.
Motion is optional (none, reveal, step, loop), defaulting to none for static, script-free output. Motion HTML may only use the single fixed, audited controller; arbitrary or modified inline scripts, remote resources, CSS @import, and executable attributes like onclick or srcdoc are rejected.
Self-check is the most-skipped step, yet it is where the official "this counts as working" bar lives. Run the bundled checker:
python3 skills/diagram-design/scripts/self_check.py <your-file.html>It must print OK. The official six criteria for "this counts as working" follow; if any fails, it is a bug worth an issue:
- A routine request (for example "draw me a flowchart") loads only
SKILL.mdplus exactly one type reference file, nothing else. - Before drawing, the agent states the type, mode, size, and planned cuts it intends, then renders.
- The artifact is a single
.htmlfile that opens offline by double-clicking, with no network requests except Google Fonts. - A screen reader can read the diagram title and description; under
prefers-reduced-motionit shows a complete static frame. self_check.pyprintsOKon that file.- After brand onboarding, new diagrams use your site's paper, ink, accent, and fonts, and a fidelity receipt names each item.
Export and import
Export finished diagrams for Figma, slides, or social cards. In Claude Code:
/diagram-design:export-diagram path/to/diagram.html
/diagram-design:export-diagram path/to/diagram.html --svg-only
/diagram-design:export-diagram path/to/diagram.html --png-only --scale=3
/diagram-design:export-diagram path/to/diagram.html --registryIn Pi swap the prefix to /export-diagram with identical arguments. SVG extracts the <svg> node and injects Google Fonts to render standalone in browsers, Figma, and Illustrator; PNG rasterizes via Playwright at 2x by default.
Important boundary: both formats contain only the diagram itself; the -full variant's editorial card and header are excluded. For a full-page editorial screenshot use the browser's print-to-PDF or full-page capture. --registry only works on "traceable block decomposition" diagrams, emitting <basename>.registry.json with each block's data-block-* metadata. To export motion HTML, capture the explicit final static frame: open ?motion=static, wait for document.fonts.ready, confirm the motion root carries data-frame="static", then capture.
If you have existing assets, the skill redraws draw.io, Mermaid, and Excalidraw sources into this design system, keeping content and swapping style. Examples:
/diagram-design:import-drawio platform.drawio
/diagram-design:import-drawio platform.drawio --size=slide-16x9 --detail=simplified --audience=executive
/diagram-design:import-mermaid README.md --diagram=all
/diagram-design:import-mermaid architecture.mmd --size=slide-16x9 --detail=simplified
/diagram-design:import-excalidraw whiteboard.excalidraw --size=slide-16x9 --detail=simplifiedSupported inputs: draw.io (.drawio, .drawio.xml, .drawio.png embedded, .drawio.svg, including base64-looking compressed payloads); Mermaid (.mmd, .mermaid, and mermaid code blocks in Markdown); Excalidraw (.excalidraw, .excalidraw.json scene files, but not .excalidraw.png or .excalidraw.svg exports). The Excalidraw path parses text only: no render, no JavaScript, no browser, no network, no click targets.
Import has four knobs: Format (html, svg, png, html+png); Size (doc-inline, doc-wide, slide-16x9, slide-4x3, social-og, social-square, print-a4-landscape, print-letter-landscape, fit); Detail (faithful up to 24 nodes with sections, balanced up to 12, simplified up to 7, downgrading by a fixed ladder: decorations, then duplicates, then leaf clusters, then infrastructure); Audience (engineer, mixed, executive, changing wording not count).
Each import ends with a fidelity ledger, for example:
Detail: balanced · 12 source nodes to 8 drawn
Collapsed: "Token valid?" decision to edge label on Gateway to Auth
Dropped: 1 sticky note ("legacy path, to be retired") to unconnected in source
Kept in full: the request path (Web/Mobile to Gateway to Orders to Postgres)Not inherited: source or renderer coordinates, source colors, source fonts, draw.io's tangled connectors, Mermaid's auto-layout, Excalidraw's hand-drawn geometry. Inherited: components, relationships, groupings, direction.
Multi-client brand isolation
Outsourcers and multi-site owners use brand isolation: onboard a brand once as a named profile, then put a .diagram-design marker file in each client project containing profile: <slug>.
A marked project reads ~/.diagram-design/profiles/<slug>.md directly, so parallel workspaces use different brands without overwriting the shared style-guide.md. The profile library is shared across Claude Code, Codex, Factory Droid, and Pi: use /diagram-design:profile in Claude Code, /profile in Factory Droid or Pi, natural language elsewhere.
Edits to references/style-guide.md can be overwritten by package updates, but saved profiles (~/.diagram-design/profiles/) and projects with a .diagram-design marker are not. For stable style changes use an editable install (next) or a profile plus marker.
The project's docs/cookbook.md gives recipes for editable install, first diagram, brand setup, import, export, validation, and a Windows junction. An editable install is simple:
git clone [email protected]: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 directory
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-designFor other Agent Skills hosts, create the directories you use and symlink them; hosted install is convenient but references/style-guide.md changes may be overwritten by updates.
Pitfall quick reference
This section is the core value of the article. The ten traps below spell out symptom and cause so anyone can save hours.
| # | Trap | Symptom and cause | Fix |
|---|---|---|---|
| 1 | Claude Code disables auto-update for third-party marketplaces | After install, if you do not manually enable auto-update in /plugin Marketplaces, the version stays frozen at old | Enable auto-update right after install; /reload-plugins when prompted |
| 2 | Factory Droid tracks by commit, ignores manifest version | Version number lies; must marketplace update then plugin update and new session | droid plugin marketplace update diagram-design then droid plugin update diagram-design@diagram-design --scope user, new session |
| 3 | Pi has no auto refresh at all | Install and forget means forever old | Manually pi update --extensions |
| 4 | Kiro copies, not links | After import files are copied into .kiro/skills/; new version needs re-import | Re-import the subdirectory URL; custom agents should include skill://diagram-design/**/SKILL.md |
| 5 | OpenCode copy install never auto-updates | No marketplace package; updates only when you replace the directory | Manually copy or symlink the new directory to .opencode/skills/diagram-design |
| 6 | Old npx skills add standalone copy ignores Codex marketplace | Two paths coexist, version chaos | Delete the standalone copy, then reinstall with the two Codex marketplace commands |
| 7 | Custom style-guide.md overwritten by package update | Hosted install reverts on update | Use editable install (clone then local path), or isolate with profile plus .diagram-design marker |
| 8 | PNG export fails the first time | Missing Playwright and Chromium | Run pip install playwright && playwright install chromium first; SVG needs none |
| 9 | Assuming export includes full layout | SVG and PNG export only the diagram; editorial card and header excluded | For full page use browser print-to-PDF or full-page capture |
| 10 | Motion HTML screenshot catches a mid-frame | Captured while animation plays | Open ?motion=static, wait for document.fonts.ready, confirm data-frame="static", then capture |
Closing judgment: which teams should spend the hour? If your diagrams go into outward-facing brand material, are shown to clients, need accessibility, or are exported to Figma or slides repeatedly, diagram-design's branding and self-check pipeline pays for itself. If they are internal sketches pasted into a README where collaborators use Mermaid, Mermaid stays the better deal: zero dependency, plain text, diff-friendly. The decision is not "which is stronger" but "do your diagrams carry a brand and get machine-checked". See diagram-design project intro.
FAQ
Q1: Should I install on Claude Code or Codex?
A1: Pick your primary host. Claude Code has the most users and the fullest docs, but third-party marketplace auto-update is off by default, so you must enable it after install. Codex refreshes the configured Git marketplace on startup, making updates easier; codex plugin marketplace upgrade diagram-design pulls immediately. Both connect; the difference is mainly the update path.
Q2: I already have Mermaid assets, can I bring them in?
A2: Yes. Use /diagram-design:import-mermaid to redraw .mmd, .mermaid, or mermaid code blocks in Markdown into this design system, with knobs like --size, --detail, and --audience, and it emits a fidelity ledger noting merged or dropped nodes. Note it does not inherit source colors or auto-layout, only components, relationships, groupings, and direction.
Q3: Can this run on Windows?
A3: Yes. Claude Code, Codex, Factory Droid, Pi, and other hosts run on Windows with no extra dependency for normal use. PNG export needs pip install playwright && playwright install chromium once. The cookbook also gives a Windows junction recipe for editable installs.
Q4: Why does PNG export report a missing dependency?
A4: Because PNG export needs Playwright plus Chromium, which are not regular dependencies and are only used for PNG. Run pip install playwright && playwright install chromium before the first PNG export. SVG export needs none and can be a temporary workaround.
Q5: If I use it for the very first diagram, will the default skin drag me off brand? A5: No. On the first diagram in a new project, the skill pauses and asks: run onboarding, paste a token manually, or use the default. It will not silently render with the default skin. Once you choose onboarding and point it at your site, new diagrams use your paper, ink, accent, and fonts, with a fidelity receipt naming each item.