llms.txt
Compare with other sites' llms.txt files →# 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
- Current Version: v0.12.2
- GitHub Repository: https://github.com/nikala-ui/ui
- Documentation Portal: https://nikala.dev/docs
- Desktop & Tauri Suite: https://nikala.dev/docs/desktop
- 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.
- **Tauri v2 Desktop Native**: First-class support for cross-platform desktop applications (macOS, Windows 11, Linux) with custom frameless window chrome, drag regions, auto-updaters, and native OS hotkey primitives.
- **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
# Initialize with AI assistant rules (.cursor/rules/nikala.mdc, .cursorrules, AGENTS.md)
bunx @nikala-ui/cli init --ai
# Generate or update AI assistant rules in an existing workspace
bunx @nikala-ui/cli rules
```
### Listing Catalog & Installed Items
```bash
# List all components and hooks with installation status
bunx @nikala-ui/cli list
# Shortcut alias
bunx @nikala-ui/cli ls
# Filter by locally installed items
bunx @nikala-ui/cli list --installed
# Filter by type
bunx @nikala-ui/cli list --component
bunx @nikala-ui/cli list --hook
# Output as JSON
bunx @nikala-ui/cli list --json
```
### Adding UI & Desktop Components
```bash
# Interactive autocomplete multiselect menu for UI components
bunx @nikala-ui/cli add
# Direct installation of specific UI and Desktop components
bunx @nikala-ui/cli add button input card dialog sidebar titlebar updater-modal
# 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 sidebar 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 sidebar
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 create-tauri-window create-document-tabs
# Shortcut option (-h)
bunx @nikala-ui/cli add -h create-global-shortcut create-app-updater create-websocket create-drop-zone
```
### 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 fine-grained signal tracking).
- `const [local, others] = splitProps(props, ["variant", "class"]);` -> **REQUIRED**.
2. **Children Inspection & Tab Hydration**:
- ALWAYS use `const resolved = children(() => props.children);` when inspecting, iterating, or conditionally rendering JSX children inside tab containers or dynamic branches.
3. **Tailwind CSS v4 Semantic Design Tokens**:
- All components must use semantic design tokens defined in modern `@import "tailwindcss";` setups (`bg-background`, `text-foreground`, `bg-card`, `border-border`, `bg-primary`, etc.). Avoid hardcoded arbitrary color values.
4. **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.
5. **Hook Imports**:
- Import copy-pasted hooks locally from project alias: `import { createClipboard } from "@/hooks/create-clipboard";`
- Import desktop hooks locally: `import { createTauriWindow } from "@/hooks/create-tauri-window";`
- Import document tabs: `import { createDocumentTabs } from "@/hooks/create-document-tabs";`
---
## 4. UI & Desktop Components Registry (82 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. **Api Table**: `ApiTable`
4. **Aspect Ratio**: `AspectRatio`
5. **Avatar**: `Avatar`, `AvatarImage`, `AvatarFallback`
6. **Badge**: `Badge`
7. **Banner**: `Banner`
8. **Breadcrumb**: `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis`
9. **Bubble**: `Bubble`
10. **Button Group**: `ButtonGroup`
11. **Button**: `Button`
12. **Callout**: `Callout`, `CalloutTitle`, `CalloutDescription`
13. **Card**: `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`
14. **Checkbox**: `Checkbox`
15. **Code Block**: `CodeBlock`
16. **Code Group**: `CodeGroup`, `CodeGroupList`, `CodeGroupTrigger`, `CodeGroupContent`
17. **Collapsible**: `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent`
18. **Combobox**: `Combobox`, `ComboboxControl`, `ComboboxInput`, `ComboboxTrigger`, `ComboboxContent`, `ComboboxItem`, `ComboboxGroup`
19. **Command**: `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandFooter`
20. **Component Viewer**: `ComponentViewer`
21. **Context Menu**: `ContextMenu`, `ContextMenuTrigger`, `ContextMenuContent`, `ContextMenuItem`, `ContextMenuCheckboxItem`, `ContextMenuRadioGroup`, `ContextMenuRadioItem`, `ContextMenuLabel`, `ContextMenuSeparator`, `ContextMenuShortcut`, `ContextMenuSub`, `ContextMenuSubTrigger`, `ContextMenuSubContent`
22. **Dialog**: `Dialog`, `DialogTrigger`, `DialogOverlay`, `DialogContent`, `DialogHeader`, `DialogFooter`, `DialogTitle`, `DialogDescription`, `DialogClose`
23. **Dropdown Menu**: `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuLabel`, `DropdownMenuSeparator`, `DropdownMenuShortcut`, `DropdownMenuSub`, `DropdownMenuSubTrigger`, `DropdownMenuSubContent`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioGroup`, `DropdownMenuRadioItem`
24. **Dropzone**: `Dropzone`, `DropzoneTrigger`, `DropzoneZone`, `DropzoneContent`, `DropzonePreviewList`, `DropzonePreviewItem`
25. **Empty**: `Empty`, `EmptyIcon`, `EmptyTitle`, `EmptyDescription`, `EmptyAction`
26. **Field**: `Field`, `FieldLabel`, `FieldDescription`, `FieldError`
27. **File Tree**: `FileTree`, `FileTreeFolder`, `FileTreeFile`
28. **Footer**: `Footer`, `FooterContainer`, `FooterContent`, `FooterColumn`, `FooterColumnTitle`, `FooterColumnList`, `FooterLink`, `FooterBrand`, `FooterBottom`, `FooterCopyright`, `FooterSocials`
29. **Form**: `Form`
30. **Form Message**: `FormMessage`
31. **Hover Card**: `HoverCard`, `HoverCardTrigger`, `HoverCardContent`, `HoverCardArrow`
32. **Icon Button**: `IconButton`
33. **Input**: `Input`
34. **Input Group**: `InputGroup`, `InputGroupInput`, `InputGroupAddon`
35. **Kbd**: `Kbd`, `KbdGroup`
36. **Label**: `Label`
37. **List**: `List`, `ListGroup`, `ListHeader`, `ListItem`
38. **Logo**: `Logo`
39. **Marker**: `Marker`, `MarkerBadge`, `MarkerTyping`
40. **Marquee**: `Marquee`
41. **Message**: `Message`, `MessageAvatar`, `MessageContent`, `MessageHeader`, `MessageFooter`, `MessageAction`
42. **Navbar**: `Navbar`, `NavbarContainer`, `NavbarBrand`, `NavbarContent`, `NavbarItem`, `NavbarLink`, `NavbarActions`, `NavbarMobileDrawer`
43. **Navigation Menu**: `NavigationMenu`, `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuTrigger`, `NavigationMenuContent`, `NavigationMenuLink`
44. **Number Input**: `NumberInput`
45. **Package Manager Tabs**: `PackageManagerTabs`
46. **Pagination**: `Pagination`, `PaginationContent`, `PaginationItem`, `PaginationLink`, `PaginationPrevious`, `PaginationNext`, `PaginationEllipsis`
47. **Pin Input**: `PinInput`, `PinInputInput`, `PinInputLabel`
48. **Popover**: `Popover`, `PopoverTrigger`, `PopoverContent`
49. **Progress**: `Progress`, `ProgressIndicator`
50. **Radio Group**: `RadioGroup`, `RadioGroupItem`, `RadioGroupItemLabel`
51. **Rating**: `Rating`
52. **Resizable**: `ResizableGroup`, `ResizablePanel`, `ResizableHandle`
53. **Review Card**: `ReviewCard`, `ReviewHeader`, `ReviewProfile`, `ReviewAvatar`, `ReviewAuthor`, `ReviewRating`, `ReviewBody`, `ReviewFooter`
54. **Rich Text Editor**: `RichTextEditor`, `RichTextToolbar`, `RichTextButton`
55. **Scroll Area**: `ScrollArea`
56. **Section Heading**: `SectionHeading`
57. **Select**: `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`
58. **Separator**: `Separator`
59. **Sheet / Drawer**: `Sheet`, `SheetTrigger`, `SheetOverlay`, `SheetContent`, `SheetHeader`, `SheetFooter`, `SheetTitle`, `SheetDescription`, `SheetClose`
60. **Sidebar**: `SidebarProvider`, `Sidebar`, `SidebarTrigger`, `SidebarRail`, `SidebarInset`, `SidebarHeader`, `SidebarContent`, `SidebarFooter`, `SidebarSeparator`, `SidebarGroup`, `SidebarGroupLabel`, `SidebarGroupAction`, `SidebarGroupContent`, `SidebarMenu`, `SidebarMenuItem`, `SidebarMenuButton`, `SidebarMenuAction`, `SidebarMenuBadge`, `SidebarMenuSkeleton`, `SidebarMenuSub`, `SidebarMenuSubItem`, `SidebarMenuSubButton`, `useSidebar`
61. **Skeleton**: `Skeleton`
62. **Slider**: `Slider`, `SliderTrack`, `SliderFill`, `SliderThumb`, `SliderLabel`, `SliderValueLabel`
63. **Spinner**: `Spinner`
64. **Stat**: `Stat`, `StatGroup`, `StatHeader`, `StatLabel`, `StatIcon`, `StatValue`, `StatUnit`, `StatTrend`, `StatHelpText`
65. **Status**: `Status`
66. **Steps**: `Steps`, `Step`, `StepTitle`, `StepDescription`
67. **Switch**: `Switch`
68. **Table**: `Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`, `TableCell`, `TableCaption`
69. **Table of Contents**: `TableOfContents`, `Toc`
70. **Tabs**: `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`
71. **Textarea**: `Textarea`
72. **Theme Manager**: `ThemeProvider`, `ThemeScript`, `ThemeToggle`, `useTheme`
73. **Timeline**: `Timeline`, `TimelineItem`, `TimelineSeparator`, `TimelineIndicator`, `TimelineConnector`, `TimelineContent`, `TimelineHeader`, `TimelineTitle`, `TimelineDescription`, `TimelineTime`
74. **Titlebar**: `Titlebar`, `TitlebarControls`, `TitlebarTitle`, `TitlebarIcon`, `TitlebarActions`, `useTitlebar`
75. **TitlebarTabs**: `TitlebarTabs`, `TitlebarTabList`, `TitlebarTab`, `TitlebarTabAddButton`, `useTitlebarTabs`
76. **Toast**: `Toast`, `ToastTitle`, `ToastDescription`, `ToastCloseButton`, `ToastRegion`, `ToastList`, `showToast`
77. **Toggle**: `Toggle`
78. **Toggle Group**: `ToggleGroup`, `ToggleGroupItem`
79. **Tooltip**: `Tooltip`, `TooltipTrigger`, `TooltipContent`, `TooltipArrow`
80. **UpdaterModal / UpdaterDialog**: `UpdaterModal`
81. **Container**: `Container`
82. **Pager**: `Pager`, `PagerLink`
---
## 5. Reactive Primitives / Hooks Registry (48 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. **`createAppUpdater`** — Controls and observes Tauri v2 application updates, download progress stream, and app relaunch (`status()`, `progress()`, `updateInfo()`, `checkForUpdates()`, `downloadAndInstall()`, `relaunch()`).
3. **`createAudio` / `createVideo`** — Controls media playback (`isPlaying()`, `duration()`, `currentTime()`, `toggle()`, `seek()`, `setVolume()`).
4. **`createBattery`** — Observes device battery level, charging status, and time metrics.
5. **`createChatScroll`** — Automated conversation container scrolling with manual user scroll-up detection.
6. **`createClickOutside`** — Detects clicks outside target element refs (`createClickOutside(targetRef, handler)`).
7. **`createClipboard`** — Copies text to clipboard with auto-reset status (`copied()`, `copy(text)`, `error()`).
8. **`createColorMode`** — Manages dark/light theme signals and system preference detection.
9. **`createControllableSignal`** — Primitive supporting both controlled and uncontrolled state patterns.
10. **`createDebounce` / `createThrottle`** — Rate-limits function executions and reactive signal updates.
11. **`createDisclosure`** — Manages boolean open/close disclosure state (`isOpen()`, `open()`, `close()`, `toggle()`).
12. **`createDocumentTabs`** — Fine-grained reactive management for multi-document tabs, editor buffers, and browser tab stacks with mouse wheel scrolling, pinned tabs, unsaved dirty state, and adjacent activation on close (`tabs()`, `activeTabId()`, `addTab()`, `closeTab()`, `markDirty()`, `togglePin()`, `closeOthers()`).
13. **`createDocumentTitle`** — Dynamically updates browser tab title with restore on unmount.
14. **`createDropZone`** — Drag-and-drop file upload operations, file validation, and native file chooser trigger.
15. **`createEventSource`** — Subscribes to Server-Sent Events (SSE) streams (`data()`, `status()`, `close()`).
16. **`createFavicon`** — Updates browser tab favicon dynamically from URLs or SVG data URIs.
17. **`createFetch`** — Handles HTTP REST API requests (`data()`, `loading()`, `error()`, `refetch()`).
18. **`createFocusTrap`** — Traps keyboard focus inside modal containers for accessibility.
19. **`createForm`** — Handles form field state, dynamic validation rules, errors, and submission.
20. **`createFullscreen`** — Requests and monitors element or document fullscreen state (`isFullscreen()`, `toggle()`).
21. **`createGeolocation`** — Tracks real-time GPS coordinates, accuracy, speed, and heading.
22. **`createGlobalShortcut`** — Registers native system-wide OS global hotkeys via Tauri v2 plugin with web keyboard fallback (`register()`, `unregister()`, `isRegistered()`).
23. **`createHover`** — Tracks element mouse hover state with enter/exit delay configurations.
24. **`createIdle`** — Detects user inactivity after customizable timeout threshold (`isIdle()`).
25. **`createInfiniteScroll`** — Manages infinite scroll pagination and auto-fetching next page triggers.
26. **`createInputMask`** — Applies formatting masks (phone numbers, credit cards, dates) to text inputs.
27. **`createIntersectionObserver`** — Observes element visibility and viewport intersection ratios.
28. **`createKeybindings`** — Listens to keyboard shortcuts, key combinations, and Escape key presses.
29. **`createLockScroll`** — Locks body or scrollable container scrolling when overlays are active.
30. **`createLongPress`** — Detects long press / touch hold interactions with custom duration.
31. **`createMediaQuery`** — Tracks CSS media queries and responsive Tailwind breakpoints.
32. **`createMousePosition`** — Tracks global window and element-relative cursor coordinates.
33. **`createNetworkStatus`** — Tracks browser online/offline status and network connection type.
34. **`createOrientation`** — Monitors screen orientation (`portrait` / `landscape`) and rotation angle.
35. **`createPagination`** — Calculates pagination state, page ranges with ellipses, and jump actions.
36. **`createPermission`** — Queries and observes browser permission states (`granted`, `denied`, `prompt`).
37. **`createPrevious`** — Accesses previous value of a reactive signal accessor.
38. **`createResizeObserver`** — Observes element width, height, and content box bounding rects.
39. **`createScrollIntoView`** — Smoothly scrolls target element or ref into container viewport.
40. **`createScrollPosition`** — Tracks container scroll offset (X, Y), scroll direction, and boundaries.
41. **`createStorage`** — Reactive `createLocalStorage` and `createSessionStorage` with cross-tab sync.
42. **`createTauriWindow`** — Fine-grained reactive signals and actions for Tauri desktop windows (`isMaximized()`, `isMinimized()`, `isFullscreen()`, `isFocused()`, `minimize()`, `maximize()`, `toggleMaximize()`, `close()`, `startDragging()`).
43. **`createTimer`** — Provides interval timers, stopwatch counters, and formatted countdowns.
44. **`createTiptapEditor`** — Headless reactive TipTap rich text editor integration for SolidJS (`editor()`, `isActive()`, `toggleBold()`, `toggleItalic()`, `setHeading()`, etc.).
45. **`createUndoRedo`** — Manages undo/redo state history stacks and pointer state resets.
46. **`createWebNotification`** — Sends native browser desktop notifications and handles permission requests.
47. **`createWebSocket`** — WebSocket client connection manager with auto-reconnect and message parsing.
48. **`createWindowSize`** — Tracks window inner width and inner height reactively.
---
## 6. Desktop & Tauri v2 Suite Reference
Nikala UI provides a complete desktop-first UI system tailored for **Tauri v2** and **SolidJS**.
### Frameless Window Chrome & Tabs (`Titlebar` + `TitlebarTabs`)
```tsx
import {
Titlebar,
TitlebarControls,
TitlebarTabs,
} from "@/components/ui/titlebar";
import { createDocumentTabs } from "@/hooks/create-document-tabs";
import { FileCode, Terminal } from "lucide-solid";
export function DesktopEditorHeader() {
const tabs = createDocumentTabs({
initialTabs: [
{ id: "main.rs", title: "main.rs", icon: Terminal, isPinned: true },
{ id: "app.tsx", title: "App.tsx", icon: FileCode, isDirty: true },
],
enableKeybindings: true, // Enables Ctrl+W / Cmd+W to close active tab
});
const handleAddTab = () => {
const id = `doc-${tabs.count() + 1}.ts`;
tabs.addTab({ id, title: id, icon: FileCode });
};
return (
<Titlebar platform="macos" class="h-10 bg-card border-b">
<TitlebarControls platform="macos" class="mr-2" />
{/* 1-Liner Declarative Tabs with Mouse Wheel Scrolling & Anchored Add Button */}
<TitlebarTabs
manager={tabs}
variant="editor"
onAddTab={handleAddTab}
/>
</Titlebar>
);
}
```
### Tauri Auto-Updater Modal (`UpdaterModal` + `createAppUpdater`)
```tsx
import { createSignal } from "solid-js";
import { UpdaterModal } from "@/components/ui/updater-modal";
import { createAppUpdater } from "@/hook