# Diagrams:ascii Art

> Draw ASCII-art / text diagrams for software documentation using extended ASCII box-drawing characters (IBM CP437 codes > 128 — single-line ┌─┐│└┘├┤┬┴┼, double-line ╔═╗║╚╝, shading ░▒▓█), never +, -, |, or /. Enforces ≤80-char width and strict row/column alignment, renders in monospaced fonts. Use when the user wants an ascii diagram, a text/box diagram, a terminal diagram, or a plain-text visualization.

- Skill: `florianbuetow/diagrams-ascii-art` (Agent Skill, multi-file: 20 files)
- Install (CLI): `npx skillmds@latest add florianbuetow/diagrams-ascii-art`
- Raw SKILL.md: https://api.skillmd.com/api/skills/florianbuetow/diagrams-ascii-art/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: florianbuetow (https://skillmd.com/u/florianbuetow)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/florianbuetow/diagrams-ascii-art

---


# Create ASCII Art Diagrams with Extended ASCII Characters (>128)

## Objective

Generate clean, professional ASCII art diagrams for software development documentation using
extended ASCII box-drawing characters (Unicode codes 128–255, specifically the IBM PC Code
Page 437 box-drawing set).

---

## ⚠️ Critical Requirements

1. **Use ONLY these box-drawing characters** (ASCII codes > 128 from CP437):
   - **Single-line characters**: `┌` (218), `─` (196), `┐` (191), `│` (179), `└` (192), `┘` (217), `├` (195), `┤` (180), `┬` (194), `┴` (193), `┼` (197)
   - **Double-line characters**: `╔` (201), `═` (205), `╗` (187), `║` (186), `╝` (188), `╚` (200), `╩` (202), `╦` (203), `╠` (204), `╣` (185), `╬` (206)
   - **Shading/Block**: `░` (176), `▒` (177), `▓` (178), `█` (219), `▄` (220), `▀` (223)

2. **Never use standard ASCII** (`+`, `-`, `|`, `/`) for box edges — only the extended characters above.

3. **Must render in monospaced fonts** only (terminal, VS Code, code editors).

4. **Maximum width: 80 characters** (fits standard terminal/code comments).

5. **Never use emojis — strictly forbidden.** No emoji (or any other wide / double-width / pictographic glyph) anywhere in the diagram: not in borders, not in labels, not inside boxes. Emojis render as two cells in most terminals and silently break column alignment. Use plain ASCII (codes 0–127) for all text and the box-drawing set above for structure.

---

## Character Reference Table (Copy-Paste Ready)

```
SINGLE LINE:
┌ (218) ─ (196) ┐ (191) │ (179) └ (192) ┘ (217)
├ (195) ┤ (180) ┬ (194) ┴ (193) ┼ (197)

DOUBLE LINE:
╔ (201) ═ (205) ╗ (187) ║ (186) ╝ (188) ╚ (200)
╠ (204) ╣ (185) ╦ (203) ╩ (202) ╬ (206)

SHADING:
░ (176) ▒ (177) ▓ (178) █ (219)
```

---

## Step-by-Step Instructions

### Step 1: Define Diagram Purpose

Choose one:
- [ ] System architecture (components + connections)
- [ ] Data structure (nodes, pointers, trees)
- [ ] Flowchart (decision paths, sequences)
- [ ] API/request flow (client → server → database)
- [ ] Table/grid (structured data)

### Step 2: Plan Layout

- Sketch mentally: how many boxes? What's the flow?
- Keep total width ≤ 80 chars.
- Use consistent spacing (2 spaces between components minimum).

### Step 3: Draw Boxes

Use single-line for primary boxes, double-line for highlighted/outer containers:

```
SINGLE-LINE BOX (component):
┌────────────┐
│   Label    │
└────────────┘

DOUBLE-LINE BOX (system/container):
╔════════════════╗
║  System Name   ║
╚════════════════╝
```

### Step 4: Connect Components

Use horizontal/vertical lines with proper junctions:

```
HORIZONTAL CONNECTION:
┌─────┐ ──────── ┌─────┐
│ Box │          │ Box │
└─────┘ ──────── └─────┘

VERTICAL CONNECTION:
     ┌──────┐
     │ Box  │
     │ (179)│
     │ (179)│
     └──┬───┘
        │ (179)
     ┌──┴──┐
     │ Box │
     └─────┘

JUNCTIONS (use correct corner):
├ (195) = vertical + right
┤ (180) = vertical + left
┬ (194) = horizontal + down
┴ (193) = horizontal + up
┼ (197) = cross (all 4 directions)
```

### Step 5: Add Arrows/Flow Indicators

```
Arrows:
──▶  (use ─ (196) + ▶)
├───▶
│
▼
┌───┐
```

### Step 6: Label Everything

- Every box must have a descriptive label.
- Labels centered horizontally in box.
- Use plain ASCII (codes 0–127) for text inside boxes.

### Step 7: Validate Alignment

- Check all vertical lines align (same column).
- Check all horizontal lines align (same row).
- No overlapping characters.
- Test in your terminal/editor.

### Automated connector check

Validate connector alignment with the bundled checker (self-contained, no network):

```
scripts/ascii-connector-check.sh diagram.txt      # or:  cat diagram.txt | scripts/ascii-connector-check.sh
```

It flags any connector whose open end has nothing to attach to — dangling ends, off-by-one shifts,
lines running into text, and line-weight mismatches — printing the line, column, glyph, and reason.
The connection rules it enforces are in `references/connector-rules.md`; sample diagrams and a
self-test suite live in `resources/` (run `resources/run-tests.sh`).

---

## Example Diagrams

### Example 1: System Architecture

```
╔═══════════════════════════════════════════╗
║           Microservices System            ║
╠═══════════════════════════════════════════╣
║  ┌──────────┐      ┌────────────┐         ║
║  │  Client  │ ───▶ │ API Gateway│         ║
║  └──────────┘      └────┬───────┘         ║
║                         │ (179)           ║
║              ┌──────────┼───────────┐     ║
║              │          │           │     ║
║         ┌────▼────┐ ┌───▼────┐ ┌────▼───┐ ║
║         │Service A│ │ServiceB│ │ServiceC│ ║
║         └────┬────┘ └───┬────┘ └────┬───┘ ║
║              │          │           │     ║
║              └──────────┼───────────┘     ║
║                         │ (179)           ║
║                    ┌────▼─────┐           ║
║                    │ Database │           ║
║                    └──────────┘           ║
╚═══════════════════════════════════════════╝
```

### Example 2: Data Structure (Linked List)

```
┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐
│ Node 1 │──│ Node 2 │──│ Node 3 │──│ Node 4 │
│  val:5 │  │ val:12 │  │ val:7  │  │ val:3  │
└───┬────┘  └───┬────┘  └───┬────┘  └───┬────┘
    └───────────┴───────────┴───────────┘
               (next pointers)
```

### Example 3: API Request Flow

```
┌──────────┐     HTTP/JSON     ┌──────────────┐
│  Client  │ ─────────────────▶│ API Gateway  │
│ (Browser)│                   └──────┬───────┘
└──────────┘                          │
                                      │ (179)
                              ┌───────▼───────┐
                              │  Auth Service │
                              └───────┬───────┘
                                      │ (179)
                              ┌───────▼───────┐
                              │ User Database │
                              └───────────────┘
```

---

## Quality Checklist

Before finalizing, verify:
- ✅ All box edges use extended ASCII (codes > 128)
- ✅ No standard ASCII (`+`, `-`, `|`) for box edges
- ✅ No emojis or wide/pictographic glyphs anywhere (strictly forbidden)
- ✅ Width ≤ 80 characters
- ✅ All lines align perfectly (no gaps)
- ✅ Labels are descriptive and centered
- ✅ Arrows show direction clearly
- ✅ Renders correctly in monospaced terminal

---

## Common Pitfalls to Avoid

| ❌ Wrong     | ✅ Right        |
|-------------|-----------------|
| `+------+`  | `┌──────┐`      |
| `\| text \|`  | `│ text │`      |
| `---->`     | `───▶`          |
| Width 100+  | Width ≤ 80      |
| Mixed fonts | Monospaced only |
| Emoji in labels (🎉 ✅ ⚠) | Plain ASCII text only |

---

## Encoding Notes

- Save files as **UTF-8** (most modern terminals support this).
- On Windows CMD: use `chcp 65001` for UTF-8.
- On macOS/Linux: UTF-8 is default.
- If characters show as `?`, your terminal font doesn't support CP437/Unicode box drawing.

---

**Now create your ASCII art diagram following these instructions.** Start by defining the
diagram's purpose, then build it step-by-step using ONLY the characters from the reference table.