🦾 Mermaid

Executive Summary

Mermaid is our preferred tool for inline text-based diagrams in the Funday documentation wiki and agent communication. It enables rapid creation of flowcharts, sequence diagrams, and architecture graphs that are version-controllable and easily rendered across our platforms. This skill codifies the specific conventions and constraints required to make Mermaid diagrams reliable, readable (especially in dark mode), and aesthetically aligned with our styling systems.

When to use / When NOT to use

Use When:

• Documenting system architecture or flow control.
• Showing request lifecycles and sequence interactions.
• Creating state machine diagrams.
• Needing quick, versionable visuals directly in Markdown.

When NOT to use:

• Complex system landscapes needing spatial grouping (use JSON Canvas instead).
• Detailed UI mockups or layouts (use SVG or Figma).
• Diagrams requiring highly custom shapes, freehand drawing, or precise pixel positioning.

Rules

1. Label Quoting and Syntax

Always quote node labels, especially if they contain spaces, emojis, or punctuation. Avoid using the unquoted lowercase word end as a node ID or label, as it is a reserved keyword in some Mermaid diagram types and can break rendering.

2. Diagram Density

Keep graphs sparse and focused. If a flowchart has more than 15-20 nodes, break it down into smaller, focused diagrams. A tangled web of edges reduces readability.

3. Semantic Colors

Use semantic colors that map well to our theme. Mermaid in our setup supports class-based styling or theme variables. When assigning colors or classes, stick to our semantic palette:

• primary
• success
• warn
• danger
• muted

4. Dark Mode Legibility

Always verify that your diagram is legible in dark mode. Avoid hardcoding absolute colors (like #000000 or #ffffff) directly in node styles unless absolutely necessary, as they will clash when the theme switches.

5. Fencing

Use standard Markdown code fences tagged with mermaid. Quartz and our OFM (Obsidian Flavored Markdown) processor handle these automatically.

Examples

Good Flowchart

graph TD
    A["🚀 Start Process"] --> B{"Is User Authenticated?"}
    
    B -- Yes --> C["✅ Grant Access"]
    B -- No --> D["🔒 Redirect to Login"]
    
    C --> E["Load Dashboard"]
    D --> F["Show Auth Prompt"]

    classDef success fill:#10b981,stroke:#047857,color:white;
    classDef danger fill:#ef4444,stroke:#b91c1c,color:white;
    class C success;
    class D danger;

Good Sequence Diagram

sequenceDiagram
    participant U as User
    participant A as API Gateway
    participant S as Auth Service
    
    U->>A: POST /login
    A->>S: Validate Token
    S-->>A: 200 OK (JWT)
    A-->>U: 200 OK + Cookie

Failure Modes / Checks

1. Syntax Errors: Mermaid fails silently or shows a giant red error block if a label isn’t quoted and contains an invalid character.
2. Invisible Text: Hardcoding text color to black will make the diagram unreadable when viewed in Quartz’s dark mode.
3. Keyword Collisions: Using end, subgraph, or style as a node ID will break the parser.
4. Edge Spaghettification: Too many intersecting lines. Check if you can use --> vs --- or adjust the direction (TD vs LR) to clean up the layout.

Related Links

• Mermaid Official Documentation
• Canvas Guru
• SVG Guru