@exxatdesignux/ui 0.5.11 → 0.5.13

package/template-vite/.cursor/skills/exxat-accessibility/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: exxat-accessibility
+description: WCAG 2.x / ARIA checklist for Exxat DS — tablists, touch targets, contrast, and audit follow-ups. Use when fixing axe/Deque issues, building nav or tab UIs, or reviewing accessibility.
+user-invocable: true
+---
+
+# Exxat DS — accessibility checklist
+
+Standard target: **WCAG 2.1 Level AA** (and 2.2 where noted).
+
+**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)
+
+- **`role="tablist"`** may only contain **`role="tab"`** (or elements that resolve to tabs). Do **not** place `role="button"`, menus (`aria-haspopup`), or ad-hoc controls **inside** the same `tablist` container.
+- **Composite view switchers** (tabs + per-tab settings menu + remove control): use **`role="toolbar"`** with **`aria-label`**, and **`aria-pressed`** on view toggle buttons instead of misusing `tab`/`tablist`.
+- Prefer **`<button type="button">`** over **`span role="button"`** for clickable icons (keyboard + AT).
+
+## Touch targets (WCAG 2.2 AA — 2.5.8 Target Size Minimum)
+
+- Interactive controls (including icon-only chevrons and close icons) should be at least **24×24 CSS pixels**, or have **24px** spacing so their **24px** hit circles do not overlap adjacent targets.
+- Use **`min-h-6 min-w-6`** (or `size-6`) with centered icons; avoid `size-4` (16px) for sole click targets.
+
+## Icons that communicate information — always have a text alternative (SC 1.1.1, 3.3.2, 2.4.6)
+
+This rule covers **every icon that carries meaning**, not only icon-only buttons. FA glyphs, inline SVGs, avatar placeholders, trend arrows, status dots, chart-legend squares, calendar/clock/pin icons in cells — if the icon **tells the user something**, that something MUST be reachable by screen readers AND discoverable to sighted users who don't recognise the glyph.
+
+There are three cases. Pick the one that matches the icon's context:
+
+### Case A — Decorative icon next to text that already names it
+
+When the icon sits adjacent to a visible text label that already carries the meaning, the icon is **decorative**. It MUST be `aria-hidden` and MUST NOT carry `aria-label` (screen readers would announce the meaning twice).
+
+```tsx
+<span className="flex items-center gap-1.5">
+  <i className="fa-light fa-calendar-days" aria-hidden />
+  <span>12/14/2025 – 12/20/2025</span>
+</span>
+
+<Button>
+  <i className="fa-light fa-plus" aria-hidden />
+  <span>New placement</span>
+</Button>
+```
+
+No tooltip needed — the text is the alt. This is the default in table cells, buttons with text labels, breadcrumbs, badges, menu items.
+
+### Case B — Informational icon standing alone (no adjacent label)
+
+When the icon is the **only visible carrier** of the information — e.g.:
+
+- `fa-calendar-days` in a compact table column header meaning "date range"
+- `fa-clock` meaning "updated at" or "time remaining"
+- `fa-location-dot` meaning "site" / "location"
+- `fa-graduation-cap` meaning "student"
+- trending arrow in a KPI card (↑ / ↓)
+- status dot (a coloured circle meaning "on track / at risk / blocked")
+- icon-only legend key on a chart
+- `fa-paperclip` meaning "has attachments"
+- `fa-lock` meaning "restricted"
+
+…the icon MUST:
+
+1. Announce itself to AT via **`role="img"` + `aria-label`** on a wrapping element (span/div), OR inherit the name from a labelled ancestor via `aria-labelledby`.
+2. Expose a visible **`Tooltip`** so sighted mouse/keyboard users who don't recognise the glyph learn the meaning.
+
+```tsx
+<Tooltip>
+  <TooltipTrigger asChild>
+    {/* Non-interactive: wrap in a span with role="img".
+        tabIndex={0} so the tooltip opens on keyboard focus, not just hover. */}
+    <span
+      role="img"
+      aria-label="Placement date range"
+      tabIndex={0}
+      className="inline-flex size-6 items-center justify-center rounded-md text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+    >
+      <i className="fa-light fa-calendar-days" aria-hidden />
+    </span>
+  </TooltipTrigger>
+  <TooltipContent side="top">Placement date range</TooltipContent>
+</Tooltip>
+```
+
+Rules:
+1. `TooltipContent` text MUST match the `aria-label`.
+2. The inner `<i>` / `<svg>` is always `aria-hidden`; the accessible name lives on the wrapper.
+3. If a visible text label could fit, **prefer Case A** (add the label) over tooltip-only.
+4. Target/focus size still **≥ 24×24 CSS px** so keyboard users can focus the icon reliably.
+5. Status dots MUST additionally carry a **text or shape cue** (not colour alone — SC 1.4.1). E.g. pair a coloured dot with a status label nearby, or differentiate by icon shape (`circle-check` vs `triangle-exclamation` vs `circle-xmark`).
+
+### Case C — Interactive icon-only button / link
+
+Any button or link whose visible content is a **single icon** — close (`×`), chevron, overflow (`⋯`), sort direction, filter chip dismiss, copy-to-clipboard, Ask Leo toggle, expand/collapse, row actions — MUST carry BOTH:
+
+1. **`aria-label`** on the `<button>` / `<a>` (programmatic name for AT and axe).
+2. A wrapping **`Tooltip`** whose content repeats the same name (plus a `Kbd` when a shortcut exists).
+
+```tsx
+import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/ui/tooltip"
+import { Kbd } from "@/components/ui/kbd"
+
+<Tooltip>
+  <TooltipTrigger asChild>
+    <button
+      type="button"
+      aria-label="Close insight"
+      onClick={onClose}
+      className="inline-flex size-7 min-h-7 min-w-7 items-center justify-center rounded-md …"
+    >
+      <i className="fa-solid fa-xmark" aria-hidden />
+    </button>
+  </TooltipTrigger>
+  <TooltipContent side="top" className="flex items-center gap-1.5">
+    <span>Close</span>
+    <Kbd>Esc</Kbd>
+  </TooltipContent>
+</Tooltip>
+```
+
+Rules:
+1. `TooltipContent` MUST match or extend the `aria-label`.
+2. Inside the tooltip use the **default tile** `<Kbd>` (NOT `variant="bare"`).
+3. The inner `<i>` / `<svg>` MUST have `aria-hidden`.
+4. Click target **≥ 24×24 CSS px** (see Touch targets section).
+
+### Narrow exceptions (all cases)
+
+- A chevron inside a labelled composite (`Select`, `Combobox`, `Breadcrumb` separator) where the parent already names the whole control or the glyph is purely structural — mark it `aria-hidden`.
+- Drag handles inside a `dnd-kit` listener that reference a labelled ancestor via `aria-describedby`.
+- Decorative icons that purely decorate (e.g. the Leo star next to an already-named "Ask Leo" button) — `aria-hidden`, no tooltip.
+
+### Decision tree
+
+```
+Icon appears somewhere →
+  Is there adjacent visible text that already names the meaning?
+    YES → Case A: aria-hidden, no tooltip. Done.
+    NO  → Is the icon the visible content of a button/link?
+            YES → Case C: aria-label on the control + Tooltip.
+            NO  → Case B: span[role="img", aria-label, tabIndex=0] + Tooltip.
+```
+
+**When in doubt: add the accessible name + tooltip.** Silence is never correct for an icon that means something.
+
+## Keyboard shortcuts inside buttons — `<Kbd variant="bare">` only
+
+The `Kbd` primitive (`@/components/ui/kbd`) has two variants:
+
+| Variant | Where it goes | Chrome |
+|---------|---------------|--------|
+| `tile` (default) | Inside `TooltipContent`, menu `shortcut=` slots, standalone surfaces | Background + border, fixed contrast |
+| `bare` | Inline **inside** a `Button` (primary, secondary, wizard Next/Back/Submit) | No background, no border, inherits `currentColor` at 70 % opacity |
+
+Inside a filled/solid button the `tile` variant looks like a pasted-on patch (wrong background color against the button fill). Always glue multi-key chords into **one** bare kbd:
+
+```tsx
+// ✅ correct — bare inside a button
+<Button>
+  <span>Ask Leo</span>
+  <KbdGroup className="ml-1.5">
+    <Kbd variant="bare">⌘⌥K</Kbd>
+  </KbdGroup>
+</Button>
+
+// ❌ wrong — tile variant on a primary button
+<Button>
+  <span>Ask Leo</span>
+  <KbdGroup className="ml-1.5">
+    <Kbd>⌘</Kbd><Kbd>⌥</Kbd><Kbd>K</Kbd>
+  </KbdGroup>
+</Button>
+```
+
+Reference pattern: `components/new-placement-form.tsx` (Next = `<Kbd variant="bare">{mod}⏎</Kbd>`, Back = `<Kbd variant="bare">{mod}{alt}←</Kbd>`). See `.cursor/rules/exxat-kbd-shortcuts.mdc` for the full shortcut table.
+
+## Color (SC 1.4.3 / 1.4.11)
+
+- **Normal text** (including small badge labels): **≥ 4.5:1** against its background.
+- **UI components** (borders, focus rings): **≥ 3:1** where required by 1.4.11.
+- **Muted text on tinted surfaces** (e.g. sidebar): use tokens mixed against **`--sidebar`**, not only against `--background` (see `--sidebar-section-label-foreground`).
+
+## Sidebar badges (design tokens)
+
+- **Count / numeric (sidebar):** **red** (`bg-red-600` + white). Placement toolbar counts use **status colors** (see below).
+- **“New”:** use **brand** (`bg-brand` + `text-brand-foreground`).
+- **“Beta”:** bright yellow fill + **dark** text (`bg-yellow-400` + `text-yellow-950`) for contrast.
+
+## Placements toolbar count pills (`filterId`)
+
+- **`all`:** slate  
+- **`upcoming`:** amber  
+- **`ongoing`:** blue  
+- **`completed`:** emerald  
+- Unknown `filterId` falls back to **all** (slate).
+
+## Form fields — format hints MUST be persistent (SC 3.3.2, 1.3.1)
+
+Placeholder text disappears on focus, is low-contrast by default, and is not reliably announced by assistive tech. For any field with a **required format**, render the format as **persistent helper text** tied to the input via `aria-describedby` — never rely on the placeholder alone.
+
+**When this applies (non-exhaustive):**
+
+- Dates, times, date ranges (even when a picker is present — the typed-format fallback must show the mask).
+- Phone / fax, country-specific formats.
+- Currency, GPA, percentages, hours, durations, unit-bearing numbers ("hrs/wk", "USD").
+- IDs with a pattern (Student ID `STU-YYYY-####`, NPI, license #).
+- Email / URL where a domain or protocol is required.
+- Credit hours, scores, weights — anything whose scale is not obvious from the label.
+
+**Pattern — use `FormDescription` from shadcn `Form`:**
+
+```tsx
+<FormField name="dob" render={({ field }) => (
+  <FormItem>
+    <FormLabel>Date of birth<span aria-hidden="true"> *</span></FormLabel>
+    <FormControl>
+      <Input {...field} inputMode="numeric" placeholder="MM/DD/YYYY" />
+    </FormControl>
+    {/* Persistent — announced via aria-describedby, survives focus */}
+    <FormDescription>MM/DD/YYYY</FormDescription>
+    <FormMessage />
+  </FormItem>
+)} />
+```
+
+**Rules:**
+
+1. The format MUST appear as visible text **outside** the placeholder — `FormDescription`, a helper `<p>` with `id` referenced by `aria-describedby`, or an adjacent `<small>`.
+2. Placeholder MAY mirror the format as extra affordance, but is never the sole source.
+3. Prefer a **picker primitive** over free-text where one exists: `DatePickerField` for dates, `Select` for enumerated values, masked input for phone/IDs.
+4. Required marker (`*`) is decorative — always pair with `aria-required="true"` on the input.
+5. Error messages (`FormMessage`) replace description announcement while active; keep the description concise so the combined `aria-describedby` string stays readable.
+6. Units belong in the description, not the label suffix, when they vary by context (e.g. "Out of 4.0" under GPA rather than in the label).
+
+## High-Contrast modes
+
+There are **two** HC paths in this app. Fix both or the bar will still look broken in one of them:
+
+1. **App HC theme — `html[data-contrast="high"]`** (user toggle in Settings). Use the **`hc:`** Tailwind variant defined in `globals.css` (line 22: `@custom-variant hc (&:is([data-contrast="high"] *));`). This is what the user sees when they switch to High Contrast in-app.
+2. **OS / browser forced-colors** — Windows High Contrast, some Linux DEs, `prefers-contrast: more`. Use `forced-colors:` variants mapping to system colors (`Canvas`, `CanvasText`, `Highlight`, `HighlightText`, `GrayText`).
+
+### Why tokens collapse in HC
+
+In HC themes many surfaces resolve to near-identical values (e.g. `bg-muted` ≈ `bg-background` in HC dark, `bg-brand` gets desaturated). Any UI encoding state **only via fill/track color** (progress bars, quota gauges, chart ranges, meter pills, dashed reference lines, status pills) flattens into a single rectangle. The fix is to force distinct contrast in HC:
+
+- **Track / container:** `hc:border hc:border-border hc:bg-background` + `forced-colors:border-[CanvasText] forced-colors:bg-[Canvas]`
+- **Active fill / progress:** `hc:bg-foreground` + `forced-colors:bg-[Highlight]`
+- **Dashed marker / divider:** `hc:border-foreground` + `forced-colors:border-[CanvasText]`
+- **Pill on colored bg:** invert to `hc:bg-background hc:text-foreground hc:border hc:border-foreground` + `forced-colors:bg-[Canvas] forced-colors:text-[CanvasText] forced-colors:border-[CanvasText]`
+- **Disabled state:** `forced-colors:text-[GrayText]`
+
+Never rely on `box-shadow` alone for separation in HC — shadows are suppressed; pair with a border.
+
+Windows HC mode (and the CSS `forced-colors: active` media query) strips every custom `background-color`, `border-color`, and `box-shadow` and remaps text/icons to a small palette of system colors. Progress bars, pills, chart legends, avg-markers, and any "color-only" indicator collapse into a single flat rectangle if you rely purely on tokens like `bg-brand` or `bg-muted`.
+
+**Rule:** for every UI that encodes state **via fill / track color** (progress bars, quota gauges, chart ranges, meter pills, status pills, dashed reference lines):
+
+1. Keep the default `bg-*` tokens for light/dark themes.
+2. Add `forced-colors:` variants mapping to system colors:
+   - **Track / container:** `forced-colors:bg-[Canvas] forced-colors:border forced-colors:border-[CanvasText]`
+   - **Active fill / progress:** `forced-colors:bg-[Highlight]` (text on it → `forced-colors:text-[HighlightText]`)
+   - **Dashed marker / divider:** `forced-colors:border-[CanvasText]`
+   - **Tooltip / pill on colored bg:** `forced-colors:bg-[Canvas] forced-colors:text-[CanvasText] forced-colors:border forced-colors:border-[CanvasText]`
+   - **Disabled state:** `forced-colors:text-[GrayText]`
+3. Never rely on `box-shadow` alone for separation in HC — shadows are suppressed; pair with a border.
+
+Reference fix: `components/dashboard-quota-progress-card.tsx` `StudentScoreProgressRow` — track → `Canvas`, fill → `Highlight`, avg-marker pill → `Canvas` + `CanvasText` border.
+
+## Audit rules to track (examples)
+
+| Severity | Rule | Criterion |
+|----------|------|-----------|
+| Critical | Certain ARIA roles must contain particular children | 1.3.1 |
+| Serious | Touch targets must be ≥24px or spaced accordingly | 2.5.8 |
+
+When fixing, re-run **axe** or your preferred checker on the **Placements** page after changing the Views toolbar.
+
+## Charts (keyboard exploration)
+
+- **Chart region:** Product charts that support arrow-key exploration use **`ChartFigure`** (`role="application"`, focus ring on the chart container, click-or-Tab to focus per `charts-overview`).
+- **Selected datum:** Prefer **visible** feedback that matches the **`/dashboard` gallery** — Recharts **`activeBar`** + **`activeIndex`** for bars, **`activeShape`** + **`activeIndex`** for pies — via **`@/lib/chart-keyboard-selection`**. Avoid relying on **opacity-only** dimming as the only “selected” indicator; pair with ring/stroke so focus is perceivable (WCAG **2.4.7 Focus Visible** where applicable).
+- **Tables under charts:** **`ChartDataTable`** (`sr-only`) provides an equivalent programmatic structure for screen-reader users.

package/template-vite/.cursor/skills/exxat-board-cards/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: exxat-board-cards
+description: >-
+  Build and maintain kanban board cards in Exxat DS — ListPageBoardCard shell, title/avatar/badge/body hierarchy, BoardCardTwoLineBlock, list-status-badges, ListPageBoardTemplate. Use when adding board view, Team/Compliance/Placements cards, or status chips on cards.
+user-invocable: true
+---
+
+# Exxat DS — board (kanban) cards
+
+**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
+
+- Adding or changing **`viewType === "board"`** on a **`ListPageTemplate`** hub.
+- Building a new **`EntityBoardView`** or **`renderCard`** for **`ListPageBoardTemplate`**.
+- Aligning **Team** / **Compliance** board cards with **Placements**.
+- Wiring **status** on cards so it matches **table** and **list** views.
+
+## Shell: `ListPageBoardCard`
+
+Import from **`@/components/data-views/list-page-board-card`**:
+
+| Part | Component | Role |
+|------|-----------|------|
+| Outer | **`ListPageBoardCard`** | **`Card` `size="sm"`**; pass **`onClick`**, **`isNew`**, **`style`** (e.g. conditional row bg) like **`BoardPlacementCard`**. |
+| Header wrapper | **`ListPageBoardCardHeader`** | Vertical rhythm inside the card. |
+| Title row | **`ListPageBoardCardTitleRow`** | **`title`** + optional **`trailing`** + **`titleClassName`** (`truncate`, `line-clamp-2`, **`lineClampClass`**). |
+| Avatar | **`ListPageBoardCardAvatar`** | **`initials`** string; **`size-7`**, **`--avatar-initials-bg` / `--avatar-initials-fg`**. |
+| Status / tags | **`ListPageBoardCardBadgeRow`** | **`ListHubStatusBadge`** **`surface="board"`** (+ maps from **`lib/list-status-badges.ts`**) — **not** raw status text or one-off **`Badge`** markup in the body. |
+| Body | **`ListPageBoardCardBody`** | Icon rows and two-line blocks (facts). |
+| Hint | **`ListPageBoardCardSecondary`** | Empty states / helper copy. |
+
+## Primitives: `board-card-primitives.tsx`
+
+- **`BoardCardTwoLineBlock`** — icon + **primary** line (`font-medium text-foreground`) + optional **secondary** (muted). Omit **`line2`** for a single-line fact row.
+- **`BoardCardIconRow`** — when mirroring rich **table cells** (see **`BoardPlacementCard`**).
+- **`lineClampClass`** — pass into title or cell wrappers when density options apply.
+- **`BoardNewCardPlaceholder`** — column chrome for **`ListPageBoardTemplate`**.
+
+Prefer **two-line blocks** for stacked **primary / secondary** facts so cards match Placements’ visual rhythm.
+
+## Status badges (list hubs: Team, Compliance, Library, …)
+
+- **Maps (single source):** **`lib/list-status-badges.ts`** — per-entity `*_STATUS_LABEL`, `*_STATUS_BADGE_CLASS`, `*_STATUS_ICON`, plus semantic **`LIST_HUB_STATUS_TINT_*`** (success / warning / neutral / danger) for new domains.
+- **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 **`placements-table-cells.tsx`** — thin wrapper over **`ListHubStatusBadge`** + **`PLACEMENT_STATUS_*`** in **`list-status-badges.ts`** (same visuals as Team / Library).
+
+## Avatar when mock has no `initials`
+
+Use **`initialsFromDisplayName`** from **`lib/initials-from-name.ts`** (e.g. compliance **owner** name).
+
+## Column template (simple hubs)
+
+**`ListPageBoardTemplate`** (`list-page-board-template.tsx`) — define **`ListPageBoardColumnDef<T>`** (`id`, `label`, `description`, **`filter`**, **`renderCard`**). Placements uses a **custom** board with richer headers; new hubs usually start here.
+
+## Placements
+
+**`BoardPlacementCard`** (`placement-board-card.tsx`) — domain-specific (lifecycle tabs, **`ColumnDef`**, conditional background). It **still** composes **`ListPageBoardCard`** parts and primitives; copy that structure for new dense entities.
+
+## Checklist
+
+- [ ] **`ListPageBoardCard`** (not one-off button/card markup).
+- [ ] Title row; avatar when product shows a person/owner chip.
+- [ ] Status in **`ListPageBoardCardBadgeRow`** with **`ListHubStatusBadge`** **`surface="board"`** + **`list-status-badges`** (if entity has status).
+- [ ] Body facts via **`BoardCardTwoLineBlock`** / **`BoardCardIconRow`**.
+- [ ] No **`uppercase`** on status **`Badge`** labels.

package/template-vite/.cursor/skills/exxat-card-vs-list-rows/SKILL.md

@@ -0,0 +1,20 @@
+# Exxat DS — cards vs rows vs lists
+
+Use when choosing **card grids**, **`DataTable`**, or **simple list rows** for a surface.
+
+## Read first
+
+- **`docs/card-vs-rows-pattern.md`**
+- **`.cursor/rules/exxat-card-vs-list-rows.mdc`**, **`exxat-data-tables.mdc`**, **`exxat-board-cards.mdc`**
+- **`exxat-centralized-list-dataset.mdc`** — one `tableState.rows` for table + board + cards
+
+## Checklist
+
+1. **10+ homogeneous records + compare/sort/filter?** → **`DataTable`** + hub template.
+2. **Kanban / visual tiles / folders?** → **`ListPageBoardCard`** or **`ListPageViewFrame`** + card primitives.
+3. **Medium vertical list without full table chrome?** → List row pattern; **promote** to `DataTable` when density and parity demand it.
+
+## MUST NOT
+
+- Card wall for the **primary** sortable hub that other hubs implement as **`DataTable`** without product reason.
+- Second mock row source for cards vs table.

package/template-vite/.cursor/skills/exxat-centralized-list-dataset/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: exxat-centralized-list-dataset
+description: Single canonical dataset and derived row bag for Exxat list hubs — useTableState.rows across table/list/board/dashboard/folder/panel/tree, TablePropertiesDrawer wired to the same table state, shared maps for status/KPIs/inspector. Use when adding a hub view, detail panel, mock data, or fixing inconsistent counts between views.
+user-invocable: true
+---
+
+# Exxat DS — centralized dataset for list hubs
+
+Goal: **one row model**, **one filtered bag** (`tableState.rows`), **one place for badge/KPI maps**, so **every** view tab and inspector matches after search/filters.
+
+**Canon:** `apps/web/AGENTS.md` §4.1–§4.2, `docs/data-views-pattern.md`, `.cursor/rules/exxat-centralized-list-dataset.mdc`.
+
+---
+
+## 1. Canonical row module
+
+- **`lib/mock/<entity>.ts`** — exported typed **`interface`** / type alias + **`ENTITY_ROWS`** (or equivalent) for mocks.
+- Future API: replace **mock export** with **`fetch` + same TS shape**; views stay unchanged.
+- **Extend fields once** (e.g. inspector-only columns): add optional props on the **shared** interface — avoid a parallel **`EntityInspectorRow`** that duplicates IDs.
+
+---
+
+## 2. Single table state → all views
+
+| Surface | Data source |
+|---------|-------------|
+| Table | `useTableState` columns + rows |
+| List / Board / Dashboard | **`tableState.rows`** |
+| Folder grid | **`tableState.rows`** (+ folder metadata from **`lib/mock/<entity>-folders.ts`** keyed by **`folderId`**, not a second question list) |
+| Panel / Finder | **`tableState.rows`** + grouping helpers |
+| Tree + detail | **`tableState.rows`** for leaf items; folders from **folder mock**; selected question resolves **by id** from **`tableState.rows`** |
+
+**Anti-pattern:** `import { ENTITY_ROWS } from "..."` inside a view component while the table uses **`useTableState`** — filters won’t match.
+
+**Fix:** Pass **`tableState.rows`** (or setter/updater from parent) into child views; only use raw **`ENTITY_ROWS`** for **initial seed** into **`useTableState`**.
+
+---
+
+## 3. Table properties = same row shape
+
+- **`buildXColumns(rows)`** — column defs use **`accessorKey`** / **`cell`** consistent with the entity interface.
+- **`TablePropertiesDrawer`** — **`columns`**, **`columnVisibility`**, density — all tied to the **`DataTable`** instance that shares **`useTableState`**.
+- **`currentView`** + **`onViewChange`** — from **`ListPageTemplate`** **`renderContent`** (**§4.2**).
+
+---
+
+## 4. KPIs, dashboards, command palette
+
+- **`entityKpiMetrics(rows)`** / **`entityTopicInsight(rows)`** — take **`tableState.rows`** (filtered).
+- Dashboard charts on the hub — same **`rows`** prop as **`KeyMetrics`**.
+- ⌘K row search — index **`tableState.rows`** or shared mock through **`lib/command-menu-search-data.ts`** patterns — not a divergent copy (**`docs/command-menu-pattern.md`**).
+
+---
+
+## 5. Status, labels, icons
+
+- **`DATA_LIST_VIEW_TILES`** / **`dataListViewLabel`** — single registry for tab labels/icons.
+- Entity status — **`lib/list-status-badges.ts`** (**`ListHubStatusBadge`**) or one **`ENTITY_STATUS_*`** map next to mock data.
+- **MUST NOT** hardcode **"Published"** / tint classes in three components when a map already exists.
+
+---
+
+## 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.
+- [ ] Board / list / dashboard / folder / panel / tree **all** branch from the same client with shared **`rows`**.
+- [ ] Inspector/detail resolves **`selectedId`** with **`rows.find(r => r.id === selectedId)`** (or passes the row object from selection).
+- [ ] **`TablePropertiesDrawer`** receives **`currentView`** / **`onViewChange`** + column model from the **same** table.
+- [ ] KPI/chart helpers invoked with **`tableState.rows`**.
+- [ ] No second mock array unless **derived** (`useMemo(() => rows.filter(...), [rows])`).
+
+---
+
+## 7. Reference implementations
+
+- **`components/placements-client.tsx`** + **`placements-table.tsx`** — Placements pattern.
+- **`components/team-client.tsx`** + **`team-table.tsx`**.
+- **`components/library-table.tsx`** — multiple **`DataListViewType`** branches sharing **`tableState`** / **`folders`** / **`items`**.
+
+---
+
+## 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`**.
+
+**Components:** Prefer **`components/data-views/*`** primitives (**`FolderGridView`**, **`FinderPanelView`**, board template, etc.) with **`rows`** from **`tableState.rows`**, not a second import of **`ENTITY_ROWS`**.
+
+**Rule:** **`.cursor/rules/exxat-centralized-list-dataset.mdc`** (presentation bullets §8–10).
+
+---
+
+## See also
+
+- `.cursor/rules/exxat-centralized-list-dataset.mdc`
+- `.cursor/rules/exxat-list-page-connected-views.mdc`
+- `.cursor/rules/exxat-list-page-view-shells.mdc`
+- `.cursor/rules/exxat-table-properties-drawer.mdc`
+- `.cursor/rules/exxat-data-tables.mdc`

package/template-vite/.cursor/skills/exxat-collaboration-access/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: exxat-collaboration-access
+description: Shared hub collaboration — PageHeader face rail, InviteCollaboratorsDrawer, library access vs directory role tags. Use when adding invite people, access roster, or collaboration variant headers.
+user-invocable: true
+---
+
+# Exxat DS — collaboration & access
+
+**Handbook:** `apps/web/AGENTS.md` §4.7  
+**Narrative:** `apps/web/docs/collaboration-access-pattern.md`  
+**Cursor rule:** `.cursor/rules/exxat-collaboration-access.mdc`  
+**Related (Library folder scope + ⋯ Customize folder):** `.cursor/rules/exxat-library-hub-header.mdc` · `docs/library-hub-header-pattern.md`
+
+## Wiring checklist
+
+1. **`PageHeaderCollaborator`** — `name`, `email`, `access`, optional `roles[]`, avatar fields (`components/page-header.tsx`).
+2. **Mock/API** — `lib/mock/<entity>-header-collaborators.ts`; one shape for header + invite sheet.
+3. **Entity header** — `variant="collaboration"`; **Invite people** first in **⋯ More**; pass **`onAddCollaborator`** and **`onCollaboratorsOpen`**.
+4. **Hub client** — **`CollaborationAccessFlow`** (preferred) or `collaborators` + `inviteOpen` + **`InviteCollaboratorsDrawer`**; on invite, append to **`collaborators`**.
+5. **Access maps** — `lib/collaborator-access.ts` for Owner / Editor / Commenter / Viewer, invite options, and **`COLLABORATION_HEADER_ADD_LABEL`**.
+6. **Header** — empty roster → outline **Add collaborator**; non-empty → face rail; both open the invite sheet.
+7. **Invite sheet** — `InviteCollaboratorsDrawer`: export-style **`Sheet`**, combined email + access menu, grouped roster (name → email → role tags → access badge).
+8. **Library — folder URL scope** — When **`?scope=folder`**, **`LibraryPageHeader`** **⋯** also lists **Customize folder**; **`LibraryNewFolderSheet`** on **`LibraryClient`** — **`.cursor/rules/exxat-library-hub-header.mdc`**, **`docs/library-hub-header-pattern.md`**.
+
+## MUST NOT
+
+- A second invite control beside a populated face rail.
+- Per-hub access label forks or parallel collaborator types.
+- Toast/snackbar for invite outcomes (**`exxat-no-toast.mdc`**).
+- **`Select`** in **`InputGroupAddon`** for access inside the sheet.
+
+## Reference
+
+- `components/collaboration-access-flow.tsx`, `components/library-page-header.tsx`, `components/library-client.tsx`
+- `components/invite-collaborators-drawer.tsx`, `components/export-drawer.tsx`

package/template-vite/.cursor/skills/exxat-dedicated-search-surfaces/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: exxat-dedicated-search-surfaces
+description: >-
+  Dedicated search landing vs results split, URL composer, recents storage, and templates
+  (generic DedicatedSearch*). Use when adding a route pair like empty ?q= landing + ListPageTemplate results,
+  or wiring localStorage recents without hydration mismatches.
+---
+
+# Dedicated search surfaces (Exxat DS)
+
+## When to use
+
+- A hub exposes **two URL states** on the same feature: **landing** (no primary query / empty `?q=`) vs **results** (non-empty query drives `ListPageTemplate` / `DataTable`).
+- You need an **AI-style composer** that **updates the URL** with `router.replace` and **does not** open Ask Leo.
+- You need **recent searches** persisted in `localStorage` **without** SSR/client markup drift.
+
+## MUST
+
+1. **Hydration-safe recents** — **MUST NOT** read `localStorage` in `useState` initializers. Initial client paint **MUST** match the server (`[]` then `useEffect` sync). See **`DedicatedSearchRecents`**.
+2. **Generic names** — Reusable pieces live under **`DedicatedSearch*`** (`components/dedicated-search-*.tsx`, **`components/templates/dedicated-search-*-template.tsx`**, **`lib/dedicated-search-*.ts`**). Hub code passes **`patchSearchParams`**, **`recents` controller**, copy, and entity table — **MUST NOT** fork parallel “question search landing” components for a second hub.
+3. **Landing shell** — Use **`DedicatedSearchLandingTemplate`** (`ListPageViewFrame` + title + composer slot + optional trailing).
+4. **Results chrome** — Reuse **`DEDICATED_SEARCH_RESULTS_OUTER_CONTENT_CLASSNAME`** on the hub content wrapper and **`DedicatedSearchResultsHeaderChrome`** around page header + composer strip.
+5. **Namespaces recents** — Use **`createDedicatedSearchRecentsController(namespace, legacy?)`** from **`lib/dedicated-search-recents.ts`**. When replacing an existing storage key, pass **`legacy: { storageKey, eventName }`** so users do not lose saved rows.
+
+## MUST NOT
+
+- Gate render on **`typeof window`** for the **first** paint of recents or landing bodies.
+- Duplicate the landing vertical rhythm (`mt-*` between title, composer, recents) outside the template without updating the template for product-wide consistency.
+
+## References (apps/web)
+
+| Piece | Path |
+|-------|------|
+| Landing template | `components/templates/dedicated-search-landing-template.tsx` |
+| Results chrome | `components/templates/dedicated-search-results-template.tsx` |
+| URL composer | `components/dedicated-search-url-composer.tsx` |
+| Recents list | `components/dedicated-search-recents.tsx` |
+| Recents storage factory | `lib/dedicated-search-recents.ts` |
+| Optional default `q` patcher | `lib/dedicated-search-url.ts` |
+| Library adapter (placeholders + patch) | `lib/library-dedicated-search.ts` |
+| Library wiring | `components/library-client.tsx` |
+
+## Cursor rule
+
+- **`.cursor/rules/exxat-dedicated-search-surfaces.mdc`**

package/template-vite/.cursor/skills/exxat-drawer-vs-dialog/SKILL.md

@@ -0,0 +1,20 @@
+# Exxat DS — drawer vs dialog
+
+Use when choosing **Radix `Dialog` / `AlertDialog`** vs **floating `Sheet` panels** vs **route** for a flow.
+
+## Read first
+
+- **`docs/drawer-vs-dialog-pattern.md`**
+- **`AGENTS.md` §6.4** + **`docs/data-views-pattern.md`** (page vs drawer)
+- **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**, **`exxat-page-vs-drawer.mdc`**
+
+## Checklist
+
+1. **Must the user see the hub while acting?** Yes → **`Sheet`** panel (properties, export, invite). No and short → **dialog**. Long / own URL → **route**.
+2. **Destructive confirm?** Prefer **dialog** (`AlertDialog`) unless the product explicitly keeps context in a sheet with the same safeguards.
+3. **Title + focus** — Dialog and sheet both need an accessible **title**; restore focus to trigger on close.
+
+## Repo references
+
+- `TablePropertiesDrawer`, `ExportDrawer`, `InviteCollaboratorsDrawer` — floating **`Sheet`** (names end in “Drawer” but implementation is `Sheet` only).
+- Delete / irreversible — dialog pattern, not toast (**`exxat-no-toast.mdc`**).