@exxatdesignux/ui 0.5.11 → 0.5.13

package/template/docs/blueprints/page-header.md

@@ -1,130 +0,0 @@
-# Blueprint: Page Header
-
-> **Status:** Stable. **Owner:** Exxat DS core. **Implements:** WCAG 2.1 AA.
-
-## 1. Intent
-
-A page header **names the route** the user is on, communicates **freshness**
-of the underlying data, and gives the user the **primary action** for that
-route (and any secondary actions behind a `⋯` overflow). It is the visual
-anchor of every primary hub.
-
-**Use when:**
-- The user lands on a primary nav destination (Placements, Team, Question
-  bank, Compliance, Settings, Dashboard).
-- The user opens a detail/record view that should advertise its own identity
-  (placement record, question detail).
-
-**Do NOT use when:**
-- The surface is already inside a hub's view body (sub-sections never get
-  their own page header — they get a `DashboardSectionHeading` or similar).
-- The surface is an overlay (drawer / dialog / sheet) — those use their own
-  `*Title` slots.
-
-## 2. Anatomy
-
-```
-┌──────────────────────────────────────────────────────────────────────┐
-│ [icon]  Title                              [face-rail] [primary] [⋯] │  ← title-row (required)
-│         Subtitle · ID · count · freshness                            │  ← meta       (optional)
-└──────────────────────────────────────────────────────────────────────┘
-```
-
-| Slot | Required? | What it carries |
-|---|---|---|
-| `icon` | optional | Product mark (`ExxatProductLogo`) or FA glyph |
-| `title` | **required** | One H1 — the route name (e.g. "Placements") |
-| `subtitle` | optional | One line: short context, ID, count, freshness |
-| `face-rail` | optional | `+N collaborators` stack (variant `collaboration`) |
-| `actions/primary` | optional | One filled `Button` (e.g. "New placement") |
-| `actions/overflow` | optional | One outline icon `Button` opening a dropdown menu |
-| `breadcrumb` | optional | Above title; never alongside it |
-
-The header **never** carries search, filters, view-tabs, or KPIs — those belong
-to `ListPageTemplate` / `KeyMetrics` / `DataTable`. The header is the route
-identity, nothing more.
-
-## 3. States
-
-| State | Visual / behavior |
-|---|---|
-| Default | Title + subtitle + actions; primary CTA filled. |
-| Collaboration empty | Outline "Add collaborator" replaces face rail. |
-| Collaboration populated | Face rail with `+N` opens `InviteCollaboratorsDrawer`. |
-| Loading | Title skeleton (60% width), meta skeleton (30% width). |
-| Error | The header still renders; errors land in the body's `LocalBanner`. |
-| RTL | Slots mirror; FA glyphs auto-mirror via Tailwind's `rtl:`. |
-
-## 4. Tokens consumed
-
-| Token | Used for |
-|---|---|
-| `--background` / `--foreground` | Surface + ink |
-| `--muted-foreground` | Subtitle / meta line |
-| `--brand-color` | Product mark fills (when icon is a product logo) |
-| `--ring` | Focus ring on actions + face rail buttons |
-| `--font-heading` | Title font family (Ivy Presto) — **not** body Inter |
-| `--text-xs` | Meta line at min 11px (SC 1.4.3) |
-| `--radius-md` | Action button corners |
-
-For monospace IDs in the subtitle, see
-[`exxat-mono-ids.mdc`](../../../.cursor/rules/exxat-mono-ids.mdc): only the
-ID token gets `font-mono tabular-nums`, the rest of the line stays sans.
-
-## 5. Accessibility
-
-| WCAG SC | How this blueprint complies |
-|---|---|
-| 1.1.1 Non-text content | Product icon decorative (Case A — title sits beside it). If a header icon must stand alone, follow Case B (label + tooltip). |
-| 1.3.1 Info & relationships | Title is exactly one `<h1>` — every route has one and only one. |
-| 1.4.3 Contrast (text) | `--muted-foreground` is ≥ 5.5:1 on `--background`. |
-| 2.1.1 Keyboard | Tab order: breadcrumb → title link (if any) → face rail → primary → overflow trigger. |
-| 2.4.6 Headings / labels | Title strings match `<title>` (document title) where they describe the same route. |
-| 2.4.11 Focus visible | All interactive slots inherit `:focus-visible` ring from `--ring`. |
-
-## 6. Variants
-
-| Variant | When to use | Differences |
-|---|---|---|
-| `base` | Default — most routes | Title + actions only |
-| `object-home` | Lists / hubs with optional metrics + tabs **below** the header | Adds a count/freshness slot under the title |
-| `record-home` | Detail / record views | May expose a small detail row (label/value pairs) — keep ≤ 5 pairs |
-| `collaboration` | Shared hubs (Library, future) | Adds face rail + invite entry — see [`exxat-collaboration-access.mdc`](../../../.cursor/rules/exxat-collaboration-access.mdc) |
-
-Pick **one** variant per header. Combining `collaboration` with
-`record-home` is allowed only when the record itself is a shareable
-artifact (e.g. a question).
-
-## 7. Implementation
-
-| Framework | Component(s) | File |
-|---|---|---|
-| **React (this app)** | `PageHeader` (shell) + per-hub headers (composition) | [`apps/web/components/page-header.tsx`](../../components/page-header.tsx), [`apps/web/components/library-page-header.tsx`](../../components/library-page-header.tsx) |
-| Mobile | — | — |
-| Figma | — | — |
-
-Reference hub-level compositions:
-
-- **Placements** — filled primary CTA `New placement` + `⋯` (Export, Customize…)
-- **Team** — same shape, count + freshness in subtitle
-- **Library** — `variant="collaboration"` + folder-scoped customize entry
-
-## 8. Do / Don't
-
-| ✅ Do | ❌ Don't |
-|---|---|
-| Render exactly one `<h1>` per route | Render two H1s (e.g. one in header + one in body) |
-| Put the primary CTA inside the header — filled, often `size="lg"` | Use `variant="outline"` for the sole primary action on an exportable page |
-| Put **Export** under `⋯` → `ExportDrawer` | Put Export as a second primary button beside New |
-| Use `ExxatProductLogo` for product marks | Substitute a logo.dev raster for the product mark |
-| Keep subtitle to **one line**; truncate long meta | Stack two meta lines below the title |
-| Show keyboard shortcuts via `Kbd` in tooltips on primary/overflow | Hard-code shortcut hints in the visible button label |
-
-## 9. References
-
-- [`apps/web/docs/data-views-pattern.md`](../data-views-pattern.md) — `PageHeader` in context of `ListPageTemplate`
-- [`apps/web/docs/collaboration-access-pattern.md`](../collaboration-access-pattern.md) — `variant="collaboration"`
-- [`apps/web/docs/library-hub-header-pattern.md`](../library-hub-header-pattern.md) — folder-scoped header
-- [`.cursor/rules/exxat-collaboration-access.mdc`](../../../.cursor/rules/exxat-collaboration-access.mdc)
-- [`.cursor/rules/exxat-mono-ids.mdc`](../../../.cursor/rules/exxat-mono-ids.mdc)
-- [`apps/web/AGENTS.md`](../../AGENTS.md) §4.7, §6.2, §9

package/template/docs/card-vs-rows-pattern.md

@@ -1,36 +0,0 @@
-# Cards vs table rows vs list rows
-
-> **Related:** **`AGENTS.md` §4–§5**, **`.cursor/rules/exxat-data-tables.mdc`**, **`.cursor/rules/exxat-board-cards.mdc`**, **`docs/data-views-pattern.md`**.
-
-## When to use **rows** (table or dense list)
-
-- **Many similar records** (roughly **10+**) where users **scan**, **sort**, **filter**, and **compare columns**.
-- **Same fields** across entities — columns align; export and **TablePropertiesDrawer** apply.
-- **Primary hub** pattern — **`DataTable`** + **`ListPageTemplate`** per **`exxat-data-tables`**.
-
-**Use:** `DataTable`, shared toolbar, row actions, pinned columns.
-
-## When to use **cards** (tile / board / marketing)
-
-- **Lower cardinality** or **visual-first** browsing — folders, dashboards, “pick a template”, hero metrics beside a chart.
-- **Heterogeneous content** — each card has a different layout (title, badge, avatar, two-line body) where a rigid grid of columns would fight the design.
-- **Kanban** — **`ListPageBoardCard`** + column model; still fed by **`tableState.rows`**.
-
-**Use:** `ListPageBoardCard`, `ChartCard`, icon grids under **`ListPageViewFrame`**, dashboard chart tiles.
-
-## When to use **list rows** (not full DataTable)
-
-- **Medium density** — fewer columns than a grid; reading order is **vertical** (timeline, activity, simple roster without heavy operators).
-- Still wire **search** when the list is the main surface and item count grows.
-
-**Prefer** graduating to **`DataTable`** once the hub needs filters, column hide, density, or export parity with other list hubs.
-
-## Anti-patterns
-
-- **Cards for 50+ homogeneous records** when the product expects sort/filter/compare — that belongs in **`DataTable`**.
-- **A second bespoke “table”** alongside **`DataTable`** for the same dataset — extend the table stack instead (**`exxat-centralized-list-dataset`**).
-- **Raw `<table>`** for product data lists — forbidden (**`exxat-data-tables`**).
-
-## See also
-
-- **`.cursor/rules/exxat-card-vs-list-rows.mdc`**, **`.cursor/skills/exxat-card-vs-list-rows/SKILL.md`**

package/template/docs/collaboration-access-pattern.md

@@ -1,116 +0,0 @@
-# Collaboration & access pattern
-
-Shared UI for **who can access a hub** (face stack in the header) and **inviting people** (floating sheet). **Reference:** Library — `LibraryPageHeader`, `LibraryClient`, `InviteCollaboratorsDrawer`.
-
-**Folder-scoped library:** When the library URL selects a folder (`?scope=folder&folderId=`), the same header **⋯ More** menu also exposes **Customize folder** (name / color / icon) via **`LibraryNewFolderSheet`** mounted on **`LibraryClient`** so it works on every view tab. See **`docs/library-hub-header-pattern.md`** and **`.cursor/rules/exxat-library-hub-header.mdc`**.
-
-## When to use
-
-- A list hub or library is **shared** across people (not a private directory).
-- Users need to see **who has access**, **invite by email**, and assign **library access** (Owner / Editor / Commenter / Viewer).
-- The hub already uses **`ListPageTemplate`** + **`PageHeader`** (or an entity header built on it).
-
-**Do not** use this for org-wide **role** administration (Faculty, Program coordinator, Director) as the only story — those are **directory role tags** on people, not library access.
-
-## Vocabulary
-
-| Concept | Meaning | Source |
-|--------|---------|--------|
-| **Library access** | What someone can do **in this hub** (Owner, Editor, Commenter, Viewer) | `lib/collaborator-access.ts` |
-| **Directory roles** | Org/job tags on a person (Faculty, Program coordinator, Director) | `PageHeaderCollaborator.roles` |
-| **Face rail** | Overlapping avatars in the header when the roster is non-empty | `PageHeader` `variant="collaboration"` |
-| **Empty roster CTA** | Outline **Add collaborator** in the header when `collaborators` is empty | `PageHeader` + `COLLABORATION_HEADER_ADD_LABEL` |
-| **Invite sheet** | Floating right **`Sheet`** for roster + invite form | `InviteCollaboratorsDrawer` |
-| **Hub wiring** | Roster state + invite sheet in one render-prop shell | `CollaborationAccessFlow` |
-
-## Header (`PageHeader`)
-
-- Set **`variant="collaboration"`**.
-- Pass **`collaborators`** (`PageHeaderCollaborator[]`) and optional **`accessInfo`**.
-- **Non-empty roster** — overlapping **face rail** only; each face and **`+N`** open the invite sheet via **`onCollaboratorsOpen`**.
-- **Empty roster** — outline **`Add collaborator`** (`addCollaboratorLabel`, default **`COLLABORATION_HEADER_ADD_LABEL`**) opens the same sheet.
-- **Invite** also lives under **⋯ More** on the entity page header (first item when `variant="collaboration"`).
-
-```tsx
-<CollaborationAccessFlow
-  initialCollaborators={LIBRARY_HEADER_COLLABORATORS}
-  resourceLabel={hubHeader.title}
->
-  {({ collaborators, openInvite }) => (
-    <LibraryPageHeader
-      variant="collaboration"
-      title={hubHeader.title}
-      questionCount={count}
-      collaborators={collaborators}
-      onAddCollaborator={openInvite}
-      onCollaboratorsOpen={openInvite}
-      onExport={() => setExportOpen(true)}
-      showMetrics={showMetrics}
-      onToggleMetrics={() => setShowMetrics(v => !v)}
-    />
-  )}
-</CollaborationAccessFlow>
-```
-
-## Hub client state
-
-- Prefer **`CollaborationAccessFlow`** — owns **`collaborators`**, **`openInvite`**, and **`InviteCollaboratorsDrawer`**; pass **`openInvite`** to **`onAddCollaborator`** / **`onCollaboratorsOpen`**.
-- Without the flow: **`collaborators`** — `useState` seeded from `lib/mock/<entity>-header-collaborators.ts` (or API later); **`inviteOpen`** — boolean; mount **`InviteCollaboratorsDrawer`** beside **`ListPageTemplate`**.
-- On invite success, append to **`collaborators`** so the **face rail** and sheet roster stay aligned.
-- **Change access** — roster menu updates **`collaborators`** via **`onCollaboratorAccessChange`** ( **`CollaborationAccessFlow`** default).
-- **Remove access** — confirm dialog then **`onCollaboratorRemove`**; blocked for the only **Owner**.
-
-## `PageHeaderCollaborator`
-
-| Field | Use |
-|-------|-----|
-| `id`, `name`, `imageUrl`, `initials` | Face rail + roster row |
-| `email` | Roster (below name); invite form |
-| `access` | Library access badge (Owner … Viewer) |
-| `roles` | Optional **outline** chips (Faculty, Program coordinator, Director) |
-
-## Invite sheet (`InviteCollaboratorsDrawer`)
-
-Mirror **`ExportDrawer`** chrome: floating **`Sheet`**, no overlay, **`showCloseButton={false}`**, footer **Cancel** / **Send invite** with inline **`Kbd`** (**Esc** / **⏎**), **`Shortcut`** for Enter on the open surface.
-
-**Invite field:** one bordered row — email input + **access** menu on the right.
-
-- Use **`Select`** with **`SelectGroup`** for access (invite row in **`InputGroupAddon`**, roster row standalone); **`position="popper"`** inside the sheet; **no** toast on success (**§6.5**).
-
-**People with access:** one **`rounded-lg border`** list with **`divide-y`** — **not** one card per person.
-
-Row order:
-
-1. **Name** (`text-sm font-medium`)
-2. **Email** (`text-xs text-muted-foreground`)
-3. **Role tags** (`Badge variant="outline"`) when `roles` is set
-4. Trailing **library access** **`Select`** when the hub wires **`onCollaboratorAccessChange`**; **Remove access** (trash) opens a confirm **`Dialog`** when **`onCollaboratorRemove`** is set. The sole **Owner** cannot be removed or demoted until another owner exists.
-
-## Library access constants
-
-- Types and invite options: **`lib/collaborator-access.ts`**
-- **`INVITE_COLLABORATOR_ACCESS_OPTIONS`** — Editor / Commenter / Viewer (no Owner on invite)
-- Customize option **descriptions** per hub; keep **values** stable for forms/API
-
-## File map
-
-| Piece | Path |
-|-------|------|
-| Access types | `lib/collaborator-access.ts` |
-| Hub flow | `components/collaboration-access-flow.tsx` |
-| Collaborator type | `components/page-header.tsx` (`PageHeaderCollaborator`) |
-| Invite sheet | `components/invite-collaborators-drawer.tsx` |
-| Entity header | `components/library-page-header.tsx` |
-| Hub wiring | `components/library-client.tsx` |
-| Demo roster | `lib/mock/library-header-collaborators.ts` |
-
-## Checklist (new hub)
-
-- [ ] `PageHeader` / entity header uses **`variant="collaboration"`** when the product is shared.
-- [ ] **Empty roster** shows **Add collaborator**; **non-empty** shows face rail; both open the invite sheet.
-- [ ] **Invite people** under **⋯ More**; **`CollaborationAccessFlow`** (or equivalent) owns roster + sheet.
-- [ ] Roster: single bordered list; **name → email → role tags**; access badge on the right.
-- [ ] Invite row: email + access menu; **`FormDescription`** for format; **no** toast.
-- [ ] Labels from **`collaborator-access.ts`**; mock/API rows extend **`PageHeaderCollaborator`** once.
-
-**Handbook:** `AGENTS.md` §4.7 · **Rule:** `.cursor/rules/exxat-collaboration-access.mdc` · **Skill:** `.cursor/skills/exxat-collaboration-access/SKILL.md`

package/template/docs/command-menu-pattern.md

@@ -1,45 +0,0 @@
-# Global command palette (⌘K)
-
-**Code:** `components/command-menu.tsx`, config **`buildCommandMenuConfig()`** in **`lib/command-menu-config.ts`**, wired in **`app/(app)/layout.tsx`** via **`CommandMenuProvider`**. Searchable row data is built in **`lib/command-menu-search-data.ts`** (not inside the shell component).
-
-## Role
-
-The command menu is the app’s **global search and AI entry**—one place to jump to routes, library pages, patterns, and AI starters. It is **not** a duplicate of the left sidebar; it **indexes** product surfaces for fast discovery.
-
-## User model
-
-| Need | Where it lives |
-|------|----------------|
-| **Find a page, component, or pattern** | Palette — filterable list, **Enter** to navigate. |
-| **Quick AI / natural language** | Prefer **short answers or “research” snippets inside the palette** when the product can return compact, citeable results without leaving the flow. |
-| **Long or complex answers** | **Ask Leo** right sidebar — multi-step reasoning, long-form help, or anything that does not fit a small results surface. |
-
-**Design rule:** Treat the palette as **progressive disclosure**—lightweight results first in-menu; **escalate** to Ask Leo when the answer is too large or needs a dedicated conversation surface.
-
-## Keyboard
-
-- **⌘K / Ctrl+K** — open / toggle the palette (global listener in `CommandMenu`).
-- **Ask Leo** remains **⌘⌥K / Ctrl+Alt+K** (see `.cursor/rules/exxat-kbd-shortcuts.mdc`) so it does not collide with table search where both exist.
-
-## Configuration
-
-- **Static groups** (AI suggestions, Navigation, Components, Patterns) live in **`lib/command-menu-config.ts`**.
-- Optional **`dataGroups`** are passed to **`buildCommandMenuConfig({ dataGroups })`** from the app shell. **Implementation:** **`getCommandMenuSearchDataGroups()`** in **`lib/command-menu-search-data.ts`** maps mock/API rows (e.g. placements with student names) to **`CommandMenuItem`** rows with **`label`**, **`href`**, and **`keywords`** for cmdk filtering. The layout uses **`buildCommandMenuConfig({ dataGroups: getCommandMenuSearchDataGroups() })`**. Keep domain mapping **outside** `command-menu.tsx` so data sources can change without editing the shell.
-- **`searchOnly` on `CommandMenuGroup`:** cmdk shows **every** mounted item when the search box is empty. For large indexes (hundreds of placements), set **`searchOnly: true`** on that group so **`command-menu.tsx`** does not render it until the user has typed a non-empty query. Static groups (AI, Navigation, …) stay visible on open; the data group appears once the user searches.
-
-## Files (quick reference)
-
-| Piece | Location |
-|-------|----------|
-| Palette UI | `components/command-menu.tsx` |
-| Static groups + `buildCommandMenuConfig` | `lib/command-menu-config.ts` (`CommandMenuGroup.searchOnly`) |
-| Row → menu items (placements, etc.) | `lib/command-menu-search-data.ts` |
-| Provider + `dataGroups` | `app/(app)/layout.tsx` |
-
-## Sidebar
-
-**“Search or ask Leo”** in the sidebar opens the same palette; shortcuts and copy should stay aligned with **`AGENTS.md` §7.1**.
-
----
-
-Keep this document aligned with **`apps/web/AGENTS.md` §7.1** when behavior or copy changes.

package/template/docs/component-selection-guide.md

@@ -1,224 +0,0 @@
-# Exxat DS — Component Selection Guide
-
-**Audience:** humans + AI agents. **Companion to:** [`token-taxonomy.md`](./token-taxonomy.md), [`blueprints/`](./blueprints/).
-
-When you're about to build a UI, **start here**. Follow the decision tree
-to find the right composition before you write any markup. The rule is
-always: **compose existing components first**; only create a new shared
-primitive after asking the user
-([`exxat-reuse-before-custom.mdc`](../../.cursor/rules/exxat-reuse-before-custom.mdc)).
-
----
-
-## 0. Quick chart
-
-```
-                ┌─────────────────────────────────────┐
-                │ What is the surface?               │
-                └──┬──────────────────────────────────┘
-                   │
-       ┌───────────┴────────────────────────────┐
-       │                                        │
-   PRIMARY HUB                               OVERLAY / SECONDARY
-   (route w/ many records,                   (on top of a hub,
-   filters, properties)                      modal task, side panel)
-       │                                        │
-       │                                        ▼
-       │                                  See § 3
-       ▼
-   See § 1
-```
-
----
-
-## 1. Building a primary hub (route with records)
-
-```
-   Q: Is the data > ~10 comparable records?
-   ─────────────────────────────────────────
-   │ yes ──────────────────────────────► DataTable inside ListPageTemplate (§1.1)
-   │ no  ──┬─ all rows shown at once?
-   │       │ yes ── simple `<dl>` / card list (no Properties / Filters needed)
-   │       │ no  ── still use DataTable — future growth is expected
-   └─────►
-```
-
-### 1.1 DataTable hub (canonical)
-
-| Need | Use |
-|---|---|
-| Browsable grid | **`DataTable`** + **`useTableState`** ([blueprint](./blueprints/data-table.md)) |
-| View tabs (table/list/board/dashboard) | **`ListPageTemplate`** + connected views ([`exxat-list-page-connected-views.mdc`](../../.cursor/rules/exxat-list-page-connected-views.mdc)) |
-| Column/density/properties | **`TablePropertiesDrawer`** (pass `currentView` + `onViewChange`) |
-| Filters | Shared `FilterFieldDef` chips |
-| Find-in-list | Toolbar search (`⌘K`) |
-| Metrics strip | **`KeyMetrics`** `variant="flat"` ([`kpi-flat-band-pattern.md`](./kpi-flat-band-pattern.md)) — **max 4 tiles** ([`exxat-kpi-max-four.mdc`](../../.cursor/rules/exxat-kpi-max-four.mdc)) |
-| Export | Filled primary CTA + `⋯` → `ExportDrawer` |
-| Kanban view body | **`ListPageBoardCard`** + `ListPageBoardTemplate` ([`exxat-board-cards.mdc`](../../.cursor/rules/exxat-board-cards.mdc)) |
-| Folder / panel view body | **`FolderGridView`** / **`FinderPanelView`** wrapped in **`ListPageViewFrame`** ([`exxat-list-page-view-shells.mdc`](../../.cursor/rules/exxat-list-page-view-shells.mdc)) |
-| Dashboard view body | **`KeyMetrics variant="card"`** + a hub-specific chart section (reference: `library-dashboard-charts.tsx`) |
-| Nested scope nav (All / Mine / tree) | **`secondaryPanel`** + `PANELS` + `useAutoPanel` ([`exxat-primary-nav-secondary-panel.mdc`](../../.cursor/rules/exxat-primary-nav-secondary-panel.mdc)) |
-| Shared hub w/ invite | **`PageHeader` `variant="collaboration"`** + `InviteCollaboratorsDrawer` |
-| Dedicated search (empty `?q=` vs results) | **`DedicatedSearchLandingTemplate`** + **`DedicatedSearchResultsHeaderChrome`** |
-
-**Reference:** `PlacementsClient` (Placements) is the most complete example.
-
-### 1.2 Visual-browse hub (kanban / gallery)
-
-If the product wants a **kanban-first** experience and the table is the
-fallback rather than primary:
-
-```
-ListPageTemplate
-├── PageHeader
-├── KeyMetrics (optional, ≤4)
-└── viewType="board" → ListPageBoardTemplate + ListPageBoardCard
-```
-
-Even here, **back the board with `useTableState`** so switching to the table
-tab is consistent. Don't fork the data.
-
----
-
-## 2. Naming a card / row / list
-
-| Pattern | What to reach for |
-|---|---|
-| Dense comparable rows | `DataTable` row (don't card-wall it — see [`card-vs-rows-pattern.md`](./card-vs-rows-pattern.md)) |
-| Kanban column card | `ListPageBoardCard` + `BoardCardTwoLineBlock` + `BoardCardIconRow` |
-| OS-folder grid | `FolderGridView` in `ListPageViewFrame` |
-| Finder split (list + preview) | `FinderPanelView` |
-| Sidebar nav row | `SidebarMenuButton` (do not roll your own) |
-| KPI tile | `KeyMetrics` `MetricItem` — never a custom `Card` w/ number |
-| Coach mark tile | `CoachMark` step — never an ad-hoc onboarding popover |
-
----
-
-## 3. Same-route overlay vs new route
-
-Always ask: **does the user need the hub visible behind them?**
-
-```
-                ┌────────────────────────────┐
-                │ Does the user need the hub │
-                │   visible behind them?     │
-                └─────────────┬──────────────┘
-                              │
-              ┌───── YES ─────┴───── NO ─────┐
-              ▼                              ▼
-        Same route                     New route
-       (overlay)                     (own URL)
-              │                              │
-        ┌─────┴──────┐                       │
-        │ Is the task│                       │
-        │   short +  │                       │
-        │  blocking? │                       │
-        └─────┬──────┘                       │
-              │                              │
-        ┌─ YES ┴ NO ──┐                      │
-        ▼              ▼                      ▼
-     Dialog        Sheet panel            Page route
-   (AlertDialog,  (TablePropertiesDrawer,  (full create/edit
-   delete confirm)  ExportDrawer,           wizard, deep detail)
-                   InviteCollaboratorsDrawer)
-```
-
-See [`drawer-vs-dialog-pattern.md`](./drawer-vs-dialog-pattern.md) and
-[`exxat-page-vs-drawer.mdc`](../../.cursor/rules/exxat-page-vs-drawer.mdc).
-
----
-
-## 4. Search / Find / Command
-
-| Need | Use | Shortcut |
-|---|---|---|
-| Find inside a table | `DataTableToolbar` search | `⌘K` / `Ctrl K` (no Alt) |
-| Find inside a hub (across tabs/views) | Same `⌘K` while focus is on the hub | `⌘K` |
-| Global navigation + AI starter | `CommandMenu` ([`command-menu-pattern.md`](./command-menu-pattern.md)) | `⌘K` while no input has focus |
-| Long AI / chat | `AskLeoSidebar` | `⌘⌥K` |
-| Dedicated search page (results view) | `DedicatedSearchLandingTemplate` + `DedicatedSearchResultsHeaderChrome` | — |
-
----
-
-## 5. Feedback / messaging
-
-| Need | Use |
-|---|---|
-| Persistent banner ("system maintenance") | `SystemBanner` |
-| Per-page contextual info | `LocalBanner` |
-| Per-control success/error | Inline text next to the field |
-| Confirm a destructive action | `AlertDialog` |
-| **Never** | `toast()` / Sonner / snackbars ([`exxat-no-toast.mdc`](../../.cursor/rules/exxat-no-toast.mdc)) |
-
----
-
-## 6. Icons
-
-| Use case | Pattern |
-|---|---|
-| Icon next to a label | FA glyph + `aria-hidden` (Case A) |
-| Icon standing alone (meaning-bearing) | `<span role="img" aria-label="…" tabIndex={0}>` + `Tooltip` (Case B) |
-| Icon-only button / link | `<button aria-label="…">` wrapped in `Tooltip` (Case C) |
-| Product mark | `ExxatProductLogo` |
-| School / org mark | `logoDevUrl()` |
-
-Source: `apps/web/AGENTS.md` §8.6.
-
----
-
-## 7. KPIs / metrics
-
-| Need | Use |
-|---|---|
-| Hub metric strip on top of `ListPageTemplate` | `KeyMetrics variant="flat"` |
-| Dashboard view tab key-metrics card | `KeyMetrics variant="card"` (1–4 tiles) |
-| Chart + mini-metric next to it | `ChartCard` + chart's own KPI helpers |
-| Trend arrow on a metric | Set `MetricItem.trend` to match delta sign; set `trendPolarity` when "up" is bad |
-
-Cap visible KPIs at **4** ([`exxat-kpi-max-four.mdc`](../../.cursor/rules/exxat-kpi-max-four.mdc)).
-
----
-
-## 8. Identifiers and typography
-
-| Carries | Use |
-|---|---|
-| System ID (`questionId`, record key) | `font-mono tabular-nums` ([`exxat-mono-ids.mdc`](../../.cursor/rules/exxat-mono-ids.mdc)) |
-| Page title | `<h1>` with `font-heading` (Ivy Presto) inside `PageHeader` |
-| Body | Default Inter, ≥ 11px (`text-xs` minimum) |
-| Status label | `ListHubStatusBadge` from `lib/list-status-badges.ts` — never raw text |
-| Currency / counts | `tabular-nums` (no `font-mono`) |
-
----
-
-## 9. When NOTHING here fits
-
-You are now in the territory covered by
-[`exxat-reuse-before-custom.mdc`](../../.cursor/rules/exxat-reuse-before-custom.mdc):
-
-1. Re-scan `apps/web/components/`, `packages/ui/src/components/`, and `apps/web/components/data-views/`.
-2. Check `AGENTS.md` §9 architecture table.
-3. If still no fit, **ask the user** with a short option list:
-   - extend an existing primitive (preferred),
-   - add a new component under `components/data-views/` or `components/templates/`,
-   - or open a packaged shared primitive in `packages/ui`.
-
----
-
-## 10. Cheat sheet — one-line rules
-
-- **Data list, > 10 rows** → `DataTable` + `ListPageTemplate`.
-- **Visual browse / kanban** → `ListPageBoardCard`.
-- **Folder / panel / OS-folder view** → `data-views/` primitive in `ListPageViewFrame`.
-- **Quick auxiliary task with hub behind** → drawer.
-- **Blocking short confirm** → dialog.
-- **Primary / long / own-URL flow** → new route.
-- **Global ⌘K** → `CommandMenu` (search + quick AI).
-- **Long AI** → Ask Leo (`⌘⌥K`).
-- **Feedback** → banner / inline / dialog — **never** toast.
-- **Icon-only button** → `aria-label` + `Tooltip` (Case C).
-- **System ID** → `font-mono tabular-nums`.
-- **KPI strip** → ≤ 4 tiles, `variant="flat"` on hubs.
-- **Hex color in code** → no. Use a token.
-
-See also: [`AGENTS.md` §13 checklist](../AGENTS.md) — run it before shipping a hub.