Diagram Design
Generate editorial-quality, self-contained HTML + SVG diagrams for Claude Code, Codex, and Pi — no shadows, no Mermaid slop.
Sources show manual-only exports, no auto-installs, read-only doctor, and importers that treat source files as untrusted data without rendering or fetching — a small permission surface. Deductions: SVG export injects a remote fonts.googleapis.com reference (external data flow), publisher unverified, and referenced scripts (e.g. verify-geometry.py) could not be behaviorally reviewed here.
Docs are highly self-consistent with detailed triggers, edge cases, verbatim failure reporting (extractor exit codes), and a doctor self-diagnostic path. Deduction: static review only — script runnability and verifier coverage of key paths were not reproduced, so the score cannot exceed the 10 anchor.
Clear fit/non-fit boundaries across 40 types, semantic-pattern triggers, four output dials, and CJK font fallback. Deduction: typography depends entirely on the Google Fonts CDN, unreachable from mainland China, and the SVG export injects a remote @import — no local fallback; Chinese support covers traditional labels only.
MIT license, version metadata (2.6), layered progressive disclosure, and thorough anti-pattern/limitation lists. Deduction: no visible changelog or explicit maintenance-ownership/update-path evidence; some conventions live in files not attached to this review.
The design system is concretely executable (connector rules, node treatments, budgets) with worked examples and a fidelity-ledger mechanism. Deduction: static review cannot verify representative outputs; no rendered sample content was attached, and comparative benefit over alternatives is claimed but not independently evidenced.
References auditable primary material (fixtures, verifier scripts, tests like test-verify-motion.py, CI mentions) but none executed; coverage and corroboration unverifiable, so below the 5 anchor — key-path reproduction evidence is unavailable in a static read.
- Typography and SVG export depend on the Google Fonts CDN; offline or mainland-China networks will see fallback rendering and inconsistent exports — localize fonts for offline use.
- Verifier scripts (verify-motion.py, lint-skin.py, etc.) are referenced but not executed in this review; run the doctor and bundled tests first to confirm the environment.
- Publisher is unverified and no brand credit was awarded; although importers claim not to execute source content, remain alert to prompt injection in imported files.
What does this skill do, and when should you use it?
Diagram Design is an Agent Skill that produces architecture diagrams, flowcharts, sequence diagrams, Sankey charts, Wardley maps, database schemas, and dozens more as single self-contained HTML files with inline SVG and CSS that open directly in any browser. It ships a skinnable editorial design system whose brand tokens can be extracted from your website in about a minute, and it redraws existing draw.io, Mermaid, or Excalidraw sources at a chosen format, size, detail level, and audience. The core philosophy is deletion: target density 4/10, a hard budget of 9 nodes and 12 arrows per diagram, and a coral accent reserved for 1–2 focal elements. Note the diagram-type count is inconsistent across the repo's own materials (38 in the description, 39 in the README, 40 in SKILL.md), so check your installed version.
It takes a natural-language diagram request (e.g. 'make me an architecture diagram of my app') or an imported .drawio/.mmd/.excalidraw file; selects a semantic pattern first when behavior carries meaning, then a visual type; lays out nodes and connectors on a 4px grid using tokens from the single-source style-guide.md; enforces six mandatory connector rules, a complexity budget, and a pre-output taste gate; and emits one self-contained .html file meeting an accessible-SVG contract (role="img", prefixed title/desc, static frame under prefers-reduced-motion). For imports it runs Python extraction scripts to parse the source into a structured digest, then redraws rather than converts — discarding source coordinates and palette, keeping content, and reporting a fidelity ledger of what was merged, collapsed, or dropped. Diagrams can be exported to SVG/PNG via slash commands or natural language.
- A technical writer generating screenshot-ready architecture or flowchart diagrams that match their blog's palette
- An engineer redrawing an existing .drawio or Mermaid file as a simplified 16:9 slide for executives
- An indie maker onboarding their website's brand colors and fonts onto all diagrams in 60 seconds instead of fighting Figma
- A consultant producing BCG/McKinsey-style 2×2 quadrant matrices (a built-in consultant-special variant)
- A data team drawing data-platform integration topologies, medallion architectures, or per-role permission matrices
- An agency managing multiple clients with named brand profiles switched per project via a .diagram-design marker
What are this skill's strengths and limitations?
- Zero-dependency self-contained HTML output — double-click to open offline, no build step
- Hard design constraints (4px grid, six connector rules, pre-output checklist) reliably suppress the usual AI-diagram sloppiness
- Brand onboarding extracts site palette and fonts with automatic WCAG AA contrast checks and a fidelity receipt
- Accessibility is built in by default: role="img", prefixed title/desc, prefers-reduced-motion static fallback
- Imports are redrawn, not converted — messy source coordinates are discarded, content kept, and a fidelity ledger reported
- Extensive in-repo validation gates: geometric label checks, waterfall/treemap/Sankey numeric-consistency checks, headless Chromium render lint, three-platform CI
- The diagram-type count shifts between 38/39/40 depending on version — documentation is internally inconsistent
- The strict complexity budget (9 nodes, 12 arrows max per diagram) forces manual splitting of large systems into overview + detail diagrams
- PNG export has a one-time Playwright + Chromium dependency (pip install playwright && playwright install chromium)
- The taste is opinionated (Instrument Serif + Geist, no shadows) — teams with different aesthetics or font needs must customize the skin
- Brand onboarding depends on your website exposing clean public colors and fonts; sites without a coherent brand will get weaker results
- The skill targets many hosts (Claude Code/Codex/Pi/Copilot, etc.), but beyond install commands the source gives no evidence of equivalent testing on each host's runtime
How do you install this skill?
Multiple hosts are supported. Claude Code: /plugin marketplace add cathrynlavery/diagram-design, then /plugin install diagram-design@diagram-design. Codex: codex plugin marketplace add cathrynlavery/diagram-design && codex plugin add diagram-design@diagram-design. Pi: pi install https://github.com/cathrynlavery/diagram-design. The README also covers GitHub Copilot, Factory Droid, Kiro, OpenCode, and Claude Cowork. Alternatively, clone the repo and symlink skills/diagram-design/ into your host's global skills directory (~/.claude/skills/ etc.). Caveat: an older standalone npx skills add copy will not follow the new Codex marketplace — uninstall it first and reinstall via marketplace commands.
How do you use this skill?
After installing, ask in natural language: 'Make me an architecture diagram of my app: frontend, backend, database, Redis cache' or 'a quadrant of Q2 projects by impact vs effort'. On first use in a new project a style-guide gate asks whether to run brand onboarding ('onboard diagram-design to https://yoursite.com'), paste tokens manually, or proceed with defaults. For imports: /diagram-design:import-drawio platform.drawio --size=slide-16x9 --detail=simplified --audience=executive. For exports: /diagram-design:export-diagram my-diagram.html --png-only --scale=3.
How does this skill compare with similar options?
Against Mermaid or draw.io, the skill explicitly markets itself as the anti-Mermaid path: rather than converting renderer output, it discards source coordinates and palette and re-lays-out content under an editorial design system. It also positions itself as the alternative to 'fighting Figma for 30 minutes' rather than a Figma replacement.