Author and render diagrams with ak:mermaidjs-v11

Use ak:mermaidjs-v11 to express a process, interaction, data model, state machine, architecture, plan, or dataset as Mermaid v11 source. The Skill provides syntax, configuration, CLI, integration, and practical-pattern references; the active runtime or a separately installed renderer must parse and render the result.

Choose ak:mermaidjs-v11 for text-based diagrams

Use ak:mermaidjs-v11 when

• You want a diagram stored as reviewable text in Markdown or a .mmd file.
• You need a flowchart, sequence, class, state, ER, Gantt, journey, Git graph, timeline, mindmap, architecture, block, quadrant, requirement, packet, pie, XY, Sankey, radar, treemap, or related Mermaid v11 diagram.
• You need SVG, PNG, or PDF output generated from an approved source diagram.
• You need Mermaid embedded in a browser, Node application, React, Vue, MDX, or another host that supports the selected syntax.

Choose another workflow when

• A short list or table communicates the information more clearly than a diagram.
• You need freehand positioning, complex illustration, or manual vector editing. Use a visual-design or diagramming tool built for that artifact.
• You only want to read existing Markdown that contains Mermaid. Use ak:markdown-novel-viewer, while respecting its CDN and security boundary.
• The target platform does not support the required v11 or beta diagram type. Choose a supported type or pre-render an image.

Prepare the diagram contract and renderer

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the current runtime and scope.
• Provide the diagram's purpose, intended reader, facts, node or actor names, relationships, direction, ordering, scope, and details that must not be inferred.
• Name the target host and exact output: inline fenced source, .mmd, .svg, .png, .pdf, or application integration. Renderer support varies by host.
• Choose a security level, theme, background, font, accessibility title and description, and whether interactive links or callbacks are allowed.
• Make Mermaid v11 or @mermaid-js/mermaid-cli available when parse or render evidence is required. The references declare Node.js ^18.19 || >=20.0 for the CLI path.

The declared input is [diagram-type or description]. It is not a fixed parser. State the diagram type when you know it, or provide the relationships and let the Skill recommend one without inventing missing facts.

Request source and rendered evidence

/ak:mermaidjs-v11 "Create a left-to-right sequence diagram for the supplied checkout events. Keep service names exact, distinguish synchronous calls from asynchronous notifications, include failure and retry branches, add accTitle and accDescr, return a fenced Mermaid block and checkout-sequence.mmd, parse it with Mermaid v11, render SVG with a pinned v11 CLI if available, and report any unverified layout."

/ak:mermaidjs-v11 "Create a left-to-right sequence diagram for the supplied checkout events. Keep service names exact, distinguish synchronous calls from asynchronous notifications, include failure and retry branches, add accTitle and accDescr, return a fenced Mermaid block and checkout-sequence.mmd, parse it with Mermaid v11, render SVG with a pinned v11 CLI if available, and report any unverified layout."

$ak:mermaidjs-v11 "Create a left-to-right sequence diagram for the supplied checkout events. Keep service names exact, distinguish synchronous calls from asynchronous notifications, include failure and retry branches, add accTitle and accDescr, return a fenced Mermaid block and checkout-sequence.mmd, parse it with Mermaid v11, render SVG with a pinned v11 CLI if available, and report any unverified layout."

For a data-driven diagram, provide the authoritative dataset and the intended encoding. A pie, XY, Sankey, radar, or treemap should not silently aggregate, normalize, reorder, or omit values. Ask the result to include a data-to-mark mapping you can reconcile with the source.

Select the smallest fitting diagram

Some referenced types carry a -beta suffix. Treat them as renderer-sensitive, test them against the exact target version, and provide a simpler fallback when the destination cannot render them.

Observe the diagram stages

1. The Skill confirms the information model. It separates supplied facts from inferred layout and asks about missing relationships that would change meaning.
2. It chooses one diagram type and direction. The choice reflects the information shape and the destination's supported Mermaid version.
3. It authors semantic source. Stable IDs, clear labels, meaningful edge text, comments, accessible title and description, and minimal styling keep the source reviewable.
4. It applies bounded configuration. Theme, look, layout, font, deterministic IDs, size limits, and security level are explicit rather than host defaults when reproducibility matters.
5. It parses before rendering. mermaid.parse() or an equivalent v11 check distinguishes syntax errors from later browser or layout failures.
6. It renders in the selected target. The CLI or host produces SVG, PNG, PDF, or live HTML using a pinned version when possible.
7. It inspects visual output. Clipped labels, overlaps, crossing arrows, contrast, scale, font substitution, responsive behavior, and accessible metadata are reviewed.
8. It returns source and evidence. The report names versions, commands, outputs, data reconciliation, render findings, and gaps.

Render with an explicit tool boundary

The referenced CLI converts .mmd input according to the output extension:

mmdc -i checkout-sequence.mmd -o checkout-sequence.svg
mmdc -i checkout-sequence.mmd -o checkout-sequence.png -t dark -b transparent
mmdc -i checkout-sequence.mmd -o checkout-sequence.pdf --configFile mermaid-config.json

Installation can be global, local, through npx, or by pulling the documented container image. Each path can use the network, write packages or image layers, start a browser-backed renderer, and consume CPU, memory, and disk. Batch conversion writes one artifact per input and can overwrite matching outputs; review targets before running it.

Browser integration can load Mermaid from a CDN or an installed npm package. Avoid the reference's @latest URL when reproducibility matters; pin a reviewed v11 version. The Jupyter example uses mermaid.ink, the editor workflow uses mermaid.live, and CDN icon packs can make diagram source or related metadata leave the machine. Obtain approval before using those external services.

Keep source, links, and rendering safe

• Prefer securityLevel: 'strict', the documented default, for user-supplied or published diagrams. loose allows more HTML and interaction and needs a separately reviewed trust boundary.
• Do not place credentials, private endpoints, customer identifiers, hidden architecture, incident details, or sensitive data in source, exported images, links, tooltips, comments, or accessibility descriptions.
• Interactive click handlers and URLs can navigate or execute page callbacks. Include them only when required and reviewed for the target host.
• Custom CSS, HTML labels, icon loaders, and remote fonts change security, appearance, accessibility, and reproducibility. Record each external asset.
• Generated SVG can contain links, IDs, style, and metadata. Treat it as active content when embedding and apply the destination's sanitization policy.
• Writing source or rendered files is authorized only when requested. Publishing, uploading, embedding in production, or replacing a checked-in diagram remains a separate action.

Verify outputs and evidence

A complete result should include:

• Canonical Mermaid source in the requested Markdown block or .mmd file, with exact IDs, labels, relationships, dates, values, and comments.
• accTitle and a useful accDescr, plus readable text alternatives when the destination cannot expose Mermaid's SVG accessibility metadata reliably.
• Mermaid and CLI or host versions, security level, theme, layout, font, configuration file, custom CSS, and commands used.
• Parse result distinct from SVG, PNG, PDF, or live-host render result.
• Rendered artifact paths and dimensions, along with visual inspection for collisions, clipping, edge routing, label placement, contrast, and scale.
• Reconciliation against the supplied process, schema, timeline, or dataset, with inferred layout and unsupported target features called out.

The Skill references companion /ak:tech-graph guidance for universal SVG layout review, but that capability is not part of this Skill directory. Use it only when it is actually installed; otherwise perform the stated visual checks with available tools and report the missing companion. The Skill contains no renderer, scripts, or directly scoped tests. The pinned stable and beta releases contain identical files.

Troubleshoot and interpret limits

Use ak:markdown-novel-viewer to read trusted Markdown with live Mermaid rendering or Runtime adapters to review renderer and tool differences.