@bloomneo/uikit 1.5.0

package/bin/templates/single/docs/QUICKSTART_SINGLE.md

@@ -0,0 +1,259 @@
+# Quick Start: Single Template
+
+**Simple component showcase with no routing - perfect for learning UIKit components and exploring themes.**
+
+## 🎯 What is Single Template?
+
+The Single template creates a component showcase on one page. No routing, no complex layouts - just a clean demonstration of UIKit components and all 5 themes. Perfect for learning, prototyping, and component exploration.
+
+**Perfect for:**
+- Learning UIKit components
+- Component demos and showcases
+- Quick prototyping and experimentation
+- Testing themes and design systems
+- Simple component libraries
+
+## ⚡ 30-Second Setup
+
+### Step 1: Install UIKit CLI Globally
+```bash
+npm install -g @bloomneo/uikit
+```
+
+### Step 2: Create Single Project
+```bash
+uikit create my-single-app
+cd my-single-app && npm run dev
+```
+
+### Step 3: Project Structure
+```
+src/
+├── App.tsx                 # Component showcase with theme switcher
+├── main.tsx               # Entry point with theme provider
+└── index.css              # Global styles with Tailwind + UIKit
+```
+
+## 🎨 How Single Template Works
+
+### App.tsx - Component Showcase
+**Why:** All components demonstrated in one file for easy exploration
+**When:** Learning components, testing themes, building demos
+**How:** Single page with theme switcher and component examples
+
+```jsx
+const UIKitShowcase = () => {
+  const { theme, mode, setTheme, toggleMode, availableThemes } = useTheme();
+
+  return (
+    <div className="min-h-screen bg-background text-foreground">
+      {/* Header with theme controls */}
+      <header className="border-b border-border p-6">
+        <div className="flex items-center justify-between">
+          <div className="flex items-center gap-3">
+            <div className="w-8 h-8 bg-primary rounded">UI</div>
+            <h1 className="voila-brand-logo text-xl font-bold">@bloomneo/uikit</h1>
+          </div>
+
+          <div className="flex items-center gap-3">
+            <select value={theme} onChange={(e) => setTheme(e.target.value)}>
+              {availableThemes.map(id => (
+                <option key={id} value={id}>{id}</option>
+              ))}
+            </select>
+            <Button onClick={toggleMode} variant="outline" size="sm">
+              {mode === 'dark' ? '☀️' : '🌙'}
+            </Button>
+          </div>
+        </div>
+      </header>
+
+      {/* Component showcase sections */}
+      <main className="max-w-6xl mx-auto p-6 space-y-8">
+        {/* Your component examples */}
+      </main>
+    </div>
+  );
+};
+```
+
+### main.tsx - Theme Provider Setup
+**Why:** Provides theme context to entire app
+**When:** Always required for UIKit components
+**How:** Wraps App with ThemeProvider
+
+```jsx
+import { ThemeProvider } from '@bloomneo/uikit/theme-provider';
+import App from './App';
+import './index.css';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <ThemeProvider theme="base" mode="light" forceConfig={true}>
+      <App />
+    </ThemeProvider>
+  </React.StrictMode>
+);
+```
+
+## 📦 Component Examples
+
+### Button Showcase
+**Why:** Demonstrate all button variants and sizes
+**When:** Learning button component API
+**How:** Grid layout with different configurations
+
+```jsx
+<Card>
+  <CardHeader>
+    <CardTitle>Buttons</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <div className="flex flex-wrap gap-3">
+      <Button size="lg">Primary</Button>
+      <Button variant="secondary" size="lg">Secondary</Button>
+      <Button variant="outline" size="lg">Outline</Button>
+      <Button variant="ghost" size="lg">Ghost</Button>
+      <Button variant="destructive" size="lg">Delete</Button>
+    </div>
+  </CardContent>
+</Card>
+```
+
+### Card Examples
+**Why:** Show different card layouts and styles
+**When:** Understanding card component patterns
+**How:** Grid of card variations
+
+```jsx
+<div className="grid grid-cols-1 md:grid-cols-3 gap-4">
+  <Card>
+    <CardHeader>
+      <CardTitle>Feature Card</CardTitle>
+      <CardDescription>Standard card component</CardDescription>
+    </CardHeader>
+    <CardContent>
+      <p className="text-sm text-muted-foreground">Perfect for content areas</p>
+    </CardContent>
+  </Card>
+
+  <Card>
+    <CardHeader>
+      <CardTitle>Interactive</CardTitle>
+    </CardHeader>
+    <CardContent>
+      <Button className="w-full">Action</Button>
+    </CardContent>
+  </Card>
+
+  <div className="bg-primary text-primary-foreground p-6 rounded-lg">
+    <h4 className="font-semibold mb-2">Custom Card</h4>
+    <p className="text-sm opacity-90">With custom styling</p>
+  </div>
+</div>
+```
+
+### Form Elements
+**Why:** Demonstrate input components and styling
+**When:** Learning form component patterns
+**How:** Grid layout with different input types
+
+```jsx
+<Card>
+  <CardHeader>
+    <CardTitle>Form Elements</CardTitle>
+  </CardHeader>
+  <CardContent className="space-y-4">
+    <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+      <input
+        type="text"
+        placeholder="Text input"
+        className="p-3 bg-background border border-input rounded-lg focus:outline-none focus:ring-2 focus:ring-ring"
+      />
+      <select className="p-3 bg-background border border-input rounded-lg">
+        <option>Select option</option>
+        <option>Option 1</option>
+      </select>
+    </div>
+    <textarea
+      placeholder="Textarea"
+      rows={3}
+      className="w-full p-3 bg-background border border-input rounded-lg resize-none"
+    />
+  </CardContent>
+</Card>
+```
+
+## 🎯 When to Use Single Template
+
+**Perfect for:**
+- Learning UIKit components
+- Creating component demonstrations
+- Quick prototyping without routing
+- Testing themes and color systems
+- Building simple component showcases
+- Teaching UIKit to others
+
+**Key Benefits:**
+- Zero configuration required
+- All components in one place
+- Built-in theme switcher
+- Perfect for experimentation
+- No routing complexity
+
+**Not ideal for:**
+- Multi-page applications (use SPA template)
+- Complex business applications (use Multi template)
+- Large scalable apps (use FBCA template)
+
+## 🔧 Customization
+
+### Adding New Components
+**Why:** Expand your component showcase
+**When:** Want to test more UIKit components
+**How:** Add new sections to App.tsx
+
+```jsx
+// Add to your component showcase
+<Card>
+  <CardHeader>
+    <CardTitle>Your New Component</CardTitle>
+  </CardHeader>
+  <CardContent>
+    {/* Your component examples */}
+  </CardContent>
+</Card>
+```
+
+### Theme Testing
+**Why:** See how components look in different themes
+**When:** Designing with multiple theme options
+**How:** Use the built-in theme switcher
+
+```jsx
+// Theme descriptions for each theme
+const themeDescriptions = {
+  base: 'Clean default configuration',
+  elegant: 'Fresh sky blue theme',
+  metro: 'Dark teal with yellow accents',
+  studio: 'Sophisticated neutrals with gold',
+  vivid: 'Premium cursive typography'
+};
+```
+
+### Custom Styling
+**Why:** Test custom component styling
+**When:** Need to override default styles
+**How:** Use semantic color classes
+
+```jsx
+// Always use semantic classes for theme compatibility
+<div className="bg-primary text-primary-foreground p-4 rounded-lg">
+  <h3 className="font-bold">Custom Component</h3>
+  <p className="text-primary-foreground/80">With theme-aware colors</p>
+</div>
+```
+
+---
+
+**Built with @bloomneo/uikit** ✨