catrender-box

Render Box

Purpose

Render boxes, tables, and bordered displays with proper emoji-aware alignment. LLMs cannot reliably calculate character-level padding for Unicode text (see M142), so this skill delegates width calculation to bash scripts that use Python's unicodedata module.

When to Use

MANDATORY when rendering any bordered output containing emojis:

• Status boxes with emoji indicators (✅, ⚠, 🔄)
• Tables with emoji columns
• Checkpoint displays
• Progress displays with emoji prefixes

Not needed for:

• Plain markdown tables without emojis
• Unbordered lists with emojis
• Simple text output

Prerequisites

The box rendering library is located in the plugin:

• ${CLAUDE_PLUGIN_ROOT}/scripts/lib/box.sh - Core rendering functions
• ${CLAUDE_PLUGIN_ROOT}/scripts/pad-box-lines.sh - Line padding with emoji widths
• ${CLAUDE_PLUGIN_ROOT}/emoji-widths.json - Terminal-specific emoji width data

Box Types

1. Simple Box

For status displays, checkpoints, and messages.

source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/box.sh"

box_init 72  # Set box width (default 74)
box_top "✅ CHECKPOINT: Task Complete"
box_empty
box_line "  Task: fix-subagent-token-measurement"
box_line "  Status: Complete"
box_empty
box_divider
box_line "  Tokens: 45,000 (22% of context)"
box_empty
box_bottom

Output:

╭─── ✅ CHECKPOINT: Task Complete ──────────────────────────────────╮
│                                                                    │
│  Task: fix-subagent-token-measurement                              │
│  Status: Complete                                                  │
│                                                                    │
├────────────────────────────────────────────────────────────────────┤
│  Tokens: 45,000 (22% of context)                                   │
│                                                                    │
╰────────────────────────────────────────────────────────────────────╯

2. Table with Headers

For data with multiple columns. Build rows as TSV, then render with column alignment. Use rounded corners for consistency with box displays.

source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/box.sh"

# Define column widths (adjust based on content)
COL1_W=17  # Type
COL2_W=32  # Description
COL3_W=8   # Tokens
COL4_W=15  # Context
COL5_W=10  # Duration

# Helper to pad cell content
pad_cell() {
    local content="$1"
    local width="$2"
    local display_w=$(display_width "$content")
    local padding=$((width - display_w))
    printf '%s%*s' "$content" "$padding" ""
}

# Render header (rounded top corners)
echo "╭$(dashes $COL1_W)┬$(dashes $COL2_W)┬$(dashes $COL3_W)┬$(dashes $COL4_W)┬$(dashes $COL5_W)╮"
echo "│$(pad_cell " Type" $COL1_W)│$(pad_cell " Description" $COL2_W)│$(pad_cell " Tokens" $COL3_W)│$(pad_cell " Context" $COL4_W)│$(pad_cell " Duration" $COL5_W)│"
echo "├$(dashes $COL1_W)┼$(dashes $COL2_W)┼$(dashes $COL3_W)┼$(dashes $COL4_W)┼$(dashes $COL5_W)┤"

# Render data rows
echo "│$(pad_cell " Explore" $COL1_W)│$(pad_cell " Explore codebase" $COL2_W)│$(pad_cell " 68.4k" $COL3_W)│$(pad_cell " 34% ✓ OK" $COL4_W)│$(pad_cell " 1m 7s" $COL5_W)│"
echo "│$(pad_cell " general-purpose" $COL1_W)│$(pad_cell " Implement refactor" $COL2_W)│$(pad_cell " 170.0k" $COL3_W)│$(pad_cell " 85% ⚠ EXCEEDED" $COL4_W)│$(pad_cell " 3m 12s" $COL5_W)│"

# Render footer (rounded bottom corners)
echo "╰$(dashes $COL1_W)┴$(dashes $COL2_W)┴$(dashes $COL3_W)┴$(dashes $COL4_W)┴$(dashes $COL5_W)╯"

Output:

╭─────────────────┬────────────────────────────────┬────────┬───────────────┬──────────╮
│ Type            │ Description                    │ Tokens │ Context       │ Duration │
├─────────────────┼────────────────────────────────┼────────┼───────────────┼──────────┤
│ Explore         │ Explore codebase               │ 68.4k  │ 34% ✓ OK      │ 1m 7s    │
│ general-purpose │ Implement refactor             │ 170.0k │ 85% ⚠ EXCEEDED│ 3m 12s   │
╰─────────────────┴────────────────────────────────┴────────┴───────────────┴──────────╯

3. Nested Box

For hierarchical displays like project status.

source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/box.sh"

box_init 72
box_top "🗺️ PROJECT STATUS"
box_empty

# Use inner_* functions for nested boxes
inner_top "📦 v1.0: Initial Release"
inner_line "☑️ v1.1: Core features (5/5)"
inner_line "🔄 **v1.2: Current** (3/5)"
inner_line "   🔳 pending-task-1"
inner_line "   🔳 pending-task-2"
inner_bottom

box_empty
box_bottom

Key Functions

Box-Drawing Characters

Note: Use rounded corners (╭╮╰╯) for all boxes and tables for visual consistency. Square corners (┌┐└┘) are deprecated.

Anti-Patterns

Never calculate padding manually

# ❌ WRONG - LLMs cannot reliably calculate emoji widths
printf "│ %-20s │\n" "✅ Task complete"

# ✅ CORRECT - Use display_width function
source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/box.sh"
box_line "  ✅ Task complete"

Never use markdown tables with emojis

<!-- ❌ WRONG - Emojis break column alignment -->
| Status | Task |
|--------|------|
| ✅ | Complete |
| ⚠ | Warning |

Use box-drawing tables instead (see Table with Headers above).

Never hardcode emoji widths

# ❌ WRONG - Emoji widths vary by terminal
EMOJI_WIDTH=2

# ✅ CORRECT - Use display_width function
WIDTH=$(display_width "✅")

Related Skills

• cat:token-report - Uses render-box for subagent token tables
• cat:status - Uses render-box for project status display
• cat:shrink-doc - Uses render-box for validation tables

Related References

• display-standards.md - Visual formatting guidelines
• M142 - Learning about LLM padding calculation limitations