---
description: nqui component implementation guide. Use when building UI with @nqlib/nqui.
globs: "**/*.{ts,tsx}"
alwaysApply: false
---

# nqui Component Guidelines

When building UI with @nqlib/nqui, follow these rules so the AI builds components correctly.

## Install (full: nqui + all optional peers)

Run this when setting up a new project or when components fail due to missing peers:

```bash
pnpm add @nqlib/nqui 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
```

Alternative (npm): `npm install @nqlib/nqui 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`

Or use `npx @nqlib/nqui install-peers` to auto-detect package manager.

## Import

```tsx
import { Button, ToggleGroup, ToggleGroupItem, Select } from "@nqlib/nqui"
```

**CSS:** `@import "@nqlib/nqui/styles"` (run `npx @nqlib/nqui init-css` first)

## CSS Setup (First-Run Fix)

`init-css` creates `nqui/index.css` and `nqui/nqui-setup.css` in the project root. **User must manually add the import** to their main CSS file. If nqui components render without styles or user reports "CSS import issue":

1. **Check** if the main CSS file has the nqui import. Main files: `app/globals.css` (Next.js), `src/index.css` (Vite), `app/root.css` (Remix).

2. **Fix options:**
   - **Option A (recommended):** Add `@import "@nqlib/nqui/styles";` near the top of the main CSS file (after `@import "tailwindcss"`).
   - **Option B:** If `nqui/nqui-setup.css` exists, copy its contents to the very top of the main CSS file.

3. **Next.js only:** Ensure `@source` directives exist for Tailwind v4:
   ```css
   @source "./**/*.{js,ts,jsx,tsx,mdx}";
   @source "../components/**/*.{js,ts,jsx,tsx,mdx}";
   @source "../node_modules/@nqlib/nqui/dist/**/*.js";
   ```

4. **Vite:** Simpler – just `@import "tailwindcss";` + `@import "tw-animate-css";` + `@import "@nqlib/nqui/styles";`

If user hasn't run init-css, suggest: `npx @nqlib/nqui init-css` then add the import as above.

## Component Selection Rules

### Inline/Toolbar Selection → ToggleGroup (never RadioGroup)

| Context | Use | NOT |
|---------|-----|-----|
| View mode (List/Grid), scale (Linear/Log), size (S/M/L) | **ToggleGroup** `type="single" variant="segmented"` | RadioGroup |
| Format toolbar (Bold/Italic/Underline) | **ToggleGroup** `type="multiple"` | Multiple Checkboxes |
| Toolbar actions (Undo/Redo) | **ButtonGroup** | — |
| Single on/off (Bold, Mute) | **Toggle** | — |

**Rule:** Inline/toolbar = ToggleGroup. RadioGroup only for form context (settings modal, stacked list).

### Quick Decision

- **ToggleGroup segmented** → 1 of N, 2–4 options, primary fill on selected
- **ToggleGroup single** → 1 of N, neutral styling
- **ToggleGroup multiple** → 0+ of N (bold/italic)
- **Select** → 1 of N, 5+ options or dropdown
- **ButtonGroup** → Actions (each click = action)
- **RadioGroup** → Form context only

## Context-First Design

**Rule:** Never show Toggle/ToggleGroup/ButtonGroup floating alone. Place in realistic context:
- Document editor: toolbar above content, `bg-muted/30`, `Separator` between groups
- Chart/settings: label + inline controls, `rounded-lg border bg-muted/30 p-3`

## Shared Conventions

- **Control sizes:** sm=h-6, default=h-7, lg=h-8
- **Enhanced vs Core:** Default is enhanced. Use `CoreButton`, `CoreBadge` for plain shadcn.
- **Z-index:** Use CSS vars only, e.g. `z-[var(--z-modal)]`. Never hardcode `z-10`, `z-50`.
- **Grouped controls:** ButtonGroup, ToggleGroup share container border; ToggleGroup uses item dividers.

## Skills (load for install or component questions)

- **Install/setup:** Load `.cursor/skills/nqui-install/SKILL.md` — commands to execute
- **Components:** Load `.cursor/skills/nqui-components/SKILL.md` — routing for per-component docs
- **After `init-skills`:** `.cursor/nqui-skills/COMPONENTS_INDEX.md` then **one** file under `.cursor/nqui-skills/components/nqui-<name>.md`

Fallback (no init-skills): `node_modules/@nqlib/nqui/docs/components/README.md` (index, skim sections) then `nqui-<name>.md`.