Who diagram-design is for#
Developers documenting architecture for blog posts or READMEs
Ask the agent for an architecture diagram of your stack and get back publication-quality HTML in your project directory. Brand colors from your site apply automatically after onboarding. The full-editorial variant includes summary cards that add context without a separate layout pass.
Skip if:
Your documentation toolchain expects Mermaid or SVG output embedded inline in Markdown and you do not want to manage separate HTML files. The skill can export SVG, but the workflow adds a conversion step compared to inline Mermaid syntax.
Teams converting draw.io or Mermaid diagrams to editorial quality
Import a .drawio file or Mermaid block and redraw it at the detail level and audience appropriate for the destination: balanced and executive for a board slide, faithful and engineer for a technical spec. The fidelity ledger shows exactly what was collapsed or dropped.
Skip if:
Your source diagrams have more than 24 nodes and you need faithful-level reproduction. The faithful detail preset caps at 24 nodes; above that the skill degrades to balanced, merging nodes and collapsing leaf clusters.
Technical writers producing slide decks for executive audiences
The slide-16x9 size preset adjusts the viewBox and type ramp for projected output (16px node names instead of 12px). The audience=executive wording reduces label verbosity: detailed service names become plain function labels. Output is PNG or HTML, ready for Keynote, PowerPoint, or Google Slides import.
Skip if:
You need live, interactive diagrams embedded in a web app. diagram-design produces static HTML or exportable SVG/PNG; it does not generate reactive or data-bound diagrams.
AI engineers and indie developers shipping editorial content
The skill reads your site's brand in 60 seconds and applies it to every diagram. The default jet-black and atomic-tangerine palette is presentable for screenshots without onboarding, but brand-matched output ships directly into production content without a designer review step.
Skip if:
You need team collaboration on diagrams: version history, comments, or shared editing. diagram-design produces files you own and edit locally; it has no cloud sync or collaboration features.
The problem it solves#
When you ask an AI agent for a diagram, you get back a generic rounded-box chart. The result looks nothing like your site, nothing like your deck, and nothing like what a designer would approve. Fixing it means a round-trip to Figma or another standalone diagramming tool, breaking your agent-driven workflow for 20 to 30 minutes every time you need one visual.
Mermaid is the standard escape hatch, but its layout engine produces connector spaghetti on anything beyond a simple flowchart, and its styling is limited to a handful of built-in themes. draw.io is more capable but requires a separate editor session and applies its own default palette that does not match your project. Neither tool integrates into an AI agent session.
How it solves it#
29 diagram types, self-contained HTML + SVG
Covers architecture, flowchart, sequence, state machine, ER/data model, timeline, swimlane, quadrant, tree, org chart, Gantt, scatter plot, loop, medallion, and more. Every type ships in three static variants: minimal light, minimal dark, and full-editorial. No build step, no JavaScript runtime, no external image dependencies. Open any file directly in a browser.
Brand matching from your website
Run "onboard diagram-design to https://yoursite.com" and the skill fetches your homepage, extracts the dominant palette and font stack, maps them to semantic roles (paper, ink, muted, accent, link), and writes the tokens to your style guide. Every diagram uses your colors from that point. WCAG AA contrast is verified before any tokens are saved. The process takes about 60 seconds.
Import and redraw from draw.io and Mermaid
Point the skill at a .drawio, .drawio.xml, .mmd file, or a fenced Mermaid block in Markdown and it redraws the content in the diagram-design system. Four dials control the output: format (HTML, SVG, PNG), size (doc-inline to slide-16x9), detail (faithful, balanced, simplified), and audience (engineer, mixed, executive). Every import ends with a fidelity ledger listing what was merged, collapsed, or dropped.
Three output variants: light, dark, and full-editorial
Each diagram type ships a minimal-light, minimal-dark, and full-editorial variant. The full-editorial variant adds summary cards and header metadata. For slides or Figma, an export command rasterizes to PNG at 2x scale via Playwright, or extracts the SVG node with Google Fonts injected for standalone rendering in browsers and Illustrator.
Accessible SVG output by default
Every diagram template gives the inline SVG an accessible name and description: role="img", a resolving aria-labelledby, and first-child title and desc slots. IDs are prefixed per diagram and variant so multiple SVG exports can be safely inlined on one page without duplicate accessible-name IDs. Decorative specimen icons are hidden from assistive technology.
Optional motion for ordered explanations
Version 2.3 adds accessible animation with four modes: none (default, static), reveal, step, and loop. Motion HTML uses the exact reviewed controller from template-motion.html. Arbitrary or modified inline scripts are rejected. Reduced-motion output shows the complete static frame and hides playback controls. The default is none: ordinary output remains static and script-free.
Strengths and trade-offs#
Strengths
- No external runtime dependencies for default HTML outputEvery diagram opens directly in a browser as a self-contained HTML file. No Node.js, no build step, no server. The gallery at cathrynlavery.github.io/diagram-design lets you preview all 29 types without installing anything, and the skill generates the same files into your project directory.
- Stays inside your agent sessiondiagram-design installs as a skill for Claude Code, Codex, or Pi. You describe the diagram in natural language and the agent builds the HTML, picks the right visual type, and saves the file. No round-trip to a GUI editor or a separate browser tab.
- MIT license with no managed-cloud requirementThe MIT license means you can run it on any project, fork it, modify the style system, and ship the output commercially without restriction. The skill directory is the product. No managed cloud tier, no API key, and no per-diagram fee.
- Semantic patterns separate behavior from layoutSeven routed semantic patterns cover fan-in queues, repeated stage slots, unstructured-input transformation, paired policy traces, secure paved roads, governance catalogs, and compensating security layers. The skill picks a pattern first and a visual type second, so a queue or policy trace uses the nearest existing type without expanding the type count.
Trade-offs
- -PNG export requires Playwright and ChromiumRasterizing a diagram to PNG requires a one-time setup: pip install playwright && playwright install chromium. This adds a system-level dependency (headless Chromium) that is not present for the default HTML or SVG outputs. On minimal CI environments or locked-down machines, this step may require manual approval or a custom Docker image.
- -Requires an AI agent runtime to generate diagramsdiagram-design is not a standalone application. It runs as a skill inside Claude Code, Codex, or Pi. Teams not using one of those agent runtimes cannot use this tool without adopting one first. You can copy templates manually from the assets directory, but the generative workflow requires an active agent session.
- -Managed installs may overwrite a customized style guideManaged installs via Pi or the Claude Code plugin marketplace may replace a customized references/style-guide.md when the package updates. The README recommends cloning the repo and installing from the local path if you plan to customize the style guide. This adds setup friction compared to a one-command managed install.
diagram-design vs alternatives#
diagram-design vs Figma
Figma is the paid design tool most teams reach for when generic AI diagrams fall short. It offers a full canvas editor, component libraries, and real-time collaboration at $15/editor/month.
The key difference is workflow. Figma requires leaving your editor, building the diagram by hand, and exporting it back. diagram-design stays inside Claude Code, Codex, or Pi: describe the diagram, the agent picks the type, and the HTML file lands in your project directory. Brand colors apply automatically after a 60-second onboarding step.
Figma is the better choice when you need real-time team collaboration on diagrams, a shared component library, or a Figma-native design handoff workflow. diagram-design has no collaborative canvas.
diagram-design vs draw.io
draw.io is free and open source with a GUI editor and export to multiple formats. The gap with diagram-design is output quality and AI integration.
draw.io output uses generic default styles unless you invest time in a custom theme. diagram-design applies an opinionated editorial design system across all 29 types: layout rules, label hierarchy, and accent usage are defined by the type specification, not left to the user.
diagram-design imports draw.io source files (.drawio, .drawio.xml, .drawio.png) and redraws them in its design system. Teams with existing draw.io libraries can migrate individual diagrams without rebuilding from scratch.
draw.io is the better fit when non-technical team members need a standalone editor without an AI agent runtime, or when you need interactive diagram features that diagram-design's static HTML does not support.
diagram-design vs Mermaid
Mermaid is the standard text-based diagramming format in developer documentation, with native support in GitHub, GitLab, Notion, and most static site generators.
The tradeoff is visual quality. Mermaid's layout engine prioritizes correctness over aesthetics: connectors can overlap and styling is limited to built-in themes. diagram-design accepts Mermaid source files and fenced mermaid blocks as import input, redraws the content in its editorial design system, and applies your brand colors.
Mermaid remains the better choice when diagrams live in Markdown files that render directly in GitHub or a static site generator and visual quality is secondary to the convenience of inline text syntax.
Install and self-host#
Install as a skill using your agent runtime's package manager, or clone the repo for an editable setup.
```bash
npx skills add https://github.com/cathrynlavery/diagram-design --skill diagram-design
git clone [email protected]:cathrynlavery/diagram-design.git ~/code/diagram-design
```What it's built on#
- Languages
- Python
FAQ#
Does diagram-design work without Claude Code?
Yes. It also works as a skill in Codex (via npx skills add) and Pi (via pi install). The shared skill files are compatible with any Agent Skills-compatible runtime. You can also copy templates directly from the assets directory and edit them manually without an agent.
Is there a hosted or cloud version?
No. diagram-design is a local skill that runs inside your agent session. All diagram generation happens in your agent's context, and output files are saved to your local project directory. There is no managed cloud service, no API key, and no per-diagram fee.
What diagram types are included?
The skill includes 29 diagram types. Examples from the gallery: architecture, flowchart, sequence, state machine, ER/data model, timeline, swimlane, quadrant, tree, org chart, Gantt, scatter plot, bar chart, loop, medallion, data flow, and DP security matrix. Each type ships in three static variants: minimal light, minimal dark, and full-editorial.
How does brand matching work?
Run "onboard diagram-design to https://yoursite.com" in your agent session. The skill fetches your homepage, extracts the dominant palette and font stack, maps them to semantic roles (paper, ink, muted, accent, link, title font, body font), and writes the tokens to references/style-guide.md. WCAG AA contrast is verified before any tokens are saved. The process takes about 60 seconds.
Can I use the diagrams in Figma or presentation slides?
Yes. The export command extracts the SVG node (with Google Fonts injected for standalone rendering) or rasterizes to PNG at 2x scale using Playwright. SVG works in Figma and Illustrator; PNG works in any presentation tool. The one-time setup for PNG export is: pip install playwright && playwright install chromium.
Similar open-source tools#
agency-agents
Expert AI agent personalities for every workflow
design.md
Generate UIs effortlessly with AI.
freeCodeCamp
Join the FreeCodeCamp community and contribute!
Optimo
Optimize and convert images and videos using open formats
Untitled UI React
Open source React UI component library with Tailwind CSS
Webstudio
Open source website builder with visual design and CMS