---
title: "Ascii Visualizer"
description: "ASCII diagram patterns for architecture, workflows, file trees, and data visualizations. Use when creating terminal-rendered diagrams, box-drawing layouts, progress bars, swimlanes, or blast radius visualizations."
---

<span className="badge badge-gray">Reference</span> <span className="badge badge-green">low</span>

> **Auto-activated** — this skill loads automatically when Claude detects matching context.

<ContextualSkillSidebar slug="ascii-visualizer" />


# ASCII Visualizer

Consistent, readable ASCII diagrams for architecture, workflows, file trees, and data visualizations. All output renders correctly in monospace terminals without external tools.

**Core principle:** Encode information into structure, not decoration. Every diagram element should communicate something meaningful.


## Box-Drawing Character Reference

This block intentionally shows multiple sets together as a key. Authors
should use ONE set per real diagram; the `single-set` lint rule enforces
this on production diagrams.

&lt;!-- ascii-lint-disable: single-set,single-arrow-style,density-min --&gt;
```
default:   ┌─┐ │ └─┘  ├─┤ ┬ ┴ ┼
emphasis:  ┏━┓ ┃ ┗━┛  ┣━┫ ┳ ┻ ╋
title:     ╔═╗ ║ ╚═╝  ╠═╣ ╦ ╩ ╬
soft:      ╭─╮ │ ╰─╯
portable:  +-+ | +-+  +-+ + + +
Arrows:    → ← ↑ ↓ ─> <─ ──> <──
Blocks:    █ ▓ ░ ▏▎▍▌▋▊▉
Status:    ● ○ ✓ ✗ ⚠ ◆ ◇ ▶ ▷  ↑↓→ ▓▒░  (closed-set vocab — see rules)
```

### Set Conventions (D8: intent-driven naming)

Tokens live in `tokens.json`. Names describe USE not APPEARANCE.

| Set | Characters | Use For |
|-----|-----------|---------|
| `default` `─│` | Normal boxes and connectors | Most diagrams |
| `emphasis` `━┃` | Headers, focus, draw the eye | Key components, outer frames |
| `title` `═║` | Document titles | §0-style banners only |
| `soft` `╭╮╰╯ ─│` | Status cards, ambient UI | Diff blocks |
| `portable` `+-\|` | NO_COLOR / CI / bare TTY | Fallback |

Rename codemod (D8): old `light/heavy/double/rounded/ascii-fallback` → new names above. Old names accepted with warning for one minor release.

### Status Glyph Vocabulary

Closed-set v1 of 11 semantic glyphs (`●○✓✗⚠◆◇▶▷ ↑↓→ ▓▒░`). Single source of truth — see `rules/status-glyph-vocabulary.md`. Add-a-glyph process in `CONTRIBUTING.md`.


## Diagram Patterns

### Architecture Diagrams

```
┌──────────────┐      ┌──────────────┐
│   Frontend   │─────>│   Backend    │
│   React 19   │      │   FastAPI    │
└──────────────┘      └───────┬──────┘
                              │
                              v
                      ┌──────────────┐
                      │  PostgreSQL  │
                      └──────────────┘
```

### File Trees with Annotations

```
src/
├── api/
│   ├── routes.py          [M] +45 -12    !! high-traffic path
│   └── schemas.py         [M] +20 -5
├── services/
│   └── billing.py         [A] +180       ** new file
└── tests/
    └── test_billing.py    [A] +120       ** new file

Legend: [A]dd [M]odify [D]elete  !! Risk  ** New
```

### Progress Bars

```
[████████░░] 80% Complete
+ Design    (2 days)
+ Backend   (5 days)
~ Frontend  (3 days)
- Testing   (pending)
```

### Swimlane / Timeline Diagrams

```
Backend  ===[Schema]======[API]===========================[Deploy]====>
                |            |                                ^
                |            +------blocks------+             |
                |                               |             |
Frontend ------[Wait]--------[Components]=======[Integration]=+

=== Active work   --- Blocked/waiting   | Dependency
```

### Blast Radius (Concentric Rings)

```
            Ring 3: Tests (8 files)
       +-------------------------------+
       |    Ring 2: Transitive (5)      |
       |   +------------------------+   |
       |   |  Ring 1: Direct (3)     |   |
       |   |   +--------------+      |   |
       |   |   | CHANGED FILE |      |   |
       |   |   +--------------+      |   |
       |   +------------------------+   |
       +-------------------------------+
```

### Comparison Tables

```
BEFORE                          AFTER
┌────────────┐                  ┌────────────┐
│  Monolith  │                  │  Service A │──┐
│  (all-in-1)│                  └────────────┘  │  ┌──────────┐
└────────────┘                  ┌────────────┐  ├─>│  Shared  │
                                │  Service B │──┘  │  Queue   │
                                └────────────┘     └──────────┘
```

### Reversibility Timeline

```
Phase 1  [================]  FULLY REVERSIBLE    (add column)
Phase 2  [================]  FULLY REVERSIBLE    (new endpoint)
Phase 3  [============....]  PARTIALLY           (backfill)
              --- POINT OF NO RETURN ---
Phase 4  [........????????]  IRREVERSIBLE        (drop column)
```


## Key Rules

| Rule | Description |
|------|-------------|
| Font | Always monospace — box-drawing requires fixed-width |
| Weight | Standard for normal, Heavy for emphasis, Double for titles |
| Arrows | `─>`, `──>`, or `│` with `v`/`^` for direction |
| Alignment | Right-pad labels to match column widths |
| Annotations | `!!` for risk, `**` for new, `[A/M/D]` for change type |
| Width | Keep under 80 chars for terminal compatibility |
| Nesting | Max 3 levels of box nesting before readability degrades |


## When to Use Each Pattern

| Pattern | Use Case |
|---------|----------|
| Layered boxes | System architecture, deployment topology |
| Concentric rings | Blast radius, impact analysis |
| Timeline bars | Reversibility, migration phases |
| Swimlanes | Execution order, parallel work streams |
| Annotated trees | File change manifests, directory structures |
| Comparison tables | Cross-layer consistency, before/after |
| Progress bars | Status tracking, completion metrics |

## Related Skills

- `brainstorm` — Design exploration where diagrams communicate ideas
- `architecture-patterns` — System architecture that benefits from ASCII diagrams
- `code-review-playbook` — Review comments with inline diagrams


---

## Rules (3)

### Create structured ASCII architecture diagrams to communicate system design without external tools — MEDIUM


## ASCII Architecture Visualization Patterns

**Incorrect — flat text descriptions:**
```
The system has a frontend that talks to a backend API which uses
a database and a cache layer. There's also a message queue for
async processing.
```

**Correct — layered architecture diagram:**
```
┌─────────────────────────────────────────────────────┐
│                    Load Balancer                      │
└──────────┬──────────────────────────┬────────────────┘
           │                          │
┌──────────v──────────┐  ┌───────────v────────────┐
│   API Gateway       │  │   API Gateway          │
│   (instance 1)      │  │   (instance 2)         │
└──────────┬──────────┘  └───────────┬────────────┘
           │                          │
           └──────────┬───────────────┘
                      │
        ┌─────────────┼────────────────┐
        │             │                │
┌───────v──────┐ ┌────v─────┐ ┌───────v──────┐
│  PostgreSQL  │ │  Redis   │ │  RabbitMQ    │
│  (primary)   │ │  (cache) │ │  (queue)     │
└──────────────┘ └──────────┘ └──────────────┘
```

### Blast Radius Visualization

```
                Ring 3: Tests (8 files)
           +-------------------------------+
           |    Ring 2: Transitive (5)      |
           |   +------------------------+   |
           |   |  Ring 1: Direct (3)     |   |
           |   |   +--------------+      |   |
           |   |   | CHANGED FILE |      |   |
           |   |   +--------------+      |   |
           |   +------------------------+   |
           +-------------------------------+

Direct dependents:   auth.py, routes.py, middleware.py
Transitive:          app.py, config.py, utils.py, cli.py, server.py
```

### Reversibility Timeline

```
REVERSIBILITY TIMELINE
Phase 1  [================]  FULLY REVERSIBLE    (add column, nullable)
Phase 2  [================]  FULLY REVERSIBLE    (new endpoint, additive)
Phase 3  [============....]  PARTIALLY           (backfill data)
              --- POINT OF NO RETURN ---
Phase 4  [........????????]  IRREVERSIBLE        (drop old column)
Phase 5  [================]  FULLY REVERSIBLE    (frontend toggle)
```

### Comparison Tables

```
CROSS-LAYER CONSISTENCY
Backend Endpoint          Frontend Consumer     Status
POST /invoices            createInvoice()       PLANNED
GET  /invoices/:id        useInvoice(id)        PLANNED
GET  /invoices            InvoiceList.tsx        MISSING  !!
```

### Key Patterns

| Pattern | Use Case |
|---------|----------|
| Layered boxes | System architecture, deployment topology |
| Concentric rings | Blast radius, impact analysis |
| Timeline bars | Reversibility, migration phases |
| Swimlanes | Execution order, parallel work streams |
| Annotated trees | File change manifests, directory structures |
| Comparison tables | Cross-layer consistency, before/after |


### Use consistent box-drawing characters and formatting for correct terminal rendering — MEDIUM


## ASCII Diagram Fundamentals

**Incorrect — inconsistent characters and alignment:**
```
+-------+    +-------+
| Frontend | -> | Backend |
+-------+    +-------+
              |
          +--------+
          | Database |
          +--------+
```

**Correct — proper box-drawing characters with alignment:**
```
Box-Drawing Characters:
┌─┐│└─┘  Standard weight
┏━┓┃┗━┛  Heavy weight
├─┤┬┴    Connectors
╔═╗║╚═╝  Double lines
```

```
┌──────────────┐      ┌──────────────┐
│   Frontend   │─────>│   Backend    │
│   React 19   │      │   FastAPI    │
└──────────────┘      └───────┬──────┘
                              │
                              v
                      ┌──────────────┐
                      │  PostgreSQL  │
                      └──────────────┘
```

### Progress Tracking

```
[████████░░] 80% Complete
+ Design    (2 days)
+ Backend   (5 days)
~ Frontend  (3 days)
- Testing   (pending)
```

### File Trees

```
src/
├── api/
│   ├── routes.py          [M] +45 -12    !! high-traffic path
│   └── schemas.py         [M] +20 -5
├── services/
│   └── billing.py         [A] +180       ** new file
└── tests/
    └── test_billing.py    [A] +120       ** new file

Legend: [A]dd [M]odify [D]elete  !! Risk  ** New
```

### Workflow Diagrams

```
Backend  ===[Schema]======[API]===========================[Deploy]====>
                |            |                                ^
                |            +------blocks------+             |
                |                               |             |
Frontend ------[Wait]--------[Components]=======[Integration]=+

=== Active work   --- Blocked/waiting   | Dependency
```

### Key Rules

| Rule | Description |
|------|-------------|
| Font | Always monospace — box-drawing characters require fixed-width |
| Weight | Standard (─│) for normal, Heavy (━┃) for emphasis |
| Arrows | Use ─>, ──>, or │ with v/^ for direction |
| Alignment | Right-pad labels to match column widths |
| Annotations | Use !! for risk, ** for new, [A/M/D] for change type |


### Use the closed-set status glyph vocabulary for semantic indicators — HIGH


## Closed Status Glyph Vocabulary (v1)

Eleven glyphs, frozen at v1.0.0. Adding a 12th is a MINOR bump via the
process in `CONTRIBUTING.md`. Removing or repurposing any of the 11 is
a MAJOR bump (rare).

### Vocabulary

```
GLYPH   SEMANTIC                    DON'T USE FOR
─────   ────────                    ─────────────
●       active / on / current       generic bullet
○       inactive / off / pending    decoration
✓       passed / completed          decoration
✗       failed / blocked            general "no"
⚠       warning / attention         hard error
◆       primary / focused           random emphasis
◇       secondary / unfocused       decoration
▶       running / in-progress       generic arrow
▷       paused / awaiting input     generic arrow
↑↓→     trend up/down/forward       random direction
▓▒░     fill: high/med/low          decoration
```

### Incorrect — generic decoration

```
* Build passed
> Tests running
- Linter clean
```

### Correct — semantic glyphs

```
✓ Build passed
▶ Tests running
✓ Linter clean
```

### Anti-pattern — repurposing a semantic for decoration

```
✓ Item 1
✓ Item 2
✓ Item 3
```

A list of items isn't passing/failing — `✓` is reserved for pass/completed
states. Use `●` for active items and `○` for inactive/pending ones, or
plain `-` for an unmarked list.

### Anti-pattern — mixing semantically-loaded glyphs with decoration

```
■  Phase 1   ✓  Phase 2   ◉  Phase 3
```

`■` and `◉` are not in the vocabulary — they read as decoration. Pick
exactly one glyph from the table above per slot:

```
✓  Phase 1   ▶  Phase 2   ○  Phase 3
   done       running       pending
```

