pi-tui-design

Files (2)

• SKILL.md
• examples.md · references/

SKILL.md (first lines)

# TUI Design for Pi

Build terminal interfaces that feel *crafted*, not generated.

## Reference Sources — Read These First

```bash
PI=$(npm root -g)/@earendil-works/pi-coding-agent

# Full TUI API (component interfaces, key identifiers, rendering rules)
cat "$PI/docs/tui.md"

# Copy-paste implementations for every pattern
# (load this file when you need working code to start from)
```

Read [references/examples.md](references/examples.md) for copy-paste implementations of:
Selection Dialog · Status+Widget · Loader with Cancel · Settings Toggles · Custom Tool Rendering · Custom Footer · Vim Modal Editor

```bash
# Real-world source references (ground truth):
cat "$PI/examples/extensions/preset.ts"           # SelectList + DynamicBorder
cat "$PI/examples/extensions/todo.ts"             # renderCall / renderResult
cat "$PI/examples/extensions/plan-mode/index.ts"  # setStatus + setWidget
cat "$PI/examples/extensions/custom-footer.ts"    # setFooter reactive
cat "$PI/examples/extensions/modal-editor.ts"     # CustomEditor vim-mode
cat "$PI/examples/extensions/snake.ts"            # full game loop
cat "$PI/examples/extensions/space-invaders.ts"   # wantsKeyRelease (Kitty)
cat "$PI/examples/extensions/overlay-qa-tests.ts" # all 9 anchors + animation
```

---

## Design Thinking

Before coding, commit to a direction:

- **Tone**: Minimal and precise? Dense and information-rich? Playful? Industrial? The terminal has its own aesthetic vocabulary — box-drawing elegance, braille-pattern density, block-element weight, symbol clarity.
- **Scope**: Full-screen takeover? Floating overlay? Persistent widget? Status line? Tool rendering? Match the delivery surface to the interaction weight.
- **Differentiation**: What detail makes this feel intentional? A progress bar with braille resolution. Aligned columns with accent headers. A dialog with breathing room.

## Terminal Aesthetic Vocabulary

| Category | Characters | Use |
|----------|-----------|-----|
| Box-drawing (light) | `─│┌┐└┘├┤┬┴┼` | Standard borders, tables |
| Box-drawing (rounded) | `╭╮╰╯` | Softer, modern feel |
| Box-drawing (heavy) | `━┃┏┓┗┛┣┫┳┻╋` | Emphasis, headers |
| Box-drawing (double) | `═║╔╗╚╝╠╣╦╩╬` | Formal, structured |
| Block elements | `█▓▒░▀▄▌▐` | Progress bars, density, fill |
| Braille | `⠀–⣿` | Sparklines, high-res patterns, spinners |
| Symbols | `◆●○◉✓✗▸▶★` | Status, bullets, selections |

**Weight hierarchy**: `█` → `▓` → `▒` → `░` → ` `. Use for density gradients, not just fill.

**Aspect ratio**: Terminal cells are ~2:1 tall. `██` reads as roughly square — account for this in spatial layouts (`snake.ts` uses `cellWidth = 2`).

## Color Discipline

**Always use theme tokens.** Hardcoded ANSI escapes break on theme change.

```typescript
// ✗ breaks on theme change
`\x1b[31m${text}\x1b[0m`

// ✓ adapts to dark/light/custom
theme.fg("accent", theme.bold("Title"))
theme.fg("success", "✓ OK")
theme.fg("muted",   "secondary info")
```

**Foreground hierarchy** (`theme.fg(color, text)`):
`accent` → primary attention · `text` → body · `muted` → secondary · `dim` → tertiary
`success` / `error` / `warning` → semantic · `border` / `borderAccent` / `borderMuted` → structural
`toolTitle` / `toolOutput` → tool contexts

**Background** (`theme.bg(color, text)`):
`selectedBg` · `toolPendingBg` · `toolSuccessBg` · `toolErrorBg` · `userMessageBg` · `customMessageBg`

**Rule**: one accent dominates. Overusing color flattens the hierarchy — a wall of green is worse than no color.

## Spatial Composition

- Every line from `render()` must not exceed the `width` parameter — use `truncateToWidth()`
- `paddingX=1` is the baseline; headers may use `paddingX=2`
- `Spacer(1)` between sections beats a separator line — let content breathe
- Compose: `Container → Box → children`. Don't flatten into one render function
- Use `visibleWidth()` for ANSI-aware column math, not `str.length`

## Animation

Timer-based via `setInterval` + `tui.requestRender()`. Braille spinner:

```typescript
const frames = ["⠋","⠙","⠹","⠸","⠼","⠴","⠦","⠧","⠇","⠏"];
this.interval = setInterval(() => {
  this.frame = (this.frame + 1) % frames.length;
  this.invalidate();
  tui.requestRender();
}, 80);
```

**Mandatory**: clear intervals in `dispose()`. Leaked timers render after component removal.

## Keyboard Conventions

Standard keys users expect: `↑↓`/`j/k` navigate · `Enter` confirm · `Escape` cancel · `Tab` next field.

Always show hints: `theme.fg("dim", "↑↓ navigate • enter select • esc cancel")`

Use `matchesKey(data, Key.up)` — handles terminal escape sequence differences. See `tui.md` for all `Key.*` identifiers.

## Component Contract

```typescript
interface Component {
  render(width: number): string[];  // each line must not exceed width
  handleInput?(data: string): void;
  wantsKeyRelease?: boolean;        // Kitty key-release events (space-invaders.ts)

From mrclrchtr/supi, MIT.

More from mrclrchtr/supi