1# UI Development Instructions
 2
 3## General Guidelines
 4- Never use commands to send messages when you can directly mutate children or state.
 5- Keep things simple; do not overcomplicate.
 6- Create files if needed to separate logic; do not nest models.
 7
 8## Architecture
 9
10### Main Model (`model/ui.go`)
11Keep most of the logic and state in the main model. This is where:
12- Message routing happens
13- Focus and UI state is managed
14- Layout calculations are performed
15- Dialogs are orchestrated
16
17### Components Should Be Dumb
18Components should not handle bubbletea messages directly. Instead:
19- Expose methods for state changes
20- Return `tea.Cmd` from methods when side effects are needed
21- Handle their own rendering via `Render(width int) string`
22
23### Chat Logic (`model/chat.go`)
24Most chat-related logic belongs here. Individual chat items in `chat/` should be simple renderers that cache their output and invalidate when data changes (see `cachedMessageItem` in `chat/messages.go`).
25
26## Key Patterns
27
28### Composition Over Inheritance
29Use struct embedding for shared behaviors. See `chat/messages.go` for examples of reusable embedded structs for highlighting, caching, and focus.
30
31### Interfaces
32- List item interfaces are in `list/item.go`
33- Chat message interfaces are in `chat/messages.go`
34- Dialog interface is in `dialog/dialog.go`
35
36### Styling
37- All styles are defined in `styles/styles.go`
38- Access styles via `*common.Common` passed to components
39- Use semantic color fields rather than hardcoded colors
40
41### Dialogs
42- Implement the dialog interface in `dialog/dialog.go`
43- Return message types from `Update()` to signal actions to the main model
44- Use the overlay system for managing dialog lifecycle
45
46## File Organization
47- `model/` - Main UI model and major components (chat, sidebar, etc.)
48- `chat/` - Chat message item types and renderers
49- `dialog/` - Dialog implementations
50- `list/` - Generic list component with lazy rendering
51- `common/` - Shared utilities and the Common struct
52- `styles/` - All style definitions
53- `anim/` - Animation system
54- `logo/` - Logo rendering
55
56## Common Gotchas
57- Always account for padding/borders in width calculations
58- Use `tea.Batch()` when returning multiple commands
59- Pass `*common.Common` to components that need styles or app access