excalidraw-generator · diff
v1.4.0 to v1.5.0
80 added, 111 removed. Audit A to A.
---
name: excalidraw-generator
description: "Generate diagrams as valid Excalidraw JSON — flowcharts, architecture, ER diagrams, mind maps, sequence diagrams, wireframes, C4 models, and more. Don't use for draw.io/Mermaid output, slide decks, or pixel-perfect brand graphics."
license: MIT
effort: high
metadata:
- version: 1.4.0
+ version: 1.5.0
author: "Luong NGUYEN <luongnv89@gmail.com>"
---
# Excalidraw Diagram Generator
- Generate professional diagrams as valid Excalidraw JSON. Every diagram goes through four phases: **Understand** the request, **Propose** options, **Generate** the JSON, and **Validate** before writing the file.
+ Generate professional diagrams as valid Excalidraw JSON. Every request flows through four phases — **Understand**, **Propose**, **Generate**, **Validate** — before the file is written. The body stays lean to respect the agent's context budget; depth lives in `references/`.
> Part of the **diagram-generator** suite. For precise, editable-in-draw.io output, use `drawio-generator` instead; the `diagram-generator` umbrella routes between the two.
- This SKILL.md is intentionally compact to fit the agent's context budget (token-efficient body). Long-form details live in `references/` — read the linked file when you need depth.
-
## When to Use
- Triggers/exclusions are set by the frontmatter `description` above. Output is an Excalidraw file, or embedded in Markdown via the `excalidraw` fenced block if the user asks for that.
+ The frontmatter `description` sets triggers and exclusions. Output: a `.excalidraw` file, plus a companion `.md` only on request.
## Environment Check
- If the Agent tool is available, use the subagent review loop described in `references/style-and-iteration.md` (Subagent Architecture). It provides fresh-context validation and avoids single-pass context overflow.
-
- If the Agent tool is unavailable (e.g., Claude.ai), execute every phase inline and self-review against the 10 checks (less rigorous, but functional).
+ If the Agent tool is available, use subagents per *Subagent Architecture* for large diagrams; fresh-context validation avoids single-pass context overflow. Without it (e.g., Claude.ai), run every phase inline and self-review against the 10 checks.
## Repo Sync Before Edits (mandatory)
- The `.excalidraw` file (and any companion `.md`) is written to the current working directory at the end of the workflow. When that path lives inside a git worktree, sync before the write to avoid clobbering remote work:
+ Run this once: before reading an existing `.excalidraw` file (*Iteration*), otherwise before the Phase 4 write. The sync target is the output file's directory.
- ```bash
- branch="$(git rev-parse --abbrev-ref HEAD)"
- git fetch origin
- git pull --rebase origin "$branch"
- ```
+ 1. Run `repo="$(git -C "<output dir>" rev-parse --show-toplevel)"`. If it fails, skip the sync and record `sync: skipped (not a git repo)`.
+ 2. Run `git -C "$repo" remote get-url origin`. If it fails, skip steps 3–7 and record `sync: skipped (no origin)`.
+ 3. Run `branch="$(git -C "$repo" rev-parse --abbrev-ref HEAD)"`. If it prints `HEAD`, skip steps 4–7 and record `sync: skipped (detached HEAD)`.
+ 4. Run `git -C "$repo" status --porcelain`. If the output is empty, run `git -C "$repo" fetch origin && git -C "$repo" pull --rebase origin "$branch"`.
+ 5. If the output is not empty, run `git -C "$repo" stash push -u -m "excalidraw-generator pre-sync"`, then the same fetch and pull, then `git -C "$repo" stash pop`.
+ 6. If `fetch` or `pull` fails before a rebase starts (network, authentication, or a missing remote branch), do not retry. Run `git -C "$repo" stash pop` when step 5 stashed, record `sync: failed (<first error line>)`, and continue. The Final Report repeats it on the `Uncertainty:` line.
+ 7. If the rebase conflicts, run `git -C "$repo" rebase --abort`, then `git -C "$repo" stash pop` when step 5 stashed. If the stash pop conflicts, leave the stash in place. In both cases do not write the file; stop and ask the user how to continue. With no answer, the status is `BLOCKED`.
- If the working tree is dirty: stash → sync → pop. If `origin` is missing or a conflict occurs: **stop and ask the user.** Skip this section only when the output path is outside any git repository.
+ This skill commits nothing.
## Core Workflow
### Phase 1: Understand
Confirm what to draw before generating anything.
- - **Clear description** ("draw a flowchart of user authentication"): restate your understanding in one sentence and propose the visualization type.
- - **Ambiguous input**: ask targeted questions — main entities/nodes, relationships, flow direction, style preference.
- - **Code, data, schemas, or files**: extract structure (code → class/dependency/architecture; SQL → ER; JSON/YAML → architecture/deployment; steps → flowchart/sequence; org data → org chart/tree).
+ - **Clear request** — restate it in one sentence and propose a visualization type.
+ - **Ambiguous input** — ask about entities, relationships, flow direction, style.
+ - **Code, data, schemas, or files** — extract structure (SQL → ER, steps → flowchart; full mapping in `references/diagram-types.md`).
### Phase 2: Propose
- Present a plan with selectable options:
+ Present the numbered plan below.
- 1. **Diagram type** — see `references/diagram-types.md` for the catalogue. If multiple fit, present numbered options.
- 2. **Key elements** — list the nodes/shapes you'll include.
- 3. **Layout** — propose 2–3 choices (e.g., `(A) Top-to-bottom`, `(B) Left-to-right`, `(C) Radial`).
- 4. **Style** — see `references/style-and-iteration.md`. Pick rendering style (clean/hand-drawn/sketchy) and color scheme that fits the diagram's purpose. No fixed palette.
- 5. **Complexity** — small (<10 elements), medium (10–30), large (30+).
+ - If the request names the diagram type and every element, or the user says "just do it", state the defaults you chose in one line and proceed to Phase 3. Defaults: hand-drawn, `roughness: 1`, Virgil font (`fontFamily: 1`), best-fit layout.
+ - Otherwise, wait for the user to confirm or change the plan. Do not generate JSON before the user answers.
- Wait for confirmation. If the user says "just do it" or the request is straightforward, use sensible defaults (hand-drawn, roughness 1, Virgil font, best-fit layout) and proceed.
+ 1. **Diagram type** — catalogue in `references/diagram-types.md`; offer numbered alternatives if several fit.
+ 2. **Key elements** — list the nodes and shapes.
+ 3. **Layout** — e.g. `(A) Top-to-bottom`, `(B) Left-to-right`, `(C) Radial`.
+ 4. **Style** — rendering style (hand-drawn, sketchy, clean) and a color scheme that fits the purpose; variants in `references/style-and-iteration.md`. No fixed palette.
+ 5. **Estimated complexity** — small (<10 elements), medium (10–30), large (>30).
### Phase 3: Generate
- Compose the `.excalidraw` document in memory (raw JSON, no wrapper) — the file is written to the current working directory in Phase 4, after validation passes. Use kebab-case names (`auth-flow.excalidraw`). The required envelope:
+ Compose the `.excalidraw` document in memory (raw JSON, no wrapper). Phase 4 writes the file.
- ```json
- {
- "type": "excalidraw",
- "version": 2,
- "source": "https://excalidraw.com",
- "elements": [],
- "appState": { "theme": "light", "viewBackgroundColor": "#ffffff" },
- "files": {}
- }
- ```
+ Output path: use the path the user gave. Otherwise use a descriptive kebab-case name ending in `.excalidraw` (`auth-flow.excalidraw`) in the current working directory. If that file exists and the user did not ask to update it, confirm with the user before you overwrite it; to update it, follow *Iteration*.
- Set `theme` and `viewBackgroundColor` to whatever suits the diagram. For full element schema and field defaults, see `references/excalidraw-format.md`.
+ Start from the envelope in `references/excalidraw-format.md` → *Top-Level Structure* (`type`, `version`, `source`, `elements`, `appState`, `files`); set `theme` and `viewBackgroundColor` to suit the diagram. That file holds the full element schema and field defaults.
- **Embedding in Markdown**: if the user asks to embed the diagram in a `.md` file, write the `.excalidraw` first, then a companion `.md` that references it via a fenced block tagged `excalidraw` containing the same JSON.
+ Critical rules every element must follow:
+ - Include every required field from `references/validation-checks.md` → *Check 2*.
+ - Use descriptive kebab-case IDs (`node-api-gateway`).
+ - Size each container to fit its bound text (*Check 10*); grow the shape, never shrink the text below `fontSize: 16`.
+ - Bind text and arrows in both directions (`containerId` ↔ `boundElements`, `startBinding`/`endBinding` ↔ `boundElements`).
+ **Embedding in Markdown:** only when asked, write the `.excalidraw` file first, then a companion `.md` holding the same JSON in a fenced block tagged `excalidraw`.
+
### Phase 4: Validate
- Before writing the file, run all 10 checks on the in-memory JSON. Fix and re-check until all pass, then write the `.excalidraw` file to the current working directory. Full check definitions and fix recipes are in `references/validation-checks.md`. Quick summary:
+ Run all 10 checks on the in-memory JSON before writing the file. See `references/validation-checks.md` for checks, the Check 10 formula, and fixes.
- 1. **Valid JSON** — top-level keys present.
- 2. **Required fields** — every element has the full field list (id, type, geometry, styling, `boundElements`, `seed`, etc.). Text adds `text/fontSize/fontFamily/textAlign/verticalAlign/containerId/originalText/lineHeight/autoResize`. Arrows add `points/startBinding/endBinding/startArrowhead/endArrowhead`.
- 3. **Unique IDs** — no duplicates.
- 4. **Two-way text bindings** — `containerId` ↔ `boundElements` `{type:"text"}`.
- 5. **Two-way arrow bindings** — `startBinding/endBinding` ↔ `boundElements` `{type:"arrow"}`.
- 6. **Arrow points** — `points` length ≥ 2 and `points[0] === [0,0]`.
- 7. **No unintentional overlaps** — bounding boxes don't overlap by more than 10px (unless grouped or inside a frame).
- 8. **Semantic completeness** — every entity/relationship the user mentioned is represented.
- 9. **Readable text** — `fontSize ≥ 16`, visible `strokeColor`, `lineHeight: 1.25` (never 1.35), `autoResize: true`.
- 10. **Shape-to-text size fit** — see below; this is the #1 failure mode.
+ 1. Run the 10 checks. If all pass, run *Repo Sync*, write the file, and give the *Final Report* with status `COMPLETE`.
+ 2. If a check fails, fix it and re-run all 10 checks. A failure of check 1 or 8 needs a Phase 3 regeneration, not a patch. Stop after 3 fix cycles.
+ 3. If checks 1–6 pass but a check from 7–10 still fails after cycle 3, run *Repo Sync*, write the file, and report `PARTIAL` with the failed check numbers.
+ 4. If a check from 1–6 still fails after cycle 3, do not write the file. Report `BLOCKED` with the failed checks.
- #### Check 10 — shape sizing (always verify)
+ The 10 checks: (1) JSON envelope, (2) required fields, (3) unique IDs, (4) text bindings, (5) arrow bindings, (6) arrow points, (7) overlaps, (8) semantic completeness, (9) readable text, (10) shape-to-text fit — the most common failure.
- For every text element with `containerId`:
+ ---
- 1. `line_count = text.split('\n').length`
- 2. `min_text_height = line_count * fontSize * 1.25`
- 3. `min_shape_height = min_text_height + 40` (20px padding top/bottom)
- 4. The container shape's `height` must be `>= min_shape_height`.
- 5. The container shape's `width` must be `>= longest_line_pixel_width + 20`.
+ ## Expected Output
- Boundary/container labels (e.g., "System Boundary") must be standalone text with `containerId: null`, positioned near the top-left of the container — never bound to it.
+ For "draw a flowchart of the user login process": a `login-flow.excalidraw` file written to disk (raw JSON), then the *Final Report*. A bound shape-and-label pair is in `references/excalidraw-format.md` → *Minimal bound-text example*.
- **Fix**: increase the shape's height/width to fit the text and shift elements below it to keep spacing. Always set `lineHeight: 1.25` and `autoResize: true` on text. Never patch individual outputs — report a new failure pattern in the step completion report instead.
+ ## Final Report
- After all checks pass, emit the validation summary (10/10 passed, element counts, binding counts, "all shapes sized to fit", any auto-fixes applied).
+ End every run, stops included, with this compact text block. A Phase 1–2 question that awaits the user's answer does not end the run; if the user ends the run without answering, report `BLOCKED`. Status is `COMPLETE` (file written, 10/10 checks pass), `PARTIAL` (file written, a check from 7–10 failed), or `BLOCKED` (no file written). Fill rules, `PARTIAL` and `BLOCKED` examples, and reader checks: `references/final-report.md`. Example:
- ## Step Completion Reports
+ ```
+ Result: COMPLETE. Wrote login-flow.excalidraw (6 shapes, 6 text labels, 5 arrows).
+ Evidence: /abs/path/login-flow.excalidraw. Validation 10/10 checks passed (inline, 1 cycle). sync: skipped (not a git repo)
+ Uncertainty: Rendering in Excalidraw untested. Assumed top-to-bottom flow; the request gave no direction.
+ Decision: No approval needed.
+ ```
- After each phase, output a status block. Templates and check labels for each phase live in `references/step-reports.md`. Result line is `PASS | FAIL | PARTIAL`.
+ ## Acceptance Criteria
- ## Expected Output
+ Verify these for every run:
- For "draw a flowchart of the user login process": file `login-flow.excalidraw` containing valid Excalidraw JSON, plus a validation summary in the response. Example fragment:
+ - [ ] A `.excalidraw` file is written to disk and its JSON parses with top-level `type`, `version`, `elements`, `appState`, `files`, unless the status is `BLOCKED`.
+ - [ ] Checks 1–7, 9 and 10 in `references/validation-checks.md` pass, or the Final Report lists each failed check.
+ - [ ] Every entity and relationship in the user's request is represented in the output (check 8).
+ - [ ] The Final Report opens with `Result:` and its status, and has `Evidence:`, `Uncertainty:` and `Decision:` lines. `Evidence:` cites only checks that ran; `10/10` appears only when all 10 passed.
+ - [ ] The Final Report passes the four reader checks in `references/final-report.md` (result findable, facts and assumptions separated, claims traceable, next decision clear). Without a human reviewer's answer, human understanding is unconfirmed.
- ```json
- {
- "type": "excalidraw", "version": 2, "source": "https://excalidraw.com",
- "elements": [
- {"id": "start-1", "type": "ellipse", "x": 300, "y": 40, "width": 120, "height": 56,
- "boundElements": [{"id": "txt-start", "type": "text"}]},
- {"id": "txt-start", "type": "text", "text": "Start", "fontSize": 18, "fontFamily": 1,
- "containerId": "start-1", "lineHeight": 1.25, "autoResize": true}
- ],
- "appState": {"theme": "light", "viewBackgroundColor": "#ffffff"}, "files": {}
- }
- ```
+ ## Edge Cases
- Expected response includes:
- ```
- Validation: 10/10 checks passed
- - Elements: 6 shapes, 6 text labels, 5 arrows
- - Bindings: 6 text bindings, 10 arrow bindings (all two-way)
- - Text fits: all shapes sized to fit their bound text
- - No overlaps, no missing fields
- ```
+ - **Empty or vague input** ("make a diagram"): ask targeted clarifying questions before generating — never produce a placeholder.
+ - **Large diagram (>30 elements)**: run the *Subagent Architecture* loop; cap at 3 fix cycles.
+ - **Very large diagram (>50 elements)**: warn that one canvas will be crowded; offer frames, several files, or an overview first, and wait for the choice.
+ - **Ambiguous relationships**: ask for direction and cardinality before generating.
+ - **Unsupported diagram type** (e.g., a chart that needs real axis scales): explain the limitation and propose the closest supported type from `references/diagram-types.md`.
+ - **User supplies an existing `.excalidraw` file**: follow *Iteration* — never regenerate it from scratch.
- ## Edge Cases
+ More edge cases: `references/style-and-iteration.md`.
- - **30+ elements** — spawn the subagent review loop in `references/style-and-iteration.md`; cap at 3 fix cycles.
- - **Text-heavy nodes** — apply Check 10 strictly; bigger shapes, never smaller text.
- - **Ambiguous relationships** — ask before guessing; saves a regeneration cycle.
- - **"Just do it"** — defaults (hand-drawn, roughness 1, Virgil, best-fit layout); skip the proposal.
- - **Iteration on an existing file** — read the file, preserve unchanged IDs, modify only the requested parts, rewrite.
+ ---
- See `references/style-and-iteration.md` for extended edge cases, iteration patterns, and style variants.
+ ## Step Completion Reports
- ## Acceptance Criteria
+ After each phase, print a short status report with that phase's checks; the template and per-phase checks are in `references/step-reports.md`. The Validate report precedes the *Final Report*; it does not replace it.
- - [ ] Output file is valid JSON with top-level `type`, `version`, `elements`, `appState`, `files`.
- - [ ] Every element has all required fields (per `references/validation-checks.md` Check 2).
- - [ ] Text elements have `fontSize >= 16`, `lineHeight: 1.25`, `autoResize: true`.
- - [ ] All element IDs are unique.
- - [ ] Text-to-shape bindings are two-way (`containerId` ↔ `boundElements`).
- - [ ] Arrow bindings are two-way (`startBinding`/`endBinding` ↔ `boundElements`).
- - [ ] Every arrow has `points[0] === [0,0]` and length ≥ 2.
- - [ ] No bounding boxes overlap by more than 10px (outside groups/frames).
- - [ ] Every entity/relationship from the user's request is represented.
- - [ ] Every container shape is sized to fit its bound text (Check 10).
- - [ ] Validation report (10/10 summary) is included in the response.
+ ## Iteration
- ## Supported Diagram Types
+ When iterating on an existing diagram, read the file and modify the JSON in memory. Preserve element IDs that haven't changed (request patterns: `references/style-and-iteration.md` → *Iteration*). Run Phase 4 on the result before rewriting the file; a `BLOCKED` result leaves the original file untouched.
- Full catalogue with layout guidance: `references/diagram-types.md`. Categories: Flow & Process, Architecture, Data & Relationships, Planning, Comparison, Data Viz, UX/Design, Custom. If the request doesn't map cleanly to one type, propose the closest fit and explain why.
+ ---
- ## References
+ ## Subagent Architecture
- - `references/validation-checks.md` — full text of all 10 Phase-4 checks plus fix recipes.
- - `references/excalidraw-format.md` — Excalidraw JSON schema and field defaults.
- - `references/diagram-types.md` — diagram-type catalogue with layout guidance.
- - `references/style-and-iteration.md` — style variants, iteration patterns, subagent architecture, extended edge cases.
- - `references/step-reports.md` — step completion report templates per phase.
- - `agents/json-generator.md`, `agents/json-validator.md`, `agents/json-fixer.md` — subagent specs for the large-diagram review loop.
+ Large diagrams (>30 elements) run this loop; others run inline. Detail: `references/style-and-iteration.md` → *Subagent Architecture*.
+
+ 1. **Generate** — spawn `agents/json-generator.md` with the confirmed plan.
+ 2. **Validate** — spawn `agents/json-validator.md`; it reports PASS/FAIL for all 10 checks.
+ 3. **Fix** — on NEEDS_FIX, spawn `agents/json-fixer.md`, which patches and never regenerates. If it returns `ready_for_validation: false` (check 1 or 8), re-spawn the generator instead. Each fix or regeneration is one cycle; stop at 3.
+ 4. The main agent applies Phase 4 steps 1–4 to the returned JSON and last validator report.
+