graph-generation

name

graph-generation

description

ALWAYS use this skill when the user asks to create, draw, design, produce, or generate any visual asset that is not a photograph or illustration. Fires on words like diagram, chart, graph, flowchart, architecture, system map, topology, sequence diagram, state machine, class diagram, ER diagram, C4, UML, BPMN, mind map, org chart, wireframe, mockup, UI sketch, infographic, dashboard, treemap, sankey, heatmap, choropleth, network graph, map, plot, visualization, mermaid, d3, drawio, draw.io, .drawio, or any request to "visualize", "render", "show as a diagram", or produce .drawio / .png / .svg / .pdf architecture artifacts. Fires on domain phrasings like "AWS architecture", "Kubernetes namespaces", "microservices diagram", "identity/auth flow", "repo topology", "dev environment", "system context", "data flow", "pipeline diagram", "network topology", "P&ID", "wiring diagram". Routes to Mermaid for text-based docs diagrams, D3.js for data-driven charts/maps, and Draw.io for architecture/vendor-icon/editable deliverables. This skill enforces a domain-shape search step (for AWS/Azure/GCP/Cisco/Kubernetes/P&ID/electrical/BPMN) and a mandatory edge-routing postprocess step — skipping the skill produces unprofessional diagrams with overlapping edges and generic boxes.

Graph Generation

Step 0 — plan first. Before rendering, run the visual-planning skill: clarify the ask (type, placement, dimensions), lock the palette/style, pin the single message the visual must convey, and confirm the real data.

Generate any chart, graph, diagram, map, or visualization and save it as an image or editable file. This skill supports three rendering engines — pick the right one first, then read that engine's README and pattern file.

How to use this skill

1. Pick the engine using the decision guide below — this is the most important step
2. Read the engine's README for workflow, templates, and best practices:
   • Mermaid → patterns/mermaid/README.md
   • D3.js → patterns/d3/README.md
   • Draw.io → patterns/drawio/README.md
3. Read the specific pattern file (for Mermaid/D3) or the xml-reference.md (for Draw.io)
4. Generate, render, and save

Do not try to memorize engine-specific details from this file — the engine READMEs are the source of truth for workflows.

HARD RULES for Draw.io (must follow, do not skip)

These two rules are why this skill exists. Skipping them produces diagrams that look amateurish — overlapping edges, generic boxes instead of real cloud/k8s icons, visible conflict points. If you write .drawio XML without following them, the output is wrong.

1. Shape search is MANDATORY for any diagram involving AWS / Azure / GCP / Oracle / Cisco / Kubernetes / P&ID / electrical / BPMN / rack equipment / Ory / Traefik / NATS / Postgres / Docker / any branded technology. Before writing XML, call:

   node ${CLAUDE_PLUGIN_ROOT}/skills/graph-generation/patterns/drawio/shape-search/search.js "<terms>"
   

   Use the returned style string verbatim and the returned w/h as the mxGeometry dimensions. Generic rounded=0;whiteSpace=wrap;html=1; rectangles are NOT acceptable for these domains. Skip shape search only for plain flowcharts, UML, ERD, org charts, mind maps, or when the user explicitly asks for "simple shapes".

2. Postprocessing is MANDATORY for every .drawio file written to disk. After writing, run:

   node ${CLAUDE_PLUGIN_ROOT}/skills/graph-generation/patterns/drawio/postprocessor/postprocess.js <file> <file>
   

   This is handled automatically by a PostToolUse hook on Write, so in most cases you don't need to run it manually — but verify the file was processed (the hook prints a before/after report). If the hook did not run, invoke the script yourself. Approach A (MCP open_drawio_xml) already runs this server-side; no manual step needed there.

Neither rule applies to Mermaid or D3.

When to Use What Engine

Engine	Pick when the user needs...	Avoid when...
Mermaid	Quick text-based software diagrams for docs or PRs (flowcharts, sequence, state, ER, class, Gantt, C4). Output embedded in markdown (GitHub, Notion, MkDocs) using fenced ```mermaid blocks. Simple/standard shapes where layout can be auto-generated. Diagrams that live in source control as plain text.	User needs vendor icons (AWS, Azure, GCP, Cisco), pixel-perfect manual layout, UI mockups, or data-driven charts.
D3.js	Data-driven visualizations — bar/line/pie/scatter/heatmap charts, choropleth/marker maps, network/force graphs, treemaps, sankey, candlesticks, infographics (timelines, stat dashboards), custom visual layouts matched to a specific website's theme. Anything requiring binding numerical data to visual attributes.	User wants a "diagram" of boxes and arrows — use Mermaid or Draw.io.
Draw.io	Professional architecture diagrams with vendor shape libraries (AWS, Azure, GCP, Kubernetes, Cisco, etc.). UI/UX mockups and wireframes. Diagrams the user will open and edit later in a GUI. Formal deliverables needing polished PNG/SVG/PDF output with embedded editable source. Complex diagrams requiring manual positioning.	A quick throwaway diagram would do — Mermaid is faster. Data visualization with numeric input — use D3.

Rule-of-thumb decision tree

Is the output a data-driven chart (axes, scales, data points)?
  → D3.js

Is it a software/system diagram that fits in markdown as plain text?
  → Mermaid

Does it need vendor icons, manual layout polish, UI mockups, or
later editing by the user in a GUI?
  → Draw.io

Cross-reference: diagram type → engine

If the user asks for...	Default engine	Notes
Flowchart in a README/PR	Mermaid	Text-based, version-controllable
Flowchart for a client deliverable	Draw.io	Polished output, vendor icons if needed
AWS/Azure/GCP architecture	Draw.io	Native cloud shape libraries
Microservices/container diagram	Mermaid C4 (simple) or Draw.io (polished)	Mermaid for docs, Draw.io for decks
Sequence / API interaction	Mermaid	Auto-layout works well here
ER / database schema	Mermaid (docs) or Draw.io (manual control)
State machine / lifecycle	Mermaid
Class diagram	Mermaid
Network topology with Cisco icons	Draw.io	Only Draw.io ships Cisco shape lib
UI mockup / wireframe	Draw.io	Mockup shape library
Bar/line/pie/scatter/heatmap	D3.js
Choropleth / location map	D3.js
Treemap / sankey / network graph	D3.js
Candlestick / OHLC financial	D3.js
Timeline / stat dashboard infographic	D3.js	For infographics specifically (stat panels, "how it works", comparisons), first consult visual-planning's references/infographic-design.md for layout/hierarchy/labeling principles.

How each engine renders (1-liner)

Engine	Output	Rendering
Mermaid	PNG (or inline markdown)	Self-contained HTML with mermaid.js CDN → Playwright MCP screenshot at high DPI
D3.js	PNG or SVG	Self-contained HTML with D3 CDN → Playwright MCP screenshot at high DPI
Draw.io	.drawio, .drawio.png/svg/pdf	Native mxGraphModel XML → draw.io CLI export (with embedded editable XML), or MCP opens in editor

Universal quality rule

Whatever engine you pick, the output must be high-resolution (at least 2x DPI for PNG) and theme-matched to the context where it will be displayed (light docs, dark websites, branded decks). All three engine READMEs cover their respective high-DPI / theming settings.

After generating: post-process & verify the SVG

When the engine emits SVG (D3 or Draw.io export), hand it to svg-mastery to optimize, validate, animate, recolor, or embed it correctly:

• Shrink and clean the output, namespacing IDs to avoid collisions when inlining → svg-mastery/references/optimization.md.
• Confirm it's well-formed and renders right before shipping → svg-mastery/references/validation-and-qa.md (the render-and-inspect loop).
• For a bespoke layout no D3 pattern covers, svg-mastery's references/custom-layouts.md hand-composes it.