Diagram-Design: Editorial-Quality Diagrams for AI Agents, 45 Types, Brand-Aware Styling

Author Encodes Taste as Rules

The project diagram-design by independent developer Cathryn Lavery (founder of LittleMight) reached 55.4k GitHub stars in six months. Its manifesto: "Reject Mermaid template flavor." Instead of teaching agents to produce merely usable diagrams, it teaches them to produce diagrams worthy of your brand.

Lavery built it after repeatedly getting generic rounded-box diagrams from Claude for her blog littlemight.com. The model understood the content but lacked taste. She codified that taste into four executable rules:

One accent color, reserved for the 1–2 elements the reader should see first.

1px hairline strokes, no drop shadows.

Every coordinate snaps to a 4px grid.

Density target of 4/10.

She also emphasizes: "The highest-quality move is usually deletion — every node must earn its place." This runs counter to most diagram tools that encourage adding more elements.

What It Pushes Back Against

diagram-design is not anti-Mermaid; it is anti-renderer-theme. The project includes a comparison table:

How it works: Mermaid/PlantUML = write text; draw.io/Excalidraw = manual drag; Diagram Design = describe in natural language to an agent.

Layout: Mermaid = automatic; draw.io = manual; Diagram Design = agent places on 4px grid, CI checks overlaps and clipping.

Look & feel: Mermaid = renderer themes; draw.io = whatever you draw; Diagram Design = one opinionated editorial style that adapts to your brand.

Artifact: Mermaid = rendered text on GitHub; draw.io = editable .drawio/.excalidraw files; Diagram Design = single inline-SVG HTML file, exportable to SVG/PNG.

The core differentiator is the opinionated editorial aesthetic that automatically matches your brand — not a theme picker, but a designer-approved default.

The library covers 45 chart types — architecture, sequence, state machine, ER models, quadrant, radar, swimlane, timeline, org chart, Sankey, fishbone, Wardley map, UML class diagrams — each with three static variants: minimal light, minimal dark, and full editorial.

One-Command Brand Color Onboarding

Unlike verification-focused tools like archify, diagram-design bakes aesthetics into brand identity. The default skin uses jet-black + tangerine, but the killer feature is a single onboarding command: onboard diagram-design to https://yoursite.com The agent fetches your homepage, extracts the primary palette and font stack, maps them to semantic roles (paper, ink, muted, accent, link), presents a diff for confirmation, and writes a style-guide.md. Every subsequent diagram automatically uses your colors: site background becomes diagram background, CTA color becomes the accent, body font becomes node labels.

It also validates WCAG AA contrast for ink-on-paper at small sizes (9–12px) and suggests corrections if needed. A first-run gate prevents silent insertion of default-skin diagrams: if style-guide.md is not yet customized, the tool pauses and asks whether to onboard, paste tokens manually, or proceed with defaults.

Four Knobs + Import Redraw

Four independent knobs let the same source file adapt to different outputs:

Format (html/svg/png/html+png): delivery format — SVG for Figma, PNG for slides, HTML for web.

Size (doc-inline, slide-16x9, print-a4, etc., 10 presets): adjusts viewBox and font sizes — slide mode uses 16px node labels instead of 12px.

Detail (faithful ≤24 nodes, balanced ≤12, simplified ≤7): fixed degradation ladder — remove decoration first, then duplicates, then leaf clusters, finally infrastructure.

Audience (engineer, mixed, executive): changes wording, not quantity — e.g., "Auth Service / JWT·RS256·:8443" → "Auth Service / token check" → "Sign-in".

Import supports draw.io, Mermaid, and Excalidraw sources. Each import produces a fidelity ledger listing what was merged, folded, or dropped — e.g., 12 source nodes → 8 rendered nodes, with the "Token valid?" decision collapsed into an edge label on Gateway→Auth.

Installation & Setup

npx skills add https://github.com/cathrynlavery/diagram-design

Or clone and open skills/diagram-design/assets/index.html to browse the 45-chart gallery. Start from a template: cp template.html my-diagram.html (choices: minimal light, editorial, motion). Compatible with Cursor, Claude Code, Codex, GitHub Copilot, Gemini CLI, Cline, Windsurf, Amp, Pi, Factory Droid.

Zero build, zero JavaScript, zero external images — only one optional Google Fonts request (Instrument Serif + Geist), switchable to system fonts for fully offline use. Double-click the .html to open.

Who This Is For

Developers using agents for architecture, sequence, quadrant diagrams but tired of the Mermaid look.

Product/tech leads needing diagrams that strictly match company brand and can go straight into presentations.

Teams with a backlog of draw.io/Mermaid diagrams wanting a unified visual style.

Conversely, for diagrams that live in Git and change every sprint, the author explicitly recommends Mermaid — a clear boundary.

Three Acknowledged Limitations

The README unusually lists downsides:

Output quality depends on the model. Same prompt run twice may yield different layouts — a common issue for any model-driven layout tool.

Result is not an editable source format. No diffable text, no draggable canvas. Changes require re-prompting the agent or editing SVG directly.

Positioning trades off editability for aesthetics + brand fit. The author states: "For docs that live in Git, Mermaid remains the better choice; Diagram Design is for the one diagram you need to publish."

Author's Take

Where archify answers "is the diagram correct?" (topology verifiable, no hallucinations), diagram-design answers "is the diagram beautiful?" The two are nearly orthogonal; which you need depends on where your pain point lies.

The project's strength isn't the 45 chart types but its clarity about what it sacrifices. Most tools claim to do everything; diagram-design openly declares: no diff, no edit, no interaction — just a diagram you're willing to ship. That boundary awareness, plus Lavery's codification of taste into measurable rules (1px hairline, 4px grid, single accent), is more valuable than vague appeals to aesthetics.

It remains a polishing tool: it can't fix a model that fundamentally can't diagram, only one that diagrams poorly. Recommendation: keep Mermaid for long-lived, frequently updated docs; try diagram-design for one-off, public-facing diagrams and see if the moment your brand colors drop into the chart feels worth it.

GitHub repository: https://github.com/cathrynlavery/diagram-design