terminal-ui

SKILL.md

DevEx Developer Experience TUI Best Practices

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.

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

Rule Categories by Priority

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-

Quick Reference

1. Rendering & Output (CRITICAL)

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

2. Input & Keyboard (CRITICAL)

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

3. Component Patterns (HIGH)

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

4. State & Lifecycle (HIGH)

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

5. Prompt Design (MEDIUM-HIGH)

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

6. UX & Feedback (MEDIUM)

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

7. Configuration & CLI (MEDIUM)

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

8. Robustness & Compatibility (LOW-MEDIUM)

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

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

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md