@nqlib/nqui 0.5.6 → 0.6.1

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

@@ -0,0 +1,148 @@
+---
+name: nqui-composition
+description: Compose nqui components into calm, product-quality screens. Use when building pages, layouts, or flows — not when looking up a single component's props. Apple-inspired craft (clarity, deference, depth). Pair with COMPOSITION.md patterns and RECIPES.md combos. Invoke before nqui-components for new views.
+---
+
+# nqui Composition — Apple-inspired Craft
+
+This skill is for **putting components together**, not for picking variants of one component (that's `nqui-components`). Read this *before* writing JSX for a new view. The goal is to make screens that feel deliberate, calm, and trustworthy — not busy, generic, or AI-flavored.
+
+## Three Apple principles, translated to nqui
+
+These come from Apple's Human Interface Guidelines but applied concretely to React + Tailwind component work.
+
+### 1. Clarity — content leads, chrome defers
+
+Everything on screen exists to serve the content. If chrome (borders, shadows, decorative panels, hover effects) competes with the content, the chrome loses.
+
+**Apply it:**
+- One typeface for UI text. Use weight and size for hierarchy, not extra families.
+- Borders are 1px and use `border-border` (subtle), never a 2-3px decorative accent.
+- The most prominent thing on screen should be the user's content, not the navigation.
+- Color is scarce. One accent (`primary`), one each for success/warning/error semantic tokens. That's it.
+- Icons are 16-20px in product UI. Bigger only when they ARE the content (empty states, hero illustrations).
+
+**Don't:**
+- Wrap every region in a Card "to give it structure" — structure comes from spacing and type, not from boxes.
+- Use multiple competing accent colors. A second "look at me" color cannibalizes the first.
+- Set body text below 14px or above 16px in product UI.
+
+### 2. Deference — UI yields to data
+
+The interface should disappear once the user understands it. After the first second, the user should be looking at *their stuff*, not at *your buttons*.
+
+**Apply it:**
+- Toolbars sit in `bg-muted/30` containers, not floating on `bg-background` (a floating toolbar is louder than the content below it).
+- Secondary actions are `variant="ghost"` or `variant="outline"`. Never two primaries.
+- Filter chips and segmented controls use the subtlest treatment that still reads — `bg-muted` for off-state, `bg-accent` for on-state, no shadows.
+- Empty states are quiet. A small icon, one sentence, one action. Not a marketing illustration.
+- Loading states (`Skeleton`) match the shape of the content they replace — not a generic spinner that demands attention.
+
+**Don't:**
+- Animate everything. Motion that doesn't serve comprehension is noise.
+- Apply `shadow-lg` to flat surfaces. Shadows imply elevation; on a flat element they read as decoration, not affordance.
+- Use `font-bold` on labels, metadata, or supporting text. Bold is for the thing the user came to read.
+
+### 3. Depth — layers must mean something
+
+Apple uses depth (translucency, layering, motion) to signal hierarchy: which surface is closer, which is further, what's modal vs ambient. nqui uses the same logic with `z-index` tokens and surface backgrounds.
+
+**Apply it:**
+- Z-index comes from `elevation.css` semantic tokens (`--z-sticky-page`, `--z-modal`, `--z-popover`). Never raw numbers.
+- Three-layer surface logic in master-detail or split views: outer wrapper (`bg-muted/20`), panels (`bg-background`), inside cards or selected items (`bg-accent/70`). The contrast IS the separation.
+- Modals, sheets, and popovers cast subtle shadows because they're physically "above" the page. Inline cards don't, because they're flat.
+- Motion conveys depth: a Sheet slides in from the edge (it came from outside), a Dialog fades + scales (it appeared in place).
+
+**Don't:**
+- Use `backdrop-blur` on inline content (it's a depth signal — reserve for overlays and sticky headers over scroll).
+- Nest cards inside cards. If you need a sub-region, use spacing and a `Separator`, not another bordered box.
+- Apply z-index tokens for ordering elements that aren't elevated — they cause stacking-context bugs.
+
+## The composition checklist (run before writing JSX)
+
+1. **What is the one outcome on this screen?** Write it down in five words.
+2. **What is the single primary action?** Everything else is secondary.
+3. **What can move off this view?** A sheet, a route, a hover card, an "advanced" section.
+4. **How many surfaces?** Cap at three (chrome + primary + optional secondary). If you have more, you have too many.
+5. **What is the canonical empty state?** What is the loading state? What is the error state? Skip this and the UI will leak placeholder lorem text.
+6. **What's the responsive breakdown?** Below what container width does this collapse to a single column / Sheet?
+
+If you can't answer all six in under a minute, you don't understand the screen yet. Don't start coding.
+
+## Decision rules baked in
+
+These are not stylistic suggestions — they are rules:
+
+| Situation | Rule |
+|-----------|------|
+| Inline selection (mode, format, view-type) | `ToggleGroup`, never `RadioGroup` |
+| Form with >5 fields | Use `Sheet` or a dedicated route, never a `Dialog` |
+| Destructive confirm | `AlertDialog`, never `Dialog` |
+| Master-detail under ~900px container width | Switch detail to `Sheet`, don't shrink both panels |
+| Status indicator | `Badge` (or a 6-8px colored dot), never `border-left: 4px` stripe |
+| Loading | `Skeleton` shaped like the content, not a `Spinner` |
+| Empty | `Empty` component, not a stylized div |
+| Toolbar | `bg-muted/30` container with internal `Separator` for groups |
+| Page chrome height | `h-12` (48px) — for header bars and section headers |
+| Default control size | `sm` for dense product UI, `default` for marketing/forms |
+
+## Hierarchy without dependence on color
+
+Apple's interfaces look intentional largely because they get hierarchy from **type weight, size, spacing, and proximity** before reaching for color. nqui defaults support this:
+
+- **Most important**: `text-base font-semibold text-foreground` (or `text-lg`/`text-xl` for page H1)
+- **Standard reading**: `text-sm text-foreground`
+- **Supporting / metadata**: `text-xs text-muted-foreground` or `text-sm text-muted-foreground`
+- **Labels / categories**: `text-xs uppercase tracking-wider text-muted-foreground font-semibold`
+- **Numeric data**: add `tabular-nums` so numbers align
+
+Spacing rhythm: 8 → 12 → 16 → 24 → 32 → 48. Tight inside related groups (8-12), generous between sections (24-48). The variation IS the hierarchy.
+
+## Elevation — the 2+1 surface rule
+
+**Cap inline nesting at 2 surfaces.** Past that, spacing + type weight + occasional Separator carry the hierarchy. One additional `surface-elevated` is reserved for overlays (modals, sheets, popovers). This is the entire elevation system — see `../ELEVATION.md` for the full rule + decision tree.
+
+| Depth | Carrier |
+|-------|---------|
+| Page → card | Surface flip (A → B) |
+| Card → sub-section | Spacing + uppercase label, NOT a new shade |
+| Section → sub-detail | More spacing + type weight, NOT a new shade |
+| Modal over content | `surface-elevated` (the only legitimate third) |
+
+**When tempted to add a third inline surface:** more space, a stronger label, or move it to a sheet/route. Never a new shade.
+
+## Surface vocabulary (when to use which container)
+
+| Surface | When | Avoid for |
+|---------|------|-----------|
+| `Card` | Bounded topic with its own title (Team members, Shipping address, Chart) | A single button, a filter chip, page-level layout |
+| `Item` (ghost variant) | A row in a list — issue, file, message, contact | Standalone content blocks |
+| `Item` (outline variant) | A row that needs to read as a tappable card | Lists where rows share a topic and proximity already groups them |
+| `Sheet` | Side panel for filters, detail view, inline forms | Confirmations, single-input prompts |
+| `Dialog` | Focused task requiring input (create record, edit small form) | Anything destructive |
+| `AlertDialog` | Destructive or irreversible confirmation only | Informational alerts |
+| `Popover` | Quick contextual content tied to a trigger element | Long content, anything with its own scroll |
+| `Drawer` | Mobile-first bottom sheet (gesture-heavy) | Desktop primary patterns |
+| `HoverCard` | Optional preview information on hover (link preview, user card) | Anything critical to the task |
+
+## What "Apple-quality" actually looks like in practice
+
+The shorthand "make it look like Apple" usually means three things, in order:
+
+1. **More space than you think you need.** Padding is generosity. Cramped UIs read as cheap.
+2. **Fewer styles, applied more consistently.** Two button variants used everywhere beat six used inconsistently.
+3. **Honest materials.** Glass surfaces over scroll. Solid surfaces in flat regions. Shadows for things that are physically above. Don't mix metaphors.
+
+If you reach for `shadow-2xl`, `bg-gradient-to-br`, `backdrop-blur`, or a fourth typeface — stop and revisit. None of those are necessary for a screen to look refined. Restraint is the technique.
+
+## Files to load next
+
+| Need | Open |
+|------|------|
+| A blueprint for the screen type (settings, dashboard, master-detail, wizard, command, dialog) | `../COMPOSITION.md` |
+| Combos: "I need to do X, what components together?" | `../RECIPES.md` |
+| Specific component props/variants | `../components/nqui-<name>.md` |
+| Sizing, spacing tokens, scroll patterns | `../nqui-design-system/SKILL.md` |
+| Brand voice / typography / color depth | `../impeccable/SKILL.md` (one time per conversation) |
+
+Do not bulk-read. See `../READ_BUDGET.md`.

package/docs/nqui-skills/nqui-data-tables/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: nqui-data-tables
+description: One-shot TanStack or native HTML data tables with nqui ScrollArea — bounded card height, sticky header, horizontal+vertical scroll, flex height chain, viewport pinning, optional infinite scroll or paged Back/Next. Use for dashboards, dense grids, portfolio views.
+---
+
+# nqui Data Tables (ScrollArea + flex)
+
+Single playbook to ship a **card-wrapped** table that scrolls **inside** the card (sticky header, many columns) without overlapping a **footer** below the grid.
+
+## Load order (save tokens)
+
+1. **`docs/components/nqui-scroll-area.md`** — **§0** symptom routing (Card, Sheet, sidebar), flex height chain §1, pitfalls §2–§5, **`§6` Data tables / wide grids** (`orientation="both"`, `h-0 flex-1`, `viewportStyle` pin), `viewportRef`.
+2. **`nqui-design-system/SKILL.md`** — **Card + ScrollArea** contract, `min-h-0`, spacing, control sizes.
+3. **`nqui-components`** — imports for `ScrollArea`, `Table*`, `Button`, `cn`.
+
+## One-shot structure
+
+```
+<div className={tableShellClass}>           // capped column flex + clip
+  <ScrollArea …>                            // flex child: scroll slot
+    <div className={tablePaddingClass}>     // px inside scrollport
+      <table>… sticky thead … tbody …</table>
+      {/* optional infinite-scroll sentinel */}
+    </div>
+  </ScrollArea>
+  <div className={tableFooterClass}>…</div> // shrink-0, outside ScrollArea
+</div>
+```
+
+### 1) Shell (`tableShellClass`)
+
+Use **one** outer wrapper for `ScrollArea` + footer:
+
+- **`flex flex-col overflow-hidden`** — column stack; clip bleed.
+- **`min-h-[18rem]`** (tune) — floor so `flex-1` children get real height when data is short.
+- **`max-h-[min(84dvh,calc(100dvh-8rem))]`** (tune) — ceiling so tall data **must** scroll inside.
+- **`rounded-2xl border border-border bg-card`** — nqui card surface.
+
+**Per-table height:** merge extra utilities with `cn(tableShellClass, extra)` (e.g. taller Operations desk) instead of changing the default for every table.
+
+### 2) ScrollArea root classes
+
+```txt
+h-0 max-h-full min-h-0 min-w-0 flex-1 overflow-hidden w-full
+```
+
+- **`h-0` + `flex-1`** — flex-column pattern so this child receives a **definite** main-axis size (avoids `min-height: auto` content blow-through).
+- **`overflow-hidden`** — keeps Radix layout clipped to the slot.
+
+### 3) ScrollArea props (data grids)
+
+```tsx
+<ScrollArea
+  orientation="both"   // default "vertical" uses overflow-x-hidden — breaks wide <table>
+  fadeMask={false}     // dense grids: skip edge fade masks over cells
+  className={tableScrollAreaRootClass}
+  viewportRef={viewportRef}              // optional: IO root, scrollTop
+  viewportStyle={tableScrollViewportStyle}
+>
+```
+
+### 4) `viewportStyle` — pin Radix viewport (critical)
+
+**Do not rely on `height: 100%` / `maxHeight: 100%` alone** on the viewport in flex-heavy trees: the viewport can still **grow to content height**, cover the footer, and show **no** vertical scroll (`clientHeight === scrollHeight`).
+
+Export a shared object (TypeScript `CSSProperties`):
+
+```ts
+export const tableScrollViewportStyle: CSSProperties = {
+  position: "absolute",
+  inset: 0,
+  minHeight: 0,
+  minWidth: 0,
+  overscrollBehavior: "contain",
+};
+```
+
+Enhanced `ScrollArea` root is **`relative`** — absolute viewport fills that box.
+
+### 5) Padding inside the scrollport
+
+Wrap the `<table>` in **`px-4 pt-0`** (or project rhythm) so horizontal scroll and sticky headers align with card padding.
+
+### 6) Sticky `<thead>`
+
+- Header cells: **`sticky top-0 z-20 bg-card`** + border token bottom edge.
+- Sticky **lead columns** (optional): **`sticky left-*`** with header `z` above body `z`; use **opaque** `bg-card` / `bg-muted` so cells don’t show through.
+
+### 7) Footer
+
+- **`shrink-0`** (included in typical `tableFooterClass` patterns).
+- Keep counts, pagination, CSV actions **here** — not inside `ScrollArea`.
+
+## Flex ancestors
+
+Put **`min-h-0`** / **`min-w-0`** on **every** flex ancestor between the page root and the table card when the page itself is also flex + scroll. See **§1 Flex / resizable panels** in `nqui-scroll-area.md`.
+
+## Infinite scroll (optional)
+
+1. Pass Radix **viewport** node as `IntersectionObserver` **`root`** (`viewportRef` callback or ref merge).
+2. Place a **sentinel** `<div className="h-1 shrink-0" />` after `<table>` inside the padded wrapper.
+3. Reset visible row window when **data / sort / filters** change.
+
+## Paged Back / Next (optional)
+
+- No sentinel. **`useState(page)`** + **`rows.slice(page * PAGE_SIZE, …)`**.
+- Reset **`page`** to `0` on data/sort change; clamp when `rows.length` shrinks.
+
+## Anti-patterns
+
+| Don’t | Why |
+|-------|-----|
+| `orientation="vertical"` only + `min-w-[1200px]` table | Horizontal scroll is suppressed in nqui’s vertical mode. |
+| `flex-1` ScrollArea without `h-0` / `min-h-0` chain | Viewport grows with rows; footer overlap or no scroll. |
+| Nested `ScrollArea` in expanded rows | Prefer `overflow-auto` on inner panels. |
+| Two accidental scroll roots (card + inner) without `max-h` | Double scrollbars / layout fights. |
+
+## Definition of done (quick verify)
+
+- With many rows: **`viewport.scrollHeight > viewport.clientHeight`** and wheel scroll moves **`scrollTop`**.
+- Footer stays **below** the scroll clip; no overlap at rest.
+- Wide table: horizontal scrollbar appears when **`table` min-width** exceeds viewport.
+
+## SSOT paths
+
+- Package skills: `packages/nqui/docs/nqui-skills/nqui-data-tables/SKILL.md` (this file).
+- After `npx @nqlib/nqui init-skills`: `.cursor/nqui-skills/nqui-data-tables/SKILL.md` in consumer repos.

package/docs/nqui-skills/nqui-design-system/SKILL.md

@@ -1,12 +1,24 @@
 ---
 name: nqui-design-system
-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).
+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). Pair with nqui-data-tables for dashboard table shells.
 ---
 
 # nqui Design System
 
 Guidelines for AI agents and developers implementing or modifying nqui components. Follow these rules to maintain visual consistency.
 
+## Elevation — 2 inline surfaces + 1 elevated (mandatory)
+
+nqui uses a **hybrid elevation model**: 2 alternating inline surface tokens + 1 elevated surface for overlays. Spacing and type weight carry hierarchy beyond 2 surfaces. Full philosophy + decision tree in `../ELEVATION.md`.
+
+| Token | Tailwind | When |
+|-------|----------|------|
+| `surface-a` | `bg-background` | Page, alternates with B |
+| `surface-b` | `bg-muted/40` | Card/panel/distinct topic region |
+| `surface-elevated` | `bg-popover` + `shadow-lg` | Modals, sheets, popovers (the only legitimate third surface) |
+
+**Hard cap: 2 nested inline surfaces.** If you reach for a third shade, use spacing (`gap-6` between sections) + an uppercase label (`text-xs uppercase tracking-wider`) instead. A third nested surface is almost always a symptom of weak composition.
+
 ## Control Size Scale
 
 All interactive controls (buttons, toggles, inputs, selects) use a unified scale:
@@ -132,6 +144,14 @@ Never use flat `bg-muted` only for selected state; always add gradient + shadow
 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.
 
+**Applies beyond Card:** **Sheet** / **Drawer** body, **sidebar** columns, **dashboard** panes, and **resizable** splits use the **same** contract — one **`flex flex-col min-h-0 overflow-hidden`** shell that owns the clip, **chrome** (`header`, tabs, toolbars) as **`shrink-0`**, scroll body in **`flex-1 min-h-0`**. Symptom → fix routing: **`docs/components/nqui-scroll-area.md` §0**.
+
+**Data tables / wide grids (same failure modes, stricter recipe):**
+
+- **`orientation="both"`** — default **`vertical`** uses **`overflow-x-hidden`** on the viewport; a **`min-w-*`** `<table>` then **cannot** scroll horizontally. See **`docs/components/nqui-scroll-area.md` §6**.
+- **ScrollArea root in a capped flex column:** **`h-0 max-h-full min-h-0 min-w-0 flex-1 overflow-hidden w-full`** so flex assigns a **finite** slot (not content-height blow-through).
+- **`viewportStyle`:** **`position: "absolute"`, `inset: 0`, `minHeight: 0`, `minWidth: 0`** — **`height: 100%`** on the Radix viewport often **does not bind** in deep flex layouts; the viewport then grows with content and overlaps a footer below. See **`docs/components/nqui-scroll-area.md` §6** and **`docs/nqui-skills/nqui-data-tables/SKILL.md`**.
+
 **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:**
@@ -140,6 +160,7 @@ Never use flat `bg-muted` only for selected state; always add gradient + shadow
 - [ ] 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`**).
+- [ ] **Wide table in ScrollArea:** **`orientation="both"`** + **`viewportStyle`** absolute fill if `%` height failed (see component doc §6).
 
 ## Density & visual hierarchy (product feel)
 

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

@@ -51,6 +51,7 @@ Copies `docs/nqui-skills` to `.cursor/nqui-skills/`, copies **`docs/components`*
 
 ```bash
 npx @nqlib/nqui init-skills
+npx @nqlib/nqui init-claude-skills
 ```
 
 Use **`HUMAN_GUIDE.md`** for task-based wayfinding; **`COMPONENTS_INDEX.md`** to pick **one** `nqui-*.md` at a time (saves tokens).

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

@@ -15,9 +15,12 @@ Start your response with:
 
 Push an interface past conventional limits. This isn't just about visual effects — it's about using the full power of the browser to make any part of an interface feel extraordinary: a table that handles a million rows, a dialog that morphs from its trigger, a form that validates in real-time with streaming feedback, a page transition that feels cinematic.
 
-## MANDATORY PREPARATION
+## Context check (lightweight)
 
-Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first.
+Before proceeding, ensure design context is loaded:
+- If `.impeccable.md` exists in project root, the project context is set — DO NOT re-invoke /impeccable.
+- If `.impeccable.md` is missing, run `/impeccable teach` ONCE to create it.
+- For depth on one topic only, see `impeccable/reference/INDEX.md` and load ONE file.
 
 **EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That's extraordinary too. Understand the project's personality and goals before deciding what's appropriate.
 

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

@@ -6,11 +6,12 @@ user-invocable: true
 argument-hint: "[target]"
 ---
 
-## MANDATORY PREPARATION
+## Context check (lightweight)
 
-Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: quality bar (MVP vs flagship).
-
----
+Before proceeding, ensure design context is loaded:
+- If `.impeccable.md` exists in project root, the project context is set — DO NOT re-invoke /impeccable.
+- If `.impeccable.md` is missing, run `/impeccable teach` ONCE to create it.
+- For depth on a specific topic, see `impeccable/reference/INDEX.md` and load ONE file.
 
 Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished.
 

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

@@ -8,9 +8,12 @@ argument-hint: "[target]"
 
 Reduce visual intensity in designs that are too bold, aggressive, or overstimulating, creating a more refined and approachable aesthetic without losing effectiveness.
 
-## MANDATORY PREPARATION
+## Context check (lightweight)
 
-Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first.
+Before proceeding, ensure design context is loaded:
+- If `.impeccable.md` exists in project root, the project context is set — DO NOT re-invoke /impeccable.
+- If `.impeccable.md` is missing, run `/impeccable teach` ONCE to create it.
+- For depth on one topic only, see `impeccable/reference/INDEX.md` and load ONE file.
 
 ---
 

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

@@ -6,9 +6,12 @@ user-invocable: true
 argument-hint: "[feature to shape]"
 ---
 
-## MANDATORY PREPARATION
+## Context check (lightweight)
 
-Invoke /impeccable, which contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. If no design context exists yet, you MUST run /impeccable teach first.
+Before proceeding, ensure design context is loaded:
+- If `.impeccable.md` exists in project root, the project context is set — DO NOT re-invoke /impeccable.
+- If `.impeccable.md` is missing, run `/impeccable teach` ONCE to create it.
+- For depth on one topic only, see `impeccable/reference/INDEX.md` and load ONE file.
 
 ---
 

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

@@ -8,9 +8,12 @@ argument-hint: "[target]"
 
 Assess and improve typography that feels generic, inconsistent, or poorly structured — turning default-looking text into intentional, well-crafted type.
 
-## MANDATORY PREPARATION
+## Context check (lightweight)
 
-Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first.
+Before proceeding, ensure design context is loaded:
+- If `.impeccable.md` exists in project root, the project context is set — DO NOT re-invoke /impeccable.
+- If `.impeccable.md` is missing, run `/impeccable teach` ONCE to create it.
+- For depth on one topic only, see `impeccable/reference/INDEX.md` and load ONE file.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nqlib/nqui",
-  "version": "0.5.6",
+  "version": "0.6.1",
   "description": "A React component library with enhanced UI components and developer tools",
   "type": "module",
   "main": "./dist/nqui.cjs.js",
@@ -118,6 +118,7 @@
     "nqui-init-css": "scripts/init-css.js",
     "nqui-init-cursor": "scripts/init-cursor.js",
     "nqui-init-skills": "scripts/download-skills.js",
+    "nqui-init-claude-skills": "scripts/install-claude-skills.js",
     "nqui-install-peers": "scripts/install-peers.js",
     "nqui-init-debug": "scripts/init-debug-css.js",
     "nqui-setup": "scripts/post-install.js"

package/scripts/build-styles.js

@@ -103,7 +103,8 @@ function extractStandaloneCSS() {
   // These need to be preserved in the final output for zero-config setup
   // Match pattern: /* comment */ @source inline( ... ); (multiline)
   // Tailwind v4 requires: @source inline("class1 class2 class3");
-  const sourceInlineRegex = /\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/\s*@source\s+inline\([\s\S]*?\)\s*;/g;
+  // Match only real directives (not comments that mention "@source inline")
+  const sourceInlineRegex = /\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/\s*@source\s+inline\("[^"]*"\)\s*;/g;
   const sourceInlineMatches = indexCss.match(sourceInlineRegex) || [];
   
   // Convert multiline format to single-line format required by Tailwind v4
@@ -145,10 +146,10 @@ function extractStandaloneCSS() {
     .replace(/\/\*\s*Import elevation system\s*\*\//g, '')
     .replace(/\/\*\s*Hit-area utilities \(expanded pointer targets\)\s*\*\/\s*\n/g, '')
     // Remove @source inline() directives (already extracted above) - must match multiline
-    .replace(/\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/\s*@source\s+inline\([\s\S]*?\)\s*;/g, '')
+    .replace(/\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/\s*@source\s+inline\("[^"]*"\)\s*;/g, '')
     // Remove other @source directives (non-inline ones)
     .replace(/@source\s+(?!inline\()[^;]+;?\s*\n/g, '')
-    .replace(/@custom-variant\s+[^;]+;?\s*\n/g, '');
+    .replace(/@custom-variant\s+[^\n]+;\s*\n/g, '');
 
   if (hitAreaCss) {
     indexCss = indexCss.replace(

package/scripts/cli.js

@@ -6,6 +6,7 @@
  * Usage:
  *   npx @nqlib/nqui init-css [output.css]
  *   npx @nqlib/nqui init-cursor
+ *   npx @nqlib/nqui init-claude-skills
  *   npx @nqlib/nqui install-peers
  *   npx @nqlib/nqui init-debug
  *   npx @nqlib/nqui setup
@@ -21,6 +22,7 @@ const subcommand = process.argv[2];
 const routes = {
   'init-cursor': './init-cursor.js',
   'init-skills': './download-skills.js',
+  'init-claude-skills': './install-claude-skills.js',
   'install-peers': './install-peers.js',
   'init-debug': './init-debug-css.js',
   'init-debug-css': './init-debug-css.js',

package/scripts/install-claude-skills.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * Install nqui skills for Claude Code / Claude Desktop.
+ *
+ * Usage: npx @nqlib/nqui init-claude-skills [--force]
+ *
+ * Copies packages/nqui/docs/nqui-skills/* → ~/.claude/skills/<skill-name>/
+ * Hub markdown → ~/.claude/skills/nqui/
+ * Component docs → ~/.claude/skills/nqui-components/components/
+ */
+
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { getPackageRoot } from './getPackageRoot.js';
+
+const root = getPackageRoot();
+const SKILLS_SOURCE = join(root, 'docs', 'nqui-skills');
+const COMPONENTS_SOURCE = join(root, 'docs', 'components');
+const CLAUDE_SKILLS = join(homedir(), '.claude', 'skills');
+
+// Root docs that live in the nqui hub directory (~/.claude/skills/nqui/)
+const HUB_FILES = [
+  'SKILL.md',
+  'README.md',
+  'HUMAN_GUIDE.md',
+  'COMPOSITION.md',
+  'COMPONENTS_INDEX.md',
+  'READ_BUDGET.md',
+  // Apple-craft + production AI skills (v0.6+)
+  'RECIPES.md',
+  'STATES.md',
+  'WRITING.md',
+  'MOTION.md',
+  'ELEVATION.md',
+  'AGENT_PROMPT.md',
+  'EVAL.md',
+  'THEMING.md',
+  'MIGRATION.md',
+];
+
+// Slash-command entry points (/design, /edit) — bundled in docs/_claude-commands/
+const SLASH_COMMANDS = ['design', 'edit'];
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+function isSkillDir(name) {
+  const path = join(SKILLS_SOURCE, name);
+  return statSync(path).isDirectory() && existsSync(join(path, 'SKILL.md'));
+}
+
+function patchHubSkill(destSkillPath) {
+  let content = readFileSync(destSkillPath, 'utf8');
+  content = content.replace(
+    /Installed into `\.cursor\/nqui-skills\/` via `npx @nqlib\/nqui init-skills`\./,
+    'Installed into `~/.claude/skills/` via `npx @nqlib/nqui init-claude-skills`.',
+  );
+  content = content.replace(
+    /- `\.cursor\/nqui-skills\/components\/nqui-<name>\.md` \(after init-skills\)/,
+    '- `~/.claude/skills/nqui-components/components/nqui-<name>.md`',
+  );
+  content = content.replace(
+    /SSOT: `packages\/nqui\/docs\/nqui-skills\/`/,
+    'SSOT: `packages/nqui/docs/nqui-skills/` (repo) · installed: `~/.claude/skills/`',
+  );
+  writeFileSync(destSkillPath, content);
+}
+
+export async function installClaudeSkills({ force = true } = {}) {
+  if (!existsSync(SKILLS_SOURCE)) {
+    console.error('Source skills not found:', SKILLS_SOURCE);
+    process.exit(1);
+  }
+
+  ensureDir(CLAUDE_SKILLS);
+
+  const hubDest = join(CLAUDE_SKILLS, 'nqui');
+  if (existsSync(hubDest) && !force) {
+    console.log('⏭️  ~/.claude/skills/nqui exists. Use --force to overwrite.');
+  } else {
+    ensureDir(hubDest);
+    for (const file of HUB_FILES) {
+      const src = join(SKILLS_SOURCE, file);
+      if (existsSync(src)) cpSync(src, join(hubDest, file), { force: true });
+    }
+    patchHubSkill(join(hubDest, 'SKILL.md'));
+    console.log('✅ Hub →', hubDest);
+  }
+
+  for (const name of readdirSync(SKILLS_SOURCE)) {
+    if (!isSkillDir(name)) continue;
+    const dest = join(CLAUDE_SKILLS, name);
+    if (existsSync(dest) && !force) {
+      console.log(`⏭️  ${name} — use --force to overwrite`);
+      continue;
+    }
+    cpSync(join(SKILLS_SOURCE, name), dest, { recursive: true, force: true });
+    console.log('✅', name, '→', dest);
+  }
+
+  // Per-component docs go in the hub at nqui/components/ (where AGENT_PROMPT.md
+  // and READ_BUDGET.md route to). Also keep a copy at nqui-components/components/
+  // for backward compatibility with the previous routing.
+  if (existsSync(COMPONENTS_SOURCE)) {
+    const hubComponentsDest = join(CLAUDE_SKILLS, 'nqui', 'components');
+    const legacyComponentsDest = join(CLAUDE_SKILLS, 'nqui-components', 'components');
+    if (existsSync(hubComponentsDest) && !force) {
+      console.log('⏭️  nqui/components — use --force to overwrite');
+    } else {
+      ensureDir(join(CLAUDE_SKILLS, 'nqui'));
+      cpSync(COMPONENTS_SOURCE, hubComponentsDest, { recursive: true, force: true });
+      console.log('✅ Component docs →', hubComponentsDest);
+    }
+    if (existsSync(join(CLAUDE_SKILLS, 'nqui-components'))) {
+      cpSync(COMPONENTS_SOURCE, legacyComponentsDest, { recursive: true, force: true });
+    }
+  }
+
+  // Slash command entry points — /design and /edit become Claude Code tools
+  const slashSrc = join(SKILLS_SOURCE, '_claude-commands');
+  if (existsSync(slashSrc)) {
+    for (const cmd of SLASH_COMMANDS) {
+      const cmdSrc = join(slashSrc, cmd);
+      const cmdDest = join(CLAUDE_SKILLS, cmd);
+      if (!existsSync(cmdSrc)) continue;
+      if (existsSync(cmdDest) && !force) {
+        console.log(`⏭️  /${cmd} — use --force to overwrite`);
+        continue;
+      }
+      cpSync(cmdSrc, cmdDest, { recursive: true, force: true });
+      console.log(`✅ /${cmd} →`, cmdDest);
+    }
+  }
+
+  console.log('\n📚 Claude skills installed under ~/.claude/skills/');
+  console.log('   Restart Claude Code or Claude Desktop to pick them up.');
+  console.log('   Try: /design [a login form]    — build a new screen');
+  console.log('        /edit  [the sprint page]  — refine existing UI');
+  console.log('   Hub: /nqui · Components: /nqui-components · Tokens: /nqui-design-system');
+}
+
+const force = process.argv.includes('--force') || !process.argv.includes('--no-force');
+installClaudeSkills({ force }).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});