tui-visual-design

What this skill does

# 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 `Style`s. 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.