diagram-design: 14.7K stars this week for self-contained agent diagrams (2026)

The short verdict

Install diagram-design if you want your agent to produce diagrams that are ready to open, review, and export instead of another Mermaid-shaped first draft. The MIT-licensed Skill creates self-contained HTML with inline SVG and CSS, chooses among diagram types, and can redraw Mermaid or draw.io sources for a specific audience and output size. It currently documents Claude Code, Codex, and Pi routes. 1 2

The adoption signal is unusually strong for a focused Skill: the weekly GitHub Trending snapshot shows 14,735 stars gained in the week, while GitHub repository metadata reports 19,388 total stars and 1,183 forks. That is attention, not proof that every output will fit your work. 3 4

Use it for architecture diagrams, technical documentation, product explainers, or slide-ready visuals. Give it a small first task before trusting an imported Mermaid file or a PNG export: the repository has open contributor reports about parser coverage, browser-engine assumptions, Python 3.9 compatibility, and documentation drift. 5 6 7 8

What changes in the workflow

Most diagram requests fail before styling. The agent has to decide what belongs in the picture, how the relationships should be routed, and which visual grammar matches the explanation. diagram-design puts those decisions into a reusable Skill instead of leaving them to a fresh prompt every time.

Its documented workflow is semantic pattern first, visual type second. A bottleneck maps to a data-flow layout; a trust boundary maps to an architecture layout; a paired policy trace maps to a flowchart. The Skill then applies a density budget, orthogonal connectors, visible arrow labels, and one or two focal elements. It explicitly recommends a table or paragraph when a diagram would add less information. 2

The output is deliberately portable. The README describes static HTML with inline SVG and CSS, no build step, and no external image dependency. The default remains static; optional motion has a complete static first frame and reduced-motion behavior. The repository also includes import paths for .drawio, embedded .drawio.png and .drawio.svg, Mermaid files, and fenced Mermaid blocks in Markdown. 1

Branding is a separate, useful part of the workflow. On first use in a project, the Skill checks whether its style guide is still at the shipped defaults. You can ask it to read a website, map the detected colors and fonts into semantic roles, show a proposed diff, and save the tokens. Named profiles and a .diagram-design marker let different client projects use different styles without overwriting the installed copy. 1

Install it

The current native manifests identify version 2.4.0, author Cathryn Lavery, and MIT licensing for both Claude Code and Codex. 9 10

Claude Code

Run the repository's marketplace commands inside Claude Code:

/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

The README says third-party marketplace auto-updates are disabled by default. After installation, open /plugin, go to Marketplaces, select diagram-design, and enable auto-update. Reload plugins when prompted. 1

Codex

codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-design

Codex refreshes configured Git marketplaces at startup. To fetch immediately, the README documents:

codex plugin marketplace upgrade diagram-design

Start a new session after the refresh. 1

Pi

pi install https://github.com/cathrynlavery/diagram-design

Run /reload in an open Pi session. Pi exposes the Skill for matching diagram requests and supports explicit /skill:diagram-design invocation. The README also documents /export-diagram, /import-mermaid, and /profile prompt templates. 1

Cursor and Cline are not installation paths documented by the repository sources checked for this issue. Treat support there as unverified until the host shows a working Skill or plugin route; do not assume that a compatible SKILL.md automatically gives you native marketplace behavior.

If you plan to export PNG files, budget for the documented Playwright dependency:

pip install playwright
playwright install chromium

That is an export prerequisite, not a requirement for creating the default HTML/SVG output. 1

Two safe first tests

The point of the first session is to test the Skill's judgment and the installed host, not to generate a giant poster.

Test 1: a bounded architecture diagram

Use a project with no sensitive data and ask for a small output:

Use diagram-design to make an architecture diagram of this application.

Show only these seven nodes: browser, API, worker, queue, database, object
storage, and observability. Use one accent color for the API. Keep connectors
orthogonal, label the two most important flows, and save one self-contained
HTML file. Before drawing, state the chosen visual type and any node or
relationship you are removing to stay within the complexity budget.

Then check the result yourself. The useful signals are concrete: the file opens without a build step, the diagram has a visible hierarchy, the arrows can be followed, and the agent explains what it left out. If the agent fills every node with the accent color or draws a single tangled route, stop there and adjust the prompt before adding a real project.

For a branded project, run onboarding first:

Onboard diagram-design to https://your-site.example, show me the proposed
paper, ink, accent, and font tokens, and wait for approval before saving them.

Replace the example URL with a site you control or are allowed to inspect. The repository says onboarding emits a fidelity receipt with sampled URLs, color roles, font families, and fallbacks. 1

Test 2: redraw a Mermaid file for a slide

Use a small Mermaid file whose output you can compare with the source:

/diagram-design:import-mermaid architecture.mmd \
  --size=slide-16x9 \
  --detail=simplified

The README's import interface keeps components, relationships, grouping, and direction while allowing the output to change format, size, detail, and audience. It also produces a fidelity ledger describing what it merged, collapsed, or dropped. 1

If you need a PNG after reviewing the HTML, use the documented export command:

/diagram-design:export path/to/diagram.html --png-only --scale=3

For this first run, compare the HTML and PNG side by side. Check text, fonts, connector routing, and the final crop. That catches the exact class of portability issue contributors are still discussing.

What users like—and where they hit edges

The strongest positive feedback I found is a first-person report rather than a star count. Dhilip Subramanian described using the Skill on an Azure document-intelligence platform: it produced two diagrams in one pass, picked up brand colors from one configuration file, and returned plain HTML without a Figma setup. He specifically liked the constraints: a nine-node maximum, one accent color, and no diagonal connectors kept the diagram from becoming overcrowded. 11

콘텐츠 카드를 불러오는 중…

The breakout signal also generated lightweight community discussion. A weekly-trending post drew comments calling self-contained SVG without Mermaid's usual mess “clutch,” while another commenter said the remaining problem was still turning AI-generated information into well-formatted information. Those comments support interest in the presentation layer; they are not a product benchmark. 12

The practical caveats are more useful than generic praise:

Mermaid import: open PR #54 says the shipped parser silently dropped quoted participants and create directives, rejected valid bidirectional arrows, and misclassified open arrows. If Mermaid import is central to your workflow, test the grammar you actually use and check whether your installed manifest has moved beyond the reported issue. 5
PNG export: open PR #59 reports that the export guide hard-coded Chromium even though the contributor verified the same local screenshot path with WebKit. Expect to install the documented engine first, or test your available browser before building a team workflow around export. 6
Contributor tooling: open PR #58 reports that the linter failed on Python 3.9 because of str | None annotations. This matters mainly if you modify the Skill or run its validation scripts; it is not a blocker for a normal managed install. 7
Documentation count: the repository description currently says 29 diagram types, while the README and SKILL.md enumerate 27. Issue #55 points to a gallery example that is not registered consistently as a type. Use the actual current command and gallery output as your check, rather than relying on the headline count. 4 8

The repository is active: metadata records an update on August 16, 2026, and the latest commit page shows a main-branch push on August 14 that added named client profiles. The native plugin manifests remain the cleaner version source for installation because they state 2.4.0; GitHub has no published release objects for this repository at the time checked. 4 9 13 14

Use it—or wait

Use it now when:

You regularly need architecture, flowchart, sequence, or data-flow diagrams in documentation or decks.
You want a self-contained HTML/SVG artifact that can be opened and reviewed before export.
A brand palette and repeatable layout rules matter more than drawing every possible shape.
You can run a small read-only test before giving the agent a real project.

Wait or sandbox it when:

You need a verified Cursor or Cline installation path today.
Your workflow depends on Mermaid grammar that you cannot test against the installed parser.
PNG export must be browser-independent on day one.
A table, paragraph, or simple before/after comparison would communicate the information more directly; the project's own guidance says those cases should stay out of a diagram. 1

Quick reference

Pick	`cathrynlavery/diagram-design`
Best for	Branded technical and product diagrams as self-contained HTML/SVG, with optional PNG export. 1
Maintainer	Cathryn Lavery. 9
License	MIT. 4
Documented hosts	Claude Code, Codex, and Pi. 1
Current native package version	`2.4.0` in the Claude and Codex manifests. 9 10
Weekly reach signal	14,735 GitHub stars gained in the current weekly Trending snapshot; 19,388 total stars in repository metadata. 3 4
Main mechanism	Semantic pattern → visual type → constrained, self-contained output. 2
Main caveat	Strong breakout signal, but open reports still cover Mermaid parsing, export portability, contributor runtime compatibility, and documentation drift. 5 6 7 8
First move	Install it in one supported host, generate a seven-node architecture diagram, and inspect the HTML before testing import or PNG export.

The sensible rollout is small. Let diagram-design prove that it can make one diagram your team would actually review. Then test the exact Mermaid grammar, browser engine, and host update path your workflow depends on.