Excalidraw Diagram

1---2name: excalidraw-diagram3description: Create Excalidraw diagram JSON files that make visual arguments. Use when the user wants to visualize workflows, architectures, or concepts.4---5 6# Excalidraw Diagram Creator7 8Generate `.excalidraw` JSON files that **argue visually**, not just display information.9 10**Setup:** If the user asks you to set up this skill (renderer, dependencies, etc.), see `README.md` for instructions.11 12## Customization13 14**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 — shape fills, strokes, text colors, evidence artifact backgrounds, everything.15 16To make this skill produce diagrams in your own brand style, edit `color-palette.md`. Everything else in this file is universal design methodology and Excalidraw best practices.17 18---19 20## Core Philosophy21 22**Diagrams should ARGUE, not DISPLAY.**23 24A diagram isn't formatted text. It's a visual argument that shows relationships, causality, and flow that words alone can't express. The shape should BE the meaning.25 26**The Isomorphism Test**: If you removed all text, would the structure alone communicate the concept? If not, redesign.27 28**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.29 30---31 32## Depth Assessment (Do This First)33 34Before designing, determine what level of detail this diagram needs:35 36### Simple/Conceptual Diagrams37Use abstract shapes when:38- Explaining a mental model or philosophy39- The audience doesn't need technical specifics40- The concept IS the abstraction (e.g., "separation of concerns")41 42### Comprehensive/Technical Diagrams43Use concrete examples when:44- Diagramming a real system, protocol, or architecture45- The diagram will be used to teach or explain (e.g., YouTube video)46- The audience needs to understand what things actually look like47- You're showing how multiple technologies integrate48 49**For technical diagrams, you MUST include evidence artifacts** (see below).50 51---52 53## Research Mandate (For Technical Diagrams)54 55**Before drawing anything technical, research the actual specifications.**56 57If you're diagramming a protocol, API, or framework:581. Look up the actual JSON/data formats592. Find the real event names, method names, or API endpoints603. Understand how the pieces actually connect614. Use real terminology, not generic placeholders62 63Bad: "Protocol" → "Frontend"64Good: "AG-UI streams events (RUN_STARTED, STATE_DELTA, A2UI_UPDATE)" → "CopilotKit renders via createA2UIMessageRenderer()"65 66**Research makes diagrams accurate AND educational.**67 68---69 70## Evidence Artifacts71 72Evidence artifacts are concrete examples that prove your diagram is accurate and help viewers learn. Include them in technical diagrams.73 74**Types of evidence artifacts** (choose what's relevant to your diagram):75 76| Artifact Type | When to Use | How to Render |77|---------------|-------------|---------------|78| **Code snippets** | APIs, integrations, implementation details | Dark rectangle + syntax-colored text (see color palette for evidence artifact colors) |79| **Data/JSON examples** | Data formats, schemas, payloads | Dark rectangle + colored text (see color palette) |80| **Event/step sequences** | Protocols, workflows, lifecycles | Timeline pattern (line + dots + labels) |81| **UI mockups** | Showing actual output/results | Nested rectangles mimicking real UI |82| **Real input content** | Showing what goes IN to a system | Rectangle with sample content visible |83| **API/method names** | Real function calls, endpoints | Use actual names from docs, not placeholders |84 85**Example**: For a diagram about a streaming protocol, you might show:86- The actual event names from the spec (not just "Event 1", "Event 2")87- A code snippet showing how to connect88- What the streamed data actually looks like89 90**Example**: For a diagram about a data transformation pipeline:91- Show sample input data (actual format, not "Input")92- Show sample output data (actual format, not "Output")93- Show intermediate states if relevant94 95The key principle: **show what things actually look like**, not just what they're called.96 97---98 99## Multi-Zoom Architecture100 101Comprehensive diagrams operate at multiple zoom levels simultaneously. Think of it like a map that shows both the country borders AND the street names.102 103### Level 1: Summary Flow104A simplified overview showing the full pipeline or process at a glance. Often placed at the top or bottom of the diagram.105 106*Example*: `Input → Processing → Output` or `Client → Server → Database`107 108### Level 2: Section Boundaries109Labeled regions that group related components. These create visual "rooms" that help viewers understand what belongs together.110 111*Example*: Grouping by responsibility (Backend / Frontend), by phase (Setup / Execution / Cleanup), or by team (User / System / External)112 113### Level 3: Detail Inside Sections114Evidence artifacts, code snippets, and concrete examples within each section. This is where the educational value lives.115 116*Example*: Inside a "Backend" section, you might show the actual API response format, not just a box labeled "API Response"117 118**For comprehensive diagrams, aim to include all three levels.** The summary gives context, the sections organize, and the details teach.119 120### Bad vs Good121 122| Bad (Displaying) | Good (Arguing) |123|------------------|----------------|124| 5 equal boxes with labels | Each concept has a shape that mirrors its behavior |125| Card grid layout | Visual structure matches conceptual structure |126| Icons decorating text | Shapes that ARE the meaning |127| Same container for everything | Distinct visual vocabulary per concept |128| Everything in a box | Free-floating text with selective containers |129 130### Simple vs Comprehensive (Know Which You Need)131 132| Simple Diagram | Comprehensive Diagram |133|----------------|----------------------|134| Generic labels: "Input" → "Process" → "Output" | Specific: shows what the input/output actually looks like |135| Named boxes: "API", "Database", "Client" | Named boxes + examples of actual requests/responses |136| "Events" or "Messages" label | Timeline with real event/message names from the spec |137| "UI" or "Dashboard" rectangle | Mockup showing actual UI elements and content |138| ~30 seconds to explain | ~2-3 minutes of teaching content |139| Viewer learns the structure | Viewer learns the structure AND the details |140 141**Simple diagrams** are fine for abstract concepts, quick overviews, or when the audience already knows the details. **Comprehensive diagrams** are needed for technical architectures, tutorials, educational content, or when you want the diagram itself to teach.142 143---144 145## Container vs. Free-Floating Text146 147**Not every piece of text needs a shape around it.** Default to free-floating text. Add containers only when they serve a purpose.148 149| Use a Container When... | Use Free-Floating Text When... |150|------------------------|-------------------------------|151| It's the focal point of a section | It's a label or description |152| It needs visual grouping with other elements | It's supporting detail or metadata |153| Arrows need to connect to it | It describes something nearby |154| The shape itself carries meaning (decision diamond, etc.) | Typography alone creates sufficient hierarchy |155| It represents a distinct "thing" in the system | It's a section title, subtitle, or annotation |156 157**Typography as hierarchy**: Use font size, weight, and color to create visual hierarchy without boxes. A 28px title doesn't need a rectangle around it.158 159**The container test**: For each boxed element, ask "Would this work as free-floating text?" If yes, remove the container.160 161---162 163## Design Process (Do This BEFORE Generating JSON)164 165### Step 0: Assess Depth Required166Before anything else, determine if this needs to be:167- **Simple/Conceptual**: Abstract shapes, labels, relationships (mental models, philosophies)168- **Comprehensive/Technical**: Concrete examples, code snippets, real data (systems, architectures, tutorials)169 170**If comprehensive**: Do research first. Look up actual specs, formats, event names, APIs.171 172### Step 1: Understand Deeply173Read the content. For each concept, ask:174- What does this concept **DO**? (not what IS it)175- What relationships exist between concepts?176- What's the core transformation or flow?177- **What would someone need to SEE to understand this?** (not just read about)178 179### Step 2: Map Concepts to Patterns180For each concept, find the visual pattern that mirrors its behavior:181 182| If the concept... | Use this pattern |183|-------------------|------------------|184| Spawns multiple outputs | **Fan-out** (radial arrows from center) |185| Combines inputs into one | **Convergence** (funnel, arrows merging) |186| Has hierarchy/nesting | **Tree** (lines + free-floating text) |187| Is a sequence of steps | **Timeline** (line + dots + free-floating labels) |188| Loops or improves continuously | **Spiral/Cycle** (arrow returning to start) |189| Is an abstract state or context | **Cloud** (overlapping ellipses) |190| Transforms input to output | **Assembly line** (before → process → after) |191| Compares two things | **Side-by-side** (parallel with contrast) |192| Separates into phases | **Gap/Break** (visual separation between sections) |193 194### Step 3: Ensure Variety195For multi-concept diagrams: **each major concept must use a different visual pattern**. No uniform cards or grids.196 197### Step 4: Sketch the Flow198Before JSON, mentally trace how the eye moves through the diagram. There should be a clear visual story.199 200### Step 5: Generate JSON201Only now create the Excalidraw elements. **See below for how to handle large diagrams.**202 203### Step 6: Render & Validate (MANDATORY)204After generating the JSON, you MUST run the render-view-fix loop until the diagram looks right. This is not optional — see the **Render & Validate** section below for the full process.205 206---207 208## Large / Comprehensive Diagram Strategy209 210**For comprehensive or technical diagrams, you MUST build the JSON one section at a time.** Do NOT attempt to generate the entire file in a single pass. This is a hard constraint — Claude Code has a ~32,000 token output limit per response, and a comprehensive diagram easily exceeds that in one shot. Even if it didn't, generating everything at once leads to worse quality. Section-by-section is better in every way.211 212### The Section-by-Section Workflow213 214**Phase 1: Build each section**215 2161. **Create the base file** with the JSON wrapper (`type`, `version`, `appState`, `files`) and the first section of elements.2172. **Add one section per edit.** Each section gets its own dedicated pass — take your time with it. Think carefully about the layout, spacing, and how this section connects to what's already there.2183. **Use descriptive string IDs** (e.g., `"trigger_rect"`, `"arrow_fan_left"`) so cross-section references are readable.2194. **Namespace seeds by section** (e.g., section 1 uses 100xxx, section 2 uses 200xxx) to avoid collisions.2205. **Update cross-section bindings** as you go. When a new section's element needs to bind to an element from a previous section (e.g., an arrow connecting sections), edit the earlier element's `boundElements` array at the same time.221 222**Phase 2: Review the whole**223 224After all sections are in place, read through the complete JSON and check:225- Are cross-section arrows bound correctly on both ends?226- Is the overall spacing balanced, or are some sections cramped while others have too much whitespace?227- Do IDs and bindings all reference elements that actually exist?228 229Fix any alignment or binding issues before rendering.230 231**Phase 3: Render & validate**232 233Now run the render-view-fix loop from the Render & Validate section. This is where you'll catch visual issues that aren't obvious from JSON — overlaps, clipping, imbalanced composition.234 235### Section Boundaries236 237Plan your sections around natural visual groupings from the diagram plan. A typical large diagram might split into:238 239- **Section 1**: Entry point / trigger240- **Section 2**: First decision or routing241- **Section 3**: Main content (hero section — may be the largest single section)242- **Section 4-N**: Remaining phases, outputs, etc.243 244Each section should be independently understandable: its elements, internal arrows, and any cross-references to adjacent sections.245 246### What NOT to Do247 248- **Don't generate the entire diagram in one response.** You will hit the output token limit and produce truncated, broken JSON. Even if the diagram is small enough to fit, splitting into sections produces better results.249- **Don't use a coding agent** to generate the JSON. The agent won't have sufficient context about the skill's rules, and the coordination overhead negates any benefit.250- **Don't write a Python generator script.** The templating and coordinate math seem helpful but introduce a layer of indirection that makes debugging harder. Hand-crafted JSON with descriptive IDs is more maintainable.251 252---253 254## Visual Pattern Library255 256### Fan-Out (One-to-Many)257Central element with arrows radiating to multiple targets. Use for: sources, PRDs, root causes, central hubs.258```259        ○260       ↗261  □ → ○262       ↘263        ○264```265 266### Convergence (Many-to-One)267Multiple inputs merging through arrows to single output. Use for: aggregation, funnels, synthesis.268```269  ○ ↘270  ○ → □271  ○ ↗272```273 274### Tree (Hierarchy)275Parent-child branching with connecting lines and free-floating text (no boxes needed). Use for: file systems, org charts, taxonomies.276```277  label278  ├── label279  │   ├── label280  │   └── label281  └── label282```283Use `line` elements for the trunk and branches, free-floating text for labels.284 285### Spiral/Cycle (Continuous Loop)286Elements in sequence with arrow returning to start. Use for: feedback loops, iterative processes, evolution.287```288  □ → □289  ↑     ↓290  □ ← □291```292 293### Cloud (Abstract State)294Overlapping ellipses with varied sizes. Use for: context, memory, conversations, mental states.295 296### Assembly Line (Transformation)297Input → Process Box → Output with clear before/after. Use for: transformations, processing, conversion.298```299  ○○○ → [PROCESS] → □□□300  chaos              order301```302 303### Side-by-Side (Comparison)304Two parallel structures with visual contrast. Use for: before/after, options, trade-offs.305 306### Gap/Break (Separation)307Visual whitespace or barrier between sections. Use for: phase changes, context resets, boundaries.308 309### Lines as Structure310Use lines (type: `line`, not arrows) as primary structural elements instead of boxes:311- **Timelines**: Vertical or horizontal line with small dots (10-20px ellipses) at intervals, free-floating labels beside each dot312- **Tree structures**: Vertical trunk line + horizontal branch lines, with free-floating text labels (no boxes needed)313- **Dividers**: Thin dashed lines to separate sections314- **Flow spines**: A central line that elements relate to, rather than connecting boxes315 316```317Timeline:           Tree:318  ●─── Label 1        │319  │                   ├── item320  ●─── Label 2        │   ├── sub321  │                   │   └── sub322  ●─── Label 3        └── item323```324 325Lines + free-floating text often creates a cleaner result than boxes + contained text.326 327---328 329## Shape Meaning330 331Choose shape based on what it represents—or use no shape at all:332 333| Concept Type | Shape | Why |334|--------------|-------|-----|335| Labels, descriptions, details | **none** (free-floating text) | Typography creates hierarchy |336| Section titles, annotations | **none** (free-floating text) | Font size/weight is enough |337| Markers on a timeline | small `ellipse` (10-20px) | Visual anchor, not container |338| Start, trigger, input | `ellipse` | Soft, origin-like |339| End, output, result | `ellipse` | Completion, destination |340| Decision, condition | `diamond` | Classic decision symbol |341| Process, action, step | `rectangle` | Contained action |342| Abstract state, context | overlapping `ellipse` | Fuzzy, cloud-like |343| Hierarchy node | lines + text (no boxes) | Structure through lines |344 345**Rule**: Default to no container. Add shapes only when they carry meaning. Aim for <30% of text elements to be inside containers.346 347---348 349## Color as Meaning350 351Colors encode information, not decoration. Every color choice should come from `references/color-palette.md` — the semantic shape colors, text hierarchy colors, and evidence artifact colors are all defined there.352 353**Key principles:**354- Each semantic purpose (start, end, decision, AI, error, etc.) has a specific fill/stroke pair355- Free-floating text uses color for hierarchy (titles, subtitles, details — each at a different level)356- Evidence artifacts (code snippets, JSON examples) use their own dark background + colored text scheme357- Always pair a darker stroke with a lighter fill for contrast358 359**Do not invent new colors.** If a concept doesn't fit an existing semantic category, use Primary/Neutral or Secondary.360 361---362 363## Modern Aesthetics364 365For clean, professional diagrams:366 367### Roughness368- `roughness: 0` — Clean, crisp edges. Use for modern/technical diagrams.369- `roughness: 1` — Hand-drawn, organic feel. Use for brainstorming/informal diagrams.370 371**Default to 0** for most professional use cases.372 373### Stroke Width374- `strokeWidth: 1` — Thin, elegant. Good for lines, dividers, subtle connections.375- `strokeWidth: 2` — Standard. Good for shapes and primary arrows.376- `strokeWidth: 3` — Bold. Use sparingly for emphasis (main flow line, key connections).377 378### Opacity379**Always use `opacity: 100` for all elements.** Use color, size, and stroke width to create hierarchy instead of transparency.380 381### Small Markers Instead of Shapes382Instead of full shapes, use small dots (10-20px ellipses) as:383- Timeline markers384- Bullet points385- Connection nodes386- Visual anchors for free-floating text387 388---389 390## Layout Principles391 392### Hierarchy Through Scale393- **Hero**: 300×150 - visual anchor, most important394- **Primary**: 180×90395- **Secondary**: 120×60396- **Small**: 60×40397 398### Whitespace = Importance399The most important element has the most empty space around it (200px+).400 401### Flow Direction402Guide the eye: typically left→right or top→bottom for sequences, radial for hub-and-spoke.403 404### Connections Required405Position alone doesn't show relationships. If A relates to B, there must be an arrow.406 407---408 409## Text Rules410 411**CRITICAL**: The JSON `text` property contains ONLY readable words.412 413```json414{415  "id": "myElement1",416  "text": "Start",417  "originalText": "Start"418}419```420 421Settings: `fontSize: 16`, `fontFamily: 3`, `textAlign: "center"`, `verticalAlign: "middle"`422 423---424 425## JSON Structure426 427```json428{429  "type": "excalidraw",430  "version": 2,431  "source": "https://excalidraw.com",432  "elements": [...],433  "appState": {434    "viewBackgroundColor": "#ffffff",435    "gridSize": 20436  },437  "files": {}438}439```440 441## Element Templates442 443See `references/element-templates.md` for copy-paste JSON templates for each element type (text, line, dot, rectangle, arrow). Pull colors from `references/color-palette.md` based on each element's semantic purpose.444 445---446 447## Render & Validate (MANDATORY)448 449You 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's right. This is a core part of the workflow, not a final check.450 451### How to Render452 453```bash454cd .claude/skills/excalidraw-diagram/references && uv run python render_excalidraw.py <path-to-file.excalidraw>455```456 457This outputs a PNG next to the `.excalidraw` file. Then use the **Read tool** on the PNG to actually view it.458 459### The Loop460 461After generating the initial JSON, run this cycle:462 463**1. Render & View** — Run the render script, then Read the PNG.464 465**2. Audit against your original vision** — Before looking for bugs, compare the rendered result to what you designed in Steps 1-4. Ask:466- Does the visual structure match the conceptual structure you planned?467- Does each section use the pattern you intended (fan-out, convergence, timeline, etc.)?468- Does the eye flow through the diagram in the order you designed?469- Is the visual hierarchy correct — hero elements dominant, supporting elements smaller?470- For technical diagrams: are the evidence artifacts (code snippets, data examples) readable and properly placed?471 472**3. Check for visual defects:**473- Text clipped by or overflowing its container474- Text or shapes overlapping other elements475- Arrows crossing through elements instead of routing around them476- Arrows landing on the wrong element or pointing into empty space477- Labels floating ambiguously (not clearly anchored to what they describe)478- Uneven spacing between elements that should be evenly spaced479- Sections with too much whitespace next to sections that are too cramped480- Text too small to read at the rendered size481- Overall composition feels lopsided or unbalanced482 483**4. Fix** — Edit the JSON to address everything you found. Common fixes:484- Widen containers when text is clipped485- Adjust `x`/`y` coordinates to fix spacing and alignment486- Add intermediate waypoints to arrow `points` arrays to route around elements487- Reposition labels closer to the element they describe488- Resize elements to rebalance visual weight across sections489 490**5. Re-render & re-view** — Run the render script again and Read the new PNG.491 492**6. Repeat** — Keep cycling until the diagram passes both the vision check (Step 2) and the defect check (Step 3). Typically takes 2-4 iterations. Don't stop after one pass just because there are no critical bugs — if the composition could be better, improve it.493 494### When to Stop495 496The loop is done when:497- The rendered diagram matches the conceptual design from your planning steps498- No text is clipped, overlapping, or unreadable499- Arrows route cleanly and connect to the right elements500- Spacing is consistent and the composition is balanced501- You'd be comfortable showing it to someone without caveats502 503### First-Time Setup504If the render script hasn't been set up yet:505```bash506cd .claude/skills/excalidraw-diagram/references507uv sync508uv run playwright install chromium509```510 511---512 513## Quality Checklist514 515### Depth & Evidence (Check First for Technical Diagrams)5161. **Research done**: Did you look up actual specs, formats, event names?5172. **Evidence artifacts**: Are there code snippets, JSON examples, or real data?5183. **Multi-zoom**: Does it have summary flow + section boundaries + detail?5194. **Concrete over abstract**: Real content shown, not just labeled boxes?5205. **Educational value**: Could someone learn something concrete from this?521 522### Conceptual5236. **Isomorphism**: Does each visual structure mirror its concept's behavior?5247. **Argument**: Does the diagram SHOW something text alone couldn't?5258. **Variety**: Does each major concept use a different visual pattern?5269. **No uniform containers**: Avoided card grids and equal boxes?527 528### Container Discipline52910. **Minimal containers**: Could any boxed element work as free-floating text instead?53011. **Lines as structure**: Are tree/timeline patterns using lines + text rather than boxes?53112. **Typography hierarchy**: Are font size and color creating visual hierarchy (reducing need for boxes)?532 533### Structural53413. **Connections**: Every relationship has an arrow or line53514. **Flow**: Clear visual path for the eye to follow53615. **Hierarchy**: Important elements are larger/more isolated537 538### Technical53916. **Text clean**: `text` contains only readable words54017. **Font**: `fontFamily: 3`54118. **Roughness**: `roughness: 0` for clean/modern (unless hand-drawn style requested)54219. **Opacity**: `opacity: 100` for all elements (no transparency)54320. **Container ratio**: <30% of text elements should be inside containers544 545### Visual Validation (Render Required)54621. **Rendered to PNG**: Diagram has been rendered and visually inspected54722. **No text overflow**: All text fits within its container54823. **No overlapping elements**: Shapes and text don't overlap unintentionally54924. **Even spacing**: Similar elements have consistent spacing55025. **Arrows land correctly**: Arrows connect to intended elements without crossing others55126. **Readable at export size**: Text is legible in the rendered PNG55227. **Balanced composition**: No large empty voids or overcrowded regions