@exxatdesignux/ui 0.2.19 → 0.3.0

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

@@ -0,0 +1,25 @@
+---
+description: Exxat DS — do not use toast / sonner / transient snackbars for product messaging.
+alwaysApply: true
+---
+
+# Exxat DS — no toast
+
+## MUST NOT
+
+- Do **not** use **`toast()`** (e.g. **Sonner**), **snackbar**, or other **transient corner notifications** for product feedback in this app.
+- Do **not** add new imports from **`sonner`** or wire **`Toaster`** for feature surfaces.
+
+## Use instead
+
+- **`LocalBanner`** / **`SystemBanner`** for persistent, readable messaging.
+- **Inline status** next to the action (e.g. button label change, subtle text under the control, row-level state).
+- **Dialog / drawer** confirmations when the user must acknowledge an outcome.
+
+## Why
+
+Toasts are easy to miss, stack poorly with complex layouts, and behave inconsistently with screen readers and focus. This product standardizes on **banners + inline + dialogs**.
+
+## Authoritative detail
+
+- **`apps/web/AGENTS.md` §6.5**

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

@@ -0,0 +1,23 @@
+---
+description: Exxat DS — when to use a drawer vs a new page for actions and auxiliary UI.
+alwaysApply: true
+---
+
+# Exxat DS — page vs drawer
+
+## 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)
+
+- **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.
+
+## Authoritative detail
+
+- **`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/consumer-extras/cursor-rules/exxat-person-identity-display.mdc

@@ -0,0 +1,47 @@
+---
+description: Exxat DS — avatar + name + email when showing a person; omit email in dense contexts (e.g. board cards).
+alwaysApply: false
+---
+
+# 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:** `QuestionBankTable` **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/consumer-extras/cursor-rules/exxat-primary-nav-secondary-panel.mdc

@@ -0,0 +1,52 @@
+---
+description: Primary sidebar item opens nested SecondaryPanel (Question bank pattern)
+globs: apps/web/components/**/*.tsx
+alwaysApply: false
+---
+
+# 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:** **Question bank** — **`lib/mock/navigation.tsx`** (`secondaryPanel: "question-bank"`), **`components/app-sidebar.tsx`**, **`components/secondary-panel.tsx`**, **`components/question-bank-panel-activator.tsx`**, **`components/question-bank-secondary-nav.tsx`**, **`lib/question-bank-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. **`"question-bank"`**). 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. **`QuestionBankPanelActivator`** + **`beforeSiteHeader`** on **`QuestionBankClient`**).
+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 **`parseQuestionBankNav`**) 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-question-bank-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/consumer-extras/cursor-rules/exxat-question-bank-hub-header.mdc

@@ -0,0 +1,28 @@
+---
+description: Question bank library — folder-scoped hub header More menu must expose Customize folder; sheet on hub client
+globs: apps/web/components/question-bank-*.tsx, packages/ui/template/components/question-bank-*.tsx
+alwaysApply: false
+---
+
+# Exxat DS — Question bank hub header (folder scope)
+
+When the question bank library URL is **scoped to a folder** (`parseQuestionBankNav` → **`scope === "folder"`** and **`folderId`** set), users are effectively on a **“folder page”**: the hub title matches that folder, and **global** actions belong in the **`QuestionBankPageHeader`** **⋯ More** menu — not only on per-row or per-tile overflow menus inside a single view tab.
+
+**Pattern doc:** **`apps/web/docs/question-bank-hub-header-pattern.md`**. **Handbook:** **`apps/web/AGENTS.md` §4.6** (folder-scoped hub chrome).
+
+## MUST
+
+1. **`QuestionBankPageHeader`** — When **`navState.scope === "folder"`** and **`navState.folderId`** resolves to a row in **`folders`**, pass **`onCustomizeFolder`** so **⋯ More** includes **Customize folder** ( **`fa-wand-magic-sparkles`** + label **Customize folder** ), placed after **Invite people** (collaboration variant) and before **Export**.
+2. **Hub client** — Mount **`QuestionBankNewFolderSheet`** on the **hub client** (e.g. **`QuestionBankClient`**) next to **`ListPageTemplate`**, driven by local **`open` / `customizingFolder`** state opened from **`onCustomizeFolder`**. **MUST NOT** rely on **`QuestionBankTable`** alone to host the sheet when some view branches (**table**, **list**, **board**, **dashboard**) do not render that sheet — users would lose **Customize folder** on those tabs.
+3. **`onCreated`** — On save, **`setFolders`** (or equivalent) **maps** the scoped folder **`id`** to updated **`name`**, **`icon`**, **`colorKey`** — same contract as **`QuestionBankTable`** panel/tree customize handlers.
+
+## MUST NOT
+
+- Omit **Customize folder** from the header **⋯** when the URL is folder-scoped, expecting users to find it only on secondary-nav tree rows or OS-folder tiles.
+- Mount **only** one customize sheet inside **`QuestionBankTable`** without a **client-level** sheet when the hub uses **`ListPageTemplate`** view tabs that omit that table subtree.
+
+## See also
+
+- **`.cursor/rules/exxat-primary-nav-secondary-panel.mdc`** — URL scope + secondary panel.
+- **`.cursor/rules/exxat-collaboration-access.mdc`** — **`variant="collaboration"`** header + **⋯** invite pattern.
+- **`lib/question-bank-nav.ts`** — **`parseQuestionBankNav`**, **`QuestionBankNavState`**.

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

@@ -0,0 +1,34 @@
+---
+description: Exxat DS — prefer centralized reusable components; ask the user before new bespoke primitives.
+alwaysApply: true
+---
+
+# 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, Question bank) 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).
+
+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/consumer-extras/cursor-rules/exxat-table-properties-drawer.mdc

@@ -0,0 +1,77 @@
+---
+description: TablePropertiesDrawer must receive currentView and onViewChange when used with ListPageTemplate view tabs
+alwaysApply: true
+---
+
+# 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/placements-table.tsx` (`PlacementsTable`), `components/team-client.tsx` + `team-table.tsx`, `components/compliance-client.tsx` + `compliance-table.tsx`.
+
+## 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/consumer-extras/cursor-rules/exxat-token-discipline.mdc

@@ -0,0 +1,103 @@
+# 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)

package/consumer-extras/cursor-skills/exxat-accessibility/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: true
 
 Standard target: **WCAG 2.1 Level AA** (and 2.2 where noted).
 
-**Canonical for agents (MUST/MUST NOT, checklist):** `exxat-ds/AGENTS.md` **§8** in the repo (same content summarized there; this skill stays the detailed checklist + product tokens).
+**Canonical for agents (MUST/MUST NOT, checklist):** `apps/web/AGENTS.md` **§8** in the repo (same content summarized there; this skill stays the detailed checklist + product tokens).
 
 ## ARIA roles & structure (SC 1.3.1)
 

package/consumer-extras/cursor-skills/exxat-board-cards/SKILL.md

@@ -7,7 +7,7 @@ user-invocable: true
 
 # Exxat DS — board (kanban) cards
 
-**Canonical MUST/MUST NOT:** **`exxat-ds/AGENTS.md` §4.4** (or **`./AGENTS.md`** when the workspace is the `exxat-ds` app folder only). **Claude:** **`.claude/skills/exxat-board-cards/SKILL.md`** (repo root) or **`exxat-ds/.claude/skills/exxat-board-cards/SKILL.md`** (app-only workspace) — same body as this file. This skill is the **how-to**; the handbook stays the contract.
+**Canonical MUST/MUST NOT:** **`apps/web/AGENTS.md` §4.4** (or **`./AGENTS.md`** when the workspace is the `apps/web/` app folder only). **Claude:** **`.claude/skills/exxat-board-cards/SKILL.md`** (repo root) — same body as this file. This skill is the **how-to**; the handbook stays the contract.
 
 ## When to use this skill
 
@@ -45,7 +45,7 @@ Prefer **two-line blocks** for stacked **primary / secondary** facts so cards ma
 - **Component:** **`ListHubStatusBadge`** from **`@/components/list-hub-status-badge`** — **`surface="table"`** for **DataTable** cells and **list** rows; **`surface="board"`** inside **`ListPageBoardCardBadgeRow`**. Do not duplicate the shell classes on each page.
 - Use the **same** maps everywhere for that entity so copy and colors never drift.
 - **Do not** add **`uppercase`** or **`tracking-wide`** — **sentence / title case**, consistent with **`BoardStatusBadge`** on Placements (`placement-board-card.tsx`).
-- **Placements** lifecycle uses **`StatusBadge`** in **`data-list-table-cells.tsx`** — thin wrapper over **`ListHubStatusBadge`** + **`PLACEMENT_STATUS_*`** in **`list-status-badges.ts`** (same visuals as Team / Question bank).
+- **Placements** lifecycle uses **`StatusBadge`** in **`placements-table-cells.tsx`** — thin wrapper over **`ListHubStatusBadge`** + **`PLACEMENT_STATUS_*`** in **`list-status-badges.ts`** (same visuals as Team / Question bank).
 
 ## Avatar when mock has no `initials`
 

package/consumer-extras/cursor-skills/exxat-centralized-list-dataset/SKILL.md

@@ -60,18 +60,7 @@ Goal: **one row model**, **one filtered bag** (`tableState.rows`), **one place f
 
 ---
 
-## 6. View registry + connected body (required)
-
-- [ ] **`lib/<hub>-supported-views.ts`** — same array on **`ListPageTemplate`** (`supportedViewTypes`) and **`TablePropertiesDrawerButton`**.
-- [ ] **`ListPageConnectedViewBody`** + **`defineHubViewRenderers(supported, { … })`** — one renderer per **`DataListViewRenderKind`**; missing → **`ListPageViewNotConfigured`** (never silent dashboard).
-- [ ] Branch on **`getDataListViewRenderKind(view)`** via the connected body — not long **`if (view === "table")`** chains in the table file.
-- [ ] **`lib/data-list-view-registry.ts`** — labels/icons/render kinds stay centralized.
-
-**Canon:** `docs/data-views-pattern.md` § “View registry and connected bodies”, **`AGENTS.md` §4.1.1**.
-
----
-
-## 7. Implementation checklist (new hub or new view)
+## 6. Implementation checklist (new hub or new view)
 
 - [ ] Exactly **one** primary row array shape in **`lib/mock/<entity>.ts`** (or API).
 - [ ] **`useTableState`** seeded from that array; **child views** receive **`tableState.rows`** (or equivalent), **not** a fresh import of the mock list.
@@ -83,15 +72,15 @@ Goal: **one row model**, **one filtered bag** (`tableState.rows`), **one place f
 
 ---
 
-## 8. Reference implementations
+## 7. Reference implementations
 
-- **`components/data-list-client.tsx`** + **`data-list-table.tsx`** — Placements pattern.
+- **`components/placements-client.tsx`** + **`placements-table.tsx`** — Placements pattern.
 - **`components/team-client.tsx`** + **`team-table.tsx`**.
 - **`components/question-bank-table.tsx`** — multiple **`DataListViewType`** branches sharing **`tableState`** / **`folders`** / **`items`**.
 
 ---
 
-## 9. Centralized presentation (with the same dataset)
+## 8. Centralized presentation (with the same dataset)
 
 **Layout:** Non-table view branches wrap in **`ListPageViewFrame`** (constants in **`list-page-view-frame.tsx`**) — see **`.cursor/rules/exxat-list-page-view-shells.mdc`**.
 

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

@@ -19,9 +19,9 @@ description: >
 ## 1. Project Overview
 
 - **Stack:** Next.js 16 (App Router), React, TypeScript, Tailwind CSS, shadcn/ui primitives, Font Awesome icons
-- **App root:** `exxat-ds/app/(app)/` — route group that wraps all authenticated pages
-- **Single source of truth:** `exxat-ds/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-focused-workflow-page`, `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`**.
+- **App root:** `apps/web/app/(app)/` — route group that wraps all authenticated pages
+- **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`**.
 - **Question bank folder-scoped header (rule + doc):** **`.cursor/rules/exxat-question-bank-hub-header.mdc`** and **`docs/question-bank-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.
 
@@ -259,21 +259,8 @@ ListPageTemplate
 ```
 
 **Reference implementations:**
-- **`apps/web`:** `components/list-hub-client.tsx` + `list-hub-table.tsx`, `question-bank-client.tsx` + `question-bank-table.tsx`
-- **`packages/ui/template/`** (ships with npm): `placements-client.tsx` + `placements-table.tsx`, `team-client.tsx` + `team-table.tsx` — diff template on upgrade
-
-### 4.1 View registry (do not fork `if (view === …)`)
-
-1. **`lib/data-list-view.ts`** — `DATA_LIST_VIEW_TILES` (labels/icons).
-2. **`lib/data-list-view-registry.ts`** — `renderKind`, `showsListPageHubMetricsStrip`, `dataListViewTilesForHub`.
-3. **`lib/foo-supported-views.ts`** — `export const FOO_SUPPORTED_VIEWS = ["table", "list", …] as const`.
-4. **`ListPageTemplate`** — `supportedViewTypes={FOO_SUPPORTED_VIEWS}`.
-5. **`foo-table.tsx`** — `ListPageConnectedViewBody` with renderers per kind; **`TablePropertiesDrawerButton`** gets the same **`supportedViewTypes`**.
-6. Generic bodies under **`components/data-views/`** — calendar, board template, folder grid, etc.
-
-**MUST NOT** default unknown views to dashboard KPIs — missing renderers use **`ListPageViewNotConfigured`**.
-
-**Narrative:** `docs/data-views-pattern.md` § “View registry and connected bodies”.
+- `components/team-client.tsx` + `components/team-table.tsx` — canonical pattern
+- `components/placements-client.tsx` + `components/placements-table.tsx` — Placements (most complete)
 
 **Files to create for a new hub page `Foo`:**
 | File | Purpose |
@@ -281,21 +268,19 @@ ListPageTemplate
 | `lib/mock/foo.ts` | Mock data + TypeScript interface (12+ rows) |
 | `lib/mock/foo-kpi.ts` | `fooKpiMetrics()` + `fooKpiInsight()` |
 | `components/foo-page-header.tsx` | `PageHeader` + primary CTA + ⋯ menu |
-| `lib/foo-supported-views.ts` | Views this hub implements (registry allowlist) |
-| `components/foo-table.tsx` | `ListPageConnectedViewBody` + `DataTable` + `useTableState` + Properties |
-| `components/foo-client.tsx` | `ListPageTemplate` + `supportedViewTypes` |
+| `components/foo-table.tsx` | `DataTable` + `useTableState` + `TablePropertiesDrawer` |
+| `components/foo-client.tsx` | `ListPageTemplate` orchestrator |
 | `app/(app)/foo/page.tsx` | Thin server component |
 
-**Do not** ship a **nav-linked hub** as an **empty page** or a single “replace this later” paragraph. If the route appears in **`lib/mock/navigation.tsx`**, implement the full hub (mock rows, **`ListPageTemplate`**, connected views per **`exxat-ds/AGENTS.md` §4.1**) unless the product explicitly defines a non-data shell.
+**Do not** ship a **nav-linked hub** as an **empty page** or a single “replace this later” paragraph. If the route appears in **`lib/mock/navigation.tsx`**, implement the full hub (mock rows, **`ListPageTemplate`**, connected views per **`apps/web/AGENTS.md` §4.1**) unless the product explicitly defines a non-data shell.
 
 ### Page vs drawer (actions)
 
 - **Drawer / sheet** — Use when the user needs **the current page behind them** *and* a **quick view**, **quick actions**, or a **short step** (e.g. properties, export, glance at a row).
 - **Dialog** — **Blocking** confirm/alert/short choice — **`docs/drawer-vs-dialog-pattern.md`**, **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**.
 - **New page** — Use **otherwise**: **primary**, **long-form**, **multi-step**, or flows that need their **own URL** without the hub visible.
-- **Focused workflow route** — **`FocusedWorkflowPageTemplate`** + **`FocusedWorkflowSingleColumn`** | **`FocusedWorkflowStepForm`** | **`FocusedWorkflowSidebarSections`** | **`FocusedWorkflowEmptyState`** — **`docs/focused-workflow-page-pattern.md`**, **`AGENTS.md` §14**, **`exxat-focused-workflow-page`** skill. **Not** list hubs; **not** Miller columns.
 
-Align with **`exxat-ds/AGENTS.md` §6.4**, **§14**, **`docs/data-views-pattern.md`**, **`docs/drawer-vs-dialog-pattern.md`**, **`docs/focused-workflow-page-pattern.md`**, **`.cursor/rules/exxat-page-vs-drawer.mdc`**, **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**, **`.cursor/rules/exxat-focused-workflow-page.mdc`**.
+Align with **`apps/web/AGENTS.md` §6.4**, **`docs/data-views-pattern.md`**, **`docs/drawer-vs-dialog-pattern.md`**, **`.cursor/rules/exxat-page-vs-drawer.mdc`**, **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**.
 
 ---
 
@@ -311,7 +296,7 @@ Align with **`exxat-ds/AGENTS.md` §6.4**, **§14**, **`docs/data-views-pattern.
 | `ColumnDef` from `@/components/data-table/types` | Column type |
 | `FilterFieldDef`, `FilterOperator`, `ConditionalRule` from `@/components/table-properties/types` | Filter types |
 
-**Board (kanban) cards:** Use **`ListPageBoardCard`** and related parts from **`components/data-views/list-page-board-card.tsx`**; **`BoardCardTwoLineBlock`** / **`BoardCardIconRow`** from **`board-card-primitives.tsx`**. **List hub** status (Team, Compliance, Question bank, …): maps in **`lib/list-status-badges.ts`**; render with **`ListHubStatusBadge`** (**`surface="table"`** in table/list, **`surface="board"`** on cards); semantic tints **`LIST_HUB_STATUS_TINT_*`** for new domains; no **`uppercase`**. **Placements** uses **`StatusBadge`** in **`data-list-table-cells.tsx`** (wrapper over **`ListHubStatusBadge`** + **`PLACEMENT_STATUS_*`**). **Full rules:** **`exxat-ds/AGENTS.md` §4.4**, **`.cursor/rules/exxat-board-cards.mdc`**, **`.cursor/skills/exxat-board-cards/SKILL.md`**.
+**Board (kanban) cards:** Use **`ListPageBoardCard`** and related parts from **`components/data-views/list-page-board-card.tsx`**; **`BoardCardTwoLineBlock`** / **`BoardCardIconRow`** from **`board-card-primitives.tsx`**. **List hub** status (Team, Compliance, Question bank, …): maps in **`lib/list-status-badges.ts`**; render with **`ListHubStatusBadge`** (**`surface="table"`** in table/list, **`surface="board"`** on cards); semantic tints **`LIST_HUB_STATUS_TINT_*`** for new domains; no **`uppercase`**. **Placements** uses **`StatusBadge`** in **`placements-table-cells.tsx`** (wrapper over **`ListHubStatusBadge`** + **`PLACEMENT_STATUS_*`**). **Full rules:** **`apps/web/AGENTS.md` §4.4**, **`.cursor/rules/exxat-board-cards.mdc`**, **`.cursor/skills/exxat-board-cards/SKILL.md`**.
 
 **Minimum required features on any data list page:**
 - Search (wire `searchable={displayOptions.showToolbarSearch}`)
@@ -621,7 +606,7 @@ Reference implementations: `new-placement-form.tsx` (Create placement = Enter on
 - **Natural language / AI:** Product **SHOULD** show **quick results in the palette** when the response fits; use **Ask Leo** (**⌘⌥K**) for **longer or complex** answers.
 - **Do not** treat the palette as a static link list only—leave room for inline AI results as they ship.
 
-**Details:** `exxat-ds/docs/command-menu-pattern.md`, **`exxat-ds/AGENTS.md` §7.1** (or `./` when the app folder is the workspace root).
+**Details:** `apps/web/docs/command-menu-pattern.md`, **`apps/web/AGENTS.md` §7.1** (or `./` when the app folder is the workspace root).
 
 ---
 
@@ -876,8 +861,8 @@ Copy and complete for every list/table/hub page:
 - [ ] Sidebar item added to `lib/mock/navigation.tsx` with light/solid icon pair
 - [ ] **Shell sidebar:** Product header uses **`ExxatProductLogo`**; school **`logoDevUrl`** + **`lib/logo-dev`**; team switcher menu **`!w-max`** (not trigger-width-only); expanded switcher **`h-auto min-h-12`** so school + program lines are not clipped; no **`CollapsibleTrigger` → `SidebarMenuButton` with `tooltip` prop**; child nav uses **popover** on icon rail per **§3.1**
 - [ ] Hub pages: `ListPageTemplate` + `DataTable` + `useTableState` + `TablePropertiesDrawer`
-- [ ] Board view: `ListPageBoardCard` shell + `ListHubStatusBadge` + `list-status-badges` when applicable (`exxat-ds/AGENTS.md` §4.4)
-- [ ] New primary hubs: not placeholder-only — full template + data + views (`exxat-ds/AGENTS.md` §4.1)
+- [ ] Board view: `ListPageBoardCard` shell + `ListHubStatusBadge` + `list-status-badges` when applicable (`apps/web/AGENTS.md` §4.4)
+- [ ] New primary hubs: not placeholder-only — full template + data + views (`apps/web/AGENTS.md` §4.1)
 - [ ] **§6.4:** Parent **context** + quick view/actions → drawer/sheet; primary or long flows → **new page** (`AGENTS.md`, `docs/data-views-pattern.md`)
 - [ ] No raw `<table>` or `ui/table` for product data lists
 - [ ] No double horizontal padding around `DataTable`

package/consumer-extras/cursor-skills/exxat-ds-skill/references/data-table-pattern.md

@@ -1,6 +1,6 @@
 # Data Table Pattern — Full Implementation Guide
 
-Reference implementation: `components/team-table.tsx` (Team) and `components/data-list-table.tsx` (Placements).
+Reference implementation: `components/team-table.tsx` (Team) and `components/placements-table.tsx` (Placements).
 
 ---
 

package/consumer-extras/cursor-skills/exxat-primary-nav-secondary-panel/SKILL.md

@@ -12,7 +12,7 @@ user-invocable: true
 ## Wiring checklist
 
 1. **`lib/mock/navigation.tsx`** — set **`secondaryPanel: "<id>"`** on the primary **`NavLinkItem`**; **`url`** = hub route.
-2. **`components/secondary-panels/registry.tsx`** — add **`SECONDARY_PANELS["<id>"]`** → panel shell (title) + hub-specific nav component (e.g. **`list-hub-panel.tsx`**, **`question-bank-panel.tsx`**). Do not add new hubs inside **`question-bank-*.tsx`**.
+2. **`components/secondary-panel.tsx`** — add **`PANELS["<id>"]`** → panel shell (title, optional search) + secondary nav component.
 3. **Hub client** — mount **`*PanelActivator`** with **`useAutoPanel("<id>")`** (same id) for the lifetime of the route (e.g. `QuestionBankPanelActivator`).
 4. **Data** — keep **one** **`useTableState`** / **`tableState.rows`**; drive scope from **URL** + small helpers (see **`lib/question-bank-nav.ts`**).
 5. **Folder-scoped hub header (Question bank library)** — When **`scope === "folder"`** in the URL, **`QuestionBankPageHeader`** **⋯ More** includes **Customize folder**; mount **`QuestionBankNewFolderSheet`** on **`QuestionBankClient`** so it works on **all** **`ListPageTemplate`** view tabs — **`.cursor/rules/exxat-question-bank-hub-header.mdc`**, **`docs/question-bank-hub-header-pattern.md`**.
@@ -39,9 +39,7 @@ Custom panel content (anything you register under `PANELS[id]`) should **read `s
 ## Reference
 
 - `components/app-sidebar.tsx` — `openPanel` on same-route primary click.
-- `components/secondary-panel.tsx` — `SecondaryPanelProvider`, **high-zoom auto-collapse**.
-- `components/secondary-panels/registry.tsx` — **`SECONDARY_PANELS`** map (`question-bank`, `list-hub`, …).
-- `lib/list-hub-nav.ts` + `components/list-hub-secondary-nav.tsx` — second hub reference implementation.
+- `components/secondary-panel.tsx` — `SecondaryPanelProvider`, `PANELS` registry, **high-zoom auto-collapse**.
 - `hooks/use-sidebar-reflow-zoom.ts` — shared zoom / reflow signal.
 - `components/templates/nested-secondary-panel-shell.tsx` — expanded vs `compact` (icon rail) widths; **`bg-[var(--secondary-panel-bg)]`**.
 - `app/globals.css` — `--secondary-panel-bg`, `--sidebar`, product **`theme-one`** / **`theme-prism`** blocks.