ascii-art-diagrams

name	ascii-art-diagrams
description	Rules for creating ASCII art diagrams with Unicode box-drawing characters. Covers boxes, trees, flow charts, and visual representations.
license	MIT
compatibility	opencode
metadata	{"type":"formatting","font":"Fira Code"}

ASCII Art Diagrams Skill

Auto-Installation

This skill requires no installation. It's a formatting guide, not a system.

To activate: Load this skill when you need to create diagrams:

skill({ name: "ascii-art-diagrams" })

When to load automatically:

• Creating architecture documentation
• Explaining complex flows or algorithms
• Building visual representations in code comments or markdown

---

When to Use This Skill

Use this skill when creating:

• Architecture diagrams
• Flow charts
• Tree structures (file trees, decision trees, hierarchies)
• Box diagrams (notes, warnings, info boxes)
• Tables with borders
• Any visual representation using Unicode box-drawing characters

Prerequisites

Font Requirement

For Unicode block characters and box-drawing characters to render correctly with monospace alignment:

/* Google Fonts - Fira Code */
@import url('https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;700&display=swap');

/* Apply to code blocks */
pre, code, .ascii-art {
    font-family: 'Fira Code', Menlo, Monaco, Consolas, 'Courier New', monospace;
}

Line Height

Use line-height 1 for ASCII diagrams (no extra spacing needed):

.ascii-art {
    line-height: 1;
}

---

Rule 1: Box Construction

1.1 All Lines Must Have Equal Length

Every line in a box MUST have identical character count. Pad shorter lines with spaces.

WRONG (unequal line lengths)
┌───────────────┐
│ short │
│ this is longer text │
└───────────────┘

CORRECT (all lines equal)
┌─────────────────────┐
│ short               │
│ this is longer text │
└─────────────────────┘

1.2 Compact Text - No Empty Lines Between Content

With line-height 1, content is compact. NO empty lines needed between text lines:

CORRECT (compact, no spacers)
┌───────────────────────────────────────────────────────┐
│  Modifying state DURING iteration loop                │
│  causes concurrent modification exception             │
│  -> collect changes, apply after loop completes       │
└───────────────────────────────────────────────────────┘

1.3 Minimum Padding

Always have at least 1-2 spaces between content and border:

CORRECT (2 space padding)
┌───────────────────────────────────────────────────────┐
│                                                       │
│  During batch processing:                             │
│                                                       │
│    - Items are processed sequentially                 │
│    - Cache is NOT invalidated                         │
│    - Previous results may be stale                    │
│                                                       │
└───────────────────────────────────────────────────────┘

Note: Empty lines at TOP and BOTTOM of box content are optional but recommended for readability.

---

Rule 2: Section Titles

2.1 Use Underlines for Title

In pseudocode blocks, use underline characters for title underlines:

CORRECT
FULL BUILD
___________________________________________________


1. CLEAN output directory

2. SORT dependencies by priority

Key points:

• One empty line after the underline
• Creates clean visual separation

2.2 Subsection Titles

For minor subsections within boxes, use thin horizontal lines:

MODE 1: Single Result (default)

- Returns first matching item
- Uses: findFirst()
- Best performance


MODE 2: All Results

- Returns array of ALL matching items

---

Rule 3: Tree Structures (Procedural Flow)

3.1 Basic Pattern

Numbered steps with tree branches for sub-steps:

1. LOAD configuration file

2. SORT tasks by priority (low -> high)

3. FOR EACH task (sorted):
   │
   ├── EXECUTE task
   │
   └── IF task.hasCallback AND task.succeeded:
       │
       └── IF callback.isAsync:
           │
           └── QUEUE callback for later

4. PROCESS callbacks:
   │
   ├── IF pending_callbacks.length > 0:
   │   │
   │   └── RUN each callback
   │
   └── IF errors.length > 0:
       │
       └── LOG errors to file

3.2 Key Rules

• │ for vertical continuation
• ├── for branch with more siblings below
• └── for last branch (no more siblings)
• Indent nested levels by 4 spaces
• One empty line between major steps
• Sub-branches connect without empty lines

3.3 Continue │ When More Siblings Follow

CORRECT
├── Child with nested content
│   │
│   └── Nested item
│
└── Last sibling

---

Rule 4: Flow Diagrams

4.1 Vertical Flow with Boxes

Each step gets a box. Use │ and ▼ between boxes:

┌───────────────────────┐
│                       │
│  processRequest()     │
│                       │
└───────────────────────┘
           │
           │
           ▼
┌───────────────────────┐
│                       │
│  validateInput        │
│                       │
└───────────────────────┘
           │
           │
           ▼
┌───────────────────────┐
│                       │
│  needsAuth?           │
│                       │
└───────────────────────┘

4.2 Branching Decisions

Use side branches with YES/NO labels and return lines:

┌───────────────────────┐
│                       │ YES
│  needsAuth?           │──▶───────────┐
│                       │              │
└───────────────────────┘              │
           │                           │
           │ NO                        │
           │                           │
           ▼                           │
┌───────────────────────┐              │
│                       │              │
│  Apply rate limits    │              │
│                       │              │
└───────────────────────┘              │
           │                           │
           │                           │
           ▼                           ▼
┌───────────────────────┐     ┌────────┴──────────┐
│                       │ YES │                   │
│  cache.isValid?       │──▶──┤  returnCached()   │──▶─┐
│                       │     │                   │    │
│                       │     └───────────────────┘    │
└───────────────────────┘                              │
           │                                           │
           │ NO                                        │
           │                                           │
           ▼                                           │

4.3 Return Lines

Use < for return flow:

           │                                           │
           │ ◀─────────────────────────────────────────┘
           │
           ▼
┌──────────────────────┐
│                      │
│  DONE                │
│                      │
└──────────────────────┘

---

Rule 5: Graphics vs Text

5.1 Graphics (Pixel Art) - Compact

When content is visual/graphical, NO empty lines between rows:

┌────────────────────────┐
│░░░░░░░░░░░░░░░░░░░░░░░░│
│░░░░░░░░░░░░░░░░░░░░░░░░│
│░░░░░░░░░░░░░░░░░░░░░░░░│
│░░░░░░████░░░░░░░░░░░░░░│
│░░░░░░████░░░░░░░░░░░░░░│
│░░░░░░████░░░░░░░░░░░░░░│
│░░░░░░░░░░░░░░░░░░░░░░░░│
└────────────────────────┘

5.2 Visual Character Choices

█ = Full block (solid, primary)
▓ = Dark shade (highlighted)
▒ = Medium shade
░ = Light shade (background, secondary)
  = Empty/cleared area

---

Rule 6: Special Box Formats

6.1 Note Box with Label

┌────────┬───────────────────────────────────────────────────┐
│        │  Cache is NOT invalidated during                  │
│  NOTE  │  batch operations!                                │
│        │  Results may be stale until refresh.              │
└────────┴───────────────────────────────────────────────────┘

6.2 Info Box with Tree Inside

┌─────────────────────────────────────────────────────────┐
│                                                         │
│  Step N: Received event                                 │
│    │                                                    │
│    │                                                    │
│    └── QUEUE change (don't apply yet)                   │
│                                                         │
│        pendingChanges = {                               │
│            toRemove: previousItem,                      │
│            toAdd: newItem                               │
│        }                                                │
│                                                         │
└─────────────────────────────────────────────────────────┘

---

Rule 7: Labeled Sections

7.1 Compact Within, Space Between

PROBLEM:
 
┌─────────────────────────────────────────────────────────┐
│  Modifying collection DURING iteration loop             │
│  causes ConcurrentModificationException                 │
│  -> collect changes, apply after loop ends              │
└─────────────────────────────────────────────────────────┘


SOLUTION:
 
┌─────────────────────────────────────────────────────────┐
│  ...content...                                          │
└─────────────────────────────────────────────────────────┘

Rules:

• One empty line after label (before box)
• Two empty lines between sections
• Content inside boxes is compact (no internal empty lines unless for visual grouping)

---

Rule 8: No Tree Characters Inside Box Content Lines

CRITICAL: Tree characters cause visual misalignment on GitHub

NEVER use ├──, └──, or │ as tree connectors mixed with text inside box content lines. These characters render with inconsistent visual width in GitHub's monospace font, causing columns to misalign even when character counts match.

WRONG (tree chars mixed with text inside box)
┌───────────────────────────────────────────┐
│  Server (localhost:8899)                  │
│  ├── Qwen3.5-4B-MLX-8bit                 │
│  ├── TurboQuant KV cache                 │
│  └── Tool calling                        │
└───────────────────────────────────────────┘

CORRECT (nested box with separators)
┌───────────────────────────────────────────┐
│  ┌───────────────────────────────────┐    │
│  │  Server (localhost:8899)          │    │
│  │  Qwen3.5-4B-MLX-8bit             │    │
│  │  TurboQuant KV cache             │    │
│  │  Tool calling                    │    │
│  └───────────────────────────────────┘    │
└───────────────────────────────────────────┘

CORRECT (plain indented text, no tree chars)
┌───────────────────────────────────────────┐
│  Server (localhost:8899)                  │
│    Qwen3.5-4B-MLX-8bit                   │
│    TurboQuant KV cache                   │
│    Tool calling                          │
└───────────────────────────────────────────┘

CORRECT (bullet lists)
┌───────────────────────────────────────────┐
│  Server (localhost:8899)                  │
│  - Qwen3.5-4B-MLX-8bit                   │
│  - TurboQuant KV cache                   │
│  - Tool calling                          │
└───────────────────────────────────────────┘

Exception: Tree characters ARE fine in standalone trees (Rule 3) that are NOT inside a │...│ box border. They are also fine in Rule 6.2 (Info Box with Tree Inside) when the tree connectors are on their own lines with only │ spacers, not mixed with descriptive text.

---

Rule 9: Character Count Verification (Mandatory Bash Check)

CRITICAL: Verify Every Box With Bash

After generating ANY box diagram, you MUST run the verification command below before presenting it to the user. Do NOT rely on visual counting — LLMs consistently miscount characters. Use real tooling instead.

Step 1: Generate the diagram normally

Write the diagram as you normally would following Rules 1-8.

Step 2: Verify with a REAL character count (NOT bytes)

CRITICAL: you MUST count REAL Unicode characters, never bytes. Unicode chars like ─ │ ┌ ┐ └ ┘ ├ ┤ ──▶ ◀── take multiple bytes but ONE visual column. Counting bytes gives false mismatches and leads to breaking correctly-aligned boxes.

DO NOT use these (they count bytes, not characters):

• wc -c — counts bytes
• awk '{print length}' — counts bytes on most systems
• ${#var} in bash without LC_ALL=en_US.UTF-8 and locale-aware tooling

USE ONE of these (real character counting):

Option A — wc -m (bash, simplest):

echo '┌─────────────────────────┐
│  your content here      │
│  more content           │
└─────────────────────────┘' | while IFS= read -r line; do printf "%d: %s\n" "$(echo -n "$line" | wc -m)" "$line"; done

Option B — Python (MOST RELIABLE, use when in doubt):

python3 -c "
import sys
for ln in sys.stdin:
    ln = ln.rstrip('\n')
    print(f'{len(ln):3d}: {ln}')
" <<'EOF'
┌─────────────────────────┐
│  your content here      │
│  more content           │
└─────────────────────────┘
EOF

Or directly on a file range:

python3 -c "
with open('/path/to/file.md') as f:
    for i, ln in enumerate(f.readlines()[START:END], START+1):
        ln = ln.rstrip('\n')
        print(f'L{i} chars={len(ln):3d} |{ln}|')"

All lines of a box MUST show the same number. Example output:

27: ┌─────────────────────────┐
27: │  your content here      │
27: │  more content           │
27: └─────────────────────────┘

Step 3: Fix if numbers differ

If any line shows a different count:

27: ┌─────────────────────────┐
27: │  your content here      │
28: │  more content            │   ← 28 ≠ 27, extra space
27: └─────────────────────────┘

• Add or remove spaces before the right │ to match the target width
• Re-run the verification command
• Repeat until ALL lines show the same number

Notes

• Always count REAL characters, never bytes. wc -c, awk '{print length}', and ${#var} (without proper locale) count bytes and will give you wrong results on Unicode diagrams.
• Use wc -m (bash) or len() in Python — both count Unicode characters correctly.
• Each █ ░ ▒ ▓ ─ │ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ▼ ▲ ◀ ▶ counts as 1 character.
• Multi-byte arrows like ──▶ count as 3 characters (two ─ + one ▶), not 5 or 6 bytes.
• This check costs one tool call but eliminates all retry loops.

---

Rule 10: Character Reference

Box Drawing — ALWAYS use Unicode box-drawing characters

NEVER use +, -, | for box borders. Always use Unicode box-drawing:

Corners:  ┌ ┐ └ ┘
Lines:    ─ │
T-joins:  ┬ ┴ ├ ┤
Cross:    ┼
Double:   ═ ║ ╔ ╗ ╚ ╝ ╠ ╣ ╦ ╩ ╬

Example:

┌───────────────────────┐
│  Content here         │
├───────────────────────┤
│  More content         │
└───────────────────────┘

Shade Blocks (for grids, heatmaps, coverage diagrams)

░ = Light shade (partial, secondary)
▒ = Medium shade
▓ = Dark shade
█ = Full block (solid, primary)
  = Empty (space)

Arrows

Down:   ▼ (or v in text flow)
Up:     ▲ (or ^ in text flow)
Left:   ◀ (or <)
Right:  ▶ (or >)
Flow:   → ← (in text)
Branch: ──▶── (horizontal connector)

Bullets and Symbols

Bullets:  - * 
Check:    [x] [ ]

---

Quick Reference

TITLE WITH UNDERLINE
____________________


1. Step one

2. Step two:
   │
   ├── Sub-step A
   │
   └── Sub-step B


┌───────────────────────┐
│                       │
│  Box content          │
│  More content         │
│                       │
└───────────────────────┘


┌────────┬──────────────┐
│  LABEL │  Content     │
└────────┴──────────────┘


           │
           │
           ▼
┌───────────────────────┐
│  Next step            │
└───────────────────────┘
           │
           │ ◀──────────┐ (return line)
           │
           ▼