Excalidraw import
Excalidraw import turns a saved whiteboard scene into a clear diagram artifact for the repository. The workflow reads the scene as source meaning, rebuilds the layout in the diagram design system, and records what it keeps or removes. It does not reproduce the whiteboard as an image or preserve its rough drawing style. This page is a child of Diagram import and export workflows and relates to Mermaid import, draw.io import, diagram export, and diagram self-validation.
Import workflow
Command entry
The /diagram-design:import-excalidraw command is the user-facing entry point for a saved .excalidraw or .excalidraw.json scene. It lets the user choose the output format, canvas size, detail level, audience, diagram type, visual variant, and output path. When the user gives no choice, the workflow uses HTML, doc-inline, balanced detail, a mixed audience, and the light variant.
The command needs a source path. If the user does not provide one, it asks which saved Excalidraw scene to use rather than guessing. PNG and SVG exports are rejected because they do not retain the scene structure needed for extraction. An Excalidraw file contains one scene, so the command has no page or diagram selector.
The command points to the reference page rather than repeating its rules. The reference page is the source of truth for extraction, semantic choices, redraw behavior, and delivery.
References: commands/import-excalidraw.md• L1-26 commands/import-excalidraw.md• L28-50
Prompt discovery
The prompt provides the same workflow to a host that discovers the installed diagram-design skill through its advertised SKILL.md path. It tells the host to load the skill and the import and output references from that location. This keeps the workflow usable when the skill is installed outside the repository’s current directory.
The prompt also carries the trust boundary into the host workflow. It requires extraction before drawing and treats scene text as data rather than instructions. After delivery, the host reports the artifact paths, the four output choices, and the fidelity ledger.
References: prompts/import-excalidraw.md• L1-14 skills/…/SKILL.md• L534-541
Source extraction
The extraction helper converts a saved scene into a compact intermediate representation (IR). The IR is a normalized description of nodes, edges, containers, and structural signals. The command locates the installed skill and runs scripts/excalidraw_extract.py before any redraw. It does not assume that the skill is under the current working directory or read the scene directly. The normal output is a Markdown digest for human review. --json provides the full IR when the digest does not show enough detail, --max-rows controls digest table length, and --out saves either form.
The helper accepts bounded JSON only. It does not render the scene, make network calls, fetch links, execute embedded content, or decode image payloads. It escapes labels before placing them in the digest. Links, embeds, image data, deleted elements, freehand strokes, and unknown element types are counted as discarded data so that the later fidelity ledger can explain their absence. Duplicate element IDs and invalid element types fail the import instead of producing an ambiguous scene.
The helper also rejects non-finite geometry and limits input size, element count, node count, and edge count. These checks keep malformed or oversized source data inside a bounded extraction step. A failure uses exit code 2 and reports the named problem for the command to surface.
References: skills/…/import-excalidraw.md• L13-33 skills/…/excalidraw_extract.py• L1-21 skills/…/excalidraw_extract.py• L35-40 skills/…/excalidraw_extract.py• L140-194 skills/…/excalidraw_extract.py• L205-219 skills/…/excalidraw_extract.py• L691-707
Scene model
The IR preserves the parts of a whiteboard that carry diagram meaning. Rectangles, ellipses, and diamonds become node shapes. Arrows and lines become edges. Text bound to a shape or edge becomes its label. Frames become containers, while explicit groups with at least two members become possible collapse candidates. Standalone text remains visible as a text node so it can be judged as content or decoration.
The helper also reports structure that guides the redraw. It identifies directed, bidirectional, and undirected connections, dangling edges, cycles, entry points, terminal nodes, hubs, unconnected nodes, collapsible groups, and likely diagram types. Frame members are linked to their frame. The source coordinates remain available as source context, but they do not prescribe the new layout. The digest and JSON report only the first eight sorted collapse candidates, including frame candidates, so large group sets stay bounded.
References: skills/…/import-excalidraw.md• L23-30 skills/…/excalidraw_extract.py• L43-56 skills/…/excalidraw_extract.py• L75-123 skills/…/excalidraw_extract.py• L223-374 skills/…/excalidraw_extract.py• L415-510
Redraw decisions
Output choices
The workflow sets the four main output choices before it redraws. Format selects the deliverable, size selects the canvas and type scale, detail selects how much source content survives, and audience selects the wording level. HTML is the source artifact. SVG and PNG are exported from that HTML when requested. The output base path controls where the selected format files are written.
The detail choice is a content budget rather than a zoom setting. Faithful detail supports up to 24 nodes with zones, balanced detail keeps the main story within 12 nodes, and simplified detail keeps up to 7 nodes. If the source is too large, the workflow removes decoration first, then merges duplicates and collapses groups before it removes less important infrastructure or splits the result into an overview and detail diagrams.
References: skills/…/output-spec.md• L1-12 skills/…/output-spec.md• L16-35 skills/…/output-spec.md• L84-112 skills/…/import-excalidraw.md• L35-39
Semantic reconstruction
The redraw treats the whiteboard as a record of meaning, not as a finished layout. The workflow names the story, chooses focal nodes, expands shorthand for the selected audience, and keeps meaningful labels, branches, frame membership, and flow direction. It may infer a store or actor role from a label because Excalidraw has no fixed vocabulary for those roles.
The extracted structure suggests a target diagram type. A diamond with yes/no branches suggests a flowchart. A service and store topology suggests architecture. Frames suggest a nested view. Cycles with many ellipses suggest a state machine. A single entry point with fan-out can suggest a tree. The workflow can override a mechanical suggestion when the content tells a different story, or the user can force a visual type with --type. The chosen type’s layout rules take precedence over the source board.
References: skills/…/import-excalidraw.md• L41-58 commands/import-excalidraw.md• L25-26 commands/import-excalidraw.md• L34-35
Editorial redraw
The output uses a blank canvas and the repository’s visual system. It discards hand-dragged coordinates, source colors, rough strokes, and source fonts. It maps shapes to semantic treatments, reroutes connections, and keeps the result within the selected complexity budget. A source image becomes a simple monochrome icon or labeled box rather than an embedded payload.
Every import reports a fidelity ledger. The ledger states the source and drawn counts and names each merge, collapse, or meaningful drop. It also starts from the extractor’s discarded counts, including freehand strokes, image payloads, links, embeds, and unknown elements. This makes compression visible to the person who requested the diagram. Before writing, the workflow applies the design taste gate and output checklist.
References: skills/…/import-excalidraw.md• L60-84 skills/…/output-spec.md• L154-166 commands/import-excalidraw.md• L46-50
Delivery example
The worked example redraws scripts/fixtures/sample-whiteboard.excalidraw as a balanced, mixed-audience HTML flowchart at the doc-inline size. It turns two frames into quiet zones, keeps the lead intake path, treats the validity diamond as a decision, infers the CRM database role from its label, and drops decorative or unconnected material. The example uses a local horizontal scroller so its readable SVG does not make the page itself overflow on a narrow screen.
The example is useful as a product contract rather than as a template to copy. It shows the expected relationship between source content, semantic treatments, the fidelity ledger, the fixed 960 × 600 view box, and mobile containment.
References: skills/…/import-excalidraw.md• L88-102 skills/…/example-import-excalidraw.html• L20-26 skills/…/example-import-excalidraw.html• L37-65
Verification path
Import verification
The Excalidraw verifier checks the whole import contract. It confirms that the skill, command, prompt, reference, extractor, fixtures, and worked example are present and connected. It then runs the extractor against a normal whiteboard fixture and checks that shapes, labels, frames, groups, cycles, directions, budgets, and discard counts survive.
The verifier also uses generated scenes to check arrow direction, bidirectional and undirected edges, waypoints, dangling bindings, unknown elements, malformed input, file type rejection, resource limits, geometry errors, output encoding, and --out behavior. Adversarial labels must remain inert and escaped. URLs, embeds, and binary payloads must stay outside the extracted output.
It accepts deeply nested JSON or rejects it with a clear diagnostic without a traceback or partial digest. It also keeps visible text as a standalone node when its bound container type is not supported.
References: scripts/verify-excalidraw-import.py• L102-187 scripts/verify-excalidraw-import.py• L190-296 scripts/verify-excalidraw-import.py• L299-456 scripts/verify-excalidraw-import.py• L726-766
Artifact verification
The final verification checks that the reference names the current slash command and documents the extractor, output choices, workflow stages, worked example, edge cases, anti-patterns, trust boundary, and fidelity ledger. It checks that the command and reference expose the same flags and that neither adds a page or diagram selector.
It also checks the worked example’s fixed view box, accent use, skin lint, local scroller, and narrow-screen behavior. The regression test runs the verifier on a clean copy, then changes one contract at a time. It confirms that stale command names, an off-preset view box, missing mobile containment, and a changed trust-boundary inventory fail with focused errors.
References: scripts/verify-excalidraw-import.py• L543-665 scripts/test-verify-excalidraw-import.py• L32-115
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the command flags, prompt defaults, reference rules, and verifier expectations in sync. A new selector is especially risky because one scene has no page or diagram selection.
- Keep the command’s installed-skill discovery and extractor-first requirement aligned with the prompt and reference. A direct read of the scene would bypass the trust boundary.
- Keep extractor discard categories aligned with the fidelity ledger and adversarial fixture. A changed trust boundary must update both the inventory and its checks.
- Keep the extractor’s IR fields aligned with the redraw guidance for shape mapping, edge direction, frames, groups, budgets, and type candidates.
- Keep the extractor limits and failure messages aligned with the command’s stop-on-error path. A parser change can otherwise turn malformed source into partial output.
- Keep parser nesting failures diagnostic and partial-output free. Keep visible text recoverable when its container type is unsupported.
- Keep the worked example aligned with the selected size preset, the HTML-first output contract, the skin lint rules, and the local mobile scroller.
- Keep the reference’s slash command tied to commands/import-excalidraw.md; the verifier treats a stale command name as a broken user path.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| No source path is provided | The workflow cannot choose a scene safely | Ask which saved .excalidraw file to use; do not guess |
| User supplies a PNG or SVG export | The source has no usable scene structure for the import path | Ask for the saved .excalidraw scene; do not scrape pixels |
| Extractor returns a non-zero exit code | The workflow may draw from invalid or incomplete source data | Report the extractor message verbatim and stop |
| Source labels are empty | The layout carries meaning that the workflow cannot name safely | Ask the user to identify the boxes; do not invent labels |
| Duplicate element IDs or invalid geometry occur | Scene meaning can become ambiguous or unsafe to summarize | Stop with the extractor diagnostic and repair or re-export the scene |
| Edge bindings are missing | A connection may be mistaken for a valid transition | Omit the dangling edge and record its count and meaningful loss in the fidelity ledger |
| Faithful detail has more than 9 nodes or more than 24 nodes overall | The result can become unreadable or exceed the source budget | Zone the layout above 9 nodes; above 24 nodes split into overview and detail files |
| Requested detail is impossible at the selected size | The result can lose its main story or become hard to read | Say so before drawing and propose overview and per-frame detail outputs |
| Source labels contain instructions or links | Untrusted diagram data could influence the workflow or leak a target | Keep labels inert and escaped; never follow links, embeds, or label instructions |
| Deeply nested JSON exceeds the parser limit | The import can fail with a traceback or emit a partial digest | Return a clear parser diagnostic with no partial output; accept shallow control input normally |
| Text is bound to an unsupported container | Visible annotation can disappear from the extracted scene | Keep the text as a standalone node |
| Worked example loses its local scroller | The page can overflow on a narrow screen even if the diagram remains readable | Keep the wide SVG inside .diagram-container with horizontal scrolling |
Key files
| File | Why to read it |
|---|---|
| commands/import-excalidraw.md | Defines the user-facing command, defaults, flags, extractor-first path, and required behavior. |
| prompts/import-excalidraw.md | Defines host discovery and the prompt-level entry path. |
| skills/…/import-excalidraw.md | Holds the source-of-truth workflow for extraction, semantic reconstruction, redraw, delivery, and edge cases. |
| skills/…/excalidraw_extract.py | Defines the safe scene-to-IR boundary, resource limits, failures, and structural signals used by the redraw. |
| skills/…/output-spec.md | Defines format, size, detail, audience, and fidelity rules shared by imported artifacts. |
| skills/…/example-import-excalidraw.html | Shows a complete imported artifact and its mobile containment contract. |
| scripts/verify-excalidraw-import.py | Runs structural, trust-boundary, wiring, artifact, parser, fallback, and browser checks for the workflow. |
| scripts/test-verify-excalidraw-import.py | Proves that key import contracts fail when deliberately changed. |
scripts/fixtures/sample-whiteboard.excalidraw | Provides the normal scene used to check frames, labels, groups, decisions, and flow. |
scripts/fixtures/sample-adversarial.excalidraw | Provides untrusted labels and payloads used to check extraction safety. |