gh-ypares-agent-skills-ypares-agent-skills/skills/textual-builder/SKILL.md

name, description

name	description
textual-builder	Build Text User Interface (TUI) applications using the Textual Python framework (v0.86.0+). Use when creating terminal-based applications, prototyping card games or interactive CLIs, or when the user mentions Textual, TUI, or terminal UI. Includes comprehensive reference documentation, card game starter template, and styling guides.

Textual Builder

Overview

This skill helps you build sophisticated Text User Interfaces (TUIs) using Textual, a Python framework for creating terminal and browser-based applications with a modern web-inspired API. It includes reference documentation, a card game template, and best practices for Textual development.

Quick Start

Basic Textual App

from textual.app import App, ComposeResult
from textual.widgets import Header, Footer, Label

class MyApp(App):
    def compose(self) -> ComposeResult:
        yield Header()
        yield Label("Hello, Textual!")
        yield Footer()

if __name__ == "__main__":
    app = MyApp()
    app.run()

Card Game Template

For card game prototyping, copy the template:

cp -r assets/card-game-template/* ./my-game/
cd my-game
python app.py

The template includes:

• Interactive Card widget with face-up/down states
• Hand containers for player cards
• Play area with turn management
• Key bindings for card selection and playing
• Customizable styling

See assets/card-game-template/README.md for customization guide.

When to Read Reference Documentation

This skill includes comprehensive reference files. Load them based on your task:

references/basics.md

Read when: Setting up app structure, using reactive attributes, handling mounting, querying widgets, or working with messages/events.

Covers:

• App structure and compose method
• Reactive attributes and watchers
• Mounting and dynamic widget creation
• Widget querying
• Messages, events, and custom messages

references/widgets.md

Read when: Adding UI elements like buttons, inputs, labels, data tables, or creating custom widgets.

Covers:

• Display widgets (Label, Static, Placeholder)
• Input widgets (Button, Input, TextArea, Switch)
• DataTable for tabular data
• Layout containers (Container, Grid, Horizontal, Vertical)
• Custom widget creation
• Header/Footer

references/layout.md

Read when: Designing layouts, positioning widgets, using grid systems, or handling responsive sizing.

Covers:

• Layout types (vertical, horizontal, grid)
• Grid configuration (cell spanning, row/column sizing)
• Alignment and content positioning
• Docking widgets to screen edges
• Sizing (fixed, relative, fractional, auto)
• Spacing (margin, padding)
• Scrolling

references/styling.md

Read when: Applying CSS styles, theming, adding borders, or customizing widget appearance.

Covers:

• CSS files and selectors
• Colors (named, hex, RGB, theme variables)
• Borders and border styling
• Text styling and alignment
• Opacity and tinting
• Rich markup for styled text
• Pseudo-classes (:hover, :focus, etc.)

references/interactivity.md

Read when: Implementing keyboard shortcuts, handling mouse events, responding to user actions, or creating interactive behaviors.

Covers:

• Key bindings and actions
• Dynamic binding updates
• Mouse events (click, hover, enter, leave)
• Keyboard events
• Focus management
• Widget-specific messages
• Custom messages
• Notifications and timers

Common Workflows

Creating a New TUI App

1. Start with basic app structure (see Quick Start)
2. Design layout (read references/layout.md)
3. Add widgets (read references/widgets.md)
4. Style with CSS (read references/styling.md)
5. Add interactivity (read references/interactivity.md)

Prototyping a Card Game

1. Copy the card game template
2. Customize the Card widget for your game's card properties
3. Modify game logic in action methods
4. Add game-specific rules in message handlers
5. Style cards and layout in app.tcss

Adding Interactive Features

1. Define key bindings in BINDINGS
2. Implement action methods (action_*)
3. Handle widget messages (on_button_pressed, etc.)
4. Use reactive attributes for state management
5. Update UI in watchers

Best Practices

• Progressive Development: Start simple, add complexity incrementally
• Reactive State: Use reactive() for state that affects UI
• CSS Separation: Keep styling in .tcss files, not inline
• Widget Reuse: Create custom widgets for repeated components
• Message Bubbling: Use event.stop() to control message propagation
• Type Hints: Use proper type hints for better IDE support
• IDs and Classes: Use semantic IDs/classes for querying and styling

Installation

pip install textual
# or
uv pip install textual

Current version: v0.86.0+ (as of November 2025, latest is v6.6.0)

Resources

references/

Comprehensive documentation loaded on-demand:

• basics.md - Core concepts and app structure
• widgets.md - Widget catalog and usage
• layout.md - Layout systems and positioning
• styling.md - CSS and theming
• interactivity.md - Events, bindings, and actions

assets/

• card-game-template/ - Complete starter template for card games with interactive cards, hands, and turn management

Official Documentation

For topics not covered in this skill, consult:

• https://textual.textualize.io/ (official docs)
• https://github.com/Textualize/textual (GitHub repo)