Skill: scottgl9/excalidraw-render (version 1.0.5)

--- name: excalidraw-diagram description: Create professional Excalidraw diagrams — flowcharts, architecture diagrams, workflows, systems, processes, or concepts. Use when user asks to "create a diagram", "draw a flowchart", "visualize a process", "make a flow diagram", "architecture diagram", "excalidraw", "technical diagram", or discusses workflow/process visualization. Supports quick DSL-based flowcharts and comprehensive hand-crafted JSON diagrams. Built-in PNG rendering and PDF export. metadata: openclaw: requires: bins: - python3 - uv - node - npm homepage: https://clawhub.ai/skills/excalidraw-render --- # Excalidraw Diagram Creator Generate `.excalidraw` files — from quick flowcharts to comprehensive technical diagrams. ## ⚠️ Golden Rule **Every diagram MUST be rendered to PNG and visually inspected before delivery.** Look at the actual image — check that text fits inside boxes, no elements overlap, arrows connect correctly, and spacing is balanced. Fix the JSON and re-render until it looks professional. See the **Render & Validate** section. No exceptions. --- ## Depth Gate (Do This First) | Need | Approach | Time | |------|----------|------| | Simple flowchart, decision tree, linear process | **Quick Path** — CLI DSL | ~1 min | | Architecture, multi-zoom technical, evidence artifacts | **Full Path** — hand-crafted JSON | ~10 min | --- ## Quick Path: CLI DSL Flowcharts For straightforward flows, use `@swiftlysingh/excalidraw-cli` (installed locally by `setup.sh`): ```bash excalidraw-cli create --inline "DSL" -o output.excalidraw ``` > **Note:** If `excalidraw-cli` is not in your PATH after setup, use: > `"$SKILL_DIR/.npm/node_modules/.bin/excalidraw-cli"` or re-run `setup.sh`. ### DSL Syntax | Syntax | Shape | Use For | |--------|-------|---------| | `[Label]` | Rectangle | Process steps | | `{Label?}` | Diamond | Decisions | | `(Label)` | Ellipse | Start/End | | `[[Label]]` | Database | Data storage | | `->` | Arrow | Connection | | `-> "text" ->` | Labeled arrow | Conditional | | `-->` | Dashed arrow | Optional path | Directives: `@direction LR|TB|RL|BT`, `@spacing 60` ### DSL Example ```bash excalidraw-cli create --inline "$(cat <<'EOF' @direction TB (Start) -> [Receive Request] -> {Authenticated?} {Authenticated?} -> "yes" -> [Process Request] -> (Success) {Authenticated?} -> "no" -> [Return 401] -> (End) EOF )" -o auth-flow.excalidraw ``` CLI options: `-d LR` (direction), `-s 80` (spacing), `--format dot` (DOT/Graphviz input). After generation, **always render and validate** (see Render section below). Fix overlaps or clipping in the JSON if needed. --- ## Full Path: Hand-Crafted JSON Diagrams For comprehensive, professional diagrams. Read these references as needed: - **`references/color-palette.md`** — All colors (read FIRST, every time) - **`references/element-templates.md`** — Copy-paste JSON for each element type - **`references/json-schema.md`** — Full property reference - **`references/layout-rules.md`** — Anti-overlap spacing and text-sizing rules ⚠️ READ THIS ### Design Process 1. **Assess depth** — simple/conceptual vs. comprehensive/technical 2. **Research** (technical diagrams) — look up real specs, event names, API formats 3. **Map concepts to visual patterns** — see Pattern Library below 4. **Sketch mentally** — trace how the eye moves through the diagram 5. **Generate JSON section-by-section** — see Large Diagram Strategy 6. **Render & validate** — MANDATORY loop (see below) ### JSON Structure ```json { "type": "excalidraw", "version": 2, "source": "https://excalidraw.com", "elements": [...], "appState": { "viewBackgroundColor": "#ffffff", "gridSize": 20 }, "files": {} } ``` ### Core Rules - `fontFamily: 3`, `roughness: 0`, `opacity: 100` on all elements - `text` property = ONLY readable words (no markup) - **Size containers to fit text** — see `references/layout-rules.md` - **Minimum 40px gap** between elements — see `references/layout-rules.md` - Default to free-floating text; use containers only when meaningful (<30% text in boxes) ### Visual Pattern Library | Concept Behavior | Pattern | |------------------|---------| | One source → many outputs | **Fan-out** (radial arrows from center) | | Many inputs → one output | **Convergence** (arrows merging) | | Hierarchy/nesting | **Tree** (lines + free-floating text) | | Sequence of steps | **Timeline** (line + dots + labels) | | Feedback loop | **Spiral/Cycle** (arrow returning to start) | | Abstract state | **Cloud** (overlapping ellipses) | | Transformation | **Assembly line** (before → process → after) | | Comparison | **Side-by-side** (parallel structures) | | Phase changes | **Gap/Break** (visual whitespace) | ### Shape Meaning | Concept | Shape | |---------|-------| | Labels, descriptions | Free-floating text (no container) | | Timeline markers | Small ellipse (12px) | | Start/trigger | Ellipse | | End/output | Ellipse | | Decision | Diamond | | Process/action | Rectangle | ### Evidence Artifacts (Technical Diagrams) | Artifact | Rendering | |----------|-----------| | Code snippets | Dark rect (`#1e293b`) + syntax-colored text | | JSON/data | Dark rect (`#1e293b`) + green text (`#22c55e`) | | Event sequences | Timeline (line + dots + labels) | | UI mockups | Nested rectangles | ### Large Diagram Strategy Build JSON **one section at a time** (Claude has ~32k token output limit): 1. Create base file + first section 2. Add one section per edit — use descriptive IDs (`"trigger_rect"`, `"auth_arrow"`) 3. Namespace seeds by section (100xxx, 200xxx, etc.) 4. Update cross-section bindings as you go 5. Review the whole before rendering ### Multi-Zoom (Comprehensive Diagrams) - **Level 1** — Summary flow (simplified overview) - **Level 2** — Section boundaries (labeled regions) - **Level 3** — Detail (evidence artifacts, code snippets, real data) --- ## Render & Validate (MANDATORY) **Every diagram must be rendered and visually inspected before delivery.** This catches overlap, text clipping, and spacing issues that are invisible in JSON. ### Render Command ```bash cd ~/.openclaw/skills/excalidraw-diagram && uv run python render_excalidraw.py <path-to-file.excalidraw> ``` Outputs a PNG next to the `.excalidraw` file. Use the **Read tool** to view it. ### First-Time Setup ```bash cd ~/.openclaw/skills/excalidraw-diagram bash setup.sh # builds local Excalidraw bundle (requires node/npm) uv sync && uv run playwright install chromium ``` ### The Loop (repeat until professional) 1. **Render** the PNG 2. **View the image** with the Read tool — actually look at it 3. **Inspect systematically:** - Does every label fit cleanly inside its box? (no clipping, no overflow) - Are all boxes/shapes clearly separated? (no overlapping edges) - Are arrows connecting the right elements without crossing through others? - Is spacing even and consistent between similar elements? - Is text large enough to read? - Does the overall layout look balanced and professional? 4. **Fix the JSON** for every issue found — widen containers, adjust x/y, add arrow waypoints, increase gaps 5. **Re-render and re-view** — look at the new PNG 6. **Repeat** until every issue is resolved (typically 2-4 iterations, sometimes more) **Do not skip this loop.** JSON coordinates are approximate — you will almost always find issues on the first render. The visual check IS the quality gate. ### Stop When - No text overflow or overlapping - Arrows route cleanly - Consistent spacing, balanced composition - You'd show it without caveats --- ## PNG & PDF Export ### PNG (for Word, presentations, sharing) The render script outputs high-res PNG (2x scale by default): ```bash cd ~/.openclaw/skills/excalidraw-diagram && uv run python render_excalidraw.py diagram.excalidraw --output diagram.png --scale 3 ``` Options: `--scale 3` (3x for print), `--width 2560` (wider viewport). ### PDF (for documents, printing) Convert PNG to PDF: ```bash # ImageMagick (most common) convert diagram.png -density 150 diagram.pdf # Or with a white background and margins convert diagram.png -gravity center -background white -extent 110%x110% -density 150 diagram.pdf ``` For multi-page or A4/Letter sizing: ```bash convert diagram.png -resize 1800x -gravity center -background white \ -extent 2100x2970 -units PixelsPerInch -density 254 diagram-a4.pdf ``` --- ## Quality Checklist ### Layout & Overlap - [ ] All text fits within containers (used layout-rules.md sizing formula) - [ ] Minimum 40px gap between all elements - [ ] Arrows don't cross through elements - [ ] Even spacing between similar elements - [ ] Balanced composition (no voids or overcrowding) ### Visual - [ ] `roughness: 0`, `opacity: 100`, `fontFamily: 3` everywhere - [ ] Colors from `references/color-palette.md` - [ ] Text readable at export size - [ ] Clear visual flow (eye path) ### Technical (if applicable) - [ ] Real specs/event names/API formats (not placeholders) - [ ] Evidence artifacts included - [ ] Multi-zoom levels present ### Export - [ ] Rendered to PNG and visually validated - [ ] PNG/PDF delivered if user needs it


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)