What it does

Provides a reference system for creating clean, consistent diagrams using Unicode box-drawing characters. These diagrams render correctly in terminals, code comments, markdown files, and chat messages without requiring any rendering tools.

The pattern

Six diagram templates cover most documentation needs:

Boxes for components or containers:

┌─────────┐    ╔═════════╗    ╭─────────╮
│  Single  │    ║  Double  ║    │ Rounded │
└─────────┘    ╚═════════╝    ╰─────────╯

Tables for structured data:

┌──────┬───────┬────────┐
│ Name │ Role  │ Status │
├──────┼───────┼────────┤
│ API  │ Serve │ Active │
└──────┴───────┴────────┘

Horizontal flows for pipelines and sequences:

┌───────┐     ┌─────────┐     ┌────────┐
│ Input │────▶│ Process │────▶│ Output │
└───────┘     └─────────┘     └────────┘

Vertical flows for hierarchies and decision trees:

┌──────────┐
│ Decision │
└────┬─────┘
     │
  ┌──┴──┐
  ▼     ▼
┌───┐ ┌───┐
│ A │ │ B │
└───┘ └───┘

Layered architectures for stack diagrams:

┌─────────────────────┐
│     Frontend        │
├─────────────────────┤
│     API Layer       │
├─────────────────────┤
│     Database        │
└─────────────────────┘

Side-by-side comparisons for before/after or option evaluation:

┌─ Before ──────┐  ┌─ After ───────┐
│ Manual deploy │  │ Auto deploy   │
│ 30 min/deploy │  │ 2 min/deploy  │
└───────────────┘  └───────────────┘

Key decisions

Never mix character sets. Pick single-line (┌─┐│└─┘), double-line (╔═╗║╚═╝), or rounded (╭─╮│╰─╯) and stick with one set per diagram. Mixed styles look broken.

Use arrows for direction. ──▶ for horizontal flow, ──▼ for downward. Plain lines (───) for connections without directionality.

Test in your target renderer. Monospace font alignment is required. If your audience reads these in a proportional font, the diagrams will misalign. Wrap in code blocks (triple backticks) in markdown.

Keep it narrow. 60-80 characters wide maximum. Wider diagrams break in chat windows, terminal splits, and mobile views.

When to use it

When you need a diagram that lives alongside code: in README files, code comments, terminal output, chat messages, or commit descriptions. ASCII diagrams travel everywhere without rendering dependencies. They are version-controllable, diffable, and readable in any text editor. Use image-based diagrams only when the complexity exceeds what box-drawing characters can express clearly.