Feat: documentation, UI/UX

crates/ratatui/README.md

@@ -0,0 +1,25 @@
+# cagire-ratatui
+
+TUI widget library and theme system for Cagire.
+
+## Widgets
+
+`category_list`, `confirm`, `editor`, `file_browser`, `hint_bar`, `lissajous`, `list_select`, `modal`, `nav_minimap`, `props_form`, `sample_browser`, `scope`, `scroll_indicators`, `search_bar`, `section_header`, `sparkles`, `spectrum`, `text_input`, `vu_meter`, `waveform`
+
+## Theme System
+
+The `theme/` module provides a palette-based theming system using Oklab color space.
+
+| Module | Description |
+|--------|-------------|
+| `mod` | `THEMES` array, `CURRENT_THEME` thread-local, `get()`/`set()` |
+| `palette` | `Palette` (14 fields), color manipulation helpers (`shift`, `mix`, `tint_bg`, ...) |
+| `build` | Derives ~190 `ThemeColors` fields from a `Palette` |
+| `transform` | HSV-based hue rotation for generated palettes |
+
+25 built-in themes.
+
+## Key Types
+
+- **`Palette`** — 14-field color definition, input to theme generation
+- **`ThemeColors`** — ~190 derived semantic colors used throughout the UI