@nqlib/nqui 0.4.8 → 0.5.1

package/dist/{sonner-CpmECDBk.js → sonner-C1ndgVQY.js}

@@ -1,36 +1,36 @@
 import { jsx as a } from "react/jsx-runtime";
-import * as i from "react";
+import * as c from "react";
 import { Toaster as T } from "sonner";
-import { HugeiconsIcon as s } from "@hugeicons/react";
+import { HugeiconsIcon as i } from "@hugeicons/react";
 import { Loading03Icon as S, MultiplicationSignCircleIcon as I, Alert02Icon as E, InformationCircleIcon as C, CheckmarkCircle02Icon as N } from "@hugeicons/core-free-icons";
-var z = (t, n, p, c, l, r, u, f) => {
+var z = (t, n, s, l, d, r, u, f) => {
   let e = document.documentElement, g = ["light", "dark"];
-  function d(o) {
-    (Array.isArray(t) ? t : [t]).forEach((m) => {
-      let v = m === "class", k = v && r ? l.map((x) => r[x] || x) : l;
-      v ? (e.classList.remove(...k), e.classList.add(r && r[o] ? r[o] : o)) : e.setAttribute(m, o);
+  function m(o) {
+    (Array.isArray(t) ? t : [t]).forEach((p) => {
+      let v = p === "class", y = v && r ? d.map((x) => r[x] || x) : d;
+      v ? (e.classList.remove(...y), e.classList.add(r && r[o] ? r[o] : o)) : e.setAttribute(p, o);
     }), w(o);
   }
   function w(o) {
     f && g.includes(o) && (e.style.colorScheme = o);
   }
-  function y() {
+  function k() {
     return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
   }
-  if (c) d(c);
+  if (l) m(l);
   else try {
-    let o = localStorage.getItem(n) || p, m = u && o === "system" ? y() : o;
-    d(m);
+    let o = localStorage.getItem(n) || s, p = u && o === "system" ? k() : o;
+    m(p);
   } catch {
   }
-}, W = i.createContext(void 0), A = { setTheme: (t) => {
+}, W = c.createContext(void 0), A = { setTheme: (t) => {
 }, themes: [] }, L = () => {
   var t;
-  return (t = i.useContext(W)) != null ? t : A;
+  return (t = c.useContext(W)) != null ? t : A;
 };
-i.memo(({ forcedTheme: t, storageKey: n, attribute: p, enableSystem: c, enableColorScheme: l, defaultTheme: r, value: u, themes: f, nonce: e, scriptProps: g }) => {
-  let d = JSON.stringify([p, n, r, t, f, u, c, l]).slice(1, -1);
-  return i.createElement("script", { ...g, suppressHydrationWarning: !0, nonce: typeof window > "u" ? e : "", dangerouslySetInnerHTML: { __html: `(${z.toString()})(${d})` } });
+c.memo(({ forcedTheme: t, storageKey: n, attribute: s, enableSystem: l, enableColorScheme: d, defaultTheme: r, value: u, themes: f, nonce: e, scriptProps: g }) => {
+  let m = JSON.stringify([s, n, r, t, f, u, l, d]).slice(1, -1);
+  return c.createElement("script", { ...g, suppressHydrationWarning: !0, nonce: typeof window > "u" ? e : "", dangerouslySetInnerHTML: { __html: `(${z.toString()})(${m})` } });
 });
 const b = "nqui-toast-styles-v2";
 function M() {
@@ -86,17 +86,17 @@ function M() {
     `, document.head.appendChild(t);
 }
 const h = ({ ...t }) => {
-  const { theme: n = "system" } = L();
-  return i.useEffect(() => {
+  const { theme: n = "light" } = L(), s = n === "dark" ? "dark" : "light";
+  return c.useEffect(() => {
     M();
   }, []), /* @__PURE__ */ a(
     T,
     {
-      theme: n,
+      theme: s,
       className: "toaster group",
       icons: {
         success: /* @__PURE__ */ a(
-          s,
+          i,
           {
             icon: N,
             strokeWidth: 2,
@@ -104,7 +104,7 @@ const h = ({ ...t }) => {
           }
         ),
         info: /* @__PURE__ */ a(
-          s,
+          i,
           {
             icon: C,
             strokeWidth: 2,
@@ -112,7 +112,7 @@ const h = ({ ...t }) => {
           }
         ),
         warning: /* @__PURE__ */ a(
-          s,
+          i,
           {
             icon: E,
             strokeWidth: 2,
@@ -120,7 +120,7 @@ const h = ({ ...t }) => {
           }
         ),
         error: /* @__PURE__ */ a(
-          s,
+          i,
           {
             icon: I,
             strokeWidth: 2,
@@ -128,7 +128,7 @@ const h = ({ ...t }) => {
           }
         ),
         loading: /* @__PURE__ */ a(
-          s,
+          i,
           {
             icon: S,
             strokeWidth: 2,

package/dist/sonner-CP8np0BP.cjs

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

package/dist/sonner.cjs.js

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

package/dist/sonner.es.js

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

package/dist/styles.css

@@ -37,13 +37,13 @@
 @source inline("border border-primary border-secondary border-destructive border-success border-warning border-info border-border border-input border-ring rounded-md rounded-lg rounded-full");
 
 /* Background color utilities */
-@source inline("bg-primary bg-secondary bg-destructive bg-success bg-warning bg-info bg-background bg-accent bg-transparent bg-none bg-muted bg-input bg-input/20 dark:bg-input/30 mid:bg-input/30");
+@source inline("bg-primary bg-secondary bg-destructive bg-success bg-warning bg-info bg-background bg-accent bg-transparent bg-none bg-muted bg-input bg-input/20 dark:bg-input/30 light:bg-input/30");
 
 /* Text color utilities */
 @source inline("text-primary-foreground text-secondary-foreground text-destructive-foreground text-success-foreground text-warning-foreground text-info-foreground text-accent-foreground text-muted-foreground text-foreground");
 
 /* Hover state utilities */
-@source inline("hover:opacity-100 hover:bg-primary/90 hover:bg-secondary/90 hover:bg-destructive/90 hover:bg-success/90 hover:bg-warning/90 hover:bg-info/90 hover:bg-accent hover:bg-muted hover:border-primary/90 hover:border-secondary/90 hover:border-destructive/90 hover:border-success/90 hover:border-warning/90 hover:border-info/90 hover:border-border hover:text-accent-foreground hover:text-muted-foreground hover:underline dark:hover:bg-muted/50 mid:hover:bg-muted/50");
+@source inline("hover:opacity-100 hover:bg-primary/90 hover:bg-secondary/90 hover:bg-destructive/90 hover:bg-success/90 hover:bg-warning/90 hover:bg-info/90 hover:bg-accent hover:bg-muted hover:border-primary/90 hover:border-secondary/90 hover:border-destructive/90 hover:border-success/90 hover:border-warning/90 hover:border-info/90 hover:border-border hover:text-accent-foreground hover:text-muted-foreground hover:underline dark:hover:bg-muted/50 light:hover:bg-muted/50");
 
 /* Focus state utilities */
 @source inline("focus:bg-primary/80 focus:bg-secondary/80 focus:bg-destructive/80 focus:bg-success/80 focus:bg-warning/80 focus:bg-info/80 focus:border-primary/80 focus:border-secondary/80 focus:border-destructive/80 focus:border-success/80 focus:border-warning/80 focus:border-info/80 focus:border-border focus:outline-0 focus-visible:outline-0 focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]");
@@ -64,7 +64,7 @@
 @source inline("[&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 [&>svg]:size-2.5");
 
 /* Group & State utilities */
-@source inline("group/badge has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 mid:aria-invalid:ring-destructive/40 aria-invalid:border-destructive");
+@source inline("group/badge has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 light:aria-invalid:ring-destructive/40 aria-invalid:border-destructive");
 
 /* Z-index elevation utilities */
 @source inline("z-[var(--z-debug)] z-[var(--z-sticky-page)] z-[var(--z-background)] z-[var(--z-content)] z-[var(--z-popover)] z-[var(--z-modal-backdrop)] z-[var(--z-modal)] z-[var(--z-tooltip)] z-[var(--z-sticky-content)] z-[var(--z-floating)]");
@@ -75,7 +75,7 @@
 
 
 /* Custom dark mode variant - matches when .dark class is on element or ancestor */
-/* Mid theme (warm paper) — matches when .mid class is on element or ancestor; palette from mind-canvas */
+/* Non-dark themes — .light (warm paper) and .mid (dimmer neutral); both use light: utilities */
 /* Hit-area — https://bazza.dev/craft/2026/hit-area */
 /* Bazza hit-area utilities — https://bazza.dev/craft/2026/hit-area */
 
@@ -784,10 +784,14 @@
    nqui Additional System Variables
    ============================================ */
 
-/* ============================================
+/*
+ * Non-dark surfaces: /* ============================================
    nqui Color System & Design Tokens
    ============================================ */
 
+:root + html.light = warm paper; html.mid = separate token block (showcase / comparison).
+ * Dark = .dark. Showcase app uses next-themes classes light | mid | dark.
+ */
 :root {
     /* ============================================
        Z-Index Elevation Scale
@@ -948,21 +952,16 @@
     --z-debug: 9999;
 
     /* Color system variables from colors.css */
-    /* ============================================
-       Primary Color Scale - Light Mode
-       Blue Theme (Hue 240)
-       ============================================ */
-
-    /* Primary Color Scale (Light Mode) - Blue Theme (Hue 240) */
-    --primary-100: oklch(0.95 0.08 240);
-    --primary-200: oklch(0.90 0.10 240);
-    --primary-300: oklch(0.85 0.12 240);
-    --primary-400: oklch(0.80 0.14 240);
-    --primary-500: oklch(0.60 0.25 240); /* Main primary - darker for light mode */
-    --primary-600: oklch(0.50 0.28 240);
+    /* Primary scale — midpoint between classic light and dark (blue hue 240) */
+    --primary-100: oklch(0.675 0.115 240);
+    --primary-200: oklch(0.675 0.14 240);
+    --primary-300: oklch(0.675 0.16 240);
+    --primary-400: oklch(0.675 0.18 240);
+    --primary-500: oklch(0.625 0.225 240);
+    --primary-600: oklch(0.6 0.25 240);
 
     /* ============================================
-       Semantic Color Scales - Light Mode
+       Semantic Color Scales — classic light (success / warning / danger / info)
        ============================================ */
 
     /* Success Color Scale (Light Mode) - Green (Hue 142) */
@@ -998,16 +997,14 @@
     --info-600: oklch(0.50 0.18 200);
 
     /* ============================================
-       System Color Mappings - Light Mode
+       System Color Mappings — system default uses primary scale + light semantic scales
        ============================================ */
 
-    /* Primary Colors - Mapped to color scales */
     --primary: var(--primary-500);
-    --primary-foreground: oklch(0.98 0 0); /* Light text for contrast */
+    --primary-foreground: oklch(0.98 0 0);
     --primary-hover: var(--primary-400);
-    --ring: var(--primary-500); /* Focus ring uses primary color */
+    --ring: var(--primary-500);
 
-    /* Semantic Colors - Mapped to color scales */
     --success: var(--success-500);
     --success-foreground: oklch(0.98 0 0);
 
@@ -1021,21 +1018,21 @@
     --info-foreground: oklch(0.98 0 0);
 
     /* Additional variables from index.css */
-    /* System UI colors (unique to index.css) */
-    --background: oklch(1 0 0);
-    --foreground: oklch(0.145 0 0);
-    --card: oklch(0.98 0 0);
-    --card-foreground: oklch(0.145 0 0);
-    --popover: oklch(1 0 0);
-    --popover-foreground: oklch(0.145 0 0);
-    --secondary: oklch(0.967 0.001 286.375);
-    --secondary-foreground: oklch(0.21 0.006 285.885);
-    --muted: oklch(0.95 0 0);
-    --muted-foreground: oklch(0.556 0 0);
-    --accent: oklch(0.96 0 0);
-    --accent-foreground: oklch(0.205 0 0);
-    --border: oklch(0.922 0 0);
-    --input: oklch(0.922 0 0);
+    /* Light / system UI — warm paper */
+    --background: oklch(0.985 0.002 78);
+    --foreground: oklch(0.2416 0.0219 57);
+    --card: oklch(0.9792 0.0042 78.3);
+    --card-foreground: oklch(0.2416 0.0219 57);
+    --popover: oklch(0.9792 0.0042 78.3);
+    --popover-foreground: oklch(0.2416 0.0219 57);
+    --secondary: oklch(0.927 0.009 73.15);
+    --secondary-foreground: oklch(0.3067 0.0309 56.81);
+    --muted: oklch(0.9111 0.0082 73.15);
+    --muted-foreground: oklch(0.5576 0.0222 57.81);
+    --accent: oklch(0.935 0.011 73.15);
+    --accent-foreground: oklch(0.2416 0.0219 57);
+    --border: oklch(0.89 0.0137 73.1);
+    --input: oklch(0.89 0.0137 73.1);
 
     /* Chart colors */
     --chart-1: oklch(0.809 0.105 251.813);
@@ -1048,14 +1045,49 @@
     --radius: 0.45rem;
 
     /* Sidebar */
-    --sidebar: oklch(0.98 0 0);
-    --sidebar-foreground: oklch(0.145 0 0);
+    --sidebar: oklch(0.9792 0.0042 78.3);
+    --sidebar-foreground: oklch(0.2416 0.0219 57);
     --sidebar-primary: var(--primary);
     --sidebar-primary-foreground: var(--primary-foreground);
-    --sidebar-accent: oklch(0.96 0 0);
-    --sidebar-accent-foreground: oklch(0.205 0 0);
-    --sidebar-border: oklch(0.922 0 0);
-    --sidebar-ring: oklch(0.708 0 0);
+    --sidebar-accent: oklch(0.96 0.004 75);
+    --sidebar-accent-foreground: oklch(0.205 0.015 55);
+    --sidebar-border: oklch(0.89 0.0137 73.1);
+    --sidebar-ring: var(--ring);
+}
+
+/* Mid — between warm paper and dark (neutral, slightly dimmer than light) */
+.mid {
+    --background: oklch(0.915 0.01 78);
+    --foreground: oklch(0.28 0.022 57);
+    --card: oklch(0.895 0.012 78);
+    --card-foreground: oklch(0.28 0.022 57);
+    --popover: oklch(0.895 0.012 78);
+    --popover-foreground: oklch(0.28 0.022 57);
+    --secondary: oklch(0.88 0.012 73);
+    --secondary-foreground: oklch(0.32 0.028 57);
+    --muted: oklch(0.855 0.012 73);
+    --muted-foreground: oklch(0.48 0.024 58);
+    --accent: oklch(0.87 0.014 73);
+    --accent-foreground: oklch(0.28 0.022 57);
+    --border: oklch(0.82 0.016 73);
+    --input: oklch(0.82 0.016 73);
+
+    --chart-1: oklch(0.809 0.105 251.813);
+    --chart-2: oklch(0.623 0.214 259.815);
+    --chart-3: oklch(0.546 0.245 262.881);
+    --chart-4: oklch(0.488 0.243 264.376);
+    --chart-5: oklch(0.424 0.199 265.638);
+
+    --radius: 0.45rem;
+
+    --sidebar: oklch(0.9 0.01 78);
+    --sidebar-foreground: oklch(0.28 0.022 57);
+    --sidebar-primary: var(--primary);
+    --sidebar-primary-foreground: var(--primary-foreground);
+    --sidebar-accent: oklch(0.875 0.012 75);
+    --sidebar-accent-foreground: oklch(0.26 0.018 55);
+    --sidebar-border: oklch(0.82 0.016 73);
+    --sidebar-ring: var(--ring);
 }
 
 .dark {
@@ -1168,43 +1200,6 @@
 }
 
 /*
- * Mid theme — light-mode layout (same token roles as :root), with warm paper chroma
- * (mind-canvas–inspired oklch). Use class="mid" on <html> or an ancestor; do not
- * combine with .dark on the same root. Destructive/success/warning/info come from
- * colors.css like default light.
- */
-.mid {
-    /* Surfaces: parallel to :root — slightly lower L and mild hue vs neutral light */
-    --background: oklch(0.9574 0.0081 73.16);
-    --foreground: oklch(0.2416 0.0219 57);
-    --card: oklch(0.9792 0.0042 78.3);
-    --card-foreground: oklch(0.2416 0.0219 57);
-    --popover: oklch(0.9792 0.0042 78.3);
-    --popover-foreground: oklch(0.2416 0.0219 57);
-    --secondary: oklch(0.927 0.009 73.15);
-    --secondary-foreground: oklch(0.3067 0.0309 56.81);
-    --muted: oklch(0.9111 0.0082 73.15);
-    --muted-foreground: oklch(0.5576 0.0222 57.81);
-    /* Hover/focus wash (menus, ghost buttons) — high L like :root accent, not a filled control */
-    --accent: oklch(0.935 0.011 73.15);
-    --accent-foreground: oklch(0.2416 0.0219 57);
-    --border: oklch(0.89 0.0137 73.1);
-    --input: oklch(0.89 0.0137 73.1);
-
-    /* Charts: same as light (:root) */
-    --chart-1: oklch(0.809 0.105 251.813);
-    --chart-2: oklch(0.623 0.214 259.815);
-    --chart-3: oklch(0.546 0.245 262.881);
-    --chart-4: oklch(0.488 0.243 264.376);
-    --chart-5: oklch(0.424 0.199 265.638);
-
-    /* Sidebar: same structure as :root (light) — primary via semantic tokens, ring follows focus */
-    --sidebar: oklch(0.985 0.002 78);
-    --sidebar-foreground: oklch(0.2416 0.0219 57);
-    --sidebar-primary: var(--primary);
-    --sidebar-primary-foreground: var(--primary-foreground);
-    --sidebar-accent: oklch(0.96 0.004 75);
-    --sidebar-accent-foreground: oklch(0.205 0.015 55);
-    --sidebar-border: oklch(0.89 0.0137 73.1);
-    --sidebar-ring: var(--ring);
-}
+ * html.light — next-themes; surface tokens match :root (warm paper).
+ * html.mid — next-themes; surfaces use .mid block above (distinct from light).
+ */

package/docs/components/README.md

@@ -12,6 +12,15 @@ Implementation guides for each component. **AI Skill:** Optimized for AI/LLM con
 
 ---
 
+## Start here (humans)
+
+1. **Know your task?** Open **`docs/nqui-skills/HUMAN_GUIDE.md`** (in the package) or **`node_modules/@nqlib/nqui/docs/nqui-skills/HUMAN_GUIDE.md`** after install — maps *forms, toolbar, dashboard, empty/loading, …* → which doc to open first.
+2. **Pick one component** → **`nqui-<kebab-case>.md`** in this folder (e.g. `nqui-combobox.md`). Don’t load every file.
+3. **Need “which component?” tables** → scroll to **When to Use (Selection & Action Components)** and **Shared Conventions** below; skip **Prerequisites** until you wire build/CSS.
+4. **Deep layout / scroll / sticky** → **Layout & Scroll Patterns** (implementation-heavy; skip if you’re only choosing a component).
+
+---
+
 ## Prerequisites
 
 | Dependency | Version | Notes |
@@ -28,7 +37,7 @@ Implementation guides for each component. **AI Skill:** Optimized for AI/LLM con
 
 ## Shared Conventions (AI Implementation Rules)
 
-- **Control sizes:** `sm`=h-6, `default`=h-7, `lg`=h-8. Button, Toggle, ToggleGroup, Input, Select, Switch, Slider use this scale. See `packages/nqui/docs/nqui-skills/design-system.md` or `.cursor/skills/nqui-design-system/SKILL.md`.
+- **Control sizes:** `sm`=h-6, `default`=h-7, `lg`=h-8. Button, Toggle, ToggleGroup, Input, Select, Switch, Slider use this scale. See `docs/nqui-skills/nqui-design-system/SKILL.md` (package) or `.cursor/skills/nqui-design-system/SKILL.md` (monorepo copy).
 - **CSS vars required:** nqui uses `--primary`, `--background`, `--foreground`, etc. Run `npx @nqlib/nqui init-css`.
 - **Enhanced vs Core:** Default exports (`Button`, `Badge`, `Checkbox`, `Select`, etc.) are the polished/3D variants. Implementations live in **`packages/nqui/src/components/ui/*.tsx`** (single file per concern). Use `CoreButton`, `CoreBadge`, `CoreCheckbox`, etc. for base Radix/shadcn-style behavior. Separator: single component with `variant` prop (no CoreSeparator).
 - **Grouped controls:** ButtonGroup, ToggleGroup share border; outer container uses **pill** radius (`rounded-full`). ToggleGroup uses item dividers (`border-foreground/20`) or `ToggleGroupSeparator`.
@@ -38,7 +47,7 @@ Implementation guides for each component. **AI Skill:** Optimized for AI/LLM con
 - **SidebarProvider:** Must wrap entire layout (sidebar + content).
 - **Z-index:** Use CSS vars from `styles/elevation.css` (e.g. `z-[var(--z-modal)]`). Never hardcode `z-10`, `z-50`, etc.
 - **Keyboard:** Use `Keys`, `isMod`, `shouldIgnoreKeyboardShortcut` from `@/lib/keyboard` for custom shortcuts.
-- **Bounded content:** Chips, pills, and inline controls should stay inside their box (ellipsis / line-clamp / scroll-by-design). See **Bounded content** in `packages/nqui/docs/nqui-skills/design-system.md`. Portals and tooltips are explicit exceptions.
+- **Bounded content:** Chips, pills, and inline controls should stay inside their box (ellipsis / line-clamp / scroll-by-design). See **Bounded content** in `docs/nqui-skills/nqui-design-system/SKILL.md`. Portals and tooltips are explicit exceptions.
 
 ---
 

package/docs/components/nqui-scroll-area.md

@@ -30,3 +30,77 @@ import { ScrollArea, ScrollBar } from "@nqlib/nqui"
 ```tsx
 <ScrollArea fadeMask>...</ScrollArea>
 ```
+
+## `viewportRef`
+
+Pass **`viewportRef`** when you need a ref to the scrollable viewport (programmatic `scrollTop`, `ResizeObserver`, etc.).
+
+```tsx
+const viewportRef = useRef<HTMLDivElement>(null);
+
+<ScrollArea viewportRef={viewportRef} className="min-h-0 flex-1">
+  …
+</ScrollArea>
+```
+
+---
+
+## Layout pitfalls (read before shipping)
+
+Radix Scroll Area wraps content in a **viewport** plus an **inner wrapper** whose default layout can interact badly with **flex**, **wide content**, and **`pre` / monospace**. Follow the checks below to avoid: **no vertical scroll**, **content growing off-screen to the right**, or **nested scroll bugs**.
+
+### 1. Flex / resizable panels — height chain
+
+In a **flex column**, children default to `min-height: auto`, so a `flex-1` scroll region can **expand with content** and **never scroll**.
+
+- Put **`min-h-0`** (and usually **`min-w-0`**) on **every** flex ancestor between the root and `ScrollArea`.
+- On **`ScrollArea` root**, use something like **`min-h-0 flex-1`** (and **`h-full`** only when the parent’s height is well-defined).
+
+```tsx
+<div className="flex min-h-0 flex-1 flex-col overflow-hidden">
+  <ScrollArea className="min-h-0 flex-1" viewportRef={viewportRef}>
+    …
+  </ScrollArea>
+</div>
+```
+
+### 2. Prose, chat, markdown — width and wrapping
+
+The viewport’s **inner wrapper** (Radix) often behaves like a **shrink-to-fit** width. Long **URLs**, **unbroken strings**, or **table layout** can make the inner column **wider than the panel**, so users lose content off the **right** even though vertical scroll “works”.
+
+**Do:**
+
+- On **`ScrollArea` root** (or the viewport via arbitrary selectors), ensure:
+  - **`overflow-x: hidden`** on the **viewport** so the column does not pan sideways at the transcript level.
+  - On the **inner content wrapper** (Radix’s direct child of the viewport): **`display: block`**, **`min-width: 0`**, **`max-width: 100%`**, **`width: 100%`**, and **`break-words`** / **`overflow-wrap: anywhere`** so body text **wraps downward** instead of widening the scroll area.
+
+**Avoid:**
+
+- Blindly forcing **`display: block`** on the inner wrapper **without** `min-w-0` / `max-w-full` / wrapping — that can **break vertical scroll measurement** in some trees. Prefer a **documented, tested** combination (height + width) for your shell (e.g. chat transcript vs. simple list).
+
+**Consumer pattern (example):** apps may ship a shared class for “chat transcript” `ScrollArea` that sets viewport `overflow-x-hidden` and targets `[data-radix-scroll-area-viewport] > div` with block + `min-w-0` + `max-w-full` + `break-words`. Reuse one class per product so behavior stays consistent.
+
+### 3. `<pre>`, fenced code, `white-space: pre`
+
+**Do not** rely on `ScrollArea` as the only clip for **fenced code** or **`white-space: pre`** blocks. Radix’s structure often **fails to clip** tall/wide `pre` content predictably.
+
+**Prefer:** a plain element with **`max-height`**, **`overflow-auto`**, and optional thin scrollbar styling (e.g. a utility class in app CSS). Keep **one** main column `ScrollArea` for the page/panel; use **native overflow** inside message bodies for code.
+
+### 4. Nested `ScrollArea`
+
+Avoid **nested** `ScrollArea` for small regions (reasoning previews, inline panels). Prefer **one** outer scroll for the column + **native `overflow-auto`** for inner blocks. Nested Radix scroll roots multiply width/height bugs.
+
+### 5. Sidebar lists vs. chat transcript
+
+A pattern that fixes **wide titles** in a list (e.g. forcing inner `display: block`) may **break** vertical scrolling in a **chat transcript**. Do not reuse one global class for both without verifying **both** behaviors; split constants (e.g. “sidebar list” vs. “chat transcript”) when needed.
+
+---
+
+## Checklist (copy for PRs)
+
+- [ ] Flex ancestors use **`min-h-0`** where the scroll area must shrink.
+- [ ] `ScrollArea` root uses **`min-h-0`** (+ **`flex-1`** / **`h-full`** as appropriate).
+- [ ] Long **text** wraps: **`min-w-0`**, **`max-w-full`**, **`break-words`** / **`overflow-wrap: anywhere`**, viewport **`overflow-x-hidden`** if prose lives inside.
+- [ ] **Code / `pre`**: **`max-height` + native `overflow-auto`**, not nested `ScrollArea`.
+- [ ] **No unnecessary nested** `ScrollArea` for small inner regions.
+- [ ] **`ScrollBar`** included where a visible scrollbar is desired (see Basic example).

package/docs/components/nqui-tooltip.md

@@ -1,6 +1,6 @@
 # nqui Tooltip
 
-> Hover tooltip. Wrap app in TooltipProvider.
+> Supplemental hint on **hover or focus** — not a substitute for visible labels or critical instructions.
 
 ## Import
 
@@ -21,4 +21,19 @@ import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "@nqlib
 
 ## Provider
 
-Place once at app root (or layout).
+Place **`TooltipProvider`** once at app root (or layout) so delays and portals work consistently.
+
+## UX & accessibility
+
+- **Do not** put **required** information only in a tooltip. Users who don’t hover (keyboard, touch, screen reader) may miss it. Repeat critical copy in the visible UI or **Dialog** / **Sheet** / inline help.
+- **Keyboard:** Triggers should be focusable; tooltips typically show on **focus** as well as hover (Radix Tooltip behavior). Don’t rely on hover-only for anything mandatory.
+- **Touch:** There is **no hover** on phones. Treat tooltip content as **nice-to-have**; use **Popover** or inline text for essential mobile copy.
+- **Screen readers:** Tooltip content is exposed when the trigger is focused; keep text **short** and **non-semantic** for critical structure (don’t use tooltips as the only form label).
+
+## When to use something else
+
+| Need | Use instead |
+|------|-------------|
+| Rich content, tap to open | **Popover** (`nqui-popover.md`) |
+| Long preview on hover | **HoverCard** (`nqui-hover-card.md`) |
+| Blocking message | **Alert** or **Dialog** |

package/docs/nqui-skills/COMPONENTS_INDEX.md

@@ -0,0 +1,48 @@
+---
+name: nqui-component-docs-index
+description: Token-efficient map for nqui per-component docs. Use BEFORE opening README or multiple nqui-*.md files. Tells which single file to load for a component.
+---
+
+# Component docs — load order (save tokens)
+
+**Do not** bulk-read every file under `components/`. **Do not** load all of `README.md` unless you need full “when to use” tables.
+
+1. **Pick one doc:** `nqui-<kebab-case>.md` for the component you are implementing (e.g. `nqui-toggle-group.md`). In this repo use **`docs/components/`**; after `init-skills` use **`.cursor/nqui-skills/components/`**.
+2. **Unsure which component?** Skim **`README.md`** in that folder only for **“When to Use”** and the category table — or use **[HUMAN_GUIDE.md](./HUMAN_GUIDE.md)** (task → docs) or the **area → filenames** list below.
+3. **Deep selection logic** (toolbar vs form, ToggleGroup vs RadioGroup): **`nqui-components/SKILL.md`** and **`nqui-design-system/SKILL.md`**.
+
+## Paths
+
+| Where | Per-component docs | Routing / human wayfinding |
+|-------|--------------------|----------------------------|
+| nqui repo / package source | `docs/components/nqui-<kebab>.md` | `docs/nqui-skills/COMPONENTS_INDEX.md` · `HUMAN_GUIDE.md` |
+| Consumer after `init-skills` | `.cursor/nqui-skills/components/nqui-<kebab>.md` | `.cursor/nqui-skills/COMPONENTS_INDEX.md` · `HUMAN_GUIDE.md` |
+| Installed only (no init-skills) | `node_modules/@nqlib/nqui/docs/components/nqui-<kebab>.md` | `node_modules/@nqlib/nqui/docs/nqui-skills/COMPONENTS_INDEX.md` · `HUMAN_GUIDE.md` |
+
+Filenames always: `nqui-<kebab>.md`.
+
+## Area → doc files (open **one**)
+
+Suffix every name with `.md` in the components folder you are using (`docs/components/` or `.cursor/nqui-skills/components/`).
+
+**Actions & selection:** `nqui-button` · `nqui-button-group` · `nqui-toggle` · `nqui-toggle-group`
+
+**Forms & inputs:** `nqui-input` · `nqui-textarea` · `nqui-select` · `nqui-native-select` · `nqui-checkbox` · `nqui-radio-group` · `nqui-switch` · `nqui-slider` · `nqui-rating` · `nqui-input-otp` · `nqui-field` · `nqui-combobox` · `nqui-color-picker` · `nqui-color-slider` · `nqui-label` · `nqui-input-group`
+
+**Display:** `nqui-badge` · `nqui-avatar` · `nqui-alert` · `nqui-empty` · `nqui-skeleton` · `nqui-spinner` · `nqui-progress` · `nqui-separator` · `nqui-card` · `nqui-item` · `nqui-kbd` · `nqui-tracker` · `nqui-frosted-glass` · `nqui-logo`
+
+**Data:** `nqui-table` · `nqui-data-table`
+
+**Code / embed:** `nqui-code-block` · `nqui-snippet` · `nqui-code-editor` · `nqui-sandbox`
+
+**Navigation:** `nqui-breadcrumb` · `nqui-tabs` · `nqui-dropdown-menu` · `nqui-context-menu` · `nqui-menubar` · `nqui-navigation-menu` · `nqui-pagination` · `nqui-command` · `nqui-command-palette` · `nqui-table-of-contents`
+
+**Overlays:** `nqui-dialog` · `nqui-alert-dialog` · `nqui-drawer` · `nqui-sheet` · `nqui-popover` · `nqui-hover-card` · `nqui-tooltip` · `nqui-toaster`
+
+**Layout:** `nqui-accordion` · `nqui-collapsible` · `nqui-scroll-area` · `nqui-aspect-ratio` · `nqui-carousel` · `nqui-resizable` · `nqui-sidebar` · `nqui-sortable`
+
+**Advanced:** `nqui-calendar`
+
+---
+
+Full index + long-form guidance: `README.md` next to those files (large — use sections, not whole-file dump).

package/docs/nqui-skills/HUMAN_GUIDE.md

@@ -0,0 +1,21 @@
+# nqui — task → docs (for designers & humans)
+
+Use this file for **wayfinding** before diving into `README.md` (long) or dozens of `nqui-*.md` files. Paths below are from the **nqui package**; after `npx @nqlib/nqui init-skills`, the same files live under **`.cursor/nqui-skills/components/`**.
+
+| I’m building… | Start here | Then open |
+|---------------|------------|-----------|
+| **Forms** (login, settings, checkout) | `docs/components/README.md` → Forms sections | One of `nqui-field.md`, `nqui-input.md`, `nqui-select.md`, `nqui-combobox.md`, … |
+| **Toolbar / editor** (bold, view mode, align) | `nqui-skills/nqui-components/SKILL.md` (ToggleGroup rules) | `nqui-toggle-group.md`, `nqui-button-group.md` |
+| **“Choose one” in a form** (stacked options, survey) | **RadioGroup** may be correct — see `nqui-components/SKILL.md` vs ToggleGroup | `nqui-radio-group.md` |
+| **Dashboard / cards / lists** | `README.md` → Display | `nqui-card.md`, `nqui-item.md`, `nqui-table.md` or `nqui-data-table.md` |
+| **Empty / loading / error** | Skeleton + Empty + Alert | `nqui-skeleton.md`, `nqui-empty.md`, `nqui-alert.md` |
+| **Confirm destructive action** | Modal pattern | `nqui-alert-dialog.md` |
+| **Navigation** | `README.md` → Navigation | `nqui-tabs.md`, `nqui-breadcrumb.md`, `nqui-sidebar.md`, … |
+| **Touch-heavy or mobile** | Prefer **default/lg** controls; avoid **only** hover for critical info | `nqui-tooltip.md` (hover limits), `nqui-components/SKILL.md` (hit area) |
+
+**Cross-cutting UX**
+
+- **Accessibility:** Prefer components’ built-in Radix semantics; **don’t** put required instructions only in **Tooltip** (see `nqui-tooltip.md`). See `nqui-shadcn/SKILL.md` + rules for forms and dialogs.
+- **States:** **Loading** → Skeleton / Spinner; **empty** → Empty; **error** → Field + Alert + validation patterns in `nqui-shadcn/rules/forms.md`.
+
+**Agents:** For token-efficient routing, use **`COMPONENTS_INDEX.md`** first, then **one** `nqui-<name>.md`.