@trendtech33566: To people whose diagrams turn into some kind of "generic box" when drawn by AI diagram-design, about 3.4k. What’s great…

| Font family token | Font token | | title font family | title font | | node-name font family | node-name font | | sublabel / caption font | sublabel font |

Contrast checks happen automatically

Before writing tokens, the skill verifies WCAG AA contrast on ink over paper. If your site has a color that fails contrast at diagram sizes (9–12px), it proposes an adjusted value and explains why.

Manual override

Prefer to set tokens by hand? Open skills/diagram-design/references/style-guide.md and edit the table. Everything downstream reads from there — all 27 diagrams, the annotation primitive, and the gallery all inherit semantic role names (accent, not #eb6c36).

First-run gate

The skill won’t silently ship default-skinned diagrams into a branded project. On first use in a new project, it checks if style-guide.md has been customized. If not, it pauses and asks:

“This is your first diagram in this project. The style guide is still at the default. Want to run onboarding, paste tokens manually, or proceed with default?”

See skills/diagram-design/references/onboarding.md for the full spec.

Quickstart

# Open the gallery to see all 27 diagrams
open ~/.claude/skills/diagram-design/assets/index.html

# In Claude Code, just ask:
# "Make me an architecture diagram of my app: frontend, backend, database, Redis cache."
# "I need a quadrant showing Q2 projects by impact vs effort."
# "Give me a sequence diagram of the OAuth handshake."

Claude will pick the right type, build the HTML, and save it. You can also start from a template directly:

cp assets/template.html my-diagram.html        # minimal light
cp assets/template-full.html my-diagram.html   # editorial with summary cards

Export to PNG / SVG

Diagrams ship as self-contained HTML, but you can export the diagram itself for Figma, slides, or social cards. Use the slash command:

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

Or just ask in natural language:

"Export this diagram as SVG and PNG."
"Save my-diagram.html as PNG."

• SVG — extracts the <svg> node and injects Google Fonts so it renders standalone in browsers, Figma, and Illustrator.
• PNG — rasterizes the diagram via Playwright at 2× by default. One-time setup: pip install playwright && playwright install chromium.

Both formats are diagram-only — editorial cards and headers from -full variants aren’t included. For a screenshot of the full editorial layout, use your browser’s print-to-PDF or full-page screenshot. See skills/diagram-design/references/export.md for the full procedure.

Architecture

Progressive disclosure. SKILL.md is a lean index — it tells Claude how to pick a type and where to look for detail. Every type lives in its own reference file, loaded only when relevant.

diagram-design/
├── SKILL.md — top-level: philosophy, selection guide, checklist
├── references/ — loaded only when a type or primitive is chosen
│   ├── style-guide.md — single source of truth for colors + fonts
│   ├── onboarding.md — the URL-to-tokens flow
│   ├── type-architecture.md
│   ├── type-flowchart.md
│   ├── type-sequence.md
│   ├── type-state.md
│   ├── type-er.md
│   ├── type-timeline.md
│   ├── type-swimlane.md
│   ├── type-quadrant.md
│   ├── type-nested.md
│   ├── type-tree.md
│   ├── type-org-chart.md
│   ├── type-layers.md
│   ├── type-venn.md
│   ├── type-pyramid.md
│   ├── primitive-annotation.md — italic-serif editorial callouts
│   ├── primitive-sketchy.md — hand-drawn SVG filter variant
│   └── primitive-terminal.md — charcoal-black CLI-window variant
├── assets/
│   ├── index.html — live gallery, tabbed
│   ├── template*.html — scaffolds for new diagrams
│   ├── example-*.html — 3 variants × 27 types
│   ├── example-loop-terminal.html — terminal-variant flagship
│   └── example-quadrant-consultant.html — consultant-special 2×2 scenario matrix
└── docs/screenshots/ — the images in this README

This keeps Claude’s working context tight (only load what you need) and makes the skill easy to extend — drop a new type-*.md and wire it into the selection guide. The skill ships with 34 reference files covering every diagram type, primitive, and utility.

Contributing / skin lint

Before submitting a new example, run python3 scripts/lint-skin.py <file>. The repository-wide check python3 scripts/lint-skin.py --all --baseline must stay green.

What loads when

The top-level SKILL.md is always in context. Everything else is pulled in only when relevant — this is what keeps the skill fast even with 34 reference files.

No matter how many types exist, Claude only reads the one you need. Add a new type tomorrow and nothing else changes.

The design system (in one paragraph)

One accent color, 1–2 focal elements per diagram. Three font families: Instrument Serif (title + italic callouts), Geist sans (node names), Geist Mono (technical sublabels). 1px hairline borders, no shadows, max border-radius 10px. Every coord, width, and gap divisible by 4 — non-negotiable, it’s what keeps the diagrams from feeling AI-generated. Mono is for technical content (ports, URLs, field types), not a blanket “dev” aesthetic. Coral-tinted focal nodes draw the eye to the 1–2 things that matter. Full spec in SKILL.md.

Primitives

• Annotation callout — italic Instrument Serif + dashed Bézier leader, for editorial asides that sit in the margins. See skills/diagram-design/references/primitive-annotation.md.
• Sketchy filter — SVG turbulence + displacement map for a hand-drawn variant. Good for essays, not for technical docs. See skills/diagram-design/references/primitive-sketchy.md.
• Icon set — 55 monochrome IT/cloud icons (laptop, phone, user, server, database, Docker, Kubernetes, AWS, Azure, GitHub, Postgres…) for richer architecture and sequence diagrams. Stroked icons from Tabler Icons (https://tabler.io/icons) (MIT); brand silhouettes from Simple Icons (https://simpleicons.org) (CC0). Each icon uses currentColor so it inherits the editorial skin or your onboarded brand. See skills/diagram-design/references/primitive-icons.md; browse the gallery. Regenerate with python scripts/build-icons.py.

When not to use this skill

• Quick unicode diagrams for tweets or terminal output → wiretext-style skill.
• Lists of anything → a table or bullets.
• Before/after comparisons → a table.
• One-shape “diagrams” — a single box with a label → just write the sentence.

Before drawing, ask: would a reader learn more from this than from a well-written paragraph? If no, don’t draw.

About

Made by Cathryn Lavery — founder of BestSelf.co (https://bestself.co?utm_source=diagram-design&utm_medium=readme&utm_campaign=github&utm_content=bio). I write about AI, entrepreneurship, and designing nice-looking things at littlemight.com (https://littlemight.com?utm_source=diagram-design&utm_medium=readme&utm_campaign=github&utm_content=bio) — blog + newsletter. If this is useful, star the repo and come say hi on X (https://x.com/cathrynlavery).