OpenParable
Skip to content
← Back to skills

Cat:render Box

Design
cat:render-box

Cat:render Box is an Agent Skill for design published in the cowwoc/cat repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Render boxes and tables with proper emoji-aware alignment using box-drawing characters

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/cowwoc/cat/blob/HEAD/skills/render-box/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/cat-render-box, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

FunctionPurpose
box_init WIDTHInitialize box width (default 74)
box_top "TITLE"Top border with optional title
box_bottomBottom border
box_line "CONTENT"Content line with borders
box_emptyEmpty line with borders
box_dividerHorizontal divider
display_width "TEXT"Calculate emoji-aware display width
pad "TEXT" WIDTHPad text to exact display width
dashes COUNTGenerate COUNT dash characters
inner_top "TITLE"Nested box top border
inner_line "CONTENT"Nested box content line
inner_bottomNested box bottom border
progress_bar PCT [WIDTH]Generate progress bar string

Box-Drawing Characters

CharacterNameUsage
─HorizontalBorders, dividers
│VerticalSide borders, column separators
╭ ╮Rounded topTop corners (ALL boxes and tables)
╰ ╯Rounded bottomBottom corners (ALL boxes and tables)
├ ┤T-junctionRow dividers
┬ ┴T-junctionColumn headers/footers
┼CrossGrid intersections
█ ░BlockProgress bars

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