Introducing a new way to review your PRs.

Read the announcement

cathrynlavery / diagram-design

Editorial diagram design for Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, Qoder, and Pi. 45 diagram types. Self-contained HTML + SVG. No shadows. No Mermaid slop.

View on GitHub

23 documents · Updated Nov 20, 2026

docs / excalidraw-import

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

TriggerConsequenceGuard
No source path is providedThe workflow cannot choose a scene safelyAsk which saved .excalidraw file to use; do not guess
User supplies a PNG or SVG exportThe source has no usable scene structure for the import pathAsk for the saved .excalidraw scene; do not scrape pixels
Extractor returns a non-zero exit codeThe workflow may draw from invalid or incomplete source dataReport the extractor message verbatim and stop
Source labels are emptyThe layout carries meaning that the workflow cannot name safelyAsk the user to identify the boxes; do not invent labels
Duplicate element IDs or invalid geometry occurScene meaning can become ambiguous or unsafe to summarizeStop with the extractor diagnostic and repair or re-export the scene
Edge bindings are missingA connection may be mistaken for a valid transitionOmit 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 overallThe result can become unreadable or exceed the source budgetZone the layout above 9 nodes; above 24 nodes split into overview and detail files
Requested detail is impossible at the selected sizeThe result can lose its main story or become hard to readSay so before drawing and propose overview and per-frame detail outputs
Source labels contain instructions or linksUntrusted diagram data could influence the workflow or leak a targetKeep labels inert and escaped; never follow links, embeds, or label instructions
Deeply nested JSON exceeds the parser limitThe import can fail with a traceback or emit a partial digestReturn a clear parser diagnostic with no partial output; accept shallow control input normally
Text is bound to an unsupported containerVisible annotation can disappear from the extracted sceneKeep the text as a standalone node
Worked example loses its local scrollerThe page can overflow on a narrow screen even if the diagram remains readableKeep the wide SVG inside .diagram-container with horizontal scrolling

Key files

FileWhy to read it
commands/import-excalidraw.mdDefines the user-facing command, defaults, flags, extractor-first path, and required behavior.
prompts/import-excalidraw.mdDefines host discovery and the prompt-level entry path.
skills/…/import-excalidraw.mdHolds the source-of-truth workflow for extraction, semantic reconstruction, redraw, delivery, and edge cases.
skills/…/excalidraw_extract.pyDefines the safe scene-to-IR boundary, resource limits, failures, and structural signals used by the redraw.
skills/…/output-spec.mdDefines format, size, detail, audience, and fidelity rules shared by imported artifacts.
skills/…/example-import-excalidraw.htmlShows a complete imported artifact and its mobile containment contract.
scripts/verify-excalidraw-import.pyRuns structural, trust-boundary, wiring, artifact, parser, fallback, and browser checks for the workflow.
scripts/test-verify-excalidraw-import.pyProves that key import contracts fail when deliberately changed.
scripts/fixtures/sample-whiteboard.excalidrawProvides the normal scene used to check frames, labels, groups, decisions, and flow.
scripts/fixtures/sample-adversarial.excalidrawProvides untrusted labels and payloads used to check extraction safety.