@exxatdesignux/ui 0.2.19 → 0.4.0

package/template/docs/blueprints/key-metrics.md

@@ -0,0 +1,128 @@
+# Blueprint: Key metrics (KPI strip + dashboard tiles)
+
+> **Status:** Stable. **Owner:** Design system. **Implements:** SC 1.3.1, 1.4.3, 1.4.11, 2.4.6, 4.1.2.
+
+## 1. Intent
+
+A **key-metrics strip** summarizes a hub's headline numbers — count, % share,
+average, freshness — in 1-4 horizontal tiles. Each tile carries a label, a
+formatted value, and an optional **trend chip** (`+12% MoM`, `↓ 0.4 day`,
+`stable`). The strip exists in two variants:
+
+- `variant="flat"` — transparent band glued under `ListPageTemplate` headers
+  (brand glow + cell hairlines, no surface panel).
+- `variant="card"` — solid card with header / actions / chart annotations
+  (dashboard "Key metrics" section).
+
+Both feed from the **same row bag** the hub's `DataTable` shows, so the
+numbers reflect active filters / search.
+
+**Use when:**
+
+- The hub's headline answer can be expressed in **≤ 4 numbers**.
+- The numbers update in response to filters, search, or a date scope.
+- The user benefits from a trend chip (signed delta + period label).
+
+**Do NOT use when:**
+
+- You need 5 + tiles (push secondary stats into a `MetricInsight`, a chart, or
+  another section — never raise `KEY_METRICS_KPI_COUNT_MAX` without DS review).
+- The metric is a long-form chart (use `Chart` family, possibly with a
+  `MetricInsight` mini-callout inside).
+
+## 2. Anatomy
+
+```
+flat:
+─────────────────────────────────────────────────────────────────
+│ Label   Value   [+12% MoM ▲] │ Label   Value   [−0.4d ▼]    │
+─────────────────────────────────────────────────────────────────
+                                ↑ hairline between cells (no panel)
+```
+
+```
+card:
+┌──────────────────────────────────────────────┐
+│ Key metrics                       [Ask Leo]  │  ← header (label + actions)
+│ ──────────────────────────────────────────── │
+│ Label   Value   [trend]   ↪ insight chip     │  ← MetricItem rows
+│ Label   Value   [trend]                      │
+└──────────────────────────────────────────────┘
+```
+
+| Slot | Required? | What it carries |
+|---|---|---|
+| `metrics` | required | `MetricItem[]` (≤ 4) — label, value, optional trend, optional polarity |
+| `variant` | required | `"flat"` (list-hub strip) or `"card"` (dashboard tile) |
+| `insight` | optional | `MetricInsight` — a narrative chip (e.g. "Renewals up 12% MoM") |
+| `headerActions` | optional (card only) | Ask-Leo trigger or drill-down button |
+| `loading` | optional | Skeleton state — same layout, no values |
+
+## 3. States
+
+| State | Visual / behavior |
+|---|---|
+| Default | Tiles render label + value + optional trend |
+| Loading | Skeleton bars in the value + trend positions, label visible |
+| Empty | Value = `0` (or `—` for averages), trend = `neutral` |
+| Trend up + favorable | Up arrow + positive tint |
+| Trend up + unfavorable (`trendPolarity: "lower_is_better"`) | Up arrow + destructive tint |
+| Trend neutral / informational | Muted tint, arrow still shows direction |
+| RTL | Trend chip flips alignment; arrows stay direction-correct (logical, not visual) |
+
+## 4. Tokens consumed
+
+| Token | Used for |
+|---|---|
+| `--exxat-color-surface-muted` / `--muted` | Card variant header band |
+| `--exxat-color-surface-2` / `--card` | Card variant background |
+| `--exxat-color-brand-tint-1` / `--brand-tint` | Flat variant OKLCH brand glow |
+| `--exxat-color-border-1` / `--border` | Cell hairlines (flat variant) |
+| `--exxat-color-ink-1` / `--foreground` | Value text |
+| `--exxat-color-ink-2` / `--muted-foreground` | Label + meta text |
+| Trend chip tokens (positive / destructive / neutral) | Trend tint + foreground |
+
+## 5. Accessibility
+
+| WCAG SC | How this blueprint complies |
+|---|---|
+| 1.3.1 Info & relationships | The strip is `role="group"` + `aria-label="Key metrics"`; each tile is a `<dl>`-style label / value pair |
+| 1.4.3 Contrast | Trend chip text + tile value ≥ 4.5:1; trend icon ≥ 3:1 |
+| 1.4.11 Non-text contrast | Trend chip border / glyph ≥ 3:1 against tile background |
+| 2.4.6 Headings / labels | Each tile's label is the accessible name; value is `aria-describedby` |
+| 4.1.2 Name / role / value | Trend chip has `aria-label` like "Trending up 12% month over month" (via `metricTrendAriaQualifier`) |
+
+## 6. Variants
+
+| Variant | When to use | Differences from default |
+|---|---|---|
+| `flat` | List-page hub headers — transparent band under `ListPageTemplate` | No surface panel; OKLCH brand glow; hairlines only |
+| `card` | Dashboards (Data tab, embed widgets) | Solid card chrome + header + optional Ask Leo trigger |
+| `compact` | Embedded in another card (chart annotation) | 1-2 tiles inline with the chart legend |
+| `mini` | Inside a chart card | Single tile rendered next to the chart title |
+
+## 7. Implementation
+
+| Framework | Component(s) | File |
+|---|---|---|
+| **React (this app)** | `KeyMetrics` + `MetricItem` + `MetricInsight` + `metricTrendTone` + `metricTrendAriaQualifier` | `@exxatdesignux/ui/components/key-metrics` |
+| Service injection (Ask Leo) | `KeyMetricsProvider` (in `apps/web/components/key-metrics-ask-leo-bridge.tsx`) | Wires `useAskLeo` → DS context |
+| Mobile | — | — |
+| Figma | "Key metrics – flat" and "Key metrics – card" frames | — |
+
+## 8. Do / Don't
+
+| ✅ Do | ❌ Don't |
+|---|---|
+| Cap visible tiles at 4 (`KEY_METRICS_KPI_COUNT_MAX`) | Add a fifth tile by raising the constant without DS review |
+| Set `trendPolarity: "lower_is_better"` for metrics where up = bad (defects, overdue, low-quality flags) | Always paint "up" as the favorable tint |
+| Feed KPI builders with `tableState.rows` so numbers honor filters | Pass raw mock arrays — the numbers will lie when filters change |
+| Use `variant="flat"` on hub headers and `variant="card"` in dashboards | Build a bespoke 3-column tile grid duplicating `KeyMetrics` |
+| Pair trend with a `MetricInsight` for narrative context | Show a bare delta with no period header or qualifier |
+
+## 9. References
+
+- `apps/web/docs/kpi-flat-band-pattern.md`, `kpi-strip-max-four-pattern.md`, `kpi-trend-pattern.md`
+- `.cursor/rules/exxat-kpi-flat-band.mdc`, `exxat-kpi-max-four.mdc`, `exxat-kpi-trends.mdc`
+- `apps/web/AGENTS.md` §4.1 (template metrics slot), §4.3 (charts + mini-metrics)
+- `apps/web/lib/dashboard-layout-merge.ts` — `KEY_METRICS_KPI_COUNT_MAX`, `clampKeyMetricsKpiCount`

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

@@ -0,0 +1,123 @@
+# Blueprint: List page template
+
+> **Status:** Stable. **Owner:** Design system. **Implements:** SC 1.3.1, 2.1.1, 2.4.3, 2.4.6, 4.1.2.
+
+## 1. Intent
+
+A **list page** is the canonical hub surface for browsing a homogeneous
+collection of records (Placements, Team, Compliance, Library items, …).
+It pairs a single `DataTable` with view-tab variants (table · list · board ·
+dashboard · folder · panel · tree), one shared filter / sort / column model,
+and a metric strip that consumes the same filtered row bag.
+
+**Use when:**
+
+- The route is the **primary** destination for an entity (a hub, not a detail).
+- Users compare records and filter / sort across them.
+- The same dataset can be productively shown as a table **and** as one or more
+  alternate views (board, dashboard, etc.).
+
+**Do NOT use when:**
+
+- The page is a **detail** view of a single record (use a record-home page).
+- The dataset is < ~10 items and never needs filters (use a card grid).
+- The flow is a multi-step **wizard** or **form** (use a primary-page template
+  with a focus mode).
+
+## 2. Anatomy
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  PageHeader  (title · subtitle · primary CTA · ⋯ menu)   │  ← slot: header (required)
+├──────────────────────────────────────────────────────────┤
+│  KeyMetrics flat band  (≤ 4 tiles · trend chips · …)     │  ← slot: metrics (optional)
+├──────────────────────────────────────────────────────────┤
+│  View tabs  [ Table · Board · Dashboard · Folder · … ]   │  ← slot: viewTabs (required, ≥ 1)
+├──────────────────────────────────────────────────────────┤
+│  Toolbar  (search · filter chips · ⋯ properties)         │  ← managed by HubTable
+│  ┌─────────────────────────────────────────────────┐     │
+│  │  Active view body — TABLE / BOARD / …           │     │  ← rendered by HubTable + renderers
+│  └─────────────────────────────────────────────────┘     │
+└──────────────────────────────────────────────────────────┘
+```
+
+| Slot | Required? | What it carries |
+|---|---|---|
+| `header` | required | `PageHeader` (object-home / record-home / collaboration variant) |
+| `metrics` | optional | `KeyMetrics variant="flat"` — ≤ 4 tiles fed by the same `tableState.rows` |
+| `viewTabs` | required (≥ 1) | `ViewTab[]` with `viewType`, `icon`, `label`, optional `filterId` |
+| `renderContent` | required | `(tab, updateTab) => ReactNode` that returns the active view body |
+| `beforeSiteHeader` | optional | Banner / promo strip rendered above the site header |
+| `tablePropertiesRef` | optional | Imperative handle so the ⋯ menu can open the Properties drawer |
+
+`ListPageTemplate` itself owns the **header + metrics + view-tab control**.
+The view body is rendered by `HubTable` (or a custom non-table view) and
+**shares one `useTableState`** instance across every view.
+
+## 3. States
+
+| State | Visual / behavior |
+|---|---|
+| Default | Header + metrics + active view body |
+| No metrics declared | Metrics band is omitted; no empty gap |
+| No rows | Active view shows entity-specific empty state; KPI tiles show zeros + neutral trend |
+| Filters applied | Toolbar chips reflect filters; KPI tiles recalculate against filtered rows |
+| Switching views | `tab.id` is the React key so table state survives (sort, search, columns) |
+| Loading | Render skeleton state in `renderContent`; metric tiles use the `metric-card` skeleton |
+| RTL | All chrome (toolbar, view tabs, properties drawer) flips with `dir="rtl"` |
+
+## 4. Tokens consumed
+
+| Token | Used for |
+|---|---|
+| `--exxat-color-surface-1` / `--background` | Page canvas |
+| `--exxat-color-surface-2` / `--card` | Header + table chrome |
+| `--exxat-color-surface-muted` / `--muted` | View-tab inactive bg, KPI flat band glow |
+| `--exxat-color-brand-1` / `--brand-color` | Active view tab, primary CTA |
+| `--exxat-color-border-1` / `--border` | Hairlines between chrome zones |
+| `--exxat-color-focus-ring` / `--ring` | `:focus-visible` ring on toolbar / tabs |
+| `--exxat-radius-2` / `--radius` | Page chrome radii |
+
+## 5. Accessibility
+
+| WCAG SC | How this blueprint complies |
+|---|---|
+| 1.3.1 Info & relationships | View tabs use `role="tablist"`; toolbar uses `role="toolbar"`; metrics use `role="group"` + name |
+| 2.1.1 Keyboard | Tab through header → tabs → toolbar → grid; arrow keys between tabs and column headers |
+| 2.4.3 Focus order | Tab order matches reading order top-to-bottom |
+| 2.4.6 Headings / labels | Header title is the route `<h1>`; each view tab announces its label |
+| 4.1.2 Name / role / value | View tabs expose `aria-selected`; properties drawer toggle has `aria-haspopup="dialog"` |
+
+## 6. Variants
+
+| Variant | When to use | Differences from default |
+|---|---|---|
+| `base` | Most hubs | Header + metrics + tabs + view body |
+| `no-metrics` | Hubs where KPI summary adds noise (e.g. Library: too many heterogeneous folders) | Omit `metrics` prop |
+| `with-banner` | Pages that need a promo or alert above the header | Use `beforeSiteHeader` slot |
+| `secondary-panel-hub` | Hubs scoped by a sidebar panel (Library) | Wrap in `SecondaryPanelHubTemplate`; same `useTableState` |
+
+## 7. Implementation
+
+| Framework | Component(s) | File |
+|---|---|---|
+| **React (this app)** | `ListPageTemplate` + `HubTable` + `useTableState` + `TablePropertiesDrawer` | `@exxatdesignux/ui/components/templates/list-page`, `@exxatdesignux/ui/components/data-views`, `@exxatdesignux/ui/components/data-table` |
+| Mobile | — | — |
+| Figma | Pattern: "List page – hub" frame in the DS library | — |
+
+## 8. Do / Don't
+
+| ✅ Do | ❌ Don't |
+|---|---|
+| One `useTableState` per hub; every view reads `tableState.rows` | Mount a second mock array for "board only" or "tree only" |
+| Pass `currentView` + `onViewChange` into `TablePropertiesDrawer` | Leave `currentView` unset on a multi-view hub (Properties drawer assumes table) |
+| Use `key={tab.id}` in `renderContent` so table state survives | Use `key={tab.viewType}` (resets state when switching views) |
+| Pull metrics from `tableState.rows` so they react to filters / search | Pass raw mock arrays to KPI builders (numbers will lie when filters change) |
+| Cap the metrics strip at 4 KPI tiles | Add a fifth tile by raising `KEY_METRICS_KPI_COUNT_MAX` without DS review |
+
+## 9. References
+
+- `apps/web/docs/data-views-pattern.md` — connected views narrative
+- `apps/web/docs/kpi-flat-band-pattern.md`, `kpi-strip-max-four-pattern.md`, `kpi-trend-pattern.md`
+- `.cursor/rules/exxat-list-page-connected-views.mdc`, `exxat-centralized-list-dataset.mdc`, `exxat-table-properties-drawer.mdc`, `exxat-list-page-view-shells.mdc`
+- `apps/web/AGENTS.md` §4.1 (template), §4.2 (Properties drawer), §4.5 (view shells)

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

@@ -0,0 +1,130 @@
+# 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/collaboration-access-pattern.md

@@ -1,8 +1,8 @@
 # Collaboration & access pattern
 
-Shared UI for **who can access a hub** (face stack in the header) and **inviting people** (floating sheet). **Reference:** Question bank — `QuestionBankPageHeader`, `QuestionBankClient`, `InviteCollaboratorsDrawer`.
+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 question bank:** When the library URL selects a folder (`?scope=folder&folderId=`), the same header **⋯ More** menu also exposes **Customize folder** (name / color / icon) via **`QuestionBankNewFolderSheet`** mounted on **`QuestionBankClient`** so it works on every view tab. See **`docs/question-bank-hub-header-pattern.md`** and **`.cursor/rules/exxat-question-bank-hub-header.mdc`**.
+**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
 
@@ -33,11 +33,11 @@ Shared UI for **who can access a hub** (face stack in the header) and **inviting
 
 ```tsx
 <CollaborationAccessFlow
-  initialCollaborators={QUESTION_BANK_HEADER_COLLABORATORS}
+  initialCollaborators={LIBRARY_HEADER_COLLABORATORS}
   resourceLabel={hubHeader.title}
 >
   {({ collaborators, openInvite }) => (
-    <QuestionBankPageHeader
+    <LibraryPageHeader
       variant="collaboration"
       title={hubHeader.title}
       questionCount={count}
@@ -100,9 +100,9 @@ Row order:
 | Hub flow | `components/collaboration-access-flow.tsx` |
 | Collaborator type | `components/page-header.tsx` (`PageHeaderCollaborator`) |
 | Invite sheet | `components/invite-collaborators-drawer.tsx` |
-| Entity header | `components/question-bank-page-header.tsx` |
-| Hub wiring | `components/question-bank-client.tsx` |
-| Demo roster | `lib/mock/question-bank-header-collaborators.ts` |
+| Entity header | `components/library-page-header.tsx` |
+| Hub wiring | `components/library-client.tsx` |
+| Demo roster | `lib/mock/library-header-collaborators.ts` |
 
 ## Checklist (new hub)
 

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

@@ -42,4 +42,4 @@ The command menu is the app’s **global search and AI entry**—one place to ju
 
 ---
 
-Keep this document aligned with **`exxat-ds/AGENTS.md` §7.1** when behavior or copy changes.
+Keep this document aligned with **`apps/web/AGENTS.md` §7.1** when behavior or copy changes.

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

@@ -0,0 +1,224 @@
+# 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        Drawer / Sheet         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.