@nqlib/nqui 0.4.8 → 0.5.1

package/docs/nqui-skills/nqui-local-published-toggle/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: nqui-local-published-toggle
+description: Enables switching between local (development) and published (npm) versions of @nqlib/nqui in consumer projects. Use when adding nqui to Vite, Next.js, or TypeScript projects; when user asks to "toggle nqui", "use local nqui", "npm link nqui", or "switch between local and published" nqui.
+---
+
+# nqui Local/Published Toggle
+
+Enables any consumer project (Vite, Next.js, TypeScript) to switch between local nqui development and the published npm package via `npm link` and env-driven scripts.
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `USE_LOCAL_NQUI=true` | Use local nqui via `npm link` |
+| `USE_LOCAL_NQUI=false` | Use published `@nqlib/nqui` from registry |
+| `NQUI_DIR` | Path to nqui **repo root** (default: sibling `../nqui` or customize in script) |
+| `SKIP_BUILD=true` | Skip `npm run build:lib` when already linked (local only) |
+
+## Setup Steps
+
+### 1. Add the script
+
+Copy [scripts/toggle-nqui.js](./scripts/toggle-nqui.js) into the consumer project's `scripts/` directory. Customize in the script:
+
+- `root` – Resolved from `__dirname` (parent of `scripts/`)
+- `nquiBaseDir` – Default `NQUI_DIR`; use `resolve(root, '..', 'nqui')` or absolute path
+- `PUBLISHED_VERSION` – Semver for published mode (e.g. `^0.5.0`)
+
+### 2. Add package.json scripts
+
+Replace `<framework-dev-command>` with the appropriate command:
+
+```json
+{
+  "scripts": {
+    "dev": "node scripts/toggle-nqui.js && <framework-dev-command>",
+    "dev:local": "USE_LOCAL_NQUI=true node scripts/toggle-nqui.js && <framework-dev-command>",
+    "dev:local:fast": "USE_LOCAL_NQUI=true SKIP_BUILD=true node scripts/toggle-nqui.js && <framework-dev-command>",
+    "dev:published": "USE_LOCAL_NQUI=false node scripts/toggle-nqui.js && <framework-dev-command>",
+    "toggle-nqui": "node scripts/toggle-nqui.js",
+    "nqui:status": "node scripts/toggle-nqui.js --check"
+  }
+}
+```
+
+### 3. Framework dev commands
+
+| Framework | `<framework-dev-command>` |
+|-----------|--------------------------|
+| Vite | `vite` |
+| Next.js | `next dev` or `next dev --webpack` (see Next.js note) |
+| Create React App | `react-scripts start` |
+
+### 4. Ensure dependency
+
+`@nqlib/nqui` must be in `dependencies` with semver:
+
+```json
+{
+  "dependencies": {
+    "@nqlib/nqui": "^0.5.0"
+  }
+}
+```
+
+## Framework-Specific Notes
+
+### Vite
+
+Works out of the box. No special config.
+
+### Next.js
+
+Use `next dev --webpack` when running with local nqui. Turbopack (Next.js 16+ default) has limited symlink support.
+
+Options:
+
+- Set `"dev": "next dev --webpack"` if you always want Webpack for dev
+- Or add `"dev:webpack": "next dev --webpack"` and use it in `dev:local` / `dev:local:fast`:
+
+```json
+"dev:local": "USE_LOCAL_NQUI=true node scripts/toggle-nqui.js && next dev --webpack",
+"dev:local:fast": "USE_LOCAL_NQUI=true SKIP_BUILD=true node scripts/toggle-nqui.js && next dev --webpack",
+"dev:published": "USE_LOCAL_NQUI=false node scripts/toggle-nqui.js && next dev"
+```
+
+### Monorepos
+
+Each app that uses nqui needs its own `scripts/toggle-nqui.js` and package.json scripts. Root can proxy:
+
+```json
+"dev:admin:local": "USE_LOCAL_NQUI=true npm --prefix client-saas run dev",
+"dev:admin:local:fast": "USE_LOCAL_NQUI=true SKIP_BUILD=true npm --prefix client-saas run dev",
+"dev:admin:published": "USE_LOCAL_NQUI=false npm --prefix client-saas run dev",
+"nqui:status": "npm --prefix client-saas run nqui:status"
+```
+
+## How It Works
+
+**Local mode** (`USE_LOCAL_NQUI=true`):
+
+1. Verify nqui exists at `NQUI_DIR/packages/nqui` (layout of the nqui **repository**)
+2. Run `npm run build:lib` in that package (unless `SKIP_BUILD=true` and already linked)
+3. Run `npm link` in the nqui package directory
+4. Run `npm unlink @nqlib/nqui` (if needed), then `npm link @nqlib/nqui` in consumer
+5. Update consumer `package.json` with `^${nqui.version}`
+
+**Published mode** (`USE_LOCAL_NQUI=false`):
+
+1. Run `npm unlink @nqlib/nqui`
+2. Set `package.json` to `"@nqlib/nqui": "^x.y.z"`
+3. Run `npm install @nqlib/nqui@^x.y.z` (add `--legacy-peer-deps` if needed)
+
+## Status Check
+
+```bash
+npm run nqui:status
+# or
+node scripts/toggle-nqui.js --check
+```
+
+Shows: Source (LOCAL/PUBLISHED), Version, Symlink status, Location.
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Next.js 16+ Turbopack symlink issues | Use `next dev --webpack` for dev when using local nqui |
+| pnpm | Script uses `npm link` for consistency; `npm link` works in pnpm projects |
+| Version mismatch | Update `PUBLISHED_VERSION` in script to match latest @nqlib/nqui release |
+| Peer dependency conflicts | Add `NPM_CONFIG_LEGACY_PEER_DEPS=true` to link env, or `--legacy-peer-deps` to install |
+| nqui dir not found | Set `NQUI_DIR` to absolute path of nqui **repository** root |

package/docs/nqui-skills/nqui-local-published-toggle/scripts/toggle-nqui.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * Toggle between local (npm link) and published @nqlib/nqui.
+ *
+ * CUSTOMIZE before copying to consumer project:
+ * - PROJECT_NAME: Used in log messages (e.g. "client-saas", "my-app")
+ * - PUBLISHED_VERSION: Semver for published mode (e.g. "^0.5.0")
+ * - USE_LEGACY_PEER_DEPS: true if consumer uses --legacy-peer-deps
+ * - NQUI_DIR: nqui repository root (monorepo with packages/nqui, or standalone nqui repo)
+ */
+import { readFileSync, writeFileSync, existsSync, lstatSync, realpathSync } from "fs";
+import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+import { dirname, join, resolve } from "path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/** Consumer project root when this file lives at `<project>/scripts/toggle-nqui.js` */
+const root = resolve(__dirname, "..");
+const packageJsonPath = join(root, "package.json");
+const nodeModulesNqui = join(root, "node_modules", "@nqlib", "nqui");
+
+// --- CUSTOMIZE ---
+const PROJECT_NAME = "this project"; // e.g. "client-saas", "my-vite-app"
+const PUBLISHED_VERSION = "^0.5.0"; // Match latest @nqlib/nqui release
+const USE_LEGACY_PEER_DEPS = false; // Set true if project uses --legacy-peer-deps
+// --- END CUSTOMIZE ---
+
+const nquiBaseDir = process.env.NQUI_DIR || resolve(root, "..", "nqui");
+
+/** Monorepo: <repo>/packages/nqui. Standalone nqui repo: <repo> is the package root. */
+const monorepoNquiDir = join(nquiBaseDir, "packages", "nqui");
+const nquiDir = existsSync(join(monorepoNquiDir, "package.json"))
+  ? monorepoNquiDir
+  : nquiBaseDir;
+
+const useLocal = process.env.USE_LOCAL_NQUI === "true";
+const skipBuild = process.env.SKIP_BUILD === "true";
+const checkOnly = process.argv.includes("--check") || process.argv.includes("--status");
+
+function isSymlink(path) {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function checkStatus() {
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+  const isLinked = existsSync(nodeModulesNqui) && isSymlink(nodeModulesNqui);
+
+  let version = "unknown";
+  let source = "unknown";
+
+  if (isLinked) {
+    try {
+      const resolvedPath = realpathSync(nodeModulesNqui);
+      if (resolvedPath.includes(nquiDir) || resolvedPath.includes("nqui")) {
+        source = "LOCAL (linked)";
+        try {
+          const nquiPackageJson = JSON.parse(readFileSync(join(nquiDir, "package.json"), "utf-8"));
+          version = nquiPackageJson.version;
+        } catch {
+          version = "unknown";
+        }
+      } else {
+        source = `LINKED (${resolvedPath})`;
+        try {
+          const linkedPackageJson = JSON.parse(readFileSync(join(resolvedPath, "package.json"), "utf-8"));
+          version = linkedPackageJson.version;
+        } catch {
+          version = "unknown";
+        }
+      }
+    } catch {
+      source = "LOCAL (linked)";
+    }
+  } else if (existsSync(nodeModulesNqui)) {
+    source = "PUBLISHED (npm package)";
+    try {
+      const installedPackageJson = JSON.parse(readFileSync(join(nodeModulesNqui, "package.json"), "utf-8"));
+      version = installedPackageJson.version;
+    } catch {
+      version = packageJson.dependencies["@nqlib/nqui"] || "unknown";
+    }
+  } else {
+    source = "NOT INSTALLED";
+  }
+
+  return { isLinked, version, source, packageVersion: packageJson.dependencies["@nqlib/nqui"] };
+}
+
+if (checkOnly) {
+  const status = checkStatus();
+  console.log("\nnqui Status:");
+  console.log("   Source:", status.source);
+  console.log("   Version:", status.version);
+  console.log("   Package.json:", status.packageVersion);
+  console.log("   Symlink:", status.isLinked ? "Yes" : "No");
+  console.log("   Location:", existsSync(nodeModulesNqui) ? nodeModulesNqui : "Not found", "\n");
+  process.exit(0);
+}
+
+const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+
+console.log("\nToggling nqui source...");
+console.log("   NQUI_DIR (repo root):", nquiBaseDir);
+console.log("   nqui package:", nquiDir);
+console.log("   USE_LOCAL_NQUI:", useLocal);
+console.log("   SKIP_BUILD:", skipBuild, "\n");
+
+if (useLocal) {
+  if (!existsSync(nquiDir)) {
+    console.error("Error: nqui directory not found at", nquiDir);
+    console.error("   Set NQUI_DIR to the nqui repository root (monorepo or standalone).");
+    process.exit(1);
+  }
+
+  const nquiPackageJsonPath = join(nquiDir, "package.json");
+  if (!existsSync(nquiPackageJsonPath)) {
+    console.error("Error: package.json not found in", nquiDir);
+    process.exit(1);
+  }
+
+  const currentStatus = checkStatus();
+  const alreadyLinked = currentStatus.isLinked && currentStatus.source.includes("LOCAL");
+
+  if (skipBuild && alreadyLinked) {
+    console.log("Skipping build (SKIP_BUILD=true and already linked)\n");
+  } else {
+    console.log("Building nqui library...");
+    try {
+      execSync("npm run build:lib", { cwd: nquiDir, stdio: "inherit" });
+      console.log("nqui library built successfully\n");
+    } catch (error) {
+      console.error("Failed to build nqui library");
+      process.exit(1);
+    }
+  }
+
+  console.log("Linking nqui library globally...");
+  try {
+    execSync("npm link", { cwd: nquiDir, stdio: "inherit" });
+    console.log("nqui linked globally\n");
+  } catch (error) {
+    console.error("Failed to link nqui globally");
+    process.exit(1);
+  }
+
+  const nquiPackageJson = JSON.parse(readFileSync(nquiPackageJsonPath, "utf-8"));
+  packageJson.dependencies["@nqlib/nqui"] = `^${nquiPackageJson.version}`;
+  writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + "\n");
+  console.log("Updated package.json (version: ^" + nquiPackageJson.version + ")");
+
+  console.log("Linking @nqlib/nqui in " + PROJECT_NAME + "...");
+  try {
+    try {
+      execSync("npm unlink @nqlib/nqui", { cwd: root, stdio: "pipe" });
+    } catch {}
+
+    const linkEnv = USE_LEGACY_PEER_DEPS ? { ...process.env, NPM_CONFIG_LEGACY_PEER_DEPS: "true" } : process.env;
+    execSync("npm link @nqlib/nqui", { cwd: root, stdio: "inherit", env: linkEnv });
+    console.log("Linked @nqlib/nqui in " + PROJECT_NAME + "\n");
+  } catch (error) {
+    console.error("Failed to link @nqlib/nqui");
+    process.exit(1);
+  }
+
+  const finalStatus = checkStatus();
+  console.log("Successfully switched to LOCAL nqui");
+  console.log("   Using:", nquiDir);
+  console.log("   Version:", finalStatus.version);
+  console.log("   Symlink:", finalStatus.isLinked ? "Active" : "Not active", "\n");
+} else {
+  console.log("Unlinking local nqui...");
+  try {
+    execSync("npm unlink @nqlib/nqui", { cwd: root, stdio: "pipe" });
+    console.log("Unlinked local nqui\n");
+  } catch {
+    console.log("No local link to remove\n");
+  }
+
+  packageJson.dependencies["@nqlib/nqui"] = PUBLISHED_VERSION;
+  writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + "\n");
+  console.log("Updated package.json to published version (" + PUBLISHED_VERSION + ")");
+
+  console.log("Installing published @nqlib/nqui...");
+  const installCmd = USE_LEGACY_PEER_DEPS
+    ? `npm install @nqlib/nqui@${PUBLISHED_VERSION} --legacy-peer-deps`
+    : `npm install @nqlib/nqui@${PUBLISHED_VERSION}`;
+  try {
+    execSync(installCmd, { cwd: root, stdio: "inherit" });
+    console.log("Installed published @nqlib/nqui\n");
+  } catch (error) {
+    console.error("Failed to install published version. Run npm install manually.");
+  }
+
+  const finalStatus = checkStatus();
+  console.log("Successfully switched to PUBLISHED nqui");
+  console.log("   Version:", finalStatus.version);
+  console.log("   Symlink:", finalStatus.isLinked ? "Still linked (run npm install)" : "Removed", "\n");
+}

package/docs/nqui-skills/nqui-shadcn/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: nqui-shadcn
+description: Manages nqui components and projects — adding, searching, fixing, debugging, styling, and composing UI. nqui is a shadcn-inspired component library with enhanced components. Applies when working with @nqlib/nqui, component imports, or designing app UI with nqui components.
+user-invocable: false
+---
+
+# nqui
+
+A shadcn-inspired React component library built on Radix UI primitives with enhanced components. Components are imported directly from `@nqlib/nqui`.
+
+> **IMPORTANT:** Use the path alias `@/` when importing from nqui in projects that support it (e.g., Next.js with path aliases configured). Otherwise use `@nqlib/nqui`.
+
+## Principles
+
+1. **Use existing components first.** Check the component index before writing custom UI.
+2. **Compose, don't reinvent.** Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
+3. **Use built-in variants before custom styles.** `variant="outline"`, `size="sm"`, etc.
+4. **Use semantic colors.** `bg-primary`, `text-muted-foreground` — never raw values like `bg-blue-500`.
+
+## Core vs Enhanced
+
+nqui provides two versions of each component:
+
+- **Default (Enhanced)**: Animated, styled, feature-rich — use this by default
+- **Core***: Plain Radix-like, minimal styling — only when you explicitly need the base version
+
+```tsx
+// Default = Enhanced (animated, styled)
+import { Button, Checkbox, Badge } from "@nqlib/nqui"
+
+// Only use Core* when you explicitly want plain/base version
+import { CoreButton, CoreCheckbox, CoreBadge } from "@nqlib/nqui"
+```
+
+## Critical Rules
+
+These rules are **always enforced**. Each links to a file with Incorrect/Correct code pairs.
+
+### Styling & Tailwind → [styling.md](./rules/styling.md)
+
+- **`className` for layout, not styling.** Never override component colors or typography.
+- **No `space-x-*` or `space-y-*`.** Use `flex` with `gap-*`. For vertical stacks, `flex flex-col gap-*`.
+- **Use `size-*` when width and height are equal.** `size-10` not `w-10 h-10`.
+- **Use `truncate` shorthand.** Not `overflow-hidden text-ellipsis whitespace-nowrap`.
+- **No manual `dark:` color overrides.** Use semantic tokens (`bg-background`, `text-muted-foreground`).
+- **Use `cn()` for conditional classes.** Don't write manual template literal ternaries.
+- **No manual `z-index` on overlay components.** Use elevation.css variables — see [elevation.css](../../../src/styles/elevation.css).
+
+### Forms & Inputs → [forms.md](./rules/forms.md)
+
+- **Forms use `FieldGroup` + `Field`.** Never use raw `div` with `space-y-*` or `grid gap-*` for form layout.
+- **`InputGroup` uses `InputGroupInput`/`InputGroupTextarea`.** Never raw `Input`/`Textarea` inside `InputGroup`.
+- **Buttons inside inputs use `InputGroup` + `InputGroupAddon`.**
+- **Option sets (2–7 choices) use `ToggleGroup`.** Don't loop `Button` with manual active state.
+- **`FieldSet` + `FieldLegend` for grouping related checkboxes/radios.** Don't use a `div` with a heading.
+- **Field validation uses `data-invalid` + `aria-invalid`.** `data-invalid` on `Field`, `aria-invalid` on the control. For disabled: `data-disabled` on `Field`, `disabled` on the control.
+
+### Component Structure → [composition.md](./rules/composition.md)
+
+- **Items always inside their Group.** `SelectItem` → `SelectGroup`. `DropdownMenuItem` → `DropdownMenuGroup`. `CommandItem` → `CommandGroup`.
+- **Dialog, Sheet, and Drawer always need a Title.** `DialogTitle`, `SheetTitle`, `DrawerTitle` required for accessibility. Use `className="sr-only"` if visually hidden.
+- **Use full Card composition.** `CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`. Don't dump everything in `CardContent`.
+- **`TabsTrigger` must be inside `TabsList`.** Never render triggers directly in `Tabs`.
+- **`Avatar` always needs `AvatarFallback`.** For when the image fails to load.
+
+### Use Components, Not Custom Markup → [composition.md](./rules/composition.md)
+
+- **Use existing components before custom markup.** Check if a component exists before writing a styled `div`.
+- **Callouts use `Alert`.** Don't build custom styled divs.
+- **Empty states use `Empty`.** Don't build custom empty state markup.
+- **Toast via `sonner`.** Use `toast()` from `sonner`.
+- **Use `Separator`** instead of `<hr>` or `<div className="border-t">`.
+- **Use `Skeleton`** for loading placeholders. No custom `animate-pulse` divs.
+- **Use `Badge`** instead of custom styled spans.
+
+### Icons → [icons.md](./rules/icons.md)
+
+- **Icons in `Button` use `data-icon`.** `data-icon="inline-start"` or `data-icon="inline-end"` on the icon.
+- **No sizing classes on icons inside components.** Components handle icon sizing via CSS. No `size-4` or `w-4 h-4`.
+- **Use Hugeicons.** Import from `@hugeicons/react` or `@hugeicons/core-free-icons`.
+
+## Key Patterns
+
+```tsx
+// Form layout: FieldGroup + Field, not div + Label.
+<FieldGroup>
+  <Field>
+    <FieldLabel htmlFor="email">Email</FieldLabel>
+    <Input id="email" />
+  </Field>
+</FieldGroup>
+
+// Validation: data-invalid on Field, aria-invalid on the control.
+<Field data-invalid>
+  <FieldLabel>Email</FieldLabel>
+  <Input aria-invalid />
+  <FieldDescription>Invalid email.</FieldDescription>
+</Field>
+
+// Icons in buttons: data-icon, no sizing classes.
+<Button>
+  <SearchIcon data-icon="inline-start" />
+  Search
+</Button>
+
+// Spacing: gap-*, not space-y-*.
+<div className="flex flex-col gap-4">  // correct
+<div className="space-y-4">           // wrong
+
+// Equal dimensions: size-*, not w-* h-*.
+<Avatar className="size-10">   // correct
+<Avatar className="w-10 h-10"> // wrong
+
+// Status colors: Badge variants or semantic tokens, not raw colors.
+<Badge variant="secondary">+20.1%</Badge>    // correct
+<span className="text-emerald-600">+20.1%</span> // wrong
+```
+
+## Component Selection
+
+| Need                       | Use                                                                                                 |
+| -------------------------- | --------------------------------------------------------------------------------------------------- |
+| Button/action              | `Button` with appropriate variant                                                                   |
+| Form inputs                | `Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `Slider` |
+| Toggle between 2–5 options | `ToggleGroup` + `ToggleGroupItem`                                                                   |
+| Data display               | `Table`, `Card`, `Badge`, `Avatar`                                                                  |
+| Navigation                 | `Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination`                                     |
+| Overlays                   | `Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation)       |
+| Feedback                   | `sonner` (toast), `Alert`, `Progress`, `Skeleton`, `Spinner`                                        |
+| Command palette            | `Command` inside `Dialog`                                                                           |
+| Layout                     | `Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible`                          |
+| Empty states               | `Empty`                                                                                             |
+| Menus                      | `DropdownMenu`, `ContextMenu`, `Menubar`                                                            |
+| Tooltips/info              | `Tooltip`, `HoverCard`, `Popover`                                                                   |
+
+## Z-Index Elevation System
+
+nqui uses a centralized z-index system via CSS variables. **Never use hardcoded z-index values.**
+
+Reference: [elevation.css](../../../src/styles/elevation.css)
+
+```tsx
+// Use CSS variable z-index, not hardcoded numbers
+<div className="z-[var(--z-modal)]">      // correct
+<div className="z-50">                    // wrong
+<div className="z-[var(--z-popover)]">   // correct
+```
+
+## Quick Reference
+
+```tsx
+// Import all components from @nqlib/nqui
+import { Button, Card, Dialog, Input, ToggleGroup } from "@nqlib/nqui"
+
+// Or use path alias if configured
+import { Button, Card } from "@/components/ui/..."
+```
+
+## Detailed References
+
+- [rules/styling.md](./rules/styling.md) — Semantic colors, variants, className, spacing, size, truncate, dark mode, cn(), z-index
+- [rules/forms.md](./rules/forms.md) — FieldGroup, Field, InputGroup, ToggleGroup, FieldSet, validation states
+- [rules/composition.md](./rules/composition.md) — Groups, overlays, Card, Tabs, Avatar, Alert, Empty, Toast, Separator, Skeleton, Badge, Button loading
+- [rules/icons.md](./rules/icons.md) — data-icon, icon sizing, Hugeicons

package/docs/nqui-skills/{rules → nqui-shadcn/rules}/forms.md

@@ -140,8 +140,8 @@ Combine with `Field` for labelled toggle groups:
 <Field orientation="horizontal">
   <FieldTitle id="theme-label">Theme</FieldTitle>
   <ToggleGroup aria-labelledby="theme-label" spacing={2}>
-    <ToggleGroupItem value="light">Light</ToggleGroup<ToggleGroupItem valueItem>
-    ="dark">Dark</ToggleGroupItem>
+    <ToggleGroupItem value="light">Light</ToggleGroupItem>
+    <ToggleGroupItem value="dark">Dark</ToggleGroupItem>
     <ToggleGroupItem value="system">System</ToggleGroupItem>
   </ToggleGroup>
 </Field>
@@ -187,4 +187,4 @@ Both attributes are needed — `data-invalid`/`data-disabled` styles the field (
 </Field>
 ```
 
-Works for all controls: `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroupItem`, `Switch`, `Slider`.
+Works for all controls: `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroupItem`, `Switch`, `Slider`.

package/docs/nqui-skills/{rules → nqui-shadcn/rules}/styling.md

@@ -177,7 +177,7 @@ import { cn } from "@/lib/utils"
 </div>
 ```
 
-Reference: [elevation.css](../src/styles/elevation.css)
+Reference: [elevation.css](../../../../src/styles/elevation.css)
 
 | Variable | Value | Use Case |
 |----------|-------|----------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nqlib/nqui",
-  "version": "0.4.8",
+  "version": "0.5.1",
   "description": "A React component library with enhanced UI components and developer tools",
   "type": "module",
   "main": "./dist/nqui.cjs.js",

package/scripts/download-skills.js

@@ -4,7 +4,8 @@
  * 
  * Usage: npx @nqlib/nqui init-skills
  * 
- * Copies docs/nqui-skills to user's .cursor/nqui-skills
+ * Copies docs/nqui-skills → .cursor/nqui-skills
+ * Copies docs/components → .cursor/nqui-skills/components (per-component docs for offline/Cursor)
  * Creates AGENTS.md pointing to the skills
  */
 
@@ -15,6 +16,8 @@ import { resolveTargetDir } from './resolve-target-dir.js';
 
 const root = getPackageRoot();
 const skillsSource = join(root, 'docs', 'nqui-skills');
+const componentsSource = join(root, 'docs', 'components');
+const componentsDestName = 'components';
 
 function ensureDir(dir) {
   if (!existsSync(dir)) {
@@ -26,12 +29,14 @@ export async function downloadSkills({ force = true }) {
   const targetDir = resolveTargetDir(process.cwd());
   const cursorDir = join(targetDir, '.cursor');
   const skillsDest = join(cursorDir, 'nqui-skills');
+  const componentsDest = join(skillsDest, componentsDestName);
   const agentsFile = join(targetDir, 'AGENTS.md');
 
   // Create .cursor directory if needed
   ensureDir(cursorDir);
 
-  // Copy skills folder
+  // Copy skills folder (includes COMPONENTS_INDEX.md, nqui-*/SKILL.md, and a **nested** `components/`
+  // placeholder only if present in source; component markdown is copied from docs/components below)
   if (existsSync(skillsSource)) {
     if (existsSync(skillsDest) && !force) {
       console.log('⏭️  nqui-skills already exists. Use --force to overwrite.');
@@ -44,6 +49,18 @@ export async function downloadSkills({ force = true }) {
     return;
   }
 
+  // Per-component docs: same content as docs/components, nested under nqui-skills for one-tree copy
+  if (existsSync(componentsSource)) {
+    if (existsSync(componentsDest) && !force) {
+      console.log('⏭️  nqui-skills/components already exists. Use --force to overwrite.');
+    } else {
+      cpSync(componentsSource, componentsDest, { recursive: true });
+      console.log('✅ Copied component docs to:', componentsDest);
+    }
+  } else {
+    console.warn('⚠️  Source component docs not found:', componentsSource);
+  }
+
   // Create or update AGENTS.md
   const agentsContent = `# AGENTS.md
 
@@ -57,16 +74,19 @@ For component implementation and UI design with @nqlib/nqui, load skills from:
 .cursor/nqui-skills/SKILL.md
 \`\`\`
 
-The skills include:
-- Component implementation guide
-- Design system conventions (sizing, z-index)
-- ToggleGroup usage rules
-- App design patterns
+The skills include (under \`.cursor/nqui-skills/\`):
+- \`SKILL.md\` — hub / entry
+- \`HUMAN_GUIDE.md\` — task → docs (designers; forms, dashboard, navigation, states)
+- \`COMPONENTS_INDEX.md\` — **read first** for which \`nqui-*.md\` to open (token-efficient)
+- \`components/\` — per-component docs (same as \`node_modules/@nqlib/nqui/docs/components/\`)
+- \`nqui-components/\`, \`nqui-design-system/\`, \`nqui-shadcn/\` (with rules)
+- \`nqui-bundle-size-best-practices/\`, \`nqui-local-published-toggle/\`, \`nqui-install/\`
 
 ## How to Use
 
 When working with nqui components, AI assistants should load:
-- \`.cursor/nqui-skills/SKILL.md\` - main guide
+- \`.cursor/nqui-skills/SKILL.md\` — hub; open subfolders (e.g. \`nqui-shadcn/SKILL.md\`) by task
+- \`.cursor/nqui-skills/COMPONENTS_INDEX.md\` then **one** file under \`components/nqui-<name>.md\` — avoid loading all component docs or the full \`components/README.md\` unless needed
 
 ---
 

package/scripts/examples/nextjs-layout-sidebar.tsx

@@ -33,8 +33,9 @@ export default function RootLayout({
       <body>
         <ThemeProvider
           attribute="class"
-          defaultTheme="system"
-          enableSystem
+          defaultTheme="light"
+          enableSystem={false}
+          themes={["light", "dark"]}
           disableTransitionOnChange
         >
           <SidebarProvider defaultOpen>

package/scripts/examples/nextjs-layout.tsx

@@ -19,8 +19,9 @@ export default function RootLayout({
       <body>
         <ThemeProvider
           attribute="class"
-          defaultTheme="system"
-          enableSystem
+          defaultTheme="light"
+          enableSystem={false}
+          themes={["light", "dark"]}
           disableTransitionOnChange
         >
           {children}

package/scripts/examples/vite-main.tsx

@@ -8,7 +8,13 @@ import App from "./App";
 
 createRoot(document.getElementById("root")!).render(
   <StrictMode>
-    <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
+    <ThemeProvider
+      attribute="class"
+      defaultTheme="light"
+      enableSystem={false}
+      themes={["light", "dark"]}
+      disableTransitionOnChange
+    >
       <BrowserRouter>
         <App />
       </BrowserRouter>