# How to Import and Redraw Excalidraw Sketches Using Diagram-Design

> Learn how to import and redraw Excalidraw sketches with Diagram-Design. Our pipeline extracts semantic meaning, applies constraints, and redraws your sketches into clean, production-ready diagrams.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-09-12

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/excalidraw_extract.py), located at [`skills/diagram-design/scripts/excalidraw_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/excalidraw_extract.py). This script parses `.excalidraw` or [`.excalidraw.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```text
/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:

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main//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:

```bash
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:

```text
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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/excalidraw_extract.py)** – Parses raw Excalidraw JSON and produces the intermediate representation.
- **[`commands/import-excalidraw.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-excalidraw.md)** – Declares command flags, defaults, and required behavior for the import operation.
- **[`skills/diagram-design/references/import-excalidraw.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/.excalidraw.json) files. The [`excalidraw_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.