Creating Diagrams

Creating Diagrams

Use Cases

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

Operations

Format Selection

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