Converts BPMN 2.0 XML to PNG diagram images. Use when user provides BPMN XML content or file path and asks to visualize, render, or create a diagram from a BPMN process definition.
apm install @mattnigh/bpmn-diagram
[](https://apm-p1ls2dz87-atlamors-projects.vercel.app/packages/@mattnigh/bpmn-diagram)---
name: bpmn-diagram
description: Converts BPMN 2.0 XML to PNG diagram images. Use when user provides BPMN XML content or file path and asks to visualize, render, or create a diagram from a BPMN process definition.
---
# BPMN Diagram Skill
This skill converts BPMN 2.0 XML into PNG diagram images using the bpmn-js rendering toolkit.
## Prerequisites
Before first use, ensure dependencies are installed:
```bash
cd ~/.claude/skills/bpmn-diagram/scripts && ./setup.sh
```
Or for project-local skills:
```bash
cd .claude/skills/bpmn-diagram/scripts && ./setup.sh
```
## Usage
### Input Formats
The skill accepts BPMN 2.0 XML in two ways:
1. **File path**: Path to an existing `.bpmn` or `.xml` file
2. **Inline XML**: Raw BPMN XML content provided directly
### Rendering a Diagram
**From a file:**
```bash
node scripts/render-bpmn.js /path/to/diagram.bpmn /path/to/output.png
```
**From inline XML:**
1. First, write the BPMN XML to a temporary file
2. Then run the render script
3. The PNG will be created at the specified output path
### Script Options
| Option | Description | Default |
|--------|-------------|---------|
| `--scale=N` | Image scale factor (e.g., 2 for 2x resolution) | 1 |
| `--min-dimensions=WxH` | Minimum output dimensions in pixels | 800x600 |
**Example with options:**
```bash
node scripts/render-bpmn.js input.bpmn output.png --scale=2 --min-dimensions=1200x800
```
## Workflow
When a user requests a BPMN diagram:
1. **Identify the input**: Determine if XML is inline or in a file
2. **Validate the XML**: Check for valid BPMN 2.0 structure
- Must have `<definitions>` root element with BPMN namespace
- Should contain `<bpmndi:BPMNDiagram>` for visual layout
3. **Prepare input file**: If inline XML, write to a temp `.bpmn` file
4. **Execute render script**: Run `node scripts/render-bpmn.js`
5. **Report result**: Provide the output PNG path to the user
## BPMN 2.0 XML Structure
Valid BPMN 2.0 XML must follow this structure:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<definitions
xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"
xmlns:dc="http://www.omg.org/spec/DD/20100524/DC"
xmlns:di="http://www.omg.org/spec/DD/20100524/DI"
id="Definitions_1"
targetNamespace="http://bpmn.io/schema/bpmn">
<!-- Process definition -->
<process id="Process_1" isExecutable="false">
<!-- BPMN elements: events, tasks, gateways, flows -->
</process>
<!-- Diagram interchange (visual layout) -->
<bpmndi:BPMNDiagram id="BPMNDiagram_1">
<bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="Process_1">
<!-- Shape and edge definitions for visual rendering -->
</bpmndi:BPMNPlane>
</bpmndi:BPMNDiagram>
</definitions>
```
## Error Handling
| Error | Cause | Solution |
|-------|-------|----------|
| "Not valid XML" | Malformed XML syntax | Check XML structure, escape special characters |
| "Not BPMN 2.0 format" | Missing `<definitions>` root | Ensure proper BPMN namespace and root element |
| "No diagram layout" | Missing `<bpmndi:BPMNDiagram>` | Add diagram interchange section or use auto-layout |
| "Render failed" | Canvas/dependencies issue | Ensure setup.sh was run, check system dependencies |
| "File not found" | Invalid input path | Verify file path exists |
## Known Limitations
This skill uses a pure Node.js rendering approach with jsdom and canvas, which has some limitations compared to browser-based rendering:
1. **SVG Transform Positioning**: Some complex transform operations may not be perfectly positioned
2. **Text Rendering**: Font rendering depends on system fonts available
3. **Complex Diagrams**: Very large or complex diagrams may have rendering artifacts
For production use with complex diagrams, consider:
- Using `bpmn-to-image` with Puppeteer (requires Chrome/Chromium)
- Running the rendering in an actual browser environment
## Common BPMN Elements
See `references/bpmn-elements.md` for a complete reference of supported BPMN 2.0 elements.
### Quick Reference
**Events:**
- `startEvent`, `endEvent`, `intermediateCatchEvent`, `intermediateThrowEvent`
**Activities:**
- `task`, `userTask`, `serviceTask`, `scriptTask`, `sendTask`, `receiveTask`
- `subProcess`, `callActivity`
**Gateways:**
- `exclusiveGateway` (XOR), `parallelGateway` (AND), `inclusiveGateway` (OR)
- `eventBasedGateway`, `complexGateway`
**Flows:**
- `sequenceFlow`, `messageFlow`, `association`
**Swimlanes:**
- `participant` (Pool), `lane`
## Example
**Input (simple-process.bpmn):**
```xml
<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"
xmlns:dc="http://www.omg.org/spec/DD/20100524/DC"
id="Definitions_1">
<process id="Process_1" isExecutable="false">
<startEvent id="Start_1" name="Start"/>
<task id="Task_1" name="Do Something"/>
<endEvent id="End_1" name="End"/>
<sequenceFlow id="Flow_1" sourceRef="Start_1" targetRef="Task_1"/>
<sequenceFlow id="Flow_2" sourceRef="Task_1" targetRef="End_1"/>
</process>
<bpmndi:BPMNDiagram id="BPMNDiagram_1">
<bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="Process_1">
<bpmndi:BPMNShape id="Start_1_di" bpmnElement="Start_1">
<dc:Bounds x="152" y="102" width="36" height="36"/>
</bpmndi:BPMNShape>
<bpmndi:BPMNShape id="Task_1_di" bpmnElement="Task_1">
<dc:Bounds x="240" y="80" width="100" height="80"/>
</bpmndi:BPMNShape>
<bpmndi:BPMNShape id="End_1_di" bpmnElement="End_1">
<dc:Bounds x="392" y="102" width="36" height="36"/>
</bpmndi:BPMNShape>
<bpmndi:BPMNEdge id="Flow_1_di" bpmnElement="Flow_1">
<di:waypoint x="188" y="120"/>
<di:waypoint x="240" y="120"/>
</bpmndi:BPMNEdge>
<bpmndi:BPMNEdge id="Flow_2_di" bpmnElement="Flow_2">
<di:waypoint x="340" y="120"/>
<di:waypoint x="392" y="120"/>
</bpmndi:BPMNEdge>
</bpmndi:BPMNPlane>
</bpmndi:BPMNDiagram>
</definitions>
```
**Command:**
```bash
node scripts/render-bpmn.js simple-process.bpmn simple-process.png
```
**Output:** `simple-process.png` - A PNG image of the rendered BPMN diagram