# How to Redraw Mermaid Imports and Track Changes with the Fidelity Ledger

> Redraw Mermaid imports by rebuilding diagrams from scratch and track changes with the fidelity ledger which documents every operation. Learn the procedure now.

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

---

**Redraw Mermaid imports by extracting a structural intermediate representation, applying four configuration dials, and rebuilding the diagram from scratch while the fidelity ledger documents every merge, collapse, or drop operation.**

The `cathrynlavery/diagram-design` repository provides a specialized workflow for converting Mermaid source files into editorial-quality diagrams. Unlike simple format conversion, the redraw Mermaid imports procedure discards all original layout and styling to rebuild diagrams according to a strict design system. This process includes a comprehensive fidelity ledger that transparently reports every structural transformation applied during the redraw.

## Understanding the Mermaid Import Redraw Procedure

The Mermaid import workflow treats conversion as a **redraw** rather than a direct translation. According to [`skills/diagram-design/references/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md), the process parses the source Mermaid file—whether `.mmd`, `.mermaid`, or fenced blocks in Markdown—into a language-agnostic **intermediate representation (IR)**.

This IR contains only structural data: labels, directives, and URLs are treated as plain text without execution or rendering. The system then rebuilds the diagram from this IR, ignoring all original Mermaid-specific layout, themes, or class information. The result is a diagram that conforms to the skill's design system rather than the original rendering.

## The Six-Step Redraw Workflow

The complete procedure is defined in [`skills/diagram-design/references/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md) and consists of six sequential steps:

1. **Extract the IR**  
   Run [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) to parse the source into the structural IR. No JavaScript execution, rendering, or network calls occur during this phase.

2. **Set the Four Dials**  
   Configure `--format`, `--size`, `--detail`, and `--audience` before drawing begins. These parameters drive the final output dimensions, abstraction level, and vocabulary style according to [`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md).

3. **Pick the Target Type**  
   Map the detected Mermaid grammar (such as `flowchart`, `sequenceDiagram`, `stateDiagram-v2`, or `erDiagram`) to the appropriate diagram type (Flowchart, Architecture, Sequence). Record any manual overrides.

4. **Build the Semantic Model**  
   Transform the IR into a story-centric model: name the narrative, apply the selected detail level, choose focal nodes, and rewrite labels for the target audience while preserving essential edge labels and container relationships.

5. **Redraw from Blank**  
   Initialize a blank `viewBox` using the size preset. Apply the semantic model while ignoring all Mermaid-specific layout or styling. Route connections according to the connector rules defined in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), without adding decorative filler components.

6. **Deliver and Report**  
   Emit a self-contained HTML file as the source of truth, optionally generate SVG/PNG outputs, and produce the **fidelity ledger** enumerating every merge, collapse, or drop operation.

## How the Fidelity Ledger Works

When the output contains fewer nodes than the input—which occurs in `balanced` or `simplified` detail levels and most `faithful` runs—the system generates a **fidelity ledger** as specified in section 5 of [`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md). This ledger makes information loss explicit and transparent.

### Ledger Entry Format

Each ledger entry follows a structured pattern documenting the transformation:

```text
Detail: balanced · 18 source nodes → 9 drawn
Merged:  worker-01..06 → "Ingest Worker ×6"
Collapsed: "Observability" group (Grafana, Loki, Tempo) → one node
Dropped: 2 sticky notes, CI pipeline (cross‑cutting)
Kept in full: the request path (Client → Gateway → Orders → Postgres)

```

### Types of Transformations

The ledger categorizes changes into five specific types:

- **Detail**: Shows the detail level used and the node count reduction (e.g., "18 source nodes → 9 drawn").
- **Merged**: Identical nodes condensed into a single representative with a multiplier (e.g., `api‑worker‑01..04 → "API Worker ×4"`).
- **Collapsed**: Container groups where all children are leaves represented by the parent container alone.
- **Dropped**: Decorative elements, degree-1 sinks, or cross-cutting infrastructure removed by the degrade ladder.
- **Kept in full**: Core story elements that survived unchanged, confirming narrative preservation.

## Running the Import Workflow

### Command-Line Execution

Invoke the extractor script directly to process Mermaid files:

```bash
python3 skills/diagram-design/scripts/mermaid_extract.py diagrams/architecture.mmd \
    --diagram all --detail balanced --size slide-16x9 --format html \
    --output diagrams/out

```

This command parses all fenced blocks (`--diagram all`), applies the **balanced** detail level, configures a slide-sized canvas, and emits HTML output.

### Pi Command Interface

For integrated workflows, use the Pi command template defined in [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md):

```text
/diagram-design:import‑mermaid diagrams/architecture.mmd --size=slide-16x9 --detail=balanced

```

The Pi backend executes [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py), applies the four dials automatically, generates the requested outputs, and returns the fidelity ledger in the chat interface after the file path.

### Verification and Testing

The [`scripts/verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-mermaid-import.py) test harness validates that the extractor and ledger logic comply with the specification in [`skills/diagram-design/references/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md). Run this to ensure fidelity reporting accuracy before production deployment.

## Summary

- **Redraw Mermaid imports** convert source files to IR and rebuild from scratch, discarding original layout and themes.
- The **fidelity ledger** documents every structural change when node counts decrease, categorized as Merged, Collapsed, Dropped, or Kept.
- **Four dials** (`--format`, `--size`, `--detail`, `--audience`) control output characteristics and must be set before drawing begins.
- HTML output serves as the **source of truth**, with optional SVG/PNG derivatives.
- Source code resides in `cathrynlavery/diagram-design`, with core logic in [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) and specifications in [`skills/diagram-design/references/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md).

## Frequently Asked Questions

### What is the difference between redrawing and converting Mermaid diagrams?

**Redrawing** extracts only structural data into an intermediate representation and rebuilds the diagram according to the skill's design system, ignoring all original Mermaid layout, themes, and styling. **Converting** typically implies preserving the original rendering with format changes, which this workflow explicitly avoids to ensure editorial quality.

### When does the fidelity ledger appear in the output?

The fidelity ledger appears whenever the output contains fewer nodes than the input source, which occurs in `balanced` or `simplified` detail levels and most `faithful` runs. According to [`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md), the ledger is mandatory for these reductions to maintain transparency about omitted elements.

### Can I override the automatically detected diagram type?

Yes. Step 3 of the workflow allows overriding the detected Mermaid grammar (such as `flowchart` or `sequenceDiagram`) when the content demands a different diagram type. Any override must be recorded in the workflow documentation to maintain auditability.

### How do I verify that the extractor and ledger are working correctly?

Run the [`scripts/verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-mermaid-import.py) test harness, which validates that [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) and the fidelity ledger logic comply with the canonical procedure in [`skills/diagram-design/references/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md). This ensures accurate parsing and transformation reporting.