@nqlib/nqui 0.4.1 → 0.4.2

package/dist/sonner-BtzU00r3.js

@@ -0,0 +1,248 @@
+import { jsx as o } from "react/jsx-runtime";
+import { Toaster as x } from "sonner";
+import { HugeiconsIcon as r } from "@hugeicons/react";
+import { Loading03Icon as b, MultiplicationSignCircleIcon as w, Alert02Icon as y, InformationCircleIcon as k, CheckmarkCircle02Icon as N } from "@hugeicons/core-free-icons";
+import * as d from "react";
+var C = (t, n, c, a, l, s, u, p) => {
+  let i = document.documentElement, g = ["light", "dark"];
+  function m(e) {
+    (Array.isArray(t) ? t : [t]).forEach((h) => {
+      let f = h === "class", T = f && s ? l.map((v) => s[v] || v) : l;
+      f ? (i.classList.remove(...T), i.classList.add(s && s[e] ? s[e] : e)) : i.setAttribute(h, e);
+    }), W(e);
+  }
+  function W(e) {
+    p && g.includes(e) && (i.style.colorScheme = e);
+  }
+  function z() {
+    return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  }
+  if (a) m(a);
+  else try {
+    let e = localStorage.getItem(n) || c, h = u && e === "system" ? z() : e;
+    m(h);
+  } catch {
+  }
+}, E = d.createContext(void 0), S = { setTheme: (t) => {
+}, themes: [] }, I = () => {
+  var t;
+  return (t = d.useContext(E)) != null ? t : S;
+};
+d.memo(({ forcedTheme: t, storageKey: n, attribute: c, enableSystem: a, enableColorScheme: l, defaultTheme: s, value: u, themes: p, nonce: i, scriptProps: g }) => {
+  let m = JSON.stringify([c, n, s, t, p, u, a, l]).slice(1, -1);
+  return d.createElement("script", { ...g, suppressHydrationWarning: !0, nonce: typeof window > "u" ? i : "", dangerouslySetInnerHTML: { __html: `(${C.toString()})(${m})` } });
+});
+const L = ({ ...t }) => {
+  const { theme: n = "system" } = I();
+  return d.useEffect(() => {
+    const c = "enhanced-toast-styles";
+    if (document.getElementById(c)) return;
+    const a = document.createElement("style");
+    a.id = c, a.textContent = `
+      /* Toast Base - Card-style design */
+      [data-sonner-toast] .enhanced-cn-toast {
+        border: 1px solid color-mix(in oklch, var(--border) 50%, transparent) !important;
+        box-shadow:
+          0 1px 0 0 color-mix(in oklch, var(--border) 40%, transparent),
+          0 1px 2px 0 oklch(0.15 0 0 / 0.05);
+        border-radius: var(--border-radius) !important;
+        transition: all 200ms ease-in-out !important;
+      }
+
+      .dark [data-sonner-toast] .enhanced-cn-toast {
+        box-shadow:
+          0 1px 0 0 color-mix(in oklch, var(--border) 40%, transparent),
+          0 1px 2px 0 oklch(0 0 0 / 0.3);
+      }
+
+      /* Success toast */
+      [data-sonner-toast] .enhanced-cn-toast.enhanced-toast-success {
+        border-left-width: 3px !important;
+        border-left-color: var(--success-500) !important;
+      }
+
+      /* Error toast */
+      [data-sonner-toast] .enhanced-cn-toast.enhanced-toast-error {
+        border-left-width: 3px !important;
+        border-left-color: var(--danger-500) !important;
+      }
+
+      /* Warning toast */
+      [data-sonner-toast] .enhanced-cn-toast.enhanced-toast-warning {
+        border-left-width: 3px !important;
+        border-left-color: var(--warning-500) !important;
+      }
+
+      /* Info toast */
+      [data-sonner-toast] .enhanced-cn-toast.enhanced-toast-info {
+        border-left-width: 3px !important;
+        border-left-color: var(--info-500) !important;
+      }
+
+      /* Loading toast */
+      [data-sonner-toast] .enhanced-cn-toast.enhanced-toast-loading {
+        border-left-width: 3px !important;
+        border-left-color: var(--primary-500) !important;
+      }
+
+      /* Icon colors */
+      .enhanced-cn-toast .toast-icon-success { color: var(--success); }
+      .enhanced-cn-toast .toast-icon-error { color: var(--destructive); }
+      .enhanced-cn-toast .toast-icon-warning { color: var(--warning); }
+      .enhanced-cn-toast .toast-icon-info { color: var(--info); }
+      .enhanced-cn-toast .toast-icon-loading { color: var(--primary); }
+    `, document.head.appendChild(a);
+  }, []), /* @__PURE__ */ o(
+    x,
+    {
+      theme: n,
+      className: "toaster group",
+      icons: {
+        success: /* @__PURE__ */ o(
+          r,
+          {
+            icon: N,
+            strokeWidth: 2,
+            className: "size-4 text-success toast-icon-success"
+          }
+        ),
+        info: /* @__PURE__ */ o(
+          r,
+          {
+            icon: k,
+            strokeWidth: 2,
+            className: "size-4 text-info toast-icon-info"
+          }
+        ),
+        warning: /* @__PURE__ */ o(
+          r,
+          {
+            icon: y,
+            strokeWidth: 2,
+            className: "size-4 text-warning toast-icon-warning"
+          }
+        ),
+        error: /* @__PURE__ */ o(
+          r,
+          {
+            icon: w,
+            strokeWidth: 2,
+            className: "size-4 text-destructive toast-icon-error"
+          }
+        ),
+        loading: /* @__PURE__ */ o(
+          r,
+          {
+            icon: b,
+            strokeWidth: 2,
+            className: "size-4 text-primary toast-icon-loading animate-spin"
+          }
+        )
+      },
+      style: {
+        "--normal-bg": "var(--popover)",
+        "--normal-text": "var(--popover-foreground)",
+        "--normal-border": "var(--border)",
+        "--border-radius": "var(--radius)"
+      },
+      toastOptions: {
+        classNames: {
+          toast: "enhanced-cn-toast",
+          success: "enhanced-toast-success",
+          error: "enhanced-toast-error",
+          warning: "enhanced-toast-warning",
+          info: "enhanced-toast-info",
+          loading: "enhanced-toast-loading"
+        }
+      },
+      ...t
+    }
+  );
+};
+L.displayName = "EnhancedToaster";
+const $ = ({ ...t }) => {
+  const { theme: n = "system" } = I();
+  return /* @__PURE__ */ o(
+    x,
+    {
+      theme: n,
+      className: "toaster group",
+      icons: {
+        success: /* @__PURE__ */ o(
+          r,
+          {
+            icon: N,
+            strokeWidth: 2,
+            className: "size-4 text-success toast-icon-success"
+          }
+        ),
+        info: /* @__PURE__ */ o(
+          r,
+          {
+            icon: k,
+            strokeWidth: 2,
+            className: "size-4 text-info toast-icon-info"
+          }
+        ),
+        warning: /* @__PURE__ */ o(
+          r,
+          {
+            icon: y,
+            strokeWidth: 2,
+            className: "size-4 text-warning toast-icon-warning"
+          }
+        ),
+        error: /* @__PURE__ */ o(
+          r,
+          {
+            icon: w,
+            strokeWidth: 2,
+            className: "size-4 text-destructive toast-icon-error"
+          }
+        ),
+        loading: /* @__PURE__ */ o(
+          r,
+          {
+            icon: b,
+            strokeWidth: 2,
+            className: "size-4 text-primary toast-icon-loading animate-spin"
+          }
+        )
+      },
+      style: {
+        "--normal-bg": "var(--popover)",
+        "--normal-text": "var(--popover-foreground)",
+        "--normal-border": "var(--border)",
+        "--border-radius": "var(--radius)",
+        "--success-bg": "var(--success)",
+        "--success-text": "var(--success-foreground)",
+        "--success-border": "var(--success-400)",
+        "--error-bg": "var(--destructive)",
+        "--error-text": "var(--destructive-foreground)",
+        "--error-border": "var(--danger-400)",
+        "--warning-bg": "var(--warning)",
+        "--warning-text": "var(--warning-foreground)",
+        "--warning-border": "var(--warning-400)",
+        "--info-bg": "var(--info)",
+        "--info-text": "var(--info-foreground)",
+        "--info-border": "var(--info-400)"
+      },
+      toastOptions: {
+        classNames: {
+          toast: "cn-toast",
+          success: "toast-success",
+          error: "toast-error",
+          warning: "toast-warning",
+          info: "toast-info",
+          loading: "toast-loading"
+        }
+      },
+      ...t
+    }
+  );
+};
+export {
+  L as E,
+  $ as T,
+  I as z
+};

package/dist/sonner-Dfk26eds.cjs

@@ -0,0 +1,54 @@
+"use strict";const o=require("react/jsx-runtime"),w=require("sonner"),a=require("@hugeicons/react"),c=require("@hugeicons/core-free-icons"),N=require("react");function C(e){const r=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(e){for(const n in e)if(n!=="default"){const s=Object.getOwnPropertyDescriptor(e,n);Object.defineProperty(r,n,s.get?s:{enumerable:!0,get:()=>e[n]})}}return r.default=e,Object.freeze(r)}const l=C(N);var z=(e,r,n,s,u,i,h,p)=>{let d=document.documentElement,f=["light","dark"];function m(t){(Array.isArray(e)?e:[e]).forEach(g=>{let x=g==="class",j=x&&i?u.map(b=>i[b]||b):u;x?(d.classList.remove(...j),d.classList.add(i&&i[t]?i[t]:t)):d.setAttribute(g,t)}),I(t)}function I(t){p&&f.includes(t)&&(d.style.colorScheme=t)}function k(){return window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light"}if(s)m(s);else try{let t=localStorage.getItem(r)||n,g=h&&t==="system"?k():t;m(g)}catch{}},S=l.createContext(void 0),T={setTheme:e=>{},themes:[]},v=()=>{var e;return(e=l.useContext(S))!=null?e:T};l.memo(({forcedTheme:e,storageKey:r,attribute:n,enableSystem:s,enableColorScheme:u,defaultTheme:i,value:h,themes:p,nonce:d,scriptProps:f})=>{let m=JSON.stringify([n,r,i,e,p,h,s,u]).slice(1,-1);return l.createElement("script",{...f,suppressHydrationWarning:!0,nonce:typeof window>"u"?d:"",dangerouslySetInnerHTML:{__html:`(${z.toString()})(${m})`}})});const y=({...e})=>{const{theme:r="system"}=v();return l.useEffect(()=>{const n="enhanced-toast-styles";if(document.getElementById(n))return;const s=document.createElement("style");s.id=n,s.textContent=`
+      /* Toast Base - Card-style design */
+      [data-sonner-toast] .enhanced-cn-toast {
+        border: 1px solid color-mix(in oklch, var(--border) 50%, transparent) !important;
+        box-shadow:
+          0 1px 0 0 color-mix(in oklch, var(--border) 40%, transparent),
+          0 1px 2px 0 oklch(0.15 0 0 / 0.05);
+        border-radius: var(--border-radius) !important;
+        transition: all 200ms ease-in-out !important;
+      }
+
+      .dark [data-sonner-toast] .enhanced-cn-toast {
+        box-shadow:
+          0 1px 0 0 color-mix(in oklch, var(--border) 40%, transparent),
+          0 1px 2px 0 oklch(0 0 0 / 0.3);
+      }
+
+      /* Success toast */
+      [data-sonner-toast] .enhanced-cn-toast.enhanced-toast-success {
+        border-left-width: 3px !important;
+        border-left-color: var(--success-500) !important;
+      }
+
+      /* Error toast */
+      [data-sonner-toast] .enhanced-cn-toast.enhanced-toast-error {
+        border-left-width: 3px !important;
+        border-left-color: var(--danger-500) !important;
+      }
+
+      /* Warning toast */
+      [data-sonner-toast] .enhanced-cn-toast.enhanced-toast-warning {
+        border-left-width: 3px !important;
+        border-left-color: var(--warning-500) !important;
+      }
+
+      /* Info toast */
+      [data-sonner-toast] .enhanced-cn-toast.enhanced-toast-info {
+        border-left-width: 3px !important;
+        border-left-color: var(--info-500) !important;
+      }
+
+      /* Loading toast */
+      [data-sonner-toast] .enhanced-cn-toast.enhanced-toast-loading {
+        border-left-width: 3px !important;
+        border-left-color: var(--primary-500) !important;
+      }
+
+      /* Icon colors */
+      .enhanced-cn-toast .toast-icon-success { color: var(--success); }
+      .enhanced-cn-toast .toast-icon-error { color: var(--destructive); }
+      .enhanced-cn-toast .toast-icon-warning { color: var(--warning); }
+      .enhanced-cn-toast .toast-icon-info { color: var(--info); }
+      .enhanced-cn-toast .toast-icon-loading { color: var(--primary); }
+    `,document.head.appendChild(s)},[]),o.jsx(w.Toaster,{theme:r,className:"toaster group",icons:{success:o.jsx(a.HugeiconsIcon,{icon:c.CheckmarkCircle02Icon,strokeWidth:2,className:"size-4 text-success toast-icon-success"}),info:o.jsx(a.HugeiconsIcon,{icon:c.InformationCircleIcon,strokeWidth:2,className:"size-4 text-info toast-icon-info"}),warning:o.jsx(a.HugeiconsIcon,{icon:c.Alert02Icon,strokeWidth:2,className:"size-4 text-warning toast-icon-warning"}),error:o.jsx(a.HugeiconsIcon,{icon:c.MultiplicationSignCircleIcon,strokeWidth:2,className:"size-4 text-destructive toast-icon-error"}),loading:o.jsx(a.HugeiconsIcon,{icon:c.Loading03Icon,strokeWidth:2,className:"size-4 text-primary toast-icon-loading animate-spin"})},style:{"--normal-bg":"var(--popover)","--normal-text":"var(--popover-foreground)","--normal-border":"var(--border)","--border-radius":"var(--radius)"},toastOptions:{classNames:{toast:"enhanced-cn-toast",success:"enhanced-toast-success",error:"enhanced-toast-error",warning:"enhanced-toast-warning",info:"enhanced-toast-info",loading:"enhanced-toast-loading"}},...e})};y.displayName="EnhancedToaster";const H=({...e})=>{const{theme:r="system"}=v();return o.jsx(w.Toaster,{theme:r,className:"toaster group",icons:{success:o.jsx(a.HugeiconsIcon,{icon:c.CheckmarkCircle02Icon,strokeWidth:2,className:"size-4 text-success toast-icon-success"}),info:o.jsx(a.HugeiconsIcon,{icon:c.InformationCircleIcon,strokeWidth:2,className:"size-4 text-info toast-icon-info"}),warning:o.jsx(a.HugeiconsIcon,{icon:c.Alert02Icon,strokeWidth:2,className:"size-4 text-warning toast-icon-warning"}),error:o.jsx(a.HugeiconsIcon,{icon:c.MultiplicationSignCircleIcon,strokeWidth:2,className:"size-4 text-destructive toast-icon-error"}),loading:o.jsx(a.HugeiconsIcon,{icon:c.Loading03Icon,strokeWidth:2,className:"size-4 text-primary toast-icon-loading animate-spin"})},style:{"--normal-bg":"var(--popover)","--normal-text":"var(--popover-foreground)","--normal-border":"var(--border)","--border-radius":"var(--radius)","--success-bg":"var(--success)","--success-text":"var(--success-foreground)","--success-border":"var(--success-400)","--error-bg":"var(--destructive)","--error-text":"var(--destructive-foreground)","--error-border":"var(--danger-400)","--warning-bg":"var(--warning)","--warning-text":"var(--warning-foreground)","--warning-border":"var(--warning-400)","--info-bg":"var(--info)","--info-text":"var(--info-foreground)","--info-border":"var(--info-400)"},toastOptions:{classNames:{toast:"cn-toast",success:"toast-success",error:"toast-error",warning:"toast-warning",info:"toast-info",loading:"toast-loading"}},...e})};exports.EnhancedToaster=y;exports.Toaster=H;exports.z=v;

package/dist/sonner.cjs.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./sonner-DbQhVp8m.cjs");exports.CoreToaster=e.Toaster;exports.EnhancedSonner=e.EnhancedToaster;exports.Toaster=e.EnhancedToaster;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./sonner-Dfk26eds.cjs");exports.CoreToaster=e.Toaster;exports.EnhancedSonner=e.EnhancedToaster;exports.Toaster=e.EnhancedToaster;

package/dist/sonner.es.js

@@ -1,4 +1,4 @@
-import { T as o, E as r, E as s } from "./sonner-Co6YpYVs.js";
+import { T as o, E as r, E as s } from "./sonner-BtzU00r3.js";
 export {
   o as CoreToaster,
   r as EnhancedSonner,

package/dist/styles.css

@@ -541,6 +541,7 @@
     position: absolute;
     z-index: 0;
     pointer-events: none;
+    overflow: visible;
     transition:
       left 0.3s ease-in-out,
       top 0.3s ease-in-out,
@@ -550,6 +551,8 @@
 
   .sliding-indicator-container {
     position: relative;
+    overflow: hidden;
+    min-width: 0;
   }
 
   .sliding-indicator-target {

package/docs/components/README.md

@@ -17,7 +17,7 @@ Implementation guides for each component. **AI Skill:** Optimized for AI/LLM con
 | Dependency | Version | Notes |
 |------------|---------|-------|
 | **React** | 18+ or 19 | nqui supports React 18 and 19 via `^18.0.0 \|\| ^19.0.0` peer. |
-| **Tailwind CSS** | ^4.x | Required. Vite: `@tailwindcss/vite`. Next.js: `@source` directives in CSS. |
+| **Tailwind CSS** | ^4.x | Required. Vite: `@tailwindcss/vite`. Both Vite and Next.js need `@source` for `node_modules/@nqlib/nqui/dist` (Tailwind does not scan node_modules). |
 | **tw-animate-css** | — | `@import "tw-animate-css"` in your CSS (added by init-css). |
 | **Radix UI** | — | Bundled (Dialog, Select, etc.). |
 | **Hugeicons** | @hugeicons/react, @hugeicons/core-free-icons | Required for icon display in components. |
@@ -41,6 +41,104 @@ Implementation guides for each component. **AI Skill:** Optimized for AI/LLM con
 
 ---
 
+## Layout & Scroll Patterns
+
+This section documents the CSS patterns used in the showcase app to ensure proper scroll behavior and prevent sticky element issues.
+
+### Sticky Elements & Momentum Scroll
+
+**The problem:** When using default body scroll, sticky elements can exhibit "momentum push" behavior during fast scrolling - they appear to float or lag before snapping back. This happens because sticky positioning is relative to the viewport, not the scroll container.
+
+**The solution:** Use a custom scroll container instead of body/html scroll.
+
+```tsx
+// App layout structure - prevents momentum push on sticky elements
+<div className="h-screen overflow-hidden">
+  <header className="sticky top-0 z-[var(--z-sticky-page)]">
+    {/* Page header */}
+  </header>
+  <main className="flex-1 min-h-0 overflow-y-auto">
+    {/* Scrollable content */}
+  </main>
+</div>
+```
+
+### Z-Index Layering for Sticky Elements
+
+Use the correct z-index variables to prevent sticky element conflicts:
+
+| Element | CSS Variable | Value |
+|---------|-------------|-------|
+| Page headers, navigation bars | `z-[var(--z-sticky-page)]` | 20 |
+| Card headers, table headers | `z-[var(--z-sticky-content)]` | 15 |
+
+**Rule:** Page-level sticky elements (20) must be above container-level sticky elements (15) to prevent scroll conflicts.
+
+### Flex Scroll Pattern
+
+For nested scrolling to work correctly, flex children must have `min-height: 0` (or `min-h-0` in Tailwind):
+
+```tsx
+// Correct - flex child can shrink and scroll
+<div className="flex flex-col h-screen">
+  <header className="flex-shrink-0">...</header>
+  <main className="flex-1 min-h-0 overflow-y-auto">
+    {/* This will scroll */}
+  </main>
+</div>
+
+// Wrong - flex child cannot shrink below content height
+<div className="flex flex-col h-screen">
+  <header>...</header>
+  <main className="flex-1 overflow-y-auto">
+    {/* May not scroll - overflows instead */}
+  </main>
+</div>
+```
+
+### Body Scroll Prevention
+
+For app-like experiences, disable body/html scroll:
+
+```tsx
+useEffect(() => {
+  // Disable browser scroll restoration
+  if ('scrollRestoration' in history) {
+    history.scrollRestoration = 'manual'
+  }
+
+  // Prevent body/html from scrolling
+  document.body.style.overflow = 'hidden'
+  document.documentElement.style.overflow = 'hidden'
+
+  return () => {
+    document.body.style.overflow = ''
+    document.documentElement.style.overflow = ''
+  }
+}, [])
+```
+
+### Sliding Indicator Containers
+
+Components with sliding indicators (Tabs, RadioGroup `sliding` variant) need specific container styling:
+
+```tsx
+// Required CSS for sliding indicator containers
+.sliding-indicator-container {
+  position: relative;
+  overflow: hidden;
+  min-width: 0;
+}
+
+.sliding-indicator {
+  position: absolute;
+  overflow: visible;
+  /* transitions for smooth sliding */
+}
+```
+
+---
+
 ## When to Use (Selection & Action Components)
 
 Use these rules to choose the right component. **Selection** = user picks from options. **Action** = user triggers a command.

package/docs/components/nqui-card.md

@@ -29,3 +29,10 @@ import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter }
   <CardContent>Scrollable content</CardContent>
 </Card>
 ```
+
+## Notes
+
+- **stickyHeader:** Use `stickyHeader` prop on Card for scrollable content with sticky header. The header uses `--z-sticky-content` (z-index: 15).
+- **Z-index layering:** Card sticky headers (15) are below page headers (20). If using in a page with sticky header, ensure proper z-index layering.
+- **Height required:** Card needs a defined height (e.g., `h-[400px]` or `h-full`) for sticky behavior to work.
+- **Content scroll:** The CardContent becomes scrollable when Card has `stickyHeader` and a defined height.

package/docs/components/nqui-checkbox.md

@@ -11,9 +11,31 @@ import { Checkbox } from "@nqlib/nqui"
 ## Basic
 
 ```tsx
-<Checkbox checked={checked} onCheckedChange={setChecked} />
+const [checked, setChecked] = useState(false)
+
+<Checkbox checked={checked} onCheckedChange={setChecked}>Accept terms</Checkbox>
+```
+
+## With Label
+
+Checkbox automatically wraps in a label when children are provided:
+
+```tsx
+<Checkbox>Accept terms</Checkbox>
 ```
 
+## Gap
+
+Control the gap between checkbox and label:
+
+```tsx
+<Checkbox gap={2}>Compact gap (8px)</Checkbox>
+<Checkbox gap={3}>Default gap (12px)</Checkbox>
+<Checkbox gap={4}>Loose gap (16px)</Checkbox>
+```
+
+Options: `0`, `1`, `2`, `3`, `4` (maps to Tailwind gap-0 through gap-4).
+
 ## Variants
 
 ```tsx

package/docs/components/nqui-radio-group.md

@@ -18,13 +18,56 @@ import { RadioGroup, RadioGroupItem } from "@nqlib/nqui"
 
 ## Basic
 
+RadioGroupItem now automatically wraps the radio button with a label when children are provided:
+
 ```tsx
+const [value, setValue] = useState("a")
+
 <RadioGroup value={value} onValueChange={setValue}>
-  <RadioGroupItem value="a" /> A
-  <RadioGroupItem value="b" /> B
+  <RadioGroupItem value="a">Option A</RadioGroupItem>
+  <RadioGroupItem value="b">Option B</RadioGroupItem>
 </RadioGroup>
 ```
 
+## With Complex Content
+
+```tsx
+<RadioGroup value={value} onValueChange={setValue}>
+  <RadioGroupItem value="email">
+    <div>
+      <div className="font-medium">Email</div>
+      <div className="text-sm text-muted-foreground">Receive notifications via email</div>
+    </div>
+  </RadioGroupItem>
+  <RadioGroupItem value="sms">
+    <div>
+      <div className="font-medium">SMS</div>
+      <div className="text-sm text-muted-foreground">Receive notifications via SMS</div>
+    </div>
+  </RadioGroupItem>
+</RadioGroup>
+```
+
+## Spacing
+
+Control the gap between radio items with the `gap` prop on RadioGroup:
+
+```tsx
+<RadioGroup gap={0}>No gap</RadioGroup>
+<RadioGroup gap={1}>4px gap</RadioGroup>
+<RadioGroup gap={2}>Compact (8px)</RadioGroup>
+<RadioGroup gap={3}>Default (12px)</RadioGroup>
+<RadioGroup gap={4}>Loose (16px)</RadioGroup>
+```
+
+Control the gap between radio button and label with the `spacing` prop on RadioGroupItem:
+
+```tsx
+<RadioGroupItem value="a" spacing="compact">Tight spacing (8px)</RadioGroupItem>
+<RadioGroupItem value="b" spacing="default">Default spacing (12px)</RadioGroupItem>
+<RadioGroupItem value="c" spacing="comfortable">Loose spacing (16px)</RadioGroupItem>
+```
+
 ## Variants
 
 ```tsx

package/docs/components/nqui-tabs.md

@@ -31,5 +31,15 @@ import { Tabs, TabsList, TabsTrigger, TabsContent } from "@nqlib/nqui"
 
 ## Notes
 
-- Sliding indicator needs `position: relative` on TabsList container.
+- **Sliding indicator:** Requires `position: relative` on TabsList container (handled automatically by the component).
+- **Responsive behavior:** On small screens, TabsList can overflow horizontally. Use `overflow-x-auto` on parent if needed.
+- **Container requirements:** For the sliding indicator to work correctly, the TabsList container needs:
+  ```css
+  .sliding-indicator-container {
+    position: relative;
+    overflow: hidden;
+    min-width: 0;
+  }
+  ```
+- **Resize handling:** The indicator recalculates position on window resize (built-in).
 - Use `EnhancedTabsList` props for additional customization.

package/docs/nqui-skills/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: nqui Components
+description: Component implementation guide for nqui. Use when building UI, designing app layouts, or implementing components with @nqlib/nqui.
+---
+
+# nqui Components Guide
+
+Reference `packages/nqui/docs/components/README.md` for the full component index and implementation rules.
+
+## Quick Reference
+
+1. **Main index:** `packages/nqui/docs/components/README.md` - all components, use cases, prerequisites
+2. **Per-component:** `packages/nqui/docs/components/nqui-<name>.md` - import, examples, variants
+3. **Design system:** this folder - sizing, grouped controls
+
+## App Design Rule: Inline Selection → ToggleGroup
+
+When designing app UI (toolbars, headers, inline controls):
+
+| Context | Use | NOT |
+|---------|-----|-----|
+| View mode (List/Grid/Table), scale (Linear/Log), size (S/M/L) | **ToggleGroup** `type="single"` | RadioGroup |
+| Format toolbar (Bold/Italic/Underline), multi-toggle | **ToggleGroup** `type="multiple"` | Multiple Checkboxes |
+| Toolbar actions (Undo/Redo, align) | **ButtonGroup** | - |
+| Single on/off (Bold, Mute) | **Toggle** | - |
+
+**Rule:** Inline/toolbar selection = ToggleGroup. Use RadioGroup only for form context (settings page, modal form, stacked list).
+
+## App Design Rule: Context-First (Toolbar in Real Environment)
+
+**Rule:** Never show Toggle/ToggleGroup/ButtonGroup in isolation. Always place them in realistic app context.
+
+| Context | Layout | Reference |
+|---------|--------|-----------|
+| Document editor | Toolbar above content; `bg-muted/30` container; `Separator` between groups | ComponentShowcase → Toggle & ToggleGroup |
+| Chart/settings | Label + inline controls; `rounded-lg border bg-muted/30 p-3` | ComponentShowcase → Chart settings |
+| Standalone | Inline with related UI | ComponentShowcase → Standalone toggle |
+
+**Canonical implementation:** `packages/nqui/src/pages/ComponentShowcase.tsx` — Toggle & ToggleGroup section.
+
+## Design System Conventions
+
+### Control Sizing
+- sm = h-6
+- default = h-7
+- lg = h-8
+
+### Z-Index
+Always use CSS variables from elevation.css:
+- `--z-content` (10) - standard content
+- `--z-sticky-content` (15) - sticky within containers
+- `--z-sticky-page` (20) - page-level sticky
+- `--z-floating` (30) - floating panels
+- `--z-modal-backdrop` (40)
+- `--z-modal` (50)
+- `--z-popover` (60)
+- `--z-tooltip` (70)
+
+### Component Naming
+- Enhanced vs Core: default is enhanced; use Core* for plain
+- File names: kebab-case
+- Component names: PascalCase
+
+## Key Dependencies
+
+Required peer dependencies:
+- `@hugeicons/react`
+- `@hugeicons/core-free-icons`
+
+Optional:
+- `next-themes` - for theme toggle
+- `tw-animate-css` - for animations
+
+## Installation & Setup
+
+```bash
+# Quick setup
+npx @nqlib/nqui init-css
+
+# App setup with sidebar
+npx @nqlib/nqui init-css --sidebar
+
+# Install peer dependencies
+npx @nqlib/nqui install-peers
+```
+
+## CSS Variables
+
+All components use CSS variables. Key ones:
+- `--background`, `--foreground`
+- `--muted`, `--muted-foreground`
+- `--accent`, `--accent-foreground`
+- `--border`, `--ring`
+- `--primary`, `--primary-foreground`
+- `--destructive`, `--destructive-foreground`