Create Excalidraw diagram JSON files that make visual arguments. Use when the user wants to create, draw, sketch, or visualize any kind of diagram — flowcharts, system diagrams, architecture diagrams, technical diagrams, data flow diagrams, sequence diagrams, entity relationship diagrams, state machines, mind maps, org charts, network topologies, pipeline diagrams, decision trees, process flows, concept maps, wireframes, or any visual explanation of workflows, systems, relationships, or concepts.
Generate .excalidraw JSON files that argue visually, not just display information.
Setup: If the user asks you to set up this skill (renderer, dependencies, etc.), see README.md for instructions.
All colors and brand-specific styles live in one file: references/color-palette.md. Read it before generating any diagram and use it as the single source of truth for all color choices.
To produce diagrams in your own brand style, edit color-palette.md. Everything else in this file is universal design methodology and Excalidraw best practices.
Diagrams should ARGUE, not DISPLAY.
A diagram is a visual argument that shows relationships, causality, and flow that words alone cannot express. The shape should BE the meaning.
The Isomorphism Test: If you removed all text, would the structure alone communicate the concept? If not, redesign.
The Education Test: Could someone learn something concrete from this diagram, or does it just label boxes? A good diagram teaches — it shows actual formats, real event names, concrete examples.
Before designing, determine what level of detail this diagram needs:
Simple/Conceptual — Use abstract shapes when explaining a mental model, the audience does not need technical specifics, or the concept IS the abstraction.
Comprehensive/Technical — Use concrete examples when diagramming a real system, the diagram will teach or explain, the audience needs to understand what things look like, or you are showing how multiple technologies integrate. For technical diagrams, you MUST include evidence artifacts (see below).
Before drawing anything technical, research the actual specifications.
If you are diagramming a protocol, API, or framework:
Bad: "Protocol" -> "Frontend" Good: "AG-UI streams events (RUN_STARTED, STATE_DELTA)" -> "CopilotKit renders via createA2UIMessageRenderer()"
Evidence artifacts are concrete examples that prove your diagram is accurate and help viewers learn. Include them in technical diagrams.
| Artifact Type | When to Use | How to Render |
|---|---|---|
| Code snippets | APIs, integrations | Dark rectangle + syntax-colored text (see color palette) |
| Data/JSON examples | Data formats, schemas | Dark rectangle + colored text |
| Event/step sequences | Protocols, workflows | Timeline pattern (line + dots + labels) |
| UI mockups | Showing actual output | Nested rectangles mimicking real UI |
| Real input content | Showing what goes IN | Rectangle with sample content visible |
| API/method names | Real function calls | Use actual names from docs, not placeholders |
The key principle: show what things actually look like, not just what they are called.
Comprehensive diagrams operate at multiple zoom levels simultaneously — like a map showing both country borders and street names.
Level 1: Summary Flow — Simplified overview of the full pipeline. Often at the top or bottom.
Level 2: Section Boundaries — Labeled regions grouping related components. Create visual "rooms" (e.g., Backend / Frontend, Setup / Execution / Cleanup).
Level 3: Detail Inside Sections — Evidence artifacts, code snippets, and concrete examples within each section. This is where educational value lives.
For comprehensive diagrams, aim to include all three levels.
| Bad (Displaying) | Good (Arguing) |
|---|---|
| 5 equal boxes with labels | Each concept has a shape mirroring its behavior |
| Card grid layout | Visual structure matches conceptual structure |
| Icons decorating text | Shapes that ARE the meaning |
| Everything in a box | Free-floating text with selective containers |
Not every piece of text needs a shape around it. Default to free-floating text. Add containers only when they serve a purpose.
| Use a Container When... | Use Free-Floating Text When... |
|---|---|
| It is the focal point of a section | It is a label or description |
| Arrows need to connect to it | It describes something nearby |
| The shape carries meaning (decision diamond) | Typography alone creates hierarchy |
| It represents a distinct "thing" in the system | It is a title, subtitle, or annotation |
The container test: For each boxed element, ask "Would this work as free-floating text?" If yes, remove the container. Aim for <30% of text elements inside containers.
Determine simple/conceptual vs. comprehensive/technical. If comprehensive, do research first.
For each concept, ask: What does it DO? What relationships exist? What is the core transformation? What would someone need to SEE to understand this?
Match each concept to the visual pattern that mirrors its behavior. See references/visual-patterns.md for the full pattern library and a concept-to-pattern quick reference table.
For multi-concept diagrams, each major concept must use a different visual pattern. No uniform cards or grids.
Mentally trace how the eye moves through the diagram. There should be a clear visual story.
Create the Excalidraw elements. For large diagrams, build section-by-section (see below).
Run the render-view-fix loop until the diagram looks right. See the Render & Validate section below.
For comprehensive or technical diagrams, build the JSON one section at a time. Do NOT generate the entire file in a single pass. Claude Code has a ~32,000 token output limit per response, and a comprehensive diagram easily exceeds that. Even for smaller diagrams, section-by-section produces better quality.
Phase 1: Build each section
type, version, appState, files) and the first section of elements."trigger_rect", "arrow_fan_left") so cross-section references are readable.boundElements array at the same time.Phase 2: Review the whole
After all sections are in place, read through the complete JSON and check:
Phase 3: Render & validate — Run the render-view-fix loop.
Plan sections around natural visual groupings. A typical split:
Choose shape based on what it represents — or use no shape at all:
| Concept Type | Shape | Why |
|---|---|---|
| Labels, descriptions, details | none (free-floating text) | Typography creates hierarchy |
| Section titles, annotations | none (free-floating text) | Font size/weight is enough |
| Markers on a timeline | small ellipse (10-20px) | Visual anchor, not container |
| Start, trigger, input | ellipse | Soft, origin-like |
| End, output, result | ellipse | Completion, destination |
| Decision, condition | diamond | Classic decision symbol |
| Process, action, step | rectangle | Contained action |
| Abstract state, context | overlapping ellipse | Fuzzy, cloud-like |
| Hierarchy node | lines + text (no boxes) | Structure through lines |
Colors encode information, not decoration. Every color choice must come from references/color-palette.md.
Key principles:
Do not invent new colors. If a concept does not fit an existing semantic category, use Primary/Neutral or Secondary.
roughness: 0 for clean/modern (default). roughness: 1 for hand-drawn/informal.1 for thin/elegant lines, 2 for standard shapes/arrows, 3 sparingly for emphasis.opacity: 100. Use color, size, and stroke width for hierarchy instead of transparency.CRITICAL: The JSON text property contains ONLY readable words.
{
"id": "myElement1",
"text": "Start",
"originalText": "Start"
}
Settings: fontSize: 16, fontFamily: 3, textAlign: "center", verticalAlign: "middle"
{
"type": "excalidraw",
"version": 2,
"source": "https://excalidraw.com",
"elements": [...],
"appState": {
"viewBackgroundColor": "#ffffff",
"gridSize": 20
},
"files": {}
}
See references/element-templates.md for copy-paste JSON templates for each element type. Pull colors from references/color-palette.md based on each element's semantic purpose.
You cannot judge a diagram from JSON alone. After generating or editing the Excalidraw JSON, you MUST render it to PNG, view the image, and fix what you see — in a loop until it is right.
cd .claude/skills/excalidraw-diagram/references && uv run python render_excalidraw.py <path-to-file.excalidraw>
This outputs a PNG next to the .excalidraw file. Then use the Read tool on the PNG to view it.
1. Render & View — Run the render script, then Read the PNG.
2. Audit against your original vision — Compare the rendered result to what you designed. Ask:
3. Check for visual defects:
4. Fix — Edit the JSON. Common fixes: widen containers for clipped text, adjust coordinates for spacing, add waypoints to arrow points arrays to route around elements, reposition labels closer to their subject.
5. Re-render & re-view — Run the render script again and Read the new PNG.
6. Repeat — Keep cycling until the diagram passes both the vision check and the defect check. Typically 2-4 iterations. Do not stop after one pass just because there are no critical bugs — if the composition could be better, improve it.
The loop is done when:
cd .claude/skills/excalidraw-diagram/references
uv sync
uv run playwright install chromium
After completing the render-validate loop, run through references/quality-checklist.md for a final comprehensive check covering depth, evidence, conceptual integrity, container discipline, structural quality, technical correctness, and visual validation.