设计终端界面（TUI）时：按任务选布局并处理输入焦点…

在实现或评审 TUI 的布局、配色、键盘导航、异步更新和终端兼容时，用这套可执行检查表保证界面可用、响应快且可恢复。

适用场景

解决思路

1. 围绕用户重复执行的动作、必须持续可见的数据和终端实际具备的能力来设计界面。
2. 在慢 I/O 下保持输入响应。
3. 明确显示选择项、焦点和操作状态。
4. 遵循项目使用的框架版本与项目视觉标识；不要把示例调色板（如 SilkCircuit Neon）当作通用主题。
5. 需要布局示例与取舍时读 references/app-patterns.md；只在选择字形、边框、图表或指示器时读 references/visual-catalog.md。
6. 浏览关联列表和详情时：用持久多面板；保持面板角色稳定且焦点可见。
7. 导航层级时：用 Miller columns 或逐层下钻栈；返回时恢复选择与滚动位置。
8. 监控变化指标时：用 widget dashboard；显示标签、单位、新鲜度和进入详情路径。
9. 编辑请求、查询或配置时：用 sidebar、editor、results；切换面板时保留编辑状态。
10. 为 shell 命令选择值时：用 inline picker 或 overlay；返回干净值并保留 shell scrollback。
11. 读取日志或事件时：用固定控件加 virtualized list；明确 follow mode，向上滚动时停止自动跟随。
12. 使用约束和内容优先级来做响应式。
13. 折叠次要面板时保持选中项可见；面板重新出现时保留状态。
14. resize 时重新计算布局，不把零尺寸的瞬时区域当作错误。
15. 在过滤、删除或视口变小后限制/clamp 滚动位置。
16. 测试窄、普通、宽布局，并测试快速 resize。
17. 最小可用尺寸由任务决定；80x24 是有用测试用例，不是禁用 40 列仍可用 picker 的理由。
18. 尺寸提示界面仍要保留退出和恢复输入。
19. 基础导航支持方向键、Enter、Escape，以及可发现的焦点移动。
20. 在能改善重复工作时，增加 vim motions 或 command palette。
21. 文本字段中可打印按键应编辑文本；q、j、/ 和助记动作不能全局触发。
22. 多键快捷键要显示 pending 上下文，并通过输入库解决 Escape/前缀歧义。
23. 模态对话框只把输入路由到模态；关闭时恢复此前有效焦点目标。
24. 破坏性操作显示确切目标和后果；按可逆性选择确认强度。
25. 鼠标支持要与键盘动作一致，并提供禁用捕获以便选择终端文本的方式。
26. 保持输入解析只有一个 owner。
27. 使用 Crossterm 时不要把 EventStream 与 read/poll 混用，也不要运行相互竞争的 reader。
28. 有意处理 key press、repeat、release；一次物理按键不能提交两次。
29. 增强键盘协议可区分旧终端编码相同的按键。
30. 协商增强键盘支持，并保留可用的回退绑定。
31. 不要假设所有终端中 Ctrl+I 不同于 Tab，或 Ctrl+M 不同于 Enter。
32. 把 bracketed paste 当作文本事件；粘贴的换行不能意外提交破坏性命令。
33. raw mode 可能禁用终端正常信号处理。
34. 通过框架有意实现 Ctrl+C 和 suspend/resume；不要假设 OS 会原样处理。
35. 把控制权交给 editor、pager、shell 或挂起进程前恢复终端状态，之后重新获取并重绘。
36. 用简短 footer 显示当前可用动作，并提供上下文帮助视图。
37. 任务运行时保持必要说明可见。
38. 持久错误要有可检索位置；消失的 toast 不能作为唯一记录。
39. 分离输入事件、状态转换、effects 和渲染。
40. 渲染函数只渲染状态快照；不要从绘制函数发起网络调用或修改领域模型。
41. 按流程图保持单向：event -> update -> state/effect -> 带 result + request identity 的 event -> state -> render。
42. 搜索 A 在搜索 B 后完成：给请求打 tag，并丢弃不再匹配活动查询的结果。
43. 刷新后行位置移动：用稳定 identity 跟踪选择，不要只用 row index。
44. 视图关闭时仍有工作在跑：取消自己拥有的工作或有意识地 detach；迟到结果不能复活视图。
45. 已取消的写入可能已到达服务器：区分取消等待和确认回滚，并协调远程状态。
46. 日志到达快于屏幕更新：在数据层保留必要事件，并渲染 virtualized viewport。
47. async 语法下工作仍阻塞 UI：找出阻塞调用或 CPU 工作，移出输入/渲染路径。
48. 重复动作会启动重复写入：跟踪 pending operation identity，在接受冲突动作前显示其结果。
49. 批量更新状态并只渲染变化帧。
50. 合并可替换的视觉快照，但不要合并审计事件或 mutation。
51. 在丢弃数据或限制并发前，诊断队列增长、索引和分配成本。
52. 显式应用设置优先。
53. 自动模式下，在颜色检测前尊重非空 NO_COLOR。
54. 颜色 override 可以有意重新启用颜色；禁用颜色不必禁用 bold、underline、布局或所有终端功能。
55. 交互式终端：检查实际 input/output TTY；支持纯文本输出或解释需要 TTY。
56. True color：使用库检测、terminfo 或协商支持；COLORTERM 只是提示，不是要求。
57. 256/16 色：把语义槽映射到支持的颜色，并在没有色相时保留标签和焦点。
58. Images、hyperlinks、clipboard：通过 multiplexers 协商协议；提供文本或文件替代。
59. Nerd Font icons：显式启用或让用户配置；没有可移植可靠的字体检测 API。
60. Unicode 布局：分段 grapheme 并测量终端 cell 宽度；不要用 byte 或 code-point 长度。
61. 只在 grapheme 边界截断，考虑 wide cells、combining marks、variation selectors、emoji sequences。
62. 宽度库与模拟器可能不一致；测试代表性用户文本，在渲染不确定处提供 ASCII 指示器。
63. 把文件名、日志和远程字符串视为不可信显示数据。
64. 通过 raw output API 写入前转义控制序列；否则显示值可移动光标、改标题或调用 OSC 操作。
65. 使用框架支持的文字/净化路径。
66. 终端查询与按键共享输入流。
67. 让一个 parser 关联 replies，限制等待不支持查询的时间，并选择回退且不吞掉用户输入。
68. 定义语义槽：foreground、muted text、focus、selection、warning、error。
69. 不要把主题值写进 widget code。
70. 先使用稳定间距和标签，再引入更多边框。
71. 应用自设背景时提供 dark/light 变体；透明/默认背景要针对用户主题测试。
72. 状态颜色要与文字或形状配对。
73. 焦点指示器要在单色模式下仍可见；避免把重要值调暗到不可读。
74. 把 WCAG 4.5:1 普通文本对比度作为设计目标，但终端字体大小和 ANSI 颜色由用户控制；粗体终端标题不会自动符合大文本例外。
75. 不要仅凭调色板声称正式无障碍合规。
76. 全屏界面妨碍屏幕阅读器导航时，提供纯文本或线性呈现。
77. 有意义的标签、键盘访问和非动画模式仍需在目标终端与辅助技术下测试。
78. 避免闪烁警告或快速闪动状态。
79. 让用户减少动态效果；动画不能延迟输入或隐藏最终状态。
80. 使用框架的 buffered rendering 和 cell diffing。
81. 批量写入；仅在支持时使用 synchronized output，并始终配对 begin/end，即使出错也要配对。
82. 单次写入不等于原子渲染；synchronized output 是增强，不是可用 TUI 的前提。
83. 在状态变化或活动动画 deadline 时渲染。
84. 在预期数据速率下测量输入延迟、输出带宽和重绘成本，包括 SSH 和 multiplexers。
85. 按实际工作负载选择刷新节奏；不要强加通用 FPS 上限，也不要人为延迟流式文本。
86. 通过 scoped owner 获取终端模式，并恢复应用启用的所有内容：raw mode、alternate screen、cursor visibility、mouse capture、bracketed paste、keyboard protocol state。
87. 覆盖正常退出、初始化失败、异常/panic 和已处理信号。
88. 框架恢复 helper 可能只覆盖一部分；检查其 contract。
89. SIGKILL 无法运行清理。
90. 用确定性状态转换测试覆盖删除后选择、陈旧异步结果、模态焦点恢复、取消操作。
91. 用框架 test backend 测试布局边界；至少检查一个真实 PTY session，因为快照不覆盖终端模式和输入协议。
92. 演练 launch、typing、paste、resize、modal open/close、慢或失败 I/O、exit。
93. 包含 light/dark 主题、禁用颜色、宽/组合文本，以及实际支持的终端/multiplexer 路径。
94. 退出后验证 shell 光标和 echo 行为已恢复。
95. 当可移植性要求或失败证明必要时扩展测试矩阵。
96. NO_COLOR 在 true-color 检测后才检查：应在能力选择前先解析用户偏好。
97. 全局助记快捷键消耗文本输入：通过焦点和活动模式路由事件。
98. 把 Unicode release cutoff 当作兼容性：应测量 graphemes/cells 并测试支持的模拟器。
99. 异步请求完成覆盖更新状态：把 result identity 与当前 view/query 关联。
100. 后台日志清屏或发 escape codes：通过 state 或单独 sink 发送日志。
101. 降低 FPS 或并发来掩盖过载队列：分别 profile producer、状态处理和 renderer。
102. 只有正常退出才恢复终端：使用生命周期 guard 和框架 panic/signal 处理。
103. 核对以下契约与指南：Ratatui application patterns、Ratatui restoration contract、Crossterm input ownership、kitty keyboard protocol、NO_COLOR、Unicode grapheme segmentation、W3C contrast guidance；原始检查日期为 2026-09-04，框架 API 变化时以项目版本为准。
104. 把状态所有权与验证指导视为工程综合，不宣称协议能保证应用正确性。

适用边界 · 注意事项

• 不要把它当作某个框架的 API 手册，也不要因此强制采用新工具包。
• 不要为了简单选择器添加动画、图标或模式。
• 不要用它替代对真实终端与辅助技术路径的测试。