OpenParable
Skip to content
← Back to skills

TUI Design System

Design

TUI Design System is an Agent Skill for design published in the pymc-labs/decision-lab repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Visual language and UX patterns for Textual TUI applications in dlab

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/pymc-labs/decision-lab/blob/HEAD/.claude/skills/tui-design/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/tui-design-system, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

TUI Design System

Design decisions for all Textual TUI apps in this project. Follow these patterns when creating or modifying TUI screens.

Theme & Layout

  • Theme: monokai (set on App class: theme = "monokai")
  • Screen alignment: align: left bottom — content anchors to bottom-left, where terminal users look
  • Container width: width: 66% — two-thirds of terminal
  • Container height: height: auto — only as tall as content. Add max-height: 80% on VerticalScroll containers to preserve scrollability
  • No chrome: Never use Header() or Footer() — the terminal stays dark above and to the right of the content

Accent Blocks

Every interactive element gets a colored left border + surface background:

Input {
    border: none;
    border-left: tall $accent;
    height: 1;
    padding: 0 1;
    background: $surface;
    &:focus { border: none; border-left: tall $accent; }
}
OptionList {
    border: none;
    border-left: tall $accent;
    background: $surface;
    scrollbar-size: 1 1;
}

Checkbox groups use a .cb-group wrapper with the same treatment:

.cb-group {
    border-left: tall $accent;
    background: $surface;
    padding: 0 1;
}

Checkboxes

Use DpackCheckbox (subclass of Checkbox) with custom glyphs:

  • Unchecked: ▢
  • Checked: ▣
  • Override BUTTON_LEFT = "", BUTTON_RIGHT = ""
  • Override _button property to swap glyph based on self.value

CSS for visibility on dark backgrounds:

Checkbox > .toggle--button { color: $text-muted; }
Checkbox.-on > .toggle--button { color: $success; }

Navigation

Arrow Keys

App-level bindings for field navigation:

Binding("down", "focus_next", show=False),
Binding("up", "focus_previous", show=False),
Binding("left", "focus_previous", show=False),
Binding("right", "focus_next", show=False),

These only fire when the focused widget doesn't consume the key (Input consumes left/right for cursor, OptionList consumes up/down for selection).

Tab Behavior

  • Normal widgets: Tab moves to next focusable element (default Textual behavior)
  • Inside .cb-group: Tab jumps OUT of the container to the next element outside. Implemented via DpackCheckbox.action_tab_out() which walks ancestors to find the .cb-group parent, then focuses the first widget after it in screen.focus_chain
  • Selection widgets: Show "Tab to continue" hint via :focus-within:
.option-hint { display: none; color: $text-muted; text-style: italic; height: 1; }
.selection-group:focus-within .option-hint { display: block; }

Button Order

  • Primary action first in DOM (focus order): Next, Create, etc.
  • Visually on the right via dock: right:
#next-btn, #create-btn, #done-btn, #skip-btn, #keep-btn { dock: right; }
  • Back button stays in normal flow (left side)
  • Nav-bar: Horizontal(classes="nav-bar") with height: 1

OptionList Selection

When user selects an item in an OptionList (e.g. package manager), auto-advance focus to the next element via on_option_list_option_selected → self.screen.focus_next().

Typography

  • Step indicator: [b]Step N of M[/b] — Title as .field-label
  • Field labels: .field-label with margin-top: 1
  • Descriptions/hints: .field-hint and .cb-desc with color: $text-muted; text-style: italic
  • Errors: .error-label with color: $error
  • Section dividers: .section-divider with color: $accent

Buttons

Button {
    min-width: 10;
    border: none;
    background: $surface;
    &:hover { background: $primary; }
    &.-success { background: $success-muted; &:hover { background: $success; } }
}

All variants have border: none. No special styling for -primary variant (buttons look uniform).

Collision Detection Pattern

When user input might conflict with existing state (e.g. decision-pack name already exists):

  1. Show red error label
  2. Show a "Delete & Overwrite" button (variant="error", with color: $text CSS override for visibility)
  3. Place both in a Horizontal(id="collision-bar") so they sit side by side
  4. On overwrite click: set state flag, show green confirmation, hide button
  5. Reset on input change

Creation Flow Pattern

For long-running operations (e.g. generating files, downloading):

  1. Run in @work(thread=True) method
  2. Accept on_progress: Callable[[str], None] callback
  3. Update UI via app.call_from_thread(label.update, message)
  4. On success: show walkthrough/results
  5. On error: show error + recovery options (Go Back, Keep Partial, Abort)

Color Palette (Connect TUI)

Uses monokai hex colors for consistency:

RoleColorHex
Process startmonokai cyan#66D9EF
Completionmonokai green#A6E22E
Action/toolmonokai orange#FD971F
Errormonokai redbold #F92672
Selection/identitymonokai purple#AE81FF
Background infomonokai comment#75715E
Main textmonokai foreground#F8F8F2