stevengonsalvez/tui-style-guide

TUI Style Guide

Premium styling patterns for agents-in-a-box TUI components.

Color Palette

Primary Colors

// Core accent colors
const CORNFLOWER_BLUE: Color = Color::Rgb(100, 149, 237);  // Primary accent, borders, section titles
const GOLD: Color = Color::Rgb(255, 215, 0);               // Important CTAs, emphasis, highlights
const SELECTION_GREEN: Color = Color::Rgb(100, 200, 100);  // Active selections, success states
const WARNING_ORANGE: Color = Color::Rgb(255, 165, 0);     // Warnings, alternate modes

// Background colors
const DARK_BG: Color = Color::Rgb(25, 25, 35);             // Main UI background
const INPUT_BG: Color = Color::Rgb(35, 35, 45);            // Input field backgrounds
const PANEL_BG: Color = Color::Rgb(30, 30, 40);            // Panel/nested container backgrounds
const LIST_HIGHLIGHT_BG: Color = Color::Rgb(40, 40, 60);   // List item hover/selection

// Text colors
const SOFT_WHITE: Color = Color::Rgb(220, 220, 230);       // Primary text
const MUTED_GRAY: Color = Color::Rgb(120, 120, 140);       // Secondary text, hints
const MEDIUM_GRAY: Color = Color::Rgb(180, 180, 180);      // Tertiary text
const DARK_GRAY: Color = Color::Rgb(100, 100, 100);        // Disabled/faded text

// Accent/status colors
const PROGRESS_CYAN: Color = Color::Rgb(100, 200, 230);    // Loading/processing
const LIGHT_BLUE: Color = Color::Rgb(100, 200, 255);       // Info highlights
const SUBDUED_BORDER: Color = Color::Rgb(60, 60, 80);      // Separator lines, secondary borders

Border Styles

Standard Panel Border

Block::default()
    .borders(Borders::ALL)
    .border_type(BorderType::Rounded)
    .border_style(Style::default().fg(CORNFLOWER_BLUE))
    .style(Style::default().bg(DARK_BG))

Active/Focused Border

.border_style(Style::default().fg(SELECTION_GREEN))

Muted/Secondary Border

.border_style(Style::default().fg(SUBDUED_BORDER))

Title Patterns

Primary Title with Icon

.title(Line::from(vec![
    Span::styled(" folder_icon ", Style::default().fg(GOLD)),
    Span::styled("Section Title",
        Style::default().fg(GOLD).add_modifier(Modifier::BOLD))
]))

Title with Count Badge

.title(Line::from(vec![
    Span::styled(" Section ", Style::default().fg(SOFT_WHITE)),
    Span::styled(
        format!("({})", count),
        Style::default().fg(CORNFLOWER_BLUE).add_modifier(Modifier::BOLD)
    )
]))

List Item Patterns

Selected Item

// Prefix
Span::styled("  > ", Style::default().fg(SELECTION_GREEN))
// Text
Span::styled(&item_text,
    Style::default()
        .fg(SELECTION_GREEN)
        .add_modifier(Modifier::BOLD))

Unselected Item

// Prefix (spacing to align with selected)
Span::raw("    ")
// Text
Span::styled(&item_text, Style::default().fg(SOFT_WHITE))

List Highlight Style

.highlight_style(Style::default().bg(LIST_HIGHLIGHT_BG))
.highlight_symbol("> ")

Status Indicators

Icon Patterns

| Status | Icon | Color | |--------|------|-------| | Running | Green circle | Green | | Stopped | Red circle | Red | | Idle | Yellow circle | Yellow | | Error | X mark | Red | | Success | Checkmark | Green | | Warning | Warning sign | Orange | | Info | Info sign | Cyan | | Loading | Refresh | Cyan |

Status Badge Style

Span::styled(
    format!("[{}]", status_symbol),
    Style::default()
        .fg(status_color)
        .add_modifier(Modifier::BOLD)
)

File/Folder Icons

fn get_file_icon(filename: &str) -> &'static str {
    match filename {
        f if f.ends_with(".rs") => "rust",
        f if f.ends_with(".py") => "python",
        f if f.ends_with(".js") || f.ends_with(".jsx") => "js",
        f if f.ends_with(".ts") || f.ends_with(".tsx") => "ts",
        f if f.ends_with(".md") => "markdown",
        f if f.ends_with(".json") => "json",
        f if f.ends_with(".toml") || f.ends_with(".yaml") || f.ends_with(".yml") => "config",
        f if f.ends_with(".sh") || f.ends_with(".bash") => "shell",
        f if f.ends_with(".html") => "html",
        f if f.ends_with(".css") || f.ends_with(".scss") => "css",
        f if f.ends_with(".go") => "go",
        f if f.ends_with(".java") => "java",
        _ => "file",
    }
}

// Folder icons
const FOLDER_ICON: &str = "folder";
const FOLDER_OPEN_ICON: &str = "folder-open";

Tree Characters

// Expand/collapse indicators
const EXPANDED: &str = "v";
const COLLAPSED: &str = ">";
const LEAF: &str = ">";

// Tree lines
const TREE_BRANCH: &str = "|-";
const TREE_LAST: &str = "`-";
const TREE_VERTICAL: &str = "|";

Keyboard Help Text

Standard Format

Line::from(vec![
    Span::styled("Up/Down", Style::default().fg(GOLD).add_modifier(Modifier::BOLD)),
    Span::styled(" Navigate", Style::default().fg(MUTED_GRAY)),
    Span::styled("  |  ", Style::default().fg(SUBDUED_BORDER)),
    Span::styled("Enter", Style::default().fg(GOLD).add_modifier(Modifier::BOLD)),
    Span::styled(" Select", Style::default().fg(MUTED_GRAY)),
])

Input Fields

Active Input

Block::default()
    .borders(Borders::ALL)
    .border_type(BorderType::Rounded)
    .border_style(Style::default().fg(SELECTION_GREEN))
    .style(Style::default().bg(INPUT_BG))

// Cursor character
Span::styled("_", Style::default().fg(SELECTION_GREEN))

Mode/Card Selection

Selected Card

Block::default()
    .borders(Borders::ALL)
    .border_type(BorderType::Rounded)
    .border_style(Style::default().fg(SELECTION_GREEN))
    .style(Style::default().bg(Color::Rgb(35, 45, 35)))  // Green tint

Unselected Card

Block::default()
    .borders(Borders::ALL)
    .border_type(BorderType::Rounded)
    .border_style(Style::default().fg(Color::Rgb(70, 70, 90)))
    .style(Style::default().bg(PANEL_BG))

Git Status Colors

const GIT_ADDED: Color = Color::Green;
const GIT_MODIFIED: Color = Color::Yellow;
const GIT_DELETED: Color = Color::Red;
const GIT_RENAMED: Color = Color::Blue;
const GIT_UNTRACKED: Color = Color::Magenta;

Diff View Colors

// Line prefixes
const DIFF_ADDITION: Color = Color::Green;      // Lines starting with +
const DIFF_DELETION: Color = Color::Red;        // Lines starting with -
const DIFF_HUNK: Color = Color::Cyan;           // @@ lines
const DIFF_FILE_HEADER: Color = Color::Yellow;  // +++ and --- lines
const DIFF_CONTEXT: Color = Color::White;       // Unchanged lines

Markdown Viewer Colors

const MD_HEADING1: Style = Style::default()
    .fg(Color::Cyan)
    .add_modifier(Modifier::BOLD | Modifier::UNDERLINED);
const MD_HEADING2: Style = Style::default()
    .fg(Color::Cyan)
    .add_modifier(Modifier::BOLD);
const MD_HEADING3: Style = Style::default()
    .fg(Color::Blue)
    .add_modifier(Modifier::BOLD);
const MD_CODE_BLOCK: Style = Style::default()
    .fg(Color::Green)
    .bg(Color::Rgb(30, 30, 30));
const MD_CODE_HEADER: Style = Style::default()
    .fg(Color::Yellow)
    .add_modifier(Modifier::BOLD);
const MD_LINK: Style = Style::default()
    .fg(Color::Blue)
    .add_modifier(Modifier::UNDERLINED);
const MD_BLOCKQUOTE: Style = Style::default()
    .fg(Color::Gray)
    .add_modifier(Modifier::ITALIC);

Layout Guidelines

Centered Modal (Standard)

• Width: 80% of terminal width
• Height: 70% of terminal height

Split Pane Ratios

• Sessions/Logs: 40/60
• Equal split: 50/50

Internal Spacing

• Panel margins: 1px
• Content padding: Use Constraint::Length(N) for headers/footers
• Flexible content: Constraint::Min(0)

Common Imports

use ratatui::{
    layout::{Constraint, Direction, Layout, Rect},
    style::{Color, Modifier, Style},
    text::{Line, Span},
    widgets::{Block, Borders, BorderType, List, ListItem, ListState, Paragraph, Tabs, Wrap},
    Frame,
};

---

Usage: Reference this guide when styling new TUI components to maintain visual consistency across the application.