TUI Review

TUI评审

Critically review terminal UIs by running them live in tmux, taking screenshots at key states, and testing against 10 UX dimensions. Benchmarks against Claude Code, OpenCode, and Codex.

Gold standard: Every keypress produces visible change within 100ms. Every state has a designed appearance. Color communicates meaning. No dead keys, no blank screens, no stuck states.

通过在tmux中实时运行终端用户界面（TUI）、在关键状态下截取屏幕截图，并对照10个UX维度进行测试，对TUI进行专业评审。同时与Claude Code、OpenCode和Codex进行基准对比。

黄金标准：每一次按键操作都应在100ms内产生可见变化。每种状态都有专属的视觉呈现。颜色传递特定含义。无无效按键、无空白屏幕、无卡顿状态。

Style Opinion: Borders

风格建议：边框

Flag excessive border usage. Many TUIs wrap the entire screen in box-drawing borders (

╭╮╰╯│─

) — this wastes precious terminal real estate and adds visual noise. Borders should be used sparingly and purposefully:

Good: Borders to separate distinct regions (input area vs conversation), to frame a modal/dialog that overlays content, or to visually group related controls.
Bad: A full outer border around the entire TUI (eats 2 columns + 2 rows for zero information gain), borders around every panel when whitespace/divider lines would suffice, nested borders creating a "box in a box" effect.

What the best TUIs actually do: Claude Code uses horizontal rule lines (

────

) to separate the input area — no outer border. OpenCode uses

┃

left-margin lines for message attribution — not a full box. Codex uses bordered boxes only for the header info panel and status panel — the conversation area itself is borderless. The pattern: content-heavy areas are borderless; chrome-heavy areas (headers, dialogs) get borders.

Flag any TUI that wraps the full screen in a border as a WARNING.

标记过度使用边框的情况。许多TUI会用绘图边框（

╭╮╰╯│─

）包裹整个屏幕——这会浪费宝贵的终端显示空间，还会增加视觉噪音。边框应少而精，且有明确用途：

合理用法：用边框分隔不同区域（输入区与对话区）、为覆盖在内容上的模态框/对话框添加边框，或是将相关控件进行视觉分组。
错误用法：为整个TUI添加完整的外边框（占用2列+2行空间却无任何信息增益）、每个面板都加边框（用空白/分隔线即可满足需求时）、嵌套边框形成「盒中盒」效果。

顶尖TUI的实际做法：Claude Code使用水平分隔线（

────

）区分输入区——无外边框。OpenCode使用

┃

左侧边距线进行消息归因——而非完整的盒子。Codex仅为头部信息面板和状态面板添加边框——对话区域本身无边框。规律是：内容密集区无边框；界面控件密集区（头部、对话框）加边框。

若发现TUI为整个屏幕添加外边框，标记为「警告」。

Process

评审流程

Launch TUI in tmux
Take initial screenshot — first impression matters
Discover the UI (find help, navigation, input areas)
Test each of the 10 dimensions, screenshotting each key state
Take resize screenshots at 80x24, 120x30, 160x40, 200x50
Visually review all screenshots using the Read tool
Produce graded report with screenshots and findings

在tmux中启动TUI
截取初始状态截图——第一印象至关重要
探索UI功能（查找帮助、导航、输入区域）
测试每个维度，在关键状态下截取屏幕截图
分别在80x24、120x30、160x40、200x50尺寸下截取窗口调整截图
使用Read工具视觉评审所有截图
生成包含截图和发现的分级报告

Setup

环境设置

CRITICAL: Enable True-Color in tmux (RGB colors)

关键步骤：在tmux中启用真彩色（RGB颜色）

Ratatui/crossterm TUIs use RGB colors (

Color::Rgb(r,g,b)

). By default, tmux does NOT pass these through, causing

capture-pane -e

to strip all color escape codes. You MUST enable true-color support BEFORE launching the TUI:

bash

undefined

基于ratatui/crossterm开发的TUI使用RGB颜色（

Color::Rgb(r,g,b)

）。默认情况下，tmux不会传递这些颜色，导致

capture-pane -e

命令会剥离所有颜色转义码。在启动TUI之前，必须启用真彩色支持：

bash

undefined

Enable true-color (Tc) for ALL terminal types — run ONCE per tmux server

为所有终端类型启用真彩色（Tc）——每个tmux服务器只需运行一次

tmux set-option -g default-terminal "xterm-256color" tmux set-option -ga terminal-overrides ",*:Tc"


**Without this fix**: `capture-pane -e` returns zero ANSI escape codes — the TUI appears monochrome in captures even though it renders colorful in a real terminal. This is because tmux's internal cell storage doesn't preserve RGB attributes unless Tc is enabled.

**Verification**: After setting the override and launching a ratatui TUI, check:
```bash
tmux capture-pane -t $SESSION -e -p | hexdump -C | grep '1b 5b 33 38 3b 32'

tmux set-option -g default-terminal "xterm-256color" tmux set-option -ga terminal-overrides ",*:Tc"


**未启用的后果**：`capture-pane -e`返回的结果中没有ANSI转义码——即使TUI在真实终端中显示彩色，截图也会呈现单色。这是因为除非启用Tc，否则tmux的内部单元格存储不会保留RGB属性。

**验证方法**：设置覆盖并启动ratatui TUI后，执行以下命令检查：
```bash
tmux capture-pane -t $SESSION -e -p | hexdump -C | grep '1b 5b 33 38 3b 32'

Should show: |.[38;2;R;G;Bm| sequences (RGB foreground color codes)

应显示：|.[38;2;R;G;Bm| 序列（RGB前景色代码）

If empty: Tc override is not working

若为空：Tc覆盖未生效

undefined

undefined

Screenshot Method

截图方法

Use

capture-pane -e

(with escape codes) piped to

freeze

for color PNG screenshots:

bash

undefined

使用带转义码的

capture-pane -e

命令，配合

freeze

工具生成彩色PNG截图：

bash

undefined

Take a color screenshot

截取彩色截图

tmux capture-pane -t $SESSION -e -p | freeze --language ansi --output /tmp/screenshot.png

IMPORTANT: freeze may hang — always run with a timeout

重要提示：freeze可能会挂起——始终配合超时命令运行

tmux capture-pane -t $SESSION -e -p | freeze --language ansi --output /tmp/screenshot.png & PID=$! sleep 6 kill $PID 2>/dev/null

undefined

tmux capture-pane -t $SESSION -e -p | freeze --language ansi --output /tmp/screenshot.png & PID=$! sleep 6 kill $PID 2>/dev/null

undefined

Full Setup

完整设置脚本

bash

source .claude/skills/tmux-cli-test/scripts/tmux_helpers.sh
TMUX_TEST_WIDTH=140
TMUX_TEST_HEIGHT=40
TMUX_TEST_POLL_INTERVAL=0.1
TMUX_SCREENSHOT_DIR="/tmp/tui-review-screenshots"
mkdir -p "$TMUX_SCREENSHOT_DIR"

bash

source .claude/skills/tmux-cli-test/scripts/tmux_helpers.sh
TMUX_TEST_WIDTH=140
TMUX_TEST_HEIGHT=40
TMUX_TEST_POLL_INTERVAL=0.1
TMUX_SCREENSHOT_DIR="/tmp/tui-review-screenshots"
mkdir -p "$TMUX_SCREENSHOT_DIR"

CRITICAL: Enable true-color BEFORE starting any TUI session

关键步骤：在启动任何TUI会话前启用真彩色

tmux set-option -g default-terminal "xterm-256color" tmux set-option -ga terminal-overrides ",*:Tc"

SESSION="tui-review"

tmux set-option -g default-terminal "xterm-256color" tmux set-option -ga terminal-overrides ",*:Tc"

SESSION="tui-review"

Launch with COLORTERM=truecolor to help crossterm detect color support

启动时设置COLORTERM=truecolor，帮助crossterm检测颜色支持

tmux new-session -d -s "$SESSION" -x $TMUX_TEST_WIDTH -y $TMUX_TEST_HEIGHT
"COLORTERM=truecolor <command>" sleep 4 # Wait for TUI to render

tmux new-session -d -s "$SESSION" -x $TMUX_TEST_WIDTH -y $TMUX_TEST_HEIGHT
"COLORTERM=truecolor <command>" sleep 4 # 等待TUI渲染完成

Take first color screenshot

截取第一张彩色截图

tmux capture-pane -t "$SESSION" -e -p |
freeze --language ansi --output "$TMUX_SCREENSHOT_DIR/01-initial.png" & PID=$!; sleep 6; kill $PID 2>/dev/null

Visually inspect it

视觉检查截图

Use Read tool on the PNG path

在PNG路径上使用Read工具


**Requires**: `freeze` (`brew install charmbracelet/tap/freeze`) for PNG screenshots.


**依赖工具**：需要`freeze`工具（通过`brew install charmbracelet/tap/freeze`安装）来生成PNG截图。

Screenshot Protocol

截图协议

Take screenshots at these moments during the review. Use the Read tool to visually inspect each PNG.


01-initial
02-help
03-commands
04-processing
05-response
06-error
07-dialog
08-permission
09-resize-WxH

#	State	Label	What to Look For
1	Initial load	`01-initial`	First impression, layout, color usage
2	Help/shortcuts overlay	`02-help`	Discoverability, overlay design
3	Command palette / slash menu	`03-commands`	Dropdown styling, selection highlight
4	During processing/streaming	`04-processing`	Loading indicator, streaming text
5	Completed response	`05-response`	Message formatting, tool output
6	Error state	`06-error`	Error visibility, color distinction
7	Dialog/modal open	`07-dialog`	Modal design, backdrop
8	Permission/confirmation flow	`08-permission`	Diff preview, action options
9-12	Resize: 80x24, 120x30, 160x40, 200x50	`09-resize-WxH`	Layout adaptation

bash

undefined

在评审过程中的以下时刻截取截图。使用Read工具视觉检查每个PNG文件。


01-initial
02-help
03-commands
04-processing
05-response
06-error
07-dialog
08-permission
09-resize-WxH

序号	状态	标签	检查要点
1	初始加载	`01-initial`	第一印象、布局、颜色使用
2	帮助/快捷键覆盖层	`02-help`	可发现性、覆盖层设计
3	命令面板 / 斜杠菜单	`03-commands`	下拉菜单样式、选中高亮
4	处理/流式传输中	`04-processing`	加载指示器、流式文本
5	响应完成	`05-response`	消息格式、工具输出
6	错误状态	`06-error`	错误可见性、颜色区分度
7	对话框/模态框打开	`07-dialog`	模态框设计、背景遮罩
8	权限/确认流程	`08-permission`	差异预览、操作选项
9-12	窗口调整：80x24、120x30、160x40、200x50	`09-resize-WxH`	布局适应性

bash

undefined

Helper function for color screenshots (use instead of tmux_screenshot for ratatui TUIs)

彩色截图辅助函数（针对ratatui TUI，替代tmux_screenshot）

take_color_screenshot() { local session="$1" label="$2" local outfile="$TMUX_SCREENSHOT_DIR/${label}.png" tmux capture-pane -t "$session" -e -p |
freeze --language ansi --output "$outfile" & local pid=$! sleep 6 kill $pid 2>/dev/null echo "$outfile" }

Example: screenshot after opening help

示例：打开帮助后截图

tmux send-keys -t "$SESSION" "?" sleep 1 take_color_screenshot "$SESSION" "02-help"

Example: resize screenshots

示例：窗口调整截图

for size in "80x24" "120x30" "160x40" "200x50"; do IFS='x' read -r w h <<< "$size" tmux resize-window -t "$SESSION" -x "$w" -y "$h" sleep 0.5 take_color_screenshot "$SESSION" "09-resize-${size}" done

Visually inspect a screenshot (CRITICAL — actually look at it)

视觉检查截图（关键步骤——实际查看渲染后的TUI，评估颜色、布局、对比度和设计质量）

Use the Read tool on the PNG path

在PNG路径上使用Read工具


**IMPORTANT**: After taking each screenshot, use the **Read tool** to view the PNG file. This is what makes the review "visual" — you are literally looking at the rendered TUI and assessing color, layout, contrast, and design quality.

**NOTE on tmux_screenshot vs take_color_screenshot**: The `tmux_screenshot` helper from `tmux_helpers.sh` may not preserve RGB colors from ratatui/crossterm TUIs. For any TUI built with ratatui, crossterm, or similar Rust terminal frameworks, use the `take_color_screenshot` function above which pipes `capture-pane -e` through freeze with `--language ansi` to preserve all RGB color information.


**重要提示**：每次截取截图后，使用**Read工具**查看PNG文件。这是让评审具备「视觉性」的关键——你需要直接查看渲染后的TUI，评估其颜色、布局、对比度和设计质量。

**关于tmux_screenshot与take_color_screenshot的说明**：`tmux_helpers.sh`中的`tmux_screenshot`辅助函数可能无法保留ratatui/crossterm TUI的RGB颜色。对于任何基于ratatui、crossterm或类似Rust终端框架开发的TUI，请使用上述`take_color_screenshot`函数，它会将`capture-pane -e`的输出通过freeze工具并指定`--language ansi`参数，以保留所有RGB颜色信息。

The 10 Dimensions

10个UX评估维度

Read references/heuristics.md for detailed test procedures, pass/fail criteria, and best-in-class examples for each dimension.

Responsiveness - Every keypress produces visible change within 100ms
Input Mode Integrity - Trigger characters don't hijack mid-sentence text input
Visual Feedback - Every app state has a distinct visual indicator
Navigation & Escape - Escape always goes back, never get stuck
Feedback Loops - Submit triggers: clear, echo, loading, stream, completion
Error & Empty States - Every state has a designed appearance, no blank screens
Layout & Resize - Usable at 80x24, scales to 200x50+
Keyboard Design - All features keyboard-reachable, shortcuts discoverable
Permission Flows - Destructive actions show preview, require confirmation
Visual Design & Color - Color communicates meaning, sufficient contrast, consistent palette

查看references/heuristics.md获取每个维度的详细测试流程、通过/失败标准以及业界最佳实践示例。

响应性 - 每一次按键操作都应在100ms内产生可见变化
输入模式完整性 - 触发字符不会劫持正在输入的文本
视觉反馈 - 应用的每种状态都有独特的视觉指示器
导航与退出 - 按Escape键总能返回上一级，不会陷入卡顿状态
反馈循环 - 提交触发：清晰、回显、加载、流式传输、完成
错误与空状态 - 每种状态都有设计好的呈现样式，无空白屏幕
布局与窗口调整 - 在80x24尺寸下可用，并能适配200x50以上的尺寸
键盘设计 - 所有功能都可通过键盘访问，快捷键易于发现
权限流程 - 破坏性操作会显示预览，并需要确认
视觉设计与色彩 - 颜色传递特定含义、对比度充足、调色板一致

Visual Review Checklist

视觉评审检查清单

When reviewing screenshots with the Read tool, evaluate:

使用Read工具评审截图时，需评估以下内容：

Color

颜色

Semantic color: Status colors (green=success, red=error, yellow=warning) used consistently
Color richness: Not monochrome — uses color to create visual hierarchy
Contrast: Text readable against background (no light-gray-on-dark-gray)
Consistency: Same element type uses same color everywhere
Restraint: Not a rainbow — limited palette with purpose

语义化颜色：状态颜色（绿色=成功、红色=错误、黄色=警告）使用一致
颜色丰富度：非单色——使用颜色构建视觉层次
对比度：文本在背景上清晰可读（无深灰底浅灰字）
一致性：同一类型的元素在所有位置使用相同颜色
克制性：非彩虹色——使用有限且有明确用途的调色板

Layout

布局

Density: Information-dense without feeling cluttered
Alignment: Elements align to a grid, no ragged edges
Whitespace: Breathing room between sections
Proportions: Input area, content area, and status bar are well-sized

密度：信息密集但不显得杂乱
对齐：元素对齐到网格，无参差不齐的边缘
空白空间：各部分之间有呼吸空间
比例：输入区、内容区和状态栏的尺寸设置合理

Typography

排版

Hierarchy: Headers/titles are visually distinct (bold, color, or size)
Readability: Line lengths reasonable (not 200-char lines)
Symbols: Unicode symbols (●, ◐, ✓, ✗) used for status, not ASCII

层次结构：标题/副标题在视觉上有区分（加粗、颜色或尺寸）
可读性：行长度合理（无200字符以上的行）
符号：使用Unicode符号（●、◐、✓、✗）表示状态，而非ASCII字符

Polish

细节打磨

No artifacts: No stray characters, broken box-drawing, or rendering glitches
Consistent borders: Border style (thin/thick/double) is consistent
Professional feel: Would this look good in a demo or conference talk?

无伪影：无 stray 字符、破损的绘图边框或渲染故障
边框一致性：边框样式（细/粗/双线条）保持一致
专业感：在演示或会议演讲中展示时是否美观

Color Assertions (Programmatic)

颜色断言（自动化检查）

Use these alongside visual review for automated checks:

bash

undefined

配合视觉评审，使用以下命令进行自动化检查：

bash

undefined

Check that the pane uses color (not monochrome)

检查面板是否使用颜色（非单色）

tmux_assert_not_monochrome "$SESSION" "TUI uses color"

Check that at least 4 distinct colors are used (visual hierarchy)

检查至少使用了4种不同的颜色（视觉层次）

tmux_assert_min_colors "$SESSION" 4 "sufficient color variety"

Check specific semantic colors

检查特定的语义化颜色

tmux_assert_text_color "$SESSION" "READY" "32" "READY is green" tmux_assert_text_color "$SESSION" "ERROR" "31" "ERROR is red" tmux_assert_has_color "$SESSION" "33" "yellow/warning color present"

undefined

tmux_assert_text_color "$SESSION" "READY" "32" "READY是绿色" tmux_assert_text_color "$SESSION" "ERROR" "31" "ERROR是红色" tmux_assert_has_color "$SESSION" "33" "yellow/warning color present"

undefined

Report Format

报告格式

markdown

undefined

markdown

undefined

TUI Review: [App Name]

TUI评审：[应用名称]

Overall Grade: [A/B/C/D/F] Tested at: [terminal size] | Binary: [path] | Date: [date] Screenshots: [directory path]

整体评分：[A/B/C/D/F] 测试环境：[终端尺寸] | 二进制文件路径：[路径] | 日期：[日期] 截图目录：[目录路径]

Summary

总结

[2-3 sentence verdict]

[2-3句话的评审结论]

Screenshots

截图展示

Initial State

初始状态

[Visual observations: layout, color palette, first impression]

[视觉观察：布局、调色板、第一印象]

Key States

关键状态

[Visual observations for each captured state]

[每个捕获状态的视觉观察]

Resize Behavior

窗口调整行为

[How the layout adapts]

[布局如何适配不同尺寸]

Scores

维度得分

#	Dimension	Grade	Issues
1	Responsiveness
2	Input Integrity
3	Visual Feedback
4	Navigation
5	Feedback Loops
6	Error States
7	Layout
8	Keyboard Design
9	Permission Flows
10	Visual Design & Color

序号	维度	评分	问题
1	响应性
2	输入完整性
3	视觉反馈
4	导航
5	反馈循环
6	错误状态
7	布局
8	键盘设计
9	权限流程
10	视觉设计与色彩

Findings

发现问题

CRITICAL (must fix)

严重问题（必须修复）

[finding with file:line if known]

[发现内容，若已知则包含文件:行号]

WARNING (should fix)

警告问题（建议修复）

[finding]

[发现内容]

INFO (nice to have)

信息提示（优化建议）

[finding]

[发现内容]

vs Best-in-Class

与业界顶尖产品对比

[How this TUI compares to Claude Code/OpenCode/Codex patterns]


**Grading**: A = no issues. B = minor polish needed. C = noticeable UX friction. D = broken workflows. F = unusable.

[该TUI与Claude Code/OpenCode/Codex的模式对比]


**评分标准**：A = 无问题；B = 需少量细节打磨；C = UX存在明显卡顿；D = 工作流程破损；F = 无法使用。

Quick Start for Unknown TUIs

未知TUI快速评审步骤

When reviewing a TUI you haven't seen before:

Launch and wait for ready
Screenshot the initial state and visually review it
Press
```
?
```
then
```
F1
```
to find help — screenshot if found
Try
```
/
```
for command palette — screenshot if found
Try
```
Tab
```
, arrow keys,
```
j
```
/
```
k
```
for navigation
Try
```
Escape
```
from every state you reach
Type text to find input areas
Submit a message and screenshot the processing + response states
Take resize screenshots at all 4 sizes
Run color assertions (monochrome check, min colors, semantic colors)
Visually review ALL screenshots using Read tool
Then run the remaining dimension tests

当评审一款你从未接触过的TUI时：

启动并等待应用就绪
截取初始状态截图并进行视觉评审
按
```
?
```
然后按
```
F1
```
查找帮助——若找到则截图
尝试按
```
/
```
打开命令面板——若找到则截图
尝试使用
```
Tab
```
、方向键、
```
j
```
/
```
k
```
进行导航
在进入的每个状态下尝试按
```
Escape
```
键
输入文本以找到输入区域
提交一条消息并截取处理中+响应完成状态的截图
截取所有4种尺寸的窗口调整截图
运行颜色断言（单色检查、最少颜色数、语义化颜色）
使用Read工具视觉评审所有截图
然后进行剩余维度的测试

tui-review

Original

Translation

TUI Review

TUI评审

Style Opinion: Borders

风格建议：边框

Process

评审流程

Setup

环境设置

CRITICAL: Enable True-Color in tmux (RGB colors)

关键步骤：在tmux中启用真彩色（RGB颜色）

Enable true-color (Tc) for ALL terminal types — run ONCE per tmux server

为所有终端类型启用真彩色（Tc）——每个tmux服务器只需运行一次

Should show: |.[38;2;R;G;Bm| sequences (RGB foreground color codes)

应显示：|.[38;2;R;G;Bm| 序列（RGB前景色代码）

If empty: Tc override is not working

若为空：Tc覆盖未生效

Screenshot Method

截图方法

Take a color screenshot

截取彩色截图

IMPORTANT: freeze may hang — always run with a timeout

重要提示：freeze可能会挂起——始终配合超时命令运行

Full Setup

完整设置脚本

CRITICAL: Enable true-color BEFORE starting any TUI session

关键步骤：在启动任何TUI会话前启用真彩色

Launch with COLORTERM=truecolor to help crossterm detect color support

启动时设置COLORTERM=truecolor，帮助crossterm检测颜色支持

Take first color screenshot

截取第一张彩色截图

Visually inspect it

视觉检查截图

Use Read tool on the PNG path

在PNG路径上使用Read工具

Screenshot Protocol

截图协议

Helper function for color screenshots (use instead of tmux_screenshot for ratatui TUIs)

彩色截图辅助函数（针对ratatui TUI，替代tmux_screenshot）

Example: screenshot after opening help

示例：打开帮助后截图

Example: resize screenshots

示例：窗口调整截图

Visually inspect a screenshot (CRITICAL — actually look at it)

视觉检查截图（关键步骤——实际查看渲染后的TUI，评估颜色、布局、对比度和设计质量）

Use the Read tool on the PNG path

在PNG路径上使用Read工具

The 10 Dimensions

10个UX评估维度

Visual Review Checklist

视觉评审检查清单

Color

颜色

Layout

布局

Typography

排版

Polish

细节打磨

Color Assertions (Programmatic)

颜色断言（自动化检查）

Check that the pane uses color (not monochrome)

检查面板是否使用颜色（非单色）

Check that at least 4 distinct colors are used (visual hierarchy)

检查至少使用了4种不同的颜色（视觉层次）

Check specific semantic colors

检查特定的语义化颜色

Report Format

报告格式

TUI Review: [App Name]

TUI评审：[应用名称]

Summary

总结

Screenshots

截图展示

Initial State

初始状态

Key States