ASCII Diagrams & Text Visualization

Create and repair pixel-perfect monospace diagrams, tables, and wireframes.

Core Principle

Every character counts. In monospace, misaligned borders break visual structure instantly.

Validation Script

Always validate diagrams before committing:

bash

python scripts/validate_boxes.py <file.md>        # Check for issues
python scripts/validate_boxes.py <file.md> --fix  # Auto-fix width issues

Quick Reference: Box Drawing Characters

Corners:  ┌ ┐ └ ┘  (light)     ╔ ╗ ╚ ╝  (double)
Lines:    ─ │      (light)     ═ ║      (double)
T-joins:  ┬ ┴ ├ ┤  (light)     ╦ ╩ ╠ ╣  (double)
Cross:    ┼        (light)     ╬        (double)
Rounded:  ╭ ╮ ╰ ╯  (rounded corners)

Creating Tables

Standard Table Pattern

┌─────────────┬────────────┬───────┐
│ Column 1    │ Column 2   │ Col 3 │
├─────────────┼────────────┼───────┤
│ Value here  │ Another    │ 123   │
│ More data   │ Content    │ 456   │
└─────────────┴────────────┴───────┘

Construction rules:

Count characters in widest cell per column
Add 1 space padding on each side (cell width + 2)
Draw top border: ┌ + ─ × width + ┬ between columns + ┐
Draw header row with │ separators
Draw separator: ├ + ─ × width + ┼ between columns + ┤
Draw data rows
Draw bottom: └ + ─ × width + ┴ between columns + ┘

Markdown-Compatible Table

When ASCII boxes render poorly, use pipe tables:

markdown

| Status      | Count | Action   |
|-------------|-------|----------|
| Connected   | 42    | None     |
| Pending     | 7     | Review   |

Creating Wireframes

Modal/Dialog Pattern

╭────────────────────────────────────────╮
│  Modal Title                        ✕  │
├────────────────────────────────────────┤
│                                        │
│  Content area with description         │
│  text that explains the action.        │
│                                        │
│  ┌──────────────────────────────────┐  │
│  │ Input field                      │  │
│  └──────────────────────────────────┘  │
│                                        │
│               [Cancel]  [Confirm]      │
│                                        │
╰────────────────────────────────────────╯

Card Pattern

┌──────────────────────────────────┐
│ ◉ Card Title             [···]  │
├──────────────────────────────────┤
│                                  │
│  Card content goes here with    │
│  multiple lines of text.        │
│                                  │
│  ● Status: Active               │
│  ○ Priority: Medium             │
│                                  │
└──────────────────────────────────┘

Layout Grid

┌────────────────────────────────────────────────┐
│                    Header                      │
├────────────┬───────────────────────────────────┤
│            │                                   │
│  Sidebar   │         Main Content              │
│            │                                   │
│  ○ Nav 1   │   ┌──────────┐  ┌──────────┐     │
│  ● Nav 2   │   │  Card 1  │  │  Card 2  │     │
│  ○ Nav 3   │   └──────────┘  └──────────┘     │
│            │                                   │
├────────────┴───────────────────────────────────┤
│                    Footer                      │
└────────────────────────────────────────────────┘

Creating Flow Diagrams

Horizontal Flow

┌─────────┐     ┌─────────┐     ┌─────────┐
│  Start  │────▶│ Process │────▶│   End   │
└─────────┘     └─────────┘     └─────────┘

Vertical Flow with Branching

          ┌─────────┐
          │  Input  │
          └────┬────┘
               │
               ▼
          ┌─────────┐
          │ Decide  │
          └────┬────┘
               │
         ┌─────┴─────┐
         ▼           ▼
   ┌─────────┐ ┌─────────┐
   │   Yes   │ │   No    │
   └────┬────┘ └────┬────┘
        │           │
        └─────┬─────┘
              ▼
          ┌─────────┐
          │ Output  │
          └─────────┘

Architecture Diagram

┌───────────────────────────────────────────────┐
│                  Frontend                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │  React   │  │  Zustand │  │  Query   │    │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘    │
└───────┼─────────────┼─────────────┼───────────┘
        │             │             │
        └─────────────┼─────────────┘
                      │ HTTP/WS
                      ▼
┌───────────────────────────────────────────────┐
│                  Backend                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │ FastAPI  │──│ Services │──│  Models  │    │
│  └──────────┘  └────┬─────┘  └────┬─────┘    │
└─────────────────────┼─────────────┼───────────┘
                      │             │
        ┌─────────────┴─────────────┘
        ▼             ▼             ▼
   ┌─────────┐   ┌─────────┐   ┌─────────┐
   │ Postgres│   │  NATS   │   │  Redis  │
   └─────────┘   └─────────┘   └─────────┘

Special Elements

Icons & Indicators

Status:     ● active   ○ inactive   ◐ partial
Checkbox:   ☑ checked  ☐ unchecked  ☒ disabled
Arrows:     → ← ↑ ↓    ▶ ◀ ▲ ▼      ➜ ➤
Progress:   ▓▓▓▓▓░░░░░ (50%)
Stars:      ★★★☆☆ (3/5)
Bullets:    • ◦ ‣ ⁃

Button Representations

Standard:  [Button]    [  OK  ]   [Cancel]
Primary:   【Submit】   ⟦ Action ⟧
Rounded:   ( Click )   (  Go  )

Fixing Broken Diagrams

CRITICAL: Always Diagnose First

Before manually fixing, run this diagnostic:

bash

python3 << 'EOF'
diagram = """
PASTE_DIAGRAM_HERE
"""
print("Line-by-line analysis:\n")
for i, line in enumerate(diagram.strip().split('\n'), 1):
    has_broken = '�' in line or '\ufffd' in line
    marker = '⚠️  BROKEN CHAR' if has_broken else ''
    print(f"{i:2d}: len={len(line):3d} {marker}")
    if has_broken:
        # Find position of broken chars
        for j, c in enumerate(line):
            if c == '�' or ord(c) == 0xFFFD:
                print(f"    Position {j}: replacement character (corrupted Unicode)")
EOF

Common diagnostic findings:

Finding	Cause	Fix
`len` varies by 1-2	Missing/extra spaces	Pad to max length
`⚠️ BROKEN CHAR`	Corrupted Unicode (copy/paste issue)	Replace `�` with `─`
Very different lengths	Nested box misalignment	Realign inner boxes

Diagnostic Checklist

Count border lengths - top ─ count must equal bottom
Check vertical alignment - all │ must be in same column
Verify corner usage - ┌┐ top, └┘ bottom, never mixed
Match cell widths - every row same total width
Consistent spacing - same padding in all cells
No broken chars - search for � (U+FFFD replacement character)

Common Issues & Fixes

Issue: Jagged right edge

❌ BROKEN                     ✅ FIXED
┌───────────────────┐        ┌───────────────────┐
│ Short          │           │ Short             │
│ Much longer text│           │ Much longer text  │
└──────────────────┘          └───────────────────┘

Fix: Pad shorter lines with spaces to match longest line.

Issue: Mismatched borders

❌ BROKEN                     ✅ FIXED
┌───────────────────┐        ┌───────────────────┐
│ Content          |         │ Content           │
└──────────────────-┘         └───────────────────┘

Fix: Use consistent box characters (│ not |, ─ not -).

Issue: Wrong corner characters

❌ BROKEN                     ✅ FIXED
+-------------------+        ┌───────────────────┐
| Content           |        │ Content           │
+-------------------+        └───────────────────┘

Fix: Replace ASCII + - | with proper box drawing characters.

Validation Checklist

Before committing any ASCII diagram:

□ All horizontal borders same length
□ All vertical bars aligned in columns
□ Corners use correct characters (┌┐└┘)
□ Content properly padded with spaces
□ No mixed ASCII/Unicode border chars
□ Renders correctly in monospace font
□ Width fits target display (80-120 chars typical)
□ Run: python scripts/validate_boxes.py <file>

Width Guidelines

Context	Max Width	Notes
Markdown docs	80 chars	Traditional terminal width
Code comments	72 chars	Leaves room for indent
Wide displays	120 chars	Modern monitors
GitHub README	100 chars	Optimal for web rendering

Pro Tips

Draft in stages - Draw outer box first, then inner structure
Use placeholders - Mark widths with XXX then replace
Copy working patterns - Start from examples above
Validate always - Run validate_boxes.py before saving
Consider alternatives - Sometimes Mermaid/PlantUML better for complex diagrams

Search AI Tools

ascii-diagrams

Install this agent skill to your Project

SKILL.md