@exxatdesignux/ui 0.5.10 → 0.5.12

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`**

package/template-vite/.cursor/rules/exxat-tabs-chrome.mdc

@@ -0,0 +1,33 @@
+---
+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)
+
+## List hubs (All students, Placements, …)
+
+**MUST** use **`ListPageTemplate`** view toolbar — `role="toolbar"` + **`w-max`** segmented control (`viewSegmentedToolbarClass`), **not** Radix **`Tabs`** stretched across the page.
+
+- Reference: `packages/ui/src/components/templates/list-page.tsx` (views toolbar block).
+- **MUST NOT** build a custom full-width tab bar for “All students · 16” + Add view.
+
+## Entity / record detail (Overview, Academics, Placements, …)
+
+**MUST** use **`Tabs`**, **`TabsList`**, **`TabsTrigger`** from `@/components/ui/tabs`:
+
+- **`TabsList`** defaults to **`inline-flex w-fit`** — **MUST NOT** pass `className="w-full"` or wrap the list in a full-width flex container that forces triggers to **`flex-1`**.
+- Prefer **`variant="line"`** for record sub-nav under a **`PageHeader`** (`record-home` blueprint).
+- **`TabsTrigger`** may use `flex-1` only inside a **`w-fit`** list with a fixed number of tabs — never inside a bar that spans the content column.
+
+## MUST NOT
+
+- A single grey/white bar spanning the entire content width with tabs distributed edge-to-edge.
+- Mix hub **view tabs** (table/list/board) with entity **section tabs** (Overview/Academics) — different patterns.
+
+## See also
+
+- **`apps/web/docs/blueprints/page-header.md`** — header never carries view tabs
+- **`apps/web/docs/data-views-pattern.md`** — `ListPageTemplate` view toolbar

package/template-vite/.cursor/rules/exxat-token-discipline.mdc

@@ -0,0 +1,109 @@
+---
+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).
+**Machine-readable index:** [`packages/ui/tokens/hooks-index.json`](mdc:packages/ui/tokens/hooks-index.json) (163 tokens · 36 namespaces; regenerate via `pnpm --filter @exxatdesignux/ui tokens:index`).
+**Enforcement:** [`@exxatdesignux/eslint-plugin`](mdc:packages/eslint-plugin-exxat-ds/README.md) (rules `exxat-ds/no-hex-color`, `exxat-ds/no-deprecated-tokens`).
+
+Use this rule when adding **any** color, spacing, radius, shadow, or
+transition value to JSX, CSS, or Tailwind class strings.
+
+## MUST
+
+1. **Prefer the Exxat L0 namespace** for new code — `var(--exxat-color-surface-1)`,
+   `bg-surface-1`, `bg-brand-1`, `rounded-2`, `--exxat-spacing-4`, … (taxonomy §2.0).
+   L1 shadcn names (`--background`, `bg-brand`, `rounded-md`, …) remain as
+   back-compat aliases and continue to work — but new product surfaces should
+   read in the canonical brand-prefixed namespace.
+2. **Reach for a semantic token first.** If the value carries semantic intent
+   ("danger", "warning", "muted text", "card surface"), use the matching
+   token family from §2 of the taxonomy. Never reinvent semantic colors.
+3. **Use Tailwind utilities backed by tokens** (e.g. `bg-card`,
+   `text-muted-foreground`, `border-border-control`, `ring-ring`,
+   `bg-chip-2`, `text-chart-4`, **`bg-surface-1`**, **`bg-brand-1`**,
+   **`rounded-2`**). The L2 bridges in `globals.css` already wire
+   `--color-*` → `var(--*)` so utilities flip with theme + dark mode.
+3. **Brand accent comes from `--brand-color` / `bg-brand`** (and its family),
+   **not** `--primary` / `bg-primary`. Primary is **neutral charcoal** in
+   Exxat — see taxonomy §3.
+4. **Form-field borders** use `--control-border` (or `border-control-3` /
+   `border-control-35`) — never `--border` (which is decorative and < 3:1
+   contrast). Taxonomy §6.
+5. **Status chips and badges** route through
+   [`lib/list-status-badges.ts`](mdc:apps/web/lib/list-status-badges.ts)
+   (`LIST_HUB_STATUS_TINT_*` + `ListHubStatusBadge`) — not direct
+   `bg-green-500` / `bg-red-500` / hex literals.
+6. **KPI tints** route through `--insight-severity-*` (info / warning) — not
+   direct chart-color reuse. Trend polarity is set via
+   `MetricItem.trendPolarity` ([`exxat-kpi-trends.mdc`](mdc:.cursor/rules/exxat-kpi-trends.mdc)).
+7. **Scoped surface tokens stay scoped.** `--dt-*` is `DataTable` only,
+   `--key-metrics-*` is `KeyMetrics` only, `--leo-*` is Ask Leo only,
+   `--secondary-panel-bg` is the nested panel only. Do **not** reuse these
+   tokens outside their owning surface.
+8. **Adding a new token** — Follow the checklist in
+   [`token-taxonomy.md` §4](mdc:apps/web/docs/token-taxonomy.md). Declare
+   the primitive in `packages/ui/src/globals.css` (canonical CSS), bridge it in the same file's `@theme inline`
+   files when Tailwind utilities are needed, document it in the taxonomy,
+   and regenerate `tokens/hooks-index.json`.
+
+## MUST NOT
+
+1. **No raw hex / rgb / hsl color literals** in JSX `className` strings,
+   inline `style={{...}}`, or `.css` files outside of `globals.css` /
+   `globals.css` / theme overrides. The only places hex is legal are:
+   - `--theme-color-chrome` (consumed by `<meta name="theme-color">`)
+   - Status icon SVG paths that are part of a vendored asset
+   - **Documentation** examples (this rule, blueprints, migrations)
+2. **No raw `oklch(...)` literals** in component code — those belong in
+   `globals.css` theme blocks only. If you need a derived value, use
+   `color-mix(in oklch, var(--token) <pct>%, var(--other))` inside a token
+   declaration, not at the call site.
+3. **No deprecated tokens.** Inspect
+   [`tokens/hooks-index.json`](mdc:packages/ui/tokens/hooks-index.json) —
+   any entry with `"deprecated": true` is removed at the version named in
+   `deprecatedMessage`. Migrate before the removal window per
+   `apps/web/docs/migrations/`.
+4. **No ad-hoc Tailwind shades** for product chrome (e.g. `bg-slate-50`,
+   `text-zinc-600`, `border-gray-200`) when an Exxat semantic equivalent
+   exists. Tailwind shade utilities are reserved for transient prototyping
+   only; product code uses the semantic tokens.
+5. **No `text-primary` for the brand accent.** That maps to neutral charcoal
+   (see MUST #3).
+6. **No utility-class typos that look like tokens.** Examples that look
+   right but aren't:
+   - `bg-brand-color` — that's the *raw L1 name*; the L2 utility is `bg-brand`.
+   - `border-control` — there's no such utility; the field-border alias is `border-control-3` (3:1) or `border-control-35` (3.5:1+), or `border-[var(--control-border)]`.
+   - `text-foreground-muted` — the token is `--muted-foreground` (note the order).
+7. **No SLDS tokens** (`--slds-g-color-*`) — see
+   [`exxat-no-slds-leakage.mdc`](mdc:.cursor/rules/exxat-no-slds-leakage.mdc).
+
+## Aliases that ARE official
+
+Some L2 bridges intentionally use a **shorter alias** than the L1 primitive
+because the long name would be awkward in Tailwind utilities. Use the alias
+form, but be aware of the underlying primitive:
+
+| Alias (use in code) | L0 canonical | L1 primitive | Notes |
+|---|---|---|---|
+| `bg-brand` / `text-brand` | `--exxat-color-brand-1` | `--brand-color` | Brand accent |
+| `bg-brand-deep` / `text-brand-deep` | `--exxat-color-brand-deep` | `--brand-color-deep` | Coach marks, hero callouts |
+| `bg-brand-tint` | `--exxat-color-brand-tint-1` | `--brand-tint` | Sidebar wash |
+| `bg-surface-1` / `text-ink-1` | `--exxat-color-surface-1` / `--exxat-color-ink-1` | `--background` / `--foreground` | Page canvas + primary text — new code SHOULD prefer L0 form |
+| `rounded-1` … `rounded-6` | `--exxat-radius-1` … `--exxat-radius-6` | (no L1 equivalent — L0 is canonical for radius) | Numeric radius scale (4 / 8 / 12 / 16 / 20 / 24 px) |
+
+The full alias table is in [`token-taxonomy.md` §2.0](mdc:apps/web/docs/token-taxonomy.md) and [§2.2](mdc:apps/web/docs/token-taxonomy.md).
+
+## See also
+
+- [`apps/web/docs/token-taxonomy.md`](mdc:apps/web/docs/token-taxonomy.md) — full namespace + naming rules
+- [`apps/web/docs/migrations/`](mdc:apps/web/docs/migrations) — deprecation index
+- [`packages/ui/tokens/hooks-index.json`](mdc:packages/ui/tokens/hooks-index.json) — machine-readable
+- [`.cursor/rules/exxat-no-slds-leakage.mdc`](mdc:.cursor/rules/exxat-no-slds-leakage.mdc)
+- [`.cursor/rules/exxat-kpi-trends.mdc`](mdc:.cursor/rules/exxat-kpi-trends.mdc)
+- [`.cursor/rules/exxat-kpi-flat-band.mdc`](mdc:.cursor/rules/exxat-kpi-flat-band.mdc)
+- [`.cursor/rules/exxat-no-toast.mdc`](mdc:.cursor/rules/exxat-no-toast.mdc)