SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsdiagram

diagram

Design & creation

View repository

Updated 10-15 10:20

About this skill

Diagram Skill

Describe your requirements in natural language, and automatically generate professional PNG diagrams that can be directly embedded into Markdown documents.

Step 1: Analyze the content topology and choose the representation method

Philosophy: the content'stopological formdetermineswhich diagrams can express it, while the readers and scenario determinewhich one to choose from them. Don't start by asking "what kind of diagram is this"—first look at what the content looks like.

1.1 Content topology identification

Classify by the content'sstructural form—the same topology may map tomultiple diagram types：

Topological Form Identification Signals Expressible Diagram Types
Linear sequence A → B → C, single path, steps, stages, process Flowchart (linear), sequence diagram, timeline, Gantt chart
Multi-source convergence / DAG Multiple entrances, multiple exits, dependencies, resource flow Flowchart (DAG), data flow diagram, network diagram, Sankey diagram
Layered stacking Hierarchy, technology stack, containerization, levels of abstraction Architecture diagram, C4 diagram
Role collaboration Multi-role / cross-system / cross-service interaction Swimlane diagram, sequence diagram, C4 system view
Entity relationships Database tables, object relationships, field mapping ER diagram, class diagram
State transition State machine, lifecycle, concurrency, git branches State diagram, Git Graph
Tree structure Decision-making, organization, knowledge hierarchy, menu hierarchy Decision tree, organization chart, mind map
Matrix / multi-dimensional evaluation Multi-dimensional comparison, four-quadrant classification, coverage relationships Heatmap, radar chart, SWOT, Venn diagram, treemap
Numerical comparison Discrete comparison, proportion, cumulative increase/decrease Bar chart, pie chart, funnel chart, waterfall chart
Trend change Time series, version evolution, trends Line chart, combined bar-line chart
Distribution relationships Scatter, clustering, correlation Scatter plot (including bubble)
Stage task management Kanban, to-do, stage transitions Kanban, Gantt chart
Root cause analysis Multi-factor attribution, defect tracing Fishbone diagram
User experience journey Touchpoints, emotional curve Journey map

1.2 For the same topology, which diagram should be chosen?

The same topology may have multiple expressions—make the final choice based onthe reader + scenario + emphasis:

Judgment dimension Selection preference
The reader is a developer Prioritize DAG-type contentflowchart/data flow diagram(high information density), do not use Sankey diagrams
The reader is a reviewer/management For flow-type content chooseSankey diagram(visual impact), for layering choose C4 container view
Screen presentation Favor visual impact:Sankey diagram, radar chart, timeline, mind map
Embedded document Favor information density:flowchart, ER diagram, table-style structure diagram
Emphasize action sequence sequence diagram > flowchart
Emphasize containerization / boundaries C4 > architecture diagram
Emphasize hierarchical relationships architecture diagram > C4
Data comparison is primary For discrete usebar chart, for trends useline chart, for proportions usepie chartortreemap
Data dimensions ≥ 3 radar chart、heatmaporscatter plot
Multi-branch decision logic decision tree > flowchart
Single-branch linear process flowchart (linear)

1.3 Mermaid / Graphviz markup language conversion

When ```mermaid or ```dot code blocks are found in Markdown:

  1. Interpretthe diagram structure (nodes, edges, labels, types, groups, etc.)
  2. Mapto the corresponding chart type template data structure
  3. Renderas PNG with unified design specifications
  4. Replacethe original text block with an image reference

Mapping rules:

Source format Keyword/Syntax Mapping target
Mermaid graph TD / flowchart Nodes + arrows flowchart template
Mermaid sequenceDiagram Participants + messages sequence template
Mermaid classDiagram Classes + relationships class template
Mermaid stateDiagram States + transitions state template
Mermaid erDiagram Entities + relationships er template
Mermaid gantt Tasks + dates gantt template
Mermaid pie Labels + values pie template
Mermaid journey Stages + scores journey template
DOT digraph Directed graph flowchart / state / class (determine by structure)
DOT graph Undirected graph er / network (determine by structure)

Note: It does not call the Mermaid/Graphviz tools to render; instead, Claude understands the graph structure described by the markup language, converts it into our template data, and renders it using a unified design specification. This way, all diagrams have a consistent style.

1.4 Diagram Types → Layout/Specification Index

1.1-1.2 determinewhich diagram type to use, and the table below is theretrieval entry point for layout strategies and dedicated specifications—it is not a "content → choose type" decision table (the decision has already been made in 1.1-1.2).

Diagram Type Typical Scenario Layout Strategy Dedicated Specification
Flowchart (Linear) Workflow, decision logic (single path) Manual layout references/diagrams/flowchart.md
Flowchart (DAG) Multi-source convergence, resource flow, relationship diagram ELKjs references/diagrams/flowchart.md
Swimlane Diagram Multi-role collaborative process Manual grid references/diagrams/swimlane.md
Sequence Diagram API calls, message interactions Custom sequential stacking references/diagrams/sequence.md
Architecture Diagram System layering, tech stack Manual layer stacking references/diagrams/architecture.md
ER Diagram Database table structure ELKjs references/diagrams/er.md
Class Diagram Object-oriented design ELKjs references/diagrams/class.md
State Diagram State transitions ELKjs references/diagrams/state.md
Network Diagram Network topology Manual layering references/diagrams/network.md
Decision Tree Selection decision Tree layout references/diagrams/decision-tree.md
Data Flow Diagram Data pipeline Manual layering references/diagrams/dataflow.md
C4 Diagram C4 system view Manual layering references/diagrams/c4.md
Mind Map Knowledge structure Bilateral tree references/diagrams/mindmap.md
Gantt Chart Project scheduling Date-axis grid references/diagrams/gantt.md
Timeline Development history Vertical list references/diagrams/timeline.md
Organizational Chart Organizational structure Tree references/diagrams/orgchart.md
SWOT Diagram Strengths and weaknesses analysis Four-quadrant cards references/diagrams/swot.md
Fishbone Diagram Root cause analysis Fishbone skeleton references/diagrams/fishbone.md
Venn Diagram Set relationships Overlapping circles references/diagrams/venn.md
Journey Map User experience Horizontal cards references/diagrams/journey.md
Bar Chart Discrete comparison Cartesian coordinates references/diagrams/bar-chart.md
Line Chart Trend changes Cartesian coordinates references/diagrams/line-chart.md
Pie Chart Proportional composition Radial references/diagrams/pie-chart.md
Radar Chart Multi-dimensional evaluation Radial references/diagrams/radar-chart.md
Heatmap Matrix data Grid references/diagrams/heatmap.md
Sankey Diagram Flow paths Flow-band layering references/diagrams/sankey.md
Scatter Plot Distribution relationship Cartesian coordinates references/diagrams/scatter.md
Treemap Data proportion / hierarchy area Squarified references/diagrams/treemap.md
Bar-line combo chart Bar + line combo Cartesian dual Y-axis references/diagrams/combo.md
Kanban Project management / task board Vertical column cards references/diagrams/kanban.md
Git Graph Git branch workflow Horizontal branch lines references/diagrams/git-graph.md

Step 2: Read the specification, generate the chart

2.1 Specification system

  • Common specifications references/design-system.md — color scheme, fonts, components, spacing
  • Common utilities references/diagram-utils.md — SVG utility functions, text measurement, collision detection
  • Dedicated specifications references/diagrams/<type>.md — data structure, layout rules, rendering details for each chart type

2.2 Layout strategy

Chart layout comes in two types:

ELKjs automatic layout(ER diagram, class diagram, state diagram, flowchart DAG mode):

  • Reference lib/elk.bundled.js
  • Define the ELK graph structure (nodes + edges)
  • elk.layout(graph).then(result => { /* 渲染 */ })
  • Note: ELKjs is asynchronous, so put all rendering code inside the .then() callback

Manual layout(flowchart, swimlane diagram, architecture diagram, sequence diagram, etc.):

  • Calculate coordinates according to the domain rules of the chart type
  • Flowchart: main path goes down, "No" branch goes right
  • Swimlane diagram: column × row grid, swimlanes have a fixed row order
  • Architecture diagram: predefined layers stacked from top to bottom
  • Sequence diagram: participants arranged horizontally at equal distances, messages stacked vertically

2.3 Generation workflow

1. 读取专属规范 → 了解数据结构和布局规则
2. 定义数据（nodes/edges/steps/tables 等）
3. 计算布局坐标（ELKjs 或手动）
4. 渲染 SVG（节点 → 连线 → 标签，按层级顺序）
5. 写入 HTML 文件（含内联 JS + CSS）
6. 用 capture.py 截图 → PNG（禁止手动调用 Playwright）

2.4 HTML template structure

All templates follow a unified structure:

<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<style>
  * { margin: 0; padding: 0; box-sizing: border-box; }
  body {
    font-family: -apple-system, system-ui, 'PingFang SC', sans-serif;
    background: #ffffff;
    padding: 24px;
    display: inline-block;  /* 关键：画布收缩包裹内容 */
  }
</style>
<!-- ELKjs 仅在 ER/类图/状态图中引入 -->
<script src="lib/elk.bundled.js"></script>
</head>
<body>
<svg id="canvas"></svg>
<script>
(function() {
  // 1. 数据定义（title, subtitle, nodes, edges 等）
  // 2. 主题定义（colors, fonts, spacing）
  // 3. 工具函数（el, measureText）
  // 4. 布局计算（ELKjs 或手动）
  // 5. 渲染（背景层 → 连线层 → 节点层 → 标签层）
})();
</script>
</body>
</html>

2.5 Title specifications

The default title behavior depends on the calling scenario— but remember: title, subtitle, top label bar, bottom legend, node icons, etc. are allstackable independent components, not "mandatory for review grade". For the complete component list and trigger conditions, see references/diagrams/review-grade.md。

Calling scenario Default behavior
User directly requests a chart Title + subtitle (normal size)
deep-research report illustration No title, the section heading takes on that role
writing skill illustration embedded in a document No title, the section heading takes on that role
writing skill roadshow / review HTML illustration Large title + subtitle on by default,other stackable components evaluated based on content(see review-grade.md)
User explicitly says "make a review version / roadshow chart" Enter the review-grade evaluation workflow,judge component by componentwhether to stack
User explicitly says "no title" Skip title rendering

Rendering parameters：

  • title is an empty string or null when it is, skip title rendering and set the title area height to 0
  • Normal title: top-left (x=0, y=18), 16px bold, color #1a1a2e, title area 52px
  • Normal subtitle: 12px, color #888888，y=36
  • Large title (review-grade.md II.1): 22px Bold (readable from a distance when projected), title area ≥ 70px
  • Large subheading (review-grade.md Section II.2): 14px Regular

Important Principle: Being called by the writing roadshow HTML ≠ all overlay components must be enabled. Each item still needs to be evaluated according to the content form; simple diagrams should be drawn simply.

// 标题可选的标准写法
var TITLE_AREA_H = title ? 52 : 0;

// 渲染时条件判断
if (title) {
  nodeGroup.appendChild(el('text', { ... })).textContent = title;
  if (subtitle) nodeGroup.appendChild(el('text', { ... })).textContent = subtitle;
}

Step 3: Output Specification

3.1 File Format

PNG (default) — for Markdown document illustrations:

  • Background: white #FFFFFF
  • Padding on all sides: at least 24px
  • Scaling: native device DPI (Retina devices automatically output 2x sharp images)

HTML (optional) — for rich document embedding and interactive display:

  • Self-contained: all CSS/JS inlined, no external dependencies, a single file can be opened directly in a browser
  • Vector: SVG scales losslessly, text can be selected/searched
  • Use cases: embedding in HTML reports, creating interactive architecture documents, diagrams that need further editing
  • Generation method:python scripts/capture.py input.html -f html

DSL (optional) — for embedding in Markdown documents, where text can be diffed and version-controlled:

  • Structure diagrams + some statistical charts support Mermaid DSL output
  • Output as plain text in Mermaid syntax
  • Use cases: MD document illustrations where you do not want to maintain PNG files, need real-time rendering with preview-md, or native rendering on GitHub/GitLab
  • Generation method: directly output text, and the user copies it into a code block in the MD file

DSL selection rules:

Chart Type DSL Code Block Marker
flowchart / sequence / class / state / er Mermaid ```mermaid
gantt / mindmap / timeline / c4 / sankey / journey Mermaid ```mermaid
architecture / swimlane / network / dataflow / orgchart / decision-tree Mermaid（flowchart + subgraph） ```mermaid
bar / line (bar chart, line chart) Mermaid（xychart-beta） ```mermaid
pie (pie chart) Mermaid ```mermaid
radar / heatmap / scatter / funnel / waterfall, etc. DSL not supported Continue using PNG
quadrant / gitGraph / block Not supported yet To be opened up later as needed

DSL output format example:

用户：画一个用户登录的流程图，输出 mermaid

输出：
` ` `mermaid
flowchart TD
    A[用户访问登录页] --> B{已有账号?}
    B -->|是| C[输入用户名密码]
    B -->|否| D[跳转注册页]
    C --> E{验证通过?}
    E -->|是| F[跳转首页]
    E -->|否| G[提示错误]
    G --> C
` ` `

用户：画一个微服务架构图，输出 mermaid

输出：
` ` `mermaid
flowchart TD
    subgraph 网关层
        nginx[Nginx 负载均衡] --> api_gw[API Gateway]
    end
    subgraph 服务层
        user_svc[用户服务]
        order_svc[订单服务]
        pay_svc[支付服务]
    end
    subgraph 数据层
        mysql[(MySQL)]
        redis[(Redis)]
    end
    api_gw --> user_svc & order_svc & pay_svc
    user_svc --> mysql
    order_svc --> mysql
    pay_svc --> redis
` ` `

3.2 Screenshot Method

You must use the established scripts; manually calling Playwright MCP tools to take screenshots is prohibited.

# 结构图：HTML → PNG
python ~/.claude/skills/diagram/scripts/capture.py <HTML文件> <输出路径>.png

# 结构图：HTML → 自包含 HTML
python ~/.claude/skills/diagram/scripts/capture.py <HTML文件> <输出路径>.html -f html

# 统计图：JSON → PNG（bridge.py 内部自动截图）
python ~/.claude/skills/diagram/scripts/bridge.py -c <配置>.json -o <输出路径>.png

# 统计图：JSON → 自包含 HTML
python ~/.claude/skills/diagram/scripts/bridge.py -c <配置>.json -o <输出路径>.html -f html

Why can't I take screenshots manually? capture.py / bridge.py already encapsulate logic such as starting the HTTP service, ELKjs asynchronous waiting, Retina 2x output, and body element positioning. Manually using browser_run_code / browser_take_screenshot easily misses the waiting logic, resulting in blank or blurry screenshots.

3.3 File Naming

<图表类型>-<描述>.png(lowercase English + hyphens)

3.4 Storage Location

  • Default: the assets/ or images/ directory at the same level as the caller's Markdown file
  • When called by deep-research:docs/research/assets/

Tool Dependencies

Tool Location Purpose
capture.py scripts/capture.py Structure diagram HTML → PNG/HTML (internally calls Playwright)
bridge.py scripts/bridge.py Statistical chart JSON → PNG/HTML (internally calls Playwright)
ELKjs lib/elk.bundled.js(already inlined) Automatic layout for ER diagrams/class diagrams/state diagrams/flowchart DAGs

Playwright is only used as the internal implementation of capture.py / bridge.py, do not directly call Playwright MCP tools (browser_navigate、browser_take_screenshot、browser_run_code , etc.) to take screenshots.

ELKjs Usage Instructions

ELKjs is only used forfree graph layout(scenarios where the positions of nodes and edges need algorithmic optimization). The following chart typesdo not use ELKjs：

  • Flowchart Linear mode(Domain rule: main path goes downward, No branch goes right)
  • Swimlane diagram (Domain rule: swimlanes have a fixed row order)
  • Architecture diagram (Domain rule: hierarchy is predefined)
  • Sequence diagram (Domain rule: participants are arranged horizontally, messages vertically)

Reason: These diagrams have explicit domain layout rules, and ELKjs's automatic optimization would break these rules (such as reordering swimlanes or changing group positions).

Exception: The flowchart's DAG mode(multiple root nodes, convergence, non-decision branches) uses ELKjs, because such topologies cannot be manually laid out with a simple "main path + side branches" approach. See references/diagrams/flowchart.md。

Notes on flowchart DAG mode

  • Faithfully reproduce the topology: Never add connections that do not exist, and multiple independent entry points must not be forced under the same root node
  • Node types faithfully reflect the original diagram: Nodes at the same level or with the same role use the same type.highlight It is only used for nodes explicitly marked as critical/core in the original diagram; do not use it to distinguish "different categories"—express category differences with process/external/datastore and other semantic types