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:
Single-screen shell
One main view with panels, tables, forms, or logs. Prefer containers plus built-in widgets.
Multi-screen workflow
Large context changes, separate flows, or drill-down views. Prefer Screen / ModalScreen.
Multi-mode admin app
Persistent top-level areas such as “dashboard / jobs / settings / logs”. Prefer named MODES, screen stacks, and command palette support.
Data explorer
Records plus details, filters, or side panes. Prefer DataTable, details panel, responsive breakpoints, and keyboard navigation.
Document or filesystem tool
Prefer DirectoryTree, MarkdownViewer, TextArea, Tree, and delivery APIs for export/download.
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
- Screens, modes, and command palette
Widget-first selection rules
Before inventing custom widgets, check the widget atlas.
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.
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
- Packaging and CI
Testing is part of the feature
Default output after any non-trivial change:
- one smoke test with
run_test()
- one behaviour test for the changed flow
- one narrow-terminal or alternate-size test when layout matters
- one snapshot test when the view structure matters visually
See testing matrix.
When working on an existing project
Start with the scripts, then refine by hand:
python scripts/inspect_textual_project.py <project>
python scripts/audit_textual_project.py <project>
- 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:
python scripts/scaffold_textual_app.py --list-templates
Generate one with:
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
- Widget selection atlas
- Reactivity and workers
- Screens, modes, and command palette
- Browser and delivery
- Testing matrix
- Anti-patterns
- Packaging and CI
- Repository map
- Upstream pattern atlas
1---
2name: textual-tui
3description: Build, refactor, debug, test, and package Python terminal user interfaces with Textual. Use when the user wants a TUI, terminal dashboard, admin console, multi-screen workflow, keyboard-first tool, data explorer, file browser, markdown or log viewer, editor, command palette, browser-served console app, or a migration from curses/Rich-only UI to Textual—even if they never say “Textual”. Covers TCSS and themes, built-in widgets, screens and modes, reactive state, workers, browser delivery APIs, and pytest Pilot or snapshot testing.
4license: Proprietary
5compatibility: Requires Python 3.9+ and the Textual package. `textual-dev`, `pytest`, and `pytest-asyncio` are strongly recommended. `pytest-textual-snapshot` and `textual[syntax]` are optional extras.
6metadata:
7 source: https://skillmd.com/skills/tristanmanchester/textual-tui
8 version: "2.0"
9 scope: "Textual apps, TUIs, browser-served Textual apps, testing, refactors"
10---
11
12Use 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.
13
14## Start by classifying the app
15
16Pick the closest shape before writing code:
17
181. **Single-screen shell**
19 One main view with panels, tables, forms, or logs. Prefer containers plus built-in widgets.
20
212. **Multi-screen workflow**
22 Large context changes, separate flows, or drill-down views. Prefer `Screen` / `ModalScreen`.
23
243. **Multi-mode admin app**
25 Persistent top-level areas such as “dashboard / jobs / settings / logs”. Prefer named `MODES`, screen stacks, and command palette support.
26
274. **Data explorer**
28 Records plus details, filters, or side panes. Prefer `DataTable`, details panel, responsive breakpoints, and keyboard navigation.
29
305. **Document or filesystem tool**
31 Prefer `DirectoryTree`, `MarkdownViewer`, `TextArea`, `Tree`, and delivery APIs for export/download.
32
336. **Chat / streaming / long-running task UI**
34 Prefer a scrollable transcript or log plus `@work` / workers for background operations.
35
36If the user has not chosen an architecture, choose one and proceed.
37
38## Default engineering stance
39
40- Prefer **built-in widgets first**. Only hand-roll behaviour when a built-in widget clearly does not fit.
41- Keep the **`App` thin**. Move screen-specific logic into `Screen` classes and reusable composite widgets.
42- Prefer **`.tcss` files** over inline `CSS` once styling grows beyond a toy example.
43- Use **IDs and semantic classes** deliberately so styling and Pilot tests stay stable.
44- Design for **narrow terminals first**, then add split panes and breakpoint-driven layouts.
45- Leave behind **tests** whenever behaviour changes.
46
47## Choose the right Textual primitive
48
49- Use **`Screen`** when navigation changes the user’s working context.
50- Use **`ModalScreen`** for short interruptions: confirmations, pickers, destructive actions.
51- Use **`ContentSwitcher`** for wizard steps or one-screen subflows.
52- Use **named `MODES`** when the app has durable top-level areas with separate navigation stacks.
53- Use **command palette providers** when there are many actions, bindings, or discoverability matters.
54- Use **workers** for network, subprocess, parsing, search, sleeps, or anything that may block input.
55
56See:
57- [Architecture decision tree](references/architecture-decision-tree.md)
58- [Screens, modes, and command palette](references/screens-modes-command-palette.md)
59
60## Widget-first selection rules
61
62Before inventing custom widgets, check [the widget atlas](references/widget-selection-atlas.md).
63
64Common defaults:
65- `DataTable` for record-heavy views
66- `DirectoryTree` for filesystem navigation
67- `MarkdownViewer` for rich document views
68- `TextArea` for editing
69- `TabbedContent` for grouped settings or alternate panes
70- `Log` / `RichLog` for live output
71- `SelectionList`, `OptionList`, `ListView`, `Tree`, `Select`, `Switch`, `Input`, `Button` for most interaction needs
72
73## Reactivity and workers
74
75Use the playbook in [reactivity and workers](references/reactivity-and-workers.md).
76
77Core rules:
78- Put fast derived state in `compute_*`, but keep it cheap and side-effect free.
79- Use `watch_*` for UI reactions, not blocking work.
80- Use `var` when you want state without automatic refresh machinery.
81- Use `set_reactive` before mount when initial state changes should not trip watchers early.
82- Move blocking work into `@work` or `run_worker(...)`.
83- Use `exclusive=True` for stale-search cancellation and similar “latest request wins” flows.
84- For thread workers, update the UI via messages or `call_from_thread`.
85
86## Browser, dev loop, and delivery
87
88Textual may run in a terminal or be served to a browser. Build with both in mind when relevant.
89
90- Use `textual run --dev` while iterating.
91- Use `textual console` and devtools when behaviour is unclear.
92- Use `textual serve` when browser parity matters.
93- Prefer `deliver_text`, `deliver_binary`, or `deliver_screenshot` for browser-friendly exports and downloads.
94- Use `open_url` when handing off to the user’s browser is appropriate.
95
96See:
97- [Browser and delivery guide](references/browser-and-delivery.md)
98- [Packaging and CI](references/packaging-and-ci.md)
99
100## Testing is part of the feature
101
102Default output after any non-trivial change:
103
1041. one smoke test with `run_test()`
1052. one behaviour test for the changed flow
1063. one narrow-terminal or alternate-size test when layout matters
1074. one snapshot test when the view structure matters visually
108
109See [testing matrix](references/testing-matrix.md).
110
111## When working on an existing project
112
113Start with the scripts, then refine by hand:
114
1151. `python scripts/inspect_textual_project.py <project>`
1162. `python scripts/audit_textual_project.py <project>`
1173. Generate scaffolds or tests only after you understand the existing structure.
118
119Use the audit to catch:
120- oversized `App` classes
121- blocking handlers
122- missing breakpoints
123- missed built-in widget opportunities
124- missing command palette or delivery APIs
125- missing Pilot tests
126
127## Bundled scripts
128
129- `scripts/scaffold_textual_app.py`
130 Generate starter apps, TCSS, tests, optional `pyproject.toml`, and CI workflow.
131
132- `scripts/inspect_textual_project.py`
133 Inventory app classes, screens, widgets, bindings, IDs, workers, and styling.
134
135- `scripts/audit_textual_project.py`
136 Heuristic architecture/performance/test audit for an existing Textual project.
137
138- `scripts/generate_pilot_tests.py`
139 Emit starter smoke and behaviour tests for an existing app.
140
141- `scripts/dump_dom_and_bindings.py`
142 If Textual is installed, launch an app under `run_test()` and dump DOM and active bindings.
143
144- `scripts/emit_textual_pyproject.py`
145 Generate a packageable Hatch-based `pyproject.toml`.
146
147- `scripts/emit_github_actions_ci.py`
148 Generate a GitHub Actions workflow for Textual tests.
149
150- `scripts/build_upstream_pattern_atlas.py`
151 Summarise a local Textual repo snapshot into `references/repo-map.md` and `references/upstream-pattern-atlas.md`.
152
153- `scripts/self_check.py`
154 Compile scripts and scaffold all bundled templates as a package validation step.
155
156## Bundled starter templates
157
158Available scaffolds:
159- `dashboard`
160- `form`
161- `chat`
162- `data-explorer`
163- `file-browser`
164- `settings`
165- `wizard`
166- `log-monitor`
167- `editor`
168- `admin-modes`
169- `download-demo`
170
171List them with:
172
173```bash
174python scripts/scaffold_textual_app.py --list-templates
175```
176
177Generate one with:
178
179```bash
180python scripts/scaffold_textual_app.py \
181 --template data-explorer \
182 --module my_app \
183 --class-name MyApp \
184 --app-title "My App" \
185 --output-dir .
186```
187
188## Output checklist
189
190Before you finish, aim to leave behind:
191
192- a clear app structure
193- stable IDs/classes for styling and tests
194- TCSS separated from Python unless the app is tiny
195- background work off the main event path
196- keyboard-discoverable actions
197- responsive layout decisions
198- at least a smoke test and one behaviour test
199- notes on how to run the app in dev mode
200
201## Read next as needed
202
203- [Architecture decision tree](references/architecture-decision-tree.md)
204- [Widget selection atlas](references/widget-selection-atlas.md)
205- [Reactivity and workers](references/reactivity-and-workers.md)
206- [Screens, modes, and command palette](references/screens-modes-command-palette.md)
207- [Browser and delivery](references/browser-and-delivery.md)
208- [Testing matrix](references/testing-matrix.md)
209- [Anti-patterns](references/anti-patterns.md)
210- [Packaging and CI](references/packaging-and-ci.md)
211- [Repository map](references/repo-map.md)
212- [Upstream pattern atlas](references/upstream-pattern-atlas.md)