🧜 MermaidGuru

Mermaid that renders correctly and themes itself on this site. Read the rule once, copy a snippet, ship. Canon: 📜 SSOT Bible §4.

1. 🎯 When

Reach for Mermaid when the relationship is the content: flow, sequence, state, schema, or hierarchy. Static iconography or hand-tuned art → 🎨 SvgGuru. Spatial knowledge maps → 🗺️ CanvasGuru.

2. 🚫 Theme

The site themes Mermaid from CSS variables and re-themes live on the dark/light toggle (verified in the plugin fork).

• Never add %%{init: ...}%%. Never set theme, themeVariables, or hex colors.
• A hardcoded directive forces dark in light mode and freezes colors so they stop adapting. Delete any you inherit.
• You get correct, adaptive, human-friendly colors for free by writing zero theme config.

3. 🔤 Labels

The #1 silent breakage. Quote every edge label and any node/subgraph text with special chars.

| Situation | ❌ Wrong | ✅ Right | | ---------------------- | ---------------------- | -------------------------- | --- | ------ | ------------ | --- | | Edge label | A --> | sends data | B | A --> | "sends data" | B | | Node with () / : | N[Daemon (py/async)] | N["Daemon (py / async)"] | | Subgraph title | subgraph A: B | subgraph S["A: B"] | | Reserved id | end[Stop] | done["Stop"] |

4. 📊 Picker

Need	Use
Process / pipeline / decision	flowchart
Messages between actors over order	sequenceDiagram
Lifecycle / status machine	stateDiagram-v2
Data model / relations	erDiagram
Idea hierarchy / brainstorm	mindmap
⛔ Time-boxed plan	none — convert to Step phases

5. 🩹 Fixes

Top syntax errors and their one-line cures.

• “Parse error” near a label → unquoted edge label; wrap in "...".
• Diagram half-renders / cut off → unquoted () or : in node text; quote the node.
• end swallows the graph → rename the node id (done, stop).
• Colors don’t toggle → you left an %%{init}%% directive; remove it.
• Arrow ignored → use --> (flowchart) or ->>/-->> (sequence), not →.
• Mindmap won’t parse → indentation, not arrows, defines structure; no -->.

6. 📋 Snippets

Flowchart:

flowchart TD
  A["User Request"] -->|"validate"| B{"Valid?"}
  B -->|"yes"| C["Process"]
  B -->|"no"| D["Reject (400)"]
  C --> E["Respond"]

Sequence:

sequenceDiagram
  participant U as User
  participant O as OMP
  participant K as OmpKeep
  U->>O: prompt
  O->>K: read memory
  K-->>O: context
  O-->>U: answer

State:

stateDiagram-v2
  [*] --> Draft
  Draft --> Review: submit
  Review --> Draft: changes
  Review --> Published: approve
  Published --> [*]

ER:

erDiagram
  AGENT ||--o{ SESSION : runs
  SESSION ||--o{ MESSAGE : contains
  AGENT {
    string id
    string role
  }

Mindmap:

mindmap
  root("0rk SSOT")
    Skills
      MermaidGuru
      CanvasGuru
    Stack
      omp
      quartz5

Spatial maps beyond a diagram → 🗺️ CanvasGuru. Hand-drawn theme-aware art → 🎨 SvgGuru.