Skill v1.0.0
currentLLM-judged scan90/100version: "1.0.0" name: generative-tui description: Guidelines and reasoning procedures for designing native interactive Python Terminal User Interfaces (TUIs) using the Textual framework, strictly avoiding HTML/Web widgets.
Generative Native TUI Dashboard Design
When the user asks you to build a "TUI", "Terminal Dashboard", or explicitly invokes the /generative_tui or generative-tui skill, you MUST build a native Python terminal interface using the textual framework.
CRITICAL RULE: DO NOT build HTML, CSS, or JS web widgets. DO NOT use the /generative_ui Web constraints. You are building a native terminal application that runs via python3 app.py inside the user's Termux shell.
1. Architectural Reasoning
Before writing the code, structure your reasoning into the following components:
- State Management: How will data be loaded and saved? (e.g., reading/writing local JSON files, querying SQLite).
- Layout Topology:
- Top: Headers (Titles, Breadcrumbs)
- Body: Scrollable Containers (Lists, Tables, Grids)
- Bottom: Footers (Hotkeys and Action binds)
- Reactive UI: Define which variables should trigger UI updates when they change by using Textual's
@reactivedecorators or.set_interval()polling.
2. Textual Framework Constraints
- Library: Always import from
textual.app,textual.widgets, andtextual.containers. - CSS: Define styling inside the
CSSclass variable. Avoid using undefined raw variables like$surfacedirectly unless you know the theme injects them; instead, rely on the default Textual terminal theme or standard color names (e.g.,green,red,blue). - Interactive Lists: DO NOT clutter the screen with giant buttons for list items. Always use
DataTablefor displaying rows of data. It is lightweight, professional, and users can navigate via arrow keys and pressEnter(triggeringon_data_table_row_selected) to perform actions on a row. - Subprocesses & Auth: If you need to run an interactive terminal script or an OAuth login flow (which prints a URL or requires standard input), use the
with self.suspend():context manager to temporarily drop out of the TUI, runsubprocess.run(), and then seamlessly resume the TUI. - Hotkeys: Always define
BINDINGS = [("q", "quit", "Quit")]in the App class so the user can gracefully exit.
3. Implementation Example Boilerplate
import subprocessfrom textual.app import App, ComposeResultfrom textual.containers import Container, Verticalfrom textual.widgets import Header, Footer, Label, DataTableclass DashboardApp(App):CSS = """#main { padding: 1; height: 100%; }DataTable { height: 100%; }"""BINDINGS = [("q", "quit", "Quit"), ("r", "refresh", "Refresh"), ("a", "add_item", "Add Item")]def compose(self) -> ComposeResult:yield Header()yield Vertical(Label("Select an item to toggle.", id="info"), DataTable(id="data_table"), id="main")yield Footer()def on_mount(self) -> None:self.title = "Professional Native TUI"table = self.query_one(DataTable)table.cursor_type = "row"table.add_columns("ID", "Status")self.action_refresh()def action_refresh(self) -> None:table = self.query_one(DataTable)table.clear()table.add_row("0", "[green]ENABLED[/]", key="0")def action_add_item(self) -> None:with self.suspend():print("Running interactive CLI script...")subprocess.run(["python3", "-c", "print('Finished!'); input('Press Enter to return...')"])self.action_refresh()def on_data_table_row_selected(self, event: DataTable.RowSelected) -> None:# User pressed Enter on a rowrow_key = event.row_key# Handle toggle logic here...self.action_refresh()if __name__ == "__main__":app = DashboardApp()app.run()
4. Execution
Always write the TUI code directly to a .py file in the user's project directory (e.g., ~/Projects/my-project/app_tui.py) and instruct the user to run it via python3 app_tui.py.