claude-engineering-plugin/plugins/compound-engineering/skills/excalidraw-png-export/SKILL.md

name, description

name

description

excalidraw-png-export

This skill should be used when creating diagrams, architecture visuals, or flowcharts and exporting them as PNG files. It uses the Excalidraw MCP to render hand-drawn style diagrams locally and Playwright to export them to PNG without sending data to any remote server. Triggers on requests like 'create a diagram', 'make an architecture diagram', 'draw a flowchart and export as PNG', or any request that needs a visual diagram delivered as an image file.

Excalidraw PNG Export

Create hand-drawn style diagrams with the Excalidraw MCP and export them locally to PNG files. All rendering happens on the local machine. Diagram data never leaves the user's computer.

Prerequisites

First-Time Setup

Run the setup script once per machine to install Playwright and Chromium headless:

bash <skill-path>/scripts/setup.sh

This creates a .export-runtime directory inside scripts/ with the Node.js dependencies. The setup is idempotent and skips installation if already present.

Required MCP

The Excalidraw MCP server must be configured. Verify availability by checking for mcp__excalidraw__create_view and mcp__excalidraw__read_checkpoint tools.

File Location Convention

Save diagram source files alongside their PNG exports in the project's image directory. This enables re-exporting diagrams when content or styling changes.

Standard pattern:

docs/images/my-diagram.excalidraw    # source (commit this)
docs/images/my-diagram.png           # rendered output (commit this)

When updating an existing diagram, look for a .excalidraw file next to the PNG. If one exists, edit it and re-export rather than rebuilding from scratch.

Temporary files (raw checkpoint JSON) go in /tmp/excalidraw-export/ and are discarded after conversion.

Workflow

Step 1: Design the Diagram Elements

Translate the user's request into Excalidraw element JSON. Load excalidraw-element-format.md for the full element specification, color palette, and sizing guidelines.

Key design decisions:

• Choose appropriate colors from the palette to distinguish different components
• Use label on shapes instead of separate text elements
• Use roundness: { type: 3 } for rounded corners on rectangles
• Include cameraUpdate as the first element to frame the view (MCP rendering only)
• Use arrow bindings (startBinding/endBinding) to connect shapes

Step 2: Render with Excalidraw MCP

Call mcp__excalidraw__create_view with the element JSON array. This renders an interactive preview in the Claude Code UI.

mcp__excalidraw__create_view({ elements: "<JSON array string>" })

The response includes a checkpointId for retrieving the rendered state.

Step 3: Extract the Checkpoint Data

Call mcp__excalidraw__read_checkpoint with the checkpoint ID to get the full element JSON back.

mcp__excalidraw__read_checkpoint({ id: "<checkpointId>" })

Step 4: Convert Checkpoint to .excalidraw File

Use the convert.mjs script to transform raw MCP checkpoint JSON into a valid .excalidraw file. This handles all the tedious parts automatically:

• Filters out pseudo-elements (cameraUpdate, delete, restoreCheckpoint)
• Adds required Excalidraw defaults (seed, version, fontFamily, etc.)
• Expands label properties on shapes/arrows into proper bound text elements

# Save checkpoint JSON to a temp file, then convert to the project's image directory:
node <skill-path>/scripts/convert.mjs /tmp/excalidraw-export/raw.json docs/images/my-diagram.excalidraw

The input JSON should be the raw checkpoint data from mcp__excalidraw__read_checkpoint (the {"elements": [...]} object). The output .excalidraw file goes in the project's image directory (see File Location Convention above).

For batch exports: Write each checkpoint to a separate raw JSON file, then convert each one:

node <skill-path>/scripts/convert.mjs raw1.json diagram1.excalidraw
node <skill-path>/scripts/convert.mjs raw2.json diagram2.excalidraw

Manual alternative: If you need to write the .excalidraw file by hand (e.g., without the convert script), each element needs these defaults:

angle: 0, roughness: 1, opacity: 100, groupIds: [], seed: <unique int>,
version: 1, versionNonce: <unique int>, isDeleted: false,
boundElements: null, link: null, locked: false

Text elements also need: fontFamily: 1, textAlign: "left", verticalAlign: "top", baseline: 14, containerId: null, originalText: "<same as text>"

Bound text (labels on shapes/arrows) needs: containerId: "<parent-id>", textAlign: "center", verticalAlign: "middle", and the parent needs boundElements: [{"id": "<text-id>", "type": "text"}].

Step 5: Export to PNG

Run the export script. Determine the runtime path relative to this skill's scripts directory:

cd <skill-path>/scripts/.export-runtime && node <skill-path>/scripts/export_png.mjs docs/images/my-diagram.excalidraw docs/images/my-diagram.png

The script:

1. Starts a local HTTP server serving the .excalidraw file and an HTML page
2. Launches headless Chromium via Playwright
3. The HTML page loads the Excalidraw library from esm.sh (library code only, not user data)
4. Calls exportToBlob on the local diagram data
5. Extracts the base64 PNG and writes it to disk
6. Cleans up temp files and exits

The script prints the output path on success. Verify the result with file <output.png>.

Step 5.5: Validate and Iterate

Run the validation script on the .excalidraw file to catch spatial issues:

node <skill-path>/scripts/validate.mjs docs/images/my-diagram.excalidraw

Then read the exported PNG back using the Read tool to visually inspect:

1. All label text fits within its container (no overflow/clipping)
2. No arrows cross over text labels
3. Spacing between elements is consistent
4. Legend and titles are properly positioned

If the validation script or visual inspection reveals issues:

1. Identify the specific elements that need adjustment
2. Edit the .excalidraw file (adjust coordinates, box sizes, or arrow waypoints)
3. Re-run the export script (Step 5)
4. Re-validate

Step 6: Deliver the Result

Read the PNG file to display it to the user. Provide the file path so the user can access it directly.

Troubleshooting

Setup fails: Verify Node.js v18+ is installed (node --version). Ensure npm has network access for the initial Playwright/Chromium download.

Export times out: The HTML page has a 30-second timeout. If it fails, check browser console output in the script's error messages. Common cause: esm.sh CDN is temporarily slow on first load.

Blank PNG: Ensure elements include all required properties (see Step 4 defaults). Missing seed, version, or fontFamily on text elements can cause silent render failures.

"READY" never fires: The exportToBlob call requires valid elements. Filter out cameraUpdate and other pseudo-elements before writing the .excalidraw file.