# UI Framework Guidelines

## CLI UI

- Use Ink (React for CLIs) for interactive command-line interfaces
- Available slash commands:
  - `/expand` - Expands all collapsible results
  - `/collapse` - Collapses all collapsible results
- Follow Ink's component patterns for layout and styling
- Always define proper TypeScript interfaces for component props
- Use functional components with TypeScript generics for type safety
- Follow React Hooks rules strictly:
  - Declare all hooks unconditionally at top level
  - Maintain consistent hook order between renders
  - Never call hooks conditionally or in loops
- For global UI state in Ink:
  - Use external state stores (e.g. Map) for cross-component state
  - Force re-renders with version counter when global state changes
  - Avoid DOM manipulation - Ink doesn't have a real DOM
- For list selection components:
  - Use arrow key navigation
  - Highlight selected item with cyan
  - Include help text for keyboard controls
  - Handle API calls in useEffect
  - Maintain selected index state
- Keep TUI components in src/components/tui directory
- Use @inkjs/ui for common CLI components like inputs, selects
- Always use .js extensions in import paths for TypeScript-compiled components
- Extract reusable UI elements into dedicated components
- Maintain consistent prop naming conventions:
  - Use `on[Action]` format for event handlers
  - Prefix handler props with `on`
- Follow React Hooks rules strictly:
  - Declare all hooks unconditionally at top level
  - Maintain consistent hook order between renders

## CLI Argument Handling
- CLI flags take precedence over environment variables
- Use yargs for command-line argument parsing
- Follow this configuration source priority:
  1. Command-line flags
  2. Environment variables
  3. Prompted user input
- Follow React Hooks rules strictly:
  - Declare all hooks unconditionally at top level
  - Maintain consistent hook order between renders
  - Never call hooks conditionally or in loops