@exxatdesignux/ui 0.5.11 → 0.5.13

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
 

package/consumer-extras/cursor-rules/exxat-mono-ids.mdc

@@ -2,6 +2,7 @@
 description: Exxat DS — monospace typography for record IDs, question IDs, and other system identifiers
 globs: apps/web/**/*.tsx
 alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — monospace IDs
@@ -16,7 +17,7 @@ Use this when rendering **system identifiers** — values a user copies, searche
 
 ## SHOULD
 
-- Match existing hubs: **`library-table.tsx`**, **`library-list-view.tsx`**, **`new-library-item-form.tsx`** (header subtitle), **`sites-table.tsx`** (`row.id`).
+- Match existing hubs: **`library-table.tsx`**, **`columns-showcase.tsx`** (mono record IDs in the showcase row), **`new-library-item-form.tsx`** (header subtitle).
 - Prefer **`truncate`** / **`min-w-0`** on mono IDs in tight layouts so long tokens do not blow out columns.
 
 ## MUST NOT

package/consumer-extras/cursor-rules/exxat-nav-single-active.mdc

@@ -2,6 +2,7 @@
 description: Sidebar and secondary nav — exactly one active item per route (longest path match)
 globs: "**/app-sidebar.tsx,**/secondary-nav.tsx,**/navigation.tsx,**/lib/nav-active.ts"
 alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — single active nav item (MUST)
@@ -17,7 +18,7 @@ Only **one** primary sidebar row, collapsible child, or secondary-panel link may
 2. **Never** mark a nav item active with bare `pathname === href` or `pathname.startsWith(href + "/")` when other nav targets share that prefix (e.g. `/dashboard` vs `/dashboard/students`).
 3. **Hash disambiguation** — when multiple items share the same path (e.g. `/settings` vs `/settings#appearance`), use `buildNavHashClaims` so the no-fragment row defers to the hash-specific row.
 4. **Collapsible parents** — when any child is active, the **parent** row stays visually neutral in the expanded sidebar; only the child gets `data-active` (icon rail may still highlight the parent — see `isCollapsibleParentMenuButtonActive` in `app-sidebar.tsx`).
-5. **Keep `ListPageTemplate.supportedViewTypes` and `HubTable.supportedViewTypes` in sync** on the same hub — do not pass `supportedViewTypes={["table"]}` on a primary hub unless that hub truly implements only table.
+5. **Keep `ListPageTemplate.supportedViewTypes` and `HubTable.supportedViewTypes` in sync** on the same hub — default **`FULL_HUB_SUPPORTED_VIEWS`** (seven views). See **`exxat-hub-supported-views.mdc`** for renderer requirements.
 
 ## MUST NOT
 
@@ -27,5 +28,5 @@ Only **one** primary sidebar row, collapsible child, or secondary-panel link may
 ## Reference
 
 - `packages/ui/src/lib/nav-active.ts`
-- `packages/ui/template/components/sidebar/app-sidebar.tsx`
-- `packages/ui/template/components/sidebar/secondary-nav.tsx`
+- `packages/ui/template-vite/components/sidebar/app-sidebar.tsx`
+- `packages/ui/template-vite/components/sidebar/secondary-nav.tsx`

package/consumer-extras/cursor-rules/exxat-no-image-pixel-copy.mdc

@@ -1,6 +1,7 @@
 ---
 description: Uploaded screenshots/mockups are IA reference only — map to Exxat DS patterns; never pixel-copy
 alwaysApply: true
+appliesTo: [universal]
 ---
 
 # Exxat DS — uploaded images are not the implementation spec
@@ -11,25 +12,35 @@ When the user attaches a **screenshot**, **mockup**, **Figma export**, **legacy
 
 ## Allowed to take from an image (content / IA)
 
-- **Screen purpose**, **nav labels**, **routes**, **fields**, **columns**, **KPIs**, **actions**, **statuses**
-- **Icon suffix** (Font Awesome) — still use **`fa-light` / `fa-solid`** DS pairing
-- **Workflow intent** — export, invite, row → detail, etc.
+- **Screen purpose** — list hub, detail record, settings, search, etc.
+- **Nav labels**, **section grouping**, **route slugs**, **field names**, **column headers**
+- **Data the user cares about** — which KPIs, filters, actions, statuses exist
+- **Icon choice** (Font Awesome suffix) when obvious — still use **`fa-light` / `fa-solid`** DS pairing
+- **Workflow** — e.g. “export from ⋯”, “row opens profile”, “invite from header”
 
 ## MUST NOT copy from an image (visual / stack)
 
-- **Hex / RGB colors**, rainbow section text, custom sidebar washes, bespoke pills
-- **Shell forks** — sidebar, header, list toolbar, tabs that bypass DS components
-- **Bespoke widgets** when DS primitives exist — raw tables, custom popovers, Vaul, full-width tabs
-- **Pixel implementation “because it’s in the picture”** without citing a **DS pattern + reference hub**
+- **Hex / RGB colors**, per-section rainbow text, custom sidebar washes, one-off pill shapes
+- **Layout chrome** that duplicates DS shell — sidebar, **`SiteHeader`**, **`PageHeader`**, **`ListPageTemplate`** toolbar, tab bars
+- **Bespoke components** when a DS primitive exists — raw `<table>`, custom popovers, hand-built buttons, full-width tabs, Vaul drawers
+- **Forking shared files** (`app-sidebar.tsx`, `sidebar.tsx`, `globals.css`) to match a legacy product
+- **Implementing “because it’s in the picture”** without naming the **DS pattern + reference file** you are using
 
-## REQUIRED workflow (before UI code)
+## REQUIRED workflow (before writing UI code)
 
-1. Classify via **`component-selection-guide`** + **`blueprints/`**
-2. Pick **`reference-implementations`** hub
-3. State mapping (screen → DS composition)
-4. Build with **`AGENTS.md`** + topic rules
-5. Image vs DS conflict → **DS wins**; ask one question only for true business gaps
+1. **Classify the screen** — use **`docs/component-selection-guide.md`** + **`docs/blueprints/`** (list page, page header, data table, dedicated search, …).
+2. **Pick a reference hub** — **`docs/reference-implementations.md`** (Placements, Team, Library, Compliance, …).
+3. **State the mapping** (briefly in your reply): e.g. “Students roster → **`ListPageTemplate`** + **`HubTable`** like Team; nav rows → **`lib/mock/navigation.tsx`** only; sidebar chrome unchanged.”
+4. **Implement with DS components + tokens** — **`AGENTS.md`**, **`exxat-ds-agents.mdc`**, topic rules (`exxat-tabs-chrome`, `exxat-page-header-actions`, `exxat-sidebar-shell`, …).
+5. **If the image conflicts with DS** — follow DS; ask **one** clarifying question only when the **business requirement** (not pixels) cannot be met with existing patterns.
+
+## Consumer apps
+
+- Product UI lives in the **customer repo** with **`@exxatdesignux/ui`** — not by restyling the DS monorepo to match uploads.
+- After upgrade, run **`exxat-ui sync-extras`** so this rule and siblings stay on disk.
 
 ## See also
 
-- **`exxat-reuse-before-custom.mdc`**, **`exxat-sidebar-shell.mdc`**, **`exxat-token-economy`** §2
+- **`exxat-reuse-before-custom.mdc`** — compose before inventing
+- **`exxat-sidebar-shell.mdc`** — sidebar-specific anti-patterns
+- **`exxat-token-economy`** skill §2 — pre-flight includes image discipline

package/consumer-extras/cursor-rules/exxat-no-slds-leakage.mdc

@@ -1,3 +1,9 @@
+---
+description: No Salesforce SLDS leakage — never copy slds-* classes, lightning-* elements, SLDS token names, or synthetic-shadow assumptions into Exxat DS code.
+alwaysApply: true
+appliesTo: [universal]
+---
+
 # Exxat DS — no SLDS leakage
 
 **Context:** Some agents have access to other repos, including the **Salesforce
@@ -23,7 +29,7 @@ codebase into **`apps/web`** or **`packages/ui`**.
    Exxat compositions in `apps/web/components/`.
 3. **Synthetic-shadow assumptions** — Do **not** call `template.querySelector`,
    `slds-color-scheme_dark`, `shadowRoot === null` checks, or anything that
-   only makes sense under Salesforce synthetic shadow. The Next.js app uses
+   only makes sense under Salesforce synthetic shadow. The Vite + React app uses
    the real DOM + Radix portals.
 4. **SLDS styling-hook vars** — Do **not** use SLDS custom properties
    (`--slds-g-color-surface-*`, `--slds-g-color-on-surface-*`,
@@ -67,7 +73,7 @@ silently breaks:
 - **Accessibility** — SLDS 1 contrast ratios differ from Exxat's WCAG 2.1 AA
   targets; mixing them produces unverifiable composites.
 - **Bundling** — Importing `@salesforce-ux/design-system` would balloon the
-  Next.js bundle and pull in classic SLDS that we explicitly chose not to use.
+  Vite bundle and pull in classic SLDS that we explicitly chose not to use.
 
 ## See also
 

package/consumer-extras/cursor-rules/exxat-no-toast.mdc

@@ -1,6 +1,7 @@
 ---
 description: Exxat DS — do not use toast / sonner / transient snackbars for product messaging.
 alwaysApply: true
+appliesTo: [universal]
 ---
 
 # Exxat DS — no toast

package/consumer-extras/cursor-rules/exxat-no-vaul.mdc

@@ -1,6 +1,7 @@
 ---
 description: Exxat DS — no Vaul Drawer primitive; side panels use Sheet only
 alwaysApply: true
+appliesTo: [universal]
 ---
 
 # Exxat DS — no Vaul
@@ -22,4 +23,4 @@ After upgrading to **`@exxatdesignux/ui@0.5.3`**, remove **`vaul`** from the app
 ## See also
 
 - **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**
-- **`docs/exxat-ds/patterns/drawer-vs-dialog-pattern.md`**
+- **`apps/web/docs/drawer-vs-dialog-pattern.md`**

package/consumer-extras/cursor-rules/exxat-page-header-actions.mdc

@@ -1,11 +1,13 @@
 ---
-description: Exxat DS — PageHeader actions slot; View as / overflow / primary CTA patterns
-alwaysApply: true
+description: Exxat DS — PageHeader actions slot; View as / overflow / primary CTA patterns. Auto-attaches when editing React PageHeader callsites; the universal "one filled primary" rule lives in P3 of exxat-ux-principles.
+globs: apps/web/{components,app}/**/*.{tsx,ts}
+alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — page header actions
 
-**Blueprint:** `docs/exxat-ds/handbook/HANDBOOK.md` + `node_modules/@exxatdesignux/ui/template/docs/blueprints/page-header.md`
+**Blueprint:** `apps/web/docs/blueprints/page-header.md`
 
 ## Anatomy (actions slot only)
 
@@ -28,4 +30,4 @@ alwaysApply: true
 
 ## Reference
 
-- **`docs/exxat-ds/handbook/reference-implementations.md`**
+- `components/library-page-header.tsx`, Placements/Team header patterns in **`apps/web/docs/reference-implementations.md`**

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

@@ -1,6 +1,7 @@
 ---
 description: Exxat DS — when to use a drawer vs a new page for actions and auxiliary UI.
 alwaysApply: true
+appliesTo: [universal]
 ---
 
 # Exxat DS — page vs drawer
@@ -14,7 +15,7 @@ alwaysApply: true
 ## Product examples (this repo)
 
 - **Drawer-appropriate:** `TablePropertiesDrawer`, `ExportDrawer`, lightweight panels that supplement a hub.
-- **Page-appropriate:** Full placement or settings flows that are the main task, multi-screen wizards.
+- **Page-appropriate:** Full settings flows, multi-step record-creation wizards (e.g. `new-library-item-form.tsx`), or any task that is itself the user's primary intent.
 
 ## Authoritative detail
 

package/consumer-extras/cursor-rules/exxat-person-identity-display.mdc

@@ -1,6 +1,7 @@
 ---
 description: Exxat DS — avatar + name + email when showing a person; omit email in dense contexts (e.g. board cards).
 alwaysApply: false
+appliesTo: [universal]
 ---
 
 # Exxat DS — person identity (name + email)

package/consumer-extras/cursor-rules/exxat-primary-nav-secondary-panel.mdc

@@ -2,6 +2,7 @@
 description: Primary sidebar item opens nested SecondaryPanel (Library pattern)
 globs: apps/web/components/**/*.tsx
 alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — primary nav → secondary panel
@@ -15,7 +16,7 @@ Some hubs expose **scoped navigation** (All / My / tree / filters) in a **nested
 1. **`NavLinkItem`** — On the **primary** row that should drive the panel, set **`secondaryPanel`** to a **stable string id** (e.g. **`"library"`**). Keep **`url`** pointing at the **hub route**.
 2. **`SecondaryPanel` registry** — In **`components/secondary-panel.tsx`**, add **`PANELS[id]`** → component that renders **panel chrome** (title, optional search) + **your secondary nav** list. **MUST** keep ids in sync with **`NAV_PRIMARY`**.
 3. **Auto-open on route** — The hub **`client`** (or layout slot) **MUST** mount **`*PanelActivator`** that calls **`useAutoPanel(id)`** with the **same id**, so deep links and first visit open the panel while the route is mounted (e.g. **`LibraryPanelActivator`** + **`beforeSiteHeader`** on **`LibraryClient`**).
-4. **Same-route reopen** — **`AppSidebar`** already calls **`openPanel(secondaryPanel)`** when the user clicks the primary item **again** while already on that **`url`** (prevents no-op navigation). Secondary nav rows that stay on the same path **SHOULD** call **`openPanel`** on click where **Next.js `Link`** would not fire (same **`href`**).
+4. **Same-route reopen** — **`AppSidebar`** already calls **`openPanel(secondaryPanel)`** when the user clicks the primary item **again** while already on that **`url`** (prevents no-op navigation). Secondary nav rows that stay on the same path **SHOULD** call **`openPanel`** on click where **`react-router-dom` `Link`** would not fire (same **`to`**).
 
 ## Surface elevation (brand chrome)
 

package/consumer-extras/cursor-rules/exxat-reuse-before-custom.mdc

@@ -1,6 +1,7 @@
 ---
 description: Exxat DS — prefer centralized reusable components; ask the user before new bespoke primitives.
 alwaysApply: true
+appliesTo: [universal]
 ---
 
 # Exxat DS — reuse before custom

package/consumer-extras/cursor-rules/exxat-sidebar-shell.mdc

@@ -2,6 +2,7 @@
 description: Application sidebar — DS shell only; legacy screenshots are IA reference, not visual spec
 globs: "**/app-sidebar.tsx,**/navigation*.tsx,**/lib/mock/navigation.tsx,**/lib/*-navigation.tsx"
 alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — application sidebar shell (MUST)
@@ -23,13 +24,18 @@ Customer / legacy app **screenshots** may show **what links exist** — not **ho
 
 ## MUST — DS sidebar chrome
 
-1. **Shell:** **`AppSidebar`** + **`SidebarMenuButton`** / **`SidebarGroup`** / **`SidebarGroupLabel`** from **`@exxatdesignux/ui`**. Reference: **`AGENTS.md` §9.1**, **`exxat-ds-skill` §3.1–§3.2**.
-2. **Typography:** Row labels **`text-sidebar-foreground`**. Section headings **`SidebarGroupLabel`** + **`text-sidebar-section-label`**.
-3. **Active state:** **`SidebarMenuButton` `isActive`** only — one active row in expanded rail; collapsible parent neutral when child active.
-4. **Icons:** **`fa-light`** / **`fa-solid`** on icons — do **not** recolor labels per module.
-5. **Nav data:** Extend **`lib/mock/navigation.tsx`** (or imported mock). **MUST NOT** paste legacy sidebar components from customer repos.
-6. **Consumer products:** Build in a **separate repo** with **`@exxatdesignux/ui`** — not DS monorepo sidebar forks.
+1. **Shell:** **`AppSidebar`** + **`SidebarMenuButton`** / **`SidebarGroup`** / **`SidebarGroupLabel`** from **`@exxatdesignux/ui`** (or app shims). Reference: **`apps/web/components/sidebar/app-sidebar.tsx`**, **`AGENTS.md` §9.1**, **`exxat-ds-skill` §3.1–§3.2**.
+2. **Typography:** Row labels **`text-sidebar-foreground`** (default from `SidebarMenuButton`). Section headings **`SidebarGroupLabel`** + **`text-sidebar-section-label`** — not rainbow section body text.
+3. **Active state:** Pass **`isActive`** into **`SidebarMenuButton`** only. Expanded rail: **one** active row (`data-active` → background pill + ring from DS). Collapsible parent stays **neutral** when a child is active. Icon rail: parent icon may light up when any child is active.
+4. **Icons:** **`fa-light`** idle / **`fa-solid`** active on the **icon** only — do **not** recolor the label per module.
+5. **Nav data:** Add or extend **`lib/mock/navigation.tsx`** (or a file it imports). **MUST NOT** paste a full legacy sidebar component from a customer repo into **`apps/web`**.
+6. **Consumer products:** Prism / customer hubs belong in a **separate consumer repo** with **`@exxatdesignux/ui`** — not product-specific rewrites of the DS monorepo sidebar.
+
+## Reference (canonical visual)
+
+- **`apps/web/components/sidebar/app-sidebar.tsx`** + **`lib/mock/navigation.tsx`**
+- **`packages/ui/src/components/ui/sidebar.tsx`** — `data-active:bg-background` pill
 
 ## Anti-pattern
 
-Legacy product sidebars with rainbow section text and bespoke selection chrome — **do not reproduce** on Exxat DS.
+Legacy Exxat Prism sidebar: color-coded **text** per module block, pink sidebar wash, bespoke selection chrome — **do not reproduce** when building on Exxat DS.

package/consumer-extras/cursor-rules/exxat-table-properties-drawer.mdc

@@ -1,6 +1,8 @@
 ---
-description: TablePropertiesDrawer must receive currentView and onViewChange when used with ListPageTemplate view tabs
-alwaysApply: true
+description: TablePropertiesDrawer must receive currentView and onViewChange when used with ListPageTemplate view tabs. Auto-attaches when editing apps/web React files; ask explicitly when wiring view-type-aware drawers.
+globs: apps/web/{components,packages/ui}/**/*.{tsx,ts}
+alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — Table properties + active view
@@ -28,7 +30,7 @@ When **`ListPageTemplate`** drives **`tab.viewType`** and the page renders **`Ta
 
 3. Thread **`view`** and **`onViewChange`** through: **client → table component → drawer toolbar → `TablePropertiesDrawer`**.
 
-**Reference implementations:** `components/placements-table.tsx` (`PlacementsTable`), `components/team-client.tsx` + `team-table.tsx`, `components/compliance-client.tsx` + `compliance-table.tsx`.
+**Reference implementations:** `components/library-hub-client.tsx` + `library-table.tsx` (canonical seven-view hub), `components/columns-showcase.tsx` (`LibraryTable` + custom `columnDefs`), `components/tokens-themes-client.tsx` (`FULL_HUB_SUPPORTED_VIEWS` + `tokens-hub-auxiliary-views.tsx`). **Add view allowlist:** **`.cursor/rules/exxat-hub-supported-views.mdc`**.
 
 ## Deep-linking into a specific panel
 

package/consumer-extras/cursor-rules/exxat-table-row-preview.mdc

@@ -1,6 +1,7 @@
 ---
 description: Exxat DS — table row identity preview uses HoverCard + DS tokens, not bespoke Popover cards
 alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — table row preview (hover / click)

package/consumer-extras/cursor-rules/exxat-tabs-chrome.mdc

@@ -1,6 +1,8 @@
 ---
-description: Exxat DS — Tabs and view toolbars must not stretch full width; use ListPageTemplate for hub views
-alwaysApply: true
+description: Exxat DS — Tabs and view toolbars must not stretch full width; use ListPageTemplate for hub views. Auto-attaches when editing React surfaces with tabs or view toolbars.
+globs: apps/web/{components,app}/**/*.{tsx,ts}
+alwaysApply: false
+appliesTo: [react]
 ---
 
 # Exxat DS — tabs chrome (no full-width stretch)
@@ -27,5 +29,5 @@ alwaysApply: true
 
 ## See also
 
-- **`docs/exxat-ds/handbook/HANDBOOK.md`** — header never carries view tabs
-- **`docs/exxat-ds/patterns/data-views-pattern.md`** — `ListPageTemplate` view toolbar
+- **`apps/web/docs/blueprints/page-header.md`** — header never carries view tabs
+- **`apps/web/docs/data-views-pattern.md`** — `ListPageTemplate` view toolbar

package/consumer-extras/cursor-rules/exxat-token-discipline.mdc

@@ -1,3 +1,9 @@
+---
+description: Token discipline — no hex literals, prefer Exxat L0 tokens (--exxat-color-*, --exxat-radius-*, --exxat-spacing-*), no deprecated tokens. ESLint enforces via @exxatdesignux/eslint-plugin.
+alwaysApply: true
+appliesTo: [universal]
+---
+
 # Exxat DS — token discipline
 
 **Authoritative reference:** [`apps/web/docs/token-taxonomy.md`](mdc:apps/web/docs/token-taxonomy.md).

package/consumer-extras/cursor-rules/exxat-ux-discovery-protocol.mdc

@@ -1,6 +1,7 @@
 ---
 description: Exxat DS — STOP before code on any surface design (new, rebuild, redesign, replace); output a design brief and WAIT for user go-ahead
 alwaysApply: true
+appliesTo: [universal]
 ---
 
 # Exxat DS — UX discovery protocol
@@ -165,6 +166,32 @@ Open questions:     <max 2; ideally 0>
 > User: "make a settings page". *Agent writes generic form.* Should have
 > asked: scope (personal/workspace), search needed, apply-on-change vs Save.
 
+## Closing artifact: the design → engineering handoff
+
+When the build is complete (files written, surface working in dev), produce
+**one filled-in handoff document** before declaring the task done.
+
+**Template** lives at:
+
+- Workspace: `apps/web/docs/templates/handoff.md` (or workspace root if not yet copied — copy from `packages/ui/consumer-extras/templates/handoff.md`)
+- Consumer apps (after `exxat-ui sync-extras`): `docs/exxat-ds/templates/handoff.md`
+
+**Fill it in** with the actual primitives, tokens, icons, and shortcuts the
+build used. Save the filled copy at:
+
+- `apps/web/docs/handoff/<surface-slug>.md` (workspace)
+- `docs/exxat-ds/handoff/<surface-slug>.md` (consumer)
+
+Attach the filled handoff to the PR description (or paste inline). The
+engineer reads it once, runs `exxat-ui audit <generated-file>` to verify
+the floor, and is done.
+
+**MUST sections:** 1 (job-to-be-done), 3 (pattern + IA), 5 (DS components
+used), 6 (tokens), 8 (a11y checklist — every box ticked), 11 (keyboard map),
+12 (any deviations from P9–P20).
+
+If the handoff is incomplete or hand-wavy, the design task is not finished.
+
 ## See also
 
 - `.cursor/skills/exxat-senior-ux/SKILL.md` — the persona + full protocol
@@ -172,3 +199,4 @@ Open questions:     <max 2; ideally 0>
 - `apps/web/docs/jobs/` — canonical references per job type
 - `apps/web/docs/modern-saas-patterns.md` — pattern codes (M1–M12)
 - `.cursor/rules/exxat-no-image-pixel-copy.mdc` — IA from screenshots only
+- **Closing artifact:** `packages/ui/consumer-extras/templates/handoff.md`

package/consumer-extras/cursor-rules/exxat-ux-principles.mdc

@@ -1,6 +1,7 @@
 ---
 description: Exxat DS UX principles — what to follow, when to break, why
 alwaysApply: true
+appliesTo: [universal]
 ---
 
 # Exxat DS — UX principles (and when to break them)

package/consumer-extras/cursor-skills/exxat-ds-skill/SKILL.md

@@ -23,7 +23,7 @@ description: >
 - **Single source of truth:** `apps/web/AGENTS.md` for full prose explanations; this skill is the actionable summary
 - **Companion skills (narrow topics):** `exxat-fontawesome-icons`, `exxat-mono-ids`, `exxat-primary-nav-secondary-panel`, `exxat-centralized-list-dataset`, `exxat-list-page-view-shells`, `exxat-dedicated-search-surfaces`, `exxat-accessibility`, `exxat-board-cards`, `exxat-collaboration-access` — live under `.cursor/skills/`; vetted copies ship with **`@exxatdesignux/ui`** in `consumer-extras/cursor-skills/` after **`pnpm --filter @exxatdesignux/ui vendor:consumer-extras`**.
 - **Library folder-scoped header (rule + doc):** **`.cursor/rules/exxat-library-hub-header.mdc`** and **`docs/library-hub-header-pattern.md`** — pair with **`exxat-primary-nav-secondary-panel`** when URL **`scope=folder`** drives the hub title.
-- **Consumer repos (npm install of `@exxatdesignux/ui`):** After a version bump, read **`node_modules/@exxatdesignux/ui/CHANGELOG.md`**, run **`npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras`** so **`docs/exxat-ds/consumer-upgrade-checklist.md`** and Cursor skills match the tarball, and diff the host app against **`node_modules/@exxatdesignux/ui/template/`** for anything new to port (routes, re-exports, AGENTS). Use **`exxat-ui changelog`**, **`exxat-ui update`**, and **`exxat-ui doctor`** for CLI guidance.
+- **Consumer repos (npm install of `@exxatdesignux/ui`):** After a version bump, read **`node_modules/@exxatdesignux/ui/CHANGELOG.md`**, run **`npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras`** so **`docs/exxat-ds/consumer-upgrade-checklist.md`** and Cursor skills match the tarball, and diff the host app against **`node_modules/@exxatdesignux/ui/template-vite/`** for anything new to port (routes, re-exports, AGENTS). Use **`exxat-ui changelog`**, **`exxat-ui update`**, and **`exxat-ui doctor`** for CLI guidance.
 
 ---
 

package/consumer-extras/cursor-skills/exxat-kpi-trends/SKILL.md

@@ -12,9 +12,11 @@ Use when adding or reviewing **`KeyMetrics`**, **`lib/mock/*-kpi.ts`** helpers,
 
 1. **Delta honest?** `trend` follows the sign of the change vs the comparison period.
 2. **Polarity correct?** If “more” is bad → **`trendPolarity: "lower_is_better"`**. If no value judgment → **`"informational"`** (muted tints).
-3. **Copy contextual?** Label + value + delta tell users *what* moved, not only *how much*.
-4. **Screen readers** — Chip keeps icon + visible delta; `aria-label` reflects favorable / unfavorable wording automatically when polarity is set.
-5. **Chart cards** — When using **`ChartCard`** `miniMetrics`, pass **`trendPolarity`** the same way as on **`MetricItem`**.
+3. **Delta is a count, not prose.** **`delta`** is `"+5"`, `"-3"`, `"+12%"`. Captions like `"left + right"`, `"vs last week"`, `"scheduled for removal"` go in **`description`** (renders **below** the value, muted).
+4. **No empty `—` chip.** If there’s no direction *and* no count, leave **`delta: ""`** + **`trend: "neutral"`** — **`KeyMetrics`** hides the chip. Don’t hand-roll a placeholder.
+5. **Copy contextual?** Label + value + (delta when present) + description tell users *what* moved, not only *how much*.
+6. **Screen readers** — Chip keeps icon + visible delta; `aria-label` reflects favorable / unfavorable wording automatically when polarity is set.
+7. **Chart cards** — When using **`ChartCard`** `miniMetrics`, pass **`trendPolarity`** the same way as on **`MetricItem`**.
 
 ## Quick examples
 

package/consumer-extras/patterns/command-menu-pattern.md

@@ -1,6 +1,6 @@
 # Global command palette (⌘K)
 
-**Code:** `components/command-menu.tsx`, config **`buildCommandMenuConfig()`** in **`lib/command-menu-config.ts`**, wired in **`app/(app)/layout.tsx`** via **`CommandMenuProvider`**. Searchable row data is built in **`lib/command-menu-search-data.ts`** (not inside the shell component).
+**Code:** `components/command-menu.tsx`, config **`buildCommandMenuConfig()`** in **`lib/command-menu-config.ts`**, wired in **`src/App.tsx`** via **`CommandMenuProvider`**. Searchable row data is built in **`lib/command-menu-search-data.ts`** (not inside the shell component).
 
 ## Role
 
@@ -34,7 +34,7 @@ The command menu is the app’s **global search and AI entry**—one place to ju
 | Palette UI | `components/command-menu.tsx` |
 | Static groups + `buildCommandMenuConfig` | `lib/command-menu-config.ts` (`CommandMenuGroup.searchOnly`) |
 | Row → menu items (placements, etc.) | `lib/command-menu-search-data.ts` |
-| Provider + `dataGroups` | `app/(app)/layout.tsx` |
+| Provider + `dataGroups` | `src/App.tsx` |
 
 ## Sidebar
 

package/consumer-extras/patterns/consumer-upgrade-checklist.md

@@ -21,7 +21,7 @@ Overwrites only **`.cursor/skills/exxat-*`** and **`docs/exxat-ds/*.md`** (inclu
 
 The npm package includes a full Next.js reference under:
 
-**`node_modules/@exxatdesignux/ui/template/`**
+**`node_modules/@exxatdesignux/ui/template-vite/`**
 
 Use it when you need to know **what files exist**, **how shims re-export** `@exxatdesignux/ui`, or **what AGENTS / layout** patterns look like for the current release. Porting is manual: diff template vs your repo and apply intentional changes (imports, new components, CSS entrypoints).
 

package/consumer-extras/patterns/jobs/README.md

@@ -25,7 +25,7 @@ contract.**
 | **Review a record's full state** | [`record-detail.md`](./record-detail.md) | Students / Placements / Library detail |
 | **Triage a list of records** (find at-risk / actionable) | *future* | `PlacementsClient`, `ComplianceClient` |
 | **Compose / create a new record** | *future* | `new-library-item-form.tsx` |
-| **Configure preferences or workspace settings** | *future* | `app/(app)/settings/page.tsx` |
+| **Configure preferences or workspace settings** | *future* | `src/views/settings.tsx` |
 | **Scan many metrics for anomalies** | *future* | Dashboard route, `DashboardTabs` |
 | **Search / find anything** | *future* | `CommandMenu`, `DedicatedSearch*` |
 | **Onboarding / first-run setup** | *future* | `getting-started.tsx`, `CoachMark` |