TUI Design for Pi

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

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.

// ✗ 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:

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

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)
  invalidate(): void;               // clear render cache; called on theme change
}

Caching — always cache, invalidate on state change:

private cachedWidth?: number;
private cachedLines?: string[];

render(width: number): string[] {
  if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
  // ... compute ...
  this.cachedWidth = width; this.cachedLines = lines;
  return lines;
}
invalidate(): void { this.cachedWidth = undefined; this.cachedLines = undefined; }

Theme invalidation — components that pre-bake theme colors must rebuild on invalidate():

override invalidate(): void {
  super.invalidate();   // clears child caches
  this.rebuild();       // re-applies current theme colors
}

Available Components

For full API (constructor signatures, options, examples) → read tui.md.

From @mariozechner/pi-tui: Text · TruncatedText · Box · Container · Spacer · Markdown · Image · SelectList · SettingsList · Loader · Input · Editor

From @mariozechner/pi-coding-agent: DynamicBorder · BorderedLoader · CustomEditor

Utilities: visibleWidth · truncateToWidth · wrapTextWithAnsi · matchesKey · Key · getMarkdownTheme · getSettingsListTheme · getAgentDir

SelectList, SettingsList, BorderedLoader cover 90% of cases — use them before building from scratch.

Delivery Surfaces

For overlayOptions (anchor, width, minWidth, maxHeight, margin, visible, offsetX/Y) → read tui.md overlays section or see overlay-qa-tests.ts.

ctx.ui.custom factory signature: (tui, theme, keybindings, done) => Component | { render, invalidate, handleInput }

Key Rules

1. Use theme from the callback — not imported directly
2. Type DynamicBorder callback — (s: string) => theme.fg("accent", s), not (s) => ...
3. Call tui.requestRender() after state changes in handleInput
4. Return { render, invalidate, handleInput } or a class with those methods
5. Use existing components — don't rebuild SelectList / SettingsList / BorderedLoader
6. Fresh instances for overlays — overlays are disposed on close; don't reuse references

Config Persistence

Use getAgentDir() for ~/.pi/agent/ — the standard location:

import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { getAgentDir } from "@mariozechner/pi-coding-agent";

const dir = join(getAgentDir(), "extensions", "my-ext");
const file = join(dir, "settings.json");
const defaults = { enabled: true };

function load() { return existsSync(file) ? { ...defaults, ...JSON.parse(readFileSync(file, "utf-8")) } : defaults; }
function save(patch: object) { mkdirSync(dir, { recursive: true }); writeFileSync(file, JSON.stringify({ ...load(), ...patch }, null, 2)); }

Anti-Patterns