tui-visual-design

TUI 视觉设计与美感打磨

当终端 UI 不仅要实现功能，还需要显得精心设计、优雅、易读且达到生产级品质时，请使用此技能。优秀的 TUI 设计是在严苛的终端限制下，巧妙运用字符单元格、文本、留白、颜色、边框、字形、节奏与动效的技艺。

设计原则

1. 从信息架构入手。 确定用户最先需要注意什么、哪些内容属于次要信息，以及哪些内容可以等到用户请求时再显示。
2. 以字符单元格为单位进行设计。 每项视觉设计都会占用固定宽度的字符单元格。留白、边框、滚动条和图标都必须物有所值。
3. 减少视觉样式，并保持一致。 精致的 TUI 通常只有一种边框风格、一套间距比例、一种标题体系和一组语义化颜色。
4. 默认保持克制。 高强度颜色、粗重边框、反白、动画和图标应突出状态变化或操作，而不是装饰每个元素。
5. 有意处理降级情况。 每种视觉设计在无颜色、ASCII、窄屏、浅色主题、远程 SSH 和便于屏幕阅读器使用的模式下，都应正常工作。

视觉层级与构图

依次通过位置、间距、分组、文本标签、对齐、字重和颜色来建立层级。不要让颜色承担全部层级表达。

• 将主要任务或当前选中项放在最醒目的视觉锚点上：便于浏览的位置是左上角；只有模态或着陆状态才居中显示。
• 将完整边框留给重要区域；次要分组则使用留白或低调的分隔线。
• 使用 0、1、2 和 4 个字符单元格等间距比例。随意设置内边距会让 TUI 显得粗制滥造。
• 表单和空状态应留有充足空间。仪表盘可以信息密集，但相关指标要分组显示，组间应留出间隔。
• 使用渐进式披露：折叠区域、详细信息面板、命令面板和帮助浮层都能让默认屏幕保持简洁。

字体排印与文本呈现

终端无法在应用中使用真正的字体，但仍然可以建立排版体系。

• 将标题视为层级结构：主标题、区块标签、字段标签、提示和状态。大小写和标点应保持一致。
• 粗体最适合用于标题、选中标签和重要数值。暗色样式只用于可选提示，绝不能用于必需文本。
• 终端对斜体的支持并不一致，应谨慎使用。下划线用于表示链接或焦点。删除线用途有限。除兼容旧版的指示符外，避免闪烁，更不要用它来吸引注意。
• 标签左对齐，数字右对齐，表格文本左对齐，单位格式保持一致，操作项按交互顺序排列。
• 截断文本时要有明确目的：保持 ID 唯一，保留文件扩展名，必要时显示路径的开头和结尾，并在聚焦或详细视图中提供完整文本。
• 按单词边界换行散文文本，并为代码、日志和结构化输出保留缩进。

边框、框和容器

边框就像标点符号。框太多会产生视觉噪声。

• 为模态框、聚焦面板和主要区域使用完整边框。
• 为导航栏、活动区块和轻量分组使用仅左侧或仅底部的线条。
• 避免深层嵌套框。在有边框的面板内，优先使用留白、标题或分隔线。
• 为产品选定一种边框风格：纯 ASCII、单线、圆角、粗线或双线。只有用于表达层级时才混用。
• 边框内的水平留白通常为一个字符单元格。零留白会显得拥挤；留白过多则浪费终端空间。
• 使用半区块字符或深色背景营造阴影和纵深效果，在受控的真彩色终端中可能显得精致，但必须提供无阴影的备用方案。

颜色设计

优先使用语义角色，而非原始颜色：primary、accent、success、warning、error、info、muted、selected、focused、disabled、border、background、surface。

• 保持调色板精简。对于大多数 TUI，一个强调色加上语义状态色就足够了。
• 除非要构建可控制主题的全屏应用，否则避免大面积填充背景色。许多用户会自定义终端背景。
• 同时支持深色和浅色背景。黄色、蓝色、暗灰色和低饱和度颜色通常难以兼顾两者。
• 为 256 色和 16 色模式有意精简颜色。在 16 色模式下，优先使用终端命名颜色，而非不可靠的 RGB 假设。
• 绝不能只靠颜色表达含义。红色错误应搭配 Error 等文字、图标、位置或边框。
• 渐变可为真彩色模式下的横幅、图表和进度条增色，但在受限模式下必须简化为纯色语义颜色。

图表、数据可视化与信息密度

终端图表应能让用户更快找到问题答案，而不是阅读原始数字。

• 水平条形图最稳妥：左侧为标签，右侧为数值，中间为条形。
• 迷你图适合展示趋势，不适合显示精确数值。应添加最小值、最大值和当前值文本。
• 进度条需要标签、百分比或计数，以及明显的未完成区域。
• 表格需要对齐、留白、稳定的列顺序和清晰标示的焦点行。斑马纹可选；在无色模式下不应取代行分隔线。
• 热力图需要图例和文本替代说明，因为用户的色彩感知和终端调色板各不相同。
• 对于仪表盘，应按决策所需的信息分组：健康状况、吞吐量、延迟、错误、队列、资源。不要只因有空位就填满每个单元格。

动画与动态效果

动态效果应传达等待、进度、过渡或提醒；否则就只是噪声。

• 对未知时长的等待使用低频率旋转动画；已知进度时使用确定型进度条。
• 在 SSH、CI、日志、启用减少动态效果的设置，或渲染成本较高时，应暂停或简化动画。
• 避免每秒闪烁超过三次。
• 滑动或淡入淡出等过渡效果有助于用户保持上下文，但必须可中断且开销低。
• 平滑滚动适合本地终端；通过远程连接时，按页移动可能更好。

图标、字形与装饰元素

字形若可预测且可选，就能提升信息浏览效率。

• 使用简单的状态符号并配上标签：成功、失败、警告、信息、加载中。
• 不要强制要求安装 Nerd Fonts 或使用私用区字形。应提供 --ascii 或纯文本图标集。
• 在对齐布局中使用 emoji 前，应先测试其宽度和显示效果。
• 可使用箭头和尖括号表示层级与导航，但应避免在关键确认操作中使用含义模糊的符号。
• 装饰性横幅、粒子效果和吉祥物应在纯文本、窄屏、CI 和无障碍模式下消失。

提示与交互元素

优秀的提示应让用户一目了然地知道下一步操作。

• 在出错的字段附近显示验证信息，并明确指出如何修正。
• 用文本显示默认值和破坏性操作的后果，而不只是用颜色表示。
• 使用在无色模式下依然清晰的焦点指示：前缀标记、边框变化、标签或光标位置。
• 保持选择菜单的视觉布局稳定。避免用户导航时选项位置发生变化。
• 确认对话框应布局简洁、操作标签明确，并为破坏性操作设置安全的默认选项。
• 只有非关键通知才应短暂显示；持久性错误需要固定区域或日志面板。

框架样式默认设置

• **Ratatui：**组合 Layout 约束、Block 边框、Paragraph 换行、Table 宽度和语义化 Style。在固定尺寸和颜色模式下生成快照。
• **Textual：**谨慎使用 CSS 类、组件变体、主题变量和过渡效果；确保自定义控件在视觉上与内置控件保持一致。
• **Bubble Tea + Lip Gloss：**集中管理样式，组合使用外边距／内边距／边框，并使用宽字符 Unicode 测试 Width／Height 计算。
• **Rich：**定义 Theme 角色，一致地使用表格／面板／进度条，并避免嵌套面板导致输出过于繁杂。
• **Ink：**有意识地使用 flex 布局，集中管理样式令牌，并注意终端宽度变化可能会导致 React 组件树重新排布。
• **Terminal.Gui：**为每种视图类定义配色方案和焦点样式；确认鼠标和键盘焦点指示样式一致。
• **Spectre.Console：**使用标记、表格、树、分隔线、面板和进度条时，应采用克制的主题，并提供无颜色回退方案。

视觉反模式

• 没有语义体系的彩虹配色。
• 每个控件都使用厚重边框。
• 文字过小，挤在边框或终端边缘。
• 仅用颜色表示错误、选中状态或警告。
• 表格或数字居中对齐。
• 使用 Nerd Fonts 图标但不提供回退方案。
• 仪表板动画重绘速度快于数据变化速度。
• 仅适用于 120 列宽度的设计。
• 忽略浅色终端主题、NO_COLOR、TERM=dumb 和非 TTY 输出。

参考文件

• references/layout-typography.md - 视觉层次、间距、节奏、排版、对齐、换行和截断。
• references/color-design.md - 语义化配色、对比度、主题适配、渐变和受限颜色模式。
• references/borders-icons-prompts.md - 方框绘制、容器、字形、图标、提示词、表单、对话框和通知。
• references/charts-visualization.md - 条形图、迷你图、仪表盘、进度条、表格、树、热力图和仪表板密度。
• references/animation-motion.md - 加载动画、动效设计、过渡效果、滚动、装饰效果和性能限制。
• references/framework-styling.md - Ratatui、Textual、Bubble Tea/Lip Gloss、Rich、Ink、Terminal.Gui 和 Spectre.Console 的视觉样式方案。