What a project gaining 7,208 stars in a week actually is
The repository cathrynlavery/diagram-design reached number 2 on the GitHub weekly trending chart for the 2026-09-14 issue, adding 7,208 stars over the window of 2026-09-08 through 2026-09-13. As of verification it carries 39,807 stars and 2,528 forks, its primary language is HTML, it is MIT licensed, created on 2026-04-16, last pushed 2026-09-10, with 44 open issues.
The author is Cathryn Lavery, founder of BestSelf.co, writing about AI, startups, and design at littlemight.com. A designer by background shipped a "diagram skill pack" that reached second place on an engineer-dominated chart by publishing a restrained set of rules about how diagrams should look, not another engine.
One verification point: the README states 39 editing-grade diagram types, but the trending chart's description says 38. They disagree. The README's 39 is correct because version 2.5.10 added ten layout syntaxes at once. A small mismatch like this is where "verified" separates from "paraphrased."
This is not a standalone app. It is a diagram skill pack for Agent Skills compatible hosts: Claude Code, Codex, Factory Droid, Pi, GitHub Copilot, Kiro, and OpenCode. You install it into your coding agent, and the agent produces diagrams as it writes documentation and proposals.
What it produces: self-contained HTML and SVG
Its output is self-contained HTML plus SVG: no build step, no JavaScript, no external image dependency. Double-click and it opens in a browser, works offline, with the only external request being the single one to Google Fonts. That line, "no JS, no build, self-contained," is the whole thesis.
Why is it the thesis? Because nearly every diagram engine must solve the rendering dependency problem. Mermaid needs a runtime to parse text into a picture. draw.io is a full editor. Excalidraw depends on a browser and a hand-drawn library. diagram-design sidesteps the entire path and emits a static file any HTML-capable environment can display, with no toolchain. You get a picture already drawn, not code still waiting to be rendered.
This is also where it draws the line against Mermaid. The official tagline reads: No shadows. No Mermaid slop. Putting Mermaid in the opponent slot is how it establishes an identity.
Every diagram type ships in three static variants: minimal light, minimal dark, and full-editorial. Light and dark are clean, single-background versions; editorial adds editorial cards and a header. On export both formats "contain only the diagram itself"; the editorial cards and header are excluded from the default export, and only the -full variant carries them.
The design system: why the constraints fight the AI look
What makes this project hold together is its design system, not the 39 types. It has constraints that look fussy alone but point at one clear goal:
- Exactly one accent color, with only 1 or 2 focal elements per diagram.
- Three typefaces: Instrument Serif for titles and italic annotations, Geist sans for node names, Geist Mono for technical sub-labels.
- 1px hairline borders, no shadows, maximum corner radius of 10px.
- Every coordinate, width, and spacing must be a multiple of 4.
- Default palette is jet-black plus atomic-tangerine.
- Target information density is 4 out of 10, and the design maxim is "the highest-quality operation is usually deletion."
Each constraint is small; together they make the diagram not look AI-generated. AI diagrams today fail two ways: they overuse gradients and shadows and look cheap, or they pile on elements, misalign, and lose density control. diagram-design closes both doors with no shadows, one accent color, and a grid in multiples of 4. The multiple-of-4 rule is the sharp one: human layout lands on an integer grid, while models hand out decimals that never line up, reading as "AI smell." Forcing multiples of 4 erases that misalignment at generation time.
The system does not cover scenarios by stacking type counts. It inverts the order: it defines behavior patterns first, then picks a visual type. The project ships 8 "semantic patterns," such as fan-in queue and bottleneck, repeating stage slots, unstructured input transformation, paired strategy trajectories, safe paved road, governance catalog, compensatory security layer, and traceable block decomposition. The logic is "decide the behavior you want to express, then choose a diagram to carry it," not "I have 39 types, pick a pretty one." That is the same judgment as the AI coding skill frameworks comparison: skills should organize around intent rather than stack around tools.
Brand onboarding and multi-client profiles
Brand onboarding is the most practical feature. You tell it "onboard diagram-design to https://your-site.com," it scrapes your homepage, extracts the dominant colors and font stack, and maps them to semantic tokens: paper, ink, muted, accent, link, paper-2. It shows a diff before writing to references/style-guide.md, and only persists after you confirm.
It runs WCAG AA contrast checks automatically; if your brand color fails at the small 9 to 12px in-diagram font sizes, it proposes adjusted values and explains why. It also emits a fidelity receipt listing the sampled URL, each color role, the font family and weight, the font source URL, and any downgrades.
A first-run gate stops the first diagram in a project with no customized style-guide and asks whether you want onboarding, manual token entry, or the default skin. That "ask before acting" step keeps an agent from blindly applying a brand it has no context for.
A brand can be saved as a named profile at ~/.diagram-design/profiles/<slug>.md. A project drops a .diagram-design marker file containing profile: <slug>, and its diagrams read that profile directly; multiple workspaces run in parallel without overwriting. The profile library is shared across Claude Code, Codex, Factory Droid, and Pi, so a brand defined in one tool is reusable in another.
Import and export: redraw, not convert
It can redraw draw.io, Mermaid, and Excalidraw source files into this design system. The keyword is "redraw," not "convert": keep content and structure, swap the style. Same idea as distilling books into skill packs.
Import coverage is broad. draw.io supports .drawio, .drawio.xml, .drawio.png (embedded diagram), and .drawio.svg, including compressed payloads. Mermaid supports .mmd, .mermaid, and mermaid code blocks inside Markdown. Excalidraw supports .excalidraw and .excalidraw.json scene files but not its png or svg exports. The Excalidraw path parses text only: no render, no JavaScript, no browser, no network, no click targets. That safety property means redrawing a received Excalidraw file triggers no side effects.
The whole import is governed by four knobs:
| Knob | Values | Notes |
|---|---|---|
| Format | html, svg, png, html+png | Output form |
| Size | doc-inline, doc-wide, slide-16x9, slide-4x3, social-og, social-square, print-a4-landscape, print-letter-landscape, fit (9 total) | Changes viewBox and the font-size ladder together; projection diagrams use a 16px node name instead of 12px |
| Detail | faithful (up to 24 nodes), balanced (up to 12), simplified (up to 7) | Fixed downgrade ladder: decorations first, then repeats, then leaf clusters, then infrastructure |
| Audience | engineer, mixed, executive | Changes wording, not count, e.g. Auth Service / JWT · RS256 · :8443 to Auth Service / token check to Sign-in |
Every import ends with a fidelity ledger stating what was merged, collapsed, or dropped. There is also a clear boundary of what it refuses to inherit: source or renderer coordinates, source palette, source fonts, draw.io's tangle of diagonal connectors, Mermaid's automatic layout, and Excalidraw's hand-drawn geometry. What it always inherits is components, relationships, grouping, and direction.
On the export side the boundary holds too. For SVG, it extracts the <svg> node and injects Google Fonts so the result stands alone in a browser, Figma, or Illustrator. For PNG it rasterizes with Playwright at a default of 2x; the one-time setup is pip install playwright && playwright install chromium. As noted, both export formats contain only the diagram itself, and the editorial cards and header in the -full variant are excluded.
Engineering quality and boundaries, and who should use it
What earns respect is how seriously it treats "diagrams that lie." It does several unglamorous but solid things.
Crop detection uses pixel differencing, not geometry. The project notes that getBoundingClientRect() misses stroke width, markers, and filter overflow, and ignores clip-path. It screens each SVG once as-is, then again with overflow released, and differences the two; ink outside is what got clipped. It stores no golden image, so the repo avoids a pile of baseline PNGs needing re-recording, which helps long-term maintenance.
It ships gate scripts for specific "diagrams that lie" cases: a Sankey conservation check, a waterfall running-total check, a treemap area-error check (relative error, not absolute, because absolutes excuse the small cells most likely to be wrong), a label-occlusion check, and a block-registry cycle and dangling-parent check. These defend against shipping a data diagram whose numbers do not add up.
Progressive disclosure is restrained: a normal call loads only SKILL.md plus that one type's reference file, with semantic, type, and animation references on demand. That is friendly to token cost and keeps the whole manual out of the model at once.
Animation is optional and adds no new types. It supports none, reveal, step, and loop, with none as the default, so the default output is static and script-free. The static first frame must be complete. Under prefers-reduced-motion it shows the full static frame and hides playback controls. Animated HTML may use only the one audited, fixed controller; any arbitrary or modified inline script, remote asset, CSS @import, or executable attribute is rejected.
Accessibility is not faked. Every diagram's SVG carries role="img", a resolvable aria-labelledby, and <title> and <desc> as its first children. SVG internal IDs are prefixed by diagram and variant so multiple inlined SVGs never collide on accessible-name IDs. It bundles 87 monochrome IT and cloud icons (laptop, phone, user, server, database, Docker, Kubernetes, AWS, Azure, GitHub, Postgres, and others); stroke icons are Tabler Icons (MIT), brand outlines Simple Icons (CC0), all via currentColor.
It is also clear about where "do not use" applies, and that restraint earns it points:
- Quick unicode diagrams for Twitter or a terminal.
- Anything checklist-shaped, where a table or list is better.
- Before-and-after comparisons, where a table wins.
- A "diagram" that is one box and one label, where a sentence is enough.
The project asks users to self-check first: will a reader learn more from this diagram than from a well-written sentence? If not, do not draw it.
So who should adopt it? If your output goes into docs, proposals, or client-facing reports, you cannot stand Mermaid's cheap look, and you want offline, archivable, accessibility-ready static files, diagram-design is worth a try. It moves "AI diagramming" from generating a decent-looking picture to producing a deliverable, archivable, accessibility-ready static file, and that step has real value.
The cost is clear. It is a heavy spec system with a higher onboarding cost than one line of Mermaid; you must learn its tokens, profiles, and four knobs. If you only want a quick README flowchart, Mermaid is enough, and you should not reach for this pack for the "premium feel." Note the tension: it positions Mermaid as the opponent yet ships a Mermaid import path. What it really replaces is not Mermaid's syntax but its "slop" aesthetic. For hands-on wiring, see the Codex harness integration walkthrough; the essence is the same, getting a skill pack into your agent workflow.
FAQ
Q1: Which agent hosts does diagram-design support?
A1: Its stated target is Agent Skills compatible hosts, explicitly Claude Code, Codex, Factory Droid, Pi, GitHub Copilot, Kiro, and OpenCode. You install it into an agent, which then calls it while writing docs or proposals. It is not a standalone GUI app.
Q2: The README says 39 types but the trending chart said 38. Which is right?
A2: Trust the README's 39. The trending chart captured a project description stating 38, and the two disagree. Version 2.5.10 added ten layout syntaxes in one release, and the README reflects the updated count.
Q3: What do I install to export PNG?
A3: It rasterizes with Playwright at a default of 2x. The one-time setup is pip install playwright && playwright install chromium. SVG export needs none of that; it only extracts the <svg> and injects Google Fonts.
Q4: Can it turn my draw.io file into this style automatically?
A4: Yes, and it is a "redraw," not a "convert": it keeps components, relationships, grouping, and direction but swaps the style. It supports .drawio, .drawio.xml, .drawio.png, and .drawio.svg, including compressed payloads. It does not inherit source coordinates, source palette, source fonts, or draw.io's tangle of diagonal connectors.
Q5: Are the IT icons in the diagrams a licensing risk?
A5: The 87 bundled monochrome IT and cloud icons use stroke icons from Tabler Icons (MIT) and brand outlines from Simple Icons (CC0), all via currentColor to inherit the skin, so they are safe to use. The repository as a whole is MIT licensed.