@exxatdesignux/ui 0.5.11 → 0.5.12

package/template-vite/.cursor/rules/exxat-list-page-connected-views.mdc

@@ -0,0 +1,28 @@
+---
+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
+
+**Authoritative detail:** **`apps/web/AGENTS.md` §4.1** and **`apps/web/docs/data-views-pattern.md`** (mock data, connected views, dashboard view).
+
+## When building `ListPageTemplate` + data client
+
+1. **One `useTableState` per tab’s table** — Pass full mock/API rows into a single table component; **`list` / `board` / `dashboard`** surfaces consume **`tableState.rows`** (same filters/search/sort as the grid).
+2. **`renderContent`** — Always pass **`view={tab.viewType}`**; use **`key={tab.id}`** (not `viewType`) so switching views does not reset table state. Pass **`onViewChange`** into the table component so **`TablePropertiesDrawer`** stays aligned (**`currentView`** + **`updateTab({ viewType, icon: dataListViewIcon(viewType) })`** — see **`apps/web/AGENTS.md` §4.2** and **`.cursor/rules/exxat-table-properties-drawer.mdc`**).
+3. **Mock data** — Typed arrays in **`lib/mock/<entity>.ts`**; KPI builders in **`lib/mock/<entity>-kpi.ts`** returning **`MetricItem[]`** / **`MetricInsight`** from **`@/components/key-metrics`**.
+4. **Dashboard view tab** — Use **`KeyMetrics`** (`variant="flat"` or `"card"`) and the **same** KPI functions with **`tableState.rows`**. Do **not** add standalone `Card` metric grids that duplicate those numbers. For chart-heavy dashboards reuse **`ChartsOverview`** / **`DashboardTabs`** patterns from the main dashboard route when appropriate.
+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/template-vite/.cursor/rules/exxat-list-page-view-shells.mdc

@@ -0,0 +1,32 @@
+---
+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)
+
+## Intent
+
+**View bodies** under `ListPageTemplate` (table, list, board, dashboard, **folder**, **panel**, and future view types) **MUST** share one **layout primitive** for horizontal gutter and optional **centered max-width** on wide viewports. **MUST NOT** copy `mx-4 lg:mx-6` + `mx-auto max-w-*` per feature file or bake view-only layout into a single route.
+
+Domain logic (columns, tiles, folder trees) stays in **`*-table.tsx` / `*-client.tsx`**; **chrome and rhythm** use **`ListPageViewFrame`** from **`@/components/data-views/list-page-view-frame`** (re-exported from **`@/components/data-views`**). **Data** for those branches still comes from the **same** **`tableState.rows`** / hub state as the grid — see **`.cursor/rules/exxat-centralized-list-dataset.mdc`**.
+
+## MUST
+
+1. Wrap **non-`DataTable`** view branches (icon folder grid, OS-style explorer, empty folder states, comparable dashboard **sections** that are not the main grid) in **`ListPageViewFrame`**, passing **`maxWidthClassName`** when the design calls for a centered cap (defaults: **`LIST_PAGE_VIEW_FRAME_MAX_ICON_GRID`** (`max-w-6xl`), **`LIST_PAGE_VIEW_FRAME_MAX_WIDE`** (`max-w-7xl`)).
+2. Add **new reusable view surfaces** under **`components/data-views/`** with **generic props** (`rows`, `renderTile`, `getRowId`, etc.) — same pattern as **`FolderGridView`**, **`FinderPanelView`**, **`ListPageBoardTemplate`**. Page files **compose** them; they **MUST NOT** own grid/folder markup.
+3. When extracting an entity-specific view (e.g. question OS folders), plan a **generic** `*View` in **`data-views/`** plus a thin adapter if the product still needs typed mock wiring.
+
+## 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/`**.
+
+## See also
+
+- **`apps/web/AGENTS.md` §4.5** — handbook table + constants.
+- **`apps/web/docs/data-views-pattern.md`** — “View layout frame”.
+- **`.cursor/rules/exxat-centralized-list-dataset.mdc`** — **`tableState.rows`** into every view branch.
+- **`.cursor/skills/exxat-list-page-view-shells/SKILL.md`** — step-by-step for agents.

package/{template → template-vite}/.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

package/template-vite/.cursor/rules/exxat-nav-single-active.mdc

@@ -0,0 +1,32 @@
+---
+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)
+
+Only **one** primary sidebar row, collapsible child, or secondary-panel link may show the active/selected state for the current route.
+
+## MUST
+
+1. **Use shared helpers** from `@exxatdesignux/ui/lib/nav-active` (or the app copy synced from the DS template):
+   - `collectNavUrls` + `buildNavHashClaims` for the full nav tree
+   - `isNavHrefActive(pathname, url, allNavUrls, { locationHash, hashClaimsByPath })` for sidebar `SidebarMenuButton` / `isActive`
+   - `resolveActiveNavHref(pathname, allLinkHrefs)` for secondary-panel links — compare the returned href to each link’s `href` (longest prefix wins)
+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 — default **`FULL_HUB_SUPPORTED_VIEWS`** (seven views). See **`exxat-hub-supported-views.mdc`** for renderer requirements.
+
+## MUST NOT
+
+- Duplicate bespoke `isNavActive` / `isActive` logic that ignores longest-prefix matching.
+- Ship a new nav surface (sidebar, secondary rail, hub scope list) without wiring the helpers above.
+
+## Reference
+
+- `packages/ui/src/lib/nav-active.ts`
+- `packages/ui/template/components/sidebar/app-sidebar.tsx`
+- `packages/ui/template/components/sidebar/secondary-nav.tsx`

package/template-vite/.cursor/rules/exxat-no-image-pixel-copy.mdc

@@ -0,0 +1,46 @@
+---
+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
+
+When the user attaches a **screenshot**, **mockup**, **Figma export**, **legacy app capture**, or any **reference image**, treat it as **product intent** — **not** as code to transcribe.
+
+**Exxat DS rules, blueprints, and reference hubs always win** over what the image shows.
+
+## Allowed to take from an image (content / IA)
+
+- **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**, 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 writing UI code)
+
+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`** — compose before inventing
+- **`exxat-sidebar-shell.mdc`** — sidebar-specific anti-patterns
+- **`exxat-token-economy`** skill §2 — pre-flight includes image discipline

package/template-vite/.cursor/rules/exxat-no-slds-leakage.mdc

@@ -0,0 +1,84 @@
+---
+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
+`design-system-2-starter-kit`** (LWC + SLDS 2 / Cosmos). Patterns there look
+similar at a glance (`page-header`, `data-table`, `card`) but the
+**implementations are not portable** — they assume LWC, synthetic shadow,
+SLDS class systems, and the Salesforce platform.
+
+This rule prevents accidental cross-pollination from any **Salesforce / SLDS**
+codebase into **`apps/web`** or **`packages/ui`**.
+
+## MUST NOT
+
+1. **CSS class strings** — Do **not** introduce **`slds-*`** classes
+   (`slds-page-header`, `slds-m-around_*`, `slds-grid`, `slds-button`,
+   `slds-text-*`, etc.) anywhere in `apps/web/**` or `packages/ui/**`. The
+   Exxat stack is **Tailwind v4** + the token system documented in
+   [`apps/web/docs/token-taxonomy.md`](mdc:apps/web/docs/token-taxonomy.md).
+2. **LWC markup** — Do **not** render `<lightning-*>` tags
+   (`<lightning-button>`, `<lightning-datatable>`, `<lightning-card>`,
+   `<lightning-icon>`, etc.) or import from `lightning/*` modules. Use the
+   shadcn-style primitives in `packages/ui/src/components/ui/` and the
+   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
+   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-*`,
+   `--slds-g-color-border-*`, `--slds-g-color-accent-*`, etc.). The Exxat
+   equivalents are documented in
+   [`apps/web/docs/token-taxonomy.md`](mdc:apps/web/docs/token-taxonomy.md):
+   surface → `--background` / `--card` / `--secondary-panel-bg`; ink →
+   `--foreground` / `--muted-foreground`; border → `--border` /
+   `--border-control` family; brand → `--brand-color` family.
+5. **SLDS theme switching** — Do **not** add UI for selecting "SLDS 1" vs
+   "SLDS 2". Exxat ships **Exxat One** (lavender) and **Exxat Prism** (rose)
+   themes via `.theme-one` / `.theme-prism` classes — see
+   `docs/shell-surface-elevation-pattern.md`.
+6. **Slot-vs-prop confusion** — Do **not** import LWC slot conventions
+   (`slot="actions"`, `<slot name="…">`) into React components. React uses
+   `children` + named props (`actions={…}`, `header={…}`).
+7. **`lightning-base-components` patterns inside React** — Do **not** add
+   per-page form-input wrappers like `lightning-input` clones. Use shadcn
+   `Input` / `Select` / `Combobox` from `packages/ui`.
+
+## SHOULD
+
+- If you're comparing SLDS patterns to gain inspiration (e.g. the
+  `object-home` / `record-home` / `related-list` variant model from
+  `ui-page-header`), **document the idea** as a blueprint under
+  [`apps/web/docs/blueprints/`](mdc:apps/web/docs/blueprints) — do **not**
+  copy SLDS markup verbatim.
+- For any "but SLDS does it this way" thought, check
+  [`apps/web/docs/component-selection-guide.md`](mdc:apps/web/docs/component-selection-guide.md)
+  first to see what Exxat ships for that pattern.
+
+## Why this rule exists
+
+Salesforce's design system is excellent — but it is **built for a different
+runtime** (LWC + synthetic shadow + classic SLDS layered with SLDS 2 /
+Cosmos). Mixing its CSS class system into a Tailwind v4 + OKLCH token app
+silently breaks:
+
+- **Theming** — `slds-*` classes don't react to `.theme-prism` / `.dark` /
+  `[data-contrast="high"]`.
+- **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.
+
+## See also
+
+- [`apps/web/docs/token-taxonomy.md`](mdc:apps/web/docs/token-taxonomy.md) — Exxat tokens
+- [`apps/web/docs/blueprints/`](mdc:apps/web/docs/blueprints) — framework-agnostic specs
+- [`apps/web/docs/component-selection-guide.md`](mdc:apps/web/docs/component-selection-guide.md) — what to reach for
+- [`.cursor/rules/exxat-token-discipline.mdc`](mdc:.cursor/rules/exxat-token-discipline.mdc) — token-level enforcement
+- [`.cursor/rules/exxat-reuse-before-custom.mdc`](mdc:.cursor/rules/exxat-reuse-before-custom.mdc) — ask before adding new primitives

package/{template → template-vite}/.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
@@ -22,5 +23,4 @@ Toasts are easy to miss, stack poorly with complex layouts, and behave inconsist
 
 ## Authoritative detail
 
-- **`AGENTS.md` §6.5**
-- Repo root **`.cursor/rules/exxat-no-toast.mdc`** when the monorepo parent is open
+- **`apps/web/AGENTS.md` §6.5**

package/template-vite/.cursor/rules/exxat-no-vaul.mdc

@@ -0,0 +1,26 @@
+---
+description: Exxat DS — no Vaul Drawer primitive; side panels use Sheet only
+alwaysApply: true
+appliesTo: [universal]
+---
+
+# Exxat DS — no Vaul
+
+## MUST
+
+- Side panels (export, properties, invite, folder create) use **`Sheet`** from `@exxatdesignux/ui/components/sheet` with the floating inset pattern (`showOverlay={false}`, `getFloatingSheetInsetProps`).
+- Product code names may end in `*Drawer` (`ExportDrawer`, `TablePropertiesDrawer`) — implementation is **`Sheet`**, not Vaul.
+
+## MUST NOT
+
+- Add **`vaul`** to `package.json` or import `@/components/ui/drawer` / Vaul `Drawer`.
+- Scaffold or extend the removed shadcn Vaul wrapper — it was deleted from `@exxatdesignux/ui@0.5.3+`.
+
+## Consumer apps
+
+After upgrading to **`@exxatdesignux/ui@0.5.3`**, remove **`vaul`** from the app `package.json`, delete any local `components/ui/drawer.tsx` re-export, and re-run **`exxat-ui sync-extras`**.
+
+## See also
+
+- **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**
+- **`apps/web/docs/drawer-vs-dialog-pattern.md`**

package/template-vite/.cursor/rules/exxat-page-header-actions.mdc

@@ -0,0 +1,33 @@
+---
+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:** `apps/web/docs/blueprints/page-header.md`
+
+## Anatomy (actions slot only)
+
+| Control | DS pattern |
+|---------|------------|
+| **Primary CTA** | One **`Button`** `variant="default"` `size="lg"` (filled) — e.g. “Add student”, “Ask Leo” when it is the main action |
+| **Secondary / scope** (“View as”, “All students”) | **`Button variant="outline" size="lg"`** + chevron, or **`Select`** / **`DropdownMenu`** trigger styled as outline button — **not** plain grey rectangles or unstyled `<button>` |
+| **Overflow (⋯)** | **`Button variant="outline" size="icon-lg"`** (or `size="lg"` icon-only) opening **`DropdownMenu`** — Export, settings, invite |
+| **Collaboration** | **`PageHeader variant="collaboration"`** face rail — not a custom avatar row |
+
+## MUST
+
+- Compose **`PageHeader`** + pass **`actions`** as DS **`Button`** / **`DropdownMenu`** primitives.
+- Keep **one** filled primary; put Export and long-tail items under **⋯**.
+
+## MUST NOT
+
+- Hand-built header button rows that skip **`PageHeader`** and **`Button`** variants.
+- Multiple filled primaries beside each other (e.g. “Ask Leo” + “Add student” both solid black unless product explicitly documents hierarchy — prefer outline for secondary).
+
+## Reference
+
+- `components/library-page-header.tsx`, Placements/Team header patterns in **`apps/web/docs/reference-implementations.md`**

package/{template → template-vite}/.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
@@ -8,6 +9,7 @@ alwaysApply: true
 ## Rule
 
 - **Drawer / sheet** — Use when the user needs **the current page’s context** *and* a **quick view**, **quick actions**, or a **short auxiliary flow** (parent list or hub stays meaningful behind the panel).
+- **Dialog (modal)** — Use for **blocking** short confirms/alerts on the **same route** when the hub must not stay interactable — see **`docs/drawer-vs-dialog-pattern.md`**, **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**.
 - **New page (route)** — Use **otherwise**: primary tasks, long-form or multi-step work, or anything that should have its **own URL** / history without the parent page visible.
 
 ## Product examples (this repo)
@@ -17,6 +19,6 @@ alwaysApply: true
 
 ## Authoritative detail
 
-- **`AGENTS.md` §6.4**
-- **`docs/data-views-pattern.md`** (Page vs drawer)
-- Repo root **`.cursor/rules/exxat-page-vs-drawer.mdc`** when the monorepo parent is open
+- **`apps/web/AGENTS.md` §6.4**
+- **`apps/web/docs/data-views-pattern.md`** (Page vs drawer)
+- **`apps/web/docs/drawer-vs-dialog-pattern.md`** (drawer vs modal dialog)

package/template-vite/.cursor/rules/exxat-person-identity-display.mdc

@@ -0,0 +1,48 @@
+---
+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)
+
+Use this when rendering **a known person** (user, collaborator, author roster row, invitee, etc.) — not anonymous counts or system actors.
+
+## MUST (when email is available)
+
+1. **Primary** — Display name (or given + family name) as the dominant line.
+2. **Avatar** — Use **`AvatarInitials`** / the same primitives as **`PageHeader`** collaborator stack and **team** roster patterns (initials from display name via **`initialsFromDisplayName`** where applicable).
+3. **Secondary** — Work email (or login id) on a **muted** second line **under** the name, smaller type (`text-xs` / `text-muted-foreground`), truncated with **`truncate`** / **`min-w-0`** when the container is narrow.
+
+## Context: when **not** to show email
+
+Dense or width-constrained surfaces **MUST NOT** squeeze email if it harms scanability or layout:
+
+- **Board / kanban cards** — title row, card trailing, or narrow columns: **avatar + name (or initials chip) only**; skip the email line. Prefer a **Tip** on the avatar/name with full email for discovery if the card is interactive.
+- **Icon-only rails** — avatar only + tooltip with name + email.
+- **Single-line table cells** — if the column is not “Person”, only show what fits (e.g. name + Tip); do not wrap email into a second line inside a 1-line cell unless the column is dedicated to identity.
+
+## Table / list / drawer / inspector
+
+- **Dedicated person column** or **profile / invite / access** surfaces — show **avatar + name + email** (stacked or name with email below), consistent with **`InviteCollaboratorsDrawer`** and **`PageHeader`** collaboration variant.
+- **Example:** `LibraryTable` **Author** — `AvatarInitials`, **primary name** (`text-sm font-medium`), **muted `text-xs` email** with optional `mailto:` (row click does not navigate when the link is used).
+
+## Avatar rows — **never overlapping**
+
+When multiple people share a row (face rail, reviewer pile, attendee list, collaborator stack):
+
+- **MUST** render avatars **side-by-side** with a small gap (`gap-1` / `gap-1.5`) — same pattern as the **`PageHeader`** collaboration variant.
+- **MUST NOT** overlap avatars (Slack / GitHub face piles with negative margins like `-space-x-2` and ring-on-background separators). Ring contrast is fragile in dark mode, click targets stack, and screen readers announce ambiguous groupings.
+- **`AvatarGroup`** in **`packages/ui`** already ships the non-overlap default (`flex items-center gap-1.5`). Pair with **`AvatarGroupCount`** for the **`+N`** overflow chip, wrapped in a **`Tip`** that names the hidden people. Each visible avatar gets its own **`Tip`** with the person’s name (per **§8.6 (Case B)** in **`AGENTS.md`**).
+
+## MUST NOT
+
+- Show raw email as the only visible identifier when a display name exists (unless the product context is strictly technical, e.g. audit log “principal” column).
+- Use a different avatar size/shape for the same person between list and detail without a deliberate density tier.
+- Restore an overlapping face pile by adding back `-space-x-*` / negative margins / `*:ring-*` to **`AvatarGroup`** or any ad-hoc row of avatars.
+
+## See also
+
+- **`.cursor/rules/exxat-collaboration-access.mdc`** — face rail, invite sheet, access roster.
+- **`.cursor/skills/exxat-collaboration-access/SKILL.md`**
+- **`apps/web/AGENTS.md`** collaboration + list hub patterns where relevant.

package/template-vite/.cursor/rules/exxat-primary-nav-secondary-panel.mdc

@@ -0,0 +1,53 @@
+---
+description: Primary sidebar item opens nested SecondaryPanel (Library pattern)
+globs: apps/web/components/**/*.tsx
+alwaysApply: false
+appliesTo: [react]
+---
+
+# Exxat DS — primary nav → secondary panel
+
+Some hubs expose **scoped navigation** (All / My / tree / filters) in a **nested panel** between the **icon rail** and **main content** — not as **primary nav child rows**.
+
+**Reference:** **Library** — **`lib/mock/navigation.tsx`** (`secondaryPanel: "library"`), **`components/app-sidebar.tsx`**, **`components/secondary-panel.tsx`**, **`components/library-panel-activator.tsx`**, **`components/library-secondary-nav.tsx`**, **`lib/library-nav.ts`** (URL scope).
+
+## MUST (wiring)
+
+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`**).
+
+## Surface elevation (brand chrome)
+
+The nested panel sits **between** the icon rail and main content. **MUST** use the three-level stack (darkest → lightest):
+
+| Level | Surface | Token |
+|-------|---------|--------|
+| **0** | Primary sidebar | `--sidebar` (= `--brand-tint` on product themes) |
+| **1** | Secondary panel | `--secondary-panel-bg` |
+| **2** | Page canvas | `--background` |
+
+- **`NestedSecondaryPanelShell`** — **`bg-[var(--secondary-panel-bg)]`**, not **`bg-sidebar`** (same as level 0).
+- **OKLCH** — light: `color-mix(in oklch, var(--background) 40%, var(--brand-tint-light) 60%)`; dark: `color-mix(in oklch, var(--card) 32%, var(--brand-tint) 68%)`. **MUST** follow **active product** (`theme-one`, `theme-prism`, `theme-custom`) — **MUST NOT** hardcode rose for all products.
+- **`ProductProvider`** — `theme-custom` only when stored accent **differs** from product default (`accentOverrideActive`).
+
+**Authoritative detail:** **`apps/web/docs/shell-surface-elevation-pattern.md`**.
+
+## SHOULD
+
+- Drive **hub scope** from the **URL** (**`useSearchParams`** + helpers like **`parseLibraryNav`**) so **refresh**, **share link**, and **breadcrumbs** match the secondary list.
+- Keep **panel content** **Font Awesome**-aligned with the rest of the app (**`.cursor/rules/exxat-fontawesome-icons.mdc`**).
+
+## MUST NOT
+
+- Register a **`secondaryPanel`** id in **`NAV_PRIMARY`** **without** a **`PANELS`** entry and a matching **`useAutoPanel`** on the hub — users get a **collapsed sidebar** with **empty** panel space.
+- Use **`secondaryPanel`** for **full** app sections that deserve their **own primary nav rows** — reserve this for **one hub** + **inner scope** UI.
+
+## See also
+
+- **`apps/web/AGENTS.md` §4.6** — handbook summary.
+- **`apps/web/docs/shell-surface-elevation-pattern.md`** — OKLCH tokens + product theme.
+- **`.cursor/rules/exxat-library-hub-header.mdc`** — folder-scoped library header **⋯** → **Customize folder** + client-mounted sheet.
+- **`.cursor/rules/exxat-page-vs-drawer.mdc`** — when **drawer** vs **route**; secondary panel is **nav chrome**, not a workflow drawer.
+- **`.cursor/rules/exxat-kpi-flat-band.mdc`** — flat KPI strip (separate from panel fill).

package/template-vite/.cursor/rules/exxat-reuse-before-custom.mdc

@@ -0,0 +1,37 @@
+---
+description: Exxat DS — prefer centralized reusable components; ask the user before new bespoke primitives.
+alwaysApply: true
+appliesTo: [universal]
+---
+
+# Exxat DS — reuse before custom
+
+## MUST
+
+1. **Compose first** — Use existing **`components/ui/`**, **`components/data-views/`**, **`components/templates/`**, **`PageHeader`**, **`ListPageTemplate`**, **`DataTable`**, **`KeyMetrics`**, and patterns in **`AGENTS.md` §9** before writing new layout or interaction chrome.
+2. **Search the codebase** — Grep or open the nearest hub (Placements, Team, Library) for the same UX (toolbar, drawer, metrics, board card, `ListPageViewFrame`, etc.).
+3. **Extend in place** — Prefer adding a variant, slot, or prop to a shared component over a one-off duplicate under a single route.
+
+## When the tool must ask the user
+
+**MUST pause and ask the user** (with a short option list) when, after scanning, **no reasonable reuse** exists and the implementation would add **any** of:
+
+- A **new reusable primitive** (new file under `components/` meant for multiple routes), or  
+- A **non-trivial bespoke widget** (custom data grid, chart system, modal stack, or parallel design-system fork) that is not already implied by the task.
+
+Do **not** silently ship a second stack for the same product pattern (e.g. another “table”, another metrics strip, another sidebar).
+
+When the user **uploads a screenshot or mockup**, read **`exxat-no-image-pixel-copy.mdc`** first — extract IA only; map to DS patterns; never pixel-copy colors or chrome.
+
+If the **user or task already explicitly** approved a greenfield component (“build a new X from scratch”), you may proceed without re-asking.
+
+## MUST NOT
+
+- Add **route-only copies** of patterns that already live in **`components/`** or **`packages/ui`** without product reason.
+- Introduce **parallel primitives** (second button row, second card shell, second command surface) when an existing one can be parameterized.
+
+## See also
+
+- **`apps/web/AGENTS.md` §1** (compose / scan before new UI), **§9** architecture table  
+- **`.cursor/rules/exxat-ds-agents.mdc`**  
+- **`.cursor/rules/exxat-centralized-list-dataset.mdc`** — one dataset / one presentation path for hubs

package/template-vite/.cursor/rules/exxat-sidebar-shell.mdc

@@ -0,0 +1,41 @@
+---
+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)
+
+Customer / legacy app **screenshots** may show **what links exist** — not **how the sidebar is styled**. Full policy: **`exxat-no-image-pixel-copy.mdc`**.
+
+## Screenshots are allowed to inform (content only)
+
+- Nav **labels**, **grouping**, **route paths**, **Font Awesome icon suffixes**
+- Whether a row needs **children**, a **secondary panel**, or a **badge**
+
+## Screenshots MUST NOT drive styling (MUST NOT)
+
+- **Per-section label colors** (magenta / teal / gold text on every row in a group)
+- **Custom active pills** (hand-built white `rounded-*` + shadow instead of `SidebarMenuButton` `data-active`)
+- **Non-token sidebar fills** (pink wash, `#hex` tints, inline `style={{ color: … }}`)
+- **Forking `app-sidebar.tsx` layout** for one product while rest of DS uses shared chrome
+- **Re-implementing `isNavActive`** in the app — use **`@exxatdesignux/ui/lib/nav-active`** (see **`exxat-nav-single-active.mdc`**)
+
+## MUST — DS sidebar chrome
+
+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 Exxat Prism sidebar: color-coded **text** per module block, pink sidebar wash, bespoke selection chrome — **do not reproduce** when building on Exxat DS.

package/template-vite/.cursor/rules/exxat-table-properties-drawer.mdc

@@ -0,0 +1,79 @@
+---
+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
+
+**Authoritative detail:** **`apps/web/AGENTS.md` §4.2**.
+
+## Why this exists
+
+`TablePropertiesDrawer` uses **`currentView`** (`DataListViewType`) for the first summary row (“Board display” vs “Table display”, matching icons/descriptions) and to show **table-only** vs **board-only** sub-panels. If **`currentView`** is omitted, the drawer assumes **table** — wrong when the tab is **Board**, **List**, or **Dashboard**.
+
+## MUST
+
+When **`ListPageTemplate`** drives **`tab.viewType`** and the page renders **`TablePropertiesDrawer`** (directly or via a toolbar slot):
+
+1. Pass **`currentView={view}`** (same value as **`tab.viewType`** passed into your table component).
+2. Pass **`onViewChange`** from **`renderContent={(tab, updateTab) => ...}`** so the drawer’s view-type tiles stay in sync with the tab:
+
+   ```tsx
+   import { dataListViewIcon, type DataListViewType } from "@/lib/data-list-view"
+
+   onViewChange={(v: DataListViewType) =>
+     updateTab({ viewType: v, icon: dataListViewIcon(v) })
+   }
+   ```
+
+3. Thread **`view`** and **`onViewChange`** through: **client → table component → drawer toolbar → `TablePropertiesDrawer`**.
+
+**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
+
+`TablePropertiesDrawer` accepts an optional **`initialPanel`** prop so callsites can open the drawer focused on a named panel — `"main"` (default), `"table-display"`, `"filter"`, `"sort"`, `"group"`, `"columns"`, or `"conditional-rules"`. The current built-in use is the **Add Conditional Rule** item in every column header menu, which deep-links to the **Conditional rules** panel.
+
+### MUST
+
+1. **One state pair owns it.** `useTableState` exposes **`sheetInitialPanel`** + **`setSheetInitialPanel`** alongside `sheetOpen` / `setSheetOpen`. Read both in the drawer button; pass **`initialPanel={sheetInitialPanel}`** to `TablePropertiesDrawer`. Reference: `packages/ui/src/components/table-properties/drawer-button.tsx`.
+2. **The toolbar Properties button MUST clear the deep-link.** Otherwise the next plain "Properties" click re-opens onto whatever panel the previous deep-link set:
+
+   ```tsx
+   onClick={() => {
+     setSheetInitialPanel?.(null)
+     setSheetOpen(true)
+   }}
+   ```
+
+3. **Deep-link callsites MUST set panel + open in the same batched setState call.** Two setters in one callback land in one render, so the drawer mounts with `initialPanel` already populated — no panel-flash:
+
+   ```tsx
+   setSheetInitialPanel("conditional-rules")
+   setSheetOpen(true)
+   ```
+
+4. **From inside a Radix DropdownMenu, queue the action into `onCloseAutoFocus`.** Opening the non-modal Sheet synchronously from `DropdownMenuItem.onSelect` races with the menu close cycle. Use the `columnMenuPendingActionRef` pattern in `packages/ui/src/components/data-table/index.tsx` (or copy it) so the drawer opens after focus has returned to the trigger.
+
+### MUST NOT
+
+- Don't introduce a second source of truth for "which panel" — `sheetInitialPanel` is the only deep-link channel. The drawer's internal `sheetPanel` state stays internal.
+- Don't call `setSheetInitialPanel` from a non-deep-link callsite (e.g. a generic "open Properties" toolbar button). Leave it `null` for index opens.
+
+## View-type tile grid is uniformly square
+
+The drawer's "View type" tile grid (and the Export drawer's "File format" grid) renders through `SelectionTileGrid` with `interaction="button"` + `labelPlacement="inside"`. The shared `selectionTileClassNames` utility now applies **`aspect-square`** so every tile is the same shape regardless of how many tiles populate the last row of a `grid-cols-N` track. Two-word labels (e.g. "List & details") wrap inside the square because `leading-tight` keeps line height compact.
+
+When you compose your own tile-style picker, **prefer the shared `SelectionTileGrid`** (or `selectionTileClassNames` directly) instead of inventing flex/grid wrappers — that's the only way to keep the squares uniform across the system.
+
+## MUST NOT (overall)
+
+- Mount **`TablePropertiesDrawer`** on a multi-view list page **without** **`currentView`** when the active view is known from the tab.
+- Omit **`onViewChange`** if the product shows the **view type** control inside Properties (otherwise tiles cannot update the tab).
+
+## See also
+
+- **`apps/web/AGENTS.md` §4.2**, **§13** checklist
+- **`.cursor/rules/exxat-list-page-connected-views.mdc`**

package/template-vite/.cursor/rules/exxat-table-row-preview.mdc

@@ -0,0 +1,25 @@
+---
+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)
+
+When a **data table** cell opens a **rich preview** of a person or record (student, placement, team member):
+
+## MUST
+
+- Use **`HoverCard`** (`@/components/ui/hover-card`) for hover-driven previews, or **`Popover`** only when the preview is **click-pinned** and small.
+- Structure identity with **`AvatarInitials`**, name, **`font-mono tabular-nums`** on IDs only (**`exxat-mono-ids.mdc`**), **`ListHubStatusBadge`** + **`lib/list-status-badges.ts`** for status — **color + icon** (**`exxat-accessibility.mdc`** 1.4.1).
+- Reuse table cell patterns from **`@/components/data-views`** (`PeopleAvatarRailCell`, `PillCell`, progress cells) — see **`columns-showcase.tsx`**.
+
+## MUST NOT
+
+- Bespoke **`PopoverContent`** layouts with ad-hoc spacing, one-off progress bars, or status chips without the shared badge map.
+- Raw email as the only identifier when a display name exists (**`exxat-person-identity-display.mdc`**).
+
+## Reference
+
+- **`HoverCard`** docs in `packages/ui/src/components/ui/hover-card.tsx`
+- **`apps/web/docs/blueprints/data-table.md`**