Initial commit

skills/textual-builder/SKILL.md

@@ -0,0 +1,175 @@
+---
+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)