Ship Editorial Diagrams in Your Brand Style with diagram-design

Ask a coding agent for an architecture diagram and you get generic rounded boxes. diagram-design, a 40k-star skill from BestSelf.co founder Cathryn Lavery, ships editorial diagrams instead — one accent color, serif titles, everything on a 4px grid — in your own brand palette.

Why This Skill Matters

Every diagram is a single self-contained HTML file with inline SVG: it opens in a browser by double-click, with no build step, no JavaScript in the static default, and no external image dependency. Each type ships in three variants — minimal light, minimal dark, and full-editorial — and a design system holds the line: one accent color reserved for the one or two focal elements, three font families (Instrument Serif, Geist, Geist Mono), 1px hairline borders, no shadows, and a maximum border radius of 10px.

One count needs disclosure: the README's prose says 39 diagram types, but the repo's references/ directory carried 40 type definitions as of September 17, 2026 — waterfall and polar charts among them. Trust the directory over the prose count, and pick from the gallery rather than from the README's number.

Installation

On Claude Code:

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

Run /reload-plugins when prompted, or let the next session load it. The README documents equivalent routes for Codex, GitHub Copilot, Factory Droid, Pi, Kiro, and OpenCode — the shared skill lives in skills/diagram-design/ and works in any Agent Skills-compatible host.

Real Workflow: Onboard Your Brand, Then Draw

Start with the one-time onboarding, which is the skill's whole point:

onboard diagram-design to https://yoursite.com

It fetches your homepage, extracts the dominant palette and font stack, maps them to semantic tokens (paper, ink, muted, accent, link), shows a proposed diff, and writes the tokens to references/style-guide.md once you approve. Contrast gets checked against WCAG AA at diagram sizes (9–12px) before anything is written, and the skill emits a fidelity receipt naming the sampled URLs, colors, and fonts. On the first diagram in a new project, a first-run gate asks whether to onboard, paste tokens manually, or proceed with the default jet-black and atomic-tangerine palette.

Then just ask: Make me an architecture diagram of my app: frontend, backend, database, Redis cache. The agent picks the type, builds the HTML, and saves it.

Real Workflow: Redraw a Mermaid Mess for a Slide

Existing diagrams get rebuilt, not converted:

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

Four dials control the output: format (HTML, SVG, PNG, or HTML plus PNG), size (from doc-inline to slide-16x9 to print-a4-landscape), detail (faithful keeps up to 24 nodes, balanced 12, simplified 7), and audience, which changes the wording rather than the count. Every import ends with a fidelity ledger — what got merged, collapsed, or dropped — so nothing disappears silently.

Tips

• Export SVG for Figma or PNG for slides with /diagram-design:export-diagram; PNG rasterizes through Playwright, which needs a one-time pip install playwright && playwright install chromium.
• Browse all the types offline by opening skills/diagram-design/assets/index.html — every diagram with light, dark, and full-editorial tabs.
• For multiple clients, save onboarding results as named profiles under ~/.diagram-design/profiles/ and mark each project with a .diagram-design file naming its profile.
• Accessibility ships by default: every SVG gets role="img" and a resolving accessible name, so screen readers announce the diagram's title and description.

When Not to Use This

The README draws the boundaries itself: quick unicode diagrams for tweets belong to a wiretext-style skill, lists of anything belong in a table, before/after comparisons belong in a table, and a one-shape "diagram" is just a sentence. Before drawing, ask whether a reader would learn more from the diagram than from a well-written paragraph.

See the leaderboard for more skills.