// Generate hand-drawn style diagrams using Excalidraw. Accepts natural language descriptions, generates Excalidraw scene JSON, and renders to PNG/SVG via headless Playwright. Use when user asks for diagrams, architecture charts, flowcharts, or visual illustrations.
| name | excalidraw |
| description | Generate hand-drawn style diagrams using Excalidraw. Accepts natural language descriptions, generates Excalidraw scene JSON, and renders to PNG/SVG via headless Playwright. Use when user asks for diagrams, architecture charts, flowcharts, or visual illustrations. |
| dependencies | ["Node.js >= 18","@playwright/test","Chromium (installed via Playwright)"] |
| allowed-tools | ["Bash","Read","Write","Edit","Glob"] |
Generate hand-drawn style diagrams programmatically using Excalidraw's rendering engine.
| Setting | Default | Description |
|---|---|---|
| Output directory | diagrams/ | Where .excalidraw and rendered files are saved |
Adjust the output directory to match your project structure. Common choices:
docs/diagrams/,assets/diagrams/,static/images/diagrams/
User describes diagram
→ Step 0: Design Phase — determine visual style (+ style review)
→ Step 1: Claude generates .excalidraw JSON following the style brief
→ Step 2: render.mjs → PNG
→ Step 3: Review the rendered image (scoring + iteration)
→ Step 4: Fix issues and re-render (loop until approved)
→ Done: Final PNG/SVG output
Before writing any JSON, you SHOULD first determine the visual style. This prevents the common failure of jumping straight to coordinates without thinking about what makes the diagram effective.
If oh-my-claudecode is installed, spawn an oh-my-claudecode:architect agent as a design consultant with the prompt below. Otherwise, perform this design thinking yourself before writing any JSON.
Design consultant prompt template:
You are a visual communication designer. Before I create an Excalidraw diagram, help me determine the visual style.
Context:
- Article/post topic: [e.g., "How to use CLAUDE.md to make AI code match team standards"]
- Diagram purpose: [e.g., "Twitter cover image showing before/after code quality comparison"]
- Target platform: [e.g., "Twitter feed, 16:9, must be readable at 500px wide thumbnail"]
- Target audience: [e.g., "Frontend developers, tech leads"]
Decide on:
1. **Visual Metaphor** — What real-world analogy best communicates this concept?
(e.g., "blueprint vs sketch", "filter/funnel", "bridge between two worlds", "before/after transformation")
2. **Layout Strategy** — Which layout pattern fits?
- Left-to-right flow (transformation, process)
- Top-to-bottom hierarchy (layers, architecture)
- Center-out radial (hub-and-spoke, ecosystem)
- Split comparison (vs, before/after)
- Single focal point (hero concept with annotations)
3. **Information Density** — How much text should be on the image?
- Minimal (3-5 words max, icon-driven, for social media thumbnails)
- Light (short labels + one key data point)
- Medium (bullet points inside boxes, for blog posts)
- Dense (detailed architecture, for documentation)
4. **Tone** — What feeling should the diagram convey?
- Technical precision (clean lines, code font, structured)
- Casual/approachable (hand-drawn, playful, loose)
- Authoritative/professional (bold, minimal, high contrast)
- Educational (annotated, step-by-step, guided)
5. **Color Strategy** — Within the monochrome-first constraint:
- Pure monochrome (black strokes, transparent/light gray fills, no accent)
- Monochrome + single accent (black + one purple/blue highlight for the key concept)
- Semantic pair (black strokes + two meaningful background colors, e.g., light red vs light green for comparison)
Output a **Style Brief** in this exact format:
---
STYLE BRIEF
Metaphor: [one line]
Layout: [pattern name]
Density: [level]
Tone: [one line]
Colors: [strategy + specific hex codes to use]
Key visual element: [the ONE thing that should catch the eye first]
Anti-patterns to avoid: [what would make this diagram look bad]
---
Style Review (adversarial):
After producing the Style Brief, review it critically. If oh-my-claudecode is installed, spawn a oh-my-claudecode:critic agent. Otherwise, challenge the brief yourself using this checklist:
Review the Style Brief. Challenge any choices that are:
1. Generic/cliché (would this produce a diagram that looks like every other tech blog?)
2. Mismatched to platform (is the density appropriate for the target size?)
3. Over-designed (is it trying to say too much? Should we simplify?)
4. Under-differentiated (will this stand out, or will people scroll past it?)
Either approve the brief or suggest ONE specific change for the biggest improvement.
Merge the feedback, then proceed to Step 1 using the finalized Style Brief as your guide.
Following the Style Brief from Step 0, create a .excalidraw file. Save it to your configured output directory (default: diagrams/).
Before writing any JSON, verify your plan against the Style Brief:
Requires: @playwright/test + Chromium browser (npx playwright install chromium)
node scripts/excalidraw/render.mjs diagrams/my-diagram.excalidraw diagrams/my-diagram.png
Options:
--width=1600 (default 1600)--height=900 (default 900)--scale=2 (default 2, for retina/HiDPI)--theme=light|dark (default light, affects background color only)For SVG output, use .svg extension:
node scripts/excalidraw/render.mjs diagrams/my-diagram.excalidraw diagrams/my-diagram.svg
How it works: Loads React + Excalidraw from CDN in a headless Chromium, runs exportToCanvas/exportToSvg, outputs the result. No extra npm deps needed beyond Playwright.
After rendering, you SHOULD review the generated image for visual quality. If oh-my-claudecode is installed, spawn a oh-my-claudecode:designer agent for an adversarial review. Otherwise, review the image yourself using the scoring rubric below.
Review prompt template:
Review this Excalidraw diagram image for visual quality. Read the image at [path].
This diagram is intended for: [purpose, e.g., "Twitter post, 16:9 ratio, needs to be eye-catching at small sizes"]
Score each dimension 1-10 and provide specific fixes:
1. **Layout & Composition** — Is content well-centered? Is there good use of whitespace? Are elements balanced?
2. **Visual Hierarchy** — Does the eye flow naturally? Are titles prominent enough? Is the most important info emphasized?
3. **Proportions & Spacing** — Are gaps between elements consistent? Are boxes proportional to their content? Any cramped or sparse areas?
4. **Readability** — Is text large enough to read at the target display size? Is there enough contrast between text and backgrounds?
5. **Color Discipline** — Is the diagram monochrome-first? Count the number of distinct strokeColors and backgroundColors used. Rules:
- strokeColor should be "#1e1e1e" (black) for ALL elements unless there's a strong semantic reason
- Maximum 2-3 backgroundColors total (transparent + 1-2 light fills)
- Maximum 1 accent color (purple "#6741d9") for emphasis
- If you see red/green/blue/orange strokeColors on different boxes, score 3/10 and demand they all become black
- Exception: BAD vs GOOD comparisons may use red/green backgrounds only (NOT stroke colors)
6. **Overall Polish** — Does it look professional and intentional? Would you be proud to post this publicly? Hand-drawn style should feel deliberate and clean, not cluttered.
For each issue found, provide the EXACT fix as a JSON path change, e.g.:
- "Element 'title': increase fontSize from 32 to 40"
- "Element 'model-box': move x from 100 to 200, increase width from 300 to 400"
- "Add 60px more vertical gap between the boxes and the bottom result bar"
The .excalidraw JSON is at [json_path] — reference element IDs directly.
Minimum passing score: 7/10 on ALL dimensions. If any dimension scores below 7, the diagram MUST be revised.
Based on the review feedback:
.excalidraw JSON file with the specific coordinate/size/style changesnode scripts/excalidraw/render.mjsCommon fixes:
| Issue | Typical Fix |
|---|---|
| Title too small | Increase fontSize to 36-40 for main title |
| Cramped layout | Increase gaps between elements by 40-80px |
| Off-center | Adjust x coordinates to center content in viewport |
| Text overflow | Reduce fontSize or increase container width/height |
| Poor contrast | Change strokeColor to darker shade, increase strokeWidth |
| Inconsistent spacing | Align elements to a grid (multiples of 40px) |
| Visual clutter | Remove unnecessary elements, simplify labels |
| Weak hierarchy | Make primary elements larger/bolder, secondary elements lighter |
A .excalidraw file is JSON with this structure:
{
"type": "excalidraw",
"version": 2,
"elements": [ ... ],
"appState": {
"viewBackgroundColor": "#ffffff",
"theme": "light",
"gridSize": null
}
}
{
"id": "unique-id-string",
"type": "rectangle|ellipse|diamond|text|arrow|line|freedraw|image",
"x": 100,
"y": 100,
"width": 200,
"height": 100,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"roundness": null,
"seed": 12345,
"version": 1,
"isDeleted": false,
"boundElements": null,
"locked": false
}
| Property | Values | Description |
|---|---|---|
fillStyle | "solid", "hachure", "cross-hatch", "dots" | How backgrounds are filled. "hachure" = classic hand-drawn |
strokeWidth | 1, 2, 4 | Line thickness. 2 is standard |
strokeStyle | "solid", "dashed", "dotted" | Line style |
roughness | 0, 1, 2 | Hand-drawn roughness. 0=smooth, 1=normal, 2=very rough |
roundness | null or {"type": 3} | null=sharp corners, type:3=rounded corners |
opacity | 0-100 | Element opacity |
Default to black (#1e1e1e) for all strokeColor. Too many colors make hand-drawn diagrams look cluttered and cheap.
Core principle: use shapes and layout to convey information, not color.
Default palette (covers 90% of use cases):
strokeColor: "#1e1e1e" (black for all elements)
backgroundColor: "transparent" or a single light fill
fillStyle: "hachure" (hatching itself provides visual layers)
Only introduce color for semantic distinction, max 2-3:
Accent: "#6741d9" (purple — for key concepts/arrow labels)
Light backgrounds (for area differentiation, not decoration):
"#f5f5f5" (very light gray — default area background)
"#e8e8e8" (light gray — secondary areas)
"#fef9c3" (pale yellow — highlight/emphasis area)
Forbidden:
Only exception: When the diagram's core meaning IS a color comparison (e.g., BAD red vs GOOD green), use 2 semantic backgrounds only, keep strokeColor black.
{
"id": "rect-1",
"type": "rectangle",
"x": 100,
"y": 100,
"width": 250,
"height": 80,
"strokeColor": "#1e1e1e",
"backgroundColor": "#f5f5f5",
"fillStyle": "hachure",
"strokeWidth": 2,
"roughness": 2,
"roundness": null,
"boundElements": [
{ "id": "text-in-rect", "type": "text" }
]
}
{
"id": "text-1",
"type": "text",
"x": 100,
"y": 100,
"width": 120,
"height": 25,
"text": "Hello World",
"fontSize": 20,
"fontFamily": 1,
"textAlign": "center",
"verticalAlign": "middle",
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "hachure",
"roughness": 2
}
fontFamily: 1 = Virgil (hand-drawn), 2 = Helvetica, 3 = Cascadia (code)
To put text inside a rectangle/ellipse/diamond, use containerId:
{
"id": "text-in-rect",
"type": "text",
"x": 130,
"y": 125,
"width": 190,
"height": 25,
"text": "My Label",
"fontSize": 20,
"fontFamily": 1,
"textAlign": "center",
"verticalAlign": "middle",
"containerId": "rect-1",
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent"
}
Important: The container element must have boundElements referencing this text:
"boundElements": [{ "id": "text-in-rect", "type": "text" }]
{
"id": "arrow-1",
"type": "arrow",
"x": 350,
"y": 140,
"width": 100,
"height": 0,
"points": [[0, 0], [100, 0]],
"strokeColor": "#1e1e1e",
"strokeWidth": 2,
"roughness": 2,
"startArrowhead": null,
"endArrowhead": "arrow",
"startBinding": {
"elementId": "rect-1",
"focus": 0,
"gap": 5
},
"endBinding": {
"elementId": "rect-2",
"focus": 0,
"gap": 5
}
}
Arrowheads: null, "arrow", "bar", "dot", "triangle"
Bindings: When an arrow connects two shapes, set startBinding and endBinding with the shape's id. The connected shapes must list the arrow in their boundElements:
"boundElements": [{ "id": "arrow-1", "type": "arrow" }]
Multi-segment arrows (with bends):
"points": [[0, 0], [50, 0], [50, 100], [100, 100]]
{
"id": "ellipse-1",
"type": "ellipse",
"x": 100,
"y": 100,
"width": 150,
"height": 150,
"strokeColor": "#1e1e1e",
"backgroundColor": "#f5f5f5",
"fillStyle": "hachure",
"roundness": { "type": 2 }
}
{
"id": "diamond-1",
"type": "diamond",
"x": 100,
"y": 100,
"width": 150,
"height": 100,
"strokeColor": "#1e1e1e",
"backgroundColor": "#f5f5f5",
"fillStyle": "hachure"
}
{
"id": "line-1",
"type": "line",
"x": 100,
"y": 100,
"width": 200,
"height": 0,
"points": [[0, 0], [200, 0]],
"strokeColor": "#1e1e1e",
"strokeWidth": 2,
"strokeStyle": "dashed"
}
To group elements visually, give them the same groupIds value:
{ "id": "a", "groupIds": ["group-1"], ... },
{ "id": "b", "groupIds": ["group-1"], ... }
--width=1600 --height=900 (default)--width=1200 --height=1200--width=1920 --height=1080Horizontal flow (left to right):
x=100 → x=400 → x=700 → x=1000
y=350 for all (centered vertically in 900h canvas)
Vertical flow (top to bottom):
y=80 → y=280 → y=480 → y=680
x=600 for all (centered horizontally in 1600w canvas)
Three-column layout:
Left: x=100 Center: x=550 Right: x=1000
When generating Excalidraw scenes, follow these rules:
Every element MUST have ALL required properties — id, type, x, y, width, height, strokeColor, backgroundColor, fillStyle, strokeWidth, roughness, opacity, angle, groupIds, roundness, seed, version, isDeleted, boundElements, locked
Use unique seed values — each element needs a different integer seed for the hand-drawn randomization to look natural
Container-text binding is bidirectional — when putting text in a shape:
containerId pointing to the shapeboundElements listing the text { "id": "...", "type": "text" }Arrow binding is bidirectional — when connecting arrows to shapes:
startBinding/endBinding referencing shape idsboundElements listing the arrow { "id": "...", "type": "arrow" }Use roughness: 2 for the classic hand-drawn look. Use roughness: 0 only for clean/technical diagrams.
Use fillStyle: "hachure" for the classic Excalidraw sketch feel (default). Use "solid" for clean/modern look.
Monochrome-first coloring (CRITICAL):
strokeColor MUST be "#1e1e1e" (black) by defaultbackgroundColor should be "transparent" or a single light gray "#f5f5f5""#6741d9" (purple) for emphasis labels/arrowsCenter content in the viewport — for a 1600x900 canvas, main content should be roughly centered around x=800, y=450.
Font sizes: Title=36-44, Subtitle=24-28, Body=18-22, Small=14-16
File naming: Save as <output-dir>/<name>.excalidraw
After generating the JSON, immediately run the render command, then review the rendered image (Step 3).