start-vibing-stacks 1.9.1 → 2.0.0

package/dist/ui.js

@@ -2,7 +2,7 @@
  * Start Vibing Stacks — Terminal UI
  */
 import chalk from 'chalk';
-const VERSION = '1.9.1';
+const VERSION = '2.0.0';
 const gradient = (text) => {
     const colors = [chalk.hex('#FF6B6B'), chalk.hex('#FF8E53'), chalk.hex('#FFBD2E'), chalk.hex('#48BB78'), chalk.hex('#4299E1'), chalk.hex('#9F7AEA')];
     return text.split('').map((c, i) => colors[i % colors.length](c)).join('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "1.9.1",
+  "version": "2.0.0",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/frontend/react/skills/preline-ui/SKILL.md

@@ -0,0 +1,273 @@
+# Preline UI — Component & Theme System for TailwindCSS 4
+
+**ALWAYS invoke when using Preline components, creating themes, or customizing design tokens.**
+
+## What is Preline
+
+Preline is a **semantic token-based design system** built on TailwindCSS. It provides:
+- 220+ CSS tokens for full UI consistency
+- Pre-built components (navbar, sidebar, card, dropdown, overlay, etc.)
+- Theme generator for custom color schemes
+- Light + dark mode via `data-theme` + `.dark`
+
+## Installation (Laravel + Inertia)
+
+```bash
+npm install preline
+```
+
+```js
+// vite.config.js
+export default defineConfig({
+  plugins: [
+    laravel({ input: ['resources/css/app.css', 'resources/js/app.tsx'] }),
+  ],
+});
+```
+
+```css
+/* resources/css/app.css */
+@import "tailwindcss";
+@import "preline/themes/theme.css";
+```
+
+```tsx
+// resources/js/app.tsx — init Preline after Inertia navigation
+import { router } from '@inertiajs/react';
+
+router.on('navigate', () => {
+  // Re-init Preline components after SPA navigation
+  setTimeout(() => {
+    import('preline/preline').then(({ HSStaticMethods }) => {
+      HSStaticMethods.autoInit();
+    });
+  }, 100);
+});
+```
+
+## Token Architecture
+
+```
+Layer 1 — Tailwind primitives:    var(--color-blue-600)
+Layer 2 — Preline semantic:       --primary: var(--color-blue-600)
+Layer 3 — Component tokens:       --navbar-nav-hover: var(--color-gray-100)
+Layer 4 — Usage in HTML:          className="bg-primary text-primary-foreground"
+```
+
+### Core Token Groups
+
+| Group | Example Tokens | Purpose |
+|---|---|---|
+| **Background** | `--background`, `--background-1`, `--background-2` | App surfaces |
+| **Foreground** | `--foreground`, `--foreground-inverse` | Text colors |
+| **Primary** | `--primary`, `--primary-hover`, `--primary-foreground`, `--primary-50`→`950` | Brand/action color |
+| **Secondary** | `--secondary`, `--secondary-hover`, `--secondary-foreground` | Secondary emphasis |
+| **Muted** | `--muted`, `--muted-foreground`, `--muted-foreground-1`, `--muted-foreground-2` | Subdued elements |
+| **Destructive** | `--destructive`, `--destructive-hover`, `--destructive-foreground` | Danger actions |
+| **Border** | `--border`, `--border-line-1`→`8` | Border scale (light→dark) |
+| **Surface** | `--surface`, `--surface-1`→`5`, `--surface-foreground` | Elevated layers |
+| **Layer** | `--layer`, `--layer-hover`, `--layer-foreground` | Stacked elements |
+
+### Component Token Groups
+
+| Component | Tokens | Notes |
+|---|---|---|
+| **Navbar** | `--navbar`, `--navbar-line`, `--navbar-nav-*` | 3 variants (base, `-1`, `-2`) |
+| **Sidebar** | `--sidebar`, `--sidebar-line`, `--sidebar-nav-*` | 3 variants (base, `-1`, `-2`) |
+| **Card** | `--card`, `--card-line`, `--card-divider`, `--card-header`, `--card-footer` | |
+| **Dropdown** | `--dropdown`, `--dropdown-item-*` | hover, focus, active states |
+| **Select** | `--select`, `--select-item-*` | Same state pattern |
+| **Overlay** | `--overlay`, `--overlay-line`, `--overlay-header`, `--overlay-footer` | Modals |
+| **Tooltip** | `--tooltip`, `--tooltip-foreground`, `--tooltip-line` | |
+| **Popover** | `--popover`, `--popover-line` | |
+| **Scrollbar** | `--scrollbar-track`, `--scrollbar-thumb` | + inverse variants |
+
+## Creating Custom Themes
+
+### Theme File Structure (MUST follow order)
+
+```css
+/* 1. Import base theme */
+@import "./theme.css";
+
+/* 2. Theme scoping block — custom palettes ONLY */
+@theme theme-brand inline {
+  --color-brand-50: oklch(98% 0.003 250);
+  --color-brand-100: oklch(95% 0.01 250);
+  --color-brand-200: oklch(88% 0.03 250);
+  --color-brand-300: oklch(78% 0.06 250);
+  --color-brand-400: oklch(68% 0.10 250);
+  --color-brand-500: oklch(58% 0.14 250);
+  --color-brand-600: oklch(50% 0.15 250);
+  --color-brand-700: oklch(42% 0.13 250);
+  --color-brand-800: oklch(35% 0.10 250);
+  --color-brand-900: oklch(28% 0.08 250);
+  --color-brand-950: oklch(20% 0.05 250);
+}
+
+/* 3. Light mode — semantic token overrides */
+:root[data-theme="theme-brand"],
+[data-theme="theme-brand"] {
+  --background: var(--color-white);
+  --foreground: var(--color-gray-800);
+
+  --primary: var(--color-brand-600);
+  --primary-foreground: var(--color-white);
+  --primary-hover: var(--color-brand-700);
+  --primary-focus: var(--color-brand-700);
+  --primary-active: var(--color-brand-700);
+
+  /* ... all 220+ tokens as needed */
+}
+
+/* 4. Dark mode */
+[data-theme="theme-brand"].dark {
+  --background: var(--color-neutral-800);
+  --foreground: var(--color-neutral-200);
+
+  --primary: var(--color-brand-500);
+  --primary-foreground: var(--color-white);
+  --primary-hover: var(--color-brand-600);
+
+  /* ... dark overrides */
+}
+```
+
+### Activation
+
+```html
+<html data-theme="theme-brand">
+<!-- Or with dark mode: -->
+<html data-theme="theme-brand" class="dark">
+```
+
+```tsx
+// React theme switcher
+function ThemeToggle() {
+  const [dark, setDark] = useState(false);
+  return (
+    <button onClick={() => {
+      document.documentElement.classList.toggle('dark');
+      setDark(!dark);
+    }}>
+      {dark ? '☀️' : '🌙'}
+    </button>
+  );
+}
+```
+
+## Using Components with React (Inertia)
+
+### Navbar
+
+```tsx
+<nav className="bg-navbar border-b border-navbar-line">
+  <div className="max-w-7xl mx-auto px-4 flex items-center justify-between h-16">
+    <Link href="/" className="text-foreground font-bold text-lg">Brand</Link>
+    <div className="flex items-center gap-1">
+      <Link href="/dashboard"
+        className="px-3 py-2 rounded-lg text-navbar-nav-foreground hover:bg-navbar-nav-hover transition-colors">
+        Dashboard
+      </Link>
+      <Link href="/leads"
+        className="px-3 py-2 rounded-lg text-navbar-nav-foreground hover:bg-navbar-nav-hover transition-colors">
+        Leads
+      </Link>
+    </div>
+  </div>
+</nav>
+```
+
+### Card
+
+```tsx
+<div className="bg-card border border-card-line rounded-xl overflow-hidden">
+  <div className="bg-card-header px-6 py-4 border-b border-card-divider">
+    <h3 className="text-foreground font-semibold">Title</h3>
+  </div>
+  <div className="px-6 py-4">
+    <p className="text-muted-foreground">Content</p>
+  </div>
+  <div className="bg-card-footer px-6 py-3 border-t border-card-divider">
+    <button className="bg-primary text-primary-foreground px-4 py-2 rounded-lg hover:bg-primary-hover transition-colors">
+      Action
+    </button>
+  </div>
+</div>
+```
+
+### Sidebar
+
+```tsx
+<aside className="w-64 bg-sidebar border-r border-sidebar-line h-screen">
+  <nav className="p-4 space-y-1">
+    {navItems.map(item => (
+      <Link key={item.href} href={item.href}
+        className={`flex items-center gap-3 px-3 py-2 rounded-lg transition-colors
+          ${isActive(item.href)
+            ? 'bg-sidebar-nav-active text-primary font-medium'
+            : 'text-sidebar-nav-foreground hover:bg-sidebar-nav-hover'}`}>
+        {item.icon}
+        {item.label}
+      </Link>
+    ))}
+  </nav>
+</aside>
+```
+
+### Dropdown (with Preline JS)
+
+```tsx
+<div className="hs-dropdown relative">
+  <button className="hs-dropdown-toggle px-4 py-2 bg-layer border border-layer-line rounded-lg text-layer-foreground hover:bg-layer-hover">
+    Options ▾
+  </button>
+  <div className="hs-dropdown-menu hidden bg-dropdown border border-dropdown-line rounded-lg shadow-lg mt-1 p-1 min-w-48">
+    <button className="w-full text-left px-3 py-2 rounded-md text-dropdown-item-foreground hover:bg-dropdown-item-hover">
+      Edit
+    </button>
+    <div className="border-t border-dropdown-divider my-1" />
+    <button className="w-full text-left px-3 py-2 rounded-md text-destructive hover:bg-dropdown-item-hover">
+      Delete
+    </button>
+  </div>
+</div>
+```
+
+## Theme Generator (CLI)
+
+```bash
+# Generate theme from config
+npx preline-theme-generator /tmp/config.json ./resources/css/themes/brand.css
+
+# Config format:
+{
+  "name": "brand",
+  "hue": 250,
+  "style": "professional",
+  "useCustomDarkGray": true,
+  "tailwindGray": "neutral"
+}
+```
+
+## Chart Tokens (Apexcharts)
+
+```css
+/* Charts require HEX for gradients — no oklch! */
+--chart-colors-primary-hex: #2563eb;
+--chart-colors-chart-1-hex: #8b5cf6;
+--chart-colors-chart-2-hex: #06b6d4;
+```
+
+## FORBIDDEN
+
+| ❌ Don't | ✅ Do |
+|---|---|
+| Modify `theme.css` (base) | Create separate theme file |
+| Put tokens inside `@theme` block | Tokens in selector blocks only |
+| Use raw colors (`bg-blue-500`) | Use semantic tokens (`bg-primary`) |
+| `oklch()` in chart `-hex` tokens | Use hex format for charts |
+| Force HTML class changes | Theme activation via `data-theme` only |
+| Invent token names | Follow Preline's naming system |
+| `@apply` for component styles | React components with token classes |
+| Skip `HSStaticMethods.autoInit()` | Always re-init after Inertia navigation |

package/stacks/frontend/react/skills/tailwind-patterns/SKILL.md

@@ -1,94 +1,273 @@
-# Tailwind Patterns — Utility-First CSS
+# TailwindCSS 4 — CSS-First Design System
 
-**ALWAYS invoke when writing Tailwind CSS classes.**
+**ALWAYS invoke when writing Tailwind classes, theming, or responsive layouts.**
 
-## Mobile-First Breakpoints
+## What Changed (v3 → v4)
 
-```
-sm: 640px → md: 768px → lg: 1024px → xl: 1280px → 2xl: 1536px
+| v3 (Legacy) | v4 (Current) |
+|---|---|
+| `tailwind.config.js` | CSS `@theme` directive |
+| PostCSS plugin | Oxide engine (10x faster) |
+| `@tailwind base/components/utilities` | `@import "tailwindcss"` |
+| Colors in JS config | Colors as CSS variables |
+| `@apply` everywhere | Components > `@apply` |
+
+## Setup (v4)
+
+```css
+/* resources/css/app.css (Laravel + Inertia) */
+@import "tailwindcss";
+
+@theme {
+  /* ─── Semantic Colors (OKLCH for perceptual uniformity) ─── */
+  --color-primary: oklch(0.55 0.15 250);
+  --color-primary-foreground: oklch(0.98 0 0);
+  --color-secondary: oklch(0.75 0.05 250);
+  --color-secondary-foreground: oklch(0.15 0 0);
+  --color-destructive: oklch(0.55 0.2 25);
+  --color-destructive-foreground: oklch(0.98 0 0);
+
+  --color-background: oklch(0.99 0 0);
+  --color-foreground: oklch(0.15 0 0);
+  --color-muted: oklch(0.95 0.01 250);
+  --color-muted-foreground: oklch(0.45 0.02 250);
+  --color-border: oklch(0.90 0.01 250);
+  --color-ring: oklch(0.55 0.15 250);
+
+  --color-surface: oklch(0.98 0 0);
+  --color-surface-raised: oklch(1 0 0);
+
+  /* ─── Typography ─── */
+  --font-sans: 'Inter', system-ui, sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+
+  /* ─── Spacing ─── */
+  --spacing-page: 1rem;
+
+  /* ─── Border Radius ─── */
+  --radius-sm: 0.375rem;
+  --radius-md: 0.5rem;
+  --radius-lg: 0.75rem;
+  --radius-xl: 1rem;
+
+  /* ─── Shadows ─── */
+  --shadow-sm: 0 1px 2px oklch(0 0 0 / 0.05);
+  --shadow-md: 0 4px 6px oklch(0 0 0 / 0.07);
+  --shadow-lg: 0 10px 15px oklch(0 0 0 / 0.1);
+
+  /* ─── Animations ─── */
+  --animate-fade-in: fade-in 0.2s ease-out;
+  --animate-slide-up: slide-up 0.3s ease-out;
+  --animate-slide-down: slide-down 0.3s ease-out;
+}
+
+/* ─── Dark Mode Override ─── */
+@theme dark {
+  --color-background: oklch(0.13 0.01 250);
+  --color-foreground: oklch(0.95 0 0);
+  --color-surface: oklch(0.17 0.01 250);
+  --color-surface-raised: oklch(0.21 0.01 250);
+  --color-muted: oklch(0.22 0.02 250);
+  --color-muted-foreground: oklch(0.65 0.02 250);
+  --color-border: oklch(0.28 0.02 250);
+}
+
+/* ─── Keyframes ─── */
+@keyframes fade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+@keyframes slide-up {
+  from { opacity: 0; transform: translateY(8px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+@keyframes slide-down {
+  from { opacity: 0; transform: translateY(-8px); }
+  to { opacity: 1; transform: translateY(0); }
+}
 ```
 
-```tsx
-<div className="w-full md:w-1/2 lg:w-1/3 xl:w-1/4">
-  {/* Mobile: full → Tablet: half → Desktop: third → Large: quarter */}
-</div>
+## Color Token Architecture
+
 ```
+Layer 1 — Primitive:    oklch(0.55 0.15 250)         (raw values)
+Layer 2 — Semantic:     --color-primary               (purpose-based)
+Layer 3 — Component:    className="bg-primary"         (usage in JSX)
 
-## Layout Patterns
+Usage in Tailwind classes:
+  bg-primary text-primary-foreground
+  bg-destructive text-destructive-foreground
+  bg-muted text-muted-foreground
+  bg-surface border-border
+```
 
-### Flexbox
-```tsx
-// Center
-<div className="flex items-center justify-center h-screen" />
+## Mobile-First Responsive
 
-// Responsive direction
-<div className="flex flex-col md:flex-row gap-4" />
+```
+Breakpoints (min-width):
+  (none) → 0px      Mobile base
+  sm:    → 640px    Large phone
+  md:    → 768px    Tablet
+  lg:    → 1024px   Laptop
+  xl:    → 1280px   Desktop
+  2xl:   → 1536px   Large desktop
 ```
 
-### Grid
 ```tsx
-// Responsive grid
-<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4" />
+{/* Mobile: stack → Tablet: 2 cols → Desktop: 3 cols */}
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
 
-// Auto-fit
-<div className="grid grid-cols-[repeat(auto-fit,minmax(300px,1fr))] gap-4" />
+{/* Mobile: full width → Desktop: sidebar layout */}
+<div className="flex flex-col lg:flex-row gap-6">
+  <aside className="w-full lg:w-64 shrink-0">Sidebar</aside>
+  <main className="flex-1">Content</main>
+</div>
 ```
 
-## Dark Mode
+## Container Queries (v4 Native)
 
 ```tsx
-<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
-  <p className="text-gray-600 dark:text-gray-300">Adapts to theme</p>
+{/* Parent defines container */}
+<div className="@container">
+  {/* Children respond to PARENT width, not viewport */}
+  <div className="flex flex-col @md:flex-row @lg:grid @lg:grid-cols-3 gap-4">
+    <Card />
+  </div>
+</div>
+
+{/* Named containers for specificity */}
+<div className="@container/card">
+  <h2 className="text-sm @md/card:text-lg">Title</h2>
 </div>
 ```
 
+**Rule:** Use container queries for **reusable components** (cards, widgets). Use viewport breakpoints for **page-level layouts**.
+
 ## Component Patterns
 
-### Card
+### Button
+
 ```tsx
-<div className="bg-white dark:bg-gray-800 rounded-lg shadow-md p-6 border border-gray-200 dark:border-gray-700 hover:shadow-lg transition-shadow">
+const buttonVariants = {
+  base: "inline-flex items-center justify-center font-medium rounded-md transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:opacity-50 disabled:cursor-not-allowed",
+  variant: {
+    primary: "bg-primary text-primary-foreground hover:bg-primary/90",
+    secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+    destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+    outline: "border border-border bg-transparent hover:bg-muted",
+    ghost: "hover:bg-muted",
+  },
+  size: {
+    sm: "h-8 px-3 text-sm",
+    md: "h-10 px-4 text-sm",
+    lg: "h-12 px-6 text-base",
+  },
+};
 ```
 
-### Button
+### Card
+
 ```tsx
-<button className="bg-primary text-primary-foreground px-4 py-2 rounded-md font-medium hover:bg-primary/90 focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2 disabled:opacity-50 disabled:cursor-not-allowed transition-colors">
+<div className="bg-surface-raised rounded-lg border border-border shadow-sm p-6 hover:shadow-md transition-shadow">
+  <h3 className="text-lg font-semibold text-foreground">Title</h3>
+  <p className="mt-2 text-muted-foreground">Description</p>
+</div>
 ```
 
 ### Input
+
 ```tsx
-<input className="w-full px-3 py-2 bg-white dark:bg-gray-900 border border-gray-300 dark:border-gray-700 rounded-md text-gray-900 dark:text-white placeholder:text-gray-400 focus:outline-none focus:ring-2 focus:ring-primary focus:border-transparent" />
+<input className="w-full h-10 px-3 rounded-md border border-border bg-background text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:border-transparent transition-colors" />
 ```
 
-## Animations
+### Table (responsive)
 
 ```tsx
-<Loader className="h-5 w-5 animate-spin" />           // Spinner
-<div className="h-4 w-24 bg-gray-200 animate-pulse" /> // Skeleton
-```
-
-### Custom (tailwind.config.js)
-```js
-animation: {
-  'fade-in': 'fadeIn 0.3s ease-in-out',
-  'slide-up': 'slideUp 0.3s ease-out',
-},
-keyframes: {
-  fadeIn: { '0%': { opacity: '0' }, '100%': { opacity: '1' } },
-  slideUp: { '0%': { transform: 'translateY(10px)', opacity: '0' }, '100%': { transform: 'translateY(0)', opacity: '1' } },
-}
+{/* Mobile: card layout → Desktop: table */}
+<div className="hidden md:block">
+  <table className="w-full text-sm">
+    <thead className="border-b border-border">
+      <tr className="text-left text-muted-foreground">
+        <th className="p-3 font-medium">Name</th>
+      </tr>
+    </thead>
+  </table>
+</div>
+<div className="md:hidden space-y-3">
+  {/* Card layout for mobile */}
+</div>
+```
+
+## Dark Mode
+
+```tsx
+{/* Automatic with semantic tokens */}
+<div className="bg-background text-foreground">
+  <p className="text-muted-foreground">Always adapts</p>
+  <div className="border-border bg-surface">Card</div>
+</div>
+
+{/* Toggle button */}
+<button onClick={() => document.documentElement.classList.toggle('dark')}>
+  Toggle Theme
+</button>
 ```
 
-## Show/Hide Responsive
+**Rule:** Use semantic tokens (`bg-background`, `text-foreground`) instead of explicit dark classes. The `@theme dark` block handles everything.
+
+## Show/Hide
 
 ```tsx
 <div className="hidden lg:block">Desktop only</div>
-<div className="block lg:hidden">Mobile only</div>
+<div className="lg:hidden">Mobile only</div>
 <span className="sr-only">Screen reader only</span>
 ```
 
+## Auto-fit Grid
+
+```tsx
+{/* Cards that auto-wrap based on available space */}
+<div className="grid grid-cols-[repeat(auto-fit,minmax(280px,1fr))] gap-4">
+  {items.map(item => <Card key={item.id} {...item} />)}
+</div>
+```
+
+## Animations
+
+```tsx
+<div className="animate-fade-in">Fades in on mount</div>
+<div className="animate-slide-up">Slides up on mount</div>
+<Loader className="h-5 w-5 animate-spin" />
+<div className="h-4 w-24 bg-muted animate-pulse rounded" />  {/* Skeleton */}
+```
+
+## Spacing Consistency
+
+```
+Use the 4px scale consistently:
+  gap-1 = 4px    p-1 = 4px
+  gap-2 = 8px    p-2 = 8px
+  gap-3 = 12px   p-3 = 12px
+  gap-4 = 16px   p-4 = 16px
+  gap-6 = 24px   p-6 = 24px
+  gap-8 = 32px   p-8 = 32px
+
+Page padding: px-4 md:px-6 lg:px-8
+Section gaps: space-y-6 md:space-y-8
+Card padding: p-4 md:p-6
+```
+
 ## FORBIDDEN
 
-1. **`!important`** — fix specificity properly
-2. **Arbitrary values when utilities exist** — use the scale
-3. **Mixing raw CSS with Tailwind** — stick to utilities
-4. **Inconsistent spacing** — follow the 4px scale (p-1=4px, p-2=8px, p-4=16px)
+| ❌ Don't | ✅ Do |
+|---|---|
+| `tailwind.config.js` in v4 | `@theme` in CSS |
+| `@apply` for everything | React components |
+| `!important` | Fix specificity |
+| `style={{ color: 'red' }}` | `text-destructive` |
+| Arbitrary values for tokens | Define in `@theme` |
+| `bg-white dark:bg-gray-900` | `bg-background` (semantic) |
+| `@tailwind base` | `@import "tailwindcss"` (v4) |
+| Dynamic class strings | Static complete strings (purge-safe) |
+| `text-[#FF5733]` inline | `--color-accent` in `@theme` |
+| Inconsistent spacing | Follow 4px scale |