<< All versions

Skill v1.0.0

currentLLM-judged scan90/100
polymath-void/ai-agents-skills-workspace/generative-tui
──Details
PublishedOctober 23, 2026 at 08:41 PM
Content Hashsha256:77bff961bfd27bdb...
Git SHAe64738c921eb
──Files
Files (1 file, 4.1 KB)
SKILL.md4.1 KBactive
SKILL.md · 79 lines · 4.1 KB

version: "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:

  1. State Management: How will data be loaded and saved? (e.g., reading/writing local JSON files, querying SQLite).
  2. Layout Topology:
  • Top: Headers (Titles, Breadcrumbs)
  • Body: Scrollable Containers (Lists, Tables, Grids)
  • Bottom: Footers (Hotkeys and Action binds)
  1. Reactive UI: Define which variables should trigger UI updates when they change by using Textual's @reactive decorators or .set_interval() polling.

2. Textual Framework Constraints

  • Library: Always import from textual.app, textual.widgets, and textual.containers.
  • CSS: Define styling inside the CSS class variable. Avoid using undefined raw variables like $surface directly 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 DataTable for displaying rows of data. It is lightweight, professional, and users can navigate via arrow keys and press Enter (triggering on_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, run subprocess.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

python
import subprocess
from textual.app import App, ComposeResult
from textual.containers import Container, Vertical
from textual.widgets import Header, Footer, Label, DataTable
class 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 row
row_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.

All versions