ascii-diagram

/ascii-diagram — Perfectly Aligned ASCII Diagrams

Orientation

Use when:

• The user wants any kind of text/ASCII diagram: architecture, flow, sequence, box-and-arrow, tree, table, org chart, network topology
• A diagram needs to be embedded in markdown, code comments, or plain text
• Visual alignment matters

Do NOT use when:

• The user wants an image (suggest Mermaid, PlantUML, or an image tool instead)
• The diagram is trivial (a single box or a one-line arrow)

What this skill needs:

• A description of what to diagram
• Optional: preferred style (single-line +--+, double-line ╔══╗, rounded ╭──╮, heavy ┏━━┓)
• Optional: target width constraint

Protocol

Step 1: PLAN THE LAYOUT

Before writing ANY characters, plan the diagram structurally:

1. Identify elements: List every box/node and its label text
2. Identify connections: List every arrow/line between elements, with optional labels
3. Choose layout direction: left-to-right, top-to-bottom, or mixed
4. Calculate dimensions:
   • Each box width = max label line length + 4 (2 padding + 2 border)
   • Each box height = label line count + 2 (top + bottom border)
   • Gutters between boxes: minimum 3 characters for arrows (→)
   • For vertical arrows: minimum 1 row gap

Write this plan out explicitly before proceeding. Example:

Elements:
  A: "Client" → width=10, height=3
  B: "Server" → width=10, height=3
  C: "Database" → width=12, height=3
Layout: left-to-right
Connections: A→B (HTTP), B→C (SQL)
Total width: 10 + 6 + 10 + 6 + 12 = 44

Step 2: BUILD ON A CHARACTER GRID

Use this JavaScript approach mentally (or actually execute it via Bash if the diagram is complex):

// For complex diagrams, RUN this — don't try to hand-align
class Grid {
  constructor(w, h) {
    this.w = w; this.h = h;
    this.cells = Array.from({length: h}, () => Array(w).fill(' '));
  }
  put(x, y, char) {
    if (x >= 0 && x < this.w && y >= 0 && y < this.h) this.cells[y][x] = char;
  }
  text(x, y, str) {
    for (let i = 0; i < str.length; i++) this.put(x + i, y, str[i]);
  }
  box(x, y, w, h, label) {
    // Top border
    this.put(x, y, '+');
    for (let i = 1; i < w-1; i++) this.put(x+i, y, '-');
    this.put(x+w-1, y, '+');
    // Bottom border
    this.put(x, y+h-1, '+');
    for (let i = 1; i < w-1; i++) this.put(x+i, y+h-1, '-');
    this.put(x+w-1, y+h-1, '+');
    // Sides
    for (let j = 1; j < h-1; j++) {
      this.put(x, y+j, '|');
      this.put(x+w-1, y+j, '|');
    }
    // Label (centered)
    const lines = label.split('\n');
    const startY = y + Math.floor((h - lines.length) / 2);
    for (let li = 0; li < lines.length; li++) {
      const line = lines[li];
      const startX = x + Math.floor((w - line.length) / 2);
      this.text(startX, startY + li, line);
    }
  }
  hArrow(x1, x2, y, label) {
    // Horizontal arrow from x1 to x2 at row y
    const dir = x2 > x1 ? 1 : -1;
    for (let x = x1; x !== x2; x += dir) this.put(x, y, '-');
    this.put(x2, y, dir > 0 ? '>' : '<');
    if (label) {
      const lx = Math.min(x1, x2) + Math.floor((Math.abs(x2-x1) - label.length) / 2);
      this.text(lx, y - 1, label);
    }
  }
  vArrow(x, y1, y2, label) {
    // Vertical arrow from y1 to y2 at column x
    const dir = y2 > y1 ? 1 : -1;
    for (let y = y1; y !== y2; y += dir) this.put(x, y, '|');
    this.put(x, y2, dir > 0 ? 'v' : '^');
    if (label) this.text(x + 2, Math.min(y1, y2) + Math.floor(Math.abs(y2-y1) / 2), label);
  }
  render() {
    return this.cells.map(row => row.join('').trimEnd()).join('\n');
  }
}