Best For
Anyone who needs high-quality diagrams in their Claude Code workflow. Specifically:
- Technical documentation authors who need architecture diagrams, flowcharts, and sequence diagrams
- Research and science writers who need visuals that look professional in published documents
- Developers who want to upgrade from Mermaid to something with higher visual output quality
- Designers and engineers with brand guidelines who need diagrams that match their website color system
If you only need rough drafts, Mermaid is sufficient. If your diagrams will appear in reports, presentations, or public-facing documents, the visual quality difference is visible.
How I Actually Use It
diagram-design addresses a problem you may not have named yet: AI-generated diagrams usually look like AI-generated diagrams.
The design philosophy has one core rule: "every node must earn its place." If removing it causes no information loss, remove it. Accent color is reserved for the one or two most important elements. All coordinates are divisible by 4 (to prevent AI aesthetic drift). These are not style preferences — they are systematic countermeasures against the specific ways AI-generated visuals tend to degrade.
The 13 diagram types cover almost everything technical documentation requires: Architecture, Flowchart, Sequence, State Machine, ER, Timeline, Swimlane, Quadrant, Nested, Tree, Layers, Venn, Pyramid. Each ships with three visual variants. Output is self-contained HTML+SVG, opens directly in a browser, and requires no build tools or external dependencies.
The brand onboarding feature is the standout. Give it a website URL, and it extracts the CSS color system, maps it to paper/ink/muted/accent semantic tokens, and applies it to every subsequent diagram. 1,127 stars, and maintainer Cathryn Lavery is actively updating the repository.
Where It Is Strong
- 13 diagram types x 3 visual variants. Covers almost all diagram needs in technical documentation, with output quality meaningfully above Mermaid.
- Provide a website URL and the color system is extracted and applied automatically, with WCAG AA contrast verification.
- Self-contained output: HTML+SVG, no dependencies, no build step. Paste anywhere.
- Node minimalism, strict accent color limits, coordinates forced to multiples of 4. These rules make the output look intentionally designed.
- MIT license, one-line install:
npx skills add cathrynlavery/diagram-design
Where It Fails
- Static SVG only, not interactive charts. Zoomable, filterable dynamic visuals require a different tool.
- The design philosophy favors minimalism; complex relationship diagrams with dozens of nodes may require manual layout adjustments.
- Brand extraction depends on CSS regularity: If a target website's color definitions aren't in CSS variables or predictable locations, automatic extraction results will vary.
Pricing, Difficulty, and Risk
Free and open source under MIT. Low difficulty: after installation, describe the diagram you need in Claude Code and the skill handles the rest. No API costs, no external service dependencies.
Verdict
The upgrade path from Mermaid. Mermaid is fast but has a visual quality ceiling; diagram-design is slightly slower but produces output that can go directly into formal documents without adjustment.
If you need diagrams that look designed rather than generated, this is the most complete option in Claude Code right now. The brand onboarding feature makes it especially useful for organizations or personal brands with established design systems.