claude-tui-dev.md

TUI Development Strategy: React-First Approach

Core Concept

Leverage Claude's strong React reasoning to design Terminal User Interfaces (TUIs) by starting with familiar React component patterns, then layering in terminal-specific implementation.

Why This Works

• React's component model maps naturally to TUI design - props, composition, and declarative rendering translate directly
• Layout concepts transfer cleanly - flexbox, boxes, borders already exist in TUI libraries
• Separation of concerns - visual structure first, event handling second reduces complexity
• Plays to strengths - uses established mental models rather than learning new domains from scratch

Three-Phase Workflow

Phase 1: Visual Design (React-Like Pseudocode)

Ask Claude to design using React component syntax, focusing purely on visual hierarchy:

function Dashboard() {
  return (
    <Box flexDirection="column" height="100%">
      <Header title="System Monitor" />
      <Box flexDirection="row" flexGrow={1}>
        <Sidebar width={20} items={menuItems} />
        <MainPanel>
          <MetricsGrid data={metrics} />
        </MainPanel>
      </Box>
      <StatusBar message="Ready" />
    </Box>
  );
}

Deliverables: Component hierarchy, layout specs, prop definitions, data flow

Phase 2: Event Handling Integration

Layer on interactivity using React-familiar patterns:

Option A - Event Props:

<Button 
  label="Submit"
  onPress={() => handleSubmit()}
  onFocus={() => setFocused(true)}
/>

Option B - Hooks:

function MyComponent() {
  useKeyPress('enter', handleSubmit);
  const [selected, setSelected] = useState(0);
  // ...
}

Deliverables: Event attachment points, state management strategy, interaction flows

Phase 3: TUI Library Mapping

Translate React design to your chosen TUI library:

React Design →

<Box flexDirection="row">
  <Text color="blue">Status:</Text>
  <Text bold>{status}</Text>
</Box>

Ink (actual React) → Direct copy
Blessed → Map to blessed API
Custom → Implement render logic

Practical Prompting Examples

Initial Design:

"Design a TUI file browser with directory tree on left, file list on right, and preview pane at bottom. Use React-like components focusing only on layout and visual hierarchy. No event handling yet."

Adding Interactivity:

"Add keyboard navigation to the file browser design: arrow keys for selection, enter to open, tab to switch panes. Use React patterns for event handling."

Refinement:

"Convert this React-style TUI design to [blessed/ink/custom] library implementation."

Key Benefits

• Familiar mental models - component composition, props, state
• Clear separation - visual design and event handling as distinct phases
• Iterative refinement - nail the UI before adding complexity
• Better communication - React syntax as shared language between human and AI

Recommended TUI Libraries

• Ink - Actual React for terminals (most direct mapping)
• Blessed - Mature, full-featured (requires translation layer)
• Custom - Build renderer from React design specs

Success Pattern

1. Request React-style visual design for your use case
2. Review and refine component structure
3. Add event handling using React patterns
4. Implement in chosen TUI library
5. Iterate on specifics with library in mind

---

Remember: Visual composition and event handling are separate concerns. Design the structure first, then make it interactive.