MermaidGuru SSOT Standards

Title: MermaidGuru SSOT Standards Source: quartz-ssot/content/skills/gurus/MermaidGuru.md Summary: Diagram generation standards enforcing double-quoted edge labels, auto-theming, and precise chart selection for Quartz parsers.

💡 Best Practices (Patterns)

• Semantic Usage: Use Mermaid only when the relationship is the content (flow, sequence, state, schema, hierarchy). Fallback to Canvas for spatial maps or SVG for static art.
• Auto-Theming: Write zero theme configuration. The site automatically themes Mermaid from CSS variables and re-themes live on dark/light toggles.
• Always Quote Labels: Double-quote every single edge label and any node/subgraph text containing special characters ((), /, :).
• Safe IDs: Always rename reserved keywords (e.g., end to done or stop) to prevent graphs from failing to render.
• Precise Chart Selection:
  • flowchart → Process / pipeline / decision.
  • sequenceDiagram → Messages between actors.
  • stateDiagram-v2 → Lifecycle / state machine.
  • erDiagram → Data models.
  • mindmap → Idea hierarchy (use indentation, never arrows).

🚨 Gotchas / Warnings (Anti-patterns)

• Hardcoded Themes: ❌ Never add %%{init: ...}%%, theme, themeVariables, or hex colors. Hardcoded directives freeze colors and break light/dark mode adaptability.
• Unquoted Edge Labels: ❌ Never write A -->|label| B. ✅ Always write A -->|"label"| B. This is the #1 cause of silent breakage in Quartz.
• Unquoted Special Characters: ❌ Never write N[Daemon (py/async)]. ✅ Always write N["Daemon (py / async)"]. Unquoted characters will half-render or truncate the diagram.
• Reserved IDs: ❌ Never use end[Stop]. The end keyword swallows the graph.
• Invalid Arrows: ❌ Never use standard text arrows like →. ✅ Always use --> for flowcharts or ->> / -->> for sequence diagrams.
• Gantt Charts: ❌ Never use Mermaid for time-boxed plans. Convert those into Markdown Step phases instead.

🔍 Research / References

• Target File: ~/quartz-ssot/content/skills/gurus/MermaidGuru.md
• SSOT Canon: Quartz SSOT Bible §4