Creating Diagrams

Use Cases

Architecture docs, workflows, data flows, comparisons, file trees, sequence diagrams, state machines.

Operations

Format Selection

| Format | Best For | Renders In | | ----------- | -------------------------------------------------------- | ------------------ | | ASCII | AI-maintained docs, terminals, code comments, git diffs | Everywhere | | Mermaid | Complex auto-layout, dependency trees, sequence diagrams | Markdown renderers | | Tables | Comparisons, feature matrices | Markdown |

Key tradeoffs:

• ASCII: works everywhere, clear git diffs, but manual layout is tedious
• Mermaid: auto-layout, parseable (@mermaid-js/parser), but requires renderer

Creating ASCII Diagrams

Reference references/ascii-patterns.md for: box diagrams, flows, file trees, decision branches, sequence diagrams, layered architecture.

Creating Mermaid Diagrams

Reference references/mermaid-syntax.md for: flowcharts, sequence diagrams, state diagrams, class diagrams, Gantt charts.

Adding Mermaid Live Links

Add one-click preview URLs above mermaid code blocks.

# Pipe diagram to script (run from project with pako installed)
echo 'sequenceDiagram
    A->>B: Hello' | node scripts/mermaid-url.js

Add URL on line before code fence for one-click preview.

CRITICAL

Right Edge Alignment

All lines in a boxed diagram must end at the same column. Ragged right edges look broken.

Technique:

1. Decide width first (e.g., 60 chars)
2. Pad with spaces to hit that width
3. Avoid deep nesting - prefer flat layouts
4. Count characters when unsure

WRONG (ragged right edges):
┌───────────────────────────┐
│  Frontend                 │
│  ┌──────┐   ┌───────┐    │
│  │ React│   │ Redux │    │
│  └──────┘   └───────┘│
└───────────────────────────┘
     ↑ inner boxes don't reach right edge

RIGHT (all lines end at same column):
┌──────────────────────────────┐
│  Frontend                    │
│  ┌──────────┐   ┌──────────┐ │
│  │  React   │   │  Redux   │ │
│  └──────────┘   └──────────┘ │
└──────────────────────────────┘

Notes

• Keep within 80-100 columns for terminal compatibility
• Label every box and arrow
• Prefer clarity over detail
• Follow logical flow: left-to-right or top-to-bottom

Appendix

Sources

Synthesized from:

• ascii-visualizer by ArieGoldkin
• Art by vdemeester