@bloomneo/uikit 1.5.0

package/bin/templates/spa/docs/UIKIT_COMPOSITE_UI_SYSTEM.md

@@ -0,0 +1,649 @@
+# UIKit Composite UI System
+
+**Industry-standard design system built on ShadCN foundations, enhanced with rapid prototyping capabilities for enterprise-scale applications.**
+
+## 🏗️ Built on Industry Standards
+
+UIKit is strategically built on **ShadCN components** and **Tailwind CSS v4** - the proven foundation used by thousands of production applications. This isn't reinventing the wheel; it's enhancing what already works.
+
+**Why this foundation matters:**
+- **Industry adoption** - ShadCN is the de-facto standard for React component libraries
+- **Battle-tested patterns** - Proven in production across enterprises and startups
+- **Radix UI primitives** - Accessibility and keyboard navigation built-in
+- **Tailwind CSS integration** - The most adopted utility-first CSS framework
+- **Community ecosystem** - Extensive documentation, tutorials, and community support
+
+**UIKit's enhancement approach:**
+- **Maintains 100% ShadCN compatibility** - Use any ShadCN pattern or tutorial
+- **Adds semantic color system** - Automatic theme adaptation without code changes
+- **Provides production layouts** - Skip weeks of layout development
+- **Enables rapid prototyping** - From idea to interface in minutes
+
+## 🎯 Why Consistent Design Matters
+
+The composite system ensures **design consistency** across your entire application:
+
+**🧩 Components (37 Standard)** → **📐 Section Components (3 Bridging)** → **🏗️ Layouts (5 Production-Ready)**
+
+**Consistency benefits:**
+- **Predictable behavior** - Users know how to interact with your interface
+- **Faster development** - Developers use familiar patterns everywhere
+- **Easier maintenance** - Changes propagate systematically across the system
+- **Professional appearance** - Cohesive design that builds user trust
+- **Team productivity** - No more "how should this look?" debates
+
+**Rapid prototyping advantage:**
+- **Start with components** - Build individual features quickly
+- **Compose with sections** - Combine into reusable interface blocks
+- **Scale to layouts** - Deploy complete application structures
+- **Iterate fast** - Modify any tier without breaking others
+
+---
+
+## 🧩 Tier 1: Components (37 Total)
+
+### Component Categories
+
+| Category            | Count | Components                                                                | Usage                    |
+| ------------------- | ----- | ------------------------------------------------------------------------- | ------------------------ |
+| **Form & Input**    | 9     | Button, Input, Textarea, Label, Checkbox, RadioGroup, Switch, Slider, Select | User interactions       |
+| **Display & Layout** | 10    | Card, Badge, Avatar, Separator, Progress, Skeleton, Alert, Breadcrumb, Tabs, Accordion | Information presentation |
+| **Navigation & Menu** | 6     | DropdownMenu, Menubar, Pagination, Command, Collapsible, Toggle        | User navigation          |
+| **Overlay & Modal**  | 5     | Dialog, Sheet, Popover, HoverCard, Tooltip                              | Layered interactions     |
+| **Data & Table**     | 4     | Table, DataTable, Calendar, Toaster                                     | Data management          |
+| **Motion & Animation** | 3     | Motion, LoadingSpinner, Reveal, Hover                                  | Visual effects           |
+
+### Component Usage Patterns
+
+All UIKit components follow consistent prop patterns for predictable behavior:
+
+#### Button Component Example
+```jsx
+import { Button } from '@bloomneo/uikit/button';
+
+// Variant system - different visual styles
+<Button variant="default">Primary Action</Button>
+<Button variant="secondary">Secondary Action</Button>
+<Button variant="outline">Outline Style</Button>
+<Button variant="ghost">Subtle Action</Button>
+<Button variant="destructive">Delete Action</Button>
+
+// Size system - consistent sizing across components
+<Button size="sm">Small</Button>
+<Button size="md">Medium (default)</Button>
+<Button size="lg">Large</Button>
+
+// Common props available on most components
+<Button
+  variant="default"
+  size="md"
+  disabled={isLoading}
+  className="w-full"  // Extend with Tailwind classes
+  onClick={handleClick}
+>
+  Save Changes
+</Button>
+```
+
+#### Pattern Consistency
+```jsx
+// Same patterns work across all components
+<Input variant="default" size="md" placeholder="Enter text" />
+<Card variant="default" size="md">
+  <CardContent>Consistent sizing and styling</CardContent>
+</Card>
+<Badge variant="default" size="sm">Status</Badge>
+```
+
+### Import Patterns
+```jsx
+// ✅ Individual imports (recommended for tree-shaking)
+import { Button } from '@bloomneo/uikit/button';
+import { Card, CardContent, CardHeader } from '@bloomneo/uikit/card';
+import { ValidatedInput } from '@bloomneo/uikit/form';
+
+// ❌ Avoid barrel imports
+import { Button, Card } from '@bloomneo/uikit'; // Larger bundle size
+```
+
+### Complete Component Reference
+
+| Component | Prop | Possible Values |
+|-----------|------|-----------------|
+| **Form & Input (9)** | | |
+| **Button** | `variant` | `default\|secondary\|outline\|ghost\|destructive` |
+| | `size` | `sm\|md\|lg` |
+| | `disabled` | `boolean` |
+| **Input** | `type` | `text\|email\|password\|number\|search` |
+| | `variant` | `default` |
+| | `size` | `sm\|md\|lg` |
+| **Textarea** | `rows` | `number` |
+| | `variant` | `default` |
+| | `resize` | `none\|vertical\|horizontal\|both` |
+| **Label** | `htmlFor` | `string` |
+| **Checkbox** | `checked` | `boolean` |
+| | `variant` | `default` |
+| **RadioGroup** | `value` | `string` |
+| | `orientation` | `horizontal\|vertical` |
+| **Switch** | `checked` | `boolean` |
+| | `size` | `sm\|md\|lg` |
+| **Slider** | `value` | `number[]` |
+| | `min` | `number` |
+| | `max` | `number` |
+| | `step` | `number` |
+| **Select** | `value` | `string` |
+| | `size` | `sm\|md\|lg` |
+| **Display & Layout (10)** | | |
+| **Card** | `variant` | `default` |
+| | `size` | `sm\|md\|lg\|xl` |
+| **Badge** | `variant` | `default\|secondary\|destructive\|outline` |
+| | `size` | `sm\|md\|lg` |
+| **Avatar** | `size` | `sm\|md\|lg\|xl` |
+| | `src` | `string` |
+| | `fallback` | `string` |
+| **Separator** | `orientation` | `horizontal\|vertical` |
+| | `variant` | `default` |
+| **Progress** | `value` | `number` |
+| | `max` | `number` |
+| | `size` | `sm\|md\|lg` |
+| **Skeleton** | `variant` | `default\|circular\|text` |
+| | `animation` | `pulse\|wave\|none` |
+| **Alert** | `variant` | `default\|destructive\|warning\|success` |
+| | `size` | `sm\|md\|lg` |
+| **Breadcrumb** | `separator` | `string\|component` |
+| | `maxItems` | `number` |
+| **Tabs** | `value` | `string` |
+| | `orientation` | `horizontal\|vertical` |
+| **Accordion** | `type` | `single\|multiple` |
+| | `collapsible` | `boolean` |
+| **Navigation & Menu (6)** | | |
+| **DropdownMenu** | `open` | `boolean` |
+| | `modal` | `boolean` |
+| **Menubar** | `value` | `string` |
+| | `orientation` | `horizontal\|vertical` |
+| **Pagination** | `page` | `number` |
+| | `totalPages` | `number` |
+| | `showEdges` | `boolean` |
+| **Command** | `value` | `string` |
+| | `filter` | `function` |
+| **Collapsible** | `open` | `boolean` |
+| | `disabled` | `boolean` |
+| **Toggle** | `pressed` | `boolean` |
+| | `variant` | `default\|outline` |
+| | `size` | `sm\|md\|lg` |
+| **Overlay & Modal (5)** | | |
+| **Dialog** | `open` | `boolean` |
+| | `modal` | `boolean` |
+| **Sheet** | `open` | `boolean` |
+| | `side` | `top\|bottom\|left\|right` |
+| **Popover** | `open` | `boolean` |
+| | `side` | `top\|bottom\|left\|right` |
+| | `align` | `start\|center\|end` |
+| **HoverCard** | `openDelay` | `number` |
+| | `closeDelay` | `number` |
+| **Tooltip** | `side` | `top\|bottom\|left\|right` |
+| | `align` | `start\|center\|end` |
+| | `delayDuration` | `number` |
+| **Data & Table (4)** | | |
+| **Table** | `variant` | `default` |
+| | `size` | `sm\|md\|lg` |
+| **DataTable** | `data` | `array` |
+| | `columns` | `array` |
+| | `searchable` | `boolean` |
+| | `filterable` | `boolean` |
+| | `sortable` | `boolean` |
+| | `pagination` | `boolean` |
+| **Calendar** | `mode` | `single\|multiple\|range` |
+| | `selected` | `Date\|Date[]` |
+| | `numberOfMonths` | `number` |
+| **Toaster** | `position` | `top-left\|top-right\|bottom-left\|bottom-right` |
+| | `richColors` | `boolean` |
+| **Motion & Animation (3)** | | |
+| **Motion** | `preset` | `fadeIn\|slideInUp\|scaleIn\|slideInLeft\|slideInRight` |
+| | `duration` | `fast\|normal\|slow` |
+| | `delay` | `number` |
+| **LoadingSpinner** | `size` | `sm\|md\|lg\|xl` |
+| | `variant` | `default\|dots\|pulse\|ring` |
+| **Reveal** | `preset` | `fadeIn\|slideInUp\|slideInLeft\|slideInRight` |
+| | `threshold` | `number` |
+
+---
+
+## 📐 Tier 2: Section Components (3 Standalone)
+
+Section components are **standalone layout building blocks** that bridge individual components and complete page layouts. They provide reusable interface sections that can be used independently or combined to create custom layouts.
+
+**Why use section components:**
+- **Independent sections** - Use without full page layouts
+- **Flexible composition** - Mix and match with any layout
+- **Consistent styling** - Follow the same prop patterns as all UIKit components
+- **Rapid prototyping** - Quickly build custom interface sections
+
+| Component | Prop | Possible Values |
+|-----------|------|-----------------|
+| **Header** | `tone` | `clean\|subtle\|brand\|contrast` |
+| | `size` | `sm\|md\|lg\|xl\|full` |
+| | `position` | `sticky\|fixed\|relative` |
+| | `navigation` | `NavigationItem[]` |
+| | `logo` | `ReactNode` |
+| | `actions` | `ReactNode` |
+| **Footer** | `tone` | `clean\|subtle\|brand\|contrast` |
+| | `size` | `sm\|md\|lg\|xl\|full` |
+| | `position` | `sticky\|fixed\|relative` |
+| | `navigation` | `NavigationItem[]` |
+| | `copyright` | `string` |
+| **Container** | `tone` | `clean\|subtle\|brand\|contrast` |
+| | `size` | `sm\|md\|lg\|xl\|full` |
+| | `sidebar` | `left\|right\|none` |
+| | `navigation` | `NavigationItem[]` |
+| | `onNavigate` | `function` |
+
+### Section Component Examples
+
+#### Standalone Header
+```jsx
+import { Header, HeaderLogo, HeaderNav } from '@bloomneo/uikit/header';
+
+<Header tone="clean" size="xl" position="sticky">
+  <HeaderLogo>
+    <img src="/logo.png" alt="Logo" className="h-8 w-auto" />
+  </HeaderLogo>
+  <HeaderNav
+    navigation={navigation}
+    currentPath="/current"
+    onNavigate={handleNavigation}
+  />
+</Header>
+```
+
+#### Standalone Footer
+```jsx
+import { Footer } from '@bloomneo/uikit/footer';
+
+<Footer tone="contrast" size="xl" position="relative">
+  <div className="text-center py-4">
+    <p className="text-muted-foreground">© 2025 Company</p>
+  </div>
+</Footer>
+```
+
+#### Container with Sidebar
+```jsx
+import { Container } from '@bloomneo/uikit/container';
+
+<Container
+  tone="clean"
+  size="xl"
+  sidebar="left"
+  navigation={sidebarNav}
+  onNavigate={handleNavigation}
+>
+  <MainContent />
+</Container>
+```
+
+---
+
+## 🏗️ Tier 3: Layouts (5 Production-Ready)
+
+Layouts are **complete page structures** that provide instant application scaffolding. They include built-in responsive design, routing support, and production-ready patterns used by thousands of applications.
+
+**Why use layouts:**
+- **Instant scaffolding** - Complete page structure in one component
+- **Production-ready** - Battle-tested patterns from real applications
+- **Responsive design** - Mobile-first approach with breakpoint handling
+- **Routing integration** - Built-in navigation state management
+- **Consistent behavior** - Standardized patterns across your application
+
+### Layout Decision Tree
+
+```
+What are you building?
+├── Admin Dashboard/SaaS App → AdminLayout (compound pattern)
+├── Marketing Website → PageLayout (compound pattern)
+├── Authentication Pages → AuthLayout (single pattern)
+├── Error/Simple Pages → BlankLayout (single pattern)
+└── Browser Extensions → PopupLayout (single pattern)
+```
+
+### Layout Reference
+
+| Layout | Child Component | Prop | Possible Values |
+|--------|----------------|------|-----------------|
+| **AdminLayout** | | `scheme` | `sidebar\|compact` |
+| | | `tone` | `clean\|subtle\|brand\|contrast` |
+| | | `size` | `sm\|md\|lg\|xl\|full` |
+| | | `defaultSidebarOpen` | `boolean` |
+| | **AdminLayout.Header** | `title` | `string` |
+| | | `position` | `sticky\|fixed\|relative` |
+| | | `breadcrumbs` | `array` |
+| | | `actions` | `ReactNode` |
+| | **AdminLayout.Sidebar** | `navigation` | `NavigationItem[]` |
+| | | `currentPath` | `string` |
+| | | `onNavigate` | `function` |
+| | | `logo` | `ReactNode` |
+| | | `footer` | `ReactNode` |
+| | **AdminLayout.Content** | `className` | `string` |
+| **PageLayout** | | `scheme` | `base\|sidebar` |
+| | | `tone` | `clean\|subtle\|brand\|contrast` |
+| | | `size` | `sm\|md\|lg\|xl\|full` |
+| | **PageLayout.Header** | `navigation` | `NavigationItem[]` |
+| | | `currentPath` | `string` |
+| | | `onNavigate` | `function` |
+| | | `logo` | `ReactNode` |
+| | | `title` | `string` |
+| | | `actions` | `ReactNode` |
+| | **PageLayout.Content** | `title` | `string` |
+| | | `breadcrumbs` | `array` |
+| | | `sidebar` | `none\|left\|right` |
+| | | `sidebarContent` | `ReactNode` |
+| | **PageLayout.Footer** | `navigation` | `NavigationItem[]` |
+| | | `copyright` | `string` |
+| **AuthLayout** | | `scheme` | `simple\|card\|split\|hero` |
+| | | `tone` | `clean\|subtle\|brand\|contrast` |
+| | | `size` | `sm\|md\|lg\|xl\|full` |
+| | | `title` | `string` |
+| | | `subtitle` | `string` |
+| | | `logo` | `ReactNode` |
+| | | `imageUrl` | `string` |
+| **BlankLayout** | | `scheme` | `simple\|card` |
+| | | `tone` | `clean\|subtle\|brand\|contrast` |
+| | | `size` | `sm\|md\|lg\|xl\|full` |
+| **PopupLayout** | | `scheme` | `modal\|drawer\|floating` |
+| | | `tone` | `clean\|subtle\|brand\|contrast` |
+| | | `size` | `sm\|md\|lg\|xl\|full` |
+| | | `title` | `string` |
+| | | `showClose` | `boolean` |
+| | | `onClose` | `function` |
+
+### Layout Examples
+
+#### AdminLayout (Compound Pattern)
+```jsx
+import { AdminLayout } from '@bloomneo/uikit/admin';
+
+// Compound pattern: Use child components
+<AdminLayout scheme="sidebar" tone="subtle" size="lg">
+  <AdminLayout.Header
+    title="Dashboard"
+    position="sticky"
+    breadcrumbs={breadcrumbs}
+    actions={<Button>Export</Button>}
+  />
+  <AdminLayout.Sidebar
+    navigation={navigation}
+    currentPath="/admin"
+    onNavigate={handleNavigation}
+    logo={<Logo />}
+  />
+  <AdminLayout.Content>
+    <DataTable data={users} columns={columns} />
+  </AdminLayout.Content>
+</AdminLayout>
+```
+
+#### PageLayout (Compound Pattern)
+```jsx
+import { PageLayout } from '@bloomneo/uikit/page';
+
+// Compound pattern: Use child components
+<PageLayout scheme="base" tone="clean" size="xl">
+  <PageLayout.Header
+    logo="MyApp"
+    navigation={navigation}
+    currentPath="/"
+    onNavigate={handleNavigation}
+  />
+  <PageLayout.Content>
+    <h1 className="text-foreground">Welcome</h1>
+    <p className="text-muted-foreground">Build amazing apps</p>
+  </PageLayout.Content>
+  <PageLayout.Footer copyright="© 2025 MyApp" />
+</PageLayout>
+```
+
+#### AuthLayout (Single Pattern)
+```jsx
+import { AuthLayout } from '@bloomneo/uikit/auth';
+
+// Single pattern: Direct children
+<AuthLayout scheme="card" tone="clean" size="md">
+  <ValidatedInput
+    type="email"
+    required
+    label="Email"
+    placeholder="Enter your email"
+  />
+  <ValidatedInput
+    type="password"
+    required
+    label="Password"
+    showPasswordToggle
+  />
+  <Button variant="default" size="md" className="w-full">
+    Sign In
+  </Button>
+</AuthLayout>
+```
+
+---
+
+## 🎨 Common Prop Patterns
+
+UIKit follows consistent naming conventions across similar component types:
+
+### Layout Props (AdminLayout, PageLayout, etc.)
+```jsx
+<Layout
+  scheme="sidebar"     // Layout structure
+  tone="subtle"        // Visual emphasis
+  size="lg"           // Layout dimensions
+/>
+```
+
+### Component Props (Button, Input, Card, etc.)
+```jsx
+<Component
+  variant="default"    // Visual style (where applicable)
+  size="md"           // Component sizing (where applicable)
+/>
+```
+
+### Size System
+| Size   | Layout Width | Sidebar Width | Usage             |
+| ------ | ------------ | ------------- | ----------------- |
+| `sm`   | 672px        | 192px         | Compact interfaces |
+| `md`   | 896px        | 224px         | Standard content  |
+| `lg`   | 1152px       | 256px         | Wide content      |
+| `xl`   | 1280px       | 288px         | Full-width layouts |
+| `full` | 100%         | 320px         | Edge-to-edge      |
+
+### Tone System
+| Tone       | Background      | Usage                    |
+| ---------- | --------------- | ------------------------ |
+| `clean`    | Pure white/light | Minimal, marketing pages |
+| `subtle`   | Light gray      | Professional, admin panels |
+| `brand`    | Primary color   | Headers, CTAs, emphasis  |
+| `contrast` | Dark/bold       | Footers, high contrast   |
+
+---
+
+## 🧭 Navigation System
+
+### Navigation Structure
+```typescript
+interface NavigationItem {
+  key: string;              // REQUIRED: Unique identifier
+  label: string;            // REQUIRED: Display text
+  href?: string;            // For page navigation
+  onClick?: () => void;     // For actions/functions
+  icon?: ComponentType;     // Lucide React icon
+  badge?: string;          // Notification badge
+  isActive?: boolean;      // Current page indicator
+  items?: NavigationItem[]; // Submenu (max 2 levels)
+}
+```
+
+### Navigation Examples
+```jsx
+const navigation = [
+  {
+    key: 'dashboard',
+    label: 'Dashboard',
+    href: '/admin',
+    icon: LayoutDashboard,
+    isActive: true,
+  },
+  {
+    key: 'users',
+    label: 'Users',
+    icon: Users,
+    badge: '12',
+    items: [
+      { key: 'list', label: 'All Users', href: '/admin/users' },
+      { key: 'new', label: 'Add User', href: '/admin/users/new' },
+    ],
+  },
+  {
+    key: 'logout',
+    label: 'Logout',
+    icon: LogOut,
+    onClick: () => handleLogout(),
+  },
+];
+```
+
+### Navigation Handlers
+```jsx
+const handleNavigation = (href, item) => {
+  if (item.onClick) {
+    item.onClick(); // Execute custom function
+  } else if (href) {
+    navigate(href); // React Router
+    // router.push(href); // Next.js
+    // window.location.href = href; // Simple navigation
+  }
+};
+```
+
+---
+
+## 🚀 Quick Start Patterns
+
+### 1. Simple Page with Components
+```jsx
+import { Card, CardContent, CardHeader, CardTitle } from '@bloomneo/uikit/card';
+import { Button } from '@bloomneo/uikit/button';
+
+function SimplePage() {
+  return (
+    <div className="p-6 bg-background">
+      <Card className="max-w-md">
+        <CardHeader>
+          <CardTitle>Welcome</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <p className="text-muted-foreground">Get started with UIKit</p>
+          <Button className="mt-4">Continue</Button>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+
+### 2. Complete Admin Interface
+```jsx
+import { AdminLayout } from '@bloomneo/uikit/admin';
+import { DataTable } from '@bloomneo/uikit/data-table';
+
+function AdminDashboard() {
+  return (
+    <AdminLayout scheme="sidebar" tone="subtle" size="lg">
+      <AdminLayout.Header title="Users" />
+      <AdminLayout.Sidebar navigation={nav} />
+      <AdminLayout.Content>
+        <DataTable
+          data={users}
+          columns={columns}
+          searchable
+          pagination
+        />
+      </AdminLayout.Content>
+    </AdminLayout>
+  );
+}
+```
+
+### 3. Marketing Site
+```jsx
+import { PageLayout } from '@bloomneo/uikit/page';
+
+function MarketingSite() {
+  return (
+    <PageLayout scheme="base" tone="clean" size="xl">
+      <PageLayout.Header logo="MyApp" navigation={nav} />
+      <PageLayout.Content>
+        <div className="text-center py-20">
+          <h1 className="text-4xl font-bold text-foreground">
+            Build Better Apps
+          </h1>
+          <p className="text-muted-foreground mt-4">
+            With UIKit's composite system
+          </p>
+        </div>
+      </PageLayout.Content>
+      <PageLayout.Footer />
+    </PageLayout>
+  );
+}
+```
+
+---
+
+## 💡 Best Practices
+
+### ✅ Do This
+- **Use semantic colors** for theme compatibility
+- **Individual imports** for better tree-shaking
+- **Compound patterns** for AdminLayout and PageLayout
+- **Single patterns** for AuthLayout, BlankLayout, PopupLayout
+- **Consistent props** (scheme, tone, size) across components
+
+### ❌ Avoid This
+- **Hardcoded colors** that break in themes
+- **Barrel imports** that increase bundle size
+- **Wrong layout patterns** (single vs compound)
+- **Inconsistent navigation** structure
+- **Missing semantic classes**
+
+### Component Selection Guide
+```jsx
+// Forms with validation → Use Enhanced Components
+<ValidatedInput type="email" required />
+
+// Simple forms → Use Basic Components
+<Input placeholder="Search..." />
+
+// Complex data → Use DataTable
+<DataTable data={users} searchable filterable />
+
+// Simple data → Use Table
+<Table>
+  <TableBody>
+    <TableRow>...</TableRow>
+  </TableBody>
+</Table>
+```
+
+---
+
+## 📚 Related Guides
+
+- **[UIKit Theme Guide](./UIKIT_THEME_GUIDE.md)** - Custom theming and colors
+- **[UIKit LLM Guide](./UIKIT_LLM_GUIDE.md)** - Complete implementation reference
+- **[GitHub Repository](https://github.com/bloomneo/uikit)** - Source code and examples
+
+---
+
+**Build beautiful, consistent interfaces with UIKit's Composite UI System** ✨