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.

<!-- ascii-lint-disable: single-set,single-arrow-style,density-min -->

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.

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

When to Use Each Pattern

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

Contributing to ascii-visualizer

Governance for the ASCII design system: char-sets, primitives, status glyph vocabulary, lint rules, render patterns. See designs/ascii-design-system.md for the full design.

Principles (locked)

• Anti-slop: encode information into structure, not decoration. Every

glyph in primitives.json must answer "what does this communicate?" — decoration alone is grounds for rejection.

• Two tiers, not three: primitives.json (raw Unicode, frozen) →

tokens.json (semantic char-sets). No component-tier tokens.

• Intent naming: char-set names describe USE, not APPEARANCE

(default/emphasis/title/soft/portable — not light/heavy).

• Closed-set vocab: the status glyph vocabulary in

rules/status-glyph-vocabulary.md is closed at v1. Additions are MINOR bumps via the process below.

Adding a glyph (status vocabulary or primitive)

1. Open an issue tagged glyph-proposal with:

• The glyph itself (and its Unicode code point, e.g. U+2713)
• Proposed semantic (status.check → "passed / completed")
• Collision check vs the existing 11 status glyphs (or 80+ primitives)
• Terminal-render screenshot (iTerm + VS Code minimum)
• One real OrchestKit usage that needs it

2. ascii-visualizer skill owner reviews; one design-system-architect reviewer signs off; one Phase-1 user must voice support. 3. Append to primitives.json (never reorder existing entries). 4. If status glyph: append to rules/status-glyph-vocabulary.md. 5. Bump tokens.json version 1.x.y → 1.x+1.0 (MINOR; additive). 6. Add a snapshot golden under tests/fixtures/ascii/golden/. 7. CHANGELOG entry under ### Design tokens.

Removing or repurposing a glyph = MAJOR bump; see Versioning below.

Adding a char-set

Threshold is high. A new set must express a distinct intent, not a new visual style. Reviewers will reject sets that overlap the existing five.

1. Same issue process as above, tagged char-set-proposal. 2. State the intent in 1 sentence; map it to scenarios where existing sets are wrong (not just suboptimal). 3. Update primitives.json (if new code points needed) AND tokens.json (the semantic alias). 4. Update tokens.schema.json properties.sets.required to include the new name. 5. Run scripts/validate-tokens.sh and npm run test:ascii. 6. Bump tokens.json MINOR.

Adding a render pattern (scripts/render-ascii.sh)

1. Implement the pattern function; follow the existing render_box style. 2. Add to the case "$PATTERN" dispatch. 3. Add 5 goldens (one per char-set) under tests/fixtures/ascii/golden/<pattern>-<set>.golden.txt. 4. Run UPDATE_SNAPSHOTS=1 bash tests/unit/test-ascii-snapshots.sh once, review the diff, commit. 5. No version bump needed — patterns are renderer features, not tokens.

Adding a lint rule (src/hooks/src/quality/ascii-lint.ts)

1. Decide classification: NORMATIVE (correctness) vs ADVISORY (taste). See designs/ascii-design-system.md §A.3. 2. Default severity = warn (D3 locked). Only NORMATIVE rules are eligible to ratchet to block in a future PR after 30d of data. 3. Provide a per-rule disable comment (// ascii-lint-disable: <name>). 4. Add a unit test fixture in tests/fixtures/ascii/ covering both pass and fail cases. 5. Update the lint table in designs/ascii-design-system.md §A.3.

Versioning

tokens.json carries semver MAJOR.MINOR.PATCH:

MAJOR releases ship as vN-rc (both names accepted, old name warns) for at least one MINOR cycle before removal.

Validators

scripts/validate-tokens.sh                 # schema + primitives membership
bash tests/unit/test-ascii-snapshots.sh    # golden diff (when implemented)
bash tests/unit/test-ascii-tokens.sh       # token-set usage in src/
bash tests/unit/test-ascii-density.sh      # info/decoration ratio
bash tests/unit/test-ascii-i18n.sh         # CJK/Devanagari alignment

All four (when shipped in C3) wired into tests/run-all-tests.sh under the unit-test block.

Rule Categories

1. ASCII Diagrams (ascii) — MEDIUM — 2 rules

Box-drawing characters, layout patterns, and structured diagram templates for terminal output.

2. Status Glyph Vocabulary (semantics) — HIGH — 1 rule

Closed-set semantic vocabulary for status indicators across skills, hooks, monitors, and rendered output.

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

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

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