VoilaJSX UIKit 🎨

AI‑ready React component toolkit for rapid frontend development, powered by Tailwind CSS v4 and ShadCN.

Create visually stunning applications in seconds with 37 components, 6 layouts, and 5 themes — all zero‑configuration and minimal complexity. Build instantly, customize effortlessly, and deploy for web, desktop, and mobile in seconds.

Why Choose @voilajsx/uikit?

🚀 For Rapid Development

• 30-second setup: From npm install to running app with routing, themes, and layouts
• 37 ready-to-use components: Skip building basic UI - focus on your unique features
• 6 production layouts: Admin dashboards, auth flows, marketing pages, mobile apps - all pre-built

🎨 For Design Consistency

• 5 professional themes: Switch from minimal to luxury instantly - no design skills needed
• OKLCH color science: Perfect accessibility and contrast ratios automatically
• Dark mode included: Every theme works in light and dark mode out of the box

⚡ For Developer Experience

• AI-optimized: Generate consistent code with LLMs - predictable patterns, fewer errors
• TypeScript-first: Full type safety with intelligent autocomplete
• Zero configuration: Works immediately, customize only what you need

🏢 For Team Productivity

• Standardized components: No more "how should this button look?" debates
• Feature-based architecture: Scale to enterprise with FBCA project structure
• Instant deployment: uikit deploy --github for immediate production hosting

🔧 For Maintainability

• Semantic colors: Themes switch automatically - no hardcoded styles to break
• Convention over configuration: Predictable file structure, minimal decisions
• Future-proof: Built on Tailwind CSS v4 and Radix UI - modern foundation

Quick Start

Two Ways to Use UIKit:

📦 As a Library - Install UIKit components into your existing React projects (Next.js, Vite, CRA, NestJS with React frontend, etc.):

npm install @voilajsx/uikit

Import components directly: import { Button } from '@voilajsx/uikit/button' and import { Card } from '@voilajsx/uikit/card'

🚀 Complete Project Setup - Use UIKit CLI to scaffold entire applications with routing, layouts, and themes pre-configured:

# Step 1: Install UIKit CLI globally
npm install -g @voilajsx/uikit

# Check if you have the latest version
npm list -g @voilajsx/uikit

# Step 2: Create your app
uikit create myapp --multi --theme elegant
cd myapp && npm run dev

Done. Your app is running with routing, layouts, and the elegant theme.

Framework Architecture

@voilajsx/uikit is built on ShadCN components and Tailwind CSS v4 with three key additions:

1. Composite UI System

Build complete interfaces with our three-tier component system - from individual form controls to full page layouts. Mix and match components, sections, and layouts to create any interface quickly without starting from scratch.

📖 Learn more: Composite UI System Guide

Components (37 Total)

| Category | Components | Description | | ---------------------- | -------------------------------------------------------------------------------------- | ----------------------------- | | Form & Input | Button, Input, Textarea, Label, Checkbox, RadioGroup, Switch, Slider, Select | Form controls with validation | | Display & Layout | Card, Badge, Avatar, Separator, Progress, Skeleton, Alert, Breadcrumb, Tabs, Accordion | Information presentation | | Navigation & Menu | DropdownMenu, Menubar, Pagination, Command, Collapsible, Toggle | User navigation | | Overlay & Modal | Dialog, Sheet, Popover, HoverCard, Tooltip | User interactions | | Data & Table | Table, DataTable, Calendar, Toaster | Data management | | Motion & Animation | Motion, LoadingSpinner, Reveal, Hover | Visual effects |

Section Components (5 Standalone)

| Component | Purpose | Usage | Props | | ------------- | -------------------------- | --------------------------- | -------------------- | | Header | Standalone header sections | Independent navigation bars | tone, size, position | | Footer | Standalone footer sections | Independent footer content | tone, size, position | | Container | Content with sidebar | Flexible content containers | tone, size, sidebar | | SafeArea | Mobile safe area wrapper | iOS notch/Android insets | edges, tone | | TabBar | Mobile bottom navigation | Tab-based navigation | tabs, tone, variant |

Layouts (6 Production-Ready)

| Layout | Use Case | Components | Routing | | ---------------- | ---------------------- | -------------------------------- | ------------------ | | AdminLayout | Dashboards, SaaS apps | Sidebar, Header, Content, Footer | Built-in nav state | | PageLayout | Marketing sites | Header, Content, Footer | Static pages | | AuthLayout | Login/signup flows | Centered forms, hero images | Auth routing | | MobileLayout | Mobile apps (Capacitor)| Header, Content, TabBar | Tab/Stack nav | | PopupLayout | Browser extensions | Compact, focused content | Extension routing | | BlankLayout | Custom pages | Clean slate | Manual routing |

2. Advanced Theming System

Switch between 5 professional themes instantly or generate custom themes with perfect accessibility. Built on OKLCH color science with automatic light/dark mode support and semantic color variables that work across all components.

📖 Learn more: Theme System Guide

Note: Instead of hardcoded colors like bg-white or text-black, use semantic color classes like bg-background, text-foreground, border-border. These automatically adapt to your selected theme and work perfectly in both light and dark modes.

5 Professional Themes

| Theme | Style | Font Family | Best For | | ----------- | -------------------- | ---------------- | --------------------- | | base | Clean metallic black | System UI | Minimalist apps | | elegant | Professional blue | Montserrat | Business applications | | metro | Modern green | Clean typography | Admin dashboards | | studio | Bold black/orange | Artistic fonts | Creative portfolios | | vivid | Luxury purple/orange | Serif fonts | Premium products |

Custom Theme Generation

# Generate custom theme automatically
uikit generate theme <name>

# Bundle themes to CSS
uikit bundle

What Happens Automatically:

1. Creates theme preset with generic values for 29 semantic colors (light + dark modes)
2. Compiles globals.css with optimized CSS variables
3. Updates main.tsx to use your new theme instantly
4. Theme visible immediately - ready to customize for your brand needs

Development Workflow:

• Customize preset: Modify the generic values in src/themes/presets/theme-<name>.js to match your brand
• Rebundle: Run uikit bundle to regenerate CSS
• See changes instantly: Theme updates appear immediately in your app

Best Practices:

• Avoid custom CSS files - work within the preset system for consistency
• No separate stylesheets - keeps theme coherence undisturbed
• Easy maintenance - all theme changes in one centralized file

3. Project Scaffolding

Generate complete project structures with pre-configured routing, layouts, and development workflows. Choose from 4 templates optimized for different application types - from simple showcases to enterprise-scale feature-based architectures.

📖 For detailed setup guides: Quick-Start Documentation

UIKit CLI Templates

| Template | Command | Structure | Routing | Best For | | ---------- | -------------------------- | ---------------- | ---------------------- | --------------------------- | | Single | uikit create app | Basic showcase | None | Component demos, learning | | SPA | uikit create app --spa | Single-page app | React Router | Marketing sites, portfolios | | Multi | uikit create app --multi | Multi-layout app | React Router + layouts | Business apps, SaaS | | FBCA | uikit create app --fbca | Feature-based | Auto-discovery routing | Enterprise, large apps |

When to Use Each Template

Single - Very basic template for building from scratch with just one page. Use when you want to start minimal and build up manually.

SPA - Single page code that visually reflects multiple pages. Use when you want the simplicity of one page but with navigation between views.

Multi - True page isolation with different layouts and basic router included. Use when your requirements need actual separate pages for better organization.

FBCA - Comprehensive large-scale applications with feature segregation and auto-discovery page router (Next.js style file-based routing). Use when your application is enterprise-grade with features like auth (login/register), user management, etc. organized in separate folders.

UIKit CLI Commands

📖 Complete CLI reference: CLI Commands Guide

# Project Creation
uikit create myapp                    # Single template (component showcase)
uikit create myapp --spa              # SPA with React Router
uikit create myapp --multi            # Multi-layout application
uikit create myapp --fbca             # Feature-based architecture

# Code Generation (for FBCA projects)
uikit generate page dashboard         # Generate new page component
uikit generate component button       # Generate reusable component
uikit generate hook useAuth           # Generate custom React hook
uikit generate feature blog           # Generate complete feature (page + component + hook)

# Theme Management
uikit generate theme brand            # Generate custom theme
uikit bundle                          # Process themes to CSS
uikit bundle --watch                  # Watch mode for development

# Development & Deployment
uikit serve                           # Start development server
uikit build                           # Production build
uikit deploy                          # Static site deployment
uikit deploy --github                 # Deploy to GitHub Pages

Example Codes

📖 AI-powered development: LLM Usage Guide

Note: As mentioned above, UIKit is built on ShadCN components but with our own import paths. Instead of @/components/ui/button, use @voilajsx/uikit/button. The semantic color classes like bg-background, text-foreground, border-border etc. work exactly the same and automatically adapt to your selected theme.

Important: Not all components have variant and size props. Use individual imports and check component documentation for available props. For layouts, PageLayout uses scheme="default|sidebar" (not "base").

UI Component Examples

Card Component

import { Card, CardHeader, CardTitle, CardContent } from '@voilajsx/uikit/card';

<Card>
  <CardHeader>
    <CardTitle>Product Title</CardTitle>
  </CardHeader>
  <CardContent>
    <p>Product description here</p>
  </CardContent>
</Card>;

Alert Component

import { Alert, AlertTitle, AlertDescription } from '@voilajsx/uikit/alert';

<Alert variant="default">
  <AlertTitle>Success!</AlertTitle>
  <AlertDescription>Your action was completed successfully.</AlertDescription>
</Alert>;

Form Component

import { Button } from '@voilajsx/uikit/button';
import { Input } from '@voilajsx/uikit/input';
import { Label } from '@voilajsx/uikit/label';

<div className="space-y-4">
  <div>
    <Label>Email</Label>
    <Input placeholder="Enter email" />
  </div>
  <Button variant="default" size="default">
    Submit
  </Button>
</div>;

Layout Examples

// Admin Dashboard
<AdminLayout scheme="sidebar" tone="subtle">
  <AdminLayout.Header title="Dashboard" />
  <AdminLayout.Sidebar navigation={nav} />
  <AdminLayout.Content>
    <h1 className="text-foreground">Dashboard Content</h1>
  </AdminLayout.Content>
</AdminLayout>

// Marketing Page
<PageLayout scheme="default" tone="clean">
  <PageLayout.Header logo="MyApp" navigation={nav} />
  <PageLayout.Content>
    <h1 className="text-foreground">Welcome</h1>
  </PageLayout.Content>
  <PageLayout.Footer />
</PageLayout>

// Auth Page
<AuthLayout scheme="card" tone="clean">
  <h1 className="text-foreground">Login Form</h1>
</AuthLayout>

Theme Usage

import { ThemeProvider, useTheme } from '@voilajsx/uikit/theme-provider';
import { Button } from '@voilajsx/uikit/button';
import '@voilajsx/uikit/styles';

// Setup (in main.tsx)
<ThemeProvider theme="base" mode="light">
  <App />
</ThemeProvider>

// Theme Switcher
const { setTheme } = useTheme();
<Button variant="outline" size="default" onClick={() => setTheme('elegant')}>
  Switch Theme
</Button>

// Semantic Colors (still work with variants)
<div className="bg-background text-foreground border-border">
  <h1 className="text-primary">Heading</h1>
  <p className="text-muted-foreground">Description</p>
</div>

Resources

📚 Documentation

• Quick-Start Guides - Template-specific setup instructions
• Composite UI System - Component architecture deep dive
• Theme System - Advanced theming and customization
• CLI Commands - Complete command reference
• LLM Usage Guide - AI-powered development patterns

📄 License

MIT © VoilaJSX - See LICENSE for details.

🔖 Tags

react typescript uikit ai-ready shadcn tailwind themes components layouts zero-config production-ready agentic-ai llm-optimized rapid-development design-system developer-experience