@nqlib/nqui 0.4.7 → 0.5.0

package/docs/nqui-skills/SKILL.md

@@ -1,106 +1,53 @@
 ---
-name: nqui Components
-description: Component implementation guide for nqui. Use when building UI, designing app layouts, or implementing components with @nqlib/nqui.
+name: nqui
+description: Hub for nqui skills — @nqlib/nqui components, design system, shadcn patterns, bundle size, local/published toggle, and install. Load sub-skills by task.
 ---
 
-# nqui Components Guide
+# nqui skills (hub)
 
-Reference `packages/nqui/docs/components/README.md` for the full component index and implementation rules.
+Use this file as the entry point when working inside **`docs/nqui-skills/`** (package) or **`.cursor/nqui-skills/`** (after `npx @nqlib/nqui init-skills`).
 
-## Quick Reference
+## Per-component docs (token-efficient)
 
-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
+1. Read **[COMPONENTS_INDEX.md](./COMPONENTS_INDEX.md)** first — which single `nqui-*.md` to open.
+2. **Designers / task-based:** **[HUMAN_GUIDE.md](./HUMAN_GUIDE.md)** — forms, dashboards, navigation, empty/loading/error, without reading all of `README.md`.
+3. **Source repo:** `docs/components/nqui-<name>.md`
+4. **After `init-skills`:** `.cursor/nqui-skills/components/nqui-<name>.md` (same files as npm `docs/components/`)
 
-## App Design Rule: Inline Selection → ToggleGroup
+Avoid loading every component doc or the full `README.md` unless you need broad “when to use” tables.
 
-When designing app UI (toolbars, headers, inline controls):
+## Where to read docs (pick by context)
 
-| 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** | - |
+| Context | Path |
+|---------|------|
+| **This package** (nqui repo or monorepo `packages/nqui`) | `docs/components/README.md`, `docs/components/nqui-<name>.md` |
+| **Consumer after init-skills** | `.cursor/nqui-skills/components/README.md` and `nqui-<name>.md` |
+| **npm only** | `node_modules/@nqlib/nqui/docs/components/` |
 
-**Rule:** Inline/toolbar selection = ToggleGroup. Use RadioGroup only for form context (settings page, modal form, stacked list).
+Per-component files: `nqui-<kebab-case>.md` (e.g. `nqui-combobox.md`).
 
-## App Design Rule: Context-First (Toolbar in Real Environment)
+## Skill index (load by task)
 
-**Rule:** Never show Toggle/ToggleGroup/ButtonGroup in isolation. Always place them in realistic app context.
+| Task | Open |
+|------|------|
+| UI, layouts, ToggleGroup vs Radio, Card + ScrollArea | [nqui-components/SKILL.md](./nqui-components/SKILL.md) |
+| Sizing, spacing, density, grouped controls, flex scroll | [nqui-design-system/SKILL.md](./nqui-design-system/SKILL.md) |
+| Imports, FieldGroup, forms, composition, icons, styling | [nqui-shadcn/SKILL.md](./nqui-shadcn/SKILL.md) |
+| Peers, externals, subpath imports | [nqui-bundle-size-best-practices/SKILL.md](./nqui-bundle-size-best-practices/SKILL.md) |
+| `npm link` local nqui vs registry | [nqui-local-published-toggle/SKILL.md](./nqui-local-published-toggle/SKILL.md) |
+| `init-css`, `install-peers`, CLI | [nqui-install/SKILL.md](./nqui-install/SKILL.md) |
 
-| 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 |
+## UX principles (cross-cutting)
 
-**Canonical implementation:** `packages/nqui/src/pages/ComponentShowcase.tsx` — Toggle & ToggleGroup section.
+- **Accessibility:** Use semantic components; **don’t** hide required instructions in **Tooltip** only (see `docs/components/nqui-tooltip.md`). Forms: `data-invalid` / `aria-invalid` per `nqui-shadcn/rules/forms.md`. Dialogs need titles (`nqui-shadcn` composition rules).
+- **Touch / pointer:** Hover-only content is **supplemental**; **Tooltip** / **HoverCard** are poor for primary info on touch. Use **default/lg** size and optional **hit-area** on small targets in padded rows (`nqui-components/SKILL.md`).
+- **States:** **Loading** → Skeleton / Spinner; **empty** → Empty; **error** → Field + Alert + validation patterns.
+- **Focus:** After closing overlays, preserve sensible focus (Radix defaults — don’t override with stray `tabIndex`).
 
-## Design System Conventions
+## Quick rules
 
-See **`design-system.md`** in this folder for sizing, grouped controls (including pill **ButtonGroup** / **ToggleGroup** shells), and file paths under `packages/nqui/src/components/ui/`.
+- **Inline/toolbar selection** → `ToggleGroup` (see **RadioGroup** when form semantics matter — `nqui-components/SKILL.md`).
+- **Card + scroll** → thread `min-h-0` through flex to `ScrollArea`; see design-system skill.
+- **Forms** → `FieldGroup` + `Field`; see `nqui-shadcn` rules.
 
-### 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)
-
-### FrostedGlass (sticky glass headers)
-
-`FrostedGlass` is only the blur layer. Implementations need a **second row** with `bg-background/40`, `relative z-[var(--z-content)]`, and content that **scrolls behind** the sticky header. Full checklist, props, and troubleshooting: **`packages/nqui/docs/components/nqui-frosted-glass.md`**. Canonical page header: `AppLayout`; card: **Card** `stickyHeader`.
-
-### Component Naming
-- Default exports are the enhanced/polished variants; use **Core\*** for plain primitives
-- Implementations are consolidated under **`ui/`** (not separate `custom/enhanced-*` per component for Button, Badge, Checkbox, Select, Combobox, Sonner)
-- File names: kebab-case
-- Component names: PascalCase
-
-### Hit area (optional)
-
-Library CSS includes [Bazza hit-area](https://bazza.dev/craft/2026/hit-area) utilities. For **Checkbox** / **Switch** in padded tables or lists, pass **`className="hit-area-6"`** (or `hit-area-4`, axis variants) on the **component root**, not on a wrapper-only parent. Opt-in only; use **`hit-area-debug`** while tuning. Details: `packages/nqui/docs/components/nqui-checkbox.md`, `nqui-switch.md`; examples: `ComponentShowcase` Checkbox + Switch sections.
-
-## 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`
+Full table: [README.md](./README.md).

package/docs/nqui-skills/nqui-bundle-size-best-practices/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: nqui-bundle-size-best-practices
+description: Bundle size best practices for @nqlib/nqui. Use when adding dependencies, creating packages that depend on nqui, or optimizing build output.
+---
+
+# nqui Bundle Size Best Practices
+
+Guidelines for keeping **@nqlib/nqui** bundles small and maintainable.
+
+## Principle
+
+Keep the main bundle small. Externalize heavy optional dependencies so consumers install only what they use.
+
+## When Adding a Dependency
+
+Before adding a dependency, ask:
+
+1. **Is it heavy (>50KB)?** Large libs (motion, @dnd-kit, embla-carousel, etc.) bloat the bundle.
+2. **Is it optional?** Only some components use it (e.g. Sortable uses @dnd-kit). If yes, add as optional peer + external in Vite.
+
+If both answers are yes, externalize it.
+
+## Externalization Checklist
+
+1. Add to `vite.config.ts` (package root) → `rollupOptions.external`:
+   ```ts
+   "package-name",
+   ```
+2. Add to `package.json`:
+   - `peerDependencies`: `"package-name": "^x.y.0"`
+   - `peerDependenciesMeta`: `"package-name": { "optional": true }`
+3. Keep in `dependencies` if the nqui dev app (showcase, Storybook) needs it.
+4. Document in `internal-notes/PEER_DEPENDENCIES.md` which component(s) require it.
+
+## Avoid Bundling
+
+Do not add large dependencies as regular dependencies when they are feature-specific:
+
+- **Animations**: motion, framer-motion
+- **Drag and drop**: @dnd-kit/*
+- **Carousels**: embla-carousel-react
+- **Tables**: @tanstack/react-table
+- **Resizable panels**: react-resizable-panels
+- **Combobox**: `cmdk` (optional peer, shared with Command)
+- **Syntax highlighting**: shiki, @shikijs/transformers
+- **Sandboxes**: @codesandbox/sandpack-react
+- **Command palettes**: cmdk
+- **Date pickers**: react-day-picker, date-fns
+- **Toasts**: sonner
+- **Drawers**: vaul
+- **Icons**: @hugeicons/react, @hugeicons/core-free-icons
+
+## Subpath Exports
+
+Consumers can import from subpaths for smaller bundles when using only specific component groups:
+
+- `@nqlib/nqui/code` — CodeBlock
+- `@nqlib/nqui/carousel` — Carousel
+- `@nqlib/nqui/command` — Command, CommandPalette
+- `@nqlib/nqui/sortable` — Sortable
+- `@nqlib/nqui/calendar` — Calendar
+- `@nqlib/nqui/sonner` — Toaster, Sonner
+- `@nqlib/nqui/drawer` — Drawer
+
+See `internal-notes/PEER_DEPENDENCIES.md` for peer requirements per subpath.
+
+## Reference
+
+- **Component-to-peer mapping:** `internal-notes/PEER_DEPENDENCIES.md`
+- **Installation notes:** `internal-notes/INSTALLATION.md` (Optional components section)
+
+## Other libraries in a monorepo
+
+Packages that wrap or extend nqui should follow the same pattern:
+
+- `peerDependencies`: `react`, `react-dom`, `@nqlib/nqui` (or workspace version)
+- In Vite library build: externalize `react`, `react-dom`, `@nqlib/nqui`
+- Keep heavy optional deps as peers when consumers may not need them

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

@@ -0,0 +1,101 @@
+---
+name: nqui-components
+description: Component implementation guide for nqui. Use when building UI, designing app layouts, or implementing components with @nqlib/nqui. ToggleGroup for inline/toolbar selection; RadioGroup when form semantics matter. Card + ScrollArea + flex min-h-0 scroll patterns.
+---
+
+# nqui Components
+
+## Where to read docs (pick by context)
+
+| Context | Path |
+|---------|------|
+| **This package** (nqui as its own repo, or `packages/nqui` in a monorepo) | `docs/components/README.md` and `docs/components/nqui-<name>.md` |
+| **Consumer app** (npm install; see `files` in `@nqlib/nqui` `package.json`) | `node_modules/@nqlib/nqui/docs/components/README.md` and `node_modules/@nqlib/nqui/docs/components/nqui-<name>.md` |
+| **Task-based entry (designers)** | `docs/nqui-skills/HUMAN_GUIDE.md` |
+
+Per-component files: `nqui-<kebab-case>.md` (e.g. `nqui-combobox.md`).
+
+## When to Load
+
+- Implementing UI with nqui components
+- Adding or modifying a component in this package
+- Choosing the right component for a use case
+- Debugging component behavior
+
+## App Design Rule: Inline Selection → ToggleGroup
+
+When designing **toolbars, headers, and inline controls** (not traditional stacked forms):
+
+| 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** | — |
+
+**Default rule:** Inline/toolbar selection = **ToggleGroup**.
+
+## ToggleGroup vs RadioGroup (semantics & a11y)
+
+| Situation | Prefer |
+|-----------|--------|
+| Toolbar, chart controls, editor chrome, **spatially inline** options | **ToggleGroup** — correct visual language; Radix exposes `role="group"` / toggle semantics as implemented |
+| **Stacked or labeled form** “choose one” (settings page, wizard, survey), users expect **radiogroup** behavior | **RadioGroup** — screen readers get **radiogroup / radio** semantics (“1 of N”) |
+| Unsure | If it reads like a **form field**, use **RadioGroup**. If it reads like a **toolbar or segmented control**, use **ToggleGroup**. |
+
+Do not use RadioGroup inside dense toolbars for purely visual reasons if ToggleGroup fits the interaction — but do not force ToggleGroup for **form questionnaires** where radio semantics matter.
+
+## 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:** `src/pages/ComponentShowcase.tsx` — Toggle & ToggleGroup section.
+
+## Quick Reference
+
+1. **Human task → component:** `docs/nqui-skills/HUMAN_GUIDE.md`
+2. **Main index:** `README.md` under `docs/components/` — full tables, prerequisites, layout patterns
+3. **Per-component:** `nqui-<name>.md` — import, examples, variants
+4. **Design system:** `docs/nqui-skills/nqui-design-system/SKILL.md` — sizing, **Card + ScrollArea flex scroll contract**
+
+**Cursor:** `npx @nqlib/nqui init-cursor` syncs from `docs/nqui-skills/`.
+
+## Accessibility & touch (summary)
+
+- **Focus:** After closing **Dialog** / **Sheet**, return focus to the trigger; don’t leave focus in the void (Radix helps — don’t fight it with extra `tabIndex`).
+- **Keyboard:** Interactive components must be focusable and activatable without a mouse; see per-component docs and `nqui-shadcn` rules.
+- **Touch:** Default control heights (h-6 / h-7 / h-8) align with dense desktop UI; for **touch-primary** surfaces, prefer **default/lg** and optional **`hit-area-*`** on small controls in padded rows (`nqui-checkbox.md`, `nqui-switch.md`).
+- **Hover-only:** **Tooltip** / **HoverCard** are poor places for **required** information — no hover on touch. See `docs/components/nqui-tooltip.md`.
+
+## Card + ScrollArea (do not overflow the card)
+
+When building **Card** + **ScrollArea** (or any **scroll inside flex**):
+
+- Read **`docs/nqui-skills/nqui-design-system/SKILL.md`** → section **Card + ScrollArea (flex scroll contract)**.
+- **Always** thread **`min-h-0`** on flex children from the height constraint down to **ScrollArea**.
+- Do **not** rely on **`overflow-hidden`** on the outer **Card** alone without a proper **flex** + **`min-h-0`** chain (Card defaults **`overflow-visible`** for popovers).
+
+## Key Conventions
+
+- React 18+ and 19 supported
+- Control sizes: sm=h-6, default=h-7, lg=h-8
+- Enhanced vs Core: default is enhanced; use Core* for plain
+- Z-index: CSS vars from `src/styles/elevation.css` only
+
+## FrostedGlass sticky headers
+
+`FrostedGlass` is only the blur layer. Pair it with a **second row** (`bg-background/40`, `relative z-[var(--z-content)]`) and ensure **content scrolls behind** the sticky header. Full detail: `docs/components/nqui-frosted-glass.md`. References: `AppLayout`, **Card** `stickyHeader`.
+
+## Hit area (optional pointer targets)
+
+nqui ships [Bazza hit-area](https://bazza.dev/craft/2026/hit-area) utilities (`hit-area-4`, `hit-area-6`, axis variants, `hit-area-debug`). Use when a **small control sits in a padded cell or row** and you want taps in the padding to hit the control.
+
+- Put utilities on the **same element** as **Checkbox** or **Switch** — not on a wrapper-only parent.
+- **Opt-in** — dense toolbars can get overlapping targets if every control uses a large hit area.
+- **Docs:** `docs/components/nqui-checkbox.md`, `nqui-switch.md`; examples: `src/pages/ComponentShowcase.tsx`.

package/docs/nqui-skills/{design-system.md → nqui-design-system/SKILL.md}

@@ -1,21 +1,21 @@
 ---
 name: nqui-design-system
-description: Design system conventions for nqui component library. Use when creating or modifying nqui UI components to ensure sizing, spacing, and styling consistency.
+description: Design system conventions for nqui component library. Use when creating or modifying nqui UI components (sizing, spacing, Card + ScrollArea flex scroll / min-h-0, grouped controls, density).
 ---
 
 # nqui Design System
 
-Guidelines for AI agents implementing or modifying nqui components. Follow these rules to maintain visual consistency.
+Guidelines for AI agents and developers implementing or modifying nqui components. Follow these rules to maintain visual consistency.
 
 ## Control Size Scale
 
 All interactive controls (buttons, toggles, inputs, selects) use a unified scale:
 
-| Size     | Height | Min Width | Use Case                          |
-|----------|--------|-----------|-----------------------------------|
-| `sm`     | h-6 (24px) | min-w-6 | Compact UIs, dense tables, toolbars |
-| `default`| h-7 (28px) | min-w-7 | Standard forms, primary actions       |
-| `lg`     | h-8 (32px) | min-w-8 | Emphasis, secondary actions         |
+| Size | Height | Min Width | Use Case |
+|------|--------|-----------|----------|
+| `sm` | h-6 (24px) | min-w-6 | Compact UIs, dense tables, toolbars |
+| `default` | h-7 (28px) | min-w-7 | Standard forms, primary actions |
+| `lg` | h-8 (32px) | min-w-8 | Emphasis, secondary actions |
 
 ### Semantic Rule
 
@@ -85,7 +85,7 @@ Font: `--font-sans` (Inter Variable). Leading: `leading-normal` or `text-xs/rela
 - **Child borders** – Items: `border-0` (container provides the border)
 - **Dividers** – ToggleGroup: item borders (`border-foreground/20`) between items. Or `ToggleGroupSeparator` when `separator={false}`.
 - **Corners** – First item: rounded-l (or rounded-t vertical), last: rounded-r (or rounded-b)
-- **Several groups on one horizontal row** – `ButtonGroup`’s container is **`inline-flex`**, so multiple sibling groups in normal flow behave like **inline boxes** and align to **baseline**. Mixed content (labels vs icons vs `ButtonGroupText`) then produces inconsistent vertical alignment. Prefer an explicit row container: **`flex flex-wrap items-center gap-*`**, or **grid** columns—so you choose **cross-axis alignment** (`items-center`, `items-end`, etc.) instead of inheriting baseline alignment from inline layout.
+- **Several groups on one horizontal row** – `ButtonGroup`’s container is `inline-flex`, so multiple sibling groups behave like inline boxes and align to **baseline**. Mixed content (labels vs icons vs `ButtonGroupText`) then looks vertically inconsistent. Prefer **`flex flex-wrap items-center gap-*`** or **grid** so you control cross-axis alignment (`items-center`, `items-end`) instead of baseline alignment.
 
 ## Toggle & ToggleGroup Visual Treatment (Visibility on Any Background)
 
@@ -94,28 +94,58 @@ Toggles and ToggleGroup items must remain visible on card, sidebar, and varied b
 | State | Default/Outline | Segmented (single select) |
 |-------|-----------------|---------------------------|
 | **Off** | `border border-input/60` (or `border-input`), `shadow-sm`, `bg-background/50` (or transparent) | Transparent |
-| **On** | `bg-secondary` + `nqui-button-gradient` + `nqui-button-shadow` (secondary-like layering) | `bg-primary` + gradient + shadow |
+| **On** | `bg-secondary` + `nqui-button-gradient` + `nqui-button-shadow` | `bg-primary` + gradient + shadow |
 | **Active (pressed)** | `active:shadow-[inset_0_3px_5px_rgba(0,0,0,0.125)]` | Same |
 
 Never use flat `bg-muted` only for selected state; always add gradient + shadow for depth and visibility.
 
+**Active label weight:** Toggle / ToggleGroup use `font-medium` when off and **`font-bold` when on** (`data-[state=on]`). TabsTrigger uses **`font-bold` when active** (`data-[state=active]`). **ButtonGroup** forces direct **`button` / `a` / select-trigger children to `font-normal`** (overrides Button’s `font-medium`); use **`font-bold` only** on the selected control via `aria-current="true"`, `aria-pressed="true"`, or `data-active`.
+
 ## Toolbar & In-Context Design
 
-**Rule:** Show controls in realistic app context, not isolated. Reference: `packages/nqui/src/pages/ComponentShowcase.tsx` (Toggle & ToggleGroup section).
+**Rule:** Show controls in realistic app context, not isolated. Reference: `src/pages/ComponentShowcase.tsx` (Toggle & ToggleGroup section).
 
 | Context | Layout | Example |
 |---------|--------|---------|
-| Document editor | Toolbar above content area, `bg-muted/30` container, `Separator` between control groups | Bold/Italic/Underline \| Align Left/Center/Right |
-| Chart/settings panel | Label + inline controls, `rounded-lg border bg-muted/30 p-3` | Y-axis: Linear/Log; Size: S/M/L |
-| Standalone | Inline with related UI, not floating alone | Pin, Mute, single Toggle |
+| Document editor | Toolbar above content, `bg-muted/30`, `Separator` between groups | Bold / Italic / Underline; align left / center / right |
+| Chart/settings panel | Label + inline controls, `rounded-lg border bg-muted/30 p-3` | Y-axis Linear/Log; size S/M/L |
+| Standalone | Inline with related UI | Pin, Mute, single Toggle |
 
 ## Bounded content (default UX)
 
-- **Rule:** Interactive surfaces should not **visually bleed** outside their box: prefer **ellipsis** (`truncate`), **line-clamp**, **controlled scroll**, or **wrapping** (`break-words` / `whitespace-normal`) instead of letting text or icons paint past padding in narrow layouts.
-- **Not universal:** Portals (dropdowns, popovers), **tooltips**, and **drag overlays** intentionally escape bounds. **Data tables** may use horizontal scroll. Choose per component.
-- **Flex gotcha:** `inline-flex` + icon + `whitespace-nowrap` + raw **string** children keeps an implicit **min-width: min-content**; parents need **`min-w-0`** (and often **`max-w-full`**) on the control and a truncating inner wrapper for long labels.
-- **Built-in helpers in nqui:** Shared `wrapInlineLabelTextNodes` + `min-w-0 max-w-full` on **Button**, **Toggle**, **TabsTrigger**, **Badge**, **ComboboxChip**; **SelectTrigger** uses **`min-w-0 max-w-full`** and **`min-w-0`** on the value slot with **`line-clamp-1`**. **Carousel** prev/next sit **inside** the carousel box so they don’t spill out of **Card** (override via `className` if you want outside arrows).
-- **Card:** **Card** uses **`min-w-0`** on shell + header/content/footer for flex/grid safety but keeps **`overflow-visible`** so overlays aren’t clipped; don’t rely on **`overflow-hidden`** on Card as a global “catch-all” unless you accept clipping dropdowns/focus.
+- **Rule:** Interactive surfaces should not **visually bleed** outside their box: prefer **ellipsis** (`truncate`), **line-clamp**, **controlled scroll**, or **wrapping** instead of letting text or icons paint past padding in narrow layouts.
+- **Not universal:** Portals (dropdowns, popovers), **tooltips**, and **drag overlays** intentionally escape bounds. **Data tables** may use horizontal scroll.
+- **Flex gotcha:** `inline-flex` + icon + `whitespace-nowrap` + raw string children keeps implicit **min-width: min-content**; parents need **`min-w-0`** (and often **`max-w-full`**) on the control and a truncating inner wrapper for long labels.
+- **Built-in helpers in nqui:** Shared `wrapInlineLabelTextNodes` + `min-w-0 max-w-full` on **Button**, **Toggle**, **TabsTrigger**, **Badge**, **ComboboxChip**; **SelectTrigger** uses `min-w-0 max-w-full` and `min-w-0` on the value slot with `line-clamp-1`. **Carousel** prev/next sit **inside** the carousel box so they don’t spill out of **Card** (override via `className` if you want outside arrows).
+- **Card:** **Card** uses **`min-w-0`** on shell + header/content/footer for flex/grid safety but keeps **`overflow-visible`** so overlays aren’t clipped; don’t rely on **`overflow-hidden`** on Card as a global catch-all unless you accept clipping dropdowns/focus.
+
+## Card + ScrollArea (flex scroll contract)
+
+**Symptom:** Content inside **Card** + **ScrollArea** overflows the card, ignores rounded corners, or **does not scroll** until someone adds `min-h-0` up the tree.
+
+**Cause:** Flex items default to **`min-height: auto`**: they won’t shrink below content height, so the scroll region never gets a bounded height → **no scrollport**. Normal CSS, not a ScrollArea bug.
+
+**Rules (every time you nest scrollable content in flex):**
+
+1. **Height chain:** From the page shell down to **ScrollArea**, every flex child that must shrink needs **`min-h-0`** (often with **`flex-1`** or **`flex-shrink`**).
+2. **Card root:** Keeps **`overflow-visible`** on purpose (dropdowns, popovers, focus rings). Do **not** use **`overflow-hidden`** on the outer **Card** alone as your only scroll fix — establish a **nested** scroll box.
+3. **Scrollable body:** Prefer **`CardContent`** (or a wrapper) with **`min-h-0 flex-1 overflow-hidden`**, then **ScrollArea** with **`className="min-h-0 h-full"`** or **`min-h-0 flex-1`** inside a **`flex flex-col min-h-0`** card.
+4. **Parent must constrain height:** e.g. `h-full`, `min-h-0`, or explicit `max-h-*` / `h-[...]`; otherwise “100%” has no reference.
+
+**Reference implementations:** `Card` + **`stickyHeader`** in `src/components/ui/card.tsx`; `src/pages/ComponentShowcase.tsx` where ScrollArea sits in a bounded layout.
+
+**Checklist before merging a scrollable card:**
+
+- [ ] Flex column from page → card includes **`min-h-0`** where the tree shrinks.
+- [ ] Card column is **`flex flex-col min-h-0`** (and **`h-full`** if filling a panel).
+- [ ] Scroll wrapper: **`flex-1 min-h-0 overflow-hidden`**.
+- [ ] **ScrollArea** has **`min-h-0`** and fills the wrapper (**`h-full`** / **`flex-1`**).
+
+## Density & visual hierarchy (product feel)
+
+- **Density:** `size="sm"` and compact patterns (tables, sidebars) read as **dense**; default/lg and generous spacing read as **comfortable**. Don’t mix ad-hoc heights — use the **size scale** so density stays intentional.
+- **Task priority:** One **primary** action per surface (full-color / high contrast). Secondary actions use **outline** / **secondary**; **tertiary** use **ghost** / muted text. Avoid multiple competing primaries.
+- **Muted vs foreground:** Use **`text-muted-foreground`** for supporting labels, **`text-foreground`** for primary reading. Don’t gray out text that must be understood to complete a task.
 
 ## Customization
 
@@ -125,16 +155,16 @@ Never use flat `bg-muted` only for selected state; always add gradient + shadow
 
 ## Hit area utilities
 
-**Hit area** expands the pointer target; it does **not** replace control **size** (sm / default / lg). Use **opt-in** on **Checkbox** / **Switch** for padded rows or cells—not as a global default. Avoid large overlapping hit areas in dense toolbars. See **`SKILL.md`** (Hit area) in this folder and `packages/nqui/docs/components/nqui-checkbox.md` / `nqui-switch.md`.
+**Hit area** expands the pointer target; it does **not** replace the **size** scale. Use **opt-in** on **Checkbox** / **Switch** in padded rows—not globally. See `docs/nqui-skills/nqui-components/SKILL.md` and `docs/components/nqui-checkbox.md` / `nqui-switch.md`.
 
 ## Files to Check for Consistency
 
-- `packages/nqui/src/components/ui/button.tsx`
-- `packages/nqui/src/components/ui/toggle.tsx`
-- `packages/nqui/src/components/ui/toggle-group.tsx`
-- `packages/nqui/src/components/ui/input.tsx`
-- `packages/nqui/src/components/ui/select.tsx`
-- `packages/nqui/src/components/ui/combobox.tsx`
+- `src/components/ui/button.tsx`
+- `src/components/ui/toggle.tsx`
+- `src/components/ui/toggle-group.tsx`
+- `src/components/ui/input.tsx`
+- `src/components/ui/select.tsx`
+- `src/components/ui/combobox.tsx`
 
 ## Anti-Patterns
 

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

@@ -0,0 +1,65 @@
+---
+name: nqui-install
+description: Install and setup @nqlib/nqui. Use when the user wants to install nqui, set up a project, fix missing peers, or run setup commands. Execute these commands in the consumer project root.
+---
+
+# nqui Install & Setup
+
+**When to load:** User asks to install nqui, set up a new project, fix "module not found" or missing peer deps, or run setup.
+
+**Action:** Run the relevant command(s) below in the **consumer project root**, in order when doing full setup.
+
+## 1. Install nqui + peers
+
+**Minimal (icons only):**
+
+```bash
+pnpm add @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons
+```
+
+(npm: `npm install @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons`)
+
+**Full (all optional components):**
+
+```bash
+npx @nqlib/nqui install-peers
+```
+
+Or manually:
+
+```bash
+pnpm add @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons cmdk @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities embla-carousel-react @tanstack/react-table react-day-picker date-fns sonner vaul react-resizable-panels
+```
+
+## 2. Setup CSS (required)
+
+```bash
+npx @nqlib/nqui init-css
+```
+
+Then add to main CSS (`app/globals.css` or `src/index.css`): `@import "@nqlib/nqui/styles";`
+
+Or copy contents of `nqui/nqui-setup.css` to the top of main CSS.
+
+## 3. Cursor skills (optional)
+
+```bash
+npx @nqlib/nqui init-cursor
+```
+
+Copies `docs/nqui-skills` to `.cursor/nqui-skills/`, copies **`docs/components`** to **`.cursor/nqui-skills/components/`**, and may add rules. For skills only:
+
+```bash
+npx @nqlib/nqui init-skills
+```
+
+Use **`HUMAN_GUIDE.md`** for task-based wayfinding; **`COMPONENTS_INDEX.md`** to pick **one** `nqui-*.md` at a time (saves tokens).
+
+## File locations (after install)
+
+- Task → docs: `node_modules/@nqlib/nqui/docs/nqui-skills/HUMAN_GUIDE.md`
+- Docs index: `node_modules/@nqlib/nqui/docs/components/README.md`
+- Per component: `node_modules/@nqlib/nqui/docs/components/nqui-<name>.md`
+- Skills (source in repo): `docs/nqui-skills/` inside the package
+- Check setup: `npx nqui-setup` (or `npx @nqlib/nqui setup`)
+