excalidraw

name excalidraw description Use when user requests diagrams, flowcharts, architecture charts, or visualizations. Also use proactively when explaining systems with 3+ components, complex data flows, or relationships that benefit from visual representation. Generates .excalidraw files and exports to PNG/SVG via Kroki API or locally using excalidraw-brute-export-cli. homepage https://github.com/Agents365-ai/excalidraw-skill metadata {"version":"1.3.0","openclaw":{"requires":{"bins":"[Truncated]"},"emoji":"🎨"}} Excalidraw Diagrams Overview Generate .excalidraw JSON files and export to PNG/SVG. Two export options: Kroki API ( curl ) — zero install, SVG output only excalidraw-brute-export-cli — local Firefox-based, PNG + SVG Supported formats: PNG (local CLI only), SVG (both options). PDF is NOT supported. When to Use Explicit triggers: user says "画图", "diagram", "visualize", "flowchart", "draw", "架构图", "流程图" Proactive triggers: Explaining a system with 3+ interacting components Describing a multi-step process or decision tree Comparing architectures or approaches side by side Skip when: a simple list or table suffices, or user is in a quick Q&A flow When NOT to use it — route elsewhere: Polished, precise diagrams, strict UML, or branded vendor icons → drawio . Diagrams-as-code in git, auto-laid-out from text → mermaid (general) or plantuml (UML). An infinite-canvas whiteboard or programmatic freehand strokes → tldraw . Prerequisites Option A: Kroki API (recommended — zero install, SVG only) # Just needs curl (pre-installed on macOS/Linux/Windows Git Bash) curl --version No additional setup. SVG rendered via https://kroki.io . Option B: Local CLI (required for PNG) The CLI uses Firefox (not Chromium). Check and install: npm install -g excalidraw-brute-export-cli npx playwright install firefox macOS patch (one-time, required): CLI_MAIN=$(npm root -g)/excalidraw-brute-export-cli/src/main.js sed -i '' 's/keyboard.press("Control+O")/keyboard.press("Meta+O")/' " $CLI_MAIN " sed -i '' 's/keyboard.press("Control+Shift+E")/keyboard.press("Meta+Shift+E")/' " $CLI_MAIN " Windows/Linux: No patch needed. Workflow Check deps — use Kroki (curl) for SVG; use local CLI for PNG Plan — pick the visual metaphor (see Relationship-to-layout map ), then the diagram type and color palette Generate — write .excalidraw JSON file (section-by-section for large diagrams) Export — run Kroki or CLI command Verify the render — view the exported PNG, fix any defects, re-export (see Verify the Render ) Review loop — show the image to the user, apply the minimal .excalidraw edit per request, re-export until approved (see Review Loop ) Report — tell user the output file path Design Principles Default style roughness: 0 — clean, modern look for all technical diagrams (use 1 only when user requests hand-drawn/casual style) fontFamily: 2 (Helvetica) — professional look; use 1 (Virgil) only for casual/sketch style, 3 (Cascadia) for code snippets fillStyle: "solid" — default fill Containers: prefer typography over boxes A box around every label makes a diagram look like a wireframe. The cleanest Excalidraw diagrams use free-floating text and lines for structure and reserve filled boxes for things that are genuinely components . Default to no container — use a standalone text element unless the box earns its place. Add a box only when the element is a real system component, an arrow binds to it, the shape itself carries meaning (decision diamond, start/end ellipse), or it groups a zone. Aim for under ~30% of text elements inside boxes. For timelines, trees, and hierarchies, use a line/connector + free-floating labels , not a stack of rectangles. Size, weight, and color create hierarchy without boxes. Font size hierarchy Level Size Use for Title 28px Diagram title Header 24px Section/group headers Label 20px Primary element labels Description 16px Secondary text, descriptions Note 14px Annotations, fine print Color palette Follow the 60-30-10 rule : 60% whitespace/neutral, 30% primary accent, 10% highlight. Semantic fill colors (use with strokeColor one shade darker): Category Fill Stroke Use for Primary / Input #dbeafe #1e40af Entry points, APIs, user-facing Success / Data #dcfce7 #166534 Data stores, success states Warning / Decision #fef9c3 #854d0e Decision points, conditions Error / Critical #fee2e2 #991b1b Errors, alerts, critical paths External / Storage #f3e8ff #6b21a8 External services, databases, AI/ML Process / Default #e0f2fe #0369a1 Standard process steps Trigger / Start #fed7aa #c2410c Start nodes, triggers, events Neutral / Container #f1f5f9 #475569 Groups, swimlanes, backgrounds Text colors: Level Color Title #1e293b Label #334155 Description #64748b Rule: Do not invent new colors. Pick from this palette. Arrow semantics Style Meaning Solid ( strokeStyle: "solid" ) Primary flow, main path Dashed ( "dashed" ) Response, async, callback Dotted ( "dotted" ) Optional, reference, weak dependency Excalidraw JSON Structure File skeleton { "type" : "excalidraw" , "version" : 2 , "source" : "claude-code" , "elements" : [ ] , "appState" : { "viewBackgroundColor" : "#ffffff" } } Element types type use for rectangle boxes, components, modules ellipse start/end nodes, databases diamond decision points arrow directed connections line undirected connections text standalone labels image , frame , and embeddable are not covered by this skill: image needs a separate files map plus a fileId , and frames/embeds render inconsistently through the export path. Stick to the six types above — and for ready-made icons built from these primitives, see Community shape & icon libraries below. Community shape & icon libraries Need a real AWS / Azure / GCP / network / UML / BPMN icon instead of a plain box? The Excalidraw community libraries (200+ .excalidrawlib files) are built almost entirely from the same vector primitives above — so their items render through Kroki and the local CLI with no image element and no files map. Use the helper in scripts/excalidraw_lib.py : # 1. Find a library (matches name / description / item names) python scripts/excalidraw_lib.py search aws # 2. List its items (index, name, element count; flags any image-based item) python scripts/excalidraw_lib.py items slobodan/aws-serverless.excalidrawlib # 3. Build your base scene first, then drop an item in at (x, y). IDs are # namespaced and coordinates translated, so it merges without collisions: python scripts/excalidraw_lib.py merge scene.excalidraw \ slobodan/aws-serverless.excalidrawlib 0 455 257 --scale 0.9 --prefix lambda Rules: Vector only. merge refuses any item containing an image element (won't render via the export path); items flags them up front. Use sparingly. An icon is just a labeled node — keep the design system's spacing, labels, and arrow semantics. Icons accent a diagram; they don't replace it. Arrows don't bind to library groups — draw connectors with explicit edge-to-edge points (bindings don't affect the static export anyway). Libraries are MIT-licensed; a courtesy credit is welcome, not required. Still run Verify the Render afterward — icon bounding boxes vary, so check alignment and spacing. Element sizing Calculate element width from label text to prevent truncation: Latin text: width = max(160, charCount * 9) CJK text: width = max(160, charCount * 18) Mixed text: estimate each character individually, sum up Height: use 60 for single-line labels, add 24 per additional line. Standalone text does NOT auto-wrap. For multi-line standalone labels, insert manual \n line breaks yourself — aim for ≤ ~30 Latin (≤ ~15 CJK) characters per line at 16px — and add 24 height per line. (Text bound inside a shape via containerId wraps to the container width automatically, so size the container instead of adding \n .) Required properties (all elements) { "id" : "auth_service" , "type" : "rectangle" , "x" : 100 , "y" : 100 , "width" : 160 , "height" : 60 , "angle" : 0 , "strokeColor" : "#1e40af" , "backgroundColor" : "#dbeafe" , "fillStyle" : "solid" , "strokeWidth" : 2 , "roughness" : 0 , "opacity" : 100 , "seed" : 100001 , "boundElements" : [ { "id" : "arrow_to_db" , "type" : "arrow" } , { "id" : "label_auth" , "type" : "text" } ] } Use descriptive string IDs (e.g., "api_gateway" , "arrow_gw_to_auth" ) instead of random strings. Give each element a unique seed (integer). Namespace by section: 100xxx, 200xxx, 300xxx. JSON field rules boundElements : use null when empty, never [] updated : always use 1 , never timestamps Do NOT include: frameId , index , versionNonce , rawText points in arrows: always start at [0, 0] seed : must be a positive integer, unique per element Property values Use only these values — all verified to render via Kroki and the local CLI: Property Valid values fillStyle "solid" , "hachure" , "cross-hatch" , "zigzag" strokeStyle "solid" (or omit), "dashed" , "dotted" fontFamily 1 (Virgil, hand-drawn), 2 (Helvetica), 3 (Cascadia, code) textAlign "left" , "center" , "right" verticalAlign "top" , "middle" , "bottom" startArrowhead / endArrowhead null , "arrow" , "triangle" , "bar" , "dot" , "circle" , "diamond" , "crowfoot_many" Arrows default to endArrowhead: "arrow" and startArrowhead: null — omit both for a standard one-way arrow. Use "triangle" for UML inheritance, "diamond" for composition, and "crowfoot_many" for ER cardinality. Need copy-paste templates or the full property/arrowhead catalogue? Read references/schema-reference.md — complete element templates (component+label, bound arrow, arrow label, swimlane zone, mind-map connector) and every verified property value. Text inside shapes (contained text) When text belongs inside a shape, bind them bidirectionally: { "id" : "label_auth" , "type" : "text" , "text" : "Auth Service" , "fontSize" : 20 , "fontFamily" : 2 , "textAlign" : "center" , "verticalAlign" : "middle" , "strokeColor" : "#1e293b" , "containerId" : "auth_service" } CRITICAL: Text strokeColor is the text color. Always set it explicitly to a dark color from the text color palette. Never omit it — omitting strokeColor on text can cause invisible text that blends with the shape background. The parent shape must list the text in its boundElements : "boundElements" : [ { "id" : "label_auth" , "type" : "text" } ] Arrow binding (bidirectional) Arrows must bind to shapes, and shapes must reference bound arrows: { "id" : "arrow_gw_to_auth" ,