| name | clarity-visualize |
| description | Create Mermaid diagrams to visualize relationships, processes, and structures. Use when: (1) asked to draw or diagram or visualize, (2) explaining process with multiple interacting elements, (3) describing hierarchical or network structure, (4) comparing multiple alternatives. |
Visualize
Create visual diagrams that work on both light and dark backgrounds to communicate structure, flow, and relationships.
Instructions
When I need to visualize processes, relationships, or conceptual structures, I create Mermaid diagrams that clarify rather than complicate.
-
Choose the right diagram type - I select flowchart for processes with decisions and branches, sequence diagrams for interactions over time between participants, class diagrams for hierarchical or categorical relationships, ER diagrams for entity relationships, or state diagrams for lifecycle and transitions, because each type reveals different aspects of a structure and choosing poorly creates confusion rather than clarity.
-
Optimize information density - I include enough detail to make the diagram useful but abstract away unnecessary specifics, showing the essential structure without overwhelming with every detail, because a diagram that tries to show everything shows nothing effectively and the goal is insight not completeness.
-
Apply consistent theming - I use colors with sufficient contrast for both light and dark backgrounds rather than assuming one display mode, ensuring readability regardless of viewer preference or environment, because a diagram that only works in one mode creates accessibility barriers and forces viewers to adjust their settings.
-
Label for clarity - I add descriptive labels to nodes and edges that make the diagram self-documenting, avoiding cryptic abbreviations or assuming context that viewers might not have, writing labels that answer "what is this?" and "why does this connect to that?" without requiring the viewer to reference external documentation.
-
Structure layout intentionally - I arrange elements to emphasize logical flow and relationships rather than letting tools auto-layout randomly, placing related components near each other and using directional flow that matches how viewers naturally scan, because layout communicates hierarchy and relationship as much as the connections themselves.
-
Test readability - I review the diagram asking "can someone unfamiliar with this understand the key relationships?" and revise until the answer is yes, removing elements that add noise rather than signal and ensuring the diagram stands alone without requiring lengthy explanation.
-
Integrate appropriately - I embed diagrams where they complement prose explanations, placing them where they provide maximum value for understanding rather than decorating every document with unnecessary visualizations.
Examples
Clarifying a decision-making process
Someone asks how their organization's budget approval process works. The process involves multiple stakeholders with different approval thresholds and conditional escalation paths. Rather than writing paragraphs describing each path, I create a flowchart showing the decision points: requests under $5k go directly to department heads, $5k-$25k requires finance review, over $25k needs executive approval, with branches for expedited requests and rejection appeals. The diagram reveals that the current process has a bottleneck where all finance reviews go through a single person regardless of amount, which explains the delays people have been experiencing. What would have been a confusing narrative becomes an immediately scannable visual that also surfaces process improvements.
Mapping stakeholder relationships
A project manager needs to understand who influences decisions in a new client organization. The relationships are complex with formal reporting lines that differ from actual influence patterns. I create a diagram showing both the official hierarchy and the informal influence connections, using different line styles to distinguish them. The visualization reveals that while the CTO formally reports to the CEO, most technical decisions actually flow through a senior architect who has no direct reports but strong relationships across teams. This insight helps the project manager know who to include in technical discussions versus who needs to sign off formally.
Explaining a multi-step process
Someone is learning how their organization handles customer complaints and asks for an overview. The process spans multiple departments with handoffs, escalation conditions, and feedback loops. Instead of walking through each step verbally, I create a sequence diagram showing the interaction between customer service, quality assurance, the relevant department, and management, with branches for different resolution paths. The diagram makes visible that complaints currently bounce between departments three times on average before resolution, and that there's no feedback loop to the customer during the investigation phase. The visualization both explains the current process and highlights where improvements could reduce friction.
Scripts
mermaid-theme.ts
Outputs themed Mermaid templates for different diagram types with light/dark compatible color schemes.
Usage:
bun {baseDir}/scripts/mermaid-theme.ts --type <flowchart|sequence|class|er|state>
Example:
bun {baseDir}/scripts/mermaid-theme.ts --type flowchart > approval-process.mmd
Output: A complete starter template with theme configuration applied, ready to edit with your specific content.
Supported types:
flowchart: Process flows with decisions and branchessequence: Interactions over time between participantsclass: Hierarchical or categorical relationshipser: Entity relationshipsstate: Lifecycle and state transitions
mermaid-preview.ts
Opens a browser window with live preview of a Mermaid diagram.
Usage:
bun {baseDir}/scripts/mermaid-preview.ts --file <path-to-mermaid-file>
echo "graph TD; A-->B" | bun {baseDir}/scripts/mermaid-preview.ts
Example:
bun {baseDir}/scripts/mermaid-preview.ts --file approval-process.mmd
Behavior: Creates a temporary HTML file using the Mermaid.js CDN and opens it in your default browser for immediate visual feedback.
