# RAVN UI: Comprehensive AI & Developer Guide
RAVN UI is a high-fidelity, minimal, and "CDN-first" UI system designed for building elite SaaS dashboards in minutes. It eliminates the complexity of modern build chains (Tailwind, Webpack, PostCSS) in favor of pure, semantic CSS and high-performance Javascript.
## 🎯 Purpose & Philosophy
The primary goal of RAVN UI is **speed to high-fidelity**.
- **No Tailwind Dependency**: Avoids utility-class bloat while maintaining a professional look.
- **Zero Configuration**: A fully functional, themed environment is one `` tag away.
- **SaaS First**: Every component is optimized for high-density, data-heavy dashboard interfaces.
- **PHP-Style Organization**: Encourages a clean, logical file structure (Assets/Pages/Functions) that is easy for both humans and AI to navigate.
---
## 🏗️ Core Architecture
### 1. The Design System (CSS)
The CSS is split into four layers:
- **Tokens (`tokens.css`)**: Defines the core design language—colors, spacing scale (1-12), typography, and shadows using CSS variables.
- **Base (`base.css`)**: Resets the browser defaults and sets up the foundation (typography, scrollbars, etc.).
- **Components (`components.css`)**: Semantic classes for complex elements (`.card`, `.btn`, `.sidebar`, `.layout-shell`, `.table`).
- **Utilities (`utilities.css`)**: Low-level helper classes for layout (`.flex`, `.grid`, `.gap-*`, `.mt-*`, `.text-*`).
### 2. Theming System (`themes.css`)
RAVN UI supports 12+ premium themes (Dark, Zinc, Claude, Midnight, Indigo, etc.) via the `data-theme` attribute on the `` or `` tag.
- Themes redefine the core semantic variables (e.g., `--primary`, `--background`, `--card`).
- The library uses **glassmorphism** and subtle gradients in dark modes for a premium feel.
### 3. Logic & SPA Utilities (`ui.js`)
The `RAVN` global object provides high-level control:
- **`RAVN.store`**: Global reactive state management (`.set`, `.get`, `.subscribe`).
- **`RAVN.route(path)`**: Handles SPA navigation, URL hash syncing, and view swapping.
- **`RAVN.on(event, selector, handler)`**: Built-in event delegation to avoid inline `onclick`.
- **`RAVN.fetch(url, options)`**: Minimal wrapper over native fetch that returns JSON.
- **`RAVN.toggleSidebar()`**: Manages the `.sidebar-collapsed` state on the ``.
---
## 📂 Project Structure (Recommended)
When an AI or developer works on a RAVN UI project, they should adhere to this "Classic/PHP-style" organization:
- `/index.html`: The root entry point.
- `/css/app.css`: Custom project-specific overrides.
- `/app.js`: Application logic entry point with the standard `render()` pattern.
- `/components/`: Pure functions returning HTML strings (e.g., `card.js`, `modal.js`).
- `/functions/`: Reusable Javascript utility modules (e.g., `store.js`, `api.js`).
- `/pages/`: Secondary HTML views (for MPA architecture).
---
## 🧩 Key Components for AI to Know
### The Layout Shell
```html