textual-builder

Original：🇺🇸 English

Translated

1 scriptsChecked / no sensitive code detected

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.

2installs

Sourceypares/agent-skills

Added on2026-02-26

NPX Install

npx skill4agent add ypares/agent-skills textual-builder

SKILL.md Content

View Translation Comparison →

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

python

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:

bash

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

Start with basic app structure (see Quick Start)
Design layout (read
```
references/layout.md
```
)
Add widgets (read
```
references/widgets.md
```
)
Style with CSS (read
```
references/styling.md
```
)
Add interactivity (read
```
references/interactivity.md
```
)

Prototyping a Card Game

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

Adding Interactive Features

Define key bindings in
```
BINDINGS
```
Implement action methods (
```
action_*
```
)
Handle widget messages (
```
on_button_pressed
```
, etc.)
Use reactive attributes for state management
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

bash

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)

textual-builder

NPX Install

Tags

SKILL.md Content

Textual Builder

Overview

Quick Start

Basic Textual App

Card Game Template

When to Read Reference Documentation

references/basics.md

references/widgets.md

references/layout.md

references/styling.md

references/interactivity.md

Common Workflows

Creating a New TUI App

Prototyping a Card Game

Adding Interactive Features

Best Practices

Installation

Resources

references/

assets/

Official Documentation