gh-cskiro-claudex/skills/planning/ascii-diagram-creator/reference/best-practices.md

Best Practices

Guidelines for creating clear, effective ASCII diagrams.

Formatting Rules

Width Constraints

Maximum line width: 80 characters

This ensures compatibility with:

• Terminal windows
• Code review tools
• Markdown rendering
• Email clients

# Good - fits in 80 chars
┌──────────────────────────────────────────────────────────────────────────┐

# Bad - exceeds 80 chars, will wrap
┌────────────────────────────────────────────────────────────────────────────────────┐

Alignment

Vertical alignment creates visual hierarchy:

# Good - aligned centers
┌─────────┐
│ Step 1  │
└─────────┘
     │
     ▼
┌─────────┐
│ Step 2  │
└─────────┘

# Bad - misaligned
┌─────────┐
│ Step 1  │
└─────────┘
        │
        ▼
   ┌─────────┐
   │ Step 2  │
   └─────────┘

Horizontal alignment for side-by-side comparisons:

# Good - columns aligned
BEFORE:                    AFTER:
├── file1.js        ──►    ├── file1.ts
└── file2.js        ──►    └── file2.ts

# Bad - uneven columns
BEFORE:          AFTER:
├── file1.js ──► ├── file1.ts
└── file2.js   ──►   └── file2.ts

Spacing

Use blank lines to separate logical sections:

┌─────────────────────────────────────────────┐
│           MIGRATION PLAN                     │
└─────────────────────────────────────────────┘

PHASE 1: Analysis
┌──────────────────┐
│ Analyze current  │
└──────────────────┘

PHASE 2: Migration
┌──────────────────┐
│ Execute changes  │
└──────────────────┘

Clarity Guidelines

Use Consistent Box Sizes

Keep related boxes the same width:

# Good - consistent widths
┌──────────────────┐    ┌──────────────────┐
│ Component A      │    │ Component B      │
└──────────────────┘    └──────────────────┘

# Bad - inconsistent
┌────────┐    ┌────────────────────────┐
│ Comp A │    │ Component B            │
└────────┘    └────────────────────────┘

Include Legends

When using symbols, explain them:

┌──────────────────┐
│ ✓ Database       │
│ ⏳ API           │
│ ✗ Legacy         │
└──────────────────┘

Legend:
✓ = Complete
⏳ = In Progress
✗ = Removed

Group Related Items

Use visual proximity to show relationships:

┌─────────────────────────────────────────┐
│          FRONTEND LAYER                  │
├─────────────────────────────────────────┤
│ • React Components                       │
│ • State Management                       │
│ • Routing                                │
└─────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────┐
│          BACKEND LAYER                   │
├─────────────────────────────────────────┤
│ • API Endpoints                          │
│ • Business Logic                         │
│ • Database Access                        │
└─────────────────────────────────────────┘

Information Density

Include Status Indicators

Show progress at a glance:

│ ✓ Step 1: Setup          │
│ ✓ Step 2: Configuration  │
│ ⏳ Step 3: Migration     │
│   Step 4: Validation     │

Show Counts When Relevant

Provide context with numbers:

┌──────────────────┐
│ Current State    │
│ 11 directories   │
│ 47 files         │
│ 3 duplicates     │
└──────────────────┘

Add Brief Descriptions

Clarify purpose without cluttering:

┌──────────────────┐
│ Auth Service     │──► Handles JWT tokens
│ 3 endpoints      │──► Login, logout, refresh
└──────────────────┘

Common Mistakes to Avoid

Mistake	Problem	Solution
Exceeding 80 chars	Wrapping breaks diagram	Split or abbreviate
No legend	Symbols are confusing	Always include legend
Inconsistent boxes	Looks unprofessional	Standardize widths
Too much detail	Overwhelming	Simplify or split
No spacing	Hard to read	Add blank lines
Misaligned arrows	Confusing flow	Check alignment