InteractiveMermaid Renderer Constraints

Field	Value
Type	Skill Resource
Source	`~/.copilot/skills/technical-writing/references/mermaid/beautiful-mermaid-constraints.md`
Description	Not specified

Source Content

InteractiveMermaid Renderer Constraints

The design-system InteractiveMermaid component now renders the DIAGRAM (SVG) view with vanilla Mermaid (the mermaid npm package, v11), not beautiful-mermaid. Know the renderer split before writing a diagram that will live in a DocsPre mermaid fence block.

Renderer split

View	Renderer	Notes
Diagram (SVG)	vanilla Mermaid v11	Monotone-first DS theme; inline FontAwesome icons; newer diagram types
ASCII art	beautiful-mermaid	Vanilla Mermaid has no ASCII output, so this path is kept
Code	none (raw text)	Shows the Mermaid source verbatim

Monotone-first theming (house standard). The SVG view maps design-system neutral/foreground tokens onto Mermaid themeVariables (theme: 'base') for BOTH light and dark, detected from the resolved --background lightness.

Every node, border, edge, label, note, and cluster is neutral by default. Colour NEVER appears as a decorative default — add it deliberately per node with style Node fill:...,stroke:...,color:.... A multicolour default reads as machine-generated; monotone with sparing colour reads as considered work.

Never use emoji in labels — use inline FontAwesome tokens at the front of the label (Node["fas:fa-user Label"]), never the @{ shape: icon } icon-node form. The FontAwesome stylesheet is loaded in the component and the Storybook preview, so fas:/fab: tokens render as monochrome icons identical to the docs site. See icons-and-surfaces.md for the concept→token map.

Because the SVG path is now vanilla Mermaid, upstream syntax (inline FontAwesome labels, classDef in the SVG view, newer diagram types) works there. The beautiful-mermaid constraints below still bind the ASCII view and remain the safe lowest-common-denominator when a diagram must render identically in both.

Supported chart types

Type	Renders	Notes
`flowchart`	Yes	Full support, including subgraphs
`sequenceDiagram`	Yes	`actor`, `participant`, `alt`, `loop`, `par`, `note`
`stateDiagram-v2`	Yes	Full support
`classDiagram`	Yes	Full support
`erDiagram`	Yes	Full support
`xychart-beta`	Yes	Bar and line series
`journey`	No	Static surface — user-journey maps
`gitGraph`	No	Use prose or a static image
`gantt`	No	Use a table or timeline prose
`pie`	No	Use an XY chart or a prose percentage list
`mindmap`	No	Use a flowchart or nested list
`timeline`	No	Use a flowchart or prose
`quadrantChart`	No	Use a table or XY chart
`sankey-beta`	No	Static surface — funnel / drop-off
`architecture-beta`	No	Static surface — infra topology
`block-beta`	No	Static surface — block architecture
`C4Context` (and C4 variants)	No	Static surface — context / container
`requirementDiagram`	No	Static surface — traceability

The full set of static-only types, each with when-to-use guidance and a rendered example, lives in service-team-diagrams.md.

Styling rules

Use style Node ... lines. Never use classDef or class.

beautiful-mermaid can expose a stray visible class keyword node when classDef is used. Only direct node style lines are safe:

flowchart LR
    PR["Open PR"] --> Merge["Merge to main"]
    style PR fill:#dbeafe,stroke:#2563eb,color:#172554
    style Merge fill:#dcfce7,stroke:#16a34a,color:#14532d

Text alignment

Node label text is always center-aligned. Left-alignment is not possible: the renderer hardcodes tspan x coordinates to the node center in JavaScript. CSS text-anchor: start overrides the SVG attribute cascade but cannot move the x positions. A PR to beautiful-mermaid would be required to change this.

Keep node labels short. Move explanation into surrounding prose, not into nodes.

Blank lines inside node labels

Use   (a space between the tags), not  :

Msg["Header line<br> <br>Body line"]

Why: renderMultilineText converts   to \n\n and creates an empty tspan. Many SVG renderers skip layout for zero-content tspans, so the blank line disappears. A tspan with a single space character is always honored.

Only use this pattern when the multiline content is itself the point of the diagram (e.g., showing what a correct commit message looks like). Do not put paragraph-length text into nodes.

Initial fit behavior

InteractiveMermaid auto-fits the diagram to its container on first render. The SVG is scaled to fill the available width with 24px padding on each side. This means:

Very wide LR flowcharts are fully visible without horizontal scrolling.
The natural SVG dimensions from beautiful-mermaid are still respected for aspect ratio — only the scale changes.
Fullscreen entry re-fits to the larger viewport, making the diagram visibly bigger than it was in the normal view.
The reset button (↺) returns to the fitted view, not 1:1 scale.

Design diagrams to be readable at the fitted scale. A flowchart with 15+ nodes across a single LR chain will render at a very small scale. Split into subgraphs or switch to a flowchart TD for that much content.

Subgraph rendering

Subgraphs render correctly. Use them to group nodes into named zones:

flowchart LR
    subgraph local[Local workspace]
        Commit["git commit"]
    end
    subgraph github[GitHub]
        PR["Open PR"] --> CI["CI checks"]
    end
    Commit -->|reviewer approves| PR
    style CI fill:#fef3c7,stroke:#b45309,color:#451a03

Do not put a colon after the subgraph label — use subgraph id[Label], not subgraph id: Label or subgraph "Label". The lint script enforces this.