Diagram Design Passes 47,900 Stars, and Its README Tells Git Users to Pick Mermaid
Software / news
Diagram Design Passes 47,900 Stars, and Its README Tells Git Users to Pick Mermaid
The agent skill draws 44 diagram types as a single HTML file. Its own README admits layouts vary between runs, and five export bugs were filed on October 6.
Diagram Design, an agent skill that draws editorial diagrams as one HTML file, has 47.9k GitHub stars, and its own README tells anyone whose diagrams live in Git to use Mermaid instead.
The repository, cathrynlavery/diagram-design, is by Cathryn Lavery and uses the MIT licence. GitHub's trending list showed it gaining 1,739 stars on October 10. It had 3.0k forks, 271 commits on main, 20 open issues and 61 open pull requests when read.
What it produces and how it installs
The skill runs inside Claude Code, Codex, GitHub Copilot, Cursor and other hosts that read the Agent Skills format. Install is npx skills add cathrynlavery/diagram-design, and Claude Code, Codex, Copilot, Factory Droid and Pi each have their own marketplace command.
Output is a single .html file that opens offline in a browser. It can be exported to SVG or to PNG, rendered through Playwright at 2x by default. The skill can also redraw existing draw.io, Mermaid and Excalidraw files.
The README lists 44 diagram types, from architecture and sequence to Sankey, Wardley map and fishbone, each in minimal light, minimal dark and full-editorial variants. The repository sidebar says 42, so the project disagrees with itself by two.
The README argues against its own use case
Most viral skills repos sell. This one carries two admissions. The first reads: "Output quality depends on the model you run it with, and the same prompt can lay out differently twice." The second says the output has "no text to diff in a pull request and no canvas to drag a box on."
For diagrams that live in Git and change often, the README says "Mermaid is still the better fit." That is a fair verdict. Mermaid is MIT-licensed, describes itself as generating diagrams "from text in a similar manner as markdown," and had 90.6k stars and 9.3k forks.
- mermaid-js/mermaid90.6 thousand stars
- cathrynlavery/diagram-design47.9 thousand stars
Source: GitHub repository pages for mermaid-js/mermaid and cathrynlavery/diagram-design, read Oct. 10, 2026
Stars are not adoption. They record a click, not a diagram in a pull request.
Five export and checker items filed on October 6
The open issues show where a generated-HTML pipeline strains. Five items were filed on October 6 and are about export and checking, the step that turns the agent's drawing into a file someone can ship. One of them, #306, is titled as a fix.
| Issue | Filed | Problem, in the issue's words |
|---|---|---|
| #299 | Oct 6 | "PNG export rejects the fractional scale documented for exact pixel sizes" |
| #289 | Oct 6 | "SVG export applies print-only diagram CSS during screen rendering" |
| #288 | Oct 6 | "SVG export rejects valid rgba paint with separate presentation opacity" |
| #291 | Oct 6 | "Treemap verifier reads a numeric suffix instead of the printed percentage" |
| #306 | Oct 6 | "fix(geometry): exclude SVG definitions from painted shape checks" |
A sixth, #209 from September 10, reports that the Mermaid extractor rejects a compact label containing whitespace, which touches the redraw feature the README advertises. None of the 20 open issues on the page is described as a security or licensing problem.
What to read next in the same pile
The issue list also holds a policy question, #262 from September 28, titled "Unattended runs: explicit path through the §0 style gate," which asks how the skill should behave when no human approves the style step. A request filed October 9 asks whether the author plans to support Cursor, even though the README lists Cursor among compatible hosts. Both read as users probing the edges of a rule set that is still being written.
The pattern matches other trending skill collections this site has covered, such as Matt Pocock's agent skills and the Impeccable design detector. The test for Diagram Design is a diagram you must regenerate next month: if the layout changes between runs, as the README admits it can, the file stops being a record. The 61 open pull requests are the number to watch.
Sources
More in Software
- 01Tencent's LoopForge Installs With Docker Socket Access and Listens on All InterfacesThe MIT-licensed coding-agent workspace has 1.6k stars, ten supported agent CLIs, and a security section its quick-start does not lead with.
- 02Plannotator, at 11.9k Stars, Reviews Agent Plans Locally but Has No Release-Check Opt-OutThe browser review tool for ten coding agents installs with a curl-to-bash script and puts small shares in an unencrypted URL fragment.
- 03Jiff 1.0 Freezes Its API, Putting a Rust Datetime Library Beside ChronoThe release post commits to the 1.0 interface indefinitely and names uv, Cargo, Starship and Nushell among the projects already using it.
- 04Chrome DevTools MCP Gives Agents 63 Tools and Sends Usage Statistics by DefaultThe repository's own README, not the launch post, is where the data-collection default and the opt-out flags are written down.