tui-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TUI Design System

TUI设计系统

Universal design patterns for building exceptional terminal user interfaces. Framework-agnostic — works with Ratatui, Ink, Textual, Bubbletea, or any TUI toolkit.

Core philosophy: TUIs earn their power through spatial consistency, keyboard fluency, and information density that respects human attention. Design for the expert's speed without abandoning the beginner's discoverability.

用于构建优秀终端用户界面的通用设计模式。与框架无关，可配合Ratatui、Ink、Textual、Bubbletea或任何TUI工具包使用。

核心理念： TUI的强大之处来源于空间一致性、流畅的键盘操作，以及符合人类注意力习惯的信息密度。在兼顾专家操作速度的同时，不牺牲新手的可发现性。

TUI Design Process

TUI设计流程

dot

digraph tui_design {
    rankdir=TB;
    "What are you building?" [shape=diamond];
    "Select layout paradigm" [shape=box];
    "Design interaction model" [shape=box];
    "Define visual system" [shape=box];
    "Validate against anti-patterns" [shape=box];
    "Ship it" [shape=doublecircle];

    "What are you building?" -> "Select layout paradigm";
    "Select layout paradigm" -> "Design interaction model";
    "Design interaction model" -> "Define visual system";
    "Define visual system" -> "Validate against anti-patterns";
    "Validate against anti-patterns" -> "Ship it";
}

dot

digraph tui_design {
    rankdir=TB;
    "What are you building?" [shape=diamond];
    "Select layout paradigm" [shape=box];
    "Design interaction model" [shape=box];
    "Define visual system" [shape=box];
    "Validate against anti-patterns" [shape=box];
    "Ship it" [shape=doublecircle];

    "What are you building?" -> "Select layout paradigm";
    "Select layout paradigm" -> "Design interaction model";
    "Design interaction model" -> "Define visual system";
    "Define visual system" -> "Validate against anti-patterns";
    "Validate against anti-patterns" -> "Ship it";
}

1. Layout Paradigm Selector

1. 布局范式选择器

Choose your primary layout based on what you're building:

App Type	Paradigm	Examples
File manager	Miller Columns	yazi, ranger
Git / DevOps tool	Persistent Multi-Panel	lazygit, lazydocker
System monitor	Widget Dashboard	btop, bottom, oxker
Data browser / K8s	Drill-Down Stack	k9s, diskonaut
SQL / HTTP client	IDE Three-Panel	harlequin, posting
Shell augmentation	Overlay / Popup	atuin, fzf
Log / event viewer	Header + Scrollable List	htop, tig

根据你要构建的应用选择主布局：

应用类型	范式	示例
文件管理器	米勒列	yazi, ranger
Git / DevOps工具	固定多面板	lazygit, lazydocker
系统监视器	部件仪表盘	btop, bottom, oxker
数据浏览器 / K8s工具	下钻堆叠	k9s, diskonaut
SQL / HTTP客户端	IDE三面板	harlequin, posting
Shell增强工具	浮层/弹窗	atuin, fzf
日志/事件查看器	头部+可滚动列表	htop, tig

Persistent Multi-Panel

固定多面板

All panels visible simultaneously. Focus shifts between them. Users build spatial memory — "branches are always top-left."

┌─ Status ──┬─────────── Detail ──────────┐
├─ Files ───┤                              │
│ > file.rs │  diff content here...        │
│   main.rs │                              │
├─ Branches ┤                              │
│ * main    │                              │
│   feat/x  │                              │
├─ Commits ─┤                              │
│ abc1234   │                              │
└───────────┴──────────────────────────────┘
  [q]uit [c]ommit [p]ush [?]help

When to use: Multi-faceted tools where users need simultaneous context (git clients, container managers, monitoring). Key rule: Panels maintain fixed positions across sessions. Never rearrange without user action.

所有面板同时可见，焦点在面板间切换，用户可以建立空间记忆——比如「分支列表永远在左上角」。

┌─ Status ──┬─────────── Detail ──────────┐
├─ Files ───┤                              │
│ > file.rs │  diff content here...        │
│   main.rs │                              │
├─ Branches ┤                              │
│ * main    │                              │
│   feat/x  │                              │
├─ Commits ─┤                              │
│ abc1234   │                              │
└───────────┴──────────────────────────────┘
  [q]uit [c]ommit [p]ush [?]help

适用场景： 用户需要同时查看多维度上下文的多功能工具（Git客户端、容器管理器、监控工具）。 核心规则： 面板在会话间保持固定位置，未经用户操作永远不会自动重排。

Miller Columns

米勒列

Three-pane past/present/future navigation. Parent directory (left), current (center), preview (right).

┌── Parent ──┬── Current ──┬── Preview ────────┐
│   ..       │ > config/   │ port: 8080        │
│   src/     │   lib/      │ host: localhost    │
│ > config/  │   main.rs   │ log_level: debug   │
│   tests/   │   mod.rs    │ db_url: postgres://│
└────────────┴─────────────┴───────────────────┘

When to use: Hierarchical data navigation (file systems, tree structures, nested configs). Key rule: Preview pane content adapts to selection type — code gets highlighting, images render, directories show contents.

三栏式「过去/现在/未来」导航结构：父目录（左）、当前目录（中）、预览（右）。

┌── Parent ──┬── Current ──┬── Preview ────────┐
│   ..       │ > config/   │ port: 8080        │
│   src/     │   lib/      │ host: localhost    │
│ > config/  │   main.rs   │ log_level: debug   │
│   tests/   │   mod.rs    │ db_url: postgres://│
└────────────┴─────────────┴───────────────────┘

适用场景： 层级数据导航（文件系统、树形结构、嵌套配置）。 核心规则： 预览面板内容随选中项类型适配——代码自动高亮、图片自动渲染、目录自动展示内容。

Drill-Down Stack

下钻堆叠

Enter

descends,

Esc

ascends. Browser-like navigation through hierarchical data.

When to use: Deep hierarchies where showing all levels simultaneously is impractical (Kubernetes resources, database schemas). Key rule: Always show the current navigation path as a breadcrumb. Provide

:resource

command-mode for direct jumps.

按

Enter

向下层级导航，按

Esc

返回上一级，类似浏览器的层级数据导航模式。

适用场景： 同时展示所有层级不现实的深层级结构（Kubernetes资源、数据库 schema）。 核心规则： 始终用面包屑展示当前导航路径，提供

:resource

命令模式支持直接跳转。

Widget Dashboard

部件仪表盘

Self-contained widget panels with independent data. All information visible at once, no navigation required.

┌─── CPU ──────────────┬─── Memory ──────────┐
│ ▁▂▃▅▇█▇▅▃▂▁▂▃▅▇     │ ████████░░ 78%      │
│ core0: 45% core1: 67%│ 12.4G / 16.0G       │
├─── Network ──────────┼─── Disk ────────────┤
│ ▲ 1.2 MB/s  ▼ 340KB/s│ /: 67%  /home: 45%  │
├─── Processes ────────┴─────────────────────┤
│ PID   USER  CPU%  MEM%  CMD                 │
│ 1234  root  23.4  4.5   postgres             │
└─────────────────────────────────────────────┘

When to use: Monitoring, real-time status, system dashboards. Key rule: Each widget is self-contained with its own title. Use braille/block characters for high-density data.

独立数据的自包含部件面板，所有信息一次性可见，无需额外导航。

┌─── CPU ──────────────┬─── Memory ──────────┐
│ ▁▂▃▅▇█▇▅▃▂▁▂▃▅▇     │ ████████░░ 78%      │
│ core0: 45% core1: 67%│ 12.4G / 16.0G       │
├─── Network ──────────┼─── Disk ────────────┤
│ ▲ 1.2 MB/s  ▼ 340KB/s│ /: 67%  /home: 45%  │
├─── Processes ────────┴─────────────────────┤
│ PID   USER  CPU%  MEM%  CMD                 │
│ 1234  root  23.4  4.5   postgres             │
└─────────────────────────────────────────────┘

适用场景： 监控、实时状态展示、系统仪表盘。 核心规则： 每个部件都是自包含的，自带标题。使用盲文/块字符展示高密度数据。

IDE Three-Panel

IDE三面板

Sidebar (left), editor/main (center), detail/output (bottom). Tab bar along top.

When to use: Editing-focused tools (SQL clients, HTTP tools, config editors). Key rule: Sidebar toggles with a single key. Center panel supports tabs. Bottom panel can expand to full height.

侧边栏（左）、编辑器/主内容区（中）、详情/输出区（底），顶部有标签栏。

适用场景： 以编辑为核心的工具（SQL客户端、HTTP工具、配置编辑器）。 核心规则： 侧边栏可通过单键切换显示/隐藏，中心面板支持标签页，底部面板可扩展到全高。

Overlay / Popup

浮层/弹窗

TUI appears on demand over the shell, disappears after use.

When to use: Shell augmentations (history search, file picker, command palette). Key rule: Configurable height. Return selection to the caller. Never disrupt scrollback.

TUI按需在Shell上方弹出，使用后自动消失。

适用场景： Shell增强工具（历史搜索、文件选择器、命令面板）。 核心规则： 高度可配置，选中结果返回给调用方，永远不破坏Shell回滚历史。

Header + Scrollable List

头部+可滚动列表

Fixed header with meters/stats, scrollable data below, function bar at bottom.

When to use: Single-list tools with metadata (process viewers, log viewers, sorted listings). Key rule: The header creates a natural "overview then detail" reading flow. Sort by the most actionable dimension by default.

固定头部展示指标/统计数据，下方是可滚动数据，底部是功能栏。

适用场景： 带元数据的单列表工具（进程查看器、日志查看器、排序列表）。 核心规则： 头部符合「先概览后详情」的自然阅读流，默认按最高可操作维度排序。

2. Responsive Terminal Design

2. 响应式终端设计

Terminals resize. Your TUI must handle it gracefully.

Strategy	When
Proportional split	Panels maintain percentage ratios on resize
Priority collapse	Less important panels hide first below minimum width
Stacking	Panels collapse to title-only bars, active one expands (zellij pattern)
Breakpoint modes	Switch layout entirely below a threshold (e.g., multi-panel → single panel)
Minimum size gate	Display "terminal too small" if below usable minimum

Rules:

Define a minimum terminal size (typically 80x24). Below that, show a resize message.
Never crash on resize. Handle
```
SIGWINCH
```
gracefully.
Use constraint-based layouts (percentages, min/max, ratios) — not absolute positions.
Test at 80x24, 120x40, and 200x60 to verify scaling.

终端尺寸会变化，你的TUI必须优雅适配这种变化。

适配策略	适用场景
比例拆分	调整大小时面板保持百分比占比
优先级折叠	低于最小宽度时，优先级低的面板先隐藏
堆叠	面板折叠为仅标题栏，激活的面板自动展开（zellij模式）
断点模式	低于阈值时完全切换布局（例如多面板→单面板）
最小尺寸限制	低于可用最小尺寸时展示「终端尺寸过小」提示

规则：

定义最小终端尺寸（通常是80x24），低于该尺寸时展示调整大小提示。
永远不要因为调整大小崩溃，优雅处理
```
SIGWINCH
```
信号。
使用基于约束的布局（百分比、最小/最大值、比例），不要用绝对位置。
在80x24、120x40、200x60三种尺寸下测试缩放效果。

3. Interaction Model

3. 交互模型

Navigation Style Selector

导航风格选择器

App Complexity	Recommended Model
Single-purpose, <20 actions	Direct keybinding (every key = action)
Multi-view, complex	Vim-style modes + contextual footer
IDE-like, many features	Command palette + tabs + vim motions
Data browser	Drill-down + fuzzy search + `:` command mode

应用复杂度	推荐模型
单用途、操作数<20	直接键位绑定（每个键对应一个操作）
多视图、复杂	Vim风格模式+上下文页脚
类IDE、功能丰富	命令面板+标签页+Vim操作
数据浏览器	下钻+模糊搜索+ `:` 命令模式

Keyboard Design Layers

键盘设计层级

Design keybindings in four progressive layers:

Layer	Keys	Audience	Always show?
L0: Universal	Arrow keys, Enter, Esc, q	Everyone	Yes (footer)
L1: Vim motions	hjkl, /, ?, :, gg, G	Intermediate	Yes (footer)
L2: Actions	Single mnemonics: d(elete), c(ommit), p(ush)	Regular users	On `?` help
L3: Power	Composed commands, macros, custom bindings	Power users	Docs only

Keybinding conventions (lingua franca):

```
j
```
/
```
k
```
— move down/up
```
h
```
/
```
l
```
— move left/right (or collapse/expand)
```
/
```
— search
```
?
```
— help overlay
```
:
```
— command mode
```
q
```
— quit (or
```
Esc
```
to go back one level)
```
Enter
```
— select / confirm / drill in
```
Tab
```
— switch focus between panels
```
Space
```
— toggle selection
```
g
```
/
```
G
```
— jump to top/bottom

Never bind:

Ctrl+C

(interrupt),

Ctrl+Z

(suspend),

Ctrl+\

(quit signal). These belong to the terminal.

按四个渐进层级设计键位绑定：

层级	按键	适用人群	是否始终展示？
L0: 通用	方向键、Enter、Esc、q	所有用户	是（页脚展示）
L1: Vim操作	hjkl、/、?、:、gg、G	中级用户	是（页脚展示）
L2: 操作	单字母助记键：d(elete)、c(ommit)、p(ush)	常规用户	按 `?` 展示帮助
L3: 高阶	组合命令、宏、自定义绑定	高级用户	仅文档展示

键位绑定通用约定（通用语）：

```
j
```
/
```
k
```
— 向下/上移动
```
h
```
/
```
l
```
— 向左/右移动（或折叠/展开）
```
/
```
— 搜索
```
?
```
— 帮助浮层
```
:
```
— 命令模式
```
q
```
— 退出（或
```
Esc
```
返回上一级）
```
Enter
```
— 选中/确认/下钻
```
Tab
```
— 在面板间切换焦点
```
Space
```
— 切换选中状态
```
g
```
/
```
G
```
— 跳转到顶部/底部

绝对不要绑定：

Ctrl+C

（中断）、

Ctrl+Z

（挂起）、

Ctrl+\

（退出信号），这些属于终端原生快捷键。

Focus Management

焦点管理

Only one widget receives keyboard input at a time
Tab cycles focus forward, Shift+Tab backward
Focus indicator: highlighted border, color change, or cursor presence
Unfocused panels: dimmed or thinner borders
Modal dialogs create focus traps — background receives no events
Nested focus: outer container routes events to focused child

同一时间只有一个部件接收键盘输入
Tab 正向循环切换焦点，Shift+Tab 反向循环
焦点指示器：高亮边框、颜色变化、光标显示
失焦面板：变暗或使用更细的边框
模态对话框创建焦点陷阱，背景不接收任何事件
嵌套焦点：外层容器将事件路由到聚焦的子部件

Search & Filtering

搜索与过滤

The universal pattern: press

, type query, results filter live.

```
n
```
/
```
N
```
— next/previous match
```
Esc
```
— dismiss search
Fuzzy matching by default,
```
'
```
prefix for exact match
Highlight matched characters in results
Preview pane updates for highlighted result

通用模式：按

输入查询词，结果实时过滤。

```
n
```
/
```
N
```
— 下一个/上一个匹配项
```
Esc
```
— 关闭搜索
默认模糊匹配，加
```
'
```
前缀使用精确匹配
高亮结果中匹配的字符
预览面板随高亮的结果同步更新

Help System — Three Tiers

帮助系统——三层结构

Tier	Trigger	Content	Audience
Always visible	Footer bar	3-5 essential shortcuts	Everyone
On demand	`?` key	Full keybinding overlay for current context	Regular users
Documentation	`--help` , man page	Complete reference	Power users

Footer format:

[q]uit [/]search [?]help [Tab]focus [Enter]select

Context-sensitive footers update based on the active panel or mode. Show only what's actionable right now.

层级	触发方式	内容	适用人群
始终可见	页脚栏	3-5个核心快捷键	所有用户
按需展示	`?` 键	当前上下文下的完整键位绑定浮层	常规用户
文档	`--help` 、man手册	完整参考	高级用户

页脚格式：

[q]退出 [/]搜索 [?]帮助 [Tab]切换焦点 [Enter]选中

上下文相关的页脚会随激活的面板或模式更新，仅展示当前可操作的功能。

Dialogs & Confirmation

对话框与确认

Action Severity	Pattern
Reversible	Just do it, show brief confirmation in status bar
Moderate (delete file)	Inline "Press y to confirm"
Severe (drop database)	Modal dialog requiring resource name input
Irreversible batch	`--dry-run` flag + explicit confirmation

Modal overlays: render popup on top of dimmed/blurred background
Toast notifications: auto-dismiss after 3-5 seconds, no interaction required
Status bar messages: vim-style one-liner feedback, auto-fade

操作严重程度	模式
可撤销	直接执行，在状态栏展示简短确认提示
中等风险（删除文件）	内联提示「按y确认」
高风险（删除数据库）	需要输入资源名确认的模态对话框
不可撤销的批量操作	`--dry-run` 标记+显式确认

模态浮层：在变暗/模糊的背景上渲染弹窗
Toast通知：3-5秒后自动消失，无需交互
状态栏消息：类Vim的单行反馈，自动淡出

4. Color Design System

4. 配色设计系统

Terminal Color Tiers

终端配色层级

Design for graceful degradation across all three tiers:

Tier	Escape Sequence	Colors	Strategy
16 ANSI	`\033[31m`	16 (relative)	Foundation. Terminal theme controls appearance.
256 Color	`\033[38;5;{n}m`	256 (16 relative + 240 fixed)	Extended palette. Fixed colors may clash with themes.
True Color	`\033[38;2;{r};{g};{b}m`	16.7M (absolute)	Full control. Requires `COLORTERM=truecolor` .

Detection hierarchy:

```
$COLORTERM
```
=
```
truecolor
```
or
```
24bit
```
→ true color
```
$TERM
```
contains
```
256color
```
→ 256 colors
```
$NO_COLOR
```
is set → disable all color
Default → 16 ANSI colors

Golden rule: Your TUI must be usable in 16-color mode. True color enhances — it never creates the hierarchy.

面向三个层级做优雅降级设计：

层级	转义序列	颜色数	策略
16色ANSI	`\033[31m`	16（相对）	基础层，由终端主题控制外观
256色	`\033[38;5;{n}m`	256（16个相对色+240个固定色）	扩展调色板，固定色可能与主题冲突
真彩色	`\033[38;2;{r};{g};{b}m`	1670万（绝对）	完全可控，需要 `COLORTERM=truecolor` 支持

检测优先级：

```
$COLORTERM
```
=
```
truecolor
```
或
```
24bit
```
→ 真彩色
```
$TERM
```
包含
```
256color
```
→ 256色
设置了
```
$NO_COLOR
```
→ 禁用所有颜色
默认 → 16色ANSI

黄金法则： 你的TUI在16色模式下必须可用，真彩色仅用于增强体验，永远不要用真彩色构建信息层级。

Semantic Color Slots

语义颜色槽

Define colors by function, not appearance. Map semantics to actual colors through your theme:

Slot	Purpose	Typical Dark Theme
`fg.default`	Body text	Off-white (#c0caf5)
`fg.muted`	Secondary text, metadata	Gray (#565f89)
`fg.emphasis`	Headers, focused items	Bright white (#e0e0e0)
`bg.base`	Primary background	Near-black (#1a1b26)
`bg.surface`	Panel/widget backgrounds	Slightly lighter (#24283b)
`bg.overlay`	Popup/dialog backgrounds	Lighter still (#414868)
`bg.selection`	Selected item highlight	Distinct (#364a82)
`accent.primary`	Interactive elements, focus	Brand color (#7aa2f7)
`accent.secondary`	Supporting interactions	Complementary (#bb9af7)
`status.error`	Errors, deletions	Red (#f7768e)
`status.warning`	Warnings, caution	Yellow (#e0af68)
`status.success`	Success, additions	Green (#9ece6a)
`status.info`	Informational	Cyan (#7dcfff)

Never hardcode hex values in widget code. Always reference semantic slots.

按功能定义颜色，而非外观，通过主题将语义映射到实际颜色：

槽位	用途	典型深色主题值
`fg.default`	正文	米白色（#c0caf5）
`fg.muted`	次要文本、元数据	灰色（#565f89）
`fg.emphasis`	头部、聚焦项	亮白色（#e0e0e0）
`bg.base`	主背景	近黑色（#1a1b26）
`bg.surface`	面板/部件背景	稍浅色（#24283b）
`bg.overlay`	弹窗/对话框背景	更浅色（#414868）
`bg.selection`	选中项高亮	区分色（#364a82）
`accent.primary`	交互元素、焦点	品牌色（#7aa2f7）
`accent.secondary`	辅助交互	互补色（#bb9af7）
`status.error`	错误、删除	红色（#f7768e）
`status.warning`	警告、注意	黄色（#e0af68）
`status.success`	成功、新增	绿色（#9ece6a）
`status.info`	提示信息	青色（#7dcfff）

永远不要在部件代码中硬编码十六进制颜色值，始终引用语义槽。

Visual Hierarchy Techniques

视觉层级技巧

Color is one tool among several. Use them in combination:

Technique	Effect	Use For
Bold (SGR 1)	Increases visual weight	Headers, labels, active items
Dim (SGR 2)	Decreases visual weight	Metadata, timestamps, secondary info
Italic (SGR 3)	Semantic distinction	Comments, types, annotations
Underline (SGR 4)	Links, actionable items	Clickable elements, URLs
Reverse (SGR 7)	Swaps fg/bg	Selection highlight (always works!)
Strikethrough (SGR 9)	Negation	Deleted items, deprecated features

Hierarchy recipe: 80% of content in

fg.default

. Headers in bold +

fg.emphasis

. Metadata in dim +

fg.muted

. Status in their semantic colors. Accents for interactive elements only.

颜色只是多种工具之一，组合使用效果更好：

技巧	效果	适用场景
粗体（SGR 1）	提升视觉权重	头部、标签、激活项
淡化（SGR 2）	降低视觉权重	元数据、时间戳、次要信息
斜体（SGR 3）	语义区分	注释、类型、标注
下划线（SGR 4）	链接、可操作项	可点击元素、URL
反色（SGR 7）	交换前景/背景色	选中高亮（永远生效！）
删除线（SGR 9）	否定	已删除项、废弃功能

层级配方： 80%内容使用

fg.default

，头部用粗体+

fg.emphasis

，元数据用淡化+

fg.muted

，状态信息使用对应语义色，仅交互元素使用强调色。

Background Layering

背景分层

Create depth without borders by layering background lightness:

bg.base (darkest) → bg.surface → bg.overlay (lightest)

Each step ~5-8% lighter in dark themes. The eye perceives depth from the contrast gradient. This reduces the need for box-drawing borders while maintaining clear visual zones.

通过背景亮度分层创造深度，无需边框：

bg.base（最深） → bg.surface → bg.overlay（最浅）

深色主题中每层亮度提升约5-8%，人眼会通过对比度梯度感知深度，这可以减少框绘边框的使用，同时保持清晰的视觉分区。

Theme Architecture

主题架构

Follow the Base16 pattern: define 16 named color slots, map them semantically:

8 monotones (base00-base07): background/foreground gradient
8 accents (base08-base0F): syntax/semantic colors

Ship a dark theme by default. Detect light/dark terminal via OSC escape query or

terminal-light

crate. Provide at least one light variant. Respect

NO_COLOR

遵循Base16模式：定义16个命名颜色槽，按语义映射：

8个单色槽（base00-base07）：背景/前景梯度
8个强调色槽（base08-base0F）：语法/语义颜色

默认附带深色主题，通过OSC转义查询或

terminal-light

库检测终端深浅模式，至少提供一个浅色变体，尊重

NO_COLOR

设置。

Accessibility Requirements

无障碍要求

WCAG AA contrast: 4.5:1 ratio for body text, 3:1 for large text/UI elements
Never use color alone: Pair with symbols (checkmark, X, triangle), text labels, position, or typography
Color blindness safe pairs: blue+orange, blue+yellow, black+white. Avoid relying on red vs green.
Test: monochrome mode, color blindness simulator, 3+ terminal emulators, light and dark themes

WCAG AA对比度： 正文对比度4.5:1，大文本/UI元素对比度3:1
永远不要仅依赖颜色传递信息： 搭配符号（对勾、叉、三角）、文本标签、位置或排版
色盲安全配色对： 蓝+橙、蓝+黄、黑+白，避免依赖红绿色差
测试： 单色模式、色盲模拟器、3款以上终端模拟器、深浅主题

5. Data Visualization

5. 数据可视化

Character-Resolution Building Blocks

字符分辨率构建块

Element	Characters	Resolution	Use For
Full blocks	`█▉▊▋▌▍▎▏`	8 steps/cell	Progress bars, bar charts
Shade blocks	`░▒▓█`	4 densities	Heatmaps, density plots
Braille	`⠁⠂⠃...⣿` (U+2800-U+28FF)	2x4 dots/cell	High-res line graphs, scatter plots
Sparkline	`▁▂▃▄▅▆▇█`	8 heights	Inline mini-charts

元素	字符集	分辨率	适用场景
全块	`█▉▊▋▌▍▎▏`	每单元格8阶	进度条、柱状图
阴影块	`░▒▓█`	4种密度	热力图、密度图
盲文	`⠁⠂⠃...⣿` （U+2800-U+28FF）	每单元格2x4点	高分辨率折线图、散点图
迷你折线图	`▁▂▃▄▅▆▇█`	8种高度	行内迷你图表

Common Widgets

常用部件

Widget	Pattern	Tips
Progress bar	`[████████░░░░] 67%`	Show percentage + ETA. Color gradient green→yellow→red by urgency.
Sparkline	`▁▂▃▅▇█▇▅▃▂`	Perfect for inline time-series in headers/status bars.
Gauge	`CPU [██████████░░] 83%`	Label + bar + value. Color by threshold.
Table	Sortable columns, zebra stripes	Align numbers right, text left. Truncate with `…` .
Tree	`├──` , `└──` , `│` guides	Indent 2-4 chars per level. Expand/collapse with Enter.
Diff	Green `+` lines, red `-` lines	Word-level highlighting within changed lines elevates quality.
Log	Colored level, timestamp, message	TRACE=dim, DEBUG=cyan, INFO=default, WARN=yellow, ERROR=red, FATAL=red+bold.

部件	模式	提示
进度条	`[████████░░░░] 67%`	展示百分比+预计完成时间，按紧急程度使用绿→黄→红渐变
迷你折线图	`▁▂▃▅▇█▇▅▃▂`	非常适合头部/状态栏的行内时间序列展示
仪表盘	`CPU [██████████░░] 83%`	标签+进度条+数值，按阈值变色
表格	可排序列、斑马纹	数字右对齐，文本左对齐，过长内容用 `…` 截断
树形结构	`├──` 、 `└──` 、 `│` 引导符	每层缩进2-4字符，按Enter展开/折叠
差异对比	绿色 `+` 行、红色 `-` 行	变更行内的词级别高亮能大幅提升体验
日志	彩色级别、时间戳、消息	TRACE=淡化、DEBUG=青色、INFO=默认、WARN=黄色、ERROR=红色、FATAL=红色+粗体

Spinner Selection

加载动画选择

Context	Spinner	Interval
Default / modern	Braille dots `⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏`	80ms
Minimal	Line `-\|/`	130ms
Heavy processing	Blocks `▖▘▝▗`	100ms
Fun / branded	Custom frames	70-100ms

Use spinners for indeterminate operations. Progress bars for determinate. Show spinners only after 200ms delay to avoid flash on fast operations.

场景	动画	间隔
默认/现代风格	盲文点 `⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏`	80ms
极简风格	线条 `-\|/`	130ms
heavy处理	块 `▖▘▝▗`	100ms
趣味/品牌定制	自定义帧	70-100ms

不确定时长的操作使用加载动画，确定时长的操作使用进度条。操作预计200ms内完成的不要展示加载动画，避免闪烁。

6. Animation & Motion

6. 动画与动效

Flicker-Free Rendering Stack

无闪烁渲染栈

Three layers, all required for smooth TUI rendering:

Double buffering — Render to off-screen buffer, diff against previous frame, emit only changed cells
Synchronized output — Wrap frame in
```
CSI ? 2026 h
```
...
```
CSI ? 2026 l
```
for atomic terminal render
Batched writes — Combine all escape sequences into a single
```
write()
```
syscall

三层结构，流畅TUI渲染的必备条件：

双缓冲 — 先渲染到离屏缓冲区，和上一帧做diff，仅输出变化的单元格
同步输出 — 用
```
CSI ? 2026 h
```
…
```
CSI ? 2026 l
```
包裹帧，实现终端原子渲染
批量写入 — 将所有转义序列合并为单次
```
write()
```
系统调用

When to Animate

动画使用场景

Situation	Animation	Duration
View transition	Fade or slide	100-200ms
Selection change	Instant highlight	0ms (never animate)
Data loading	Spinner or skeleton	Until complete
Success feedback	Brief flash/checkmark	1-2 seconds
Panel resize	Immediate reflow	0ms
Chart data update	Smooth value transition	200-500ms

Rule: Animations must never delay user input. If the user presses a key during a transition, cancel it and respond immediately.

场景	动画	时长
视图切换	淡入淡出或滑动	100-200ms
选中变更	即时高亮	0ms（永远不要加动画）
数据加载	加载动画或骨架屏	直到加载完成
成功反馈	短暂闪烁/对勾	1-2秒
面板调整大小	即时重排	0ms
图表数据更新	平滑数值过渡	200-500ms

规则： 动画永远不能阻塞用户输入，如果用户在动画过程中按下按键，立即取消动画并响应操作。

Real-Time Updates

实时更新

Cap refresh to 15-30 FPS for dashboards (saves CPU, prevents flicker)
Use differential updates — only redraw changed cells
Stream text (AI responses, logs) at a readable pace, not network burst speed
Background operations: show status in a status bar widget, never block the main loop

仪表盘刷新频率限制在15-30FPS（节省CPU，避免闪烁）
使用差分更新，仅重绘变化的单元格
流式文本（AI响应、日志）以可读速度输出，不要按网络突发速度输出
后台操作：在状态栏部件展示状态，永远不要阻塞主循环

7. The Seven Design Principles

7. 七大设计原则

Keyboard-first, mouse-optional — Every feature accessible via keyboard. Mouse enhances but never replaces.
```
Shift+click
```
must bypass mouse capture for text selection.
Spatial consistency — Panels stay in fixed positions. Users build mental maps. Never rearrange without explicit user action. Tabs provide stable landmarks.
Progressive disclosure — Show 5 essential shortcuts in the footer. Full help behind
```
?
```
. Complete reference in docs. The floor is accessible, the ceiling is unlimited.
Async everything — Never freeze the UI. File operations, network requests, scans all run in the background with progress indication. Cancel with
```
Esc
```
.
Semantic color — Color encodes meaning, not decoration. If you removed all color, the interface should still be usable through layout, typography, and symbols.
Contextual intelligence — Keybindings update per panel. Status bars reflect current state. Help shows what's actionable right now, not everything ever.
Design in layers — Start monochrome (usable?). Add 16 ANSI colors (readable?). Layer true color (beautiful?). Each tier must stand independently.

键盘优先，鼠标可选 — 所有功能都可以通过键盘访问，鼠标仅作为增强而非替代，
```
Shift+点击
```
必须绕过鼠标捕获支持文本选择。
空间一致性 — 面板保持固定位置，用户可以建立心智地图，未经用户显式操作永远不要重排，标签提供稳定的定位标识。
渐进式披露 — 页脚展示5个核心快捷键，完整帮助在
```
?
```
后展示，完整参考在文档中，下限足够友好，上限无限制。
全异步 — 永远不要冻结UI，文件操作、网络请求、扫描都在后台运行并展示进度提示，按
```
Esc
```
可取消。
语义化颜色 — 颜色传递含义而非装饰，即使去掉所有颜色，界面依然可以通过布局、排版和符号正常使用。
上下文感知 — 键位绑定随面板变化，状态栏反映当前状态，帮助仅展示当前可操作的功能，而非所有功能。
分层设计 — 从单色开始（确认可用），添加16色ANSI（确认可读），再叠加真彩色（确认美观），每个层级都可以独立使用。

8. Anti-Pattern Checklist

8. 反模式检查清单

Validate your design against these ranked pitfalls (ordered by real-world complaint frequency):

#	Anti-Pattern	Fix
1	Colors break on different terminals	Use 16 ANSI colors as foundation. Test 3+ emulators + light/dark themes.
2	Flickering / full redraws	Double buffer + synchronized output + batched writes. Overwrite, never clear.
3	Undiscoverable keybindings	Context-sensitive footer + `?` help overlay + Which-Key-style hints.
4	Broken on Windows / WSL	Test on Windows Terminal. Avoid advanced Unicode beyond box-drawing.
5	Unicode rendering inconsistency	Stick to box-drawing + block elements. Restrict emoji to Unicode 9.0.
6	Terminal multiplexer incompatibility	Test inside tmux and zellij. Mouse capture must not break selection.
7	No accessibility support	Respect `NO_COLOR` , provide monochrome mode, never color-only meaning.
8	Blocking UI during operations	Show feedback within 100ms. Use async + spinners + progress bars.
9	Modal confusion	Always show current mode in status bar. Cursor shape changes per mode.
10	Over-decorated chrome	Borders and colors serve content, not ego. The content IS the interface.

对照这些常见问题验证你的设计（按实际投诉频率排序）：

#	反模式	修复方案
1	颜色在不同终端下显示异常	以16色ANSI为基础，测试3款以上模拟器+深浅主题
2	闪烁/全量重绘	双缓冲+同步输出+批量写入，覆盖而非清空内容
3	键位绑定难以发现	上下文敏感页脚+ `?` 帮助浮层+类似Which-Key的提示
4	在Windows/WSL下运行异常	在Windows Terminal下测试，避免使用框绘字符以外的高级Unicode
5	Unicode渲染不一致	仅使用框绘+块元素，表情限制在Unicode 9.0范围内
6	与终端多路复用器不兼容	在tmux和zellij中测试，鼠标捕获不能破坏文本选择
7	无障碍支持缺失	尊重 `NO_COLOR` 设置，提供单色模式，永远不要仅用颜色传递信息
8	操作过程中UI阻塞	100ms内展示反馈，使用异步+加载动画+进度条
9	模式混乱	始终在状态栏展示当前模式，光标形状随模式变化
10	过度装饰的外壳	边框和颜色为内容服务，内容才是界面本身

9. Compatibility Checklist

9. 兼容性检查清单

Before shipping, verify:

Works at 80x24 minimum terminal size
Handles terminal resize without crash
Looks correct on dark AND light terminal themes
Respects
```
NO_COLOR
```
environment variable
Works inside tmux / zellij / screen
Functions over SSH (no features require local-only protocols)
Mouse capture doesn't break text selection (
```
Shift+click
```
)
All features accessible via keyboard alone
No ANSI escape sequence leaks to piped/redirected output
Exits cleanly on
```
Ctrl+C
```
/
```
SIGINT
```
(restores terminal state)

For Unicode character reference tables and border style gallery, see visual-catalog.md. For real-world TUI app design analysis and inspiration, see app-patterns.md.

发布前验证以下项：

支持80x24的最小终端尺寸
终端调整大小时不会崩溃
在深色和浅色终端主题下显示正常
尊重
```
NO_COLOR
```
环境变量
在tmux/zellij/screen中正常运行
通过SSH正常运行（无依赖本地协议的功能）
鼠标捕获不会破坏文本选择（
```
Shift+点击
```
正常）
所有功能仅通过键盘即可访问
没有ANSI转义序列泄漏到管道/重定向输出中
收到
```
Ctrl+C
```
/
```
SIGINT
```
时干净退出（恢复终端状态）

Unicode字符参考表和边框样式库请查看 visual-catalog.md。真实TUI应用设计分析和灵感参考请查看 app-patterns.md。