tui-design

TUI 设计系统

围绕用户反复执行的操作、必须始终查看的数据，以及终端实际具备的能力进行设计。在 I/O 较慢时保持输入响应灵敏，并明确显示选择、焦点和操作状态。

主要文档核对日期：2026-09-04。 框架 API 会变化；请使用项目所采用的版本。遵循项目的视觉标识（Bliss 个人工具使用 SilkCircuit Neon），不要把示例调色板当作通用主题。

根据任务选择布局

任务	布局	实用原则
浏览相关列表和详情	持久化多面板	面板职责稳定，焦点清晰可见
浏览层级结构	Miller 列或逐层深入堆栈	返回时恢复选择和滚动位置
监控不断变化的测量值	小组件仪表板	显示标签、单位、数据新鲜度，并提供查看详情的路径
编辑请求、查询或配置	侧边栏、编辑器、结果	切换面板时保留编辑状态
为 shell 命令选择值	内联选择器或浮层	返回干净的值，并保留 shell 滚动历史
阅读日志或事件	固定控件加虚拟化列表	明确显示跟随模式；向上滚动后停止自动跟随

阅读 app-patterns.md 了解示例和权衡。仅在选择字形、边框、图表或指示器时阅读 visual-catalog.md。

响应式行为

使用约束和内容优先级。收起次要面板时，确保所选项目仍然可见；面板重新出现时保留状态。调整窗口大小时重新计算布局，不要将短暂的零尺寸区域视为错误。筛选、删除或视口缩小时，应限制滚动范围。

测试窄屏、常规屏幕和宽屏布局，包括快速调整窗口大小的情况。最低可用尺寸取决于任务；80x24 是实用的测试用例，但这不意味着可以禁用在 40 列宽度下仍能工作的选择器。尺寸提示应保留退出和恢复操作的输入。

输入、焦点与编辑

关注点	决策
基本导航	支持方向键、Enter、Escape，并确保焦点移动方式易于发现
专家快捷键	在能提升重复操作效率时，添加 vim 操作或命令面板
文本字段	可打印按键用于编辑文本；q、j、/ 和助记操作不得全局触发
多键快捷键	显示待处理上下文，并通过输入库处理 Escape／前缀歧义
模态对话框	仅将输入路由到模态对话框；关闭时恢复先前有效的焦点目标
破坏性操作	显示确切目标及后果；根据操作的可逆性选择适当的确认方式
鼠标支持	与键盘操作保持一致，并提供禁用捕获的方式，以便在终端中选择文本

输入解析只能由一个组件负责。使用 Crossterm 时，不要混用 EventStream 与 read／poll，也不要运行相互竞争的读取器。应有意处理按键按下、重复和释放事件；一次物理按键不得提交两次。

增强型键盘协议可以区分传统终端编码相同的按键。应协商支持情况，并保留可用的备用按键绑定。切勿假定 Ctrl+I 在所有地方都不同于 Tab，或 Ctrl+M 不同于 Enter。将括号括起的粘贴内容视为文本事件；粘贴的换行符不得意外提交破坏性命令。

原始模式可能会禁用终端的常规信号处理。应通过框架妥善实现 Ctrl+C 和挂起／恢复；不要假定操作系统会按原样处理它们。将控制权交给编辑器、分页器、Shell 或挂起的进程前，应恢复终端状态；之后重新获取终端并重绘。

为当前可用操作显示简短页脚，并提供上下文帮助视图。任务运行期间，应保持必要说明可见。持久错误必须有可供检索的位置；消失的 Toast 不能是唯一记录。

状态与异步工作

将输入事件、状态转换、效果和渲染分开。渲染状态快照时，不要从绘图函数发起网络调用或修改领域模型。

digraph tui_state {
    rankdir=LR;
    event -> update;
    update -> state;
    update -> effect;
    effect -> event [label="result + request identity"];
    state -> render;
}

故障模式	设计应对
搜索 A 在搜索 B 之后完成	为请求添加标记，并丢弃与当前活动查询不再匹配的结果
刷新后某行位置发生变化	根据稳定标识跟踪所选项，而不只依赖行索引
工作进行期间视图关闭	取消由该视图负责的工作，或有意将其分离；延迟返回的结果不得使视图重新出现
已取消的写入可能已到达服务端	区分已取消的等待与已确认的回滚；协调远程状态
日志到达速度快于屏幕更新速度	在数据层保留必需事件，并渲染虚拟化视口
尽管使用了 async 语法，工作仍阻塞界面	找出阻塞调用或 CPU 密集型工作，并将其移出输入／渲染路径
重复操作会启动重复写入	跟踪待处理操作的标识，并在接受冲突操作前显示其结果

批量更新状态，并仅渲染发生变化的帧。合并可替换的视觉快照，而不是审计事件或变更。在丢弃数据或限制并发前，应先诊断队列增长、索引和内存分配成本。

终端能力策略

显式应用设置优先。在自动模式下，进行颜色检测前先遵循非空的 NO_COLOR。颜色覆盖设置可以有意重新启用颜色；禁用颜色并不意味着必须禁用粗体、下划线、布局或所有终端功能。

能力	依据与回退方案
交互式终端	检查实际的输入/输出 TTY；支持纯文本输出，或说明为何需要 TTY
真彩色	使用库的检测、terminfo 或协商后的支持；COLORTERM 是提示，而非要求
256/16 色	将语义色位映射到受支持的颜色，并在没有色相时保留标签和焦点
图像、超链接、剪贴板	通过复用器协商协议；提供文本或文件替代方案
Nerd Font 图标	明确提供或允许用户配置；没有可移植且可靠的字体检测 API
Unicode 布局	按字素簇分段并测量终端单元格宽度；不要使用字节长度或码点长度

仅在字素簇边界处截断，并考虑宽字符单元格、组合标记、变体选择符和表情符号序列。宽度库和终端模拟器的结果可能不一致；请测试有代表性的用户文本，并在渲染不确定时提供 ASCII 指示符。

将文件名、日志和远程字符串视为不可信的显示数据。通过原始输出 API 写入前，应对控制序列进行转义；否则，显示的值可能移动光标、更改标题或触发 OSC 操作。请使用框架支持的文本处理/净化路径。

终端查询与按键输入共用输入流。应由一个解析器关联响应，限制对不支持查询的等待时间，并选择回退方案，避免吞掉用户输入。

视觉层级与无障碍

定义语义色位，例如前景色、弱化文本、焦点、选中、警告和错误。不要在控件代码中放置主题值。先提供稳定的间距和标签，再引入更多边框。当应用设置自己的背景时，请提供深色和浅色变体；透明/默认背景需要针对用户主题进行测试。

状态颜色应搭配文本或形状。使用在单色模式下仍有效的焦点指示，并避免将重要值调暗到难以辨认。WCAG 的普通文本 4.5:1 对比度是有用的设计目标，但终端字体大小和 ANSI 颜色由用户控制；终端标题加粗并不自动符合大文本例外条件。不要仅凭调色板就声称符合正式的无障碍标准。

当全屏界面妨碍屏幕阅读器导航时，请提供纯文本或线性呈现方式。仍需使用预期的终端和辅助技术测试有意义的标签、键盘操作和非动画模式。避免闪烁警告或快速闪烁的状态。允许用户减少动态效果；动画不得延迟输入或隐藏最终状态。

渲染与终端生命周期

使用框架的缓冲渲染和单元格差异比较。批量写入；仅在支持时使用同步输出，并确保即使发生错误也始终成对调用 begin/end。单次写入并不能证明渲染是原子的；同步输出是增强功能，而非 TUI 可用的前提。

在状态变化或动画截止时间到达时进行渲染。在预期数据速率下测量输入延迟、输出带宽和重绘成本，包括 SSH 和复用器。根据实际工作负载选择刷新频率；不要强制设定通用 FPS 上限，也不要人为延迟流式文本。

通过作用域限定的所有者获取终端模式，并恢复应用启用的所有设置：原始模式、备用屏幕、光标可见性、鼠标捕获、括号粘贴和键盘协议状态。涵盖正常退出、初始化失败、异常/崩溃以及已处理的信号。框架的恢复辅助函数可能只涵盖其中一部分；请检查其约定。SIGKILL 无法执行清理。

能提升信心的验证

针对删除后的选中项、过期的异步结果、模态窗口焦点恢复以及已取消的操作，编写确定性的状态转换测试。使用框架的测试后端检查布局边界；至少检查一次真实 PTY 会话，因为快照不会测试终端模式或输入协议。

测试启动、输入、粘贴、调整大小、打开/关闭模态窗口、缓慢或失败的 I/O，以及退出。涵盖浅色/深色主题、禁用颜色、宽字符/组合字符，以及实际支持的终端/复用器路径。退出后，验证 shell 的光标和回显行为已恢复。只有在可移植性要求或故障情况确有需要时，才扩展测试矩阵。

反模式

反模式	更好的做法
在检测真彩色后才检查 NO_COLOR	在选择终端能力前解析用户偏好
全局快捷键占用文本输入	根据焦点和活动模式路由事件
将 Unicode 版本的发布截止时间当作兼容性依据	测量字素/单元格，并测试受支持的模拟器
异步请求完成时覆盖较新的状态	将结果标识与当前视图/查询关联
后台日志记录清屏或转义码	通过状态或独立接收端发送日志
降低 FPS 或并发度来掩盖过载队列	分别分析生产者、状态处理和渲染器
仅在正常退出时恢复终端	使用生命周期保护机制以及框架的崩溃/信号处理

主要来源

核查日期：2026-09-04：Ratatui 应用模式、Ratatui 恢复约定、Crossterm 输入所有权、kitty 键盘协议、NO_COLOR、Unicode 字素分段以及对比度指南。

关于状态所有权和验证的指导，是基于这些约定综合得出的工程建议，并不意味着协议能保证应用正确性。

此技能不是什么

• 不是框架 API 手册，也不要求采用新工具包。
• 不是给简单选择器添加动画、图标或模式的理由。
• 不能替代对实际终端和无障碍操作路径的测试。