Skip to content

aalmada/Stationary / .agents/skills/python-tui-apps

python-tui-apps

Unverified

Create polished Python terminal user interfaces and skill scripts with Textual and Rich. Use when: building TUI apps; adding interactive terminal workflows; designing tabs, progress bars, checkboxes, radio buttons, tables, charts, forms, status views, keyboard navigation, color, or responsive terminal layouts; making Python scripts visually appealing and informative. Every skill script defaults to a TUI on an interactive terminal and provides --no-tui for deterministic stream output. DO NOT USE FOR: browser GUIs; desktop-native GUIs; plain shell commands with no interactive workflow; non-Python applications.

Python TUI Apps

Anatomy

FilePurposeTarget Size
SKILL.mdDefaults, workflow, component quick reference<100 lines
references/implementation.mdTextual/Rich architecture, CLI contract, stream fallback<200 lines
references/ux-and-components.mdComponent selection, visual design, interaction states<200 lines
references/testing-and-accessibility.mdHeadless tests, terminal sizes, accessibility, release checks<200 lines

Required Contract

ConcernRule
DefaultLaunch the Textual TUI when input and output are interactive terminals
Model/automation modeAccept --no-tui; emit ordered Rich/plain stream output; never prompt or animate
Redirected I/OFall back to stream mode unless the user explicitly forces a TUI
Core logicKeep operations and state independent of Textual widgets and Rich rendering
ProgressReport phase, completed/total work, current item, and useful failure context
ColorUse a restrained semantic palette; preserve meaning without color
ControlsChoose widgets that match the data and action; do not add decorative controls
ExitSupport cancel/back, clean shutdown, stable exit codes, and a final result summary

Workflow

  1. Define the primary task, user decisions, long-running phases, errors, and final artifact.
  2. Design the stream event/result model before either renderer.
  3. Implement --no-tui and redirected-I/O fallback; keep stdout machine-safe when required.
  4. Compose the Textual app from semantic widgets and responsive containers.
  5. Add keyboard paths, focus states, loading/empty/error/success states, and confirmation for destructive actions.
  6. Test both renderers, narrow and standard terminal sizes, cancellation, errors, and piped output.

Component Quick Reference

NeedPrefer
Distinct viewsTabbedContent / TabPane; preserve each tab's state
Mutually exclusive choiceRadioSet + RadioButton or Select for compact forms
Multiple choicesSelectionList or Checkbox; show selected count
Determinate workProgressBar; pair percentage with counts and current phase
Unknown-duration workLoadingIndicator; use only while work is genuinely indeterminate
Records and comparisonDataTable; align numbers and keep columns scannable
Trends/distributionsSparkline, compact bars, or textual-plotext when a chart adds insight
CommandsButton plus keyboard binding; make the primary action visually dominant
Guidance/resultsStatic, Label, Markdown, Log, or RichLog based on content

References

FileLoad When
references/implementation.mdStarting a Python TUI, separating logic/renderers, or adding --no-tui
references/ux-and-components.mdChoosing controls, color, layout, charts, or interaction states
references/testing-and-accessibility.mdWriting tests, checking terminal sizes, or preparing release validation
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall