diagram-design skill for Claude Code: install, diagram types, and brand setup

Ask Claude Code for an architecture diagram with no skill loaded and you usually get a Mermaid block with equal-sized boxes, crossing arrows and no clear focus. The diagram-design skill addresses that: it makes the agent draw editorial diagrams in your brand colors, as one self-contained HTML file.

Key takeaways

• diagram-design has 4,613 installs (skills.sh registry) and its repo has 31,735 stars (GitHub).
• It ships 41 visual types, from architecture and sequence diagrams to Sankey, Wardley map and database schema (diagram-design SKILL.md, GitHub).
• It redraws existing draw.io, Mermaid and Excalidraw sources, with three detail levels capped at 24, 12 and 7 nodes (diagram-design README).
• A one-time onboarding step reads your website and maps its palette and fonts to diagram tokens, with a WCAG AA contrast check on text.
• If you want Mermaid text that diffs in a pull request, design-doc-mermaid is the better fit at 44,237 installs (skills.sh registry). The full comparison is in best diagram skills for Claude Code.

What is the diagram-design skill?

diagram-design is a Claude Code skill by Cathryn Lavery that turns a plain-language request into a designed diagram saved as HTML, SVG or PNG. Our catalog files it under Design & UI/UX with 4,613 installs and 31,735 GitHub stars (skills.sh registry, GitHub). The README states the design rules plainly: one accent color, one or two focal elements, 1px hairlines, no shadows, and every coordinate divisible by 4. Those constraints give the output a hand-designed look.

How do you install diagram-design in Claude Code?

Run /plugin marketplace add cathrynlavery/diagram-design, then /plugin install diagram-design@diagram-design inside Claude Code. The README recommends that you turn on auto-update once: run /plugin, open Marketplaces, select diagram-design and enable auto-update, because Claude Code turns it off by default for third-party marketplaces. After that, ask in normal words, for example "make me an architecture diagram of my app: frontend, backend, database, Redis cache". Our guide to installing a Claude skill covers the general mechanics, and Anthropic documents how skills load in the Claude Code skills docs.

What kinds of diagrams can it make?

The skill covers 41 visual types (diagram-design SKILL.md, GitHub), and each one has a minimal light, minimal dark and full-editorial variant (diagram-design README). The software-engineering set includes architecture, sequence, state machine, ER, deployment, dependency graph, UML class and database schema. The planning and product set includes Gantt, swimlane, kanban, user journey, story map and Wardley map. For data it draws bar, line, scatter, treemap, Sankey and waterfall charts. A routine request loads SKILL.md plus one type reference, so the agent does not read the whole library for every diagram. You can browse every type in the author's live diagram gallery.

How do you make the diagrams match your brand?

Run the onboarding once per project: tell the agent "onboard diagram-design to https://yoursite.com". The skill fetches the homepage, extracts the palette and font stack, and maps them to five semantic roles (paper, ink, muted, accent, link). It shows a diff before it writes the tokens to references/style-guide.md. It also checks WCAG AA contrast of ink on paper at diagram text sizes of 9 to 12px, and proposes a darker value if your color fails. On first use in a new project, the skill stops and asks whether to onboard, so default-colored diagrams do not ship into a branded doc by accident. If you design for several clients, save each brand as a named profile and point each repo at its profile with a .diagram-design marker file. For broader visual direction beyond diagrams, see the UI design hub.

Can it convert existing Mermaid or draw.io diagrams?

Yes. It redraws the source: the output keeps components, relationships, grouping and direction, and drops the source coordinates, palette and fonts. It reads .drawio files (including compressed payloads), .mmd files and fenced mermaid blocks in Markdown, and .excalidraw scene files. Four settings shape the result: format (html, svg, png), size (doc-inline through slide-16x9 and print sizes), detail (faithful up to 24 nodes, balanced up to 12, simplified up to 7) and audience (engineer, mixed, executive). Every import ends with a fidelity ledger that lists what was merged or dropped, so you can check it against the source.

When should you use a different diagram skill?

Use diagram-design when the diagram goes into a blog post, a deck or product docs where looks matter. Use a Mermaid skill when the diagram lives in the repo and must diff in review. design-doc-mermaid leads on installs at 44,237, and mermaid-diagrams is a lighter option at 4,847 installs (skills.sh registry). For an editable whiteboard canvas, excalidraw-diagram-generator has 29,011 installs from a repo with 38,671 stars (skills.sh registry, GitHub). The ranked list for this whole area is on best skills for docs and planning, and you can browse every option in the docs and planning category.

A complete starter stack

• diagram-design for branded diagrams in docs, posts and slides.
• design-doc-mermaid for diagrams that live as text in the repo, inside a design doc.
• excalidraw-diagram-generator for sketches a teammate will edit by hand.

Common pitfalls

• Skipping onboarding. The default palette is jet black with an orange accent, which will clash with most brand sites.
• Asking for a diagram when a table is better. The README itself says lists and before/after comparisons belong in a table.
• Importing a 40-node draw.io file at faithful detail for a slide. Use --detail=simplified --size=slide-16x9 and read the fidelity ledger.

Install it once, onboard your site, and your next architecture sketch will look like it belongs in your docs.

Common questions