@exxatdesignux/ui 0.5.10 → 0.5.12

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
 

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,25 +1,73 @@
 ---
-description: Exxat DS — output a design brief before writing files for any new surface; question bank by surface type
+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
 
-On any task that creates a **new route, page, template, wizard, or
-significant component**, the assistant MUST output a **design brief in chat**
-BEFORE writing files. Brief format is defined in
-`.cursor/skills/exxat-senior-ux/SKILL.md` §3.
+## STOP — read before you write any file
+
+If the user's prompt asks you to **design, create, build, rebuild, redesign,
+replace, redo, refresh, modernize, re-imagine, or "make a new version of"**
+any **page, route, screen, hub, detail view, wizard, settings section,
+dashboard, dialog, sheet, drawer, panel, layout, or significant component**:
+
+1. **Do NOT write code, do NOT edit files, do NOT call edit tools yet.**
+2. **Output the design brief** (template below) in chat.
+3. **Wait for the user to reply** with `yes` / `proceed` / `ship it` / edits.
+4. **Only then** move to implementation.
+
+If your next tool call would be `write_file`, `str_replace`, `create_file`,
+or any code-mutating action **and** you have not posted a brief and received
+go-ahead, you are violating this rule. **Stop and post the brief.**
+
+## When this gate fires (and when it doesn't)
+
+This gate fires on **any task that decides what a surface should look like
+or how it works** — whether the surface exists today or not. Treat
+"replace what we have" and "create from scratch" identically — both need a
+brief, because both make a design decision.
+
+**Fires (brief required):**
+
+- "Create a new student detail page."
+- "Rebuild the dashboard."
+- "Redesign the settings screen instead of what we have."
+- "Make a new version of the placements table."
+- "Replace the current onboarding flow."
+- "Build a wizard for adding a site."
+- "Design a sheet for inviting collaborators."
+- User attaches a screenshot / mockup / Figma link and asks to "build this".
+
+**Does NOT fire (brief not required, edit freely):**
+
+- Single-class restyle of an existing surface that already follows DS rules.
+- Copy / label edits.
+- Bug fixes (a11y violation, broken state, wrong data).
+- Dependency bumps, ESLint passes, type fixes, test-only changes.
+- Adding a new column / filter to an *existing* `HubTable` that doesn't
+  change the page's IA.
+
+When in doubt, ask: **"Am I deciding what this surface should be?"** Yes →
+brief. No → edit.
 
 ## MUST
 
-1. **No code without a brief.** New surfaces require the brief. Trivial edits
-   to existing surfaces (copy tweak, single-class change, bug fix, refactor)
-   are exempt.
+0. **Output the brief, then WAIT.** The brief is a checkpoint, not a
+   preamble. Do not bundle the brief and the first file edit in the same
+   turn. After posting the brief, end your turn with an explicit
+   "Ready to build — confirm or edit." prompt. Resume only on the user's
+   next message.
+1. **No code without a confirmed brief.** "Confirmed" means the user wrote
+   `yes`, `proceed`, `ship it`, `LGTM`, `build it`, accepted edits, or asked
+   a follow-up that implies acceptance. Silence is not consent.
 2. **Cite a reference.** Every brief names **one repo reference** + **two
-   modern SaaS analogues** (Linear / Notion / Stripe / Figma / Vercel / etc.)
-   that solve the same **job-to-be-done**. Cite the SaaS analogues by
-   product name + pattern codes from
-   `apps/web/docs/modern-saas-patterns.md` (e.g. `Linear issue detail (M1, M4, M7)`).
+   modern SaaS analogues** (Linear / Notion / Stripe / Figma / Vercel /
+   Linear / Airtable / Coda / Height / etc.) that solve the same
+   **job-to-be-done**. Cite the SaaS analogues by product name + pattern
+   codes from `apps/web/docs/modern-saas-patterns.md` (e.g.
+   `Linear issue detail (M1, M4, M7)`).
 3. **Name principles + breaks.** Brief lists the principles applied
    (`exxat-ux-principles.mdc`) and any deviations with one-sentence reasons.
    **Never-break** principles (P1–P8) cannot be deviated from.
@@ -30,6 +78,11 @@ BEFORE writing files. Brief format is defined in
 
 ## MUST NOT
 
+- **Skip the brief because the prompt sounds like a refactor.** "Rebuild",
+  "redesign", "replace", "instead of what we have", and "from scratch" are
+  design decisions, not refactors. Brief required.
+- **Post a brief and then write 8 files in the same turn.** That's not a
+  brief — that's a press release. End the turn after the brief.
 - Generate files before the brief.
 - Ask more than **3** questions in one batch.
 - Ask questions whose answer is already in the prompt, the file tree, or
@@ -113,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
@@ -120,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