@nqlib/nqui 0.5.6 → 0.6.1

package/docs/nqui-skills/_claude-commands/README.md

@@ -0,0 +1,50 @@
+# Claude Code slash commands shipped with nqui
+
+This folder contains the **slash command entry points** that the `init-claude-skills` CLI installs into `~/.claude/skills/` on a consumer machine. These become invocable as `/design` and `/edit` inside Claude Code and Claude Desktop after install.
+
+## How a consumer installs (once they `pnpm install`)
+
+```bash
+pnpm install @nqlib/nqui                # install the library
+npx @nqlib/nqui init-claude-skills      # install Claude Code skills to ~/.claude/skills
+```
+
+What that command does:
+1. Copies all 15 root docs (SKILL.md, AGENT_PROMPT.md, ELEVATION.md, MOTION.md, RECIPES.md, STATES.md, WRITING.md, EVAL.md, THEMING.md, MIGRATION.md, COMPOSITION.md, COMPONENTS_INDEX.md, HUMAN_GUIDE.md, READ_BUDGET.md, README.md) → `~/.claude/skills/nqui/`
+2. Copies all subdirectory skills (nqui-composition, nqui-components, nqui-design-system, nqui-shadcn, impeccable, audit, layout, polish, etc.) → `~/.claude/skills/<skill-name>/`
+3. Copies all 68 per-component docs → `~/.claude/skills/nqui/components/`
+4. Copies the slash command skills (this folder) → `~/.claude/skills/design/` and `~/.claude/skills/edit/`
+
+After install, the consumer restarts Claude Code, and `/design` and `/edit` become available as tools.
+
+## What `/design` does
+
+When the user types `/design [a login form]` (or any UI build request), the agent:
+
+1. Loads `AGENT_PROMPT.md` (the non-negotiable rules)
+2. Loads design context from `.impeccable.md` (or asks the user if missing)
+3. Picks a named layout pattern from `COMPOSITION.md`
+4. Pulls combos from `RECIPES.md`
+5. Applies the elevation rule (2+1 surfaces), state matrix, writing rules
+6. Runs the 30-second Linear designer self-review
+7. Ships work that's reliably 8/10 or better
+
+## What `/edit` does
+
+When the user points at existing UI (`/edit the sprint tracker page`), the agent:
+
+1. Reads the target file(s)
+2. Diagnoses against the design rules (elevation / states / writing / motion / composition / anti-patterns)
+3. Names findings as P0/P1/P2 with file:line locations
+4. Proposes minimum-viable fixes
+5. Applies them via Edit tool, citing which rule each fix maps to
+
+Different from `/design` (which builds from scratch).
+
+## Updating the slash commands
+
+The source of truth lives in this folder (`docs/nqui-skills/_claude-commands/`). Edit `design/SKILL.md` or `edit/SKILL.md` here; the next `init-claude-skills` run propagates changes.
+
+## Why both files live in the package, not just in `~/.claude/skills/`
+
+So consumers get the same versioned slash commands every install. The local `~/.claude/skills/` copy can drift (manual edits, partial deletes); the package source is the canonical version that ships with each nqui release.

package/docs/nqui-skills/_claude-commands/design/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: design
+description: Build a new product UI screen/page/feature with @nqlib/nqui. Apple-inspired craft, 2+1 elevation rule, full state coverage, restrained motion. Use when the user says "design", "build", "create a page", "make a screen", or any new-UI request. Loads the full nqui skill chain and follows the Agent Build Protocol from start to finish.
+argument-hint: "[what to build, e.g. 'a login form' or 'a sprint dashboard']"
+---
+
+# /design — Build with nqui
+
+This is the **canonical entry point** for any UI build request when nqui is available. It orchestrates the full skill chain (composition → patterns → recipes → components) and produces production-quality output.
+
+## What this skill does
+
+When invoked, you build a new UI surface using `@nqlib/nqui` following the **Agent Build Protocol** (10 steps) and the **30-second Linear designer test** before declaring done.
+
+The output bar: a senior Linear / Vercel / Stripe / Apple designer reviewing your diff would find **zero** AI-flavored cues (nested cards, "Submit" buttons, missing empty states, decorative shadows, generic copy).
+
+## Mandatory protocol
+
+### Step 1 — Load the entry contract
+Read `~/.claude/skills/nqui/AGENT_PROMPT.md` if you have not in this conversation. This is the non-negotiable rule set: hard rules, anti-patterns, build flow. Don't skip it.
+
+### Step 2 — Load design context
+Check for `.impeccable.md` in the project root.
+- If present: use that brand/voice/aesthetic context.
+- If absent: ASK the user for brand tone, target audience, and any reference apps. Do not infer from the codebase — code tells you what was built, not who it's for.
+
+### Step 3 — Understand the user's job (5-word outcome)
+- One sentence: what is the outcome of this screen?
+- One primary action?
+- What can move off-screen (Sheet, route, hover card)?
+
+If the user's request is vague ("build me a dashboard"), ask 2-3 clarifying questions before writing code. Generic prompts produce generic output.
+
+### Step 4 — Pick a named layout pattern
+Read `~/.claude/skills/nqui/COMPOSITION.md` and match the request to one of the named patterns:
+- App Shell (sidebar + content)
+- Settings page
+- Dashboard (metrics + table/chart)
+- Master-Detail Split (responsive → Sheet below 900px)
+- Wizard / Stepper
+- Command / Search Interface
+- Form Dialog
+
+Commit to one. Don't blend.
+
+### Step 5 — Look up combos in RECIPES.md
+Read `~/.claude/skills/nqui/RECIPES.md` and grab the specific recipes you need (status pill, bulk action, filter toolbar, the three states, auth recipes 16-22 for login/signup, etc.). Don't reinvent — use the canonical blueprints.
+
+### Step 6 — Apply the elevation rule
+Read `~/.claude/skills/nqui/ELEVATION.md`. Cap inline nesting at **2 surfaces**: page (`bg-background`) → card (`bg-muted/40`). Past that, use spacing + uppercase labels + type weight. `bg-popover` + `.nqui-elevated` is for Dialog / Sheet / Popover / DropdownMenu only.
+
+### Step 7 — Cover all states
+Read `~/.claude/skills/nqui/STATES.md`. For every interactive surface, design:
+- Lists: idle + loading (Skeleton) + empty (Empty w/ CTA) + error (Alert w/ retry)
+- Forms: idle + focus + filled + submitting + validation-error + server-error + success
+- Buttons: idle + hover + focus + active + disabled + loading
+- Async views: loading + populated + empty + error + refreshing
+
+**No blank screens. No happy-path-only views.**
+
+### Step 8 — Write the copy properly
+Read `~/.claude/skills/nqui/WRITING.md`. Every button, label, error, empty state, toast must:
+- Specific verb + object ("Send invite", not "Submit")
+- Errors say what + how to fix
+- Sentence case, present tense, no exclamation marks
+- No "Welcome!" / "Awesome!" / "Let's get started!" — these are AI signatures
+- No emoji in UI chrome
+
+### Step 9 — Motion only with intent
+Read `~/.claude/skills/nqui/MOTION.md` ONLY if you're adding animation. Default: no motion. When present: 150ms quick / 200ms standard, ease-out for entrances, ease-in for exits. Never bounce/elastic. Respect `prefers-reduced-motion`.
+
+### Step 10 — Self-review (the 30-second Linear designer test)
+Before declaring done, walk this checklist:
+1. Hierarchy clear within 2 seconds?
+2. All states designed (not just happy path)?
+3. Copy specific, not generic?
+4. One primary action per surface?
+5. Spacing varied (not monotonous)?
+6. Cards used only for bounded topics?
+7. Focus styles on every interactive element?
+8. No decorative shadows on flat elements?
+9. No nested cards inside cards?
+10. No banned anti-patterns (border-l-4 stripes, gradient text, hero metrics, "Submit" buttons)?
+
+**If you can name 2+ failures → fix them BEFORE asking the user.**
+
+## Routing reference
+
+If uncertain at any step, the doc to load is in `~/.claude/skills/nqui/READ_BUDGET.md`. Don't bulk-read the skills folder.
+
+## What you do NOT do in /design
+
+- Don't ship a single happy-path view without the other states
+- Don't invent custom CSS where a component exists
+- Don't add transitions "to feel modern" — most state changes should not animate
+- Don't ask "is this OK?" when you can name 2+ failures from the self-review
+- Don't deliver work that would trigger any of the 10 "Linear designer" reactions
+
+## What you DO in /design
+
+- Cite which named pattern + which recipes you used (helps the user understand the choices)
+- Apply the surface rule strictly (count surfaces before declaring done — never more than 2 inline)
+- Use real-feeling content (not lorem ipsum, not "Card Title 1 / Card Title 2")
+- Test the responsive split if using master-detail (does it switch to Sheet below 900px?)
+- Verify accessibility minimums (focus visible, ARIA on interactive non-buttons, no tooltip-as-label)
+
+## The promise
+
+Output from `/design` is reliably 8/10 or better. Not 10/10 (that requires design context this skill can't infer alone), but never embarrassing, never AI-flavored, never missing critical states.
+
+That's the bar. Hit it on every invocation.

package/docs/nqui-skills/_claude-commands/edit/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: edit
+description: Refine, fix, or improve existing UI built with @nqlib/nqui. Diagnoses issues against the design rules (elevation, states, writing, motion), then applies the smallest fix that resolves them. Use when the user says "fix this", "improve this", "this looks off", "edit", "refine", or references a specific page/component that needs polish. Different from /design (which builds from scratch) — /edit changes what's already there.
+argument-hint: "[what to fix, e.g. 'the sprint tracker page' or 'this dialog']"
+---
+
+# /edit — Refine existing nqui UI
+
+This is the **canonical entry point** for fixing or improving UI that's already in the codebase. It runs a diagnostic pass against the nqui design rules, names what's wrong specifically, then applies the smallest fix.
+
+Different from `/design`:
+- `/design` = build from scratch (Agent Build Protocol, 10 steps)
+- `/edit` = read what's there, diagnose, fix in place
+
+## Mandatory protocol
+
+### Step 1 — Load the entry contract (skip if loaded this session)
+Read `~/.claude/skills/nqui/AGENT_PROMPT.md`. The rules you'll judge the existing code against.
+
+### Step 2 — Read the target
+- If the user named a file/component: read it.
+- If the user pointed at a page route: find the page file in `src/pages/` (or wherever the project keeps them) and read it.
+- Read enough context to understand the surrounding components/layout, not just the line they're complaining about.
+
+### Step 3 — Diagnose against the design rules
+Walk the code mentally against these checks (skip checks the user explicitly excluded):
+
+| Rule | What to look for | Doc |
+|------|------------------|-----|
+| **Elevation** | Cards inside cards inside cards? `bg-muted/60` or `bg-muted/70` (third surface)? `shadow-*` on inline cards? | `ELEVATION.md` |
+| **State coverage** | Lists without empty/loading/error? Buttons without loading state? Forms without validation states? | `STATES.md` |
+| **Composition** | More than 3 surfaces on screen? Two competing primary buttons? Toolbar floating on bg-background? | `COMPOSITION.md` |
+| **Writing** | "Submit" / "OK" / "Are you sure?"? Exclamation marks? "Welcome!" / "Awesome!"? Generic errors? | `WRITING.md` |
+| **Motion** | Elastic/bounce easing? Durations > 250ms for routine state changes? Animating layout properties? | `MOTION.md` |
+| **Component selection** | RadioGroup in a toolbar? Dialog for a confirmation? Tooltip as the only label? Sheet for >5 fields? | `COMPONENTS_INDEX.md` |
+| **Anti-patterns** | `border-l-4` colored stripes? Gradient text? Hero metric template? Sparklines as decoration? Glassmorphism on inline cards? | `nqui-composition/SKILL.md` |
+
+### Step 4 — Name the findings specifically
+Before fixing anything, tell the user what you found. Use this format:
+
+```
+Findings (in order of severity):
+
+🔴 [P0] {issue} — {file:line}. Why it matters: {one sentence}.
+🟠 [P1] {issue} — {file:line}.
+🟡 [P2] {issue} — {file:line}.
+```
+
+P0 = clear rule violation (banned anti-pattern, missing critical state, broken accessibility).
+P1 = noticeable quality issue (wrong component, lazy copy, monotonous spacing).
+P2 = polish (could be tighter, but not embarrassing).
+
+If you find nothing: say so. Don't invent issues to look thorough.
+
+### Step 5 — Propose minimum-viable fixes
+For each finding, propose the smallest change that resolves it. Don't refactor surrounding code unless the user asked. Examples:
+
+- "Submit" → "Send invite" (change 1 word)
+- Nested Cards → outer Card + `<section>` with uppercase label (replace 1 Card pair)
+- Missing empty state → add Empty component with one CTA (insert 8 lines)
+- Bouncy easing → swap to `ease-out` (change 1 className)
+
+The goal is **edit, not rewrite**. Honor the existing structure; remove violations.
+
+### Step 6 — Apply the fixes
+Apply your proposed fixes via Edit tool. After each change, briefly state what changed and why ("Swapped to `Sheet` because the form has 8 fields — Dialog would feel trapped").
+
+### Step 7 — Self-review the edit
+Walk the same diagnostic again post-edit. If new issues surfaced from your fix, name them — don't pretend the edit is done if it created new violations.
+
+## What you do NOT do in /edit
+
+- Don't rebuild the page. The user said "edit," not "redesign."
+- Don't bundle unrelated improvements ("while I was here I also refactored X"). Stay scoped.
+- Don't fix one violation by introducing another (replacing nested Cards with a 4-color gradient header — that's just a different anti-pattern).
+- Don't skip the diagnostic step ("I'll just fix obvious stuff"). The diagnostic IS the value — naming what's wrong is half the deliverable.
+- Don't ask the user to verify before applying fixes if the fixes are P0 (clearly wrong) and small (< 20 lines). Just do them.
+
+## What you DO in /edit
+
+- Cite the rule each fix maps to ("removed the third nested Card per ELEVATION.md")
+- Note what you intentionally left alone ("the Card-of-cards on line 80 looks suspect but I'm leaving it — it's a Sortable wrapper, not a hierarchy choice")
+- When the user's complaint is vague ("it looks off"), do the diagnostic first, then offer 2-3 specific options with trade-offs
+
+## Triggering examples
+
+- "the sprint tracker feels heavy" → /edit, diagnose elevation + spacing + density
+- "this dialog has too many fields" → /edit, suggest Sheet conversion + state coverage check
+- "fix the empty state on the inbox page" → /edit, audit the empty state against STATES.md + WRITING.md
+- "this button feels wrong" → /edit, check component selection + label specificity + state coverage
+- "make this look more Apple" → /edit, diagnose against `nqui-composition/SKILL.md` clarity/deference/depth principles
+
+## The promise
+
+`/edit` finds the real issues, not imaginary ones. Names them with rules and locations. Fixes them minimally. Leaves the working parts alone.
+
+That's the bar.

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

@@ -8,9 +8,12 @@ argument-hint: "[target] [context (mobile, tablet, print...)]"
 
 Adapt existing designs to work effectively across different contexts - different screen sizes, devices, platforms, or use cases.
 
-## 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: target platforms/devices and usage contexts.
+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: target platforms/devices and usage contexts.
 
 ---
 

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,29 +33,49 @@ 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
 
 - React 18+ and 19 supported
+- **cmdk list rows:** nqui ≥ 0.6.1 uses `aria-selected:bg-accent` in `floatingListItemInteractive`. Do not add custom `data-selected:bg-accent` on `CommandItem` (React 19 + `[data-selected]` highlights every row). See `docs/components/nqui-command-palette.md`.
 - 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 elevation.css only
 
 ## 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 +101,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.
+