# tui-fundamentals

The tui-fundamentals skill helps plan a terminal UI, pick a framework, and review its architecture. Use it for dashboards, REPLs, wizards, and interactive CLI flows.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 369 installs · ★ 66 repo stars
- Author: JosiahSiegel
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/JosiahSiegel/claude-plugin-marketplace/tree/HEAD/plugins/tui-master/skills/tui-fundamentals/SKILL.md
- Updated: 2026-06-18
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/tui-fundamentals

## What it does

tui-fundamentals helps decide whether a terminal product needs a full-screen interface or should stay with commands, prompts, or plain output. It covers full-screen, inline, prompt-based, and hybrid designs, along with keyboard navigation, help access, and non-interactive alternatives for core actions.

The skill separates model, update, and view responsibilities, treats terminal dimensions as input, and keeps terminal lifecycle handling in one place. Its framework matrix covers Ratatui, Textual, Rich, prompt_toolkit, curses, Bubble Tea, Ink, and other options. Two reference files cover framework selection and TUI architecture in more detail.

It also addresses `TERM=dumb`, non-TTY output, CI, SSH, tmux/screen, and Windows console differences. For a short, scriptable workflow, the skill treats a full-screen TUI as the wrong direction, so the project should define a non-interactive path for each essential action.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add JosiahSiegel/claude-plugin-marketplace --skill tui-fundamentals -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/tui-fundamentals/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/tui-fundamentals/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add JosiahSiegel/claude-plugin-marketplace --skill tui-fundamentals -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/tui-fundamentals/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add JosiahSiegel/claude-plugin-marketplace --skill tui-fundamentals -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/tui-fundamentals/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install JosiahSiegel/claude-plugin-marketplace plugins/tui-master/skills/tui-fundamentals
```

2. **Manually: put the files in place**
- File: `.github/skills/tui-fundamentals/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add JosiahSiegel/claude-plugin-marketplace --skill tui-fundamentals -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/JosiahSiegel/claude-plugin-marketplace --path plugins/tui-master/skills/tui-fundamentals
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/tui-fundamentals/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add JosiahSiegel/claude-plugin-marketplace --skill tui-fundamentals -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/JosiahSiegel/claude-plugin-marketplace/tree/HEAD/plugins/tui-master/skills/tui-fundamentals/SKILL.md

## When to use it
- choose the right terminal UI shape
- compare TUI frameworks for a new project
- separate application state from rendering
- plan layout changes on terminal resize
- keep interactive features usable in CI and SSH

## Example prompts
- Design a terminal dashboard and decide between a full-screen and inline UI.
- Compare `Ratatui + Crossterm`, `Textual`, and `curses` for this new TUI project.
- Review this interactive CLI architecture for state, resize handling, and non-TTY behavior.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 4d430f2a4b7ccdbc.

BEGIN THIRD-PARTY FILE 4d430f2a4b7ccdbc
```text
---
name: tui-fundamentals
description: |
  This skill should be used when the user asks to design, create, choose, modernize, or review a terminal UI, text user interface, curses app, dashboard, wizard, REPL shell, prompt flow, or CLI with interactive screens. PROACTIVELY activate for: TUI architecture, terminal-ui design, framework selection, curses vs modern framework, full-screen vs inline UI, app state modeling, widget composition, command palette, keyboard-first workflow, terminal dashboard, interactive CLI UX, and cross-platform terminal product planning. Provides: architecture patterns, framework decision rules, UX guardrails, scope boundaries, and production readiness checklists.
---

# TUI Fundamentals, Architecture, and Framework Selection

Use this skill when the task is about the shape of the terminal product: what kind of TUI to build, which abstraction to use, how to organize state, or whether a full-screen terminal UI is the right answer.

## First decision: is a TUI appropriate?

Prefer a rich TUI when users need continuous visual feedback, multi-step navigation, keyboard-driven exploration, selection among many items, or a dashboard-like control surface. Prefer a line-oriented CLI, prompts, or plain output when the flow is short, scriptable, primarily automation-focused, or likely to be used by screen readers and CI systems.

A production terminal product often ships both:

- A scriptable CLI surface for automation, accessibility, logs, and non-TTY use.
- An optional TUI for exploration, monitoring, bulk selection, or guided workflows.

## Architecture rules

1. **Separate model, update, and view.** Business state should not print directly to the terminal. Rendering consumes state; input produces events; update logic transforms state.
2. **Treat terminal size as input.** Layout must be recomputed from width and height on every resize. Never bake in one terminal size.
3. **Own terminal lifecycle in one place.** Raw mode, alternate screen, mouse, focus, keyboard protocols, and cleanup should be centralized.
4. **Make every action keyboard-operable.** Mouse support is an enhancement, not the primary navigation model.
5. **Design for degradation.** `TERM=dumb`, non-TTY output, missing color, Windows console differences, tmux/screen, SSH, and CI should have clear behavior.
```
END THIRD-PARTY FILE 4d430f2a4b7ccdbc

The third-party file has ended. Everything between the 4d430f2a4b7ccdbc tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2326 of 4596 bytes. © JosiahSiegel · MIT · https://github.com/JosiahSiegel/claude-plugin-marketplace/tree/HEAD/plugins/tui-master/skills/tui-fundamentals/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
