nw-ux-tui-patterns

# TUI and CLI Patterns

Actionable terminal interface patterns for requirements gathering and design review. Use when target is CLI tool or interactive terminal application.

## CLI Argument Design

### Command Structure
Follow `program subcommand [flags] [arguments]` (e.g., `git commit -m "message"`).

### Flags and Options
- Both short (`-h`) and long (`--help`) for common flags
- Reserve single-letter flags for frequently used options
- Standard flags always: `--help`, `--version`, `--verbose`/`--quiet`, `--no-color`
- Never accept secrets via flags (use files, stdin, or env vars)
- Make flag order independent

### Subcommands
- Verbs for actions: `create`, `delete`, `list`, `show`, `update`
- Nouns for targets: `user`, `project`, `config`
- Pick one pattern (`tool resource action` or `tool action resource`) consistently
- Provide shell completion scripts for discoverability

### Argument Design Principles
Required arguments are positional; optional use flags. Accept stdin for piping. Support glob patterns for file arguments. Provide `--dry-run` for destructive/complex operations.

## Interactive TUI Patterns

### Framework Architectures

| Framework | Language | Architecture | Best For |
|-----------|----------|-------------|----------|
| **Bubble Tea** | Go | Elm (Model-Update-View) | Full TUI apps with complex state |
| **Rich** | Python | Declarative rendering | Beautiful output, progress, tables |
| **Ink** | JavaScript | React component model | Teams with React experience |
| **Textual** | Python | CSS-like styling, widgets | Dashboard-style applications |
| **Ratatui** | Rust | Immediate-mode rendering | High-performance terminal apps |

### Key Architectural Pattern (Elm Architecture)
- **Model**: Application state (single data structure)
- **Update**: Pure function taking model + message, returns new model
- **View**: Pure function rendering model to string

Unidirectional data flow makes TUI state predictable and testable.

### Interactive Selection Patterns
Arrow keys to navigate, Enter to select. Type-ahead filtering for long lists. Multi-select with space bar, confirm with Enter. Show selected count with clear visual indicator. Support Esc to cancel.

## Color and Formatting

### Color Conventions
**Red**: errors, failures, deletions | **Yellow/amber**: warnings, attention | **Green**: success, confirmations, additions | **Blue/cyan**: information, links, highlights | **Dim/gray**: secondary info, metadata

### Color Rules
- Never use color as only way to convey information (accessibility)
- Respect `NO_COLOR` environment variable (no-color.org)
- Detect TTY: disable color when piped or redirected
- Test with color-blindness simulators (protanopia, deuteranopia)

### Formatting Patterns
Bold for emphasis and headings | Tables for structured data | Indentation for hierarchy | Horizontal rules for section breaks | Unicode box-drawing for visual structure (provide ASCII fallback)

## Error Message Design

Every CLI error answers three questions:

1. **What happened?** Clear, jargon-free description
2. **Why?** The cause or context
3. **What to do?** Concrete next step

### Good Example
```
Error: Could not connect to database at localhost:5432

  The connection was refused. The database server may not be
  running or is not accepting connections on this port.

  Try:
    1. Check if PostgreSQL is running:  pg_isready -h localhost -p 5432
    2. Start the server:                sudo systemctl start postgresql
    3. Verify the port in config:       cat ~/.config/myapp/database.yaml

  Documentation: https://docs.myapp.com/troubleshooting/database
```

### Bad Example
```
Error: ECONNREFUSED
```

### Error Guidelines
- Never blame user ("You entered invalid..." becomes "The value ... is not valid because...")
- Suggest most likely correction (did-you-mean for typos)
- Exit codes consistent: 0=success, 1=general error, 2=usage error
- Log verbose diagnostics to file, not stderr by default

## Help Text Design

### `--help` Output Structure
```
tool-name - One-line description

USAGE
  tool-name <command> [flags]

COMMANDS
  create    Create a new resource
  list      List existing resources
  delete    Remove a resource

FLAGS
  -h, --help       Show this help message
  -v, --version    Show version information
  -q, --quiet      Suppress non-error output

EXAMPLES
  # Create a new project
  tool-name create my-project --template=web

  # List all projects
  tool-name list --format=table

LEARN MORE
  Documentation:  https://docs.tool-name.com
  Report issues:  https://github.com/org/tool-name/issues
```

### Help Text Principles
Lead with examples (users scan for examples first). Show common commands/flags first. One line per description. Link to detailed docs. Support both `tool help <cmd>` and `tool <cmd> --help`.

## Output Design

### Human-Readable (Default)
Detect TTY: terminal gets colors, tables, progress bars. Disable animations/spinners in non-TTY mode. Use structured formatting (headers, indentation, alignment).

### Machine-Parseable Alternatives
- `--json` for structured output (most important machine format)
- `--plain` or `--tsv` for tabular data compatible with grep, awk, cut
- `--quiet` for scripts needing only exit code

### Output Contract
Once `--json` schema published, treat as API contract. Breaking changes require major version bump or `--output-version` flag.

## Progress and Responsiveness

- Respond within 100ms: output something immediately, especially before network calls
- Spinner for operations 1-5 seconds
- Progress bar with percentage for operations >5 seconds
- Multi-step: `[3/7] Installing dependencies...`
- Make operations idempotent where possible (safe to re-run after interruption)
- Handle Ctrl+C cleanly with proper cleanup

## CLI/TUI Anti-Patterns

| Anti-Pattern | Alternative |
|-------------|-------------|
| Wall of unformatted text | Structured output with headers, tables, color |
| Raw exception stack traces | Caught errors rewritten in human language |
| No --help or misleading help | Comprehensive, example-led help text |
| Requiring interactive input in CI/CD | Detect non-TTY and accept flags/env vars |
| Breaking JSON output between versions | Treat machine output as versioned API contract |
| Secrets accepted via flags | Use files, stdin, or environment variables |
| Color as only information channel | Pair color with text labels or symbols |

## CLI/TUI Review Checklist

### Discoverability
- [ ] --help produces useful, example-led output
- [ ] Subcommands use consistent verb/noun patterns
- [ ] Shell completion scripts available
- [ ] Did-you-mean suggestions for typos

### Output
- [ ] Default output is human-readable with color in TTY
- [ ] --json flag available for machine consumption
- [ ] Color never only way to convey information
- [ ] NO_COLOR environment variable respected
- [ ] Animations disabled in non-TTY mode

### Error Handling
- [ ] Errors answer: what happened, why, what to do
- [ ] No raw stack traces in user-facing output
- [ ] Exit codes consistent (0=success, 1=error, 2=usage)
- [ ] Suggestions for common mistakes

### Responsiveness
- [ ] First output within 100ms
- [ ] Spinner for 1-5 second operations
- [ ] Progress bar for longer operations
- [ ] Ctrl+C handled with clean cleanup

### Configuration
- [ ] Precedence: flags > env vars > project config > user config > defaults
- [ ] Secrets never via flags
- [ ] Sensible defaults for all optional config