diagram

Generates diagrams with Mermaid, D2, Graphviz, and SVG using a render-and-review feedback loop.

1|1|Updated Nov 25, 2024
One-click install
npx skills add https://github.com/joeledwardson/dev-setup --skill diagram-joeledwardson
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: diagram
Source: https://github.com/joeledwardson/dev-setup/tree/main/configs/claude/skills/diagram
Command: npx skills add https://github.com/joeledwardson/dev-setup --skill diagram-joeledwardson

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? LLMs reliably produce diagram source code but rarely produce diagrams that actually look good without seeing the rendered output. This Skill closes that gap with a generate → render → view PNG → critique → iterate loop, so flowcharts, matrices, and architecture diagrams come out readable instead of tall, clipped, or illegible. ## Core Features & Use Cases - Tool selection by data shape: Picks the right renderer for the data — Mermaid for flows and quadrant charts, D2 for grids and matrices, Graphviz for dependency graphs, raw SVG for precise custom layouts. - Render-and-review loop: Renders source to PNG at a fixed 1200×800 viewport, scores it against a rubric (aspect ratio, text clipping, legibility, colour contrast, overlaps), and iterates up to 3 times before switching tools. - Dark-theme and mkdocs fixes: Built-in rules for dark-theme Mermaid rendering, classDef colour palettes with verified contrast, and known workarounds for broken C4 layout, subgraph styling, and invisible edge labels. - Use Case: A user asks to visualize a buyer-segmentation table. Instead of defaulting to a tall flowchart TD, the Skill switches to D2 with grid-columns: 3, renders at 1200×900, colour-codes by priority, and delivers a readable matrix. ## Quick Start Ask the assistant to create a flowchart or architecture diagram of your system and have it render and review the output until it is readable.

Frequently Asked Questions about diagram

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate a Mermaid diagram that renders correctly?

Generate the Mermaid source, render it to PNG with mmdc at a fixed viewport (mmdc -i file.mmd -o file.png -w 1200 -H 800 -t dark), then read the PNG back and critique it against a rubric. Iterate on the source until aspect ratio, text clipping, and legibility all pass.

Mermaid vs D2 vs Graphviz — which tool for which diagram?

Use Mermaid for flows, sequences, state machines, quadrant charts, and mind maps. Use D2 with grid-columns for matrices and parallel categories, and Graphviz DOT for dependency graphs needing strong auto-layout. Use raw SVG only for precise custom layouts.

Why is my Mermaid flowchart rendering as a tall narrow image?

A very tall output (e.g. 350×2800) usually means flowchart TD was used for non-flow data with too many sequential nodes. Switch to flowchart LR, use D2 with grid-columns, or restructure the data as a matrix instead of a flowchart.

Why is text cut off or unreadable in my Mermaid diagram?

Text clipping comes from markdown like **bold** or <b> inside node labels, long unbroken words, or em-dashes that Mermaid mismeasures. Remove inline markdown, use <br/> for line wraps, and replace em-dashes with hyphens.

Does Mermaid dark theme work with mkdocs-material sites?

Yes, but you must add %%{init: {'theme': 'dark'}}%% as the first line of every Mermaid block. Also avoid subgraphs and edge labels in dark theme, since their default backgrounds render as near-invisible dark-on-dark; use classDef colour coding instead.

When should I not use this diagram generation approach?

Do not use it for numeric data plots (use matplotlib or plotly), code call graphs (use madge or pydeps), or real-time dashboards. It is designed for static conceptual diagrams, not data-driven or live visualizations.