Box Diagram

Box Diagram Generator

Purpose

Generate perfectly aligned box diagrams where every box, line, and arrow lines up correctly in monospace fonts. Uses a Python validator to catch misalignment before outputting.

Workflow

1. Generate the diagram following the Rules below
2. Write diagram to a temp file
3. Run validator: python ${CLAUDE_SKILL_DIR}/validate.py
4. If validator reports errors — fix them and re-validate
5. Only output the diagram to the user after it passes validation
6. Output from the file — read the validated file and paste its content into the code block. NEVER re-type the diagram manually, as even one lost space breaks alignment

Validator

Located at ${CLAUDE_SKILL_DIR}/validate.py

# Validate a file
python ${CLAUDE_SKILL_DIR}/validate.py diagram.txt

# Validate inline
python ${CLAUDE_SKILL_DIR}/validate.py --inline "╭──╮\n│  │\n╰──╯"

Checks:

• Double-width characters (emoji, CJK) that break alignment
• Inconsistent line widths within box groups
• Vertical connector (│, ╭) misalignment between consecutive lines
• Broken box borders (╭───╮ with wrong fill)
• Tab characters

Returns OK: N lines, max width M chars on success, or list of errors.

IMPORTANT: Always validate before showing the diagram to the user.

Rules

Character Set

Use Unicode box-drawing characters:

| Element | Character | Code point | |---------|-----------|------------| | Corners | ╭ ╮ ╰ ╯ | U+256D-256F | | Horizontal | ─ | U+2500 | | Vertical | │ | U+2502 | | Arrow right | ▸ | U+25B8 | | Arrow down | ▾ | U+25BE | | Content arrow | → | U+2192 | | Branch corners | ┌ ┐ └ ┘ | U+250C-2518 | | T-junctions | ┬ ┴ ├ ┤ ┼ | U+252C-253C |

NEVER use emoji — they are double-width and break alignment.

Box Format

╭──────────────────╮
│  Content here    │
╰──────────────────╯

Width = left ╭ + dashes + right ╮. Content lines: │ + space + text padded to fixed width + space + │. The corners and │ must be in the same columns.

Construction Method

1. Define grid: assign exact column positions for each box (colA=0, colB=25, col_C=50)
2. Fixed-width boxes: every line in a box must be the same character count
3. Draw row by row: pad each content line to match the border width
4. Connectors: horizontal dashes count = gap between boxes, vertical │ shares column with box center
5. Assert text fits: assert len(text) <= inner_width before generating — one char overflow breaks everything
6. Validate: run the Python validator before output

Prefer Python generation for diagrams with 3+ boxes. Define helper functions for borders, content lines, and padding — hand-counting spaces is error-prone. Example pattern:

H = '\u2500'  # ─
V = '\u2502'  # │
TL, TR = '\u256d', '\u256e'  # ╭ ╮
BL, BR = '\u2570', '\u256f'  # ╰ ╯

def box_line(text, w):
    return V + ' ' + text + ' ' * (w - len(text)) + ' ' + V
def border_top(w):
    return TL + H * (w + 2) + TR
def border_bot(w):
    return BL + H * (w + 2) + BR

Connector Patterns

Horizontal:   ──────────▸     ◂──────────     ◂──────────▸
Vertical:     │               ▴
              │               │
              ▾               │

Branching (fan-out / fan-in)

Fan-out (1 → 3): use ┌ ┬ ┤ or ┐ with ─ between them. Fan-in (3 → 1): use └ ┼ ┘ with ─ between them.

         │                     (source)
┌────────┼────────┐            fan-out
│        │        │
▾        ▾        ▾

│        │        │
└────────┼────────┘            fan-in
         │                     (destination)
         ▾

Labels on Arrows

       label
A ──────────────────▸ B

    │
    │ label
    ▾

Anti-patterns

• NEVER use emoji (double-width)
• NEVER eyeball alignment — always validate with the script
• NEVER manually re-type the diagram for output — always read from the validated file. Even one lost space breaks alignment between corners and │
• NEVER mix tabs and spaces
• Avoid boxes wider than 60 chars

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ilia-pluzhnikov
• Source: ilia-pluzhnikov/box-diagram
• License: MIT

Install and usage instructions live in the source repository linked above.