textual-tui

What this skill does

Use this skill when the task is fundamentally about **building or changing a Textual app**, not merely printing Rich output or writing a non-interactive CLI.

## Start by classifying the app

Pick the closest shape before writing code:

1. **Single-screen shell**  
   One main view with panels, tables, forms, or logs. Prefer containers plus built-in widgets.

2. **Multi-screen workflow**  
   Large context changes, separate flows, or drill-down views. Prefer `Screen` / `ModalScreen`.

3. **Multi-mode admin app**  
   Persistent top-level areas such as “dashboard / jobs / settings / logs”. Prefer named `MODES`, screen stacks, and command palette support.

4. **Data explorer**  
   Records plus details, filters, or side panes. Prefer `DataTable`, details panel, responsive breakpoints, and keyboard navigation.

5. **Document or filesystem tool**  
   Prefer `DirectoryTree`, `MarkdownViewer`, `TextArea`, `Tree`, and delivery APIs for export/download.

6. **Chat / streaming / long-running task UI**  
   Prefer a scrollable transcript or log plus `@work` / workers for background operations.

If the user has not chosen an architecture, choose one and proceed.

## Default engineering stance

- Prefer **built-in widgets first**. Only hand-roll behaviour when a built-in widget clearly does not fit.
- Keep the **`App` thin**. Move screen-specific logic into `Screen` classes and reusable composite widgets.
- Prefer **`.tcss` files** over inline `CSS` once styling grows beyond a toy example.
- Use **IDs and semantic classes** deliberately so styling and Pilot tests stay stable.
- Design for **narrow terminals first**, then add split panes and breakpoint-driven layouts.
- Leave behind **tests** whenever behaviour changes.

## Choose the right Textual primitive

- Use **`Screen`** when navigation changes the user’s working context.
- Use **`ModalScreen`** for short interruptions: confirmations, pickers, destructive actions.
- Use **`ContentSwitcher`** for wizard steps or one-screen subflows.
- Use **named `MODES`** when the app has durable top-level areas with separate navigation stacks.
- Use **command palette providers** when there are many actions, bindings, or discoverability matters.
- Use **workers** for network, subprocess, parsing, search, sleeps, or anything that may block input.

See:
- [Architecture decision tree](references/architecture-decision-tree.md)
- [Screens, modes, and command palette](references/screens-modes-command-palette.md)

## Widget-first selection rules

Before inventing custom widgets, check [the widget atlas](references/widget-selection-atlas.md).

Common defaults:
- `DataTable` for record-heavy views
- `DirectoryTree` for filesystem navigation
- `MarkdownViewer` for rich document views
- `TextArea` for editing
- `TabbedContent` for grouped settings or alternate panes
- `Log` / `RichLog` for live output
- `SelectionList`, `OptionList`, `ListView`, `Tree`, `Select`, `Switch`, `Input`, `Button` for most interaction needs

## Reactivity and workers

Use the playbook in [reactivity and workers](references/reactivity-and-workers.md).

Core rules:
- Put fast derived state in `compute_*`, but keep it cheap and side-effect free.
- Use `watch_*` for UI reactions, not blocking work.
- Use `var` when you want state without automatic refresh machinery.
- Use `set_reactive` before mount when initial state changes should not trip watchers early.
- Move blocking work into `@work` or `run_worker(...)`.
- Use `exclusive=True` for stale-search cancellation and similar “latest request wins” flows.
- For thread workers, update the UI via messages or `call_from_thread`.

## Browser, dev loop, and delivery

Textual may run in a terminal or be served to a browser. Build with both in mind when relevant.

- Use `textual run --dev` while iterating.
- Use `textual console` and devtools when behaviour is unclear.
- Use `textual serve` when browser parity matters.
- Prefer `deliver_text`, `deliver_binary`, or `deliver_screenshot` for browser-friendly exports and downloads.
- Use `open_url` when handing off to the user’s browser is appropriate.

See:
- [Browser and delivery guide](references/browser-and-delivery.md)
- [Packaging and CI](references/packaging-and-ci.md)

## Testing is part of the feature

Default output after any non-trivial change:

1. one smoke test with `run_test()`
2. one behaviour test for the changed flow
3. one narrow-terminal or alternate-size test when layout matters
4. one snapshot test when the view structure matters visually

See [testing matrix](references/testing-matrix.md).

## When working on an existing project

Start with the scripts, then refine by hand:

1. `python scripts/inspect_textual_project.py <project>`
2. `python scripts/audit_textual_project.py <project>`
3. Generate scaffolds or tests only after you understand the existing structure.

Use the audit to catch:
- oversized `App` classes
- blocking handlers
- missing breakpoints
- missed built-in widget opportunities
- missing command palette or delivery APIs
- missing Pilot tests

## Bundled scripts

- `scripts/scaffold_textual_app.py`  
  Generate starter apps, TCSS, tests, optional `pyproject.toml`, and CI workflow.

- `scripts/inspect_textual_project.py`  
  Inventory app classes, screens, widgets, bindings, IDs, workers, and styling.

- `scripts/audit_textual_project.py`  
  Heuristic architecture/performance/test audit for an existing Textual project.

- `scripts/generate_pilot_tests.py`  
  Emit starter smoke and behaviour tests for an existing app.

- `scripts/dump_dom_and_bindings.py`  
  If Textual is installed, launch an app under `run_test()` and dump DOM and active bindings.

- `scripts/emit_textual_pyproject.py`  
  Generate a packageable Hatch-based `pyproject.toml`.

- `scripts/emit_github_actions_ci.py`  
  Generate a GitHub Actions workflow for Textual tests.

- `scripts/build_upstream_pattern_atlas.py`  
  Summarise a local Textual repo snapshot into `references/repo-map.md` and `references/upstream-pattern-atlas.md`.

- `scripts/self_check.py`  
  Compile scripts and scaffold all bundled templates as a package validation step.

## Bundled starter templates

Available scaffolds:
- `dashboard`
- `form`
- `chat`
- `data-explorer`
- `file-browser`
- `settings`
- `wizard`
- `log-monitor`
- `editor`
- `admin-modes`
- `download-demo`

List them with:

```bash
python scripts/scaffold_textual_app.py --list-templates
```

Generate one with:

```bash
python scripts/scaffold_textual_app.py \
  --template data-explorer \
  --module my_app \
  --class-name MyApp \
  --app-title "My App" \
  --output-dir .
```

## Output checklist

Before you finish, aim to leave behind:

- a clear app structure
- stable IDs/classes for styling and tests
- TCSS separated from Python unless the app is tiny
- background work off the main event path
- keyboard-discoverable actions
- responsive layout decisions
- at least a smoke test and one behaviour test
- notes on how to run the app in dev mode

## Read next as needed

- [Architecture decision tree](references/architecture-decision-tree.md)
- [Widget selection atlas](references/widget-selection-atlas.md)
- [Reactivity and workers](references/reactivity-and-workers.md)
- [Screens, modes, and command palette](references/screens-modes-command-palette.md)
- [Browser and delivery](references/browser-and-delivery.md)
- [Testing matrix](references/testing-matrix.md)
- [Anti-patterns](references/anti-patterns.md)
- [Packaging and CI](references/packaging-and-ci.md)
- [Repository map](references/repo-map.md)
- [Upstream pattern atlas](references/upstream-pattern-atlas.md)