general-ui-ux

# Ensure you have Python 3.8+ installed
python --version

# Install Textual and dependencies
pip install textual textual-dev

# Install test dependencies (optional but recommended)
pip install pytest pytest-asyncio pytest-textual-snapshot

# Run the quick start example
cd examples
python quick_start.py

from helpers.skill_finder import SkillFinder

# Verify plugin is loaded
finder = SkillFinder()
skills = finder.find_skills("getting started")
print(f"Found {len(skills)} skills")

# Launch the comprehensive demo
cd examples
python quick_start.py

# Start with the basics
cd skills/textual/core
python 01_getting_started.py

# Explore widgets
cd ../widgets
python 01_builtin_widgets.py

from helpers.textual_generator import TextualGenerator, WidgetSpec

# Create a specification
widgets = [
    WidgetSpec("Button", id="submit", properties={"label": "Submit"}),
    WidgetSpec("Input", id="name", properties={"placeholder": "Name"}),
]

# Generate complete app
generator = TextualGenerator()
app_code = generator.generate_app(
    "MyFormApp",
    widgets=widgets,
    css="Button { margin: 1; }",
    bindings=[("q", "quit", "Quit")]
)

print(app_code)

from helpers.template_manager import TemplateManager, TemplateType

manager = TemplateManager()

# Get an app template
app_code = manager.get_template(
    TemplateType.APP,
    "basic",
    app_name="MyApp"
)

# Get a reactive widget template
widget_code = manager.get_template(
    TemplateType.WIDGET,
    "reactive",
    widget_name="Counter",
    reactive_attr="count",
    default_value=0
)

from helpers.textual_generator import TextualGenerator, WidgetSpec

# Generate a complete app
generator = TextualGenerator()

widgets = [
    WidgetSpec("Header"),
    WidgetSpec("Static", id="title", properties={"content": "My App"}),
    WidgetSpec("Button", id="click", properties={"label": "Click Me"}),
    WidgetSpec("Footer"),
]

code = generator.generate_app(
    "HelloWorldApp",
    widgets=widgets,
    css="""
    Screen {
        align: center middle;
    }
    Button {
        margin: 1;
    }
    """,
    bindings=[
        ("q", "quit", "Quit"),
        ("r", "reload", "Reload"),
    ]
)

"""
Generated Textual Application: HelloWorldApp
"""
from textual.app import App, ComposeResult
from textual.widgets import Header, Footer, Static, Button

class HelloWorldApp(App):
    """A Textual application."""

    CSS = '''
    Screen {
        align: center middle;
    }
    Button {
        margin: 1;
    }
    '''

    BINDINGS = [
        ("q", "quit", "Quit"),
        ("r", "reload", "Reload"),
    ]

    def compose(self) -> ComposeResult:
        """Create child widgets."""
        yield Header()
        yield Static("My App", id="title")
        yield Button("Click Me", id="click")
        yield Footer()

    def on_button_pressed(self, event: Button.Pressed) -> None:
        """Handle button press."""

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

from helpers.template_manager import TemplateManager, TemplateType

manager = TemplateManager()

# List all templates
templates = manager.list_templates()
print(templates)

# Get a specific template
app_template = manager.get_template(
    TemplateType.APP,
    "multi_screen",
    app_name="MyMultiScreenApp"
)

# Get a modal template
modal_template = manager.get_template(
    TemplateType.MODAL,
    "confirm",
    title="Confirm Action",
    message="Are you sure?"
)

# Template with variables
widget_code = manager.get_template(
    TemplateType.WIDGET,
    "reactive",
    widget_name="CustomWidget",
    reactive_attr="value",
    default_value="default",
    widget_type="Static"  # The underlying widget
)

from helpers.skill_finder import SkillFinder

finder = SkillFinder()

# Search by keyword
skills = finder.find_skills("button events")
for skill in skills:
    print(f"{skill.name}: {skill.description}")

# Get task-based recommendations
task = "Create a data entry form with validation"
recommendations = finder.find_by_task(task)
print(f"Recommended skills: {[r.name for r in recommendations]}")

# Get learning path
path = finder.get_learning_path("beginner")
print(f"Learning path: {path}")

# Find by category
core_skills = finder.find_by_category("core")
widget_skills = finder.find_by_category("widgets")

from helpers.quick_reference import QUICK_REFERENCE, get_pattern

# Display full reference
print(QUICK_REFERENCE)

# Get specific pattern
counter_pattern = get_pattern("counter")
form_pattern = get_pattern("form")
modal_pattern = get_pattern("modal")
reactive_pattern = get_pattern("reactive")

from helpers.marimo.marimo_generator import MarimoNotebookGenerator

gen = MarimoNotebookGenerator()

# Create basic notebook
gen.add_imports_cell(["import marimo as mo", "import pandas as pd"])
gen.add_markdown_cell("# My Analysis")
gen.add_widget_cell("slider", "threshold", start=0, stop=100)
gen.add_code_cell("filtered_data = df[df['value'] > threshold]")

gen.save("analysis.py")

skills/
├── textual/
│   ├── core/
│   │   ├── 01_getting_started.py        # ⭐ Start here
│   │   └── 02_app_lifecycle.py
│   ├── widgets/
│   │   ├── 01_builtin_widgets.py        # Essential widgets
│   │   └── 02_custom_widgets.py
│   ├── layout/
│   │   ├── 01_layouts.py                # Layout systems
│   │   └── 02_css_styling.py            # CSS styling
│   ├── interactivity/
│   │   └── 01_events_messages.py        # Event handling
│   ├── reactivity/
│   │   └── 01_reactive_attributes.py    # State management
│   ├── navigation/
│   │   └── 01_screens.py                # Multi-screen apps
│   └── testing/
│       └── 01_snapshot_testing.py       # Testing patterns
├── marimo/
│   ├── 01_getting_started.py            # Reactive notebooks
│   ├── 02_widgets_ui.py
│   ├── 03_layouts.py
│   └── 04_working_with_marimo.py
└── design/
    ├── 01_cli_ux_principles.py          # CLI UX best practices
    └── 02_general_ui_ux.py              # General UX principles

1. ⭐ skills/textual/core/01_getting_started.py
2. ⭐ skills/textual/widgets/01_builtin_widgets.py
3. ⭐ skills/textual/layout/01_layouts.py
4. ⭐ skills/textual/interactivity/01_events_messages.py
5. ⭐ skills/textual/layout/02_css_styling.py

1. skills/textual/widgets/02_custom_widgets.py
2. skills/textual/reactivity/01_reactive_attributes.py
3. skills/textual/navigation/01_screens.py
4. skills/textual/testing/01_snapshot_testing.py

1. skills/textual/core/02_app_lifecycle.py
2. Advanced testing strategies
3. Performance optimization
4. Complex state management
5. Accessibility

1. ⭐ skills/design/01_cli_ux_principles.py
2. ⭐ skills/design/02_general_ui_ux.py
3. Apply to Textual apps
4. Apply to Marimo notebooks

from textual.app import App, ComposeResult
from textual.widgets import Static

class BasicApp(App):
    def compose(self) -> ComposeResult:
        yield Static("Hello, Textual!")

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

# Button
Button("Click Me", variant="success")

# Input
Input(placeholder="Enter name", id="name")

# DataTable
table = DataTable()
table.add_columns("Name", "Age", "City")
table.add_rows([["Alice", 30, "NYC"], ["Bob", 25, "LA"]])

from textual.containers import Vertical, Horizontal, Container

# Vertical layout (default)
with Vertical():
    yield Button("Top")
    yield Button("Bottom")

# Horizontal layout
with Horizontal():
    yield Button("Left")
    yield Button("Right")

# Grid layout
with Container():
    # CSS will define grid
    pass

CSS = '''
Screen {
    background: $primary;
}

Button {
    margin: 1;
    padding: 0 2;
}

#special-button {
    background: $success;
}
'''

from textual.widgets import Button

def on_button_pressed(self, event: Button.Pressed) -> None:
    """Handle button clicks."""
    if event.button.id == "submit":
        self.process_form()

# Or using @on decorator
from textual.on import on

@on(Button.Pressed, "#submit")
def handle_submit(self) -> None:
    self.process_form()

from textual.reactive import reactive

class CounterApp(App):
    count = reactive(0)

    def watch_count(self, new_count: int) -> None:
        """Called when count changes."""
        self.query_one("#display", Static).update(str(new_count))

    def on_button_pressed(self) -> None:
        self.count += 1

from textual.screen import Screen

class SettingsScreen(Screen):
    """Settings screen."""

    def compose(self) -> ComposeResult:
        yield Button("Back", id="back")

class MainApp(App):
    async def on_button_pressed(self) -> None:
        """Show settings screen."""
        await self.push_screen_wait(SettingsScreen())

from textual.testing import press

def test_counter():
    """Test counter app."""
    app = CounterApp()
    async with app.run_test() as pilot:
        # Click increment button
        await pilot.click("#inc")
        # Check result
        assert app.query_one("#display").renderable == "1"

# Use grid layout with CSS
CSS = '''
.grid-container {
    grid-size: 3 2;
    grid-gutter: 1;
}
'''

# Add widgets to grid
with Container(classes="grid-container"):
    yield DataTable(id="table")
    yield ProgressBar(id="progress")
    yield Static(id="stats")

# Create form widgets
yield Input(placeholder="Name", id="name")
yield Input(placeholder="Email", id="email")
yield Button("Submit", id="submit")

# Handle submission
def on_button_pressed(self, event: Button.Pressed) -> None:
    if event.button.id == "submit":
        self.submit_form()

def submit_form(self):
    name = self.query_one("#name", Input).value
    email = self.query_one("#email", Input).value
    # Validate and process

from textual.app import App, ComposeResult
from textual.widgets import Static

class MyApp(App):
    """A well-structured app."""

    CSS = '''
    /* Keep CSS concise */
    '''

    def compose(self) -> ComposeResult:
        """Create child widgets."""
        yield Static("Content")

    def on_mount(self) -> None:
        """Initialize after mounting."""
        self.log("App mounted")

    def on_unmount(self) -> None:
        """Clean up before unmounting."""
        self.log("App unmounting")

# Don't put logic in compose()
def compose(self) -> ComposeResult:
    # This should only yield widgets!
    data = fetch_data()  # ❌
    yield create_widget_from_data(data)  # ❌

# Use IDs for unique widgets
yield Button("Click", id="submit-button")

# Use classes for groups
yield Button("Cancel", classes="secondary-button")
yield Button("Save", classes="primary-button")

# Don't query by content
self.query("Button:disabled")  # ❌ Fragile

# Use external CSS files for large projects
class MyApp(App):
    CSS_PATH = "styles.tcss"

# Or use a separate CSS constant
CSS = '''
/* Group related styles */
.header {
    background: $primary;
}

.content {
    padding: 1;
}
'''

# Don't inline styles in compose()
with Container(style="background: red;"):  # ❌
    pass

from textual.on import on

@on(Button.Pressed, "#submit")
def handle_submit(self, event: Button.Pressed) -> None:
    """Handle submit button."""
    self.process_form()

# Or use named methods
def on_button_pressed(self, event: Button.Pressed) -> None:
    """Handle any button press."""
    if event.button.id == "submit":
        self.process_form()

# Don't use complex conditionals
def on_key(self, event) -> None:
    if event.key == "a" and self.state == "editing":  # ❌
        pass

from textual.reactive import reactive

class CounterApp(App):
    count = reactive(0)

    def watch_count(self, new_count: int) -> None:
        """Auto-update when count changes."""
        self.query_one("#display", Static).update(str(new_count))

# Don't manually update without reactivity
def increment(self):
    self.count += 1
    self.update_display()  # ❌ Manual update

from textual.testing import press, click

async def test_form_submission():
    app = FormApp()
    async with app.run_test() as pilot:
        # Simulate user interaction
        await pilot.click("#submit")
        # Verify state
        assert app.submitted

# Don't test without running the app
def test_form():
    app = FormApp()
    assert app.is_valid()  # ❌ No event loop

from textual.widgets import Static

def on_button_pressed(self) -> None:
    try:
        self.process_data()
    except ValueError as e:
        self.notify(f"Error: {e}", severity="error")
        self.query_one("#error", Static).update(str(e))

# Don't silently ignore errors
def on_button_pressed(self) -> None:
    self.process_data()  # ❌ No error handling

from textual.workers import worker

@worker
async def fetch_data(self):
    """Use workers for long operations."""
    data = await self.api.get_data()
    self.data = data

def on_mount(self):
    self.run_worker(self.fetch_data)

# Don't block the UI
def on_mount(self):
    # This will freeze the app!
    data = self.blocking_api.get_data()  # ❌
    self.data = data

ModuleNotFoundError: No module named 'textual'

# Install Textual
pip install textual textual-dev

# Verify installation
python -c "import textual; print(textual.__version__)"

# ✅ Use reactive attributes
count = reactive(0)

def watch_count(self, new_count):
    self.query_one("#display").update(str(new_count))

def on_button_pressed(self, event):
    self.log(f"Button pressed: {event.button.id}")  # Debug

CSS = '''
Container {
    grid-size: 2 2;  /* 2 columns, 2 rows */
}
'''

# ✅ Correct nesting
with Container():
    with Vertical():
        yield Button("Top")

# ❌ Incorrect
yield Container(Vertical(Button("Top")))

# Ensure IDs match
yield Button("Click", id="my-button")

def on_button_pressed(self, event: Button.Pressed):
    if event.button.id == "my-button":  # ✅ Match
        pass

from textual.on import on

@on(Button.Pressed, "#my-button")
def handle_click(self) -> None:
    """Explicit event handler."""
    pass

Permission denied: examples/quick_start.py

# Make executable (optional)
chmod +x examples/*.py

# Run with Python
python examples/quick_start.py

def on_unmount(self) -> None:
    """Clean up resources."""
    self.log("App closing")

# Or use exit hooks
def on_exit(self) -> None:
    """Handle exit."""
    pass

from textual.workers import worker

@worker
async def long_task(self):
    result = await self.do_work()
    return result

def update_multiple_widgets(self):
    with self.batch_update():
        self.query_one("#w1").update("New 1")
        self.query_one("#w2").update("New 2")
        self.query_one("#w3").update("New 3")

class MyApp(App):
    CSS_PATH = "styles.tcss"  # File must exist

CSS = '''
Button {  /* ✅ Correct */
    margin: 1;
}
'''

from textual.widgets import Button
from textual.app import ComposeResult

def compose(self) -> ComposeResult:
    """Return type hint."""
    yield Button("Click")

def on_button_pressed(self, event: Button.Pressed) -> None:
    """Event type hint."""
    pass

CSS = '''
Button {
    background: $primary;
    color: $text;
    margin: 1;
}
'''

from textual.screen import Screen

class SettingsScreen(Screen):
    pass

class MainApp(App):
    async def show_settings(self):
        await self.push_screen_wait(SettingsScreen())

import sqlite3
import asyncpg
import sqlalchemy

# Use workers for DB operations
@worker
async def fetch_data(self):
    async with sqlite3.connect('data.db') as conn:
        cursor = conn.cursor()
        cursor.execute("SELECT * FROM users")
        return cursor.fetchall()

from textual.widgets import Static
from textual.reactive import reactive

class CustomWidget(Static):
    """A custom widget."""

    DEFAULT_CSS = '''
    CustomWidget {
        background: $primary;
        color: $text;
    }
    '''

    value = reactive(0)

    def compose(self) -> ComposeResult:
        yield Static("Custom content")

    def watch_value(self, new_value):
        """Auto-update when value changes."""
        self.update(str(new_value))