textual-builder

仓库: ypares/agent-skills
安装量: 63
排名: #11973

安装

npx skills add https://github.com/ypares/agent-skills --skill textual-builder

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

  • 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

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:

← 返回排行榜