# Nikala UI — LLM & AI Developer Reference Manual

> Nikala UI is a copy-paste component system and reactive primitives suite for SolidJS built natively for Tailwind CSS v4. Honoring Georgian painter Niko Pirosmani (Nikala).

- Official Website: https://nikala.dev
- GitHub Repository: https://github.com/nikala-ui/ui
- Documentation Portal: https://nikala.dev/docs
- Interactive Playground: https://nikala.dev/playground
- Raw LLM Reference: https://nikala.dev/llms.txt

---

## 1. Core Architecture & Philosophy

Nikala UI rejects heavy `node_modules` UI dependencies for component structures and reactive primitives. Instead, it follows a 100% **Pure Copy-Paste Ownership** model.

### Key Architectural Pillars:
- **Native SolidJS Reactivity**: Fine-grained reactive signals, props splitting (`splitProps`), and explicit memoization (`children(() => props.children)`).
- **Tailwind CSS v4 Native**: Built on modern `@import "tailwindcss";` setups, CSS-first `@theme` variables, and semantic color design tokens without legacy JS configs.
- **Full Source Ownership**: The CLI writes components to `src/components/ui/` and primitive hooks directly to `src/hooks/`. Developers own, inspect, and customize all generated source files.
- **Zero Lock-In**: Decoupled `@nikala-ui/cli` client, `@nikala-ui/core` registry, and `@nikala-ui/mcp` server for remote HTTP(S) manifest installs and direct AI IDE integration.
- **Model Context Protocol (MCP)**: Native `@nikala-ui/mcp` integration supporting Stdio local execution (`npx @nikala-ui/mcp`) and remote HTTP/SSE streaming (`https://nikala.dev/api/mcp/sse`) with callable tools, pre-built AI prompts, and SolidJS engineering resources.

---

## 2. CLI Command Quick Reference

### Installation & Initialization
```bash
# Initialize Nikala UI configuration, cn helper, path aliases, and theme CSS
bunx @nikala-ui/cli init
```

### Adding UI Components
```bash
# Interactive autocomplete multiselect menu for UI components
bunx @nikala-ui/cli add

# Direct installation of specific UI components
bunx @nikala-ui/cli add button input card dialog

# Add all available UI components
bunx @nikala-ui/cli add --all

# Overwrite existing component files
bunx @nikala-ui/cli add button --overwrite
```

### Upgrading Components & Hooks
```bash
# Interactive menu to select installed items to upgrade
bunx @nikala-ui/cli upgrade

# Alias command to update specific items or all
bunx @nikala-ui/cli update button dialog create-clipboard
bunx @nikala-ui/cli update --all
```

### Removing & Uninstalling Components
```bash
# Interactive menu to safely remove components from codebase
bunx @nikala-ui/cli remove

# Direct uninstall of specific components or hooks
bunx @nikala-ui/cli uninstall button dialog
bunx @nikala-ui/cli remove -h create-clipboard
```

### Adding Primitive Hooks (Pure Copy-Paste to `src/hooks/`)
```bash
# Interactive autocomplete multiselect menu for reactive hooks
bunx @nikala-ui/cli add --hook

# Direct copy-paste installation of specific hooks to src/hooks/
bunx @nikala-ui/cli add --hook create-audio create-fetch create-clipboard

# Shortcut option (-h)
bunx @nikala-ui/cli add -h create-websocket
```

### Theme Management & Diagnostics
```bash
# Set primary brand accent color and base gray palette
bunx @nikala-ui/cli theme set wine zinc

# Run workspace health diagnostics
bunx @nikala-ui/cli validate
```

---

## 3. Strict Engineering Rules for AI Code Generation

When generating or editing SolidJS code using Nikala UI components and hooks, AI models MUST follow these strict rules:

1. **NEVER Destructure Props Directly**:
   - `const { variant, class: className } = props;` -> **FORBIDDEN** (breaks SolidJS signal tracking).
   - `const [local, others] = splitProps(props, ["variant", "class"]);` -> **REQUIRED**.

2. **Children Inspection & Tab Hydration**:
   - ALWAYS use `const resolved = children(() => props.children);` when inspecting or conditionally rendering JSX children inside tab containers or dynamic branches.

3. **SSR Anti-FOUC Theme Script**:
   - When using `ThemeProvider`, ALWAYS place `<ThemeScript storageKey="nikala-theme" />` synchronously inside `<head>` or root HTML before `<ThemeProvider>` to eliminate flash of unstyled content during SSR.

4. **Hook Imports**:
   - Import copy-pasted hooks locally from project alias: `import { createClipboard } from "@/hooks/create-clipboard";`

---

## 4. UI Components Registry (34 Components)

Below is the complete inventory of available Nikala UI components with exported JSX elements:

1. **Accordion**: `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`
2. **Alert**: `Alert`, `AlertTitle`, `AlertDescription`
3. **Avatar**: `Avatar`, `AvatarImage`, `AvatarFallback`
4. **Badge**: `Badge`
5. **Banner**: `Banner`
6. **Breadcrumb**: `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis`
7. **Button**: `Button`
8. **Card**: `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`
9. **Checkbox**: `Checkbox`
10. **Combobox**: `Combobox`, `ComboboxControl`, `ComboboxInput`, `ComboboxTrigger`, `ComboboxContent`, `ComboboxItem`, `ComboboxGroup`
11. **Command**: `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandFooter`
12. **Dialog**: `Dialog`, `DialogTrigger`, `DialogOverlay`, `DialogContent`, `DialogHeader`, `DialogFooter`, `DialogTitle`, `DialogDescription`, `DialogClose`
13. **Dropdown Menu**: `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuLabel`, `DropdownMenuSeparator`, `DropdownMenuShortcut`, `DropdownMenuSub`, `DropdownMenuSubTrigger`, `DropdownMenuSubContent`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioGroup`, `DropdownMenuRadioItem`
14. **Hover Card**: `HoverCard`, `HoverCardTrigger`, `HoverCardContent`, `HoverCardArrow`
15. **Input**: `Input`
16. **Input Group**: `InputGroup`, `InputGroupInput`, `InputGroupAddon`
17. **Kbd**: `Kbd`, `KbdGroup`
18. **Label**: `Label`
19. **List**: `List`, `ListGroup`, `ListHeader`, `ListItem`
20. **Pin Input**: `PinInput`, `PinInputInput`, `PinInputLabel`
21. **Popover**: `Popover`, `PopoverTrigger`, `PopoverContent`
22. **Progress**: `Progress`, `ProgressIndicator`
23. **Radio Group**: `RadioGroup`, `RadioGroupItem`, `RadioGroupItemLabel`
24. **Select**: `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`
25. **Separator**: `Separator`
26. **Sheet / Drawer**: `Sheet`, `SheetTrigger`, `SheetOverlay`, `SheetContent`, `SheetHeader`, `SheetFooter`, `SheetTitle`, `SheetDescription`, `SheetClose`
27. **Skeleton**: `Skeleton`
28. **Slider**: `Slider`, `SliderTrack`, `SliderFill`, `SliderThumb`, `SliderLabel`, `SliderValueLabel`
29. **Switch**: `Switch`
30. **Tabs**: `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`
31. **Textarea**: `Textarea`
32. **Theme Manager**: `ThemeProvider`, `ThemeScript`, `ThemeToggle`, `useTheme`
33. **Toast**: `Toast`, `ToastTitle`, `ToastDescription`, `ToastCloseButton`, `ToastRegion`, `ToastList`, `showToast`
34. **Tooltip**: `Tooltip`, `TooltipTrigger`, `TooltipContent`, `TooltipArrow`

---

## 5. Reactive Primitives / Hooks Registry (40 Hooks)

Nikala UI primitives are written directly to `src/hooks/<hook-name>.ts`. Below is the complete catalog:

1. **`createActiveElement`** — Tracks currently focused DOM element (`activeElement()`, `hasFocus()`).
2. **`createAudio` / `createVideo`** — Controls media playback (`isPlaying()`, `duration()`, `currentTime()`, `toggle()`, `seek()`, `setVolume()`).
3. **`createBattery`** — Observes device battery level, charging status, and time metrics.
4. **`createClickOutside`** — Detects clicks outside target element refs (`createClickOutside(targetRef, handler)`).
5. **`createClipboard`** — Copies text to clipboard with auto-reset status (`copied()`, `copy(text)`, `error()`).
6. **`createColorMode`** — Manages dark/light theme signals and system preference detection.
7. **`createControllableSignal`** — Primitive supporting both controlled and uncontrolled state patterns.
8. **`createDebounce` / `createThrottle`** — Rate-limits function executions and reactive signal updates.
9. **`createDisclosure`** — Manages boolean open/close disclosure state (`isOpen()`, `open()`, `close()`, `toggle()`).
10. **`createDocumentTitle`** — Dynamically updates browser tab title with restore on unmount.
11. **`createEventSource`** — Subscribes to Server-Sent Events (SSE) streams (`data()`, `status()`, `close()`).
12. **`createFavicon`** — Updates browser tab favicon dynamically from URLs or SVG data URIs.
13. **`createFetch`** — Handles HTTP REST API requests (`data()`, `loading()`, `error()`, `refetch()`).
14. **`createFocusTrap`** — Traps keyboard focus inside modal containers for accessibility.
15. **`createForm`** — Handles form field state, dynamic validation rules, errors, and submission.
16. **`createFullscreen`** — Requests and monitors element or document fullscreen state (`isFullscreen()`, `toggle()`).
17. **`createGeolocation`** — Tracks real-time GPS coordinates, accuracy, speed, and heading.
18. **`createHover`** — Tracks element mouse hover state with enter/exit delay configurations.
19. **`createIdle`** — Detects user inactivity after customizable timeout threshold (`isIdle()`).
20. **`createInfiniteScroll`** — Manages infinite scroll pagination and auto-fetching next page triggers.
21. **`createInputMask`** — Applies formatting masks (phone numbers, credit cards, dates) to text inputs.
22. **`createIntersectionObserver`** — Observes element visibility and viewport intersection ratios.
23. **`createKeybindings`** — Listens to keyboard shortcuts, key combinations, and Escape key presses.
24. **`createLockScroll`** — Locks body or scrollable container scrolling when overlays are active.
25. **`createLongPress`** — Detects long press / touch hold interactions with custom duration.
26. **`createMediaQuery`** — Tracks CSS media queries and responsive Tailwind breakpoints.
27. **`createMousePosition`** — Tracks global window and element-relative cursor coordinates.
28. **`createNetworkStatus`** — Tracks browser online/offline status and network connection type.
29. **`createOrientation`** — Monitors screen orientation (`portrait` / `landscape`) and rotation angle.
30. **`createPermission`** — Queries and observes browser permission states (`granted`, `denied`, `prompt`).
31. **`createPrevious`** — Accesses previous value of a reactive signal accessor.
32. **`createResizeObserver`** — Observes element width, height, and content box bounding rects.
33. **`createScrollIntoView`** — Smoothly scrolls target element or ref into container viewport.
34. **`createScrollPosition`** — Tracks container scroll offset (X, Y), scroll direction, and boundaries.
35. **`createStorage`** — Reactive `createLocalStorage` and `createSessionStorage` with cross-tab sync.
36. **`createTimer`** — Provides interval timers, stopwatch counters, and formatted countdowns.
37. **`createUndoRedo`** — Manages undo/redo state history stacks and pointer state resets.
38. **`createWebNotification`** — Sends native browser desktop notifications and handles permission requests.
39. **`createWebSocket`** — WebSocket client connection manager with auto-reconnect and message parsing.
40. **`createWindowSize`** — Tracks window inner width and inner height reactively.

---

## 6. Complete Documentation Sitemap Index

### Overview Pages
- System Philosophy & Intro: https://nikala.dev/docs
- CLI Reference Guide: https://nikala.dev/docs/cli
- Tailwind v4 Theming System: https://nikala.dev/docs/theming
- Model Context Protocol (MCP): https://nikala.dev/docs/mcp
- Live Interactive Playground: https://nikala.dev/playground

### All Component Pages (34 Components)
- Accordion: https://nikala.dev/docs/components/accordion
- Alert: https://nikala.dev/docs/components/alert
- Avatar: https://nikala.dev/docs/components/avatar
- Badge: https://nikala.dev/docs/components/badge
- Banner: https://nikala.dev/docs/components/banner
- Breadcrumb: https://nikala.dev/docs/components/breadcrumb
- Button: https://nikala.dev/docs/components/button
- Card: https://nikala.dev/docs/components/card
- Checkbox: https://nikala.dev/docs/components/checkbox
- Combobox: https://nikala.dev/docs/components/combobox
- Command: https://nikala.dev/docs/components/command
- Dialog: https://nikala.dev/docs/components/dialog
- Dropdown Menu: https://nikala.dev/docs/components/dropdown-menu
- Hover Card: https://nikala.dev/docs/components/hover-card
- Input: https://nikala.dev/docs/components/input
- Input Group: https://nikala.dev/docs/components/input-group
- Kbd: https://nikala.dev/docs/components/kbd
- Label: https://nikala.dev/docs/components/label
- List: https://nikala.dev/docs/components/list
- Pin Input: https://nikala.dev/docs/components/pin-input
- Popover: https://nikala.dev/docs/components/popover
- Progress: https://nikala.dev/docs/components/progress
- Radio Group: https://nikala.dev/docs/components/radio-group
- Select: https://nikala.dev/docs/components/select
- Separator: https://nikala.dev/docs/components/separator
- Sheet: https://nikala.dev/docs/components/sheet
- Skeleton: https://nikala.dev/docs/components/skeleton
- Slider: https://nikala.dev/docs/components/slider
- Switch: https://nikala.dev/docs/components/switch
- Tabs: https://nikala.dev/docs/components/tabs
- Textarea: https://nikala.dev/docs/components/textarea
- Theme Manager: https://nikala.dev/docs/components/theme-manager
- Toast: https://nikala.dev/docs/components/toast
- Tooltip: https://nikala.dev/docs/components/tooltip

### All Reactive Hooks & Primitives (40 Hooks)
- createActiveElement: https://nikala.dev/docs/hooks/create-active-element
- createAudio: https://nikala.dev/docs/hooks/create-audio
- createBattery: https://nikala.dev/docs/hooks/create-battery
- createClickOutside: https://nikala.dev/docs/hooks/create-click-outside
- createClipboard: https://nikala.dev/docs/hooks/create-clipboard
- createColorMode: https://nikala.dev/docs/hooks/create-color-mode
- createControllableSignal: https://nikala.dev/docs/hooks/create-controllable-signal
- createDebounce: https://nikala.dev/docs/hooks/create-debounce
- createDisclosure: https://nikala.dev/docs/hooks/create-disclosure
- createDocumentTitle: https://nikala.dev/docs/hooks/create-document-title
- createEventSource: https://nikala.dev/docs/hooks/create-event-source
- createFavicon: https://nikala.dev/docs/hooks/create-favicon
- createFetch: https://nikala.dev/docs/hooks/create-fetch
- createFocusTrap: https://nikala.dev/docs/hooks/create-focus-trap
- createForm: https://nikala.dev/docs/hooks/create-form
- createFullscreen: https://nikala.dev/docs/hooks/create-fullscreen
- createGeolocation: https://nikala.dev/docs/hooks/create-geolocation
- createHover: https://nikala.dev/docs/hooks/create-hover
- createIdle: https://nikala.dev/docs/hooks/create-idle
- createInfiniteScroll: https://nikala.dev/docs/hooks/create-infinite-scroll
- createInputMask: https://nikala.dev/docs/hooks/create-input-mask
- createIntersectionObserver: https://nikala.dev/docs/hooks/create-intersection-observer
- createKeybindings: https://nikala.dev/docs/hooks/create-keybindings
- createLockScroll: https://nikala.dev/docs/hooks/create-lock-scroll
- createLongPress: https://nikala.dev/docs/hooks/create-long-press
- createMediaQuery: https://nikala.dev/docs/hooks/create-media-query
- createMousePosition: https://nikala.dev/docs/hooks/create-mouse-position
- createNetworkStatus: https://nikala.dev/docs/hooks/create-network-status
- createOrientation: https://nikala.dev/docs/hooks/create-orientation
- createPermission: https://nikala.dev/docs/hooks/create-permission
- createPrevious: https://nikala.dev/docs/hooks/create-previous
- createResizeObserver: https://nikala.dev/docs/hooks/create-resize-observer
- createScrollIntoView: https://nikala.dev/docs/hooks/create-scroll-into-view
- createScrollPosition: https://nikala.dev/docs/hooks/create-scroll-position
- createStorage: https://nikala.dev/docs/hooks/create-storage
- createTimer: https://nikala.dev/docs/hooks/create-timer
- createUndoRedo: https://nikala.dev/docs/hooks/create-undo-redo
- createWebNotification: https://nikala.dev/docs/hooks/create-web-notification
- createWebSocket: https://nikala.dev/docs/hooks/create-websocket
- createWindowSize: https://nikala.dev/docs/hooks/create-window-size