@exxatdesignux/ui 0.5.11 → 0.5.12

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.5.12
+
+### Patch Changes
+
+- **The legacy `template/` (Next.js scaffold) is retired and no longer ships in the npm tarball.** It was already unreachable from the CLI as of 0.5.11 (`create-exxat-app` scaffolds from `template-vite/` only) and was being half-regenerated from the now-Vite `apps/web/` at publish time, leaving consumers with a Next.js eslint config layered over a Vite source tree. Three concrete changes in this release:
+  - **`packages/ui/package.json` `files`** drops `template` — `template-vite` is the only scaffold shipped.
+  - **CLI help (`exxat-ui update`)** points at `node_modules/@exxatdesignux/ui/template-vite/` when it suggests "compare your app with the reference template".
+  - **Workspace rules and skills** (`exxat-nav-single-active.mdc`, `exxat-library-hub-header.mdc`, `exxat-ds-skill`) point at `template-vite/` paths instead of `template/`. `consumer-extras/` regenerates from those sources.
+  - The `sync-template-from-web.mjs` script and the workflow step that runs it are kept (now a no-op for the published tarball) so the build pipeline continues to typecheck/lint a known-shaped reference, and so the next migration off it is a small follow-up rather than a workflow edit. Consumers see no regression — `exxat-ui sync-extras` continues to be the supported channel for rules + skills + patterns.
+- **The reference app (`apps/web`) is now Vite + React + react-router-dom — Next.js fully removed.** A six-PR program (May 2026) cut steady-state dev memory from **1.4–4 GB RSS per `next-server`** down to **~250–500 MB per `vite`**, and cold start from 8–12 s to **~150–300 ms**. Designers running long sessions and customers comparing two branches side-by-side were the practical reason; the stack swap is what made it possible. Three layers of the published package change because of this.
+  - **`scripts/dev-guard.mjs`** is now Vite-only. The detector that previously listed running `next-server` parents was carrying dead code branches after PR-6; it now matches `vite` processes only and the warning copy is rewritten ("Two parallel Vite servers stabilize at ~500–800 MB combined and confuse HMR"). Customer apps that wired `predev: exxat-ui dev-guard` keep working unchanged — the guard simply reflects the new stack.
+  - **`bin/init.mjs`** drops `--stack=vite|next`. There is one starter now and it is `template-vite/` — Vite 6 + React 19 + react-router-dom + Tailwind v4 + TypeScript. The CLI's `--help` text and on-screen messages were rewritten to match. Customers that need a Next.js scaffold can copy `template-vite/` and bring their own `next.config.mjs` — the components, tokens, and rules are all stack-agnostic.
+  - **`bin/cli.mjs`** help text is updated: `dev-guard` reads "Detect concurrent Vite dev servers" instead of "Next.js + Vite", and `audit` audits a "React component / route" rather than a "Next.js component / route".
+- **Consumer-extras and patterns refreshed for the Vite stack.** Every `npx exxat-ui sync-extras` payload that mentioned Next now reads as it does in the workspace today:
+  - **`patterns/perf-memory-pattern.md`** rewritten end-to-end. It used to be Next + Turbopack tuning ("`NODE_OPTIONS=--max-old-space-size=6144`", "Turbopack mmap'd FS cache", `pnpm clean:cache` for `.next/dev/cache`). It is now a Vite + Node 24 doc — the four knobs that matter (`dev-guard`, `optimizeDeps.include`, `optimizeDeps.exclude` for the workspace package, `resolve.dedupe` for React), how to bust `node_modules/.vite/`, and how to diagnose RSS climbing past 1 GB. A short "History" callout still explains where the 8× memory drop came from for anyone reading the migration in context.
+  - **`patterns/consumer-upgrade-checklist.md`** §3 now points at `node_modules/@exxatdesignux/ui/template-vite/` (was `template/`) and adds a "Migrating an existing Next.js consumer to Vite?" pointer for customers ready to follow the same path the reference app took.
+  - **`cursor-rules/exxat-no-slds-leakage.mdc`**, **`cursor-rules/exxat-primary-nav-secondary-panel.mdc`**, **`cursor-rules/exxat-list-page-view-shells.mdc`**, **`cursor-rules/exxat-command-menu.mdc`**, **`apps/web/.cursor/rules/exxat-dashboard-view-charts.mdc`** updated: where they cited `app/(app)/...` paths and `Next.js bundle` / `next/Link` / `Next.js app`, they now cite `src/views/...`, `src/App.tsx`, `Vite bundle`, and `react-router-dom Link`. Pure documentation — no rule logic changed, no globs broadened.
+  - **`consumer-extras/README.md`** drops the `--stack=next` example and rewords the `dev-guard` description to be Vite-only.
+- **Designer landing page (`DESIGNER_LANDING.html`) refreshed.** The hero hint, "Starting fresh" / "Already coding" paths, and the *Sixty seconds* §ii ("Teach Next to transpile" → "No bundler config needed") all match the new stack. The "Layout that speaks Arabic." highlight card was removed — the DS doesn't yet ship logical-property layout end-to-end and the claim overstated 0.5.3.
+- **Why this is a `0.5.x` patch and not a major bump:** the **runtime API** of `@exxatdesignux/ui` did not change. Every component, hook, token, and CSS export has the same shape it had in 0.5.11. What changed is which sample stack the published `template-vite/` runs, what `dev-guard` looks for in `ps`, and what the bundled rules / patterns / handbook say about the reference app. Customer apps that already install the package keep working with no code changes; running `exxat-ui sync-extras` after the upgrade refreshes the docs and rules in place.
+- **Customer migration steps** (only if you want the new dev-experience pattern):
+  1. **`pnpm add @exxatdesignux/ui@0.5.12`** in your app.
+  2. **`npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras`** to pull the refreshed rules + patterns.
+  3. If you ran a *Next.js* app and want to migrate to Vite, follow the new §7 "Upgrading an existing customer app to the Vite stack" in `perf-memory-pattern.md` (the same six-step program the reference app followed; the codemod for `next/*` → `react-router-dom` lives in commit `d16ec77` of this repo if you need a starting point).
+  4. If you stay on Next.js, no action required — the package supports any React app via `transpilePackages: ["@exxatdesignux/ui"]`.
+
 ## 0.5.11
 
 ### Patch Changes

package/bin/cli.mjs

@@ -33,6 +33,65 @@ function runSyncExtras() {
   })
 }
 
+function runDevGuard(extraArgs) {
+  const script = resolve(__dirname, "../consumer-extras/scripts/dev-guard.mjs")
+  if (!existsSync(script)) {
+    // Old install — pass through silently so predev hooks never break a build.
+    process.exit(0)
+  }
+  try {
+    execFileSync(process.execPath, [script, ...extraArgs], {
+      stdio: "inherit",
+      cwd: process.cwd(),
+    })
+  } catch (err) {
+    process.exit(err?.status ?? 1)
+  }
+}
+
+/**
+ * `exxat-ui audit <file>` — engineer-facing quality gate.
+ *
+ * The full audit logic lives in the `exxat-ux-audit` skill (consumed by
+ * Cursor / Claude). This subcommand is a *stub* that prints the right
+ * invocation for both clients and exits. It is *not* a standalone linter —
+ * a full machine audit lives behind the agent so the rules stay in one
+ * place (the skill) instead of being duplicated in JS.
+ */
+function runAudit(args) {
+  const target = args[0]
+  if (!target) {
+    console.error("Usage: exxat-ui audit <file-or-route>\n")
+    console.error("Audits a React component / route against the Exxat DS")
+    console.error("rules + UX principles (P1–P20) + modern SaaS patterns (M1–M12).\n")
+    console.error("This stub prints the agent prompt to run; the actual audit is")
+    console.error("performed by the `exxat-ux-audit` skill in your agent client.")
+    process.exitCode = 1
+    return
+  }
+  console.log(`
+Audit target: ${target}
+
+Run inside Cursor or Claude Code:
+
+  /skill exxat-ux-audit
+  audit ${target}
+
+The skill loads:
+  • .cursor/rules/exxat-accessibility.mdc      (a11y floor)
+  • .cursor/rules/exxat-ux-principles.mdc      (P1–P20)
+  • .cursor/rules/exxat-token-discipline.mdc   (no hex)
+  • .cursor/rules/exxat-no-toast.mdc           (no Sonner)
+  • .cursor/rules/exxat-ds-agents.mdc          (top of stack)
+
+…and produces a Blocker / Issue / Nit findings report with code citations
+and a fix plan. Text-only Blocker fixes are auto-applied on confirmation.
+
+For headless / CI use: hit the same skill via the SDK
+(\`@cursor/sdk\` Agent.prompt) and grep the JSON output for "Blocker:".
+`)
+}
+
 /** @returns {number} negative if a < b, 0 if equal, positive if a > b (x.y.z only) */
 function compareSemver(a, b) {
   const pa = a.split(".").map(n => parseInt(n, 10) || 0)
@@ -55,6 +114,10 @@ Commands:
   update       How to upgrade an existing project that depends on this package.
   changelog    Print CHANGELOG.md from the installed package (release notes + AI upgrade hints).
   doctor       Compare this CLI version vs npm registry "latest" (diagnose stale installs).
+  dev-guard    Detect concurrent Vite dev servers — the #1 memory killer.
+               Wire as a "predev" hook to abort if a sibling dev server is already running.
+  audit <f>    Print the prompt to audit a file against DS rules + UX principles (P1–P20).
+               The audit runs inside your agent client (the exxat-ux-audit skill).
 
 Do NOT use plain npx @exxatdesignux/ui — use the scoped form below.
 
@@ -100,7 +163,7 @@ After upgrading — for humans and AI tools:
        npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras
 
   3. Compare your app with the reference template when something new is unclear:
-       node_modules/@exxatdesignux/ui/template/
+       node_modules/@exxatdesignux/ui/template-vite/
 
 **Still seeing old code?** Run **exxat-ui doctor** — the npm "latest" tag can lag
 this Git repo until maintainers publish (git tag **ui-v<version>**).
@@ -191,6 +254,12 @@ switch (cmd) {
   case "doctor":
     printDoctor()
     break
+  case "dev-guard":
+    runDevGuard(process.argv.slice(3))
+    break
+  case "audit":
+    runAudit(process.argv.slice(3))
+    break
   case "help":
   case "--help":
   case "-h":

package/bin/init.mjs

@@ -18,15 +18,27 @@ import { fileURLToPath } from "node:url"
 import { execSync } from "node:child_process"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
-const templateDir = resolve(__dirname, "../template")
 const selfPkgPath = resolve(__dirname, "../package.json")
 const selfPkg = JSON.parse(readFileSync(selfPkgPath, "utf8"))
 
 const args = process.argv.slice(2)
-const flags = new Set(args.filter((a) => a.startsWith("--")))
+const allFlags = args.filter((a) => a.startsWith("--"))
+const flags = new Set(allFlags.map((f) => (f.includes("=") ? f.slice(0, f.indexOf("=")) : f)))
 const positional = args.filter((a) => !a.startsWith("--"))
 const targetArg = positional[0] ?? "."
 const targetDir = resolve(process.cwd(), targetArg)
+
+// `template-vite/` is the canonical scaffold source. The `template/`
+// (Next.js) directory was retired alongside the apps/web Next removal
+// (PR-6, May 2026); customers who need a Next scaffold can copy
+// `template-vite/` and migrate it.
+const templateDirName = "template-vite"
+const templateDir = resolve(__dirname, `../${templateDirName}`)
+if (!existsSync(templateDir)) {
+  console.error(`❌  Template directory ${templateDirName}/ not found in this @exxatdesignux/ui release.`)
+  console.error(`    Try upgrading: npm i @exxatdesignux/ui@latest`)
+  process.exit(1)
+}
 // `displayName` is what we show in messages and use to derive package.json
 // `name`. For "." or an absolute path we just use the basename; for a
 // relative path the user typed (`my-app`, `apps/sandbox`) we keep it as-is.
@@ -41,7 +53,9 @@ const skipExtras = flags.has("--no-extras") || flags.has("--skip-extras")
 
 if (flags.has("--help") || flags.has("-h")) {
   console.log(`
-create-exxat-app — scaffold a Next.js app on @exxatdesignux/ui
+create-exxat-app — scaffold a starter app on @exxatdesignux/ui
+
+Stack: Vite + React + react-router-dom (low-memory, fast HMR).
 
 Usage:
   create-exxat-app [target-directory] [options]
@@ -97,7 +111,7 @@ if (blockers.length > 0 && !force) {
   process.exit(1)
 }
 
-console.log(`📦  Copying Exxat DS starter app into ${displayName}/ …`)
+console.log(`📦  Copying Exxat DS starter app (Vite) into ${displayName}/ …`)
 cpSync(templateDir, targetDir, { recursive: true })
 
 // Pin DS to this CLI's published version so `latest` cache drift cannot

package/bin/sync-extras.mjs

@@ -37,10 +37,11 @@ function log(...m) {
 }
 
 const SOURCES = {
-  skills:   join(pkgRoot, "consumer-extras", "cursor-skills"),
-  rules:    join(pkgRoot, "consumer-extras", "cursor-rules"),
-  patterns: join(pkgRoot, "consumer-extras", "patterns"),
-  handbook: join(pkgRoot, "consumer-extras", "handbook"),
+  skills:    join(pkgRoot, "consumer-extras", "cursor-skills"),
+  rules:     join(pkgRoot, "consumer-extras", "cursor-rules"),
+  patterns:  join(pkgRoot, "consumer-extras", "patterns"),
+  handbook:  join(pkgRoot, "consumer-extras", "handbook"),
+  templates: join(pkgRoot, "consumer-extras", "templates"),
 }
 
 const DESTINATIONS = {
@@ -49,6 +50,7 @@ const DESTINATIONS = {
   cursorRules:   join(cwd, ".cursor", "rules"),
   patterns:      join(cwd, "docs", "exxat-ds"),
   handbook:      join(cwd, "docs", "exxat-ds", "handbook"),
+  templates:     join(cwd, "docs", "exxat-ds", "templates"),
 }
 
 let wrote = 0
@@ -150,11 +152,33 @@ function syncHandbook() {
   }
 }
 
+/**
+ * Templates (handoff.md etc.) land in `docs/exxat-ds/templates/` next to the
+ * patterns + handbook. The agent fills them in via the `exxat-ux-discovery-protocol`
+ * rule at the close of any design task.
+ */
+function syncTemplates() {
+  if (!existsSync(SOURCES.templates)) {
+    console.warn("[sync-extras] no packaged templates (optional)")
+    skipped++
+    return
+  }
+  mkdirSync(DESTINATIONS.templates, { recursive: true })
+  for (const name of readdirSync(SOURCES.templates)) {
+    const src = join(SOURCES.templates, name)
+    if (!statSync(src).isFile()) continue
+    cpSync(src, join(DESTINATIONS.templates, name))
+    log(`[sync-extras] wrote docs/exxat-ds/templates/${name}`)
+    wrote++
+  }
+}
+
 syncSkillsTo(".cursor/skills", DESTINATIONS.cursorSkills)
 syncSkillsTo(".claude/skills", DESTINATIONS.claudeSkills)
 syncRules()
 syncPatterns()
 syncHandbook()
+syncTemplates()
 
 console.log(`[sync-extras] Done. ${wrote} files / dirs written; ${skipped} optional sources missing.`)
 if (!QUIET) console.log("[sync-extras] Product routes and app content were not modified.")

package/consumer-extras/README.md

@@ -11,6 +11,40 @@ touching product routes or pages.
 | `cursor-rules/exxat-*.mdc` | `.cursor/rules/exxat-*.mdc` (replaced) — binding **MUST / MUST NOT** files |
 | `patterns/*.md` | `docs/exxat-ds/*.md` (replaced) — pattern docs + **`consumer-upgrade-checklist.md`** |
 | `handbook/*.md` | `docs/exxat-ds/handbook/*.md` (replaced) — `HANDBOOK`, `glossary`, `voice-and-tone`, `reference-implementations` |
+| `templates/handoff.md` | `docs/exxat-ds/templates/handoff.md` (replaced) — design → engineering handoff artifact (the agent fills this in at the close of every design task) |
+| `scripts/dev-guard.mjs` | Runs in place via `exxat-ui dev-guard` (no copy) — wire as `predev` to abort if a sibling `vite` is already running and stacking memory |
+
+## CLI — what each subcommand does for your team
+
+```bash
+# Scaffold a new app (Vite + React + react-router-dom — fast cold start, ~250–400 MB RSS):
+npx --package=@exxatdesignux/ui@latest create-exxat-app my-app
+
+# Engineering quality-gate — read DS rules + UX principles for a file:
+npx --package=@exxatdesignux/ui@latest exxat-ui audit src/views/students.tsx
+
+# Memory guard for designers running long dev sessions:
+"scripts": { "predev": "exxat-ui dev-guard" }
+```
+
+`dev-guard` lists every running `vite` parent and refuses to start a second
+one without confirmation. Per `patterns/perf-memory-pattern.md` §2, two
+parallel Vite servers stabilize at ~500–800 MB combined and confuse HMR —
+even though they're 8× lighter than the Next dev servers this CLI used to
+guard against (May 2026 migration).
+
+## Rule tiers (`appliesTo:` metadata)
+
+Every shipped `.mdc` rule carries an `appliesTo:` field:
+
+- `[universal]` — UX principles, accessibility floor, anti-patterns, decision
+  frameworks. Works for any framework (HTML, React, Vue, iOS).
+- `[react]` — cites React component names / hooks / JSX. Auto-attaches via
+  `globs:` when the agent edits matching files; not always-on.
+
+Today this is documentation metadata. It is positioned for a future
+`exxat-ui sync-extras --stack=html` flag that filters out `[react]` rules
+for non-React consumers.
 
 The CLI is **namespaced**: it only touches files starting with `exxat-` (skills + rules)
 so a consumer's own non-Exxat rules / skills are preserved. Product code under `app/`,
@@ -41,11 +75,13 @@ pnpm --filter @exxatdesignux/ui vendor:consumer-extras
     └── exxat-ds/
         ├── *-pattern.md          ← narrative pattern docs (patterns/)
         ├── consumer-upgrade-checklist.md
-        └── handbook/
-            ├── HANDBOOK.md
-            ├── glossary.md
-            ├── voice-and-tone.md
-            └── reference-implementations.md
+        ├── handbook/
+        │   ├── HANDBOOK.md
+        │   ├── glossary.md
+        │   ├── voice-and-tone.md
+        │   └── reference-implementations.md
+        └── templates/
+            └── handoff.md         ← design → engineering handoff artifact
 ```
 
 ## Note on handbook link rewriting

package/consumer-extras/cursor-rules/exxat-accessibility.mdc

@@ -1,6 +1,7 @@
 ---
 description: Exxat DS — WCAG 2.1 AA, ARIA tablists, 24px targets, contrast; see AGENTS.md §8 and exxat-accessibility skill
 alwaysApply: true
+appliesTo: [universal]
 ---
 
 # Exxat DS — accessibility (binding summary)
@@ -26,7 +27,7 @@ alwaysApply: true
    - **C. Interactive icon-only button/link** (close `×`, chevron, overflow `⋯`, sort direction, filter chip dismiss, copy, Ask Leo toggle, row actions) → MUST pair **`aria-label`** on the `<button>` with a wrapping **`Tooltip`**. `aria-label` alone is NOT enough — sighted mouse users and keyboard users rely on the tooltip to discover what a bare icon does.
 
    In all three cases, the inner `<i>` / `<svg>` MUST be `aria-hidden`; the accessible name lives on the wrapping element. Tooltip text MUST match the accessible name. Narrow exception: a chevron inside a labelled composite (`Select`, `Combobox`) where the parent control already names the whole thing. See **§8.6 (Case A/B/C)** in `AGENTS.md` and the accessibility skill.
-10. **Keyboard shortcut hints inside buttons** MUST use **`<Kbd variant="bare">`** (no background, no border, inherits `currentColor` at 70%). The default `tile` variant is reserved for **tooltips** and **menu `shortcut=` slots**. Glue multi-key chords into one bare kbd (e.g. `<Kbd variant="bare">⌘⌥K</Kbd>`), not one tile per key. Reference: `Next` / `Back` buttons in `new-placement-form.tsx`; see `.cursor/rules/exxat-kbd-shortcuts.mdc`.
+10. **Keyboard shortcut hints inside buttons** MUST use **`<Kbd variant="bare">`** (no background, no border, inherits `currentColor` at 70%). The default `tile` variant is reserved for **tooltips** and **menu `shortcut=` slots**. Glue multi-key chords into one bare kbd (e.g. `<Kbd variant="bare">⌘⌥K</Kbd>`), not one tile per key. Reference: `Next` / `Back` buttons in `new-library-item-form.tsx`; see `.cursor/rules/exxat-kbd-shortcuts.mdc`.
 
 After changing **views toolbar** or **tab** UIs, re-run **axe** (or equivalent) on **Placements** (or the affected page).
 

package/consumer-extras/cursor-rules/exxat-board-cards.mdc

@@ -1,6 +1,8 @@
 ---
-description: Exxat DS — board (kanban) cards; ListPageBoardCard, badges, primitives
-alwaysApply: true
+description: Exxat DS — board (kanban) cards via ListPageBoardCard, badges, primitives. Auto-attaches when editing React board/list files; ask explicitly when designing kanban surfaces.
+globs: apps/web/components/**/*.{tsx,ts}
+alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — board cards
@@ -11,7 +13,7 @@ alwaysApply: true
 
 1. **Shell** — Use **`ListPageBoardCard`** from **`components/data-views/list-page-board-card.tsx`** for product board cards (same **`Card` `size="sm"`** treatment as Placements).
 2. **Hierarchy** — **Title** (`ListPageBoardCardTitleRow`) → optional **avatar** (`ListPageBoardCardAvatar` on `trailing`) → **status row** (`ListPageBoardCardBadgeRow` + **`ListHubStatusBadge`** **`surface="board"`**) when the entity has status → **body** (`ListPageBoardCardBody`) with **`BoardCardTwoLineBlock`** / **`BoardCardIconRow`** (**`components/data-views/board-card-primitives.tsx`**).
-3. **Status** — **Placements** (**`PLACEMENT_STATUS_*`** + **`StatusBadge`** in **`placements-table-cells.tsx`**), **Team / Compliance / Library** (**`ListHubStatusBadge`** + entity maps): all labels/tints/icons live in **`lib/list-status-badges.ts`**. **`surface="table"`** in grid/list rows, **`surface="board"`** on kanban cards. Prefer semantic **`LIST_HUB_STATUS_TINT_*`**. **MUST NOT** use **`uppercase`** on those chips.
+3. **Status** — Use **`ListHubStatusBadge`** with **`surface="table"`** in grid / list rows and **`surface="board"`** on kanban cards. Generic semantic tints live in **`lib/list-status-badges.ts`** (**`LIST_HUB_STATUS_TINT_SUCCESS / WARNING / INFO / NEUTRAL / DANGER`**); compose per-domain label / icon maps next to the entity's mock data. Reference: **`library-board-view.tsx`** + **`lib/mock/library.ts`**. **MUST NOT** use **`uppercase`** on those chips.
 4. **Simple column boards** — **`ListPageBoardTemplate`** + **`renderCard`**; compose **`ListPageBoardCard`** inside **`renderCard`**.
 
 ## MUST NOT

package/consumer-extras/cursor-rules/exxat-breadcrumbs-no-back.mdc

@@ -2,6 +2,7 @@
 description: Do not duplicate parent navigation with a Back control when breadcrumbs exist
 globs: apps/web/**/*.tsx
 alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — breadcrumbs and back navigation

package/consumer-extras/cursor-rules/exxat-card-vs-list-rows.mdc

@@ -1,6 +1,7 @@
 ---
 description: Exxat DS — when to use cards vs DataTable rows vs simple list rows.
 alwaysApply: true
+appliesTo: [universal]
 ---
 
 # Exxat DS — cards vs rows vs lists

package/consumer-extras/cursor-rules/exxat-centralized-list-dataset.mdc

@@ -1,6 +1,8 @@
 ---
-description: Single source of truth for hub rows, KPIs, table properties, detail views, and shared view chrome — dataset + presentation consistency across DataListViewType surfaces
-alwaysApply: true
+description: Single source of truth for hub rows, KPIs, table properties, detail views, and shared view chrome — dataset + presentation consistency across DataListViewType surfaces. Auto-attaches when editing list-hub React files.
+globs: apps/web/{components,lib}/**/*.{tsx,ts}
+alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — centralized list hub dataset + presentation

package/consumer-extras/cursor-rules/exxat-collaboration-access.mdc

@@ -2,6 +2,7 @@
 description: Shared hubs — collaboration header, invite sheet, library access vs directory roles
 globs: apps/web/components/**/*.{tsx,ts},apps/web/lib/**/*.{tsx,ts}
 alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — collaboration & access

package/consumer-extras/cursor-rules/exxat-command-menu.mdc

@@ -1,19 +1,20 @@
 ---
 description: Exxat DS — global command palette (⌘K) as search + quick AI vs Ask Leo for long answers.
 alwaysApply: true
+appliesTo: [universal]
 ---
 
 # Exxat DS — global command palette (`CommandMenu`)
 
 ## Intent
 
-- **`CommandMenu`** (**⌘K** / **Ctrl+K**) is **global search** (routes, library, patterns, AI starters, optional row data such as placements / student names) — see **`apps/web/AGENTS.md` §7.1** and **`apps/web/docs/command-menu-pattern.md`**.
+- **`CommandMenu`** (**⌘K** / **Ctrl+K**) is **global search** (routes, library, patterns, AI starters, optional row data such as student names / question stems) — see **`apps/web/AGENTS.md` §7.1** and **`apps/web/docs/command-menu-pattern.md`**.
 - **Quick / lookup / short AI:** Prefer **results inside the palette** when the product can return compact answers or lightweight “research” without leaving the flow.
 - **Long or complex answers:** **Ask Leo** side panel (**⌘⌥K** / **Ctrl+Alt+K**)—not forced into the palette.
 
 ## Implementation pointers
 
-- Shell: `apps/web/components/command-menu.tsx`; config **`buildCommandMenuConfig()`** in **`apps/web/lib/command-menu-config.ts`**; optional **`dataGroups`** from **`apps/web/lib/command-menu-search-data.ts`** (e.g. **`getCommandMenuSearchDataGroups()`**), wired in **`apps/web/app/(app)/layout.tsx`**. Keep domain mapping out of the shell.
+- Shell: `apps/web/components/command-menu.tsx`; config **`buildCommandMenuConfig()`** in **`apps/web/lib/command-menu-config.ts`**; optional **`dataGroups`** from **`apps/web/lib/command-menu-search-data.ts`** (e.g. **`getCommandMenuSearchDataGroups()`**), wired in **`apps/web/src/App.tsx`**. Keep domain mapping out of the shell.
 - Large indexes: set **`searchOnly: true`** on **`CommandMenuGroup`** so **`command-menu.tsx`** skips the group until the user types (avoids listing every row on open; cmdk shows all items when the search string is empty).
 
 ## See also

package/consumer-extras/cursor-rules/exxat-data-tables.mdc

@@ -1,6 +1,8 @@
 ---
-description: Exxat DS — product data tables must use DataTable with search, filters, and table properties; no alternate table stacks.
-alwaysApply: true
+description: Exxat DS — product data tables must use HubTable/DataTable with search, filters, table properties; no alternate table stacks. Auto-attaches when editing apps/web React files; ask for it explicitly when designing a list/grid surface.
+globs: apps/web/**/*.{tsx,ts}
+alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — data tables (mandatory pattern)
@@ -17,7 +19,7 @@ For **any app screen that shows a browsable, filterable grid of records** (direc
 6. **Table properties:** Always reachable. `HubTable` mounts `TablePropertiesDrawerButton` in `toolbarSlot`; on **`ListPageTemplate`** pages with **table / list / board / dashboard** tabs it **MUST** also receive **`currentView`** and **`onViewChange`** (see **`apps/web/AGENTS.md` §4.2** and **`.cursor/rules/exxat-table-properties-drawer.mdc`**) so Properties matches the selected view.
 7. **Dropdown menus:** `DropdownMenuContent` uses the shared **`@exxatdesignux/ui`** default (**intrinsic `w-max`**, **`min-w-52`**, capped **`max-w`**) for view settings, row ⋯, column menus, and filter pickers — **pure CSS**, no **`ResizeObserver`**. Override only for deliberate narrow/wide rails (e.g. pagination **`w-20`**, account trigger-width, school switcher **`!w-max min-w-72 …`**). See **`docs/data-views-pattern.md`** (“Dropdown menus”).
 8. **Cell renderers MUST come from `@/components/data-views` (`table-cells.tsx`).** The DS ships **`ProgressCell`**, **`CurrencyCell`**, **`NumericCell`**, **`RatingCell`**, **`SignalBarsCell`**, **`BooleanToggleCell`**, **`AttachmentCountCell`**, **`ExternalLinkCell`**, **`RelativeTimeCell`**, **`PeopleAvatarRailCell`**, **`PillCell`**, **`TagListCell`**, and a generic **`RowActionsCell<TRow>`**. A `ColumnDef['cell']` for these patterns is a **one-liner** that calls the named cell. **MUST NOT** inline `Intl.NumberFormat`, raw `<a target="_blank">`, `[1,2,3,4,5].map(s => …)` star loops, paperclip + count chips, custom face-rail `AvatarGroup`s, or per-hub `DropdownMenu` overflow menus inside `cell:` — those are signals you're re-deriving a shipped primitive. Catalog: `apps/web/components/columns-showcase.tsx` (`/columns`). Skill: `.cursor/skills/exxat-token-economy/SKILL.md` §3.
-9. **Add view parity** — **`FULL_HUB_SUPPORTED_VIEWS`** + a real renderer per view — **`.cursor/rules/exxat-hub-supported-views.mdc`**, **`docs/exxat-ds/patterns/hub-supported-views-pattern.md`**.
+9. **Add view parity** — **`FULL_HUB_SUPPORTED_VIEWS`** + a real renderer per view — **`.cursor/rules/exxat-hub-supported-views.mdc`**, **`apps/web/docs/hub-supported-views-pattern.md`**.
 
 **Reference implementations:**
 

package/consumer-extras/cursor-rules/exxat-dedicated-search-surfaces.mdc

@@ -1,3 +1,10 @@
+---
+description: Dedicated search surfaces — DedicatedSearch* templates, recents storage, landing-vs-results URL composer. Auto-attaches when editing search-related React routes.
+globs: apps/web/{components,app,lib}/**/*.{tsx,ts}
+alwaysApply: false
+appliesTo: [react]
+---
+
 # Exxat DS — dedicated search surfaces
 
 **Authoritative detail:** **`apps/web/AGENTS.md` §4.8**, **`.cursor/skills/exxat-dedicated-search-surfaces/SKILL.md`**.

package/consumer-extras/cursor-rules/exxat-drawer-vs-dialog.mdc

@@ -1,6 +1,7 @@
 ---
 description: Exxat DS — drawer/sheet vs modal dialog vs route for flows and confirmations.
 alwaysApply: true
+appliesTo: [universal]
 ---
 
 # Exxat DS — drawer vs dialog
@@ -19,4 +20,4 @@ alwaysApply: true
 ## See also
 
 - **`docs/drawer-vs-dialog-pattern.md`** · **`.cursor/skills/exxat-drawer-vs-dialog/SKILL.md`**
-- **`exxat-page-vs-drawer.mdc`** (sheet vs **route**)
+- **`exxat-page-vs-drawer.mdc`** (drawer vs **route**)

package/consumer-extras/cursor-rules/exxat-ds-agents.mdc

@@ -1,6 +1,7 @@
 ---
 description: Exxat DS — follow AGENTS.md; DataTable, ListPageTemplate, primary hubs, export, Kbd
 alwaysApply: true
+appliesTo: [universal]
 ---
 
 # Exxat DS — AI handbook (binding)

package/consumer-extras/cursor-rules/exxat-fontawesome-icons.mdc

@@ -2,6 +2,7 @@
 description: Font Awesome Pro icons — kit, weights, markup, subset audit, accessibility pairing
 globs: apps/web/**/*.tsx
 alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — Font Awesome icons

package/consumer-extras/cursor-rules/exxat-hub-supported-views.mdc

@@ -1,6 +1,8 @@
 ---
-description: List-page hubs — FULL_HUB_SUPPORTED_VIEWS, Add view parity, and real renderers (never trimmed allowlists or placeholder list rows)
-alwaysApply: true
+description: List-page hubs — FULL_HUB_SUPPORTED_VIEWS, Add view parity, and real renderers (never trimmed allowlists or placeholder list rows). Auto-attaches when editing hub clients / list-page templates.
+globs: apps/web/components/**/*.{tsx,ts}
+alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — hub supported views (Add view parity)
@@ -50,5 +52,5 @@ Every **`ListPageTemplate`** + **`HubTable`** hub that mounts a product data gri
 ## See also
 
 - **`.cursor/rules/exxat-data-tables.mdc`**, **`exxat-list-page-connected-views.mdc`**, **`exxat-list-page-view-shells.mdc`**
-- **`docs/exxat-ds/patterns/hub-supported-views-pattern.md`** (vendored from monorepo `apps/web/docs/`)
-- **`docs/exxat-ds/patterns/data-views-pattern.md`**
+- **`apps/web/docs/hub-supported-views-pattern.md`**
+- **`apps/web/docs/data-views-pattern.md`**

package/consumer-extras/cursor-rules/exxat-kbd-shortcuts.mdc

@@ -1,6 +1,7 @@
 ---
 description: Exxat DS — show Kbd hints on primary/secondary actions, search, Ask Leo; avoid browser-reserved chords.
 alwaysApply: true
+appliesTo: [universal]
 ---
 
 # Exxat DS — keyboard shortcuts (`Kbd`)
@@ -24,7 +25,7 @@ Use `@/components/ui/kbd` (`Kbd` + `KbdGroup`) anywhere users discover actions b
    | Inside a `DropdownMenuItem` via `shortcut=` | menu handles it — pass the chord string |
    | Standalone helper text on a surface | **default `tile`** |
 
-   Glue multi-key chords into **one** bare kbd (`<Kbd variant="bare">⌘⌥K</Kbd>`), not one tile per key. See `new-placement-form.tsx` (Next = `{mod}⏎`, Back = `{mod}{alt}←`) and the primary "Ask Leo" button inside chart insight popovers.
+   Glue multi-key chords into **one** bare kbd (`<Kbd variant="bare">⌘⌥K</Kbd>`), not one tile per key. See `new-library-item-form.tsx` (Next = `{mod}⏎`, Back = `{mod}{alt}←`) and the primary "Ask Leo" button inside chart insight popovers.
 
 1. **Pair hint with behavior** — If `Kbd` shows a chord, implement the same shortcut. **Preferred:** the shared primitives from `@/components/ui/dropdown-menu`:
 
@@ -58,8 +59,8 @@ Use `@/components/ui/kbd` (`Kbd` + `KbdGroup`) anywhere users discover actions b
 | Toggle main sidebar | ⌘/Ctrl + **B** (`components/ui/sidebar.tsx`) |
 | Table search | ⌘/Ctrl + **K** (no Alt — `DataTable`) |
 | Ask Leo | ⌘/Ctrl + **⌥/Alt** + **K** |
-| New placement (Placements header) | ⌘/Ctrl + **⌥/Alt** + **N** |
-| Placements overflow menu | ⌘/Ctrl + **⌥/Alt** + **M** |
+| New record (primary hub header) | ⌘/Ctrl + **⌥/Alt** + **N** |
+| Hub overflow menu (⋯) | ⌘/Ctrl + **⌥/Alt** + **M** |
 | Export | ⌘/Ctrl + **⇧/Shift** + **E** |
 | Hide/Show metric section | ⌘/Ctrl + **⌥/Alt** + **H** |
 | Rename (view, tab) | **F2** |
@@ -79,14 +80,14 @@ Every **workflow surface** (form, dialog, drawer, sheet, multi-step wizard final
 1. **Primary action (submit/commit)** — **Enter** (⏎). Render the `<Kbd>⏎</Kbd>` **inline inside the button** (after the label, inside a `<KbdGroup className="ml-1.5">`) — NOT inside a hover `Tip`. Primary/secondary workflow buttons must expose the shortcut at rest so it is discoverable without hovering. Pair with a `<Shortcut keys="Enter" onInvoke={...}>` mounted while the surface is open. The shared `useShortcut` hook skips events from inputs/textarea/contenteditable, so Enter inside a text field still types normally — it only fires when focus is on the surface chrome.
 2. **Secondary action (Cancel/Dismiss)** — **Esc**. Inline `<Kbd>Esc</Kbd>` inside the Cancel button (same `ml-1.5` pattern). Radix `Dialog` / `Sheet` / `AlertDialog` already bind Esc natively.
 
-> Tip-on-hover Kbd hints remain correct for **page-level** actions (e.g. "New placement", ⋯ overflow triggers) where the button is part of dense page chrome and a persistent Kbd would crowd the layout. Workflow buttons inside a form/drawer/dialog are spacious enough to render the Kbd inline.
+> Tip-on-hover Kbd hints remain correct for **page-level** actions (e.g. primary "New …" CTA, ⋯ overflow triggers) where the button is part of dense page chrome and a persistent Kbd would crowd the layout. Workflow buttons inside a form/drawer/dialog are spacious enough to render the Kbd inline.
 
 **Variant inside a button:** always use `<Kbd variant="bare">` — no background, no border, inherits `currentColor` at 70% opacity. The default tile variant looks like a pasted-on patch on filled primary buttons. Glue multi-key chords into one `<Kbd variant="bare">⌘⌥←</Kbd>` rather than one tile per key.
 3. **Multi-step wizards** — plain **Enter** must NOT submit on intermediate steps (it would auto-close the review/final step when users hit Enter inside an input). Either:
    - Gate `form.onSubmit` on `step === lastStep` (`if (step !== N) { e.preventDefault(); return }`), **or**
    - Remove `type="submit"` on intermediate Next buttons and bind **⌘Enter** to "Next" via `<Shortcut>`.
    On the final step, plain **Enter** submits and the Kbd hint shows **⏎**.
-4. Examples in-app: `new-placement-form.tsx` (Create placement = Enter on step 5, Back = ⌘⌥←), `export-drawer.tsx` (Export = Enter, Cancel = Esc).
+4. Examples in-app: `new-library-item-form.tsx` (Create = Enter on the final step, Back = ⌘⌥←), `export-drawer.tsx` (Export = Enter, Cancel = Esc).
 
 ## Every action menu MUST carry shortcuts
 

package/consumer-extras/cursor-rules/exxat-kpi-flat-band.mdc

@@ -2,6 +2,7 @@
 description: KeyMetrics variant flat — transparent band, brand glow only, OKLCH hairlines
 globs: apps/web/components/**/*key-metrics*,apps/web/app/globals.css,apps/web/docs/kpi*.md
 alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — KPI flat band (`variant="flat"`)

package/consumer-extras/cursor-rules/exxat-kpi-max-four.mdc

@@ -1,6 +1,7 @@
 ---
 description: Exxat DS — at most four KPI tiles on primary hub strips and key-metrics dashboard cards.
 alwaysApply: true
+appliesTo: [universal]
 ---
 
 # Exxat DS — KPI strip (max four)

package/consumer-extras/cursor-rules/exxat-kpi-trends.mdc

@@ -1,6 +1,7 @@
 ---
 description: Exxat DS — KPI deltas and trend arrows must be contextual; use trendPolarity when “up” is not good news.
 alwaysApply: true
+appliesTo: [universal]
 ---
 
 # Exxat DS — KPI trends (`KeyMetrics` + chart mini-metrics)

package/consumer-extras/cursor-rules/exxat-library-hub-header.mdc

@@ -1,7 +1,8 @@
 ---
 description: Library library — folder-scoped hub header More menu must expose Customize folder; sheet on hub client
-globs: apps/web/components/library-*.tsx, packages/ui/template/components/library-*.tsx
+globs: apps/web/components/library-*.tsx, packages/ui/template-vite/components/library-*.tsx
 alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — Library hub header (folder scope)

package/consumer-extras/cursor-rules/exxat-list-page-connected-views.mdc

@@ -1,6 +1,8 @@
 ---
-description: ListPageTemplate — shared table state across views, mock + KPI helpers, dashboard tab
-alwaysApply: true
+description: ListPageTemplate — shared table state across views, mock + KPI helpers, dashboard tab. Auto-attaches when editing list-page React clients.
+globs: apps/web/{components,lib,app}/**/*.{tsx,ts}
+alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — list page connected views
@@ -16,9 +18,11 @@ alwaysApply: true
 5. **List hub metrics strip** — Prefer **`KeyMetrics variant="flat"`** on **`ListPageTemplate`** **`metrics`** slot (transparent band, brand glow only) — **`docs/kpi-flat-band-pattern.md`**, **`.cursor/rules/exxat-kpi-flat-band.mdc`**.
 6. **MUST NOT** ship “not wired” / “switch to table” placeholders for list/board/dashboard when the stack supports those views.
 7. **MUST NOT** add a **primary nav** destination that is only placeholder copy with no **`ListPageTemplate`** hub, mock rows, and wired views — see **`apps/web/AGENTS.md` §4.1** (no empty hubs).
+8. **Add view parity** — Use **`FULL_HUB_SUPPORTED_VIEWS`** (default) and implement **all seven** views with real bodies — **`.cursor/rules/exxat-hub-supported-views.mdc`**. List rows **MUST** use **`ListPageBoardCard`** (`library-table.tsx`), not bare title + id lines.
 
 ## See also
 
 - **`.cursor/rules/exxat-centralized-list-dataset.mdc`** — single **`tableState.rows`** source for every hub view, inspectors, and **`TablePropertiesDrawer`** on the same **`DataTable`**.
 - **Centered view bodies + reusable shells:** **`apps/web/AGENTS.md` §4.5**, **`.cursor/rules/exxat-list-page-view-shells.mdc`**, **`ListPageViewFrame`** in **`components/data-views/list-page-view-frame.tsx`**.
 - **Flat KPI band:** **`docs/kpi-flat-band-pattern.md`**, **`.cursor/rules/exxat-kpi-flat-band.mdc`**.
+- **Hub supported views:** **`docs/hub-supported-views-pattern.md`**, **`.cursor/rules/exxat-hub-supported-views.mdc`**.

package/consumer-extras/cursor-rules/exxat-list-page-view-shells.mdc

@@ -2,6 +2,7 @@
 description: Exxat DS — centered reusable shells for list-page views (not page-specific markup)
 globs: apps/web/components/**/*.tsx
 alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — list-page view shells (centered, reusable)
@@ -21,7 +22,7 @@ Domain logic (columns, tiles, folder trees) stays in **`*-table.tsx` / `*-client
 ## MUST NOT
 
 - Wrap **`DataTable`** (or its outer toolbar shell) in **`ListPageViewFrame`** if that **duplicates** horizontal inset already applied by **`DataTable`** / **`DataTableToolbar`** — see **`AGENTS.md` §5** (double indent).
-- Ship **view-only** layout classes only inside **`app/(app)/.../page.tsx`** for a hub that other entities will mirror — belong in **`data-views/`** or **`templates/`**.
+- Ship **view-only** layout classes only inside **`src/views/<route>.tsx`** (or any route entry) for a hub that other entities will mirror — belong in **`data-views/`** or **`templates/`**.
 
 ## See also