@exxatdesignux/ui 0.2.19 → 0.4.0

package/consumer-extras/cursor-rules/exxat-ds-agents.mdc

@@ -0,0 +1,56 @@
+---
+description: Exxat DS — follow AGENTS.md; DataTable, ListPageTemplate, primary hubs, export, Kbd
+alwaysApply: true
+---
+
+# Exxat DS — AI handbook (binding)
+
+**App location:** `apps/web/` in this **pnpm monorepo**. The legacy single-folder layout (`exxat-ds/`) was migrated in 2026-05; the path no longer exists. Shared design system lives at `packages/ui/` (`@exxatdesignux/ui`).
+
+**Read `AGENTS.md`:** `apps/web/AGENTS.md` from the monorepo root, or `./AGENTS.md` when the workspace is the `apps/web/` folder only (same file).
+
+Before implementing or reviewing **list / table / board / dashboard / data-heavy** pages, read **AGENTS.md** (rule precedence, MUST/MUST NOT, file references, §4.1–§4.8, **§6.4** page vs drawer, **§6.5** no toast, §7.1 command palette, §13 checklist). **Before** adding **new shared UI** not covered by existing **`components/`** patterns, read **`exxat-reuse-before-custom.mdc`**.
+
+## Non‑negotiables (if anything conflicts, open AGENTS.md §12–§13)
+
+1. **Product data lists** → `DataTable` + search + shared filters + `TablePropertiesDrawer` — not raw `<table>` / ui `Table` alone / ad-hoc grids. With **`ListPageTemplate`** view tabs, pass **`currentView`** + **`onViewChange`** into **`TablePropertiesDrawer`** (**`AGENTS.md` §4.2**, **`.cursor/rules/exxat-table-properties-drawer.mdc`**).
+2. **Main `DataTable` surface** → wrapped in **`ListPageTemplate`** (view tabs). All tab view types share **`useTableState`**; list/board/dashboard read **`tableState.rows`**. Reference: `PlacementsClient`, `TeamClient`, `TeamTable`, `ComplianceClient`.
+3. **Do not double-indent** the toolbar/table — avoid extra `px`/`mx` wrappers around `DataTable` when it already applies horizontal inset.
+4. **Primary hub + large/complex data** → same composition as Placements/Team: `ListPageTemplate` + metrics/export pattern as in `PlacementsClient` / `TeamClient`, not `PageHeader`-only. **Do not** ship empty or "replace later" placeholder pages for nav-linked hubs (**`AGENTS.md` §4.1**).
+5. **Exportable pages** → filled primary CTA; **⋯** menu with Export → `ExportDrawer` pattern (see `PlacementsPageHeader`).
+6. **Keyboard hints** → `.cursor/rules/exxat-kbd-shortcuts.mdc`; pair hints with behavior.
+7. **Accessibility** → `.cursor/rules/exxat-accessibility.mdc` + **`apps/web/AGENTS.md` §8** + `.cursor/skills/exxat-accessibility/SKILL.md`.
+8. **Data view dashboard charts** → **`apps/web/AGENTS.md` §4.3** + **`apps/web/.cursor/rules/exxat-dashboard-view-charts.mdc`** (centralized storage, `chart-keyboard-selection`, `ChartFigure`).
+9. **Board (kanban) cards** → **`apps/web/AGENTS.md` §4.4** + **`exxat-board-cards.mdc`** + **`.cursor/skills/exxat-board-cards/SKILL.md`** (`ListPageBoardCard`, **`ListHubStatusBadge`** + **`lib/list-status-badges.ts`**, primitives).
+10. **List-page view shells** (folder / panel / centered non-table bodies) → **`apps/web/AGENTS.md` §4.5** + **`exxat-list-page-view-shells.mdc`** + **`.cursor/skills/exxat-list-page-view-shells/SKILL.md`** (`ListPageViewFrame`, **`components/data-views/`**).
+11. **Centralized hub dataset + presentation** — **`apps/web/AGENTS.md` §4.1** / **§4.5** + **`.cursor/rules/exxat-centralized-list-dataset.mdc`** + **`.cursor/skills/exxat-centralized-list-dataset/SKILL.md`** — one **`useTableState`** row bag for **all** views + **`TablePropertiesDrawer`**; **`ListPageViewFrame`** + **`data-views/`** for shared chrome; **no** parallel mock arrays per **`DataListViewType`**.
+12. **Font Awesome (product icons)** — **`.cursor/rules/exxat-fontawesome-icons.mdc`** — Kit in **`app/layout.tsx`**, **`fa-light` / `fa-solid`**, subset audit, **`aria-hidden`** on decorative **`<i>`**; pair with **`exxat-accessibility.mdc`** for icon-only controls.
+13. **Monospace system IDs** — **`apps/web/AGENTS.md` §1 (item 9)** + **`.cursor/rules/exxat-mono-ids.mdc`** + **`.cursor/skills/exxat-mono-ids/SKILL.md`** — **`font-mono tabular-nums`** on question/record keys; mono **only** the ID token in mixed lines.
+14. **Primary nav → secondary panel** (Library) — **`apps/web/AGENTS.md` §4.6** + **`.cursor/rules/exxat-primary-nav-secondary-panel.mdc`** — **`secondaryPanel`** + **`PANELS`** + **`useAutoPanel`**; **`--secondary-panel-bg`** brand elevation (**`apps/web/docs/shell-surface-elevation-pattern.md`**); **folder URL scope** → **`exxat-library-hub-header.mdc`** + **`apps/web/docs/library-hub-header-pattern.md`**.
+15. **Collaboration & access** (shared hubs) — **`apps/web/AGENTS.md` §4.7** + **`.cursor/rules/exxat-collaboration-access.mdc`** + **`.cursor/skills/exxat-collaboration-access/SKILL.md`** — face rail, **`InviteCollaboratorsDrawer`**, **`lib/collaborator-access.ts`**.
+16. **Dedicated search** (landing vs results, `DedicatedSearch*`) — **`apps/web/AGENTS.md` §4.8** + **`.cursor/rules/exxat-dedicated-search-surfaces.mdc`** + **`.cursor/skills/exxat-dedicated-search-surfaces/SKILL.md`**.
+17. **No toast** → **`apps/web/AGENTS.md` §6.5** + **`exxat-no-toast.mdc`** — do not use **`toast()`** / Sonner / snackbars for product messaging; use banners, inline status, or dialogs.
+18. **KPI trend polarity** (`KeyMetrics`, `*-kpi.ts`, chart mini-metrics) — **`docs/kpi-trend-pattern.md`** + **`.cursor/rules/exxat-kpi-trends.mdc`** + **`.cursor/skills/exxat-kpi-trends/SKILL.md`** — **`trend`** follows the data; set **`trendPolarity`** when “up” is not good news (e.g. defect counts, **low PBI flags**).
+19. **Drawer vs dialog** (same-route overlays) — **`docs/drawer-vs-dialog-pattern.md`** + **`.cursor/rules/exxat-drawer-vs-dialog.mdc`** + **`.cursor/skills/exxat-drawer-vs-dialog/SKILL.md`** — drawers preserve hub context; dialogs for **blocking** short confirms.
+20. **Cards vs table rows** — **`docs/card-vs-rows-pattern.md`** + **`.cursor/rules/exxat-card-vs-list-rows.mdc`** + **`.cursor/skills/exxat-card-vs-list-rows/SKILL.md`** — **`DataTable`** for dense comparable hubs; cards for kanban / visual browse (**`ListPageBoardCard`**).
+21. **KPI strip max four** — **`docs/kpi-strip-max-four-pattern.md`** + **`.cursor/rules/exxat-kpi-max-four.mdc`** + **`.cursor/skills/exxat-kpi-max-four/SKILL.md`** — **≤ 4** `MetricItem` per primary **`KeyMetrics`** strip / Data-tab key-metrics card (**`KEY_METRICS_KPI_COUNT_MAX`**).
+22. **KPI flat band** — **`docs/kpi-flat-band-pattern.md`** + **`.cursor/rules/exxat-kpi-flat-band.mdc`** + **`.cursor/skills/exxat-kpi-flat-band/SKILL.md`** — **`variant="flat"`**: transparent cells, OKLCH brand glow only, border hairlines (no grey panel).
+23. **Reuse before custom** — **`exxat-reuse-before-custom.mdc`** — compose from **`components/`** + **`AGENTS.md` §9**; **ask the user** before new shared primitives or bespoke widgets unless the task already approved greenfield.
+24. **Token discipline** — **`docs/token-taxonomy.md`** + **`.cursor/rules/exxat-token-discipline.mdc`** + **`packages/ui/tokens/hooks-index.json`** (163 tokens · 36 namespaces) — no hex literals in app code; no deprecated tokens; **prefer Exxat L0** (`--exxat-color-*`, `--exxat-radius-*`, `--exxat-spacing-*`) for new code (taxonomy §2.0 · rollout `docs/migrations/0002-exxat-token-namespace.md`); legacy L1 shadcn names stay as aliases. ESLint enforces via `exxat-ds/no-hex-color` + `exxat-ds/no-deprecated-tokens` in **`@exxatdesignux/eslint-plugin`** (workspace: **`packages/eslint-plugin-exxat-ds/`**).
+25. **No SLDS leakage** — **`.cursor/rules/exxat-no-slds-leakage.mdc`** — no `slds-*` classes, no `<lightning-*>` markup, no SLDS token names, no synthetic-shadow assumptions. ESLint catches via `exxat-ds/no-slds-classes` + `exxat-ds/no-lightning-elements` (from **`@exxatdesignux/eslint-plugin`**).
+26. **Blueprints + selection guide** — **`apps/web/docs/blueprints/`** + **`apps/web/docs/component-selection-guide.md`** — framework-agnostic specs + decision tree across the whole DS. Start there before composing a new hub.
+27. **Migrations** — **`apps/web/docs/migrations/`** — every deprecation gets a numbered entry (`NNNN-<slug>.md`). Token deprecations surface in `tokens/hooks-index.json` as `deprecated: true` and are lint-flagged.
+
+## Also read
+
+- **`apps/web/docs/data-views-pattern.md`** — architecture narrative for list hubs. Includes **Page vs drawer** (§6.4 in `AGENTS.md`), **board UI** (§4.4), and **KPI trend polarity** → **`apps/web/docs/kpi-trend-pattern.md`**.
+- **`apps/web/docs/command-menu-pattern.md`** — global ⌘K palette (search + quick AI vs Ask Leo).
+- **`apps/web/docs/token-taxonomy.md`** — naming + deprecation policy for every CSS custom property the DS ships (semantic shadcn + brand / chip / chart / interactive / sidebar / control / radius / shadow / transition families).
+- **`apps/web/docs/component-selection-guide.md`** — top-of-funnel decision tree for picking the right composition.
+- **`apps/web/docs/blueprints/`** — framework-agnostic specs (start: `page-header.md`, `data-table.md`).
+- **`apps/web/docs/migrations/`** — token rename + removal history.
+- **`packages/ui/tokens/hooks-index.json`** — machine-readable token index (regenerate via `pnpm --filter @exxatdesignux/ui tokens:index`).
+- `.cursor/rules/exxat-data-tables.mdc`, `exxat-list-page-connected-views.mdc`, **`exxat-centralized-list-dataset.mdc`**, **`exxat-list-page-view-shells.mdc`**, **`exxat-fontawesome-icons.mdc`**, **`exxat-mono-ids.mdc`**, **`exxat-primary-nav-secondary-panel.mdc`**, **`exxat-library-hub-header.mdc`**, **`exxat-collaboration-access.mdc`**, **`exxat-dedicated-search-surfaces.mdc`**, **`exxat-kpi-trends.mdc`**, **`exxat-kpi-flat-band.mdc`**, **`exxat-drawer-vs-dialog.mdc`**, **`exxat-card-vs-list-rows.mdc`**, **`exxat-kpi-max-four.mdc`**, **`exxat-reuse-before-custom.mdc`**, `exxat-table-properties-drawer.mdc`, **`exxat-board-cards.mdc`**, **`exxat-page-vs-drawer.mdc`**, **`exxat-no-toast.mdc`**, **`exxat-command-menu.mdc`**, `exxat-kbd-shortcuts.mdc`, `exxat-accessibility.mdc` at repo root; **`apps/web/.cursor/rules/exxat-dashboard-view-charts.mdc`** for Data tab charts.
+- **`apps/web/docs/kpi-flat-band-pattern.md`**, **`apps/web/docs/shell-surface-elevation-pattern.md`** — flat KPI strip + sidebar/secondary/page OKLCH stack.
+- **`apps/web/docs/library-hub-header-pattern.md`** — folder-scoped library header **Customize folder**.
+- **`apps/web/docs/collaboration-access-pattern.md`** — shared hub face rail + invite sheet.

package/consumer-extras/cursor-rules/exxat-fontawesome-icons.mdc

@@ -0,0 +1,31 @@
+---
+description: Font Awesome Pro icons — kit, weights, markup, subset audit, accessibility pairing
+globs: apps/web/**/*.tsx
+alwaysApply: false
+---
+
+# Exxat DS — Font Awesome icons
+
+Product UI uses **Font Awesome 6 Pro** via the **Kit script** in **`apps/web/app/layout.tsx`** (not per-page ad-hoc CDNs). **Authoritative accessibility pairing** for decorative vs informational vs icon-only controls: **`.cursor/rules/exxat-accessibility.mdc`** (Case A/B/C).
+
+## MUST
+
+1. **Markup** — Use **`<i className="…" />`** with **`fa-*`** weight + icon classes (e.g. **`fa-light fa-folder`**, **`fa-solid fa-check`**). Put **`aria-hidden="true"`** on the **`<i>`** when the **accessible name** lives on a parent (**`Button` `aria-label`**, adjacent text, **`Tip`** on interactive controls).
+2. **Weights** — Default inactive/ambient icons to **`fa-light`**; use **`fa-solid`** for **selected / active / strong emphasis** when the pattern already exists (e.g. sidebar rows, view tabs). Stay consistent within a surface.
+3. **Class strings** — Prefer **static** `className` strings so **`pnpm --filter web fa:subset-audit`** (see **`apps/web/scripts/fontawesome-subset-audit.mjs`**) can discover glyphs for **Kit subsetting** (`fontawesome-subset.manifest.json` → [fontawesome.com/kits](https://fontawesome.com/kits) Icon Selection).
+4. **Props APIs** — When a component accepts an icon, document **suffix only** (`fa-folder`) or **full classes** consistently with nearby code (**`lib/data-list-view.ts`**, **`lib/list-status-badges.ts`**, **`os-folder-glyph.tsx`**).
+
+## SHOULD
+
+- After adding **new** Font Awesome glyph names, run **`fa:subset-audit`** and refresh the **Kit** subset so production does not 404 missing icons.
+- Reuse **shared** maps (**`DATA_LIST_VIEW_TILES`**, **`lib/list-status-badges.ts`**) instead of one-off **`fa-*`** strings for the same semantic concept.
+
+## MUST NOT
+
+- Add **second** icon systems for **product chrome** (duplicate Lucide/Phosphor/Heroicons for the same nav, table toolbar, or hub cards) when Font Awesome is already the standard for that surface.
+- Put **meaningful** accessible names **only** on **`<i>`** without **`role`** / parent labelling — follow **Case B/C** in **`exxat-accessibility.mdc`**.
+
+## See also
+
+- **`apps/web/AGENTS.md`** — handbook; **§8** accessibility.
+- **`.cursor/rules/exxat-accessibility.mdc`** — tooltips + **`aria-label`** for icon-only buttons.

package/consumer-extras/cursor-rules/exxat-kbd-shortcuts.mdc

@@ -0,0 +1,100 @@
+---
+description: Exxat DS — show Kbd hints on primary/secondary actions, search, Ask Leo; avoid browser-reserved chords.
+alwaysApply: true
+---
+
+# Exxat DS — keyboard shortcuts (`Kbd`)
+
+## When to show `Kbd`
+
+Use `@/components/ui/kbd` (`Kbd` + `KbdGroup`) anywhere users discover actions by hovering or reading tooltips:
+
+- **Primary actions** — main page CTAs (e.g. “New …”, “Save”, “Submit”).
+- **Secondary actions** — overflow menus, “More”, outline companions to a primary button.
+- **Global affordances** — **Search** (table toolbar), **Ask Leo**, **Toggle sidebar**.
+
+## Rules
+
+0. **`Kbd` variant MUST match its host surface** (this is the #1 recurring mistake):
+
+   | Where the `Kbd` renders | Required variant |
+   |-------------------------|------------------|
+   | Inside a `Button` (primary, secondary, wizard Next/Back/Submit, full-width CTAs in popovers) | **`variant="bare"`** — no bg/border, inherits `currentColor` @ 70 % |
+   | Inside a `TooltipContent` | **default `tile`** (no prop) |
+   | Inside a `DropdownMenuItem` via `shortcut=` | menu handles it — pass the chord string |
+   | Standalone helper text on a surface | **default `tile`** |
+
+   Glue multi-key chords into **one** bare kbd (`<Kbd variant="bare">⌘⌥K</Kbd>`), not one tile per key. See `new-placement-form.tsx` (Next = `{mod}⏎`, Back = `{mod}{alt}←`) and the primary "Ask Leo" button inside chart insight popovers.
+
+1. **Pair hint with behavior** — If `Kbd` shows a chord, implement the same shortcut. **Preferred:** the shared primitives from `@/components/ui/dropdown-menu`:
+
+    ```tsx
+    import { DropdownMenuItem, Shortcut } from "@/components/ui/dropdown-menu"
+
+    // Visual hint in a menu item:
+    <DropdownMenuItem shortcut="⌘⇧E" onSelect={onExport}>Export</DropdownMenuItem>
+
+    // Global binding — render in a parent that stays mounted (menu items unmount on close):
+    <Shortcut keys="⌘⇧E" onInvoke={onExport} />
+    ```
+
+    The hook skips input/textarea/contenteditable targets and any open dialog. Accepts symbols (`⌘⇧⌥⌃⌫⌦⏎↑↓`) and words (`Cmd+Shift+D`, `Alt+P`). Avoid ad-hoc `document.addEventListener("keydown", …)` + `isEditableTarget` — use `<Shortcut>` instead.
+2. **Modifier labels** — Use `useModKeyLabel()` (**⌘** / **Ctrl**) and `useAltKeyLabel()` (**⌥** / **Alt**) from `@/hooks/use-mod-key-label` for tooltips.
+3. **Avoid browser-reserved chords** — Do **not** use combinations that match common browser defaults, including:
+   - **⌘⇧N / Ctrl+Shift+N** — private/incognito window
+   - **⌘⇧T / Ctrl+Shift+T** — reopen closed tab
+   - **⌘⇧O / Ctrl+Shift+O** — bookmark manager (Chromium)
+   - **⌘⇧B / Ctrl+Shift+B** — bookmarks bar
+   - **⌘L / Ctrl+L** — focus address bar (avoid plain **L** with only mod unless scoped)
+   - **⌃⌥L / Ctrl+Alt+L** — screen lock on many Linux desktops (avoid for in-app actions)
+4. **Preferred pattern for app shortcuts** — Use **⌘⌥** / **Ctrl+Alt** + letter (e.g. **⌘⌥N** for “New”, **⌘⌥M** for “More”, **⌘⌥K** for Ask Leo). Table search stays **⌘K** / **Ctrl+K** **without** Alt so **⌘⌥K** does not collide.
+5. **Tooltips** — `Tip` supports `label` as `React.ReactNode` so you can compose text + `KbdGroup`.
+6. **Do not** decorate every control — skip dense tables, icon-only row actions that already have `aria-label`, and third-party widgets.
+
+## Reference shortcuts (app)
+
+| Action | Shortcut |
+|--------|----------|
+| Toggle main sidebar | ⌘/Ctrl + **B** (`components/ui/sidebar.tsx`) |
+| Table search | ⌘/Ctrl + **K** (no Alt — `DataTable`) |
+| Ask Leo | ⌘/Ctrl + **⌥/Alt** + **K** |
+| New placement (Placements header) | ⌘/Ctrl + **⌥/Alt** + **N** |
+| Placements overflow menu | ⌘/Ctrl + **⌥/Alt** + **M** |
+| Export | ⌘/Ctrl + **⇧/Shift** + **E** |
+| Hide/Show metric section | ⌘/Ctrl + **⌥/Alt** + **H** |
+| Rename (view, tab) | **F2** |
+| Duplicate | ⌘/Ctrl + **D** |
+| Review / Info | ⌘/Ctrl + **I** |
+| Remove / Delete | ⌘/Ctrl + **⌫** |
+| Add view (1..n) | **1..9** (plain digit; skipped in inputs / open dialogs) |
+| **Submit a workflow** (Create, Save, Export, Apply) | **Enter** (⏎) — scoped to the form/drawer/dialog |
+| **Cancel / dismiss** a workflow | **Esc** (Radix handles for Dialog/Sheet) |
+| **Advance a multi-step wizard** | ⌘/Ctrl + **Enter** (plain Enter stays in the input) |
+| **Back** in a wizard | ⌘/Ctrl + **⌥/Alt** + **←** |
+
+## Every workflow primary/secondary action MUST carry shortcuts
+
+Every **workflow surface** (form, dialog, drawer, sheet, multi-step wizard final step) MUST bind:
+
+1. **Primary action (submit/commit)** — **Enter** (⏎). Render the `<Kbd>⏎</Kbd>` **inline inside the button** (after the label, inside a `<KbdGroup className="ml-1.5">`) — NOT inside a hover `Tip`. Primary/secondary workflow buttons must expose the shortcut at rest so it is discoverable without hovering. Pair with a `<Shortcut keys="Enter" onInvoke={...}>` mounted while the surface is open. The shared `useShortcut` hook skips events from inputs/textarea/contenteditable, so Enter inside a text field still types normally — it only fires when focus is on the surface chrome.
+2. **Secondary action (Cancel/Dismiss)** — **Esc**. Inline `<Kbd>Esc</Kbd>` inside the Cancel button (same `ml-1.5` pattern). Radix `Dialog` / `Sheet` / `AlertDialog` already bind Esc natively.
+
+> Tip-on-hover Kbd hints remain correct for **page-level** actions (e.g. "New placement", ⋯ overflow triggers) where the button is part of dense page chrome and a persistent Kbd would crowd the layout. Workflow buttons inside a form/drawer/dialog are spacious enough to render the Kbd inline.
+
+**Variant inside a button:** always use `<Kbd variant="bare">` — no background, no border, inherits `currentColor` at 70% opacity. The default tile variant looks like a pasted-on patch on filled primary buttons. Glue multi-key chords into one `<Kbd variant="bare">⌘⌥←</Kbd>` rather than one tile per key.
+3. **Multi-step wizards** — plain **Enter** must NOT submit on intermediate steps (it would auto-close the review/final step when users hit Enter inside an input). Either:
+   - Gate `form.onSubmit` on `step === lastStep` (`if (step !== N) { e.preventDefault(); return }`), **or**
+   - Remove `type="submit"` on intermediate Next buttons and bind **⌘Enter** to "Next" via `<Shortcut>`.
+   On the final step, plain **Enter** submits and the Kbd hint shows **⏎**.
+4. Examples in-app: `new-placement-form.tsx` (Create placement = Enter on step 5, Back = ⌘⌥←), `export-drawer.tsx` (Export = Enter, Cancel = Esc).
+
+## Every action menu MUST carry shortcuts
+
+All dropdown action menus (⋯ overflow, view-settings chevron, Add view, row actions) should declare a `shortcut=` on each `DropdownMenuItem` AND pair it with a `<Shortcut>` in a parent that stays mounted. This covers both discoverability (visual hint) and operability (global key binding).
+
+Adjust this table when adding new global shortcuts.
+
+## See also
+
+- **`apps/web/AGENTS.md`** §7 — keyboard rules in project context.
+- **`apps/web/AGENTS.md`** §7.1 — global command palette (⌘K) vs **Ask Leo** (**⌘⌥K**); **`apps/web/docs/command-menu-pattern.md`**.

package/consumer-extras/cursor-rules/exxat-kpi-flat-band.mdc

@@ -0,0 +1,28 @@
+---
+description: KeyMetrics variant flat — transparent band, brand glow only, OKLCH hairlines
+globs: apps/web/components/**/*key-metrics*,apps/web/app/globals.css,apps/web/docs/kpi*.md
+alwaysApply: false
+---
+
+# Exxat DS — KPI flat band (`variant="flat"`)
+
+**Authoritative detail:** **`apps/web/docs/kpi-flat-band-pattern.md`**, **`.cursor/skills/exxat-kpi-flat-band/SKILL.md`**.
+
+## MUST
+
+1. **`KeyMetrics variant="flat"`** on list hubs / dashboard mix — **no** opaque band surface; section background is **only** `--key-metrics-flat-band-radial` (brand glow).
+2. **Cells** — **`bg-transparent`**; hairlines via **`flatMetricsHairlineClass`** (cell **borders**, not `gap-px` grid fill).
+3. **Four tiles** — default **4-across** verticals between columns; **2×2** hairlines only when `@container` is narrow (`@[max-width:29.99rem]`). **No** horizontal rule in 4-across layout.
+4. **OKLCH** — `--key-metrics-flat-divider`, glow stops via `color-mix(in oklch, var(--brand-color) …)`; divider uses `var(--sidebar-border)` mix. **Do not** hardcode rose/indigo on one product for all themes.
+5. **`--key-metrics-flat-band-shadow: none`** on flat band. **≤ 4** tiles — **`exxat-kpi-max-four.mdc`**.
+
+## MUST NOT
+
+- Stack linear gradients, `bg-background` on cells, or `gap-px` + tinted grid background on flat KPI (reads as a grey/lavender **box**).
+- Use **`variant="card"`** for **`ListPageTemplate`** metrics when the strip should sit on the page canvas.
+- Reintroduce **`lg:border-l`** on insight column when `variant="flat"` (insight card ring is enough).
+
+## See also
+
+- **`exxat-kpi-max-four.mdc`**, **`exxat-kpi-trends.mdc`**, **`exxat-list-page-connected-views.mdc`**
+- **`exxat-primary-nav-secondary-panel.mdc`** — shell elevation (separate from KPI band)

package/consumer-extras/cursor-rules/exxat-kpi-max-four.mdc

@@ -0,0 +1,21 @@
+---
+description: Exxat DS — at most four KPI tiles on primary hub strips and key-metrics dashboard cards.
+alwaysApply: true
+---
+
+# Exxat DS — KPI strip (max four)
+
+## MUST
+
+1. **Cap visible KPIs at four** on **`ListPageTemplate`** metric strips and on **Data tab** **`key-metrics`** dashboard cards — align with **`KEY_METRICS_KPI_COUNT_MAX`** in **`lib/dashboard-layout-merge.ts`** and **`clampKeyMetricsKpiCount`** when persisting layout.
+2. **KPI helpers** (`*-kpi.ts`) return **≤ 4** `MetricItem` entries for those surfaces, or **`.slice(0, 4)`** after prioritization.
+3. **Overflow narrative** — Push secondary stats into **`MetricInsight`**, charts, or another section — not a fifth headline tile.
+
+## MUST NOT
+
+- Render **five or more** KPI tiles in a single **`KeyMetrics`** row/band meant as the **primary** summary for a hub or the **key-metrics** card.
+- Raise **`KEY_METRICS_KPI_COUNT_MAX`** without design-system review.
+
+## See also
+
+- **`docs/kpi-strip-max-four-pattern.md`** · **`docs/kpi-trend-pattern.md`** · **`docs/kpi-flat-band-pattern.md`** · **`.cursor/skills/exxat-kpi-max-four/SKILL.md`**

package/consumer-extras/cursor-rules/exxat-kpi-trends.mdc

@@ -0,0 +1,31 @@
+---
+description: Exxat DS — KPI deltas and trend arrows must be contextual; use trendPolarity when “up” is not good news.
+alwaysApply: true
+---
+
+# Exxat DS — KPI trends (`KeyMetrics` + chart mini-metrics)
+
+## MUST
+
+1. **`trend` matches reality** — `up` / `down` / `neutral` reflects the **signed change** in the metric; arrows are not “spin for optimism”.
+2. **Set `trendPolarity` on `MetricItem`** when an increase is **not** favorable:
+   - **`lower_is_better`** — defect / error / overdue / **low PBI or quality-flag counts**, cost or time when the product goal is to **reduce**.
+   - **`informational`** — volume or mix where **direction is not** inherently good or bad (library size, % split between categories); tints stay **muted**, arrows still show direction.
+3. **Default** — Omitting `trendPolarity` means **`higher_is_better`** (legacy): up = positive tint, down = negative tint.
+4. **`delta` is a count, `description` is a caption.** **`delta`** (next to the arrow) is a **numeric change** like `"+5"`, `"-3"`, `"+12%"`. Contextual prose like `"left + right"`, `"vs last week"`, `"across 4 sites"` goes in **`MetricItem.description`** which renders **below** the value row (muted, small). **MUST NOT** stuff prose into **`delta`**.
+5. **Hide the trend chip when there is nothing to say.** If **`trend === "neutral"`** **and** **`delta`** is empty (`""` / `0` / unset), `KeyMetrics` suppresses the chip entirely — no `—` placeholder. Use **`description`** for the supporting caption instead. Only show the chip when the metric has a real direction (`up` / `down`) or a real count to surface.
+6. **Contextual copy** — `label` + `value` + (`delta` when present) + period header should read as one sentence; avoid orphan deltas.
+7. **Accessibility** — Do not rely on colour alone; keep delta text + icon; chip `aria-label` comes from **`metricTrendAriaQualifier`** in **`components/key-metrics.tsx`**.
+
+## MUST NOT
+
+- Paint an **up** arrow with the “good” tint when the metric is **worse** when it goes up (unless **`trendPolarity: "lower_is_better"`** is set so “up” correctly tints **destructive**).
+- Use **`ResizeObserver`** or JS layout measurement **only** to pick trend colours — polarity is a **product** decision, not a layout one.
+- Render an **empty `—`** trend chip just to keep the layout symmetric. If a metric has no comparison this period, leave **`delta`** empty and let **`KeyMetrics`** hide the chip.
+- Put words like **"left + right"**, **"hidden"**, **"shown"**, **"vs last week"** in **`delta`** — they are not deltas. Put them in **`description`**.
+
+## See also
+
+- **`docs/kpi-trend-pattern.md`** (app) — narrative + table of examples.
+- **`.cursor/skills/exxat-kpi-trends/SKILL.md`** — checklist for new hubs.
+- **`components/key-metrics.tsx`** — `MetricTrendPolarity`, `metricTrendTone`, `metricTrendAriaQualifier`.

package/consumer-extras/cursor-rules/exxat-library-hub-header.mdc

@@ -0,0 +1,28 @@
+---
+description: Library library — folder-scoped hub header More menu must expose Customize folder; sheet on hub client
+globs: apps/web/components/library-*.tsx, packages/ui/template/components/library-*.tsx
+alwaysApply: false
+---
+
+# Exxat DS — Library hub header (folder scope)
+
+When the library library URL is **scoped to a folder** (`parseLibraryNav` → **`scope === "folder"`** and **`folderId`** set), users are effectively on a **“folder page”**: the hub title matches that folder, and **global** actions belong in the **`LibraryPageHeader`** **⋯ More** menu — not only on per-row or per-tile overflow menus inside a single view tab.
+
+**Pattern doc:** **`apps/web/docs/library-hub-header-pattern.md`**. **Handbook:** **`apps/web/AGENTS.md` §4.6** (folder-scoped hub chrome).
+
+## MUST
+
+1. **`LibraryPageHeader`** — 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 **`LibraryNewFolderSheet`** on the **hub client** (e.g. **`LibraryClient`**) next to **`ListPageTemplate`**, driven by local **`open` / `customizingFolder`** state opened from **`onCustomizeFolder`**. **MUST NOT** rely on **`LibraryTable`** 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 **`LibraryTable`** 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 **`LibraryTable`** 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/library-nav.ts`** — **`parseLibraryNav`**, **`LibraryNavState`**.

package/consumer-extras/cursor-rules/exxat-list-page-connected-views.mdc

@@ -0,0 +1,24 @@
+---
+description: ListPageTemplate — shared table state across views, mock + KPI helpers, dashboard tab
+alwaysApply: true
+---
+
+# 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).
+
+## 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`**.

package/consumer-extras/cursor-rules/exxat-list-page-view-shells.mdc

@@ -0,0 +1,31 @@
+---
+description: Exxat DS — centered reusable shells for list-page views (not page-specific markup)
+globs: apps/web/components/**/*.tsx
+alwaysApply: false
+---
+
+# 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/consumer-extras/cursor-rules/exxat-mono-ids.mdc

@@ -0,0 +1,30 @@
+---
+description: Exxat DS — monospace typography for record IDs, question IDs, and other system identifiers
+globs: apps/web/**/*.tsx
+alwaysApply: false
+---
+
+# Exxat DS — monospace IDs
+
+Use this when rendering **system identifiers** — values a user copies, searches, or matches in APIs and tables (not human-readable names or prose).
+
+## MUST
+
+1. **Class** — Wrap identifier text in **`font-mono tabular-nums`**. Add size/color from context: typically **`text-xs text-muted-foreground`** (secondary line, table meta) or **`text-sm`** when the ID is the primary label in a narrow cell.
+2. **What counts as an ID** — Question IDs (`questionId`, `Q-YYMM-XXXX`), record/entity keys shown in UI, folder/surface technical keys when displayed as identifiers, hex tokens in pickers, audit/log principals, site/row **`id`** columns meant for lookup.
+3. **Mixed lines** — When an ID sits beside prose (e.g. page subtitle), only the ID segment is mono; keep separators and labels in the default sans stack.
+
+## SHOULD
+
+- Match existing hubs: **`library-table.tsx`**, **`library-list-view.tsx`**, **`new-library-item-form.tsx`** (header subtitle), **`sites-table.tsx`** (`row.id`).
+- Prefer **`truncate`** / **`min-w-0`** on mono IDs in tight layouts so long tokens do not blow out columns.
+
+## MUST NOT
+
+- Apply **`font-mono`** to **person names**, **folder display names**, **status labels**, **dates**, **counts**, **currency**, or **body copy** — only the identifier token.
+- Use mono for **option letters** (A/B/C) or **step numbers** unless they are literal system IDs.
+
+## See also
+
+- **`.cursor/skills/exxat-mono-ids/SKILL.md`**
+- **`apps/web/AGENTS.md`** — §1 item on IDs, §13 checklist

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

@@ -0,0 +1,78 @@
+# 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/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:** `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.