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

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. 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 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:

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 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.

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.

8. Delivery and Fidelity Ledger

The final output—HTML, SVG, or PNG—is written after passing the taste-gate defined in SKILL.md §9 and the checklist in 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.

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:

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

Process a Markdown file containing multiple diagram blocks:

# 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 to generate a language-agnostic IR before any visual processing occurs.
• Four configuration dials (--format, --size, --detail, --audience) validated against 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.
• 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, 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 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 §9 and the output checklist in output-spec.md §6, ensuring all exported formats meet editorial standards.

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