mermaid-syntax

name	mermaid-syntax
description	This skill should be used when the user asks about Mermaid diagram syntax, how to write flowchart, sequence, class, state, ER, Gantt, C4, mindmap, timeline, or other diagram types, node shapes, styling, theming, or rendering errors.
paths	["**/*.mmd","**/*.mermaid","**/ARC-*-DIAG-*.md"]

Mermaid Syntax Reference

A comprehensive reference for all 23 Mermaid diagram types plus configuration and theming. This skill provides official Mermaid syntax documentation sourced from the mermaid-skill project (auto-synced from upstream Mermaid docs).

This skill ships reference material, not runnable scripts. Read the relevant reference file with Read, apply the syntax, and write the diagram into the user's artefact. Do not Bash-execute anything from references/ — they are Mermaid syntax docs, not commands.

To look up syntax for a specific diagram type, identify the type from the table below and read the corresponding reference file.

Supported Diagram Types

Select the appropriate diagram type and read the corresponding reference file:

Type	Reference	ArcKit Commands Using It
Flowchart	flowchart.md	/arckit:diagram, /arckit:dfd, /arckit:roadmap, /arckit:plan, /arckit:backlog, /arckit:strategy, /arckit:story, /arckit:jsp-936
Sequence Diagram	sequenceDiagram.md	/arckit:diagram
Class Diagram	classDiagram.md	—
State Diagram	stateDiagram.md	—
ER Diagram	entityRelationshipDiagram.md	/arckit:data-model
Gantt Chart	gantt.md	/arckit:roadmap, /arckit:plan, /arckit:strategy, /arckit:story, /arckit:presentation
Pie Chart	pie.md	/arckit:story, /arckit:presentation
Mindmap	mindmap.md	/arckit:story
Timeline	timeline.md	/arckit:story
Git Graph	gitgraph.md	—
Quadrant Chart	quadrantChart.md	/arckit:presentation
Requirement Diagram	requirementDiagram.md	—
C4 Diagram	c4.md	/arckit:diagram, /arckit:presentation
Sankey Diagram	sankey.md	—
XY Chart	xyChart.md	—
Block Diagram	block.md	—
Packet Diagram	packet.md	—
Kanban	kanban.md	—
Architecture Diagram	architecture.md	—
Radar Chart	radar.md	—
Treemap	treemap.md	—
User Journey	userJourney.md	—
ZenUML	zenuml.md	—

Configuration & Theming

Topic	Reference
Theming	config-theming.md
Directives	config-directives.md
Layouts	config-layouts.md
Configuration	config-configuration.md
Math	config-math.md
Tidy Tree	config-tidy-tree.md
Examples	examples.md

C4 Layout Science

For research-backed C4 diagram layout guidance (declaration ordering, edge crossing targets, colour standards, PlantUML directional hints), see c4-layout-science.md. This ArcKit-specific reference supplements the upstream C4 syntax reference with graph drawing science and layout optimisation techniques.

Common Syntax Gotchas

These are the most common Mermaid syntax errors encountered when generating diagrams:

Gotcha	Problem	Fix
<br/> in flowchart edge labels	Mermaid flowchart parser rejects HTML in edge labels	Use comma-separated text: -->|"Uses, HTTPS"|
end as node ID	end is a reserved keyword in Mermaid	Use a different ID: EndNode["End"]
Gantt date formats	Gantt requires specific date format	Use YYYY-MM-DD (e.g., 2025-01-15)
Gantt task status	Invalid task status keywords	Valid: done, active, crit, milestone
Parentheses in labels	Unescaped () breaks node parsing	Wrap in quotes: Node["Label (with parens)"]
Special chars in IDs	Hyphens, dots, spaces in node IDs	Use camelCase or underscores: apiGateway, api_gateway
Missing semicolons in ER	ER diagram attributes need specific syntax	Follow entity { type name } pattern
Subgraph naming	Subgraph IDs with spaces need quotes	subgraph "My Group"

ArcKit Integration

This skill handles conversational Mermaid syntax questions — quick lookups, syntax examples, troubleshooting rendering issues, and learning about diagram types.

For formal architecture diagram generation with document control, project integration, C4 layout science, and governance compliance, use the /arckit:diagram command instead. It generates versioned diagram artifacts saved to your project directory with full traceability to requirements and architecture principles.