@nqlib/nqui 0.5.6 → 0.6.0

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

@@ -8,9 +8,12 @@ argument-hint: "[target]"
 
 Analyze a feature and strategically add animations and micro-interactions that enhance understanding, provide feedback, and create delight.
 
-## 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: performance constraints.
+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. Additionally gather: performance constraints.
 
 ---
 

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

@@ -6,9 +6,12 @@ user-invocable: true
 argument-hint: "[area (feature, page, component...)]"
 ---
 
-## 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/bolder/SKILL.md

@@ -8,9 +8,12 @@ argument-hint: "[target]"
 
 Increase visual impact and personality in designs that are too safe, generic, or visually underwhelming, creating more engaging and memorable experiences.
 
-## 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/clarify/SKILL.md

@@ -8,9 +8,12 @@ argument-hint: "[target]"
 
 Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use.
 
-## 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: audience technical level and users' mental state in context.
+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. Additionally gather: audience technical level and users' mental state in context.
 
 ---
 

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

@@ -8,9 +8,12 @@ argument-hint: "[target]"
 
 Strategically introduce color to designs that are too monochromatic, gray, or lacking in visual warmth and personality.
 
-## 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: existing brand colors.
+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. Additionally gather: existing brand colors.
 
 ---
 

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

@@ -8,11 +8,12 @@ argument-hint: "[target]"
 
 Identify opportunities to add moments of joy, personality, and unexpected polish that transform functional interfaces into delightful experiences.
 
-## 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: what's appropriate for the domain (playful vs professional vs quirky vs elegant).
-
----
+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.
 
 ## Assess Delight Opportunities
 

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

@@ -8,9 +8,12 @@ argument-hint: "[target]"
 
 Remove unnecessary complexity from designs, revealing the essential elements and creating clarity through ruthless simplification.
 
-## 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/impeccable/SKILL.md

@@ -7,22 +7,6 @@ argument-hint: "[craft|teach|extract]"
 license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution.
 ---
 
-<post-update-cleanup>
-BEFORE doing any design work, run this one-time maintenance step. Tell the user:
-
-> **Impeccable was updated.** A few skills were renamed or merged in this version (e.g. `/arrange` is now `/layout`, `/normalize` was folded into `/polish`). I'll clean up the old skill files so they don't clutter your project. This only runs once after an update.
-
-Then run:
-
-```bash
-node .agents/skills/impeccable/scripts/cleanup-deprecated.mjs
-```
-
-If the script removed files, briefly confirm what was cleaned up. If it found nothing, skip any output and move on.
-
-After running the script, delete this entire section (from `<post-update-cleanup>` through `</post-update-cleanup>` inclusive) from THIS file so it does not run again until the next update. Save the file.
-</post-update-cleanup>
-
 This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
 
 ## Context Gathering Protocol

package/docs/nqui-skills/impeccable/reference/INDEX.md

@@ -0,0 +1,26 @@
+---
+name: impeccable-reference-index
+description: One-line summary of each impeccable reference file. Read this before opening any reference file so you load only the topic you need (never all 8).
+---
+
+# Impeccable reference — pick ONE
+
+The main `impeccable/SKILL.md` covers principles inline. Open a reference file ONLY when you need depth on that specific topic. Never load multiple references at once.
+
+| File | Lines | Load when |
+|------|-------|-----------|
+| `typography.md` | 142 | Picking fonts, modular scale ratios, OpenType features, web font loading, line-length calculations |
+| `color-and-contrast.md` | 105 | OKLCH details, WCAG contrast calculation, palette construction beyond the inline `<color_principles>` |
+| `spatial-design.md` | 100 | Grid systems, container queries, optical centering, fluid spacing math |
+| `motion-design.md` | 99 | Easing curves, reduced-motion patterns, timing values, transform-vs-layout details |
+| `interaction-design.md` | 195 | Form patterns, focus management, loading-state choreography, progressive disclosure depth |
+| `responsive-design.md` | 114 | Mobile-first patterns, container queries vs viewport queries, fluid design math |
+| `ux-writing.md` | 107 | Labels, error messages, empty-state copy, button text patterns |
+| `craft.md` | 70 | The `craft` mode flow (only when invoked via `/impeccable craft`) |
+| `extract.md` | 70 | The `extract` mode flow (only when invoked via `/impeccable extract`) |
+
+## Rules
+
+1. **One file per task.** If you need typography AND color, do typography first, finish the task, then color if still needed.
+2. **Skip if inline principle is enough.** `impeccable/SKILL.md` has `<typography_principles>`, `<color_principles>`, `<spatial_principles>` blocks that often answer the question without opening the reference.
+3. **`craft.md` and `extract.md` are mode-only** — never load unless the user typed `/impeccable craft` or `/impeccable extract`.

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

@@ -8,9 +8,12 @@ argument-hint: "[target]"
 
 Assess and improve layout and spacing that feels monotonous, crowded, or structurally weak — turning generic arrangements into intentional, rhythmic compositions.
 
-## 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/nqui-components/SKILL.md

@@ -33,18 +33,33 @@ When designing app UI (toolbars, headers, inline controls):
 
 | 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 |
+| Document editor | Toolbar above content; `bg-muted/30` container; `Separator` between groups | `/catalog` → Toggle & ToggleGroup |
+| Chart/settings | Label + inline controls; `rounded-lg border bg-muted/30 p-3` | `/catalog` → Chart settings |
+| Standalone | Inline with related UI | `/catalog` → Standalone toggle |
 
-**Canonical implementation:** ComponentShowcase (from nqui package) — Toggle & ToggleGroup section. All app designs must follow this pattern.
+**Canonical implementation:** `/catalog` Toggle section, or full pages at `/patterns` and `/recipes/settings`.
+
+## Composition (product UI)
+
+Before picking components, read **`../COMPOSITION.md`** (or `docs/nqui-skills/COMPOSITION.md`). Dev app: **Recipes** at `/`, catalog at `/catalog`.
+
+### Pre-ship checklist
+
+- [ ] One user goal and primary action on the screen
+- [ ] ≤3 major surfaces (chrome + primary + optional secondary)
+- [ ] Toolbars use ToggleGroup in context (`bg-muted/30`), not isolated in Cards
+- [ ] Forms use FieldSet + FieldGroup (not a card per field)
+- [ ] Cards only for bounded topics, not every control
+- [ ] Loading / empty / error states use Skeleton, Empty, Alert
 
 ## Quick Reference
 
-1. **Main index:** `./README.md` – all components, use cases, prerequisites
-2. **Per-component:** `./nqui-<name>.md` – import, examples, variants
-3. **Design system:** `.cursor/skills/nqui-design-system/SKILL.md` – sizing, grouped controls
-4. **Layout & Scroll Patterns:** `./README.md` – custom scroll container, sticky element z-index, flex scroll pattern, momentum scroll prevention
+1. **Composition:** `../COMPOSITION.md` – when to assemble, not just which component
+2. **Main index:** `./README.md` – all components, use cases, prerequisites
+3. **Per-component:** `./nqui-<name>.md` – import, examples, variants
+4. **Design system:** `.cursor/skills/nqui-design-system/SKILL.md` – sizing, grouped controls, **Card + ScrollArea** (any bounded panel)
+5. **Scroll / flex / overflow:** `docs/components/nqui-scroll-area.md` – **§0** symptom routing, §1–§6 pitfalls, **`viewportStyle`**, **`orientation`**
+6. **Layout index:** `./README.md` – custom scroll container, sticky z-index, momentum scroll prevention
 
 ## Key Conventions
 
@@ -55,7 +70,11 @@ When designing app UI (toolbars, headers, inline controls):
 
 ## Layout Pattern: Card + ScrollArea + flex min-h-0 scroll
 
-When a component demo is placed inside a `Card` (which itself lives in a responsive grid), the card content must not overflow its boundary. Use this exact pattern:
+When a component demo is placed inside a `Card` (which itself lives in a responsive grid), the card content must not overflow its boundary. **If scroll is stuck, the footer overlaps, or `h-full` does nothing**, read **`docs/components/nqui-scroll-area.md` §0** (symptom routing) and **§1** — almost always a **`min-h-0`** / finite-height chain issue, not ScrollArea itself.
+
+For **stubborn** Radix viewports in deep flex trees, add **`viewportStyle`** with **`position: "absolute"`, `inset: 0`, `minHeight: 0`, `minWidth: 0`** (see **§6**). For **wide** native tables or **`min-w-*`** grids, use **`orientation="both"`** (default vertical hides horizontal scroll).
+
+Use this exact pattern for **simple** wide horizontal areas (pagination, etc.):
 
 ```tsx
 <Card>
@@ -81,3 +100,7 @@ When a component demo is placed inside a `Card` (which itself lives in a respons
 - `overflow-y-auto` — vertical scroll for tall content (logs, feeds, lists)
 - `overflow-hidden` — when you want to clip visible overflow without scrolling
 
+## Data tables (TanStack + ScrollArea)
+
+For **bounded card tables** with sticky headers, **horizontal + vertical** scroll, flex height chain, and optional infinite scroll or paging, follow **`nqui-data-tables`** (`../nqui-data-tables/SKILL.md`) and read **`docs/components/nqui-scroll-area.md`** (**§0**–**§6**) first.
+

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.
 
 ---