chore: add tui-design-system agent skill

Author: elkaix

.agents/skills/tui-design-system/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: tui-design-system
+description: Use when designing or building any terminal user interface — choosing a layout paradigm, keybindings/interaction model, color system, data visualization, or motion. Framework-agnostic universal patterns that work with Ratatui, Ink, Textual, Bubbletea, or any TUI toolkit. For the repo's own pythinker-code TUI, use write-tui instead.
+---
+
+# TUI Design System
+
+Universal design patterns for building exceptional terminal user interfaces. Framework-agnostic — works with Ratatui, Ink, Textual, Bubbletea, or any TUI toolkit.
+
+> For editing **this repo's** terminal UI (`apps/pythinker-code/src/tui`), use the **write-tui** skill instead. This skill is the cross-project design vocabulary.
+
+**Core philosophy:** TUIs earn their power through spatial consistency, keyboard fluency, and information density that respects human attention. Design for the expert's speed without abandoning the beginner's discoverability.
+
+## Design process
+
+```dot
+digraph tui_design {
+    rankdir=TB;
+    "What are you building?" [shape=diamond];
+    "Select layout paradigm" -> "Design interaction model" -> "Define visual system" -> "Validate against anti-patterns" -> "Ship it";
+    "What are you building?" -> "Select layout paradigm";
+    "Ship it" [shape=doublecircle];
+}
+```
+
+1. Pick a **layout paradigm** from what you're building.
+2. Design the **interaction model** (navigation, keybindings, help, dialogs).
+3. Define the **visual system** (color tiers, semantic slots, hierarchy).
+4. Add **data visualization** and **motion** where they earn their place.
+5. **Validate** against the anti-patterns checklist, then ship.
+
+---
+
+## 1. Layout paradigm selector
+
+| App type | Paradigm | Examples |
+|---|---|---|
+| File manager | Miller Columns | yazi, ranger |
+| Git / DevOps tool | Persistent Multi-Panel | lazygit, lazydocker |
+| System monitor | Widget Dashboard | btop, bottom, oxker |
+| Data browser / K8s | Drill-Down Stack | k9s, diskonaut |
+| SQL / HTTP client | IDE Three-Panel | harlequin, posting |
+| Shell augmentation | Overlay / Popup | atuin, fzf |
+| Log / event viewer | Header + Scrollable List | htop, tig |
+
+### Persistent Multi-Panel
+All panels visible simultaneously; focus shifts between them. Users build spatial memory — "branches are always bottom-left."
+
+```
+┌─ Status ──┬─────────── Detail ──────────┐
+├─ Files ───┤                             │
+│ > file.rs │  diff content here...       │
+│   main.rs │                             │
+├─ Branches ┤                             │
+│ * main    │                             │
+│   feat/x  │                             │
+└───────────┴─────────────────────────────┘
+  [q]uit [c]ommit [p]ush [?]help
+```
+**Use for:** multi-faceted tools needing simultaneous context (git clients, container managers, monitoring).
+**Key rule:** panels keep fixed positions across sessions. Never rearrange without user action.
+
+### Miller Columns
+Three-pane past/present/future navigation: parent (left), current (center), preview (right).
+
+```
+┌── Parent ──┬── Current ──┬── Preview ────────┐
+│   ..       │ > config/   │ port: 8080        │
+│   src/     │   lib/      │ host: localhost   │
+│ > config/  │   main.rs   │ log_level: debug  │
+│   tests/   │   mod.rs    │ db_url: postgres  │
+└────────────┴─────────────┴───────────────────┘
+```
+**Use for:** navigating hierarchical data where context above and below matters.
+**Key rule:** selecting in the center shifts everything left; the preview always reflects the highlighted item.
+
+### Drill-Down Stack
+One level at a time; navigation pushes/pops levels like a stack. Breadcrumb shows depth.
+
+```
+ Context > namespace: prod > pods
+┌─────────────────────────────────────────────┐
+│ NAME              READY   STATUS    AGE       │
+│ > api-7f9c        2/2     Running   3d        │
+│   worker-1a2b     1/1     Running   3d        │
+└─────────────────────────────────────────────┘
+ :pods  :deploy  :svc        [Enter] drill [Esc] up
+```
+**Use for:** deep hierarchies where showing all levels at once is impractical (Kubernetes, DB schemas).
+**Key rule:** always show the navigation path as a breadcrumb. Provide a `:resource` command mode for direct jumps.
+
+### Widget Dashboard
+Self-contained widget panels with independent data. All info visible at once; no navigation required.
+
+```
+┌─── CPU ──────────────┬─── Memory ──────────┐
+│ ▁▂▃▅▇█▇▅▃▂▁▂▃▅▇      │ ████████░░ 78%       │
+│ core0: 45% core1: 67%│ 12.4G / 16.0G        │
+├─── Network ──────────┼─── Disk ─────────────┤
+│ ▲ 1.2 MB/s ▼ 340KB/s │ /: 67%  /home: 45%   │
+├─── Processes ────────┴──────────────────────┤
+│ PID   USER  CPU%  MEM%  CMD                  │
+│ 1234  root  23.4  4.5   postgres             │
+└──────────────────────────────────────────────┘
+```
+**Use for:** monitoring, real-time status, dashboards.
+**Key rule:** each widget is self-contained with its own title. Use braille/block characters for density.
+
+### IDE Three-Panel
+Sidebar (left), editor/main (center), detail/output (bottom). Tab bar along top.
+**Use for:** editing-focused tools (SQL clients, HTTP tools, config editors).
+**Key rule:** sidebar toggles with a single key. Center supports tabs. Bottom panel can expand to full height.
+
+### Overlay / Popup
+TUI appears on demand over the shell, disappears after use.
+**Use for:** shell augmentations (history search, file picker, command palette).
+**Key rule:** configurable height; return the selection to the caller; never disrupt scrollback.
+
+### Header + Scrollable List
+Fixed header with meters/stats, scrollable data below, function bar at bottom.
+**Use for:** single-purpose viewers of one stream (process lists, logs, commit history).
+**Key rule:** header and footer stay pinned; only the middle scrolls.
+
+---
+
+## 2. Responsive layout
+
+Terminals resize constantly. Pick a degradation strategy and test it.
+
+| Strategy | Behavior |
+|---|---|
+| Priority collapse | Less important panels hide first below minimum width |
+| Stacking | Panels collapse to title-only bars; the active one expands (zellij pattern) |
+| Breakpoint modes | Switch layout entirely below a threshold (multi-panel → single panel) |
+| Minimum size gate | Show "terminal too small" below a usable minimum |
+
+**Rules:**
+- Define a minimum size (typically **80×24**). Below it, show a resize message.
+- Never crash on resize. Handle SIGWINCH gracefully.
+- Use constraint-based layouts (percentages, min/max, ratios) — not absolute positions.
+- Test at **80×24, 120×40, 200×60**.
+
+---
+
+## 3. Interaction model
+
+### Navigation style by complexity
+
+| App complexity | Recommended model |
+|---|---|
+| Single-purpose, <20 actions | Direct keybinding (every key = action) |
+| Multi-view, complex | Vim-style modes + contextual footer |
+| IDE-like, many features | Command palette + tabs + vim motions |
+| Data browser | Drill-down + fuzzy search + `:` command mode |
+
+### Keyboard design layers
+
+| Layer | Keys | Audience | Always shown? |
+|---|---|---|---|
+| L0 Universal | arrows, Enter, Esc, q | Everyone | Yes (footer) |
+| L1 Vim motions | `hjkl / ? : gg G` | Intermediate | Yes (footer) |
+| L2 Actions | single mnemonics: `d`elete, `c`ommit, `p`ush | Regular | On `?` help |
+| L3 Power | composed commands, macros, custom bindings | Power | Docs only |
+
+**Lingua franca (don't deviate):** `j/k` down/up · `h/l` left/right or collapse/expand · `/` search · `?` help · `:` command mode · `q` quit (or Esc back one level) · `Enter` select/confirm/drill · `Tab` switch focus · `Space` toggle selection · `g/G` top/bottom.
+
+**Never bind:** `Ctrl+C` (interrupt), `Ctrl+Z` (suspend), `Ctrl+\` (quit). They belong to the terminal.
+
+### Focus management
+- Only one widget receives input at a time. `Tab`/`Shift+Tab` cycle focus.
+- Focus indicator: highlighted border, color change, or cursor presence. Unfocused panels are dimmed or use thinner borders.
+- Modal dialogs are focus traps — the background receives no events.
+- Nested focus: the outer container routes events to the focused child.
+
+### Search & filtering
+Universal pattern: press `/`, type, results filter live.
+- `n/N` next/previous match · `Esc` dismiss.
+- Fuzzy by default; `'` prefix for exact. Highlight matched characters. Preview updates for the highlighted result.
+
+### Help — three tiers
+
+| Tier | Trigger | Content | Audience |
+|---|---|---|---|
+| Always visible | Footer bar | 3–5 essential shortcuts | Everyone |
+| On demand | `?` | Full keybindings for current context | Regular |
+| Documentation | `--help` / man page | Complete reference | Power |
+
+Footer format: `[q]uit [/]search [?]help [Tab]focus [Enter]select`. Make it context-sensitive — show only what's actionable right now.
+
+### Dialogs & confirmation
+
+| Severity | Pattern |
+|---|---|
+| Reversible | Just do it; brief status-bar confirmation |
+| Moderate (delete file) | Inline "Press y to confirm" |
+| Severe (drop database) | Modal requiring the resource name typed in |
+| Irreversible batch | `--dry-run` flag + explicit confirmation |
+
+Modals render over a dimmed background. Toasts auto-dismiss in 3–5s. Status-bar messages are vim-style one-liners that auto-fade.
+
+---
+
+## 4. Color design system
+
+### Terminal color tiers — design for graceful degradation
+
+| Tier | Sequence | Colors | Strategy |
+|---|---|---|---|
+| 16 ANSI | `\033[31m` | 16 (relative) | Foundation; terminal theme controls appearance |
+| 256 | `\033[38;5;{n}m` | 256 | Extended; fixed colors may clash with themes |
+| True color | `\033[38;2;{r};{g};{b}m` | 16.7M (absolute) | Full control; needs `COLORTERM=truecolor` |
+
+**Detection order:** `COLORTERM=truecolor|24bit` → true color · `TERM` contains `256color` → 256 · `NO_COLOR` set → no color · else 16 ANSI.
+
+**Golden rule:** the TUI must be usable in 16-color mode. True color *enhances* — it never *creates* the hierarchy.
+
+### Semantic color slots — name by function, not appearance
+
+| Slot | Purpose | Typical dark |
+|---|---|---|
+| `fg.default` | Body text | `#c0caf5` |
+| `fg.muted` | Secondary / metadata | `#565f89` |
+| `fg.emphasis` | Headers, focused | `#e0e0e0` |
+| `bg.base` | Primary background | `#1a1b26` |
+| `bg.surface` | Panel/widget bg | `#24283b` |
+| `bg.overlay` | Popup/dialog bg | `#414868` |
+| `bg.selection` | Selected highlight | `#364a82` |
+| `accent.primary` | Interactive / focus | `#7aa2f7` |
+| `accent.secondary` | Supporting | `#bb9af7` |
+| `status.error` | Errors / deletions | `#f7768e` |
+| `status.warning` | Caution | `#e0af68` |
+| `status.success` | Success / additions | `#9ece6a` |
+| `status.info` | Informational | `#7dcfff` |
+
+**Never hardcode hex in widget code. Always reference a semantic slot.**
+
+### Visual hierarchy techniques
+
+| Technique | Effect | Use for |
+|---|---|---|
+| Bold (SGR 1) | More weight | Headers, labels, active items |
+| Dim (SGR 2) | Less weight | Metadata, timestamps |
+| Italic (SGR 3) | Distinction | Comments, types |
+| Underline (SGR 4) | Actionable | Links, URLs |
+| Reverse (SGR 7) | Swap fg/bg | Selection (always works!) |
+| Strikethrough (SGR 9) | Negation | Deleted/deprecated |
+
+**Recipe:** 80% of content in `fg.default`. Headers `bold + fg.emphasis`. Metadata `dim + fg.muted`. Status in semantic colors. Accents for interactive elements only.
+
+### Background layering
+Create depth without borders by stepping lightness: `bg.base` → `bg.surface` → `bg.overlay`, each ~5–8% lighter in dark themes. The contrast gradient reads as depth and reduces the need for box-drawing.
+
+### Theme architecture & accessibility
+- Base16 pattern: 8 monotones (background↔foreground gradient) + 8 accents. Ship a dark theme by default, at least one light variant, and respect `NO_COLOR`.
+- **WCAG AA:** 4.5:1 for body text, 3:1 for large text / UI elements.
+- **Never use color alone** — pair with symbols (✓ ✗ ▲), text, position, or typography.
+- Color-blind-safe pairs: blue+orange, blue+yellow, black+white. Avoid red vs green as the only signal.
+- Test: monochrome mode, a color-blindness simulator, 3+ terminal emulators, light and dark.
+
+---
+
+## 5. Data visualization
+
+### Character-resolution building blocks
+
+| Element | Characters | Resolution | Use for |
+|---|---|---|---|
+| Full blocks | `█▉▊▋▌▍▎▏` | 8 steps/cell | Progress bars, bar charts |
+| Shade blocks | `░▒▓█` | 4 densities | Heatmaps, density plots |
+| Braille | `⠁⠂…⣿` (U+2800–28FF) | 2×4 dots/cell | High-res line/scatter |
+| Sparkline | `▁▂▃▄▅▆▇█` | 8 heights | Inline mini-charts |
+
+### Common widgets
+
+| Widget | Pattern | Tips |
+|---|---|---|
+| Progress bar | `[████████░░░░] 67%` | Show % + ETA; gradient green→yellow→red by urgency |
+| Sparkline | `▁▂▃▅▇█▇▅▃▂` | Inline time-series in headers/status bars |
+| Gauge | `CPU [██████████░░] 83%` | Label + bar + value; color by threshold |
+| Table | Sortable, zebra stripes | Numbers right, text left; truncate with `…` |
+| Tree | `├── └── │` guides | Indent 2–4/level; expand/collapse with Enter |
+| Diff | green `+`, red `-` | Word-level highlight within changed lines |
+| Log | colored level + ts + msg | TRACE dim · DEBUG cyan · INFO default · WARN yellow · ERROR red · FATAL red+bold |
+
+### Spinners
+
+| Context | Spinner | Interval |
+|---|---|---|
+| Default / modern | braille `⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏` | 80ms |
+| Minimal | `-\|/` | 130ms |
+| Heavy processing | blocks `▖▘▝▗` | 100ms |
+
+Spinners for indeterminate work, progress bars for determinate. Show spinners only after a ~200ms delay so fast operations don't flash.
+
+---
+
+## 6. Animation & motion
+
+Flicker-free rendering, three layers — all required:
+1. **Double buffering** — render to an off-screen buffer, then swap. Never paint directly to the visible screen.
+2. **Diff-based updates** — compute the changed cells and emit only those escape sequences; don't repaint the whole screen each frame.
+3. **Frame budget** — cap at the display rate (15–60 fps is plenty for a TUI). Coalesce rapid state changes into one frame; throttle on resize.
+
+Motion guidelines:
+- Animate to communicate state change (loading, transition, focus move), not for decoration.
+- Keep transitions short (<150ms feel). Anything longer needs a cancel path.
+- Respect reduced-motion preferences and `NO_COLOR`-style restraint — offer a static fallback.
+- Never animate on every keystroke; input must always feel instant.
+
+---
+
+## 7. Validate against anti-patterns
+
+Before shipping, confirm none of these are true:
+
+- [ ] Crashes or corrupts on resize / below minimum size (no size gate).
+- [ ] Hierarchy depends on true color — unusable in 16-color or `NO_COLOR`.
+- [ ] Information conveyed by color alone (no symbol/text/position backup).
+- [ ] Body-text contrast below WCAG AA (4.5:1).
+- [ ] Binds `Ctrl+C`, `Ctrl+Z`, or `Ctrl+\`.
+- [ ] No footer hints and no `?` help — undiscoverable.
+- [ ] Panels rearrange themselves between sessions (broken spatial memory).
+- [ ] Destructive action with no confirmation proportional to severity.
+- [ ] Full-screen repaint every frame (flicker, wasted bandwidth over SSH).
+- [ ] Hardcoded hex/ANSI in widget code instead of semantic slots.
+- [ ] Search doesn't filter live, or `Esc` doesn't dismiss it.
+- [ ] Disrupts shell scrollback (for overlay/popup tools).