Skip to main content
skill CX Codex

textual-builder — Claude Code skill for Textual TUIs

The textual-builder skill guides agents through building terminal interfaces with Textual and prototyping card games. It includes references for widgets, layouts, styling, and interaction.

MIT 7 installs ★ 31 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add YPares/agent-skills --skill textual-builder -a claude-code
Open on GitHub

What textual-builder does

textual-builder helps an agent create terminal and browser interfaces with Textual, a Python framework. Its reference files cover app structure, widgets, layout, CSS styling, and user input handling. Each topic has its own guide in references/.

For a card game prototype, start from assets/card-game-template/. The starter includes face-up and face-down cards, player hand areas, and turn handling; run it with python app.py. Textual v0.86.0 or later is required, so the app will not run without that dependency.

What it helps with

  • scaffold a terminal app with Textual
  • arrange widgets in grids and containers
  • add inputs, buttons, or a data table
  • wire keyboard bindings to event handlers
  • start a card game prototype from a template

Example prompts for the agent

  • Build a Textual terminal app with a header, main content area, and footer.
  • Create a responsive Textual layout with a data table and input fields.
  • Start a card game prototype from assets/card-game-template/.

How to install textual-builder

1Skills CLI (Vercel)

npx skills add YPares/agent-skills --skill textual-builder -a claude-code

2Manually: put the files in place

~/.claude/skills/textual-builder/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/textual-builder/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about textual-builder

How do I install textual-builder in Claude Code?

Run npx skills add YPares/agent-skills --skill textual-builder -a claude-code. The skill file is at ~/.claude/skills/textual-builder/SKILL.md.

What does textual-builder do?

It guides an agent in making Textual interfaces, from widget layout and CSS styling to handling user actions. It also provides a starter project for card game prototypes.

Which Textual version does textual-builder require?

The skill requires Textual v0.86.0 or later. Install the package with pip install textual.

Source text

SKILL.md · MIT
---
name: textual-builder
description: 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

```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

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

```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)

© YPares · MIT · YPares/agent-skills

Similar skills

All skills for Frontend and UI →

From the same set3

Project sponsors

Companies that keep this analytics open