@nqlib/nqui 0.5.6 → 0.6.1

package/docs/nqui-skills/ELEVATION.md

@@ -0,0 +1,181 @@
+---
+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.
+
+## Mode 3: Single-surface refinement (not just an "exception")
+
+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.
+
+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.
+
+### 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
+
+| ❌ 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.)