diagram-design

Open source alternative to Napkin AI, Lucidchart, EdrawMax, Miro and Figma

58.9K stars
MIT
Active this week
Last commit 2 days ago

Last verified Oct 20, 2026

Generate editorial-quality diagrams with Claude Code, Codex, or Pi. 29 self-contained HTML + SVG types, MIT licensed, with brand matching and draw.io import.

Visit website GitHub58.9K

Read the full breakdownWho it is for, how it works, trade-offs, the quick start and the FAQ

who it's for

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

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 diagram-design solves it

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 · trade-offs

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.

versus alternatives

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 · quick start

Quick start#

bash

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
```

tech stack · detected from GitHub

What it's built on#

Languages: Python

frequently asked

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.

also worth a look

Similar open-source tools#

OpenFlowKit

Alternative toEraser.io

Local-first AI diagramming tool for developers and builders

897 GitHub stars
Licence MIT

diagrams.net

Alternative toLucidchart

Create portable diagrams without vendor lock-in

8,886 GitHub stars
Licence Apache-2.0

Excalidraw

Alternative toMiro

Open source whiteboard for hand-drawn style diagrams

134,025 GitHub stars
Licence MIT

Onlook

Alternative toFigma

Visual React editor where every design change writes real code

26,928 GitHub stars
Licence Apache-2.0

Penpot

Alternative toFigma

Open source collaborative UI design and whiteboard workspace

61,434 GitHub stars
Licence MPL-2.0

ChartDB

Alternative toSqlDBM

Free open source database diagram editor and visualizer

23,011 GitHub stars
Licence AGPL-3.0

by category

Open source tools in these categories#

Featured

rakazo

Alternative toGrok Bot

AI teammates you own: your keys, your model, your machine.

4,904 GitHub stars
Licence Apache-2.0
#AI Agents

Omnara

Alternative toClaude Managed Agents

Open-source agent deployment API. Self-host or use Omnara Cloud.

2,957 GitHub stars
Licence Apache-2.0
#AI Agents

Inbox Zero

Alternative toSuperhuman

AI email assistant that drafts replies and clears your inbox

12,712 GitHub stars
Licence AGPL-3.0
#Email

Feature your project

The projects we add and every new guide. Free, unsubscribe any time.

Find open source alternatives to paid software

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.

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.

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.

Who diagram-design is for#

Developers documenting architecture for blog posts or READMEs

Skip if:

Teams converting draw.io or Mermaid diagrams to editorial quality

Skip if:

Technical writers producing slide decks for executive audiences

Skip if:

AI engineers and indie developers shipping editorial content

Skip if:

The problem it solves#

How it solves it#

29 diagram types, self-contained HTML + SVG

Brand matching from your website

Import and redraw from draw.io and Mermaid

Three output variants: light, dark, and full-editorial

Accessible SVG output by default

Optional motion for ordered explanations

Strengths and trade-offs#

Strengths

Trade-offs

diagram-design vs alternatives#

diagram-design vs Figma

diagram-design vs draw.io

diagram-design vs Mermaid

Quick start#

What it's built on#

FAQ#

Similar open-source tools#

Open source tools in these categories#

Design & Creative

Product & Project Management

Web Development

Find open source alternatives to paid software

Who diagram-design is for#

Developers documenting architecture for blog posts or READMEs

Skip if:

Teams converting draw.io or Mermaid diagrams to editorial quality

Skip if:

Technical writers producing slide decks for executive audiences

Skip if:

AI engineers and indie developers shipping editorial content

Skip if:

The problem it solves#

How it solves it#

29 diagram types, self-contained HTML + SVG

Brand matching from your website

Import and redraw from draw.io and Mermaid

Three output variants: light, dark, and full-editorial

Accessible SVG output by default

Optional motion for ordered explanations

Strengths and trade-offs#

Strengths

Trade-offs

diagram-design vs alternatives#

diagram-design vs Figma

diagram-design vs draw.io

diagram-design vs Mermaid

Quick start#

What it's built on#

FAQ#

Similar open-source tools#

Open source tools in these categories#

Design & Creative

Product & Project Management

Web Development

Find open source alternatives to paid software