@nqlib/nqui 0.5.6 → 0.6.0

package/docs/nqui-skills/ELEVATION.md

@@ -0,0 +1,154 @@
+---
+name: nqui-elevation
+description: The 2-surface + spacing hybrid model for elevation. Caps inline nesting at 2 surfaces; past that, spacing + type weight do the work. One additional "elevated" surface reserved for modals/popovers/sheets. Read before designing any layered UI.
+---
+
+# nqui Elevation — The 2+1 Surface Hybrid
+
+The single most consequential design-system decision is **how you express elevation** (this-is-deeper-than-that). nqui's answer is the **hybrid model**: 2 alternating inline surfaces + 1 elevated surface for overlays + spacing for everything else.
+
+This file is the rule. Apply it to every layered UI.
+
+## The model in one diagram
+
+```
+┌─ Surface A (page) ──────────────────────────────┐
+│                                                 │
+│  ┌─ Surface B (card) ─────────────────────────┐ │
+│  │                                            │ │
+│  │   Section title (uppercase label)          │ │
+│  │   ──spacing--                              │ │
+│  │   Section content                          │ │
+│  │                                            │ │
+│  │   ────── Separator (optional) ──────       │ │
+│  │                                            │ │
+│  │   Another section                          │ │
+│  │   ──spacing--                              │ │
+│  │   Sub-detail (indent + smaller text)       │ │
+│  │                                            │ │
+│  │   ⛔ NO third nested surface                │ │
+│  │                                            │ │
+│  └────────────────────────────────────────────┘ │
+│                                                 │
+└─────────────────────────────────────────────────┘
+
+      ┌─ Surface Elevated (modal / popover) ─┐
+      │   Only for overlays, never inline.   │
+      └──────────────────────────────────────┘
+```
+
+## The 3 tokens (and only 3)
+
+| Token | Tailwind class | When to use |
+|-------|---------------|-------------|
+| `surface-a` | `bg-background` | Page background, alternates with B |
+| `surface-b` | `bg-muted/40` (or `bg-muted/30` for a subtler step) | Cards, panels, regions that need to read as a distinct topic |
+| `surface-elevated` | `bg-popover` + `shadow-lg` | Modals, sheets, popovers, dropdowns — anything physically "above" the page |
+
+**These are the only legitimate inline surface tokens.** If you find yourself wanting a fourth, the answer is *not* a new shade — the answer is more spacing, a stronger label, or a different layout.
+
+## The depth rule
+
+**Maximum 2 inline surfaces. Period.**
+
+| Depth | Carrier | Example |
+|-------|---------|---------|
+| Page → card | Surface flip (A → B) | Page is `bg-background`, card is `bg-muted/40` |
+| Inside card → sub-section | **Spacing only** (`gap-6` between sections + uppercase label) | No new surface. `<h3 className="text-xs uppercase tracking-wider">Section</h3>` + content |
+| Section → detail group | **Spacing only** (`gap-4`) or one horizontal `Separator` | No new surface |
+| Sub-detail | **Type weight + indentation** | `text-sm` → `text-xs text-muted-foreground` |
+| Modal over content | `surface-elevated` (the ONLY third allowed) | `Dialog`, `Sheet`, `Popover` |
+
+## When you want a third inline surface — the decision tree
+
+You almost never want this. When the impulse hits, walk this tree:
+
+1. **Is this a genuinely separate topic from its parent?**
+   - **No** → use spacing + a label. (Most cases land here.)
+   - **Yes** → continue.
+
+2. **Could this content move to its own route, sheet, or popover?**
+   - **Yes** → move it. The hierarchy will be cleaner.
+   - **No** → continue.
+
+3. **Does this content benefit from being closed by default?**
+   - **Yes** → use `Accordion` or `Collapsible`. The closed state IS the separation; no surface needed.
+   - **No** → continue.
+
+4. **Are you building a stacked-modal or genuinely physical depth metaphor?**
+   - **Yes** → use `surface-elevated`. This is the legitimate exception.
+   - **No** → STOP. Flatten. Your hierarchy is over-engineered.
+
+## What spacing/typography do instead of color
+
+The discipline is: **make spacing, weight, and indentation do the work that color was doing**. The hierarchy is preserved; it just expresses through different signals.
+
+| Old (color-based) | New (space + type) |
+|-------------------|-------------------|
+| Nested card with `bg-muted/60` | `<section className="mt-6"><h3 className="text-xs uppercase">Title</h3>...</section>` |
+| Card-inside-card with border | Outer card + horizontal `Separator` between sections |
+| Three-color metadata strip | One surface, columns laid out with `gap-6`, label text in muted color |
+| Deep nested settings groups | `<FieldSet>` with `<FieldLegend>` — no extra surface |
+
+**Spacing scale to use as the hierarchy signal:**
+- `gap-2` (8px) — within a row, between tight related elements (label + value)
+- `gap-4` (16px) — between fields in a form, between cards in a grid
+- `gap-6` (24px) — between sub-sections within a single surface
+- `gap-8` (32px) — between major sections within a surface
+- `gap-12` (48px) — between top-level page regions
+
+The *variation* of spacing IS the hierarchy. Don't make everything the same gap.
+
+## When continuous (5-shade) elevation is the right call
+
+This rule has principled exceptions. Continuous is correct when:
+
+1. **Stacked modals** — modal opening from modal. Each must feel physically above. (iOS does this; macOS does this.)
+2. **Bloomberg-class data UIs** — when you genuinely have 4+ semantic depth levels and density is the dominant design constraint. Most products don't have this.
+3. **File-system metaphors** — where depth IS the content (Finder columns, tree views with visualized hierarchy).
+
+If your screen isn't one of these three, you don't need continuous.
+
+## When single-surface (no nesting) is the right call
+
+Even more refined than 2-surface alternation:
+
+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.
+
+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.
+
+## Anti-patterns this rule eliminates
+
+| ❌ Old pattern | ✅ Hybrid pattern |
+|---------------|-------------------|
+| `<Card><Card><Card>...</Card></Card></Card>` (nested) | Outer Card → sections separated by `gap-6` + label, no inner cards |
+| 5-token elevation scale (`bg-1` through `bg-5`) | 2 alternating + 1 elevated, total 3 tokens |
+| "Slightly darker shade for the sub-region" | More space, uppercase label, no shade |
+| `border-l-4 border-accent` on a sub-section | Uppercase label + spacing |
+| `shadow-md` on a flat inline card | No shadow — shadows are for elevated surfaces only |
+| `bg-muted/20` inside `bg-muted/40` inside `bg-background` | `bg-background` (A) → `bg-muted/40` (B) → spacing for the third level |
+
+## The check before shipping any layered UI
+
+Walk the screen from outside in. Count surface changes.
+
+- [ ] Did I use more than 2 distinct inline surface colors? If yes, collapse to 2.
+- [ ] Did I nest a card inside a card inside a card? If yes, flatten one level.
+- [ ] Did I add a shade just because "this section needed to feel distinct"? If yes, use spacing + label instead.
+- [ ] Is my elevated surface (Modal/Sheet/Popover) using `shadow-lg` + `bg-popover`? If not, fix.
+- [ ] Are my section gaps varied (some `gap-4`, some `gap-6`, some `gap-8`)? If everything is the same, the hierarchy is monotonous.
+
+## Why this works (the principle)
+
+Color is a heavy signal. The eye uses it for category ("this is selected", "this is destructive", "this is a warning"). When you use color to signal **depth**, you're spending a category-signaling slot on a hierarchy job that spacing handles for free.
+
+The hybrid model frees color to do what color is best at:
+- Brand/accent: one primary
+- Semantic: success / warning / error
+- State: selected / hover / focus
+
+And spacing does what spacing is best at: rhythm, grouping, breathing room — which is what makes UI feel calm and intentional.
+
+This is why Linear, Things 3, Apple Notes feel different from Material Design dashboards. Not because they have prettier colors. Because they spent fewer signals on hierarchy, leaving more bandwidth for the content.

package/docs/nqui-skills/EVAL.md

@@ -0,0 +1,148 @@
+---
+name: nqui-eval
+description: Eval set + grading rubric for AI agents using nqui. Run before each release. The skills folder is theory until the eval validates it produces consistently good output. Without this, nqui is documentation, not infrastructure.
+---
+
+# nqui Eval — How We Measure "Production AI Ready"
+
+The skills folder claims that AI agents using nqui produce reliably good output. **Without an eval, that's an unfalsifiable claim.** This file is the eval set + grading rubric. Run it before any release that touches tokens, components, or skills.
+
+## How to run
+
+1. Load **only** the nqui skills folder + `AGENT_PROMPT.md` into a fresh agent context (Claude API, GPT-4, etc.)
+2. Send each prompt below verbatim, in a fresh conversation
+3. Let the agent build the code (no follow-up clarifying questions allowed in the eval — measure cold output)
+4. Score using the rubric below
+5. Track per-prompt scores over time. Regression = something broke.
+
+## Grading rubric (per prompt, max 10)
+
+| Category | Max | What to check |
+|----------|-----|---------------|
+| **Composition** | 2 | Right named pattern picked? Surface cap respected? Three-surface rule followed? |
+| **State coverage** | 2 | All required states designed? Empty / loading / error present where needed? |
+| **Component selection** | 1 | Right component for the situation? (Dialog vs AlertDialog, ToggleGroup vs RadioGroup, etc.) |
+| **Writing** | 1 | Copy specific (not "Submit" / "Are you sure?")? No exclamation marks? Sentence case? |
+| **Motion** | 1 | Restrained (default: none)? No banned curves? `prefers-reduced-motion` respected? |
+| **Anti-patterns avoided** | 2 | Zero from the 10 hard-banned (nested cards, gradient text, hero metric template, etc.)? |
+| **Code quality** | 1 | Readable, uses kit conventions, no custom CSS where component exists? |
+
+**Pass threshold: 8/10 average across all prompts. Below 7 average = block release.**
+
+---
+
+## The eval set (12 prompts)
+
+Each prompt simulates a real user request that the kit is expected to handle. Coverage spans the long tail of common product surfaces.
+
+### 1. Auth: login form
+> Build a login screen with email + password. Include "forgot password?" link and a primary sign-in button. The user should see clear error messages if auth fails.
+
+**Looks for:** `FieldSet` + `Field` + `Input` + `FieldError`. Sentence-case labels. Specific error copy ("Incorrect email or password" not "Auth failed"). One primary button + `outline` for secondary. Loading state on submit button. NO `Dialog` (this is a page).
+
+### 2. Auth: OAuth + email signup
+> Build a signup page that offers Google OAuth and email signup. Show a divider between OAuth providers and the email form.
+
+**Looks for:** OAuth buttons as `variant="outline"` with provider name + brand-name (no `Submit`). `Separator` with text label. Email form uses same `Field` pattern as login. Reasonable security copy ("We'll never share your email").
+
+### 3. Settings: account preferences
+> Build an account settings page with: display name, email, time zone selector, weekly digest toggle, two-factor toggle, change password button, danger zone (delete account).
+
+**Looks for:** `FieldSet` + `FieldGroup`. `Switch` for toggles. `Select` for time zone. Danger zone uses `AlertDialog` for delete confirmation with SPECIFIC stakes (not "Are you sure?"). Surface cap respected — no card per field.
+
+### 4. Dashboard: deploy/build monitor
+> Build a deployment dashboard showing recent deploys with status (building, success, failed), commit info, and a detail panel when one is selected.
+
+**Looks for:** Master-detail pattern. Responsive switch to `Sheet` below 900px. `Tracker` for build history visualization. `Badge` for status. Real status copy ("Building" / "Failed" not "Status 1"). Empty + loading states for the list.
+
+### 5. Billing: pricing + checkout
+> Build a pricing page with 3 tiers (Free / Pro / Team). Selecting a paid tier opens a Sheet with order summary and a payment form (card number, expiry, CVC).
+
+**Looks for:** Pricing cards with ONE recommended (subtle emphasis, not screaming). `Sheet` for checkout (long form). `Field` + `InputOTP` or formatted `Input`. Specific button copy ("Pay $49/month" not "Submit"). Real-feeling totals.
+
+### 6. Search: filterable list
+> Build a project search page with a search box, status filter (open/closed/all), assignee filter, and results list. Show "no results" state when nothing matches.
+
+**Looks for:** Search input with leading icon. `ToggleGroup` for status (NOT RadioGroup). `Combobox` for assignee. Filter container uses `bg-muted/30`. `Empty` w/ "clear filter" action (not just apology). Result count + sort.
+
+### 7. File upload: multi-file with progress
+> Build a file uploader that accepts multiple files via drag-and-drop or file picker, shows per-file progress, and handles errors per file (e.g., file too large).
+
+**Looks for:** Drop zone with active state on dragover. Per-file `Progress`. Per-file status (uploading/success/error). Specific error messages per file. Remove button per file. No alarming language for fails.
+
+### 8. Data table: sortable + paginated
+> Build a customers data table with columns: name, email, plan, signup date, MRR. Make it sortable, paginated, with row selection for bulk actions.
+
+**Looks for:** `DataTable` with header sort indicators. Sticky header on scroll. Bulk action bar appears on selection (sticky pill at bottom). `Pagination` component. Real-feeling column widths.
+
+### 9. Onboarding: 4-step wizard
+> Build a 4-step onboarding wizard: workspace name → invite teammates → choose integrations → review and start. Show progress, allow back navigation, validate each step.
+
+**Looks for:** `Progress` or step indicator. ONE primary action per step ("Continue" / "Skip for now" / "Start"). Back is `variant="outline"`. Validation prevents advance. `Alert` for step errors. Centered single card on each step.
+
+### 10. Notification preferences
+> Build a notification settings page where the user can choose, per category (mentions, comments, weekly digest, security alerts), whether to receive Email / Push / Slack — like a matrix.
+
+**Looks for:** Table-like or grid layout with `Switch` or `Checkbox` per cell. Clear column headers. Row labels explain each category. "Apply to all" affordance per row. No nested cards.
+
+### 11. Chat / message thread
+> Build a chat interface with a message list (showing user vs assistant alternation), an input at the bottom with send button, and a typing indicator when the assistant is responding.
+
+**Looks for:** Distinct visual for user vs assistant (NOT just color — also alignment or avatar). `Item` or custom message block. Auto-scroll to bottom. Loading dots while assistant responds. Send on Enter (Shift+Enter for newline).
+
+### 12. Error / empty page
+> Build a 404 page with a clear message, helpful next actions (go home, search, contact), and the site's normal navigation.
+
+**Looks for:** `Empty` component or similar. Specific, friendly copy ("This page moved or was deleted") not "404 Not Found". 2-3 actions, ONE primary. Page chrome still present (user isn't stranded).
+
+---
+
+## Common failure modes to watch for
+
+These are the patterns the eval should catch reliably. If multiple prompts surface the same failure, fix the underlying skill/recipe.
+
+| Failure mode | Symptom in output | Fix in |
+|--------------|------------------|--------|
+| Three-surface nesting | `<Card><Card><Card>` or `bg-muted/60` inside `bg-muted/40` | `ELEVATION.md`, lint rule |
+| Empty state forgotten | List renders blank when 0 items | `STATES.md`, component template |
+| Generic copy | "Submit", "An error occurred", "Are you sure?" | `WRITING.md` |
+| Bouncy/elastic motion | overshoot easing on any element | `MOTION.md` |
+| Wrong component | RadioGroup in toolbar, Dialog for destructive confirm | `COMPONENTS_INDEX.md` decision tables |
+| Side-stripe status | `border-l-4 border-yellow-500` | `RECIPES.md` Status Pill recipe |
+| Two primary buttons | Two `variant="default"` Buttons in one surface | `nqui-composition/SKILL.md` |
+| Wall-of-cards layout | every section wrapped in Card | `COMPOSITION.md` |
+| Tooltip-as-label | icon button with only Tooltip context | A11y rule in `AGENT_PROMPT.md` |
+| Custom CSS where component exists | hand-rolled dropdown instead of `Select` | `AGENT_PROMPT.md` "never reach outside the kit" |
+
+---
+
+## Running the eval — what to do with results
+
+After running 12 prompts:
+
+1. **Sum scores.** Average ≥ 8 = ship. 7-8 = warn, fix obvious gaps. < 7 = block release.
+2. **Per-prompt analysis.** Which prompts scored low? Each low score points to a missing recipe or unclear rule.
+3. **Failure clustering.** If 5 prompts all forgot empty states, the issue is STATES.md isn't being read — restructure the routing in `READ_BUDGET.md`.
+4. **Anti-pattern leak detection.** If "no nested cards" was violated in 3+ prompts, add a lint rule, don't just update docs.
+5. **Trend over time.** Re-run after token changes / new components / doc rewrites. Did the score go up? Down? That's the signal.
+
+## When to run
+
+- **Before any release** that touches: tokens, component APIs, skills folder structure, AGENT_PROMPT
+- **After any breaking visual change** (we just shipped Card-no-shadow and chart palette flip — should have re-run)
+- **Monthly** as a baseline regression check
+- **Before adding a new component** — make sure existing patterns still work
+
+---
+
+## What this eval does NOT measure
+
+- Performance (runtime, bundle size) — separate concern
+- Accessibility audits (run axe-core separately)
+- Cross-browser rendering (visual regression suite)
+- Long-form copy quality (eval is short prompts)
+- Multi-page app coherence (eval is per-screen)
+
+These are valuable. They're not in scope here. The eval measures: **"given a prompt, does the agent produce something a Linear designer wouldn't be embarrassed by?"**
+
+That's the bar nqui ships to.

package/docs/nqui-skills/HUMAN_GUIDE.md

@@ -2,6 +2,24 @@
 
 Use this file for **wayfinding** before diving into `README.md` (long) or dozens of `nqui-*.md` files. Paths below are from the **nqui package**; after `npx @nqlib/nqui init-skills`, the same files live under **`.cursor/nqui-skills/components/`**.
 
+## Composition first (product UI)
+
+**Read:** [`COMPOSITION.md`](./COMPOSITION.md) — when to use Card, ToggleGroup vs RadioGroup, three-surface cap, anti-patterns.
+
+**Dev app (`npm run dev` in `packages/nqui`):**
+
+| Route | Purpose |
+|-------|---------|
+| `/` | **Recipes hub** — start here |
+| `/patterns` | Commerce dashboard recipe |
+| `/recipes/settings` | Settings form recipe |
+| `/catalog` | Component variant catalog |
+| `/design-system` | Tokens |
+
+Do **not** learn layout from the catalog alone — it is API reference, not composition guidance.
+
+---
+
 | I’m building… | Start here | Then open |
 |---------------|------------|-----------|
 | **Forms** (login, settings, checkout) | `docs/components/README.md` → Forms sections | One of `nqui-field.md`, `nqui-input.md`, `nqui-select.md`, `nqui-combobox.md`, … |

package/docs/nqui-skills/MIGRATION.md

@@ -0,0 +1,133 @@
+---
+name: nqui-migration
+description: Breaking changes consumers must be aware of when updating. Each entry includes what changed, why, and how to migrate. Keep this file additive — never edit historical entries, only append new ones.
+---
+
+# nqui Migration Notes
+
+When upgrading nqui, scan the latest version section for breaking changes BEFORE running `pnpm install`. Visual regressions disguise themselves as "the new design"; they aren't.
+
+---
+
+## v0.6 (current) — Design system rebuild
+
+This release applies the **2+1 elevation rule** to the token system, fixes several real bugs in color tokens, and tightens motion. Most changes are visual — runtime behavior is unchanged.
+
+### 🔴 Breaking visual changes
+
+#### 1. Card lost its default shadow
+**What:** `.nqui-card` no longer applies `box-shadow`. Card surfaces now rely on border + background contrast for separation.
+
+**Why:** The 2+1 elevation rule (see `ELEVATION.md`) reserves shadows for ELEVATED surfaces only (Dialog, Sheet, Popover, DropdownMenu). Inline cards with shadows produced template-y, decorative depth that competed with content.
+
+**Migration:**
+- If your app depends on Card lift, wrap with `.nqui-elevated` instead — but ask first whether you actually need elevation. Most "needs a shadow" instincts are better solved with `bg-muted/40` (surface B).
+- If you have custom CSS adding shadow to Card, remove it — that's now the system default.
+
+#### 2. Chart palette changed from 5-blues to categorical
+**What:** `--chart-1` through `--chart-5` used to be 5 shades of blue (hue 251-265). Now they're distinct hues: blue / orange / green / purple / amber.
+
+**Why:** 5 shades of blue is useless for categorical data — you can't tell series apart. The new palette is for *categorical* (different categories, different statuses). For *sequential* (ordinal intensity) data, override per the `THEMING.md` guide.
+
+**Migration:**
+- Audit any chart that depended on the old blue palette. Visualizations may look completely different now.
+- If you specifically need sequential blues, override `--chart-*` in your project (see `THEMING.md` → Chart palette).
+- This may shift the visual identity of dashboards — review screenshots before deploying.
+
+#### 3. Light mode sidebar flipped direction
+**What:** `--sidebar` in light mode was `oklch(0.953)` (DARKER than the `0.982` page background). Now `oklch(0.988)` (LIGHTER than page).
+
+**Why:** macOS, Linear, Vercel all do "sidebar lighter than page" — the sidebar lifts forward. Dark mode already did this. Light mode was inverted. Now they match.
+
+**Migration:**
+- Sidebar will look subtly different — lighter, more lifted. Verify your custom sidebar content still has enough contrast.
+- `--sidebar-accent` and `--sidebar-border` also adjusted to remain visible against the lighter sidebar.
+
+#### 4. Accent token darker in light mode
+**What:** `--accent` was `oklch(0.895)`, lighter than `--muted` (`0.914`). Now `oklch(0.880)`, properly darker for hover/selection contrast.
+
+**Why:** Real bug — accent was LIGHTER than the muted surface, so hover states *reduced* contrast instead of increasing it. Now hover is properly visible.
+
+**Migration:**
+- Hover and selection states on Items, list rows, etc. will appear darker than before. This is correct behavior. Don't override back to the old value.
+
+#### 5. Warning hue shifted (65 → 80)
+**What:** Warning was OKLCH hue 65 (olive/khaki, despite the comment claiming "orange"). Now hue 80 (true amber).
+
+**Why:** Bug. Warning badges and alerts looked slightly sickly. Now they read as amber/warning.
+
+**Migration:**
+- Visual shift, no API change. Verify warning states still read as intended in your theme.
+
+#### 6. Success hue shifted (142 → 135)
+**What:** Subtle 7° hue shift to harmonize with warm-paper background.
+
+**Why:** Hue 142 was cool emerald — clashed with the warm light-mode palette. Hue 135 is a slightly warmer green that fits.
+
+**Migration:**
+- Subtle. Existing green badges will look very slightly warmer. No action needed unless you've customized success colors.
+
+#### 7. Dark mode border softened (0.34 → 0.27)
+**What:** `--border` in dark mode was `oklch(0.34)` (drawn lines). Now `oklch(0.27)` (subtle folds).
+
+**Why:** Match Linear / Vercel dark-mode convention. Borders should read as "where surfaces meet," not as drawn lines.
+
+**Migration:**
+- Dark mode borders will be more subtle. Verify forms and panels still have enough definition. If a specific surface NEEDS a stronger border, opt in per-component.
+
+#### 8. Semantic foreground tokens aligned with `--foreground`
+**What:** `--primary-foreground`, `--success-foreground`, `--destructive-foreground`, etc. were all `oklch(0.98)` (near-pure white). Now `oklch(0.92)` (matching the global softened foreground).
+
+**Why:** Eye-strain consistency. 0.98 white on saturated backgrounds was harsh.
+
+**Migration:**
+- Text on colored buttons (primary/destructive/success) is now slightly softer. If contrast looks too low against a custom brand color, re-verify per `THEMING.md` checklist.
+
+#### 9. Tooltip z-index corrected (9998 → 70)
+**What:** `--z-tooltip` was `9998` (extreme value, fighting other systems). Now `70` (matches documented scale).
+
+**Why:** Was a patch that never got reconciled. The actual stacking scale documents tooltip at 70.
+
+**Migration:**
+- If you have custom z-index values above 70 that depended on tooltip being at 9998 to overlay them, they will now incorrectly cover tooltips. Refactor to use the `--z-*` semantic scale.
+
+#### 10. Motion: checkbox bounce removed
+**What:** Checkbox `transition` was `cubic-bezier(0.68, -0.55, 0.265, 1.55)` (elastic overshoot). Now standard ease-out.
+
+**Why:** Elastic/overshoot curves are explicitly banned per `MOTION.md`. They feel dated and AI-flavored.
+
+**Migration:**
+- Checkboxes now snap rather than bounce. This is intentional. If you preferred the bounce, you preferred the wrong thing.
+
+### 🟠 Internal restructuring (no API change, may affect overrides)
+
+- `src/styles/elevation.css` renamed to `src/styles/z-index.css` — the file is z-index tokens only, not surface depth. Elevation now lives in `ELEVATION.md` (philosophy) + `shadows.css` (shadow tokens).
+- New file `src/styles/motion.css` — duration + easing tokens + `prefers-reduced-motion` media query.
+- New file `src/styles/shadows.css` — `--shadow-elevated`, `--shadow-modal`, `--shadow-focus` tokens.
+- New semantic surface aliases: `--surface-a`, `--surface-b`, `--surface-elevated` (alias the existing `--background`, `--muted`, `--popover`).
+- `--popover` is now `var(--card)` (was a duplicated value pretending to be a separate token).
+- Sheet transitions changed from `duration-500`/`duration-300` to `duration-250`/`duration-200` for tighter feel.
+- Navigation menu chevron animation: `duration-300` → `duration-200`.
+- Enhanced progress bar: `duration-300` → `duration-200`.
+
+### ✅ Additive (not breaking)
+
+- New skill: `nqui-composition/SKILL.md` — Apple-inspired craft principles.
+- New skill docs: `RECIPES.md`, `STATES.md`, `WRITING.md`, `MOTION.md`, `ELEVATION.md`, `READ_BUDGET.md`, `AGENT_PROMPT.md`, `EVAL.md`, `THEMING.md`, `MIGRATION.md` (this file).
+- New showcase routes: `/recipes/tracker`, `/recipes/elevation`.
+- Updated `SKILL.md` Agent Build Protocol (now 10 steps, plus the "30-second Linear designer test").
+
+### Recommended migration path
+
+1. **Read the breaking changes above.** Identify which apply to your app.
+2. **Run your visual regression suite** if you have one. (If you don't — this release is a good reason to set one up.)
+3. **Audit chart-using pages first** — palette change is the most visible.
+4. **Audit Card-using pages** — shadow removal may reveal places that depended on lift.
+5. **Verify dark mode** — multiple dark token changes, easier to miss than light.
+6. **Run the eval** (see `EVAL.md`) against your most important pages — make sure the kit still produces good output for your common patterns.
+
+---
+
+## Earlier versions
+
+(Append entries for prior versions above this line, newest first, as future releases land.)

package/docs/nqui-skills/MOTION.md

@@ -0,0 +1,189 @@
+---
+name: nqui-motion
+description: Motion design as a system, not decoration. Easing vocabulary, timing scale, choreography, reduced-motion. Use when adding ANY animation or transition. Without this, motion is either absent (cold) or busy (chaotic).
+---
+
+# nqui Motion — Choreography, Not Decoration
+
+Motion is design. It either serves comprehension (showing where something came from, conveying hierarchy, providing feedback) or it's noise. This file is the vocabulary.
+
+## Three motion principles
+
+1. **Motion has a job.** Every animation answers one of: *Where did this come from? Where did it go? What changed? What's happening right now?* If you can't answer, cut the animation.
+2. **Motion respects continuity.** Things appear from their source (Sheet slides from edge, Popover scales from its trigger, Toast slides from the toast region — never from random space).
+3. **Motion gets out of the way.** A confirmation animation that takes 600ms means the user waits 600ms before moving on. Make motion fast unless it's communicating something significant.
+
+## The timing scale
+
+Use named tokens, not arbitrary milliseconds. These cover 95% of UI motion.
+
+| Token | Duration | When to use |
+|-------|----------|-------------|
+| **instant** | 0ms (no animation) | State toggles where motion would be a delay (`checked`, `disabled`) |
+| **micro** | 100ms | Hover states, focus rings, color shifts on press |
+| **quick** | 150ms | Most state changes: opening dropdowns, button presses, small reveals |
+| **standard** | 200-250ms | Modal/Sheet/Drawer entries, page transitions, accordion expansions |
+| **dramatic** | 300-400ms | One-off attention moments — initial empty state appearing, success confirmation, onboarding cues |
+| **never** | ≥500ms | Almost nothing. If you reach for 500ms+, you're decorating, not communicating |
+
+**Default if unsure:** 150ms (`quick`). Most UI motion should be this fast.
+
+## The easing vocabulary
+
+Easing curves communicate **physicality** — they tell the eye whether something is decelerating naturally (good) or moving mechanically (bad).
+
+| Curve | Tailwind / CSS | When |
+|-------|---------------|------|
+| **ease-out** (`cubic-bezier(0.16, 1, 0.3, 1)`) | `ease-out` | **Default for entrances.** Things decelerate as they arrive — feels natural |
+| **ease-in** (`cubic-bezier(0.4, 0, 1, 1)`) | `ease-in` | **Default for exits.** Things accelerate as they leave — out of the way |
+| **ease-in-out** | `ease-in-out` | Reserved for symmetric back-and-forth (toggle that animates same way both directions) |
+| **linear** | `linear` | Only for continuous motion (loading bar, spinner, marquee) — never for state changes |
+| **spring** (react-spring / framer) | — | Only when modeling physical objects (drag, drawer pull). Subtle, not bouncy |
+
+**Banned curves:** elastic, bounce, anything with overshoot > 10%. They look dated and tacky. Real objects decelerate smoothly; they don't sproing.
+
+## Animate this, never animate that
+
+| ✅ Animate | ❌ Never animate |
+|------------|------------------|
+| `opacity` | `width` / `height` (use grid-row tricks if you need height transition) |
+| `transform` (translate, scale, rotate) | `top` / `left` / `right` / `bottom` |
+| `filter: blur()` (sparingly) | `padding` / `margin` |
+| `background-color` (subtle, fast) | `box-shadow` (very expensive — use opacity on a shadow layer instead) |
+| `color` | `font-size` |
+| CSS variables (modern, GPU-friendly) | Layout properties that cause reflow |
+
+**Why:** transform and opacity are GPU-composited and free. Layout properties cause reflow and jank, especially during scroll.
+
+## What to animate, when
+
+### Entrance / exit (mount, unmount)
+- **Modal/Dialog:** scale from 95% + fade in, 200ms ease-out
+- **Sheet:** translate from off-screen edge, 250ms ease-out (in), 200ms ease-in (out)
+- **Popover/Tooltip:** scale from 95% + fade, 150ms ease-out, origin at trigger
+- **Toast:** slide in from toast region (usually bottom or top-right), 200ms ease-out
+- **Empty state on first appearance:** fade in + translate up 4px, 300ms ease-out
+- **List items appearing:** stagger 30ms per item, fade + translate up 8px each, ease-out
+
+### State changes
+- **Selection (item in a list):** background color shift, 150ms
+- **Button press:** scale 0.97 for 100ms, then back — micro-affordance
+- **Hover:** background or color shift, 100ms — never transform
+- **Focus ring:** instant appear, fade out at 150ms
+
+### Attention direction (use sparingly)
+- **Skeleton → real content:** crossfade 150ms (avoid the "snap")
+- **Optimistic item appearing:** fade in at 70% opacity, then to 100% when confirmed
+- **Error shake:** translate x ±4px, 4 cycles of 50ms each — only for form submission errors with severity
+
+### Continuous (loading)
+- **Spinner:** 1 full rotation per 900ms, linear
+- **Skeleton shimmer:** 1.5s loop, ease-in-out, very subtle (8-12% opacity range)
+- **Loading bar (indeterminate):** 1.5s loop, ease-in-out
+- **Progress bar (determinate):** transition `width` change with 200ms ease-out (this is one of the few times width animation is OK because it represents real progress)
+
+## Choreography — when multiple things move
+
+Bad: everything animates at once → chaos.
+Good: a clear sequence the eye can follow.
+
+### Stagger
+When N similar things appear (list items, cards, nav items), animate them sequentially with a small delay (20-40ms between each). Stagger creates a sense of rhythm and avoids the "everything pops at once" feel.
+
+```tsx
+{items.map((item, i) => (
+  <div
+    key={item.id}
+    style={{ animationDelay: `${i * 30}ms` }}
+    className="animate-fade-in-up"
+  >
+    ...
+  </div>
+))}
+```
+
+**Cap stagger at ~8 items.** Beyond that, the last items appear so late it feels broken. For larger lists, skip the stagger or use a much smaller delay (10ms).
+
+### Sequence (different things, in order)
+When a complex element appears, parts can arrive in sequence — but only when sequence conveys meaning:
+
+```
+modal appears:
+  backdrop fades in (150ms)
+  → modal scales in (200ms, starts at 50ms — backdrop catches up)
+  → modal content fades in (150ms, starts at 200ms)
+```
+
+**Default to simultaneous unless sequence is meaningful.** Don't sequence parts of a single UI element — that fragments perception.
+
+## Reduced motion (mandatory)
+
+Respect `prefers-reduced-motion: reduce`. This is not optional — vestibular disorders are real.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+**What survives reduced motion:**
+- Opacity transitions (fade in/out) — these don't cause vestibular issues
+- Color transitions — fine
+- Subtle scale (≤ 5% change) — fine
+
+**What gets disabled:**
+- All translate-based animations (slide-in, slide-up)
+- Spinners (replace with text "Loading…")
+- Parallax, scroll-driven motion
+- Auto-playing carousels
+
+**The pattern:** wrap motion in a media query and provide a static alternative:
+
+```tsx
+const prefersReducedMotion = useReducedMotion()
+
+<div className={prefersReducedMotion ? "" : "animate-slide-in"}>
+  {content}
+</div>
+```
+
+## Anti-patterns (the AI-motion ones)
+
+These are the motion patterns that immediately signal AI-generated:
+
+| ❌ Anti-pattern | ✅ Use instead |
+|----------------|---------------|
+| Bouncing/elastic everything | Smooth ease-out, no overshoot |
+| 500ms+ for routine state changes | 150ms |
+| Animating layout (width/height/padding) | Transform + opacity |
+| Sequential typewriter text reveal | Just render the text |
+| Hover scales > 1.05 | Hover background shift only |
+| Wobbly button presses | scale(0.97) for 100ms, done |
+| Marquee scrolling text in non-marketing UI | Truncate with ellipsis |
+| Pulsing CTAs to "draw attention" | Better hierarchy, not motion |
+| Spinning logos | Why? Just why? |
+| Hero "shimmer" effects on every gradient | One shimmer, on one element, occasionally |
+| Per-letter text animation in product UI | Reserve for marketing landing pages |
+
+## The motion audit
+
+Before shipping:
+
+- [ ] Every animation answers one of the four "why" questions (where from / where to / what changed / what's happening)
+- [ ] No animation is longer than 250ms unless it's the rare "dramatic" moment
+- [ ] Animating only `transform` and `opacity` (no layout props)
+- [ ] Easing is ease-out for entrances, ease-in for exits (never linear except for continuous)
+- [ ] `prefers-reduced-motion: reduce` is respected — verified with the OS toggle
+- [ ] No bounce, elastic, or overshoot curves anywhere
+- [ ] Stagger capped at ~8 items
+- [ ] No infinite/looping animation outside of loading states
+- [ ] Hover states are color/background shifts, not transforms
+
+If anything moves "to look cool" rather than to serve comprehension, cut it.