Introducing a new way to review your PRs.

Read the announcement

cathrynlavery / diagram-design

Editorial diagram design for Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, Qoder, and Pi. 45 diagram types. Self-contained HTML + SVG. No shadows. No Mermaid slop.

View on GitHub

23 documents · Updated Nov 20, 2026

docs / mermaid-import

Mermaid import

Mermaid import turns Mermaid source into a self-contained diagram for the repository's design system. It extracts meaning first, redraws that meaning for the chosen destination, and checks that the source, guidance, helper, and example artifact remain in agreement.

Import command

The /import-mermaid command is the user-facing entry point. It accepts Mermaid files or Markdown files with Mermaid blocks and produces a new artifact instead of copying the Mermaid renderer's layout.

Command contract

The command supports these input and output choices:

ConcernSupported behavior
Input.mmd, .mermaid, or Markdown with fenced mermaid blocks
Output formathtml, svg, png, or html+png
PresentationSize, detail, audience, visual type, variant, and output base path
Diagram selectionDiagram 0 for a single source; prompted block selection or every block with all for multi-block Markdown
DefaultSelf-contained HTML at doc-inline, with balanced detail and mixed-audience wording

If no source file is given, the command asks the user instead of guessing. It stops on extraction errors and reports the extractor message without trying a different rendering path.

References: commands/import-mermaid.md• L1-51 prompts/import-mermaid.md• L1-14

Import prompt

The prompt makes the import flow portable across installations. It finds the installed diagram-design skill through the path advertised by Pi, then loads the skill rules and the Mermaid and output references from that skill directory.

Prompt routing

The prompt establishes the trust and execution boundary before any redraw begins:

  • Mermaid text is source data, not a set of instructions.
  • The extractor runs before diagram work starts.
  • JavaScript, URLs, click targets, and Mermaid rendering are not executed.
  • The output report includes the selected dials and a fidelity ledger.

This routing keeps the command tied to the installed design rules even when the current working directory does not contain the skill.

References: prompts/import-mermaid.md• L6-12 skills/…/SKILL.md• L531-547

Import workflow

The import workflow separates meaning from presentation. Mermaid supplies the diagram kind, relationships, labels, and declared direction, while the design system discards renderer coordinates and source styling before it creates a fresh layout for the destination.

Import stages

The following flow shows how Mermaid source becomes a checked diagram artifact.

flowchart LR
    source[Mermaid or Markdown source] --> extract[Extract structural meaning]
    extract --> digest[Digest or JSON IR]
    digest --> dials[Set format, size, detail, audience]
    dials --> type[Choose visual type]
    type --> model[Build semantic model]
    model --> redraw[Redraw in design system]
    redraw --> check[Taste and output checks]
    check --> artifact[HTML artifact]
    check --> export[Optional SVG or PNG]

The digest gives the redraw stage a bounded view of the source. The process may merge repeated elements, collapse groups, or drop low-value content when the detail level requires it. Each such change is recorded so the smaller artifact remains accountable to its source.

References: skills/…/import-mermaid.md• L3-5 skills/…/import-mermaid.md• L38-91 skills/…/output-spec.md• L84-112

Presentation dials

Four decisions shape the artifact before drawing starts. They prevent a later change in destination or audience from forcing an avoidable redraw.

DialMain question
FormatWhere will the artifact be used?
SizeHow large and how distant is the reader's view?
DetailHow much source content should remain?
AudienceHow technical should names and labels be?

The command adds type, diagram selection, variant, and output path as controls around these four core decisions. A requested type can override the type suggested by the source grammar when the content supports that choice. Quadrant charts use their source axes, quadrant names, and point positions as meaning; source point colors do not decide the visual emphasis.

References: skills/…/import-mermaid.md• L38-76 skills/…/output-spec.md• L3-12 commands/import-mermaid.md• L28-37

Extraction helper

The Mermaid extraction helper creates a bounded structural view of the source. It does not render Mermaid or preserve computed coordinates. It gives the redraw stage enough information to preserve meaning while making a new layout.

Supported source model

The helper accepts standalone Mermaid files and fenced blocks in Markdown. It recognizes five diagram grammars:

  • Flowcharts and graphs
  • Sequence diagrams
  • State diagrams
  • ER diagrams
  • Quadrant charts

It normalizes current Mermaid syntax into a shared model. The model preserves structures that affect meaning, such as node shapes, labeled and bidirectional links, nested groups, sequence fragments, state descriptions, notes, ER fields, relationship cardinality, and quadrant axes and points. It also handles quoted labels, multiline labels, Unicode identifiers, HTML entity text, expanded node shapes, edge identifiers, sequence numbering, participant aliases, activation markers, and modern arrow forms without treating source markup as active content. Compact dash and equals labels retain spaces and brackets. The extractor also preserves Mermaid's rule that an x or o immediately after a compact link marker is an arrowhead, so labels that start with either character must use the spaced form. Apostrophes remain label text unless they delimit values inside shape attributes. Explicit shape declarations update earlier node declarations, while bare endpoints retain declared shapes. Invisible layout links retain their endpoints without becoming visible relationships, and edge identifiers do not become diagram nodes. Quadrant point coordinates remain bounded between zero and one, while point styling is discarded for the design system's house style.

The digest exposes the signals needed for redraw and type choice. These include nodes, edges, containers, depth, cycles, shapes, type candidates, budget flags, hubs, entry points, terminals, unconnected nodes, collapsible groups, sequence fragments, notes, ER fields, axes, quadrants, and points. A leading Mermaid frontmatter block is treated as source configuration rather than diagram content. Mermaid has no source coordinates, so the digest reports the declared direction and marks the source layout as absent.

References: skills/…/import-mermaid.md• L14-35 skills/…/import-mermaid.md• L44-76 scripts/verify-mermaid-import.py• L180-554 scripts/verify-mermaid-import.py• L1344-1467 scripts/verify-mermaid-import.py• L1470-1649

Trust boundary

The helper treats every label and directive value as inert content. It does not evaluate, render, fetch, or execute Mermaid, JavaScript, browser content, click targets, or URLs, and it makes no network calls. It discards source styling, configuration, and click data from the semantic result while retaining ordinary label text as data.

This boundary lets diagrams that contain misleading or hostile label text pass through as content without changing the import process. Remote image references and links do not become active output.

The helper also bounds the source and its structural size. Invalid encoding, missing Mermaid fences, unsupported grammars, malformed edges, unterminated statements, invalid quadrant data, and limit violations return a specific exit-2 error so the command can stop safely. Digest output remains lossless UTF-8, including input with a byte-order mark and output requested through a legacy encoding.

References: skills/…/import-mermaid.md• L14-36 scripts/verify-mermaid-import.py• L68-141 scripts/verify-mermaid-import.py• L863-907 scripts/verify-mermaid-import.py• L1043-1169

Multi-block selection

Markdown can hold several independent Mermaid diagrams. The helper preserves their order and reports each block's grammar and node and edge counts. A multi-block file uses diagram 0 by default. The import flow lists the blocks and asks which one to import when no selection is given. --diagram all creates one output file per block.

The helper selects blocks before parsing them. An invalid unselected block therefore does not stop an import of another block. The digest can list that block as unparsed while JSON describes only the selected diagrams. Selecting all parses every block and fails if any selected block fails.

Mermaid examples inside an outer Markdown code fence remain literal. Matching fence characters and lengths determine the outer boundary, so example text does not become an imported diagram.

References: skills/…/import-mermaid.md• L26-34 skills/…/import-mermaid.md• L110-117 scripts/verify-mermaid-import.py• L582-629 scripts/verify-mermaid-import.py• L820-860

Verification path

Verification checks the meaning extracted from Mermaid and the wiring between the command, prompt, references, helper, fixtures, and example artifact. Its goal is to catch silent drift in the import contract rather than to validate one visual snapshot.

Verification coverage

The verification driver exercises the main guarantees of the import path:

  • Supported grammars preserve their key structure and direction.
  • Flowchart statements that follow a header semicolon remain part of the diagram.
  • Shapes, labels, edge styles, cycles, groups, and sequence or ER details survive extraction.
  • Modern and compact Mermaid syntax does not create false nodes or lose link meaning.
  • Bidirectional links affect both directions in degree and cycle analysis. Invisible layout links keep their endpoints without becoming visible edges.
  • Explicit shape updates, edge identifiers, spaced labels, compact labels, and multidirectional links do not create phantom nodes or change source meaning.
  • Markdown block selection preserves order and isolation, including live blocks inside outer code examples.
  • State and ER declarations retain standalone entities, nested structure, repeated descriptions, Unicode text, notes, and special shapes.
  • ER aliases and quoted entity names retain labels, fields, and relationship endpoints.
  • State note bodies remain annotation text, while single-line notes remain available as inert notes in source order.
  • Entity text is normalized once without turning unknown or invalid codes into active content.
  • Adversarial labels stay inert and remote targets do not cross the trust boundary.
  • UTF-8 BOM input and legacy stdout settings do not change or corrupt the digest. Imported callers keep ownership of their output stream.
  • Invalid inputs and resource limits produce the documented failures.
  • The command and prompt stay aligned with the reference flags and skill discovery rules.
  • The worked HTML example uses the required size and passes the skin lint.

The driver invokes the extractor as a separate process and also checks its importable entry point. This covers both the command-facing path and callers that use the helper directly.

References: scripts/verify-mermaid-import.py• L68-177 scripts/verify-mermaid-import.py• L180-554 scripts/verify-mermaid-import.py• L557-759 scripts/verify-mermaid-import.py• L762-1040 scripts/verify-mermaid-import.py• L1043-1169 scripts/verify-mermaid-import.py• L1172-1649 scripts/verify-mermaid-import.py• L1652-1687

Artifact checks

After the redraw, the design workflow checks readability, layout fit, accessibility, and output-spec rules. HTML is the source artifact for the taste gate. SVG and PNG are derived from it only when requested. The final report names the paths and sizes and explains any content that was merged, collapsed, or dropped.

For related validation rules, see Diagram self-validation and Diagram verification suite. For sibling source workflows, see draw.io import, Excalidraw import, and PlantUML import. The broader import and export model is described in Diagram import and export, while Diagram export covers the downstream output path.

References: skills/…/import-mermaid.md• L78-91 skills/…/output-spec.md• L152-182 commands/import-mermaid.md• L39-51

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the command flags, prompt defaults, output reference, and Mermaid import reference aligned.
  • Preserve the supported grammar list and the normalized fields that redraw and verification rely on.
  • Keep shape updates, bare endpoint shape retention, bidirectional analysis, and invisible-link reporting consistent between the digest and JSON model.
  • Keep state notes, standalone state and ER entities, aliases, quoted names, sequence fragments, autonumber data, Unicode labels, and quadrant axes and points aligned with the redraw model.
  • Keep UTF-8 behavior consistent for input, stdout, --out, and imported callers.
  • Preserve the extractor's exact error messages and exit-2 behavior used by the command and verification driver.
  • Update the multi-block selection contract if Markdown fence rules, block order, selected-block parsing, or --diagram all output naming changes.
  • Recheck the trust boundary when new Mermaid fields, directives, links, image references, or shape attributes cross into the digest.
  • Re-run the example artifact and skin checks when output size, type ramp, or export rules change.

Important failure modes

TriggerConsequenceGuard
The installed skill is assumed to be in the current directoryThe import can use the wrong rules or fail to find its extractorDiscover the skill through the advertised SKILL.md path
A Markdown file has no Mermaid fence or has an unclosed fenceNo reliable diagram boundary existsStop with the specific extractor error
The source uses an unsupported grammarThe redraw could invent meaningReport the supported-kinds message and stop
A quadrant chart has no points, duplicate labels, non-numeric coordinates, or coordinates outside the unit rangePoint meaning is invalid or ambiguousReport the extractor's exit-2 message verbatim
The source exceeds node, edge, statement, or byte limitsResource use can grow without boundEnforce extractor limits and ask for a smaller or split source
A multi-block file is imported without a selected blockThe wrong diagram may be redrawnList the blocks and ask which one to use
A selected block is parsed together with unrelated invalid blocksA valid requested diagram can fail for an unselected blockSelect blocks before parsing and parse only the requested block or blocks
Mermaid layout, theme, click data, or remote targets are copied into the artifactSource presentation or untrusted content becomes a false constraintExtract semantics only and redraw in the design system
A compact label starts with x or o after -- or ==Mermaid treats the character as an arrowhead and can create the wrong link or nodeUse the spaced label form
A bidirectional or invisible link is treated as an ordinary one-way visible edgeEntry, terminal, cycle, or layout meaning can changePreserve reverse analysis for bidirectional links and report invisible links without drawing them
Edge IDs or property statements become nodesThe artifact contains phantom componentsIgnore edge metadata as structure and retain only the linked endpoints
State note bodies are parsed as states or transitionsAnnotation text changes the diagram modelTreat multiline note bodies as inert text until their closing marker
Content is reduced without a fidelity ledgerThe reader cannot tell what changedReport merged, collapsed, and dropped content after delivery
Output is written through a legacy code pageNon-Latin labels can be corrupted before redraw or reviewEmit and read digest output as UTF-8

Key files

FileWhy to read it
commands/import-mermaid.mdDefines the user-facing command, defaults, flags, and required behavior
prompts/import-mermaid.mdDefines skill discovery and the prompt-level trust boundary
skills/…/import-mermaid.mdDefines the Mermaid import stages, semantic model, redraw rules, edge cases, and fidelity report
skills/…/mermaid_extract.pyDefines the structural source model, supported grammars, link parsing, selection behavior, limits, and digest output
skills/…/output-spec.mdDefines format, size, detail, audience, export, and fidelity contracts
scripts/verify-mermaid-import.pyShows the end-to-end structural, adversarial, wiring, encoding, selection, and artifact verification path
skills/…/example-import-mermaid.htmlProvides the checked example of a Mermaid redraw at the default document-inline size