@nqlib/nqui 0.4.3 → 0.4.5

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. |
@@ -28,16 +28,115 @@ 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 use this scale. See `.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 `packages/nqui/docs/nqui-skills/design-system.md` or `.cursor/skills/nqui-design-system/SKILL.md`.
 - **CSS vars required:** nqui uses `--primary`, `--background`, `--foreground`, etc. Run `npx @nqlib/nqui init-css`.
-- **Enhanced vs Core:** Button, Badge, Checkbox, Select, etc. default to enhanced (3D, animations). Use `CoreButton`, `CoreBadge`, etc. for base shadcn. Separator: single component with `variant` prop (no CoreSeparator).
-- **Grouped controls:** ButtonGroup, ToggleGroup share border; ToggleGroup uses item dividers (`border-foreground/20`) or `ToggleGroupSeparator`.
+- **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`.
 - **Toolbar context:** Always show Toggle/ToggleGroup in realistic context (document toolbar, chart settings, etc.). Reference: `src/pages/ComponentShowcase.tsx`.
-- **Style injection:** Checkbox, Rating, Combobox inject `<style>` at mount → client-only guard for SSR.
+- **Style injection:** Some components inject `<style>` once at mount (e.g. **Combobox** input chrome in `ui/combobox.tsx`) → safe for SSR if the component is client-only (`"use client"`).
 - **OKLCH:** ColorPicker expects OKLCH strings (`oklch(0.5 0.15 240)`), not hex.
 - **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.
+
+---
+
+## 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 */
+}
+```
 
 ---
 
@@ -67,7 +166,7 @@ Use these rules to choose the right component. **Selection** = user picks from o
 |-------|-----|
 | 2–5 options, inline (e.g. bold/italic/underline) | **ToggleGroup** `type="multiple"` |
 | Form context, list of options | **Checkbox** (each option) |
-| Many options, need search | **Combobox** `multiSelect` |
+| Many options, need search | **Combobox** with `multiple` (see `nqui-combobox.md`) |
 
 ### Actions (trigger, not select)
 
@@ -108,7 +207,7 @@ Use these rules to choose the right component. **Selection** = user picks from o
 | Single choice, 5+ options or no space | **Select** |
 | Single choice, need search | **Combobox** (single) |
 | Single choice, form, small option set | **RadioGroup** |
-| Multiple choice, need search | **Combobox** `multiSelect` |
+| Multiple choice, need search | **Combobox** with `multiple` (see `nqui-combobox.md`) |
 | One boolean (agree, subscribe) | **Checkbox** |
 | On/off setting (dark mode, notifications) | **Switch** |
 | Numeric range (volume, opacity) | **Slider** |
@@ -135,7 +234,7 @@ Use these rules to choose the right component. **Selection** = user picks from o
 | Rating | [nqui-rating.md](./nqui-rating.md) | Star/score (1–5). |
 | InputOTP | [nqui-input-otp.md](./nqui-input-otp.md) | OTP/verification. |
 | Field | [nqui-field.md](./nqui-field.md) | Label + description + error wrapper. |
-| Combobox | [nqui-combobox.md](./nqui-combobox.md) | **Searchable** select. Single or `multiSelect`. Use when user types to filter. |
+| Combobox | [nqui-combobox.md](./nqui-combobox.md) | **Searchable** select. Single or `multiple`. Use when user types to filter. |
 | ColorPicker | [nqui-color-picker.md](./nqui-color-picker.md) | Color selection. OKLCH. |
 | ColorSlider | [nqui-color-slider.md](./nqui-color-slider.md) | Hue/saturation (used in ColorPicker). |
 | Label | [nqui-label.md](./nqui-label.md) | Form label. |
@@ -158,7 +257,7 @@ Use these rules to choose the right component. **Selection** = user picks from o
 | List row (avatar + title + actions) | **Item** |
 | Show keyboard shortcut | **Kbd** |
 | Activity blocks (e.g. heatmap) | **Tracker** |
-| Glass effect | **FrostedGlass** |
+| Glass effect (blur + tint row; scroll behind) | **FrostedGlass** |
 
 ---
 
@@ -178,7 +277,7 @@ Use these rules to choose the right component. **Selection** = user picks from o
 | Item | [nqui-item.md](./nqui-item.md) | List row: media + title + description + actions. |
 | Kbd | [nqui-kbd.md](./nqui-kbd.md) | Keyboard shortcut display. |
 | Tracker | [nqui-tracker.md](./nqui-tracker.md) | Activity blocks (heatmap). |
-| FrostedGlass | [nqui-frosted-glass.md](./nqui-frosted-glass.md) | Glass effect. |
+| FrostedGlass | [nqui-frosted-glass.md](./nqui-frosted-glass.md) | Glass blur; use with second tint row + scroll behind (see doc). |
 | NquiLogo | [nqui-logo.md](./nqui-logo.md) | Theme-aware logo. |
 
 ---

package/docs/components/nqui-badge.md

@@ -38,5 +38,6 @@ import { Badge } from "@nqlib/nqui"
 
 ## Notes
 
+- Implementation: **`packages/nqui/src/components/ui/badge.tsx`** (enhanced + core in one module).
 - ghost/link route to CoreBadge (different styling).
 - Use `CoreBadge` for plain shadcn badge.

package/docs/components/nqui-button.md

@@ -1,6 +1,6 @@
 # nqui Button
 
-> Enhanced button with 9 variants, gradients, active scale. Default import is EnhancedButton.
+> Default **Button** is the enhanced variant (gradients, depth, active scale). Implemented in **`ui/button.tsx`** with **`CoreButton`** for the plain primitive.
 
 ## Import
 
@@ -52,5 +52,7 @@ Render as `<a>` or custom element:
 
 ## Notes
 
+- **Shape:** full pill (`rounded-full`) for all sizes.
+- **Bounded label:** string/number children are wrapped so **`truncate`** + **`min-w-0`** apply in narrow layouts. Same pattern is used across **Toggle**, **Tabs**, **Badge**, **Combobox** chips; **Select** value uses **line-clamp**. Custom markup with one long inner node may still need its own `min-w-0 truncate` or a **`title`**.
 - Active state uses `scale-95`; avoid parent `transform` overrides.
 - Use `CoreButton` from `@nqlib/nqui` for base shadcn style.

package/docs/components/nqui-card.md

@@ -29,3 +29,11 @@ import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter }
   <CardContent>Scrollable content</CardContent>
 </Card>
 ```
+
+## Notes
+
+- **Layout / bounds:** Root **Card**, **CardHeader**, **CardContent**, and **CardFooter** include **`min-w-0`** so nested flex/grid layouts can shrink and children are less likely to spill horizontally. **Card** stays **`overflow-visible`** on purpose so popovers, menus, and focus rings are not clipped—pair with bounded components (buttons, carousel insets, `truncate`, etc.) instead of `overflow-hidden` on the card by default.
+- **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-carousel.md

@@ -20,3 +20,9 @@ import { Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext
   <CarouselNext />
 </Carousel>
 ```
+
+## Notes
+
+- **Prev/Next** are positioned **inside** the carousel region (`left-2` / `right-2`, or `top-2` / `bottom-2` when vertical) so arrows stay within parents like **Card** instead of using negative offsets that sat outside the viewport (`-left-12` / `-right-12` previously).
+- **Visibility:** Arrows are **dim by default** (`opacity-35`), ramp up on **carousel hover** (`group-hover/carousel`), and go **full opacity** on **button** `:hover`, `:focus-visible`, and `:active` (tap). Disabled controls stay faint.
+- Override with `className` on `CarouselPrevious` / `CarouselNext` if you need edge-aligned or external controls.

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
@@ -27,8 +49,23 @@ import { Checkbox } from "@nqlib/nqui"
 <Checkbox checked="indeterminate" onCheckedChange={...} />
 ```
 
+## Hit area (expanded pointer target)
+
+nqui ships [Bazza **hit-area** utilities](https://bazza.dev/craft/2026/hit-area) in library CSS (`hit-area-*`, `hit-area-x-*`, `hit-area-debug`, etc.). They extend the clickable region with a `::before` layer without changing layout.
+
+**Enhanced checkbox:** The checkmark is drawn with `::after` on the control root so `::before` stays free for `hit-area-*` on the **same** element. Add a class when you want a larger target (e.g. padded table cells):
+
+```tsx
+<Checkbox className="hit-area-6" checked={rowSelected} onCheckedChange={...} aria-label="Select row" />
+```
+
+**Label hover pill:** `.checkbox-animated-label::before` is on the **label** wrapper only; it does not conflict with `hit-area-*` on the checkbox button.
+
+**Without hit-area:** You can still wrap the control in `<span className="relative hit-area-6">` if you prefer the expanded area on a wrapper.
+
 ## Notes
 
+- Implementation: **`packages/nqui/src/components/ui/checkbox.tsx`** (enhanced + core in one module).
 - Injects `<style>` at mount. Use client-only guard for SSR.
 - Square and round share the same animation (pulse + checkmark scale); round has no SVG filters.
 - Use `CoreCheckbox` for plain Radix checkbox.

package/docs/components/nqui-color-slider.md

@@ -10,10 +10,12 @@ import { ColorSlider } from "@nqlib/nqui"
 
 ## Types
 
+Built on **`Slider`** from `ui/slider` (white thumb + shadow). For **non-controlled** demos, prefer **`defaultValue`** so the thumb stays draggable.
+
 ```tsx
-<ColorSlider sliderType="hue" value={[240]} onValueChange={setVal} min={0} max={360} />
-<ColorSlider sliderType="saturation" value={[0.5]} onValueChange={setVal} min={0} max={1} step={0.01} />
-<ColorSlider sliderType="lightness" value={[0.6]} onValueChange={setVal} min={0} max={1} step={0.01} />
+<ColorSlider sliderType="hue" defaultValue={[240]} onValueChange={setVal} min={0} max={360} />
+<ColorSlider sliderType="saturation" defaultValue={[0.5]} onValueChange={setVal} min={0} max={1} step={0.01} />
+<ColorSlider sliderType="lightness" defaultValue={[0.6]} onValueChange={setVal} min={0} max={1} step={0.01} />
 ```
 
 ## Custom

package/docs/components/nqui-combobox.md

@@ -1,73 +1,94 @@
 # nqui Combobox
 
-> **Searchable** select. Single or multi-select. Use when user types to filter options.
+> **Searchable** select (Base UI). User types to filter options. Single or multiple selection.
 
 ## When to Use
 
-- **Selection:** Single or multiple
-- **Key feature:** User searches/filters options by typing
-- **Options:** Many (dozens, hundreds)
+- **Selection:** Single (default) or multiple (`multiple` on root)
+- **Key feature:** Filter list by typing in the input
+- **Options:** Many rows; use **`items`** on `Combobox` + render prop on `ComboboxList` for built-in filtering
 
-**Choose Combobox when:** Options are too many to scroll, or user knows the name. Type to filter. Use Select when options are few and no search needed.
+**Choose Combobox when:** Users need search. Use **Select** when a plain dropdown is enough.
 
 ## Import
 
 ```tsx
 import {
-  Combobox, ComboboxInput, ComboboxContent, ComboboxList,
-  ComboboxItem, ComboboxEmpty, ComboboxChips, ComboboxChip,
-  ComboboxTrigger, ComboboxValue, ComboboxCollection, ComboboxGroup,
-  ComboboxLabel, ComboboxSeparator
+  Combobox,
+  ComboboxInput,
+  ComboboxContent,
+  ComboboxList,
+  ComboboxItem,
+  ComboboxEmpty,
+  ComboboxGroup,
+  ComboboxLabel,
+  ComboboxSeparator,
+  ComboboxCollection,
+  ComboboxChips,
+  ComboboxChip,
+  ComboboxChipsInput,
+  ComboboxTrigger,
+  ComboboxValue,
+  ComboboxClear,
+  useComboboxAnchor,
 } from "@nqlib/nqui"
 ```
 
-## Basic
+## Single selection + type-to-filter (recommended)
+
+Pass **`items`** to `Combobox` and use a **render function** as the only child of `ComboboxList`. Place **`ComboboxEmpty`** next to `ComboboxList` (both under `ComboboxContent`), not inside `ComboboxList` alongside the function.
 
 ```tsx
-<Combobox options={items} value={value} onChange={setValue}>
+const fruits = ["Apple", "Banana", "Cherry", "Date", "Elderberry"]
+
+<Combobox items={fruits}>
   <ComboboxInput placeholder="Search..." />
   <ComboboxContent>
+    <ComboboxEmpty>No results found.</ComboboxEmpty>
     <ComboboxList>
-      {items.map((item) => (
-        <ComboboxItem key={item.value} value={item.value}>{item.label}</ComboboxItem>
-      ))}
+      {(item) => (
+        <ComboboxItem key={item} value={item}>
+          {item}
+        </ComboboxItem>
+      )}
     </ComboboxList>
-    <ComboboxEmpty>No results</ComboboxEmpty>
   </ComboboxContent>
 </Combobox>
 ```
 
-## showClear
+## Static list (no `items` filter)
 
-```tsx
-<Combobox showClear ... />
-```
-
-## Multi-select chips
+You can still render `ComboboxItem` children manually when you control filtering yourself.
 
 ```tsx
-<Combobox multiSelect value={selected} onChange={setSelected}>
-  <ComboboxChips placeholder="Select...">
-    {(vals) => vals.map((v) => <ComboboxChip key={v} value={v} onRemove={...} />)}
-  </ComboboxChips>
-  ...
+<Combobox>
+  <ComboboxInput placeholder="Search..." />
+  <ComboboxContent>
+    <ComboboxList>
+      <ComboboxItem value="a">A</ComboboxItem>
+      <ComboboxItem value="b">B</ComboboxItem>
+    </ComboboxList>
+  </ComboboxContent>
 </Combobox>
 ```
 
-## Groups
+## Clear button
 
 ```tsx
-<ComboboxCollection>
-  <ComboboxGroup>
-    <ComboboxLabel>Group A</ComboboxLabel>
-    <ComboboxItem value="a">A</ComboboxItem>
-  </ComboboxGroup>
-  <ComboboxSeparator />
-  ...
-</ComboboxCollection>
+<ComboboxInput showClear placeholder="Search..." />
 ```
 
+## Multiple selection
+
+Use **`multiple`** on `Combobox` (see [Base UI Combobox](https://base-ui.com/react/components/combobox)). Combine with **`ComboboxChips`**, **`ComboboxChip`**, **`ComboboxChipsInput`** as needed for chip UI.
+
+## Implementation
+
+- **Source:** `packages/nqui/src/components/ui/combobox.tsx`
+- **Public API:** exported from `@nqlib/nqui` (same as `CoreCombobox*` aliases in the barrel if you need the unprefixed base re-exports)
+- **Styling:** Input group uses injected CSS once per page (`nqui-combobox-styles-v1`) for trigger depth/shadow; component is `"use client"`.
+
 ## Notes
 
-- Injects CSS at mount; client-only in SSR.
-- `useComboboxAnchor` for PopoverAnchor positioning.
+- **`useComboboxAnchor`:** ref for anchoring `ComboboxContent` when using chips / custom layout.
+- **Dropdown items:** spacing/hover treatment aligns with **Select** (`SelectItem`-style density).

package/docs/components/nqui-drawer.md

@@ -1,6 +1,6 @@
 # nqui Drawer
 
-> Bottom drawer. DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription, DrawerFooter.
+> **Vaul** drawer. **DrawerContent** keeps an **inset rounded card** (`before:bg-card`, `before:inset-2`, `before:rounded-xl`) so the panel does not read as a full-bleed slab—surface follows **`card`** tokens in both themes.
 
 ## Import
 

package/docs/components/nqui-frosted-glass.md

@@ -1,6 +1,8 @@
 # nqui FrostedGlass
 
-> Frosted glass blur effect. For sticky headers, overlays.
+> Apple-style frosted glass using `backdrop-filter`, extended backdrop, and masks. **Do not use `FrostedGlass` alone** in headers—pair it with a second row that carries the tint and controls stacking.
+
+**Background:** [Josh Comeau — `backdrop-filter`](https://www.joshwcomeau.com/css/backdrop-filter/)
 
 ## Import
 
@@ -8,12 +10,88 @@
 import { FrostedGlass } from "@nqlib/nqui"
 ```
 
-## Basic
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|--------|
+| `blur` | `number` | `16` | Blur radius in pixels (`backdrop-filter`). |
+| `borderRadius` | `number` | `0` | Pixels. `> 0` enables an SVG corner mask; `0` uses a linear gradient mask (flat header edge). |
+| `className` | `string` | — | Extra classes on the backdrop layer (e.g. z-index). |
+
+There is **no `opacity` prop**—tint comes from the sibling bar (see below). The backdrop layer uses a very light `bg-background/3` internally so the blur reads clearly.
+
+## Why two layers?
+
+`FrostedGlass` renders an **absolute** backdrop layer (`pointer-events-none`, extended height for sampling). Your **toolbar/title row** must be a **sibling** on top with:
+
+- `relative z-[var(--z-content)]`
+- A semi-opaque surface, e.g. `bg-background/40` (tint + readability)
+- Optional `border-b`, transitions, flex layout
+
+Without that second row, you only get blur with almost no “glass” read and no interactive chrome.
+
+## Z-index (elevation)
+
+Use variables from `styles/elevation.css` (never raw `z-10` / `z-50`).
+
+| Layer | Typical class | Role |
+|-------|----------------|------|
+| Sticky container | `z-[var(--z-sticky-page)]` or `z-[var(--z-sticky-content)]` | Page header vs sticky **inside** a card/panel. |
+| `FrostedGlass` | `className="z-[var(--z-background)]"` | Blur sits **below** the bar content. |
+| Bar / controls | `relative z-[var(--z-content)]` | Text, buttons, borders. |
+
+**Rule:** `--z-sticky-content` (15) < `--z-sticky-page` (20). Use `--z-sticky-page` for app chrome; `--z-sticky-content` for a **Card** with `stickyHeader` so page nav stays above card headers.
+
+## Scroll requirement
+
+`backdrop-filter` blurs **what is painted behind** the element. For a sticky header:
+
+1. Put the header and the main content in the **same scroll container** (or ensure content scrolls under the sticky region).
+2. Content must **move behind** the header while scrolling. If nothing scrolls behind the bar, you will see a flat tint with little or no visible blur.
+
+Reference: `AppLayout` wraps header + main in `overflow-y-auto` so the main area scrolls under the sticky header.
+
+## Page sticky header (canonical)
+
+Same structure as `packages/nqui/src/components/AppLayout.tsx`:
 
 ```tsx
-<FrostedGlass blur={16} borderRadius={0} />
+<div className="flex-1 min-h-0 flex flex-col overflow-y-auto overflow-x-hidden">
+  <header className="sticky top-0 z-[var(--z-sticky-page)] flex-shrink-0 relative">
+    <FrostedGlass blur={16} borderRadius={0} className="z-[var(--z-background)]" />
+    <div className="relative z-[var(--z-content)] border-b bg-background/40 flex h-12 items-center gap-2 px-4">
+      {/* title, nav, actions */}
+    </div>
+  </header>
+  <main>{/* scrolls behind header */}</main>
+</div>
 ```
 
-## Props
+- Outer `header`: `sticky` + `relative` + page-level z-index.
+- `FrostedGlass`: `borderRadius={0}` for a straight top edge; increase if the header has rounded corners.
+- Inner bar: `bg-background/40` (adjust opacity to taste).
+
+## Card with sticky header
+
+**Card** `stickyHeader` wires this pattern for you: `FrostedGlass` with `borderRadius={8}` under **CardHeader**, scrollable **CardContent** below. See `ComponentShowcase` and `packages/nqui/src/components/ui/card.tsx`.
+
+Use `--z-sticky-content` on the sticky region when the glass sits inside a card, not the full page.
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---------|----------------|
+| Solid bar, almost no blur | No content scrolling behind the sticky region, or header not in the scrolling ancestor. |
+| Blur but unreadable text | Add / raise `bg-background/40` (or similar) on the **content row**, not only on `FrostedGlass`. |
+| Wrong stacking vs sidebar/modals | Check elevation: floating sidebars use `--z-floating`; modals/popovers sit above—see `elevation.css`. |
+| Rounded header corners | Set `borderRadius` to match; `> 0` switches to the SVG mask path. |
+
+## Vite / Tailwind
+
+Consumer apps must import nqui styles **and** add Tailwind `@source` for the library (see **INSTALLATION.md** §2c). Missing sources can strip utilities used around the header (`bg-background/40`, z-index arbitrary values, etc.).
+
+## Related
 
-blur, borderRadius, opacity. Use in sticky header with z-index.
+- **AppLayout** — full app shell with frosted page header.
+- **Card** `stickyHeader` — frosted sticky card header.
+- **Select** — popover row uses the same backdrop layering pattern.

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

@@ -18,13 +18,58 @@ 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">Option A</RadioGroupItem>
+  <RadioGroupItem value="b">Option B</RadioGroupItem>
+</RadioGroup>
+```
+
+**Do not** pair an empty `RadioGroupItem` with a separate `Label` in the same row: the item’s outer wrapper is meant to include the text (as children) or stand alone without a sibling label. Putting `Label` beside a control-only item can create a wide empty flex region and push the label to the far edge. Prefer the pattern above; if you must use a separate label, use `CoreRadioGroupItem` from `@nqlib/nqui` (see package exports) or ensure the item is not wrapped in a full-width row that fights the layout.
+
+## With Complex Content
+
 ```tsx
 <RadioGroup value={value} onValueChange={setValue}>
-  <RadioGroupItem value="a" /> A
-  <RadioGroupItem value="b" /> B
+  <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-scroll-area.md

@@ -1,6 +1,6 @@
 # nqui ScrollArea
 
-> Custom scrollbar. fadeMask (enhanced), horizontal scroll.
+> Default export is **EnhancedScrollArea** (fade mask, orientation). Underlying primitive: **`CoreScrollArea`** / `ScrollBar` from **`ui/scroll-area`**. Core scrollbar uses a **thinner** track/thumb (drawer-like).
 
 ## Import
 

package/docs/components/nqui-select.md

@@ -48,6 +48,6 @@ import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGr
 
 ## Notes
 
-- Injects CSS at mount; client-only in SSR.
+- **Content:** FrostedGlass + popover surface; **items** use relaxed row spacing (hover `accent`, margins) for dropdown parity with **Combobox** list items.
 - Use `SelectScrollUpButton` / `SelectScrollDownButton` for long lists.
-- `CoreSelect*` for plain styling.
+- **`CoreSelect*`** for the same primitives without the enhanced trigger chrome (re-exported from the same `ui/select` module).

package/docs/components/nqui-sheet.md

@@ -1,6 +1,6 @@
 # nqui Sheet
 
-> Side panel. SheetTrigger, SheetContent, SheetHeader, SheetTitle, SheetDescription, SheetFooter. side: top|right|bottom|left.
+> Side panel (Radix **Dialog** pattern). **SheetContent** uses an **inset card** panel: transparent outer shell + `before:bg-card` block inset with **rounded corners** (matches drawer-style “card floating in the viewport”). **No edge borders** on the sheet shell (divider lines removed in favor of the card shape).
 
 ## Import
 

package/docs/components/nqui-slider.md

@@ -14,3 +14,16 @@ import { Slider } from "@nqlib/nqui"
 <Slider value={[50]} onValueChange={([v]) => setVal(v)} />
 <Slider value={[20, 80]} onValueChange={setRange} />
 ```
+
+## Sizes
+
+```tsx
+<Slider size="sm" defaultValue={[40]} />
+<Slider size="default" defaultValue={[40]} />
+<Slider size="lg" defaultValue={[40]} />
+```
+
+## Notes
+
+- **Thumb:** white, rounded-full, subtle shadow (aligned with **Switch** thumb language).
+- **`size`:** `sm` | `default` | `lg` (control scale heights).