Tui Visual Design

TUI Visual Design and Aesthetic Polish

Use this skill when a terminal UI needs to look deliberate, elegant, readable, and production-grade, not merely functional. Good TUI design is the craft of using cells, text, whitespace, color, borders, glyphs, rhythm, and motion under harsh terminal constraints.

Design operating principles

1. Start with information architecture. Decide what the user must notice first, what is secondary, and what can be hidden until requested. 2. Design in cells. Every visual decision consumes fixed-width character cells. Padding, borders, scrollbars, and icons must earn their space. 3. Use fewer treatments, consistently. A polished TUI usually has one border language, one spacing scale, one heading system, and semantic color roles. 4. Prefer calm defaults. High-intensity color, heavy borders, inverse video, animation, and icons should highlight state changes or actions, not decorate every element. 5. Make degradation intentional. Every visual design should still work in no-color, ASCII, narrow-width, light theme, remote SSH, and screen-reader-friendly modes.

Visual hierarchy and composition

Create hierarchy with, in order: placement, spacing, grouping, text labels, alignment, weight, then color. Do not make color carry the entire hierarchy.

• Put the main task or current selection in the strongest visual anchor: top-left for scanning, centered only for modal or landing states.
• Reserve full borders for important regions; use whitespace or subtle separators for secondary grouping.
• Use a spacing scale such as 0, 1, 2, and 4 cells. Random padding makes TUIs look improvised.
• Give forms and empty states breathing room. Give dashboards density, but cluster related metrics and leave gutters between groups.
• Use progressive disclosure: collapsed sections, detail panes, command palettes, and help overlays keep the default screen calm.

Typography and text presentation

Terminals do not give you real fonts inside the app, but they still have typographic systems.

• Treat headings as a hierarchy: title, section label, field label, hint, status. Use predictable casing and punctuation.
• Bold is best for headings, selected labels, and important values. Dim is for optional hints only, never required text.
• Italic is inconsistent across terminals; use sparingly. Underline suggests links or focus. Strikethrough is niche. Avoid blink except for legacy compatibility indicators, and never for attention grabbing.
• Align labels left, numbers right, table text left, units consistently, and actions by interaction order.
• Truncate with intent: keep IDs unique, preserve file extensions, show start and end of paths when needed, and expose full text on focus or detail view.
• Wrap prose at word boundaries and preserve indentation for code, logs, and structured output.

Borders, boxes, and containers

Borders are punctuation. Too many boxes create visual noise.

• Use full borders for modals, focused panels, and major regions.
• Use left-only or bottom-only rules for navigation rails, active sections, and subtle grouping.
• Avoid deep nested boxes. Prefer whitespace, headings, or separators inside a bordered panel.
• Pick one border family for the product: plain ASCII, single-line, rounded, thick, or double-line. Mix only to express hierarchy.
• Padding inside a border is usually one cell horizontally. Zero padding feels cramped; excessive padding wastes terminal space.
• Shadow/depth tricks using half-blocks or dark backgrounds can look premium in controlled truecolor terminals, but need no-shadow fallback.

Color design

Use semantic roles before raw colors: primary, accent, success, warning, error, info, muted, selected, focused, disabled, border, background, surface.

• Keep a small palette. One accent plus semantic states is enough for most TUIs.
• Avoid large background fills unless building a full-screen app with theme control. Many users customize terminal backgrounds.
• Support dark and light backgrounds. Yellow, blue, dim gray, and low-saturation colors often fail on one of them.
• Downsample deliberately for 256-color and 16-color modes. In 16-color, prefer named terminal colors over fragile RGB assumptions.
• Never encode meaning by color alone. Pair red errors with words like Error, icons, placement, or borders.
• Gradients can add polish to banners, charts, and progress bars in truecolor, but must collapse to solid semantic color in constrained modes.

Charts, data visualization, and density

Terminal charts should answer a question faster than reading raw numbers.

• Horizontal bars are the safest chart: label left, value right, bar in the middle.
• Sparklines are useful for trend, not exact value. Add min/max/current text.
• Progress bars need labels, percentage or count, and a distinct incomplete region.
• Tables need alignment, padding, stable column order, and a clear focused row. Zebra striping is optional and should not replace row separators in no-color mode.
• Heat maps need legends and text alternatives because color perception and terminal palettes vary.
• For dashboards, group by decision: health, throughput, latency, errors, queue, resources. Do not fill every cell just because space exists.

Animation and motion

Motion should communicate waiting, progress, transition, or attention; otherwise it is noise.

• Use low-frequency spinners for unknown waits and determinate bars when progress is known.
• Pause or simplify animation over SSH, in CI, in logs, with reduced-motion settings, or when rendering is expensive.
• Avoid flashing more than three times per second.
• Transitions such as slide or fade can help users maintain context, but they must be interruptible and cheap.
• Smooth scrolling is attractive for local terminals; page-based movement may be better over remote links.

Icons, glyphs, and decorative elements

Glyphs improve scanability when they are predictable and optional.

• Use simple status symbols with labels: success, failure, warning, info, loading.
• Do not require Nerd Fonts or private-use glyphs. Offer --ascii or a plain icon set.
• Test emoji width and rendering before using emoji in aligned layouts.
• Use arrows and chevrons for hierarchy and navigation, but avoid ambiguous symbols in critical confirmations.
• Decorative banners, particles, and mascots should disappear in plain, narrow, CI, and accessibility modes.

Prompts and interactive elements

A beautiful prompt makes the next action obvious.

• Put validation near the field that failed, with a clear correction path.
• Show defaults and destructive consequences in text, not just color.
• Use focus indicators that survive no-color mode: prefix marker, border change, label, or cursor position.
• Keep selection menus visually stable. Avoid moving choices while the user navigates.
• Confirmation dialogs should use calm layout, explicit action labels, and safe defaults for destructive operations.
• Toasts and notifications should be short-lived only when non-critical; persistent errors need a stable region or log panel.

Framework styling defaults

• Ratatui: compose Layout constraints, Block borders, Paragraph wrapping, Table widths, and semantic Styles. Snapshot at fixed sizes and color modes.
• Textual: use CSS classes, component variants, theme variables, and transitions carefully; keep custom widgets visually consistent with built-ins.
• Bubble Tea + Lip Gloss: centralize styles, compose margins/padding/borders, and test Width/Height calculations with wide Unicode.
• Rich: define Theme roles, use tables/panels/progress consistently, and avoid nesting panels until output becomes visually heavy.
• Ink: use flex layout deliberately, centralize style tokens, and remember terminal width changes can reflow React component trees.
• Terminal.Gui: define color schemes and focus styles per view class; verify mouse and keyboard focus indicators match.
• Spectre.Console: use markup, tables, trees, rules, panels, and progress with a restrained theme and no-color fallback.

Visual anti-patterns

• Rainbow palettes with no semantic system.
• Every widget in a heavy border.
• Tiny text crammed against borders or terminal edges.
• Color-only errors, selections, or warnings.
• Center-aligned tables or numbers.
• Icons from Nerd Fonts with no fallback.
• Animated dashboards that redraw faster than data changes.
• Designs that only work at 120 columns.
• Ignoring light terminal themes, NO_COLOR, TERM=dumb, and non-TTY output.

Reference files

• references/layout-typography.md - Visual hierarchy, spacing, rhythm, typography, alignment, wrapping, and truncation.
• references/color-design.md - Semantic palettes, contrast, theme adaptation, gradients, and constrained color modes.
• references/borders-icons-prompts.md - Box drawing, containers, glyphs, icons, prompts, forms, dialogs, and notifications.
• references/charts-visualization.md - Bars, sparklines, gauges, progress, tables, trees, heat maps, and dashboard density.
• references/animation-motion.md - Spinners, motion design, transitions, scrolling, decorative effects, and performance limits.
• references/framework-styling.md - Visual styling recipes for Ratatui, Textual, Bubble Tea/Lip Gloss, Rich, Ink, Terminal.Gui, and Spectre.Console.

Animation and Motion in TUIs

When motion helps

Use motion to communicate:

• The app is alive during unknown waits.
• Determinate work is advancing.
• A view changed and the user's context should be preserved.
• A notification appeared or a background task completed.

Avoid motion as constant decoration. In terminals, every frame is text output and can cost CPU, bandwidth, battery, and readability.

Spinners

Choose spinner style by tone and compatibility:

• ASCII: - \ | /, safest and familiar.
• Dots: calm, low visual weight.
• Braille: smooth and compact, but needs Unicode fallback.
• Arc/clock: expressive, but emoji width can be unreliable.
• Custom frames: useful for brand, but test all frames for equal display width.

Keep spinner text stable. Do not rewrite long status lines at high frequency.

Progress animation

Determinate progress should update on meaningful progress, not on a fixed high-rate timer. Indeterminate bars can pulse or slide, but should slow down over remote connections and stop immediately when work completes or fails.

Transitions

Slide, fade, and expand/collapse transitions can make navigation feel spatial. Use them sparingly:

• Keep duration short.
• Allow interruption by input.
• Skip transitions in reduced-motion, CI, non-TTY, and slow-terminal modes.
• Do not animate large full-screen diffs over SSH unless throttled.

Color fades are cheaper conceptually but can generate many SGR changes. Use coarse steps rather than dozens of truecolor frames.

Scrolling and viewport motion

Smooth scrolling helps local browsing and file explorers. Page jumps are often better for logs, terminals over SSH, and screen-reader-adjacent workflows. Always keep selection visible and expose position through a scrollbar, line count, percentage, or breadcrumb.

Decorative effects

Particles, shimmer, typewriter effects, and animated borders can delight in onboarding or empty states, but they are rarely appropriate in dense work screens. They must be disableable and should not block input.

Performance and accessibility limits

• Avoid flashing more than three times per second.
• Cap redraws to the minimum that preserves perceived smoothness.
• Coalesce animation ticks with data updates.
• Pause animation when the app is unfocused if focus events are available.
• Respect reduced-motion preferences and provide a config flag.
• Stabilize tests by disabling animation, cursor blink, clocks, and random decorative frames.

Borders, Icons, Glyphs, Prompts, and Dialogs

Border families

Common border choices:

• ASCII: +---+, safest for logs, old terminals, and plain mode.
• Single-line: light, default for most panels.
• Rounded: friendly for modals and modern dashboards, but not universal.
• Double-line: strong heading or primary container; overuse feels heavy.
• Thick/block: high emphasis, selected states, or retro aesthetics.

Choose one default and one emphasis variant. Mixing many border styles makes a UI look inconsistent.

Container patterns

• Full border: major region, focused panel, modal dialog.
• Left border: active navigation item, quote, nested detail.
• Bottom border/rule: section separation, table header.
• No border: dense lists, simple forms, inline prompts.
• Tab container: when peer views share the same space; keep active tab obvious without color alone.

Avoid nested full borders deeper than one level. Inside panels, use headings, blank lines, indentation, or separators instead.

Padding and margin

A border with no padding feels cramped. One horizontal cell of padding is the default. Use vertical padding for forms, dialogs, and empty states; remove it for dense tables. Preserve at least one-cell gutters between adjacent panes.

Shadow and depth illusions

Depth can be simulated with dark right/bottom cells, half blocks, or offset panels. Use only in controlled full-screen apps, and provide no-shadow fallback. Shadows consume cells and can reduce readability on light themes.

Icons and glyphs

Use glyphs as redundant scan aids, not the only signal.

• Success: check mark plus Success or completed state text.
• Failure: cross or Error label with message.
• Warning: warning marker plus consequence.
• Loading: spinner plus action text.
• Navigation: chevrons/arrows plus indentation or labels.

Nerd Font/private-use icons are attractive for file browsers and git dashboards, but must be optional. Provide Unicode and ASCII icon sets, and never align critical tables around emoji without width tests.

Prompt styling

Prompts should make the next action unmistakable:

• Keep the question short and direct.
• Display defaults inline, such as [Y/n] or (default: main).
• Place help below or beside the prompt, not far away.
• Reserve accent color for the active input or selected option.
• Show validation directly under the field that failed.
• Preserve typed input exactly; do not surprise users with decorative transformations.

Menus and selectors

• Keep selected item position stable when possible.
• Use a prefix marker, inverse style, or border to show focus in no-color mode.
• For long menus, show count, filter text, and scroll position.
• Grid selectors work for short homogeneous options; lists are better for descriptions.

Forms and dialogs

• Align labels in one column; keep inputs in another.
• Put field-level errors next to or below the field.
• Put form-level errors near the submit action or top status region.
• Confirm destructive actions with explicit labels and safe defaults.
• Modal dialogs should trap focus, list keyboard exits, and restore previous focus on close.

Toasts and notifications

Toasts are appropriate for transient non-critical feedback. Critical errors, failed saves, and security warnings need persistent placement. In full-screen apps, maintain a notification log or status panel so messages are not lost during redraws.

Charts and Terminal Data Visualization

Visualization rules

• Every chart needs a textual summary for accessibility, logs, and no-color modes.
• Label axes or ranges unless the scale is obvious.
• Use units consistently.
• Prefer stable scales for dashboards; constantly rescaling charts hides change.
• Avoid charts when sorted numbers or a table would answer the question better.

Horizontal bars

Horizontal bars are the most robust terminal chart.

Recommended structure: label, bar, value, unit. Right-align values and keep labels truncated consistently. Use block elements for Unicode mode and #, =, or - for ASCII mode. For negative values, include a zero baseline or use separate positive/negative columns.

Vertical bars

Vertical bars can look impressive but need height. Use them for small category counts or time buckets. Add bottom labels only when they fit; otherwise use a legend or focused detail readout.

Sparklines

Sparklines show trend, not exact values. Pair them with current, min, max, and direction text. Braille or block sparklines are compact but require Unicode fallback. Keep sampling strategy stable so changes are meaningful.

Progress bars

Determinate progress should include at least one of: percentage, current/total, bytes, elapsed/remaining time, or current phase. Indeterminate progress should state what is happening and provide cancel instructions when possible. Segmented bars are useful for multi-phase work, but label segments or expose details on focus.

Gauges and meters

Use gauges for bounded values such as CPU, memory, quota, health, or confidence. Show thresholds with labels, not just color. Avoid gauge shapes that consume many rows unless they are central to the product experience.

Tables

• Separate header from rows with style or a rule.
• Align text left and numbers right.
• Keep padding predictable, usually one cell between columns.
• Freeze important identifiers when horizontal scrolling.
• Use zebra striping only as a secondary aid; selection must work without color.
• Provide sorting indicators and current sort text.

Trees and hierarchy

Tree views need clear expansion state, indentation, and selected-node context. Use ASCII tree fallbacks for box drawing. For large trees, show path breadcrumbs, match counts, and viewport position.

Heat maps and matrices

Heat maps require legends, no-color alternatives, and careful palette choice. Use symbols, intensity characters, or numeric overlays for users who cannot distinguish colors. Keep row and column labels visible when scrolling.

Dashboard density

A dashboard should support decisions, not merely display metrics. Group related cards, keep refresh cadence visible, and distinguish stale data from live data. Prefer drill-down detail panes over stuffing every metric into the first screen.

Terminal Color Design

Semantic palette roles

Define roles before choosing RGB values:

• text, muted, disabled
• background, surface, surface-muted, border
• primary, accent, selected, focused
• success, warning, error, info
• chart-1 through chart-n

Map widgets to roles, not raw colors. This allows dark/light themes, 16-color fallback, and user customization without rewriting components.

Color hierarchy

• Main content should remain readable in default terminal foreground/background.
• Accent color should be rare enough to guide the eye.
• Error and warning colors should be reserved for actual problems.
• Disabled and muted content must still meet readability needs when the text is required.
• Avoid mixing multiple saturated colors in the same small panel.

Backgrounds

Use background colors carefully because many users tune terminal backgrounds for comfort.

• No background fill: safest for CLI output and mixed scrollback.
• Subtle surface fill: useful for selected rows, focused inputs, and cards when contrast is verified.
• Full-screen fill: acceptable for immersive TUIs that own the alternate screen and have theme control.
• Danger fill: reserve for destructive confirmation or critical alerts, with text labels and fallback.

Dark and light themes

Design palettes as paired themes rather than assuming a dark terminal. Verify yellow, blue, purple, and dim gray on both light and dark backgrounds. When terminal background detection is unavailable or blocked, choose conservative colors and expose a theme override.

16-color, 256-color, and truecolor

• In truecolor, choose colors with enough luminance separation, not just hue separation.
• In 256-color, test the downsampled palette; some hues collapse together.
• In 16-color, prefer semantic terminal colors and high-intensity variants cautiously.
• In no-color, preserve all meaning through labels, prefixes, icons, borders, or ordering.

Example fallback palette:

Mapping function shape:

resolve(role, color_level, theme):
  if color_level == none: return no_color_style(role)
  if color_level == 16: return theme.roles[role].ansi16
  if color_level == 256: return nearest_ansi256(theme.roles[role].rgb)
  return theme.roles[role].rgb

Never use fallback color alone as the semantic signal. The no-color column is part of the design contract, not an afterthought.

Contrast and accessibility

Aim for WCAG-style contrast: 4.5:1 for text and 3:1 for meaningful borders, focus outlines, and chart marks. Terminal color names are user-controlled, so test common themes and provide no-color modes. Do not rely on red/green alone; color vision deficiencies can make them indistinguishable.

Gradients and fades

Gradients can make banners, progress bars, and charts feel polished in truecolor terminals. Keep them decorative or redundant:

• Provide a single-color fallback.
• Avoid gradients behind text unless contrast is controlled.
• Use short gradients; long truecolor ramps generate many escape sequences.
• Over SSH or slow terminals, prefer static solid colors.

Theme adaptation

Support explicit theme selection before clever automatic detection. If using OSC palette or background queries, time out quickly and treat failure as normal. Respect NO_COLOR, CLICOLOR, CLICOLOR_FORCE, FORCE_COLOR, TERM=dumb, non-TTY output, and app-level --color=auto|always|never.

Framework-Specific Styling Recipes

Fetch current official docs when exact APIs matter. Use these as design defaults and review heuristics.

Ratatui

• Centralize Style values by semantic role.
• Use Layout constraints for rhythm instead of fixed coordinates.
• Use Block borders selectively; avoid nesting bordered Blocks.
• Style focused widgets through border, title, or prefix changes, not only color.
• Use Gauge, BarChart, Sparkline, Table, and List with textual labels.
• Snapshot widgets at multiple widths and color modes.

Textual

• Treat CSS variables and classes as the design system.
• Use component classes for variants: compact, danger, focused, muted.
• Prefer built-in layout containers before custom positioning.
• Keep animations short and respect reduced-motion settings.
• Use compound widgets to package consistent label, input, help, and error presentation.

Bubble Tea and Lip Gloss

• Keep a style module with semantic Lip Gloss styles.
• Compose margins, padding, borders, and widths deliberately; test calculated widths.
• Use Bubbles components for common controls, then wrap with consistent styling.
• Remember View() returns strings: ANSI width, wide glyphs, and newlines affect layout.
• Downsample colors with terminal-aware libraries when possible.

Rich

• Define a Theme for semantic roles and reuse it across console, tables, panels, logs, and progress.
• Use Table for alignment, Panel for emphasis, Rule for separation, and Progress for tasks.
• Avoid panel nesting in scrollback output; it becomes visually heavy.
• Use Console color-system detection and plain output when not attached to a TTY.

Ink

• Use Flexbox intentionally: rows for toolbars, columns for sidebars, fixed sizes for status bars.
• Centralize color/style tokens rather than scattering Chalk calls.
• Keep render functions pure and stable; animation should come from state/timers.
• Test resize and Unicode width behavior in component tests and PTY runs.

Terminal.Gui

• Define color schemes for normal, focused, hotkey, disabled, error, and dialog states.
• Verify focus indicators for keyboard-only users.
• Use layout primitives rather than hard-coded absolute positions where possible.
• Keep mouse affordances secondary to keyboard behavior.

Spectre.Console

• Use markup styles as semantic roles and keep them consistent across prompts, tables, trees, rules, panels, and progress.
• Prefer Table, Tree, BarChart, BreakdownChart, Panel, Rule, Status, and Progress before custom ANSI.
• Ensure prompts and confirmations expose defaults and safe choices in text.
• Honor no-color and redirected-output behavior.

Cross-framework polish checklist

• One spacing scale.
• One border language plus one emphasis variant.
• Semantic color roles with dark, light, 16-color, and no-color mappings.
• Focus visible without color.
• Text measured by display cells.
• Snapshots for normal, narrow, tiny, and wide terminals.
• Animation disabled in tests and reduced-motion modes.

Layout, Visual Hierarchy, and Typography

Composition checklist

• Define the primary user question for each view, then place the answer in the strongest location.
• Use a consistent spacing scale: 0 for dense tables, 1 for panels and lists, 2 for section gaps, 4 for empty states or landing screens.
• Keep gutters between split panes. If panes touch, add a separator or contrasting heading.
• Leave at least one cell between text and a border when space allows.
• Align related elements on the same columns across screens to create rhythm.
• Use progressive disclosure: summary first, details on focus, expanded rows, side panels, or command palette.

Visual weight ladder

Use weight deliberately from quiet to loud:

1. Plain text and whitespace. 2. Muted text, small labels, section spacing. 3. Separators or single-side borders. 4. Bold headings or selected values. 5. Full borders, inverse video, or accent color. 6. Modal overlay, danger color, or high-intensity fill.

If many items use levels 5-6, nothing is important.

Information density patterns

• Minimal prompts: one question, one hint, one error region, one action path.
• Spacious forms: labels in a stable column, inputs aligned, help below focused field, group separators.
• Dense dashboards: compact cards, abbreviated labels, clear units, grouped metrics, detail drill-down.
• Data explorers: table/list takes primary space; filters, status, and help remain peripheral.

Common layout recipes

Use sketches during design review. They expose impossible density before implementation.

Sidebar/detail          Table/detail             Wizard
┌──────┬─────────┐      ┌────────────────┐       ┌─ Step 2 of 4 ───┐
│ nav  │ detail  │      │ filter         │       │ Label [____]    │
│ > a  │ title   │      ├────┬────┬──────┤       │ Error near field│
│   b  │ body    │      │ >  │ id │ msg  │       │ Back Next Cancel│
└──────┴─────────┘      ├────┴────┴──────┤       └─────────────────┘
footer: quit/help       │ selected detail│
                        └────────────────┘

Dashboard               Tiny fallback
┌ CPU ┐ ┌ Mem ┐         App needs 60x15.
│ 42% │ │ 7G  │         Current: 32x8.
└─────┘ └─────┘         Use --plain or --json.
┌ logs/status ─┐        q quit
└──────────────┘

Recipe rules:

• Sidebar/detail: separate navigation selection from detail scroll; collapse navigation first on narrow screens.
• Table/detail: render only visible rows; keep full selected content in a detail pane.
• Wizard: show progress, field-local validation, Back/Next/Cancel, and non-interactive equivalents.
• Dashboard: include units and text values; throttle updates and support reduced motion.
• Tiny fallback: define minimum dimensions and keep quit/recovery instructions visible.

Terminal typography

Terminal apps inherit user fonts. Do not assume Nerd Fonts, ligatures, or emoji rendering. Recommend programming fonts for users only when documenting setup; the app itself must survive ordinary monospace fonts.

• Use title case or sentence case consistently.
• Keep headings short; terminals punish verbose labels.
• Use bold for headings and key values. Use dim for hints only.
• Avoid blink. Use italic and underline only where terminal support is acceptable.
• Use monospace affordances: columns, indentation, rulers, and stable prefixes.

Alignment rules

• Left-align text, commands, labels, filenames, and descriptions.
• Right-align numbers, durations, counts, percentages, and sizes.
• Align decimals when comparing numeric values.
• Put units in a consistent suffix column or repeat them in every value when scanning matters.
• Center only banners, empty states, and modal titles; never center dense tabular content.

Wrapping and truncation

• Wrap prose on word boundaries and preserve paragraphs.
• Do not wrap table cells unless row height expansion is part of the design.
• For paths, prefer middle truncation: keep root or context plus basename and extension.
• For hashes and IDs, keep enough prefix/suffix to distinguish values.
• For commands, preserve leading tokens and show continuation markers.
• Expose full truncated content in a detail pane, tooltip-like help, copy action, or expanded row.