@j3m-quantum/ui 2.1.0 → 2.1.5

package/dist/cli/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import * as fs2 from 'fs';
-import * as path2 from 'path';
+import * as path from 'path';
 
 var CURSOR_RULES_CONTENT = `# J3M Design System Rules
 
@@ -10,21 +10,128 @@ var CURSOR_RULES_CONTENT = `# J3M Design System Rules
 - Do NOT use shadcn CLI to add components - everything is already bundled
 - Do NOT create local component copies - use the package exports
 
-## CRITICAL: Do NOT Create Components
+## CRITICAL: Pre-built Blocks - USE THESE FIRST!
 
-When implementing UI from Figma or any design:
-1. FIRST check if @j3m-quantum/ui has the component (see list below)
-2. Use the package component with appropriate props
-3. NEVER create new component files for existing components
+Before implementing ANY sidebar, navigation, header, or dashboard layout, ALWAYS import these pre-built blocks:
+
+\`\`\`tsx
+// Pre-built blocks - USE THESE, don't build from scratch!
+import {
+  SiteHeader,      // Header with breadcrumbs + search + sidebar trigger
+  NavMain,         // Main navigation with icons + collapsible sub-items
+  NavSecondary,    // Secondary nav (Support, Feedback links)
+  NavUser,         // User profile with dropdown menu
+  NavProjects,     // Project list navigation
+  SearchForm,      // Search input for sidebar
+} from '@j3m-quantum/ui'
+\`\`\`
+
+## \u26D4 NEVER Create These Manually
+
+| Instead of building... | Use this block |
+|------------------------|----------------|
+| \u274C Custom sidebar navigation | \u2705 \`NavMain\` |
+| \u274C Custom user menu/profile | \u2705 \`NavUser\` |
+| \u274C Custom page header | \u2705 \`SiteHeader\` |
+| \u274C Custom project list | \u2705 \`NavProjects\` |
+| \u274C Custom secondary links | \u2705 \`NavSecondary\` |
+| \u274C Custom search in sidebar | \u2705 \`SearchForm\` |
+| \u274C Custom CSS tokens | \u2705 Package provides all tokens |
+
+## Block Props Reference
+
+### NavMain
+\`\`\`tsx
+import { NavMain, type NavItem } from '@j3m-quantum/ui'
+import { Home, Settings, Users } from 'lucide-react'
+
+const navItems: NavItem[] = [
+  { title: "Home", url: "/", icon: Home, isActive: true },
+  { title: "Settings", url: "/settings", icon: Settings, items: [
+    { title: "General", url: "/settings/general" },
+    { title: "Team", url: "/settings/team" },
+  ]},
+  { title: "Users", url: "/users", icon: Users },
+]
+
+<NavMain items={navItems} label="Navigation" />
+\`\`\`
+
+### NavUser
+\`\`\`tsx
+import { NavUser } from '@j3m-quantum/ui'
+
+<NavUser 
+  user={{ 
+    name: "John Doe", 
+    email: "john@example.com", 
+    avatar: "/avatar.jpg"  // or "" for initials fallback
+  }} 
+/>
+\`\`\`
+
+### SiteHeader
+\`\`\`tsx
+import { SiteHeader, SidebarTrigger } from '@j3m-quantum/ui'
+
+<SiteHeader 
+  trigger={<SidebarTrigger />}
+  breadcrumbs={[
+    { label: "Dashboard", href: "/" },
+    { label: "Settings" }  // No href = current page
+  ]}
+  showSearch={true}
+/>
+\`\`\`
+
+### NavSecondary
+\`\`\`tsx
+import { NavSecondary } from '@j3m-quantum/ui'
+import { LifeBuoy, Send } from 'lucide-react'
+
+<NavSecondary items={[
+  { title: "Support", url: "/support", icon: LifeBuoy },
+  { title: "Feedback", url: "/feedback", icon: Send },
+]} />
+\`\`\`
+
+## Sidebar Features Checklist
+
+When using Sidebar, remember these features:
+
+| Feature | Usage |
+|---------|-------|
+| \`collapsible="icon"\` | Collapses sidebar to icons only |
+| \`collapsible="offcanvas"\` | Slides sidebar off screen |
+| \`<SidebarRail />\` | Edge rail for drag-to-toggle |
+| \`tooltip\` prop on SidebarMenuButton | Shows tooltips when collapsed |
+| \`<SidebarMenuBadge>\` | Notification counts on menu items |
+| \`<SidebarGroup>\` + \`<SidebarGroupLabel>\` | Organize sections |
+
+\`\`\`tsx
+<Sidebar collapsible="icon">
+  <SidebarContent>
+    <SidebarGroup>
+      <SidebarGroupLabel>Platform</SidebarGroupLabel>
+      <NavMain items={navItems} />
+    </SidebarGroup>
+  </SidebarContent>
+  <SidebarRail />
+</Sidebar>
+\`\`\`
 
 ## CSS Import Order (Critical)
-The order in src/index.css must be:
 \`\`\`css
 @import "tailwindcss";
 @import "tw-animate-css";           /* Required for animations */
 @import "@j3m-quantum/ui/styles";   /* J3M theme and tokens */
+
+/* REQUIRED: Tell Tailwind to scan the package for utility classes */
+@source "../node_modules/@j3m-quantum/ui/dist/**/*.js";
 \`\`\`
 
+The @source directive is CRITICAL - without it, Tailwind v4 won't generate CSS for component classes.
+
 ## Theme Modes (4 Modes)
 | Mode | Classes | Description |
 |------|---------|-------------|
@@ -58,28 +165,17 @@ When you see these Figma layer names, use these components:
 
 | Figma Layer Name | Import |
 |------------------|--------|
-| "Button", "CTA", "Primary Button", "Action" | \`import { Button } from '@j3m-quantum/ui'\` |
-| "Card", "Container", "Panel", "Box" | \`import { Card, CardHeader, CardContent } from '@j3m-quantum/ui'\` |
-| "Input", "Text Field", "Text Input" | \`import { Input } from '@j3m-quantum/ui'\` |
-| "Dialog", "Modal", "Popup" | \`import { Dialog, DialogContent, DialogHeader } from '@j3m-quantum/ui'\` |
-| "Sheet", "Side Panel", "Drawer" | \`import { Sheet, SheetContent } from '@j3m-quantum/ui'\` |
-| "Table", "Data Table", "Grid" | \`import { Table } from '@j3m-quantum/ui'\` |
-| "Planning Grid", "Week Table", "Supplier Matrix" | \`import { PlanningTable } from '@j3m-quantum/ui'\` |
-| "Calibration Table", "Production Grid" | \`import { CalibrationTable } from '@j3m-quantum/ui'\` |
-| "Loading View", "Delivery Grid" | \`import { SupplierWeeklyLoading } from '@j3m-quantum/ui'\` |
-| "Sidebar", "Navigation" | \`import { Sidebar, SidebarProvider } from '@j3m-quantum/ui'\` |
-| "Dropdown", "Menu" | \`import { DropdownMenu } from '@j3m-quantum/ui'\` |
-| "Select", "Picker" | \`import { Select } from '@j3m-quantum/ui'\` |
-| "Checkbox", "Check" | \`import { Checkbox } from '@j3m-quantum/ui'\` |
-| "Switch", "Toggle" | \`import { Switch } from '@j3m-quantum/ui'\` |
-| "Badge", "Tag", "Label" | \`import { Badge } from '@j3m-quantum/ui'\` |
-| "Avatar", "Profile Image" | \`import { Avatar } from '@j3m-quantum/ui'\` |
-| "Progress", "Progress Bar" | \`import { Progress } from '@j3m-quantum/ui'\` |
-| "Tabs", "Tab Bar" | \`import { Tabs, TabsList, TabsTrigger, TabsContent } from '@j3m-quantum/ui'\` |
-| "Accordion", "Expandable" | \`import { Accordion } from '@j3m-quantum/ui'\` |
-| "Tooltip", "Hint" | \`import { Tooltip } from '@j3m-quantum/ui'\` |
-| "Calendar", "Date Picker" | \`import { Calendar } from '@j3m-quantum/ui'\` |
-| "Chart", "Graph" | \`import { Chart } from '@j3m-quantum/ui'\` |
+| "Button", "CTA", "Primary Button" | \`Button\` |
+| "Card", "Container", "Panel" | \`Card, CardHeader, CardContent\` |
+| "Input", "Text Field" | \`Input\` |
+| "Dialog", "Modal", "Popup" | \`Dialog, DialogContent, DialogHeader\` |
+| "Sheet", "Side Panel", "Drawer" | \`Sheet, SheetContent\` |
+| "Sidebar", "Navigation", "Nav" | \`SidebarProvider, Sidebar, NavMain\` |
+| "Header", "Page Header", "Toolbar" | \`SiteHeader\` |
+| "User Menu", "Profile", "Avatar Menu" | \`NavUser\` |
+| "Table", "Data Grid" | \`Table\` |
+| "Planning Grid", "Week Table" | \`PlanningTable\` |
+| "Calibration Table" | \`CalibrationTable\` |
 
 ## Available Components (60+)
 
@@ -109,83 +205,108 @@ Map, MapTileLayer, MapMarker, MapPopup, MapTooltip, MapZoomControl
 
 ## DO
 - Import all components from @j3m-quantum/ui
+- Use pre-built blocks (NavMain, NavUser, SiteHeader) instead of building custom
 - Use Tailwind semantic classes: bg-primary, text-muted-foreground, bg-accent
-- Use CSS variables for custom styling: var(--primary), var(--background)
 - Use \`glass-context\` class on Cards with interactive components in glass mode
-- Check the component list above before building custom components
-- Use the j3m-app-bg class on root element for proper backgrounds
+- Check the component/block list above BEFORE building anything custom
 
 ## DON'T
-- Don't create new component files for UI elements that exist in @j3m-quantum/ui
+- Don't create new component files for UI that exists in @j3m-quantum/ui
+- Don't build custom sidebar/navigation - use NavMain, NavUser, etc.
 - Don't use shadcn CLI - components are already bundled
-- Don't override component CSS unless approved by design system maintainer
+- Don't add custom CSS tokens - the package provides everything
 - Don't use arbitrary color values like bg-[#F58446] - use bg-primary
-- Don't modify component border-radius - pill shapes are intentional
-- Don't style portal components manually - they auto-adapt to theme
 
-## Common Patterns
+## Complete Dashboard Example (Header on Top)
 
-### Form in Card
-\`\`\`tsx
-import { Card, CardHeader, CardTitle, CardContent, Input, Button } from '@j3m-quantum/ui'
+The recommended layout places the header at the top spanning full width,
+with the sidebar positioned below it:
 
-<Card className="glass-context">
-  <CardHeader>
-    <CardTitle>Contact Form</CardTitle>
-  </CardHeader>
-  <CardContent className="space-y-4">
-    <Input placeholder="Name" />
-    <Input placeholder="Email" />
-    <Button>Send</Button>
-  </CardContent>
-</Card>
+\`\`\`
+\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+\u2502            SiteHeader               \u2502  \u2190 Full width, sticky
+\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524
+\u2502          \u2502                          \u2502
+\u2502 Sidebar  \u2502      SidebarInset        \u2502
+\u2502          \u2502       (content)          \u2502
+\u2502          \u2502                          \u2502
+\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
 \`\`\`
 
-### Dashboard Layout
 \`\`\`tsx
 import { 
-  SidebarProvider, Sidebar, SidebarContent, SidebarFooter, SidebarInset,
-  SiteHeader, SidebarTrigger, NavMain, NavUser 
+  SidebarProvider, Sidebar, SidebarContent, SidebarFooter, SidebarInset, SidebarRail,
+  SiteHeader, SidebarTrigger, NavMain, NavUser, NavSecondary, 
+  SIDEBAR_BELOW_HEADER_CLASS, type NavItem
 } from '@j3m-quantum/ui'
-
-<SidebarProvider>
-  <Sidebar>
-    <SidebarContent>
-      <NavMain items={navItems} />
-    </SidebarContent>
-    <SidebarFooter>
-      <NavUser user={userData} />
-    </SidebarFooter>
-  </Sidebar>
-  <SidebarInset>
-    <SiteHeader trigger={<SidebarTrigger />} breadcrumbs={[{ label: "Dashboard" }]} />
-    <main className="p-4">{/* Content */}</main>
-  </SidebarInset>
-</SidebarProvider>
+import { Home, Settings, LifeBuoy, Send } from 'lucide-react'
+
+const navItems: NavItem[] = [
+  { title: "Home", url: "/", icon: Home, isActive: true },
+  { title: "Settings", url: "/settings", icon: Settings },
+]
+
+function App() {
+  return (
+    <div 
+      className="j3m-app-bg min-h-screen" 
+      style={{ "--header-height": "3.5rem" } as React.CSSProperties}
+    >
+      <SidebarProvider className="flex flex-col min-h-screen">
+        {/* Header FIRST - spans full width */}
+        <SiteHeader 
+          trigger={<SidebarTrigger />} 
+          breadcrumbs={[{ label: "Dashboard" }]} 
+        />
+        
+        {/* Sidebar + Content below header */}
+        <div className="flex flex-1">
+          <Sidebar collapsible="icon" className={SIDEBAR_BELOW_HEADER_CLASS}>
+            <SidebarContent>
+              <NavMain items={navItems} />
+            </SidebarContent>
+            <SidebarFooter>
+              <NavSecondary items={[
+                { title: "Support", url: "#", icon: LifeBuoy },
+                { title: "Feedback", url: "#", icon: Send },
+              ]} />
+              <NavUser user={{ name: "John Doe", email: "john@example.com", avatar: "" }} />
+            </SidebarFooter>
+            <SidebarRail />
+          </Sidebar>
+          <SidebarInset>
+            <main className="p-4">
+              {/* Your content here */}
+            </main>
+          </SidebarInset>
+        </div>
+      </SidebarProvider>
+    </div>
+  )
+}
 \`\`\`
 
-### Dialog with Form
-\`\`\`tsx
-import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, Input, Button } from '@j3m-quantum/ui'
-
-<Dialog>
-  <DialogTrigger asChild>
-    <Button>Open Form</Button>
-  </DialogTrigger>
-  <DialogContent>
-    <DialogHeader>
-      <DialogTitle>Edit Profile</DialogTitle>
-    </DialogHeader>
-    {/* No glass-context needed - Dialog is a portal */}
-    <Input placeholder="Name" />
-    <Button>Save</Button>
-  </DialogContent>
-</Dialog>
-\`\`\`
+Key points:
+- Set \`--header-height: 3.5rem\` on the wrapper div
+- \`SidebarProvider\` needs \`className="flex flex-col min-h-screen"\`
+- \`SiteHeader\` comes FIRST (before the sidebar)
+- Wrap Sidebar + SidebarInset in \`<div className="flex flex-1">\`
+- Add \`SIDEBAR_BELOW_HEADER_CLASS\` to Sidebar (or use: \`className="top-[var(--header-height)] h-[calc(100svh-var(--header-height))]!"\`)
 
-## CLI Commands
+## Recommended Prompts for AI
+
+**Good prompts:**
+- "Create a dashboard using @j3m-quantum/ui blocks: NavMain, NavUser, SiteHeader"
+- "Use only pre-built blocks from @j3m-quantum/ui, don't create custom components"
+- "Import SiteHeader for the header and NavMain for navigation from @j3m-quantum/ui"
+- "Check the j3m-quantum cursor rules before implementing"
 
-Run these in your project:
+**Bad prompts (avoid these):**
+- "Create a sidebar" \u2192 AI might build from scratch
+- "Add navigation" \u2192 Too vague, specify NavMain
+- "Make a header" \u2192 Specify SiteHeader instead
+
+## CLI Commands
 
 \`\`\`bash
 npx @j3m-quantum/ui init     # Set up these rules (already done!)
@@ -193,12 +314,53 @@ npx @j3m-quantum/ui list     # List all available components
 npx @j3m-quantum/ui doctor   # Check if setup is correct
 \`\`\`
 `;
+var SOURCE_DIRECTIVE = '@source "../node_modules/@j3m-quantum/ui/dist/**/*.js";';
+function findCssFile(cwd) {
+  const possiblePaths = [
+    path.join(cwd, "src", "index.css"),
+    path.join(cwd, "src", "styles", "globals.css"),
+    path.join(cwd, "src", "styles", "index.css"),
+    path.join(cwd, "src", "app", "globals.css"),
+    path.join(cwd, "app", "globals.css"),
+    path.join(cwd, "styles", "globals.css"),
+    path.join(cwd, "styles", "index.css")
+  ];
+  for (const cssPath of possiblePaths) {
+    if (fs2.existsSync(cssPath)) {
+      return cssPath;
+    }
+  }
+  return null;
+}
+function updateCssFile(cssPath) {
+  const content = fs2.readFileSync(cssPath, "utf-8");
+  if (content.includes("@j3m-quantum/ui/dist")) {
+    return { updated: false, message: "already configured" };
+  }
+  if (!content.includes("@j3m-quantum/ui/styles")) {
+    return { updated: false, message: "missing @j3m-quantum/ui/styles import" };
+  }
+  const lines = content.split("\n");
+  let insertIndex = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes("@j3m-quantum/ui/styles")) {
+      insertIndex = i + 1;
+      break;
+    }
+  }
+  if (insertIndex === -1) {
+    return { updated: false, message: "could not find insertion point" };
+  }
+  lines.splice(insertIndex, 0, "", "/* Required: Tell Tailwind v4 to scan package for utility classes */", SOURCE_DIRECTIVE);
+  fs2.writeFileSync(cssPath, lines.join("\n"), "utf-8");
+  return { updated: true, message: "added @source directive" };
+}
 async function init() {
   const cwd = process.cwd();
-  const cursorDir = path2.join(cwd, ".cursor");
-  const rulesDir = path2.join(cursorDir, "rules");
-  const rulesFile = path2.join(rulesDir, "j3m-quantum.md");
-  const cursorRulesFile = path2.join(cwd, ".cursorrules");
+  const cursorDir = path.join(cwd, ".cursor");
+  const rulesDir = path.join(cursorDir, "rules");
+  const rulesFile = path.join(rulesDir, "j3m-quantum.md");
+  const cursorRulesFile = path.join(cwd, ".cursorrules");
   console.log("");
   console.log("\u{1F3A8} Setting up @j3m-quantum/ui...");
   console.log("");
@@ -217,24 +379,49 @@ async function init() {
       }
     }
     console.log("");
+    console.log("Configuring Tailwind v4...");
+    const cssFile = findCssFile(cwd);
+    if (cssFile) {
+      const relativePath = cssFile.replace(cwd, "").replace(/^\//, "");
+      const result = updateCssFile(cssFile);
+      if (result.updated) {
+        console.log(`  \u2713 Updated ${relativePath} - ${result.message}`);
+      } else if (result.message === "already configured") {
+        console.log(`  \u2713 ${relativePath} - already configured`);
+      } else {
+        console.log(`  \u26A0 ${relativePath} - ${result.message}`);
+        console.log("    You may need to manually add:");
+        console.log(`    ${SOURCE_DIRECTIVE}`);
+      }
+    } else {
+      console.log("  \u26A0 Could not find CSS entry file");
+      console.log("    Add this to your main CSS file after the @j3m-quantum/ui/styles import:");
+      console.log("");
+      console.log(`    ${SOURCE_DIRECTIVE}`);
+    }
+    console.log("");
     console.log("\u2705 Setup complete!");
     console.log("");
+    console.log("What was configured:");
+    console.log("  \u2022 AI cursor rules for correct component usage");
+    console.log("  \u2022 Tailwind v4 @source directive to scan package classes");
+    console.log("");
     console.log("AI assistants will now:");
     console.log("  \u2022 Use components from @j3m-quantum/ui");
     console.log("  \u2022 Know about all 60+ available components");
     console.log("  \u2022 Map Figma layers to correct components");
     console.log("  \u2022 Follow J3M styling guidelines");
     console.log("");
-    console.log("Next steps:");
-    console.log("  1. Ensure your CSS imports are correct:");
-    console.log('     @import "tailwindcss";');
-    console.log('     @import "tw-animate-css";');
-    console.log('     @import "@j3m-quantum/ui/styles";');
+    console.log("Required CSS imports (if not already present):");
+    console.log('  @import "tailwindcss";');
+    console.log('  @import "tw-animate-css";');
+    console.log('  @import "@j3m-quantum/ui/styles";');
+    console.log(`  ${SOURCE_DIRECTIVE}`);
     console.log("");
-    console.log("  2. Run 'npx @j3m-quantum/ui doctor' to verify setup");
+    console.log("Run 'npx @j3m-quantum/ui doctor' to verify setup");
     console.log("");
   } catch (error) {
-    console.error("\u274C Failed to set up cursor rules:", error.message);
+    console.error("\u274C Failed to set up:", error.message);
     process.exit(1);
   }
 }
@@ -410,7 +597,7 @@ async function doctor() {
   console.log("");
   console.log("Checking your project setup...");
   console.log("");
-  const packageJsonPath = path2.join(cwd, "package.json");
+  const packageJsonPath = path.join(cwd, "package.json");
   if (fs2.existsSync(packageJsonPath)) {
     const packageJson = JSON.parse(fs2.readFileSync(packageJsonPath, "utf-8"));
     const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
@@ -475,8 +662,8 @@ async function doctor() {
       message: "Not found - run from project root"
     });
   }
-  const cursorRulesPath = path2.join(cwd, ".cursor", "rules", "j3m-quantum.md");
-  const altCursorRulesPath = path2.join(cwd, ".cursorrules");
+  const cursorRulesPath = path.join(cwd, ".cursor", "rules", "j3m-quantum.md");
+  const altCursorRulesPath = path.join(cwd, ".cursorrules");
   if (fs2.existsSync(cursorRulesPath)) {
     results.push({
       name: "Cursor rules configured",
@@ -508,11 +695,11 @@ async function doctor() {
     });
   }
   const possibleCssPaths = [
-    path2.join(cwd, "src", "index.css"),
-    path2.join(cwd, "src", "styles", "globals.css"),
-    path2.join(cwd, "src", "app", "globals.css"),
-    path2.join(cwd, "app", "globals.css"),
-    path2.join(cwd, "styles", "globals.css")
+    path.join(cwd, "src", "index.css"),
+    path.join(cwd, "src", "styles", "globals.css"),
+    path.join(cwd, "src", "app", "globals.css"),
+    path.join(cwd, "app", "globals.css"),
+    path.join(cwd, "styles", "globals.css")
   ];
   let cssFound = false;
   let cssContent = "";
@@ -529,6 +716,7 @@ async function doctor() {
     const hasJ3mStyles = cssContent.includes("@j3m-quantum/ui/styles");
     const hasTailwind = cssContent.includes("tailwindcss");
     cssContent.includes("tw-animate-css");
+    const hasSourceDirective = cssContent.includes("@j3m-quantum/ui/dist");
     if (hasJ3mStyles && hasTailwind) {
       const tailwindIndex = cssContent.indexOf("tailwindcss");
       const twAnimateIndex = cssContent.indexOf("tw-animate-css");
@@ -563,6 +751,20 @@ async function doctor() {
         fix: 'Add: @import "tailwindcss";'
       });
     }
+    if (hasSourceDirective) {
+      results.push({
+        name: "Tailwind @source directive",
+        status: "pass",
+        message: `${foundCssPath} - @source configured for package scanning`
+      });
+    } else {
+      results.push({
+        name: "Tailwind @source directive",
+        status: "fail",
+        message: `${foundCssPath} - missing @source directive (components will be unstyled!)`,
+        fix: 'Add: @source "../node_modules/@j3m-quantum/ui/dist/**/*.js";'
+      });
+    }
   } else {
     results.push({
       name: "CSS imports configured",
@@ -571,8 +773,8 @@ async function doctor() {
       fix: "Create src/index.css with required imports"
     });
   }
-  const viteConfigPath = path2.join(cwd, "vite.config.ts");
-  const viteConfigJsPath = path2.join(cwd, "vite.config.js");
+  const viteConfigPath = path.join(cwd, "vite.config.ts");
+  const viteConfigJsPath = path.join(cwd, "vite.config.js");
   if (fs2.existsSync(viteConfigPath) || fs2.existsSync(viteConfigJsPath)) {
     const configPath = fs2.existsSync(viteConfigPath) ? viteConfigPath : viteConfigJsPath;
     const configContent = fs2.readFileSync(configPath, "utf-8");

package/dist/cli/postinstall.js

@@ -3,23 +3,50 @@
 var isCI = process.env.CI || process.env.CONTINUOUS_INTEGRATION;
 if (!isCI) {
   console.log(`
-\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
-\u2502                                                         \u2502
-\u2502   \u{1F3A8} @j3m-quantum/ui installed successfully!            \u2502
-\u2502                                                         \u2502
-\u2502   To set up AI assistance (Cursor, Copilot):            \u2502
-\u2502                                                         \u2502
-\u2502     npx @j3m-quantum/ui init                            \u2502
-\u2502                                                         \u2502
-\u2502   This ensures AI uses the correct components           \u2502
-\u2502   instead of creating new ones.                         \u2502
-\u2502                                                         \u2502
-\u2502   Other commands:                                       \u2502
-\u2502     npx @j3m-quantum/ui list     - List components      \u2502
-\u2502     npx @j3m-quantum/ui doctor   - Check setup          \u2502
-\u2502                                                         \u2502
-\u2502   Docs: See cursor-rules-for-consumers.md in package    \u2502
-\u2502                                                         \u2502
-\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+\u2502  \u{1F3A8} @j3m-quantum/ui installed successfully!                      \u2502
+\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+
+\u{1F4E6} Quick Start - Dashboard Layout (Header on Top):
+\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+import { 
+  SidebarProvider, Sidebar, SidebarContent, SidebarFooter, SidebarInset,
+  SiteHeader, SidebarTrigger, NavMain, NavUser, SIDEBAR_BELOW_HEADER_CLASS
+} from '@j3m-quantum/ui'
+
+<div className="j3m-app-bg min-h-screen" style={{ "--header-height": "3.5rem" }}>
+  <SidebarProvider className="flex flex-col min-h-screen">
+    {/* Header FIRST - spans full width */}
+    <SiteHeader trigger={<SidebarTrigger />} breadcrumbs={[{ label: "Home" }]} />
+    
+    {/* Sidebar + Content below header */}
+    <div className="flex flex-1">
+      <Sidebar collapsible="icon" className={SIDEBAR_BELOW_HEADER_CLASS}>
+        <SidebarContent>
+          <NavMain items={[{ title: "Home", url: "/", icon: Home, isActive: true }]} />
+        </SidebarContent>
+        <SidebarFooter>
+          <NavUser user={{ name: "User", email: "user@example.com", avatar: "" }} />
+        </SidebarFooter>
+      </Sidebar>
+      <SidebarInset>
+        <main className="p-4">{/* content */}</main>
+      </SidebarInset>
+    </div>
+  </SidebarProvider>
+</div>
+\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+\u26A1 IMPORTANT: Run this to set up AI assistance:
+
+   npx @j3m-quantum/ui init
+
+   This configures Cursor/Copilot to use the correct components
+   and adds the required @source directive for Tailwind v4.
+
+\u{1F4CB} Other commands:
+   npx @j3m-quantum/ui list     - List all 60+ components
+   npx @j3m-quantum/ui doctor   - Check if setup is correct
+
 `);
 }