Turning Content into Clean Diagrams (Diagram Design)

The user gives you a long piece of text, a process or a set of knowledge points, and you draw it as a tidy, well-designed diagram. Underneath, it uses the open-source diagram-design (MIT license, by Cathryn Lavery): 45 chart types. The output is a single self-contained HTML file (with inline SVG), which opens by double-clicking in a browser and can also be exported as SVG or PNG.

Its style is restrained: one accent color used only in the one or two most important places, thin-line borders, no shadows, and all coordinates land on a 4-pixel grid.

When to Use

The user wants content turned into a diagram: architecture diagrams, flowcharts, sequence diagrams, state machines, database structures, timelines, swimlane diagrams, quadrant charts, radar charts, Sankey diagrams, Gantt charts, kanban boards, user journeys, dependency graphs, and so on; or they want an existing Mermaid, draw.io or Excalidraw diagram redrawn to look better; or they want the chart to use their own website's colors and fonts.

First, Judge Whether It Is Worth Drawing

Before drawing, ask: will the reader learn more from the diagram than from a well-written paragraph? If not, don't draw it. The repository explicitly recommends not using it in these cases:

• A diagram kept in Git that changes every iteration: use Mermaid, which can show diffs and GitHub renders it directly.
• A "diagram" with only one box: just write a sentence.
• Just a list: use a table or bullet points.
• Before-and-after comparisons: use a table.

Hard Rules

1. Stay faithful to the user's content. Do not invent nodes, numbers, percentages or causal relationships. If data is missing, ask, or leave a placeholder, but do not fill it in.
2. State the plan before drawing. Before starting, explain which chart type you'll choose, what size, and what you plan to cut, then draw. A good diagram comes from subtraction: every node must have a reason to exist.
3. Only visit the website the user specifies. When extracting brand colors and fonts, fetch only the URL the user gives; if the user hasn't mentioned one, don't fetch anything.
4. Disclose network requests. By default, generated diagrams load fonts from Google Fonts, which is the only network request. If the user needs fully offline use, switch to system fonts.
5. Do not overwrite existing files. Output goes in the project folder; if a file with the same name already exists, rename it or ask first.
6. Tell the user before installing. npx skills add installs third-party skills onto the user's computer, so tell the user before running it.

Installation

Check first:

ls ~/.claude/skills 2>/dev/null | grep -i diagram || echo "未安装"

If it is not installed, choose one of two options:

# Option 1: universal install
npx skills add cathrynlavery/diagram-design

# Option 2: install as a plugin in Claude Code (receives updates and includes slash commands)
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

Restart Claude Code once after installing.

Applying the User's Own Brand

The default is an orange-on-black color scheme. The first time you draw in a new project and the style is still the default, ask the user: do a brand adaptation, fill in colors manually, or use the default for now?

How brand adaptation works: the user gives a URL, for example "adapt diagram-design to https://user-site". You fetch that site's primary colors and fonts, map them to roles such as paper color, ink color, secondary color and accent color, list the changes, and once the user agrees, write them into the style file. Before writing, check that text-to-background contrast meets the standard; if it doesn't, propose adjustments.

Common Requests

Help me draw an architecture diagram: frontend, backend, database, Redis cache.

I want a quadrant chart that places Q2 projects by impact and effort.

Turn the core process of this article into a flowchart, keeping no more than 6 steps.

Redraw this Mermaid diagram to look better, for use in a 16:9 slide.

Importing Existing Diagrams

You can redraw existing diagrams from draw.io, Mermaid or Excalidraw in this style: the content stays the same, the styling is unified. It supports .drawio, .mmd and mermaid code blocks in Markdown, as well as .excalidraw scene files. You can specify a size (such as a 16:9 slide) and a level of detail (faithful to the original, balanced, or simplified). For the specific command format, see the import section of the repository README.

Export

The default output is HTML. To put it into Figma, slides or social cards, use the repository's built-in export command to export SVG or PNG; for usage, see the export section of the README.

Checks After Drawing

• Open the HTML and check for overlapping, clipped or overflowing text.
• Run the repository's self-check script; only output of OK counts as a pass:

python3 skills/diagram-design/scripts/self_check.py your-diagram.html

• Compare the content item by item against the user's original text to confirm nothing extra was added or invented.

Things to Note

• Output quality depends on the model you use; the same prompt may produce a different layout on two runs.
• The output is not an editable source format: there is no text to diff and no canvas to drag boxes on. To change it, have the agent redraw it, or edit the SVG directly.
• For diagrams the user wants to revise repeatedly and keep long-term in a code repository, Mermaid is recommended instead.

Output Format

1. First state which chart type was chosen and why, and what content was removed.
2. Give the file path and note that it can be opened in a browser.
3. State the font source (Google Fonts or system fonts) and the result of the self-check script.
4. List the places that need the user's confirmation: missing data, uncertain relationships.