@nqlib/nqui 0.6.0 → 0.6.1

package/dist/nqui.es.js

@@ -8,9 +8,9 @@ import { E as Fx, a as Gx, C as Bx, u as Vx } from "./enhanced-calendar-CHmWNi0l
 import { z as Ir } from "./sonner-C1ndgVQY.js";
 import { T as Wx, E as Kx, T as Ux } from "./sonner-C1ndgVQY.js";
 import { jsx as o, jsxs as M, Fragment as te } from "react/jsx-runtime";
-import { c as fe, b as ke, P as B, u as pe, d as Z, e as I, f as ie, o as re, g as xn, p as Tr, h as sc, q as fr, i as lc, R as cc, F as dc, D as Ar, n as Ve, l as Ee, m as be } from "./input-shared-NnOiyHpu.js";
-import { c as lt, a as wn, R as uc, T as pc, b as fc, u as He, d as Pr, e as Cn, f as Lt, g as Dr, A as yn, h as $e, I as zt, i as Ft, j as Sn, k as Nn, l as mc, m as gc, n as hc, o as Or, P as vc, p as bc, q as ot, r as nt, s as at, t as Gt, L as xc, v as wc, w as Cc } from "./debug-panel-BjfW-YVo.js";
-import { $ as jx, a1 as Xx, a0 as Yx, x as Zx, y as Qx, S as Jx, F as e0, z as t0, H as r0, G as o0, N as n0, K as a0, J as i0, E as s0, B as l0, X as c0, _ as d0, Y as u0, Z as p0, C as f0, D as m0, M as g0, a2 as h0, a3 as v0, a4 as b0, a5 as x0, S as w0, F as C0, z as y0, H as S0, G as N0, N as k0, K as M0, J as R0, E as _0, B as E0, a6 as I0, a9 as T0, O as A0, W as P0, Q as D0, V as O0, ac as $0, U as L0, a8 as z0, a7 as F0, ab as G0, aa as B0 } from "./debug-panel-BjfW-YVo.js";
+import { c as fe, b as ke, P as B, u as pe, d as Z, e as I, f as ie, o as re, g as xn, p as Tr, h as sc, q as fr, i as lc, R as cc, F as dc, D as Ar, n as Ve, l as Ee, m as be } from "./input-shared-DXf3Edqt.js";
+import { c as lt, a as wn, R as uc, T as pc, b as fc, u as He, d as Pr, e as Cn, f as Lt, g as Dr, A as yn, h as $e, I as zt, i as Ft, j as Sn, k as Nn, l as mc, m as gc, n as hc, o as Or, P as vc, p as bc, q as ot, r as nt, s as at, t as Gt, L as xc, v as wc, w as Cc } from "./debug-panel-BcYzsTp2.js";
+import { $ as jx, a1 as Xx, a0 as Yx, x as Zx, y as Qx, S as Jx, F as e0, z as t0, H as r0, G as o0, N as n0, K as a0, J as i0, E as s0, B as l0, X as c0, _ as d0, Y as u0, Z as p0, C as f0, D as m0, M as g0, a2 as h0, a3 as v0, a4 as b0, a5 as x0, S as w0, F as C0, z as y0, H as S0, G as N0, N as k0, K as M0, J as R0, E as _0, B as E0, a6 as I0, a9 as T0, O as A0, W as P0, Q as D0, V as O0, ac as $0, U as L0, a8 as z0, a7 as F0, ab as G0, aa as B0 } from "./debug-panel-BcYzsTp2.js";
 import { cva as se } from "class-variance-authority";
 import * as $r from "@radix-ui/react-slot";
 import { createSlottable as yc, createSlot as Sc, Slot as We } from "@radix-ui/react-slot";
@@ -18,8 +18,8 @@ import { w as Xe, B as Bt, b as Nc, E as mr } from "./button-S6w9SzkF.js";
 import { e as H0 } from "./button-S6w9SzkF.js";
 import { HugeiconsIcon as q } from "@hugeicons/react";
 import { Tick02Icon as Qe, CircleIcon as St, ArrowRight01Icon as ct, Cancel01Icon as Vt, ArrowUpDownIcon as kc, ArrowDown01Icon as Ht, ArrowUp01Icon as Mc, MoreHorizontalIcon as Rc, MinusSignIcon as _c, UnfoldMoreIcon as Ec, MoreHorizontalCircle01Icon as Ic, ArrowLeft01Icon as Tc, PanelLeftIcon as Ac, PaintBoardIcon as gr, Moon01Icon as Pc } from "@hugeicons/core-free-icons";
-import { j as kn, R as Mn, T as Rn, W as Dc, k as _n, l as En, D as In, m as Wt, P as Tn, O as An, I as Pn, n as Oc, o as Dn, p as On, c as $c, f as Lc, d as zc, C as Fc, e as $n, h as Gc, b as Ln } from "./command-palette-DhoWGyk_.js";
-import { a as K0, i as U0, g as q0, q as j0, s as X0, t as Y0, x as Z0, v as Q0, u as J0, y as ew, z as tw, w as rw, r as ow, A as nw, B as aw } from "./command-palette-DhoWGyk_.js";
+import { j as kn, R as Mn, T as Rn, W as Dc, k as _n, l as En, D as In, m as Wt, P as Tn, O as An, I as Pn, n as Oc, o as Dn, p as On, c as $c, f as Lc, d as zc, C as Fc, e as $n, h as Gc, b as Ln } from "./command-palette-CHUiGh5m.js";
+import { a as K0, i as U0, g as q0, q as j0, s as X0, t as Y0, x as Z0, v as Q0, u as J0, y as ew, z as tw, w as rw, r as ow, A as nw, B as aw } from "./command-palette-CHUiGh5m.js";
 import { C as sw, a as lw, b as cw, d as dw, c as uw } from "./carousel-Cs7SCVhI.js";
 import { D as fw, d as mw, e as gw, i as hw, g as vw, f as bw, b as xw, a as ww, h as Cw, c as yw } from "./drawer-DO26uhym.js";
 import Bc from "react-dom";
@@ -5305,32 +5305,33 @@ function Mm(e) {
 function lv({
   className: e,
   children: t,
-  ...r
+  renderItem: r,
+  ...n
 }) {
-  const { items: n, filterItems: a, search: i, open: l, setListboxIdAria: c } = Se(), { staticNodes: d, renderFn: f } = Mm(t), u = s.useMemo(() => !f || !n ? null : n.filter(a).map((v) => f(v)), [f, n, a, i]), p = s.useRef(null);
+  const { items: a, filterItems: i, search: l, open: c, setListboxIdAria: d } = Se(), { staticNodes: f, renderFn: u } = Mm(t), p = r ?? u, m = s.useMemo(() => !p || !a ? null : a.filter(i).map((b) => p(b)), [p, a, i, l]), v = s.useRef(null);
   return s.useLayoutEffect(() => {
-    if (!l) {
-      c(void 0);
+    if (!c) {
+      d(void 0);
       return;
     }
     requestAnimationFrame(() => {
-      const v = p.current?.id;
-      v && c(v);
+      const b = v.current?.id;
+      b && d(b);
     });
-  }, [l, c, n, u, d]), /* @__PURE__ */ M(
+  }, [c, d, a, m, f]), /* @__PURE__ */ M(
     $c,
     {
-      ref: p,
+      ref: v,
       "data-slot": "combobox-list",
       className: h(
         "pointer-events-auto relative z-[1] min-h-0 flex-1",
         "max-h-[min(18rem,max(0px,calc(var(--radix-popover-content-available-height,24rem)-5.5rem)))]",
         e
       ),
-      ...r,
+      ...n,
       children: [
-        d,
-        u
+        f,
+        m
       ]
     }
   );

package/dist/styles.css

@@ -49,7 +49,7 @@
 @source inline("focus:bg-primary/80 focus:bg-secondary/80 focus:bg-destructive/80 focus:bg-success/80 focus:bg-warning/80 focus:bg-info/80 focus:border-primary/80 focus:border-secondary/80 focus:border-destructive/80 focus:border-success/80 focus:border-warning/80 focus:border-info/80 focus:border-border focus:outline-0 focus-visible:outline-0 focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-destructive");
 
 /* Active state utilities */
-@source inline("active:bg-primary/75 active:bg-secondary/75 active:bg-destructive/75 active:bg-success/75 active:bg-warning/75 active:bg-info/75 active:border-primary/75 active:border-secondary/75 active:border-destructive/75 active:border-success/75 active:border-warning/75 active:border-info/75 active:border-border active:bg-none active:shadow-[inset_0_3px_5px_rgba(0,0,0,0.125)] active:scale-95");
+@source inline("active:bg-primary/75 active:bg-secondary/75 active:bg-destructive/75 active:bg-success/75 active:bg-warning/75 active:bg-info/75 active:border-primary/75 active:border-secondary/75 active:border-destructive/75 active:border-success/75 active:border-warning/75 active:border-info/75 active:border-border active:bg-none active:shadow-[inset_0_3px_5px_rgb(0_0_0/0.125)] active:scale-95");
 
 /* Disabled state utilities */
 @source inline("disabled:bg-transparent disabled:shadow-none disabled:opacity-65 disabled:pointer-events-none");
@@ -57,6 +57,9 @@
 /* Interaction & Cursor utilities */
 @source inline("cursor-pointer select-none touch-manipulation opacity-90 overflow-hidden");
 
+/* cmdk row selection (React 19 — aria-selected, not data-selected) */
+@source inline("aria-selected:bg-accent aria-selected:text-accent-foreground data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground");
+
 /* Transition utilities */
 @source inline("transition-[color,background-color,border-color,box-shadow,opacity,transform] duration-150 ease-in-out");
 
@@ -66,9 +69,6 @@
 /* Group & State utilities */
 @source inline("group/badge has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 light:aria-invalid:ring-destructive/40 aria-invalid:border-destructive");
 
-/* Z-index elevation utilities */
-@source inline("z-[var(--z-debug)] z-[var(--z-sticky-page)] z-[var(--z-background)] z-[var(--z-content)] z-[var(--z-popover)] z-[var(--z-modal-backdrop)] z-[var(--z-modal)] z-[var(--z-tooltip)] z-[var(--z-sticky-content)] z-[var(--z-floating)]");
-
 /* Hit-area utilities (referenced from TSX / docs; @utility defines behavior) */
 @source inline("hit-area-4 hit-area-6 hit-area-debug");
 
@@ -261,11 +261,7 @@
     /* ─── Radius scale ──────────────────────────────────────────────────
      * Lives in @theme (not a separate file) because Tailwind v4 requires
      * --radius-* tokens here to generate the `rounded-*` utilities.
-     * Base: --radius = 0.45rem (defined in /* ============================================
-   nqui Color System & Design Tokens
-   ============================================ */
-
-:root below).
+     * Base: --radius = 0.45rem (see merged theme variables).
      *
      * Usage convention:
      *   rounded-sm   — kbd, small inline pills, dense controls
@@ -815,6 +811,10 @@
    ============================================ */
 
 /* Default light theme variables (.dark block follows) */
+/* ============================================
+   nqui Color System & Design Tokens
+   ============================================ */
+
 :root {
     /* Primary scale — blue hue 240; toned down vs prior (lower L / slightly less chroma on saturated stops) */
     --primary-100: oklch(0.655 0.11 240);

package/docs/components/README.md

@@ -352,6 +352,8 @@ Use these rules to choose the right component. **Selection** = user picks from o
 | CommandPalette | [nqui-command-palette.md](./nqui-command-palette.md) | Full Cmd+K palette. |
 | TableOfContents | [nqui-table-of-contents.md](./nqui-table-of-contents.md) | Doc section links from headings. |
 
+**Cmd+K / cmdk row highlight (React 19):** Fixed in **nqui ≥ 0.6.1** (`aria-selected:bg-accent` in `floatingListItemInteractive`). If every row still looks selected on an older version, see [nqui-command-palette.md](./nqui-command-palette.md).
+
 ---
 
 ## Overlays – When to Use

package/docs/components/nqui-combobox.md

@@ -130,16 +130,29 @@ When `**showPanelSearch**` is false, the panel `**CommandInput**` is wrapped in
 ## cmdk constraints
 
 - **List `id`:** cmdk **overwrites** the `id` on `Command.List`. Do not assume `useId()` matches the DOM — the combobox mirrors the mounted list element’s id into context for `**aria-controls`**.
-- **Selection styling:** Prefer `**aria-selected`** / `**data-selected**` (boolean) utilities. Patterns like `**data-[selected=true]:**` can fail because the attribute is not always the string `"true"`.
 - **Panel input:** Keep the cmdk input **mounted** when filtering (see `**sr-only`** branch above).
 
+### Row selection styling (React 19 + cmdk)
+
+cmdk sets `data-selected` / `aria-selected` on **every** row. **React 19** renders booleans as strings (`data-selected="false"`, `aria-selected="false"`), not absent attributes.
+
+| Tailwind utility | Compiled selector | Safe with React 19? |
+| ---------------- | ----------------- | ------------------- |
+| `data-selected:bg-accent` | `[data-selected]` | **No** — matches `"false"` too → all rows highlighted |
+| `data-[selected=true]:bg-accent` | `[data-selected=true]` | Yes — selected row only |
+| `data-[selected=false]:bg-transparent` | `[data-selected=false]` | Yes — reset unselected rows when overriding CommandItem |
+| `aria-selected:bg-accent` | `[aria-selected=true]` | **Yes** — preferred (used by `ComboboxItem` in source) |
+
+nqui **ComboboxItem** and **CommandItem** (≥ 0.6.1) use `aria-selected:bg-accent` via `floatingListItemInteractive`.
+
 ## Troubleshooting
 
 
 | Symptom                                                      | What to check                                                                                                                                                                                                                                                                                                                                                      |
 | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Trigger `**aria-controls**` missing or wrong                 | `**ComboboxList**` must mount while the popover is open so the list ref can read `**id**`.                                                                                                                                                                                                                                                                         |
-| Row highlight / keyboard selection looks wrong               | Styles targeting only `**data-[selected=true]**`; use `**aria-selected:**` or boolean `**data-selected**` variants.                                                                                                                                                                                                                                                |
+| **Every row** has muted/accent background (looks all selected) | DevTools: unselected rows have `data-selected="false"`. Bare `data-selected:` / `[data-selected]` CSS matches them. Use `aria-selected:bg-accent` or `data-[selected=true]:` + `data-[selected=false]:bg-transparent`. See `nqui-command.md`. |
+| Row highlight / keyboard selection looks wrong               | Not only `data-[selected=true]` — with React 19, also avoid `data-selected:bg-accent`. Prefer `aria-selected:bg-accent`. |
 | **Mouse hover / click on rows does nothing; keyboard works** | Row styles must not use a broad `**data-[disabled]:pointer-events-none`** (can match any `data-disabled` value). Use `**aria-disabled:**` (or `**data-[disabled=true]:**`) so only disabled items drop pointer events. Hidden panel search is wrapped with `**sr-only**` + `**pointer-events-none**`; the cmdk `**CommandInput**` keeps `**pointer-events-auto**`. |
 | Filter feels out of sync                                     | Avoid hiding the panel `**CommandInput**` with `**display: none**`.                                                                                                                                                                                                                                                                                                |
 

package/docs/components/nqui-command-palette.md

@@ -23,7 +23,14 @@ import { CommandPalette } from "@nqlib/nqui"
 <CommandPalette shortcutEnabled={false} ... />
 ```
 
+## Row highlight (Cmd+K list)
+
+`CommandItem` uses `floatingListItemInteractive` with **`aria-selected:bg-accent`** (nqui ≥ 0.6.1). Do not add `data-selected:bg-accent` on custom rows — React 19 sets `data-selected="false"` on unselected cmdk items, and `[data-selected]` would highlight every row.
+
+If an older nqui version still shows all rows filled: upgrade to **0.6.1+** or see `nqui-command.md` for a temporary `CommandItem` className override.
+
 ## Notes
 
 - Keyboard listener on window. May conflict with other global shortcuts.
 - Custom title/description for accessibility.
+- Prefer plain `CommandList` in the showcase; wrap in `ScrollArea` only when you need a bounded height — scroll behavior is separate from row highlight.

package/docs/components/nqui-command.md

@@ -37,3 +37,44 @@ import {
   <CommandList>...</CommandList>
 </CommandDialog>
 ```
+
+## CommandItem selection styling (cmdk + React 19)
+
+Default `CommandItem` classes come from `floatingListItemInteractive` in `lib/floating-surface.ts`:
+
+- `data-selected:bg-accent` → CSS **`[data-selected]`** (any value)
+- `data-[highlighted]:bg-accent` — Radix pointer highlight
+- `focus:bg-accent` — keyboard focus
+
+cmdk sets **`data-selected` and `aria-selected` on every row**. With **React 19**, unselected rows render as `data-selected="false"` / `aria-selected="false"` (strings), not omitted attributes.
+
+### Symptom
+
+Every list row has a muted/accent pill background; hover/keyboard should highlight **one** row only.
+
+### What to check
+
+1. Inspect an idle row: `data-selected="false"` present → bare `data-selected:` utilities will still match.
+2. Only **one** row should have `aria-selected="true"` (unless two items share the same cmdk `value`).
+3. Do not assume “only one selected” in the DOM means correct CSS — check computed `background-color`.
+
+### Do / don't (Tailwind)
+
+| Do | Don't |
+| -- | ----- |
+| `aria-selected:bg-accent` | `data-selected:bg-accent` |
+| `data-[selected=true]:bg-accent` | `data-[selected]:bg-accent` |
+| `data-[selected=false]:bg-transparent` when overriding defaults | `bg-muted` on every row “to match design” |
+
+**nqui ≥ 0.6.1:** `floatingListItemInteractive` uses `aria-selected:bg-accent` (same as ComboboxItem).
+
+### Consumer override (nqui &lt; 0.6.1 only)
+
+```tsx
+<CommandItem
+  className="bg-transparent data-[selected=false]:!bg-transparent aria-selected:bg-accent aria-selected:text-accent-foreground focus:bg-accent focus:text-accent-foreground data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground"
+  ...
+>
+```
+
+See `nqui-command-palette.md` for Cmd+K-specific notes.

package/docs/nqui-skills/ELEVATION.md

@@ -109,15 +109,42 @@ This rule has principled exceptions. Continuous is correct when:
 
 If your screen isn't one of these three, you don't need continuous.
 
-## When single-surface (no nesting) is the right call
+## Mode 3: Single-surface refinement (not just an "exception")
 
-Even more refined than 2-surface alternation:
+The most refined surface model: ONE inline surface (`bg-background`) for everything — page, sidebar, header, content — with structure carried entirely by spacing, type weight, and the occasional uppercase label. The `bg-popover` overlay surface (Mode 2's "+1") still exists for modals/sheets/popovers, but inline surfaces collapse to a single canvas.
 
-1. **Focus-mode editors** — iA Writer, Apple Notes detail, Things 3 task detail. No nesting at all.
-2. **Reading views** — long-form text, documentation, blog posts.
-3. **Single-concept screens** — a page that does one thing, deeply.
+This is **not a rare special case** — it's a deliberate mode used by a meaningful slice of modern product / docs UIs. Recognize it as the third recognized model alongside continuous and 2+1 hybrid.
 
-For these, ONE surface + generous spacing + careful typography is the most refined option. Use it when the content's job is sustained attention rather than navigation between sub-regions.
+### When single-surface is the right mode
+
+1. **Focus-mode editors** — iA Writer, Apple Notes detail, Things 3 task detail. Sustained-attention contexts.
+2. **Reading views** — long-form text, documentation, blog posts, changelogs.
+3. **Marketing / landing pages** — Linear's homepage, Vercel's docs, Boneyard's overview. One canvas, generous space, type does all the hierarchy.
+4. **Docs sites** — Stripe docs, Tailwind docs. Content > chrome.
+5. **Content-first apps** — note-taking, journaling, writing tools. The reader/writer needs uninterrupted visual flow.
+6. **Single-concept product surfaces** — a page that does one thing, deeply, without branching sub-regions.
+
+### How structure works without surfaces
+
+Without surface contrast, hierarchy comes from:
+- **Spacing rhythm** — vary gaps deliberately (gap-2 within a row, gap-6 between sections, gap-12 between major regions). Variation IS the structure.
+- **Type weight + size** — bold display headlines, regular body, muted secondary text. A 3-step type ladder replaces 3 surfaces.
+- **Uppercase labels** — `text-xs uppercase tracking-wider text-muted-foreground` to mark sections without drawing boxes around them.
+- **Active-nav indicator as an inset bar** — not `bg-accent` pill. See `RECIPES.md` #23 "Active nav indicator."
+- **One bordered/contained element per page** at most — the place that genuinely needs to feel "lifted" (a callout, a code block, a primary action area).
+
+### Trade-offs (be honest about them)
+
+| Use single-surface when… | Use 2+1 hybrid when… |
+|--------------------------|----------------------|
+| The page has ONE primary content stream | The page has SEPARATE sub-regions that need to feel like distinct topics (e.g. a card grid of metrics) |
+| Reading/writing/scanning content is the task | Navigating between distinct workspaces / tools / lists is the task |
+| Density is moderate-to-low | Density is high (data tables, kanban boards, dashboards) |
+| The product personality is calm/editorial | The product personality is operational/dense |
+
+### Anti-pattern within single-surface mode
+
+The biggest failure mode: removing surfaces but keeping every horizontal divider. You then have NO surface contrast AND a stack of `border-b` lines, which reads as "broken" not "refined." Either commit to surfaces+borders (2+1) or commit to single-surface+spacing — don't mix.
 
 ## Anti-patterns this rule eliminates
 

package/docs/nqui-skills/RECIPES.md

@@ -723,6 +723,91 @@ Auth is the most-requested pattern that the kit must cover well. Get these wrong
 
 ---
 
+## Single-surface / refined recipes
+
+These recipes apply when the surrounding shell uses single-surface mode (see `ELEVATION.md` Mode 3 — landing pages, docs, content-first apps). They're cleaner alternatives to recipes that work well on multi-surface shells but feel heavy without surrounding chrome.
+
+### 23. Active nav indicator (inset bar, not bg-fill)
+
+**Intent:** mark the active route in a sidebar / docs nav without using `bg-accent` as a pill. Used by Linear sidebar, Notion docs, Vercel docs, Boneyard.
+
+```tsx
+<NavLink
+  to={item.to}
+  className={({ isActive }) =>
+    [
+      "relative flex items-center gap-2 rounded-md px-3 py-1.5 text-sm transition-colors",
+      // INSET LEFT BAR — appears only when active. 2px wide, full row height,
+      // sits in the left padding without shifting the label.
+      "before:absolute before:left-0 before:top-1/2 before:-translate-y-1/2",
+      "before:h-4 before:w-[2px] before:rounded-full before:bg-foreground",
+      "before:opacity-0 before:transition-opacity",
+      isActive
+        ? "text-foreground font-medium before:opacity-100"
+        : "text-muted-foreground hover:text-foreground hover:bg-muted/40",
+    ].join(" ")
+  }
+>
+  {item.label}
+</NavLink>
+```
+
+**Rules:**
+- Bar is **2px wide** — wider reads as a divider, narrower disappears at low DPI.
+- Bar uses **`bg-foreground`** (or the brand color) — needs full contrast to register as an active marker.
+- Active row gets **bolder text** (`font-medium`) AND the bar. Either alone is too weak; both together makes the active state unambiguous.
+- Hover on inactive rows uses **`bg-muted/40`** — a soft pill — so hover and active are distinguishable (active = bar + bold; hover = soft pill).
+- **Do NOT also fill with `bg-accent`** — defeats the point. The bar+bold combo IS the indicator.
+
+**When to use this instead of bg-fill pill:**
+- Single-surface shell (no surface contrast available — bg-fill would clash with the borderless canvas)
+- Docs / marketing / content-first app where the nav is meant to defer to the content
+- Sidebars where 6+ items would create too many filled pills if multiple states were highlighted
+
+**When to KEEP bg-fill instead:**
+- Dense product UI with high information density (Linear's issue list nav, our PMO sidebar with badges + icons + counts) — there, the bg-fill survives the noise better than a thin bar.
+
+### 24. Concept demonstration (show, don't tell)
+
+**Intent:** explain an abstract feature by pairing the REAL artifact with the ABSTRACT artifact side-by-side in one frame. Used by Boneyard (real UI vs skeleton), Vercel marketing (code before vs after), Anthropic docs (prompt vs response).
+
+```tsx
+<figure className="rounded-xl border border-border overflow-hidden">
+  {/* Top — labels for each half, monospace-ish small caps */}
+  <div className="grid grid-cols-2 px-6 pt-5 pb-2 text-[10px] uppercase tracking-wider text-muted-foreground font-semibold">
+    <span>Real UI</span>
+    <span>Skeleton</span>
+  </div>
+
+  {/* Body — the two artifacts, equal-width, same vertical rhythm */}
+  <div className="grid grid-cols-2 gap-6 px-6 pb-6">
+    <div className="flex flex-col gap-3">
+      {/* REAL — full-fidelity rendering with colour, icons, labels, data */}
+      <RealDashboard />
+    </div>
+    <div className="flex flex-col gap-3">
+      {/* ABSTRACT — same shapes/positions but stripped of colour and detail */}
+      <SkeletonDashboard />
+    </div>
+  </div>
+</figure>
+```
+
+**Rules:**
+- **Equal column widths** — asymmetry implies one is more important than the other; for "concept = output" pairing, they need to read as equals.
+- **Same vertical rhythm** — both halves use the same `gap-*` values so eye-line moves left-right at the same heights. Misaligned rows kill the visual rhyme.
+- **The contrast IS the explanation** — don't add an arrow or "→" between them. The user's brain does the comparison automatically.
+- **Real side gets all the colour** — accent colors, icons, brand. The abstract side stays monochrome / grey. The colour drop-off is the second signal that "this is the stripped version."
+- **Containing frame is borderless or has the lightest possible border** (`border-border`) — heavy frame would compete with the contrast inside.
+- **Labels go above each half** in tiny uppercase muted text — not floating labels in the middle, not headers in their own rows. The labels are minor; the demonstration is the point.
+
+**Don't use this pattern for:**
+- Single concepts that don't benefit from comparison (just show the thing)
+- More than 2 panels — 3+ becomes a comparison table, different recipe
+- Steps in a sequence — use a numbered flow, not a side-by-side
+
+---
+
 ## Combo synthesis — how to think about new ones
 
 When you face a situation not listed here, ask:

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.