terminal-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DevEx Developer Experience TUI Best Practices

DevEx 开发者体验 TUI 最佳实践

Comprehensive developer experience guide for building TypeScript terminal user interfaces using Ink (React for CLIs) and Clack prompts. Contains 42 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

这是一份面向使用Ink（CLI版React）和Clack提示符构建TypeScript终端用户界面的全面开发者体验指南。包含8个类别下的42条规则，按影响优先级排序，可指导自动化重构与代码生成。

When to Apply

适用场景

Reference these guidelines when:

Building CLI tools with interactive prompts using @clack/prompts
Creating React-based terminal UIs with Ink
Handling keyboard input and user interactions
Optimizing terminal rendering and preventing flicker
Designing developer-friendly CLI experiences

在以下场景中可参考本指南：

使用@clack/prompts构建带交互式提示符的CLI工具
使用Ink创建基于React的终端UI
处理键盘输入与用户交互
优化终端渲染并防止闪烁
设计对开发者友好的CLI体验

Rule Categories by Priority

按优先级划分的规则类别


render-
input-
tuicomp-
tuistate-
prompt-
ux-
tuicfg-
robust-

Priority	Category	Impact	Prefix
1	Rendering & Output	CRITICAL	`render-`
2	Input & Keyboard	CRITICAL	`input-`
3	Component Patterns	HIGH	`tuicomp-`
4	State & Lifecycle	HIGH	`tuistate-`
5	Prompt Design	MEDIUM-HIGH	`prompt-`
6	UX & Feedback	MEDIUM	`ux-`
7	Configuration & CLI	MEDIUM	`tuicfg-`
8	Robustness & Compatibility	LOW-MEDIUM	`robust-`


render-
input-
tuicomp-
tuistate-
prompt-
ux-
tuicfg-
robust-

优先级	类别	影响程度	前缀
1	渲染与输出	关键	`render-`
2	输入与键盘	关键	`input-`
3	组件模式	高	`tuicomp-`
4	状态与生命周期	高	`tuistate-`
5	提示符设计	中高	`prompt-`
6	用户体验与反馈	中	`ux-`
7	配置与CLI	中	`tuicfg-`
8	健壮性与兼容性	中低	`robust-`

Quick Reference

快速参考

1. Rendering & Output (CRITICAL)

1. 渲染与输出（关键）

```
render-single-write
```
- Batch Terminal Output in Single Write
```
render-overwrite-dont-clear
```
- Overwrite Content Instead of Clear and Redraw
```
render-synchronized-output
```
- Use Synchronized Output Protocol for Animations
```
render-60fps-baseline
```
- Target 60fps for Smooth Animation
```
render-partial-updates
```
- Update Only Changed Regions
```
render-escape-sequence-batching
```
- Defer ANSI Escape Code Generation to Final Output

```
render-single-write
```
- 批量终端输出为单次写入
```
render-overwrite-dont-clear
```
- 覆盖内容而非清除后重绘
```
render-synchronized-output
```
- 使用同步输出协议实现动画
```
render-60fps-baseline
```
- 以60fps为目标实现流畅动画
```
render-partial-updates
```
- 仅更新变化区域
```
render-escape-sequence-batching
```
- 延迟ANSI转义码生成至最终输出

2. Input & Keyboard (CRITICAL)

2. 输入与键盘（关键）

```
input-useinput-hook
```
- Use useInput Hook for Keyboard Handling
```
input-immediate-feedback
```
- Provide Immediate Visual Feedback for Input
```
input-modifier-keys
```
- Handle Modifier Keys Correctly
```
input-isactive-focus
```
- Use isActive Option for Focus Management
```
input-escape-routes
```
- Always Provide Escape Routes

```
input-useinput-hook
```
- 使用useInput Hook处理键盘事件
```
input-immediate-feedback
```
- 为输入提供即时视觉反馈
```
input-modifier-keys
```
- 正确处理修饰键
```
input-isactive-focus
```
- 使用isActive选项管理焦点
```
input-escape-routes
```
- 始终提供退出路径

3. Component Patterns (HIGH)

3. 组件模式（高）

```
tuicomp-box-flexbox
```
- Use Box Component with Flexbox for Layouts
```
tuicomp-text-styling
```
- Use Text Component for All Visible Content
```
tuicomp-measure-element
```
- Use measureElement for Dynamic Sizing
```
tuicomp-static-for-logs
```
- Use Static Component for Log Output
```
tuicomp-percentage-widths
```
- Use Percentage Widths for Responsive Layouts
```
tuicomp-border-styles
```
- Use Border Styles for Visual Structure

```
tuicomp-box-flexbox
```
- 使用Box组件结合Flexbox实现布局
```
tuicomp-text-styling
```
- 使用Text组件处理所有可见内容
```
tuicomp-measure-element
```
- 使用measureElement实现动态尺寸调整
```
tuicomp-static-for-logs
```
- 使用Static组件处理日志输出
```
tuicomp-percentage-widths
```
- 使用百分比宽度实现响应式布局
```
tuicomp-border-styles
```
- 使用边框样式构建视觉结构

4. State & Lifecycle (HIGH)

4. 状态与生命周期（高）

```
tuistate-useapp-exit
```
- Use useApp Hook for Application Lifecycle
```
tuistate-cleanup-effects
```
- Always Clean Up Effects on Unmount
```
tuistate-functional-updates
```
- Use Functional State Updates to Avoid Stale Closures
```
tuistate-usecallback-stable
```
- Stabilize Callbacks with useCallback
```
tuistate-usememo-expensive
```
- Memoize Expensive Computations with useMemo

```
tuistate-useapp-exit
```
- 使用useApp Hook管理应用生命周期
```
tuistate-cleanup-effects
```
- 卸载时始终清理副作用
```
tuistate-functional-updates
```
- 使用函数式状态更新避免过时闭包
```
tuistate-usecallback-stable
```
- 使用useCallback稳定回调函数
```
tuistate-usememo-expensive
```
- 使用useMemo缓存昂贵计算

5. Prompt Design (MEDIUM-HIGH)

5. 提示符设计（中高）

```
prompt-group-flow
```
- Use Clack group() for Multi-Step Prompts
```
prompt-validation
```
- Validate Input Early with Descriptive Messages
```
prompt-cancellation
```
- Handle Cancellation Gracefully with isCancel
```
prompt-spinner-tasks
```
- Use Spinner and Tasks for Long Operations
```
prompt-custom-render
```
- Build Custom Prompts with @clack/core

```
prompt-group-flow
```
- 使用Clack group()实现多步骤提示符
```
prompt-validation
```
- 提前验证输入并提供描述性消息
```
prompt-cancellation
```
- 使用isCancel优雅处理取消操作
```
prompt-spinner-tasks
```
- 使用Spinner和Tasks处理长耗时操作
```
prompt-custom-render
```
- 基于@clack/core构建自定义提示符

6. UX & Feedback (MEDIUM)

6. 用户体验与反馈（中）

```
ux-progress-indicators
```
- Show Progress for Operations Over 1 Second
```
ux-color-semantics
```
- Use Colors Semantically and Consistently
```
ux-error-messages
```
- Write Actionable Error Messages
```
ux-next-steps
```
- Show Next Steps After Completion
```
ux-intro-outro
```
- Use Intro and Outro for Session Framing

```
ux-progress-indicators
```
- 为超过1秒的操作显示进度
```
ux-color-semantics
```
- 语义化且一致地使用颜色
```
ux-error-messages
```
- 编写可执行的错误消息
```
ux-next-steps
```
- 完成操作后显示后续步骤
```
ux-intro-outro
```
- 使用Intro和Outro构建会话框架

7. Configuration & CLI (MEDIUM)

7. 配置与CLI（中）

```
tuicfg-sensible-defaults
```
- Provide Sensible Defaults for All Options
```
tuicfg-env-vars
```
- Support Standard Environment Variables
```
tuicfg-flags-over-args
```
- Prefer Flags Over Positional Arguments
```
tuicfg-help-system
```
- Implement Comprehensive Help System
```
tuicfg-json-output
```
- Support Machine-Readable Output Format

```
tuicfg-sensible-defaults
```
- 为所有选项提供合理默认值
```
tuicfg-env-vars
```
- 支持标准环境变量
```
tuicfg-flags-over-args
```
- 优先使用标志而非位置参数
```
tuicfg-help-system
```
- 实现全面的帮助系统
```
tuicfg-json-output
```
- 支持机器可读的输出格式

8. Robustness & Compatibility (LOW-MEDIUM)

8. 健壮性与兼容性（中低）

```
robust-tty-detection
```
- Detect TTY and Adjust Behavior Accordingly
```
robust-signal-handling
```
- Handle Process Signals Gracefully
```
robust-exit-codes
```
- Use Meaningful Exit Codes
```
robust-terminal-restore
```
- Always Restore Terminal State on Exit
```
robust-graceful-degradation
```
- Degrade Gracefully for Limited Terminals

```
robust-tty-detection
```
- 检测TTY并相应调整行为
```
robust-signal-handling
```
- 优雅处理进程信号
```
robust-exit-codes
```
- 使用有意义的退出码
```
robust-terminal-restore
```
- 退出时始终恢复终端状态
```
robust-graceful-degradation
```
- 针对受限终端优雅降级

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules
render-single-write - Example rule file
input-useinput-hook - Example rule file

阅读单个参考文件获取详细说明与代码示例：

章节定义 - 类别结构与影响级别
规则模板 - 添加新规则的模板
render-single-write - 规则示例文件
input-useinput-hook - 规则示例文件

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需查看包含所有扩展规则的完整指南，请查看：

AGENTS.md