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:

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:

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

Markdown-Compatible Table

When ASCII boxes render poorly, use pipe tables:

| 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:

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

1. Count border lengths - top ─ count must equal bottom
2. Check vertical alignment - all │ must be in same column
3. Verify corner usage - ┌┐ top, └┘ bottom, never mixed
4. Match cell widths - every row same total width
5. Consistent spacing - same padding in all cells
6. 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

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