How to Import and Redraw Excalidraw Sketches Using Diagram-Design

Diagram-Design imports Excalidraw files through a six-step pipeline that extracts semantic meaning, applies configurable editorial constraints, and redraws the content as a clean, production-ready diagram with a complete fidelity ledger.

The cathrynlavery/diagram-design repository treats Excalidraw sketches as structured semantic data rather than finished graphics. When you import and redraw Excalidraw sketches, the system discards hand-drawn styling while preserving the underlying information architecture, then rebuilds the visualization according to defined layout rules and audience constraints. This approach ensures editorial consistency, prevents code injection, and provides transparent documentation of every transformation through a detailed fidelity ledger.

The Six-Step Import Pipeline

The import process follows a strict pipeline defined in skills/diagram-design/references/import-excalidraw.md. Each stage transforms the source material while maintaining a clear audit trail of discarded or modified content.

1. Extract the Intermediate Representation

The pipeline begins with excalidraw_extract.py, located at skills/diagram-design/scripts/excalidraw_extract.py. This script parses .excalidraw or .excalidraw.json files and emits a compact intermediate representation (IR) containing nodes, edges, frames, and groups. The extractor never renders the scene, fetches remote URLs, or executes embedded code, ensuring a safe, static analysis of the source file.

2. Configure the Four Dials

Before drawing occurs, command-level flags --format, --size, --detail, and --audience are resolved against the output specification defined in skills/diagram-design/references/output-spec.md. These four dials drive layout constraints, glyph density, and phrasing style. For example, --detail=simplified limits the diagram to ≤ 7 nodes, trimming low-priority elements, while --size=slide-16x9 establishes a 960 × 540 viewBox.

3. Select the Target Diagram Type

The IR's type candidates field suggests a visual classification such as flowchart, architecture diagram, or state machine. Operators may override this suggestion using --type. The system then loads layout conventions from the corresponding type-*.md reference file to govern spatial organization and connector logic.

4. Build the Semantic Model

Using the IR, the skill composes a narrative structure consisting of a one-sentence title, a detail-appropriate subset of nodes, focal hubs, and rewritten labels tailored to the selected audience. All hand-drawn geometry, colors, and image payloads are discarded at this stage; they appear only in the fidelity ledger, never in the redrawn output.

5. Execute the Redraw

A fresh viewBox is created based on the chosen size preset. Shapes are mapped to the skill's design system: diamonds become decision nodes, rectangles become stores, and other elements conform to consistent geometric standards. Connectors are routed according to the guidelines in skills/diagram-design/SKILL.md, and no sketch-style strokes or freehand artifacts are reproduced.

6. Generate Output and Ledger

The final artifact is delivered as a self-contained HTML file by default, or as SVG/PNG generated from that HTML. Alongside the visual output, a fidelity ledger summarizes what was merged, collapsed, or dropped, including counts of discarded freedraw strokes, images, external links, and unknown elements.

Practical Usage Examples

Import via the Pi Slash Command

The typical entry point uses the Pi assistant interface:

/diagram-design:import-excalidraw whiteboard.excalidraw --size=slide-16x9 --detail=simplified

This command invokes the import-excalidraw routine, which runs the extractor and processes the pipeline using a widescreen aspect ratio and simplified node density.

Run the Extractor Manually for Debugging

To inspect the intermediate representation without triggering the full redraw:

python3 skills/diagram-design/scripts/excalidraw_extract.py \
    scripts/fixtures/sample-whiteboard.excalidraw \
    --json \
    --max-rows 40 \
    --out /tmp/ir.json

The resulting /tmp/ir.json contains structured fields for nodes, edges, frames, and a discarded line itemizing ignored content such as freedraw strokes or embedded images.

Import via the Pi CLI

If you have the Pi CLI installed, import directly from the terminal:

pi import-excalidraw \
    docs/diagrams/flow.excalidraw \
    --format=svg \
    --size=doc-wide \
    --detail=balanced \
    --audience=engineer \
    --output=out/flow-diagram

This generates out/flow-diagram.svg and prints a fidelity ledger to the console:

Source IR nodes: 10   Drawn nodes: 8   Discarded: 2 freedraw, 1 image, 0 links

Inspect the Fidelity Ledger in Generated HTML

Open the produced HTML file and locate the preformatted text block titled Fidelity Ledger. This section lists every transformation applied, matching the summary provided by the command-line tool.

Core Implementation Files

• skills/diagram-design/scripts/excalidraw_extract.py – Parses raw Excalidraw JSON and produces the intermediate representation.
• commands/import-excalidraw.md – Declares command flags, defaults, and required behavior for the import operation.
• skills/diagram-design/references/import-excalidraw.md – Contains the step-by-step procedural specification used by the command implementation.
• skills/diagram-design/references/output-spec.md – Defines the four dials (format, size, detail, audience) and their valid value ranges.
• skills/diagram-design/SKILL.md – Documents the overall design system, including connector routing rules and taste-gate logic.
• skills/diagram-design/assets/example-import-excalidraw.html – A complete worked example showing expected output from a sample whiteboard.

Summary

• Diagram-Design treats Excalidraw as semantic data, not as a final graphic, enabling systematic redraws that enforce visual consistency.
• The four dials (--format, --size, --detail, --audience) control every aspect of the output, from aspect ratio to node density and label complexity.
• Safety is enforced by design: the extractor never executes embedded code, fetches URLs, or renders external images, eliminating injection risks.
• Transparency is guaranteed through the fidelity ledger, which explicitly documents every freedraw stroke, image, link, or unknown element removed during processing.
• Output defaults to self-contained HTML but can generate SVG or PNG through the --format flag.

Frequently Asked Questions

What file formats can I import?

The system accepts .excalidraw and .excalidraw.json files. The excalidraw_extract.py script handles both extensions natively, parsing the JSON scene to build the intermediate representation without requiring the Excalidraw application to be running.

How does the system handle hand-drawn sketches or embedded images?

All hand-drawn geometry, freehand strokes, colors, and image payloads are intentionally discarded during the semantic modeling phase. These elements appear only in the fidelity ledger, ensuring the final diagram uses the skill's standardized design system rather than inconsistent sketch styling.

Can I customize the visual style of the output diagram?

Visual styling is controlled through the four dials and the target type selection. While you cannot micromanage individual colors or stroke widths, you can specify --audience and --detail levels that trigger predefined design system rules documented in skills/diagram-design/SKILL.md.

Where is the fidelity ledger stored?

The fidelity ledger appears in two places: printed to standard output when using the CLI, and embedded within the generated HTML file as a preformatted text block. This ledger lists exactly what was merged, collapsed, or dropped, including counts of discarded freedraw strokes, images, links, and unrecognized elements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}