Skip to main content

Swimlane Infographic Guide

Introduction​

Swimlane diagrams provide a clear visualization of how processes flow across different departments or roles. This guide establishes standards for creating consistent swimlane diagrams in our Knowledge Base using Mermaid syntax with popup modal display in Docusaurus.

Using MermaidModal in Docusaurus​

Basic Usage​

To display a Mermaid diagram in a modal, use the MermaidModal component:

<MermaidModal title="Your Diagram Title">{`
flowchart LR
    %% Your diagram code here
    A[First Step] --> B[Second Step]
`}</MermaidModal>

Key points:

  • Wrap your Mermaid diagram code in template literals using {`...`}
  • Provide a descriptive title that will appear on both the button and modal
  • The diagram will be hidden behind a button until clicked

Multiple Diagrams​

You can use multiple MermaidModal components in the same document:

<MermaidModal title="First Process">{`
flowchart LR
    A --> B
`}</MermaidModal>

<MermaidModal title="Second Process">{`
flowchart LR
    C --> D
`}</MermaidModal>

Mermaid Syntax Specification​

Basic Structure​

All swimlane diagrams should use the following format:

<MermaidModal title="Process Title">{`
flowchart LR
    %% Define participants as swimlanes
    subgraph [Participant1]
    A[Step1]
    B[Step2]
    end
    
    subgraph [Participant2]
    C[Step3]
    end
    
    %% Define process flow
    A --> B
    B --> C
`}</MermaidModal>

Component Naming Conventions​

  1. Participant/Swimlane IDs

    • Use descriptive role names
    • Format: Role or Department name

  2. Step IDs

    • Use single letters in sequential order (A, B, C, etc.)
    • Add explanatory comments in the diagram

  3. Node Text

    • Use concise action phrases (e.g., "Reviews Documents" not "The documents are reviewed")
    • Start with action verbs when possible
    • Keep to 3-5 words maximum

Flow Direction​

  • Always use left-to-right flow (flowchart LR) for process swimlanes
  • Use top-to-bottom flow (flowchart TD) only for hierarchical or decision-based diagrams

Connection Labels​

  • Add labels to connections when the transfer involves critical information
  • Format: A -->|Label Text| B
  • Keep labels to 1-3 words when possible

Styling Guidelines​

Color Schemes​

By default, Mermaid will apply its own colors based on the current theme. For consistency, use these colors for common roles:

  • Customers/Owners: fill:#e0f7fa
  • Management/Executives: fill:#e8f5e9
  • Project Management: fill:#ede7f6
  • Accounting/Finance: fill:#f3e5f5
  • Staff/Team Members: fill:#e8eaf6
  • Vendors/External Parties: fill:#fff3e0

Layout Best Practices​

  1. Participant Order

    • Arrange participants in the order they first appear in the process
    • Place the process initiator at the left or top
    • Group closely collaborating participants together

  2. Step Alignment

    • Within a swimlane, steps should progress left-to-right or top-to-bottom
    • Avoid long vertical chains within a horizontal swimlane

  3. Connection Flow

    • Avoid crossing lines when possible
    • Use clear connection paths that follow the general flow direction
    • For complex diagrams, consider breaking into multiple diagrams

Examples​

Example 1: Simple Approval Process​

Example 2: Payment Processing Flow​

Best Practices​

  1. Focus on Value Flow

    • Emphasize how value moves through the organization
    • Highlight key decision points and approvals

  2. Limit Complexity

    • Aim for 3-5 swimlanes maximum
    • If more are needed, consider breaking the process into multiple diagrams
    • Maximum of 15-20 total nodes for readability

  3. Use Consistent Terminology

    • Match node text to terminology used in the KB article
    • Use the same role names as in organizational charts

  4. Include Clear Start and End Points

    • Label the first step with a clear process initiator
    • Conclude with the final deliverable or outcome

  5. Diagram Review Process

    • Have stakeholders review diagrams for accuracy
    • Test diagrams with someone unfamiliar with the process to ensure clarity

Implementation Checklist​

  • Identify all participants/roles involved in the process
  • List all major steps in sequence
  • Determine handoffs between participants
  • Create diagram using Mermaid syntax
  • Review for clarity and completeness
  • Wrap diagram in MermaidModal component
  • Test in both light and dark themes

Troubleshooting​

Common Issues and Solutions​

  1. Diagram Not Rendering

    • Check for syntax errors in the Mermaid code
    • Ensure diagram code is wrapped in template literals {`...`}
    • Verify that all nodes referenced in connections are defined
    • Confirm that all opening and closing brackets match

  2. Modal Not Displaying

    • Verify the diagram code is properly escaped
    • Check browser console for any JavaScript errors
    • Ensure the MermaidModal component is properly imported

  3. Diagram Too Complex

    • Break into multiple smaller diagrams using separate MermaidModal components
    • Simplify complex steps into higher-level activities
    • Consider using multiple diagrams to show different levels of detail

  4. Theme Compatibility

    • The MermaidModal component automatically handles theme changes
    • Test the diagram in both light and dark themes
    • Adjust colors if needed using style definitions

Docusaurus Configuration​

The MermaidModal component is already configured in our Docusaurus setup. No additional configuration is needed to use it in your MDX files.

tip

Remember to always wrap your Mermaid diagram code in template literals using {`...`} when using the MermaidModal component.