# How Mermaid Imports Are Redrawn into the Editorial Style System in diagram-design

> Learn how Mermaid imports are redrawn into the editorial style system in diagram-design. Discover how raw Mermaid source becomes a styled diagram using internal conventions, not direct rendering.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: internals
- Published: 2026-09-13

---

**The diagram-design skill converts raw Mermaid source into a language-agnostic intermediate representation and redraws it using internal layout, theme, and style conventions rather than rendering or converting the original.**

The `cathrynlavery/diagram-design` repository implements a specialized pipeline for importing Mermaid diagrams that prioritizes editorial consistency over fidelity to Mermaid's native rendering. Unlike traditional conversion tools, this system **discards all Mermaid-specific styling**—including themes, `classDef`, `linkStyle`, and computed positions—to produce diagrams that conform strictly to the skill's design system. The process relies on an **extractor-first approach** that treats source labels as untrusted data and rebuilds visuals from a normalized semantic model.

## The 8-Step Import Pipeline

When a user invokes `/diagram-design:import-mermaid <file>`, the skill executes a deterministic, eight-step workflow defined in [`skills/diagram-design/references/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md). Each stage enforces strict boundaries between parsing, validation, and rendering to ensure security and consistency.

### 1. Command Trigger

The pipeline begins when the command file [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) receives the invocation. It directs the system to the reference documentation and validates basic argument presence before handing off to the extraction layer.

### 2. IR Extraction

The skill locates its installation directory and executes the Python extractor:

```bash
python3 <skill-dir>/skills/diagram-design/scripts/mermaid_extract.py <file> …

```

This script parses raw Mermaid text or fenced Markdown blocks to produce a structured **intermediate representation (IR)**. The IR describes nodes, edges, containers, and budget flags but **never evaluates code, renders graphics, or makes network calls**. All labels remain inert, establishing a strict trust boundary that prevents injection attacks.

### 3. Validation Gate

If the extractor exits with a non-zero status, its error message propagates verbatim and the workflow terminates. Common failures include "no fenced mermaid block found" when processing Markdown inputs lacking Mermaid blocks.

### 4. Dial Configuration

The system consults [`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md) to configure four user-controlled **dials**: `--format`, `--size`, `--detail`, and `--audience`. The IR's `budget:` line determines feasibility; if the requested combination exceeds limits, the skill may propose an overview-plus-detail split rather than fail silently.

### 5. Editorial Type Selection

Based on the extracted grammar—`flowchart`, `sequenceDiagram`, `stateDiagram-v2`, `erDiagram`, etc.—the system selects the appropriate editorial diagram type (Flowchart, Architecture, Sequence, State machine, ER, or Nested). The mapping table resides in [`skills/diagram-design/references/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md).

### 6. Semantic Model Building

The skill constructs a semantic model by writing a short narrative, applying the requested detail level, selecting focal hubs, and rewriting labels for the target audience. **All Mermaid-specific styling is discarded** during this phase, including click handlers and CSS directives defined in the source.

### 7. Redraw from Blank Canvas

Starting from a fresh `viewBox` sized according to presets, the system redraws the diagram using its own layout conventions and connector rules. Mermaid's computed positions and visual themes are **never reused**; connectivity is re-routed to match the skill's editorial standards defined in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md).

### 8. Delivery and Fidelity Ledger

The final output—HTML, SVG, or PNG—is written after passing the taste-gate defined in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) §9 and the checklist in [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md) §6. The system generates a **fidelity ledger** detailing what elements were merged, collapsed, or dropped, providing transparent traceability for every import. Reference output is available in [`skills/diagram-design/assets/example-import-mermaid.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-import-mermaid.html).

## Key Architectural Principles

The redraw system is built on several foundational constraints that distinguish it from simple format converters.

**Extractor-First Design**  
All rendering logic is deferred until the IR is fully materialized. This ensures that Mermaid's native layout quirks—such as automatic node spacing or directionality heuristics—cannot leak into the editorial output.

**Untrusted Data Handling**  
The extractor treats every label, directive, and URL as inert content. It does not follow hyperlinks, execute embedded JavaScript, or resolve external resources, maintaining security when processing third-party diagrams.

**Budget-Driven Detail Management**  
The IR's `budget:` field acts as a governor for complexity. High-detail requests on large diagrams trigger automatic reduction strategies rather than producing unreadable or oversized outputs.

## Practical Usage Examples

Import a single Mermaid file with specific size and detail constraints:

```bash
diagram-design:import-mermaid architecture.mmd --size=slide-16x9 --detail=simplified

```

Process a Markdown file containing multiple diagram blocks:

```bash

# Interactive selection from available blocks

diagram-design:import-mermaid docs/overview.md

# Generate one HTML per block

diagram-design:import-mermaid docs/overview.md --diagram=all

```

Both commands execute the identical eight-stage pipeline; the `--diagram` flag only affects which extracted block enters the redraw phase.

## Summary

- The diagram-design skill **redraws** Mermaid imports rather than converting or rendering them, ensuring full editorial control over the final output.
- The pipeline uses [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) to generate a language-agnostic IR before any visual processing occurs.
- Four configuration dials (`--format`, `--size`, `--detail`, `--audience`) validated against [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md) govern the final rendering parameters.
- All Mermaid-specific styling, themes, and computed positions are discarded in favor of the skill's internal design system defined in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md).
- Every import produces a **fidelity ledger** documenting structural changes, ensuring transparency for critical documentation workflows.

## Frequently Asked Questions

### Does the system preserve Mermaid themes and custom CSS?

No. The redraw pipeline explicitly strips all Mermaid-specific styling, including `classDef`, `linkStyle`, themes, and click handlers. The diagram is rebuilt using the editorial style system defined in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), ensuring visual consistency with other diagrams produced by the skill.

### How does the system handle large or complex diagrams?

The IR includes a `budget:` field that measures structural complexity against the requested `--detail` and `--size` parameters. If the combination is infeasible, the skill may automatically split the output into an overview plus detailed views, or reduce fidelity, rather than generating unreadable or oversized graphics.

### Is it safe to import untrusted Mermaid files?

Yes. The [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) script operates under a strict trust boundary: it parses text into an IR without executing code, following URLs, or making network requests. All labels are treated as inert data throughout the extraction and redraw phases, preventing injection attacks.

### What file formats can the import command generate?

The `--format` dial supports HTML (default), SVG, and PNG outputs. The final file is generated only after passing the taste-gate validation defined in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) §9 and the output checklist in [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md) §6, ensuring all exported formats meet editorial standards.