@exxatdesignux/ui 0.2.19 → 0.4.0

package/template/docs/components-audit-2026-05.md

@@ -0,0 +1,158 @@
+# `apps/web/components/` audit — 2026-05
+
+**Author:** Exxat DS hardening sweep · **Scope:** observation only — no code moved.
+
+This audit was triggered by formalizing the design system (token taxonomy +
+blueprints + selection guide + ESLint guardrails) so that any future
+component refactor has a clear target structure. **No file is moved or
+deleted by this audit itself.** Treat each finding as a follow-up PR
+candidate; bundle them as you like.
+
+## 1. Sizes & shape
+
+| Bucket | Count | Notes |
+|---|---|---|
+| Top-level `components/*.tsx` | **99** | Mix of hub clients, hub tables, hub views, page headers, dashboard charts, sidebar bits, leaf primitives |
+| `components/data-table/` | 5 | Correct — base table stack |
+| `components/data-views/` | 14 | Correct — generic view primitives + board card |
+| `components/onboarding/` | 5 (4 demos + index) | Demo variants of `GettingStarted` |
+| `components/table-properties/` | (drawer + parts) | Correct |
+| `components/templates/` | 7 | Correct — page-level templates |
+| `components/ui/` | 40+ | Reserved for shadcn primitives bridged from `packages/ui` |
+
+## 2. Findings
+
+### 2.1 Dead components (zero importers found)
+
+> **Resolved 2026-05-19.** A re-verification scan confirmed that
+> `form-layout-01.tsx` and `section-cards.tsx` are **not present** in either
+> `apps/web/components/` or `packages/ui/template/components/` — the audit's
+> initial finding was based on a stale snapshot. No action needed.
+
+### 2.2 Onboarding components split between two locations
+
+> **Resolved 2026-05-19.** Option A landed:
+> - `getting-started.tsx` moved into `components/onboarding/getting-started.tsx`
+>   (both `apps/web/` and `packages/ui/template/`).
+> - Deprecated shims `dashboard-onboarding.tsx` and
+>   `dashboard-onboarding-gallery.tsx` deleted in both locations
+>   (no consumers outside themselves).
+> - `components/onboarding/index.ts` now re-exports `GettingStarted`,
+>   `GettingStartedProgressCard`, `GettingStartedVariantView`,
+>   `renderGettingStartedVariant`, `GETTING_STARTED_STORAGE_KEY`, and
+>   the `Onboarding01`–`Onboarding04` variant cards.
+> - Dashboard consumers (`dashboard-tabs.tsx`, `dashboard-report-charts.tsx`)
+>   import via `@/components/onboarding/getting-started`; intra-folder
+>   variants use the relative `./getting-started` path.
+
+### 2.3 Sidebar shell — high top-level density
+
+> **Resolved 2026-05-19.** All 11 sidebar files relocated into
+> `components/sidebar/` (both `apps/web/` and `packages/ui/template/`):
+>
+> ```
+> components/sidebar/
+> ├── index.ts            ← barrel re-export
+> ├── app-sidebar.tsx
+> ├── app-sidebar-dynamic.tsx
+> ├── sidebar-shell.tsx
+> ├── sidebar-auto-collapse.tsx
+> ├── sidebar-auto-open.tsx
+> ├── nav-main.tsx
+> ├── nav-secondary.tsx
+> ├── nav-documents.tsx
+> ├── nav-user.tsx
+> ├── secondary-nav.tsx
+> └── secondary-panel.tsx
+> ```
+>
+> **External consumers** now import via the barrel:
+> `import { AppSidebar, SidebarShell, useSecondaryPanel } from "@/components/sidebar"`.
+> Per-file paths still resolve (escape hatch), e.g.
+> `@/components/sidebar/secondary-panel`.
+>
+> **Intra-folder** imports use relative paths (`./nav-user`, `./secondary-panel`)
+> so internal restructure does not ripple out.
+>
+> Dead-import audit at completion: zero references to `@/components/<sidebar-file>"`
+> remain outside the new folder.
+>
+> `nav-main`, `nav-secondary`, `nav-documents`, `sidebar-auto-open` are
+> currently zero-import (only mentioned in docs/skills). They were moved for
+> directory consistency; pruning truly dead files is a separate concern.
+
+### 2.4 Dedicated-search files — naming consistent
+
+`dedicated-search-recents.tsx`, `dedicated-search-url-composer.tsx`,
+`components/templates/dedicated-search-{landing,results}-template.tsx` —
+generic family already lives across `templates/` + top-level. **No action.**
+
+### 2.5 Entity-bound views — correctly at top level
+
+`*-list-view.tsx`, `*-board-view.tsx`, `*-page-header.tsx`, `*-client.tsx`,
+`*-table.tsx`, `*-dashboard-charts*.tsx`, `*-os-folder-view.tsx`,
+`*-panel-activator.tsx` — these are entity-specific compositions that
+**must** stay co-located with the hub they serve. **No action.**
+
+### 2.6 Possibly generic — re-evaluate during reuse work
+
+- `tinted-icon-disc.tsx` — used in KPI/empty states. If the API has stabilized,
+  consider moving to `components/data-views/` or `packages/ui/src/components/ui/`.
+- `task-list-panel.tsx`, `task-priority-badge.tsx` — generic-sounding but
+  bound to a Task entity. Confirm scope before any move.
+- `tree-panel-view.tsx`-style: `hub-tree-panel-view.tsx`,
+  `folder-details-shell.tsx` — already generic-sounding. If imported by
+  ≥ 2 hubs, move under `data-views/`.
+
+A quick rule of thumb:
+
+> If a component is imported by **only one** hub, it stays at the top level
+> next to that hub.
+> If it is (or could be) imported by **≥ 2** hubs, promote it into
+> `components/data-views/` (record-bearing) or `components/templates/`
+> (page chrome).
+
+### 2.7 `packages/ui/template/` parity
+
+Most top-level files are mirrored under `packages/ui/template/components/`
+(starter scaffold for `create-exxat-app`). When a file moves in
+`apps/web/components/`, `pnpm --filter @exxatdesignux/ui sync-template`
+will also move it under `template/`. **Always run `sync-template` after any
+refactor under §2.3 / §2.6** so the published starter stays buildable.
+
+## 3. Non-findings — what's already healthy
+
+- **`components/ui/`** is reserved for shadcn-aligned primitives; no
+  duplicates appear at the top level (e.g. no rogue `button.tsx` next to the
+  one in `ui/`).
+- **`components/data-views/`** is the right home for generic record-bearing
+  surfaces (`FolderGridView`, `FinderPanelView`, `ListPageBoardCard`).
+  Entity-specific board cards (`placement-board-card.tsx`) correctly stay
+  at top level.
+- **`components/templates/`** is the right home for page-level wrappers
+  (`ListPageTemplate`, `DedicatedSearch*Template`,
+  `SecondaryPanelHubTemplate`, `DiscoveryHubTemplate`). No drift.
+- **No `components/lightning/`** folder anywhere — `exxat-no-slds-leakage`
+  rule already passes.
+- **No second toast surface** — only `components/ui/sonner.tsx` exists, and
+  it's gated by `exxat-no-toast` + the new `exxat-ds/no-sonner-toast` lint.
+
+## 4. Suggested follow-up PRs
+
+| # | Title | Scope | Risk |
+|---|---|---|---|
+| 1 | Remove dead `form-layout-01.tsx` + `section-cards.tsx` from `apps/web/` and `packages/ui/template/` | Trivial | Low |
+| 2 | Consolidate `getting-started.tsx` + `dashboard-onboarding*.tsx` under `components/onboarding/` | Small | Low (import rename) |
+| 3 | ~~Move sidebar files into `components/sidebar/`~~ — **done 2026-05-19** (§2.3) | Medium | — |
+| 4 | Promote `tinted-icon-disc.tsx`, `hub-tree-panel-view.tsx`, `folder-details-shell.tsx` to `data-views/` if used by ≥ 2 hubs | Small per file | Low |
+| 5 | Run `sync-template` after each of 1–4 to keep `packages/ui/template/` aligned | Single command | Low |
+
+None of these is urgent. They become valuable when the top-level file count
+exceeds ~110 or when a new hub joins the codebase.
+
+## 5. References
+
+- [`apps/web/AGENTS.md`](../AGENTS.md) §9 — architecture pointers
+- [`apps/web/docs/component-selection-guide.md`](./component-selection-guide.md)
+- [`.cursor/rules/exxat-reuse-before-custom.mdc`](../../.cursor/rules/exxat-reuse-before-custom.mdc) — ask before adding new primitives
+- [`.cursor/rules/exxat-list-page-view-shells.mdc`](../../.cursor/rules/exxat-list-page-view-shells.mdc) — when to extract to `data-views/`

package/template/docs/data-views-pattern.md

@@ -2,6 +2,8 @@
 
 > **Canonical rules for agents (MUST/MUST NOT, checklists):** [`AGENTS.md`](../AGENTS.md) in this package (including **§8 Accessibility**). This file is the long-form narrative; keep both aligned when patterns change.
 
+> **Scaling past ~2K rows:** see [`large-dataset-strategy.md`](./large-dataset-strategy.md) for pagination, server-mode upgrade path, and the virtualization follow-up.
+
 This document describes how list pages combine **views**, **toolbar** behavior, **filters**, **properties**, and **persistence** in this codebase.
 
 ## Reuse existing components (required)
@@ -10,18 +12,18 @@ This document describes how list pages combine **views**, **toolbar** behavior,
 
 | Need | Reuse | Where Placements uses it |
 | --- | --- | --- |
-| **View tabs** (table / list / board, lifecycle filters) | `ListPageTemplate` (`ViewTab`, `renderContent`, optional metrics + export) | `components/data-list-client.tsx` + `components/templates/list-page.tsx` |
-| **Table shell** (search, filter bar, sort, grouping, columns, pagination) | `DataTable`, `DataTableToolbar`, `useTableState` | `components/data-table/`, `components/data-list-table.tsx` |
-| **Properties drawer** (display, columns, filters, sort, view type tiles) | `TablePropertiesDrawer` from `@/components/table-properties` | `DrawerToolbar` / list–board shells in `data-list-table.tsx` |
-| **Board / list** | `PlacementsBoardView`, `PlacementsListView` + same `useTableState` | `DataListTable` |
-| **Page header** (primary CTA + More ⋯ + export) | `PlacementsPageHeader` or `TeamPageHeader` | `components/placements-page-header.tsx`, `components/team-page-header.tsx` |
-| **Team page (primary template)** | `TeamClient` = `ListPageTemplate` + `KeyMetrics` + `TeamPageHeader` + `TeamTable` (same composition as `DataListClient`) | `components/team-client.tsx`, `lib/mock/team-kpi.ts` |
-| **Team roster** | `TeamTable` — `DataTable` + `useTableState` + `TablePropertiesDrawer`; list/board/dashboard read **`tableState.rows`** | `components/team-table.tsx` |
-| **Dashboard view (list tab)** | **`KeyMetrics`** (`variant="flat"` or `"card"`) — same KPI system as the template metrics strip; **do not** add ad-hoc `Card` grids for entity summaries | `TeamTable` dashboard branch, `lib/mock/team-kpi.ts` |
-| **List hub metrics strip** | **`KeyMetrics variant="flat"`** — transparent cells, OKLCH brand glow only, border hairlines (**no** grey panel) | **`docs/kpi-flat-band-pattern.md`**, Placements / Team / Question bank clients |
-| **Secondary panel chrome** | **`--secondary-panel-bg`** on **`NestedSecondaryPanelShell`** (lighter than sidebar, follows active product) | **`docs/shell-surface-elevation-pattern.md`**, Question bank |
-| **Export** | `ExportDrawer` | `ListPageTemplate` export props; `DataListClient` |
-| **View body layout** (gutter + centered max-width for folder / icon / panel-style content) | **`ListPageViewFrame`** (`components/data-views/list-page-view-frame.tsx`, re-exported from `components/data-views`) | **`FolderGridView`** (uses the frame); **`QuestionBankOsFolderView`** — see **`AGENTS.md` §4.5** |
+| **View tabs** (table / list / board, lifecycle filters) | `ListPageTemplate` (`ViewTab`, `renderContent`, optional metrics + export) | `components/library-hub-client.tsx` + `components/templates/list-page.tsx` |
+| **Table shell** (search, filter bar, sort, grouping, columns, pagination) | `HubTable` → `DataTable`, `DataTableToolbar`, `useTableState` | `components/data-table/`, `components/data-views/hub-table.tsx`, `components/columns-showcase.tsx` |
+| **Properties drawer** (display, columns, filters, sort, view type tiles) | `TablePropertiesDrawer` from `@/components/table-properties` (auto-wired by `HubTable`) | `DrawerToolbar` / list–board shells in `library-table.tsx` |
+| **Board / list** | `PlacementsBoardView`, `PlacementListRowContent` (wrapped by `HubTable.renderListRow` → `DataRowList`) + same `useTableState` | `PlacementsTable` |
+| **Page header** (primary CTA + More ⋯ + export) | Per-hub page header composing `PageHeader` + `ExportDrawer` button | `components/library-page-header.tsx` |
+| **Primary hub composition** | `*Client` = `ListPageTemplate` + `KeyMetrics` + `*PageHeader` + `*Table`. Reference: `LibraryHubClient`. | `components/library-hub-client.tsx`, `components/columns-client.tsx`, `components/tokens-themes-client.tsx` |
+| **Hub table body** | `HubTable` — wraps `DataTable` + `useTableState` + `TablePropertiesDrawer`; list / board / dashboard read **`tableState.rows`**. Pagination chrome is auto-mounted when the hub passes `pagination` + `onPaginationChange`. | `components/data-views/hub-table.tsx`, `components/library-table.tsx`, `components/columns-showcase.tsx` |
+| **Dashboard view (list tab)** | **`KeyMetrics`** (`variant="flat"` or `"card"`) — same KPI system as the template metrics strip; **do not** add ad-hoc `Card` grids for entity summaries. | `LibraryTable` dashboard branch, `components/library-dashboard-charts.tsx` |
+| **List hub metrics strip** | **`KeyMetrics variant="flat"`** — transparent cells, OKLCH brand glow only, border hairlines (**no** grey panel) | **`docs/kpi-flat-band-pattern.md`**, Placements / Team / Library clients |
+| **Secondary panel chrome** | **`--secondary-panel-bg`** on **`NestedSecondaryPanelShell`** (lighter than sidebar, follows active product) | **`docs/shell-surface-elevation-pattern.md`**, Library |
+| **Export** | `ExportDrawer` | `ListPageTemplate` export props; `PlacementsClient` |
+| **View body layout** (gutter + centered max-width for folder / icon / panel-style content) | **`ListPageViewFrame`** (`components/data-views/list-page-view-frame.tsx`, re-exported from `components/data-views`) | **`FolderGridView`** (uses the frame); **`LibraryOsFolderView`** — see **`AGENTS.md` §4.5** |
 
 **Rules:** (1) Import and compose these components; pass **props** and **column defs** for your entity. (2) If something is missing, **extend the shared component** under `components/` (e.g. a new optional slot on `DataTableToolbar`) rather than copying markup into a single page. (3) Card-only or lightweight pages may use a smaller **Properties** sheet only when there is **no** table—otherwise use `TablePropertiesDrawer` with `DataTable` (see Team).
 
@@ -29,7 +31,7 @@ This document describes how list pages combine **views**, **toolbar** behavior,
 
 If the page uses a **`DataTable`** (or equivalent data grid) as the main surface, it **must** sit under **`ListPageTemplate`** so users get the **views toolbar** (tabs, add view, per-tab settings). The default `ViewTab` entries should include at least one tab whose `viewType` is **`table`** when the primary experience is tabular data. **Do not** render a `DataTable` alone under only `PageHeader` + body.
 
-- **Reference:** `DataListClient` (Placements) and `TeamClient` (Team).
+- **Reference:** `PlacementsClient` (Placements) and `TeamClient` (Team).
 - **Rationale:** Consistent navigation, saved views, per-tab view type (table / list / board), and export at the template level.
 
 ## View layout frame (centered, reusable)
@@ -38,45 +40,10 @@ Non-table view branches (e.g. **folder** icon grid, **panel** finder, OS-style f
 
 **Handbook:** **`AGENTS.md` §4.5**. **Cursor:** **`.cursor/rules/exxat-list-page-view-shells.mdc`**. **Skill:** **`.cursor/skills/exxat-list-page-view-shells/SKILL.md`**. **Do not** wrap **`DataTable`** in the frame if that stacks padding with the table toolbar (**`AGENTS.md` §5**).
 
-## View registry and connected bodies (extensibility)
-
-To add a **new view type** without breaking existing hubs:
-
-1. **Register once** — Add a tile in `lib/data-list-view.ts` (`DATA_LIST_VIEW_TILES`). Capabilities (hub KPI strip, render kind) derive automatically in `lib/data-list-view-registry.ts`.
-2. **Build the body once** — Add or extend a generic surface under `components/data-views/` (e.g. `ListPageCalendarView`). Entity-specific wiring stays in props (`getEventDate`, board `renderCard`), not a second calendar implementation per hub.
-3. **Declare what each hub supports** — `lib/<hub>-supported-views.ts` exports a `const` array; pass the same array to **`ListPageTemplate`** (`supportedViewTypes`), the hub table (`supportedViewTypes` → `TablePropertiesDrawerButton`), and rely on defaults if omitted. **Add view**, **⌘1–9** shortcuts, and **Properties → View type** tiles all use `dataListViewTilesForHub` / `dataListViewSelectionTilesForHub` so users cannot pick a view the hub never implemented.
-4. **Route in the hub table with `ListPageConnectedViewBody`** — Switch on **`getDataListViewRenderKind(view)`**, not raw `view === "…"` chains. Pass one renderer per kind the hub supports via **`defineHubViewRenderers(MY_HUB_SUPPORTED_VIEWS, { … })`** (`lib/hub-connected-view-renderers.ts`) so dev builds warn when a supported view has no body. **Do not** use a default branch that renders dashboard/KPIs; missing renderers show `ListPageViewNotConfigured`.
-5. **Let the template own hub chrome** — `ListPageTemplate` hides the metrics strip on calendar/dashboard via `showsListPageHubMetricsStrip(activeTab.viewType)`. Hub clients pass `showMetrics` only; they do not reimplement per-tab KPI visibility.
-6. **Panel / Miller columns** — Reuse **`ListPageFolderColumnsPanel`** (`components/data-views/list-page-folder-columns-panel.tsx`) for folder + record columns; hub-specific chrome (folder colors, actions) lives in a thin wrapper (e.g. `QuestionBankFolderColumnsPanel`). **Do not** export question-bank-only tree/folder nav from the generic `data-views` barrel.
-
-```tsx
-// lib/my-hub-supported-views.ts
-export const MY_HUB_SUPPORTED_VIEWS = ["table", "list", "calendar"] as const satisfies readonly DataListViewType[]
-
-// my-hub-client.tsx
-<ListPageTemplate supportedViewTypes={MY_HUB_SUPPORTED_VIEWS} showMetrics={showMetrics} … />
-
-// my-hub-table.tsx
-import { defineHubViewRenderers } from "@/lib/hub-connected-view-renderers"
-
-return (
-  <ListPageConnectedViewBody
-    view={view}
-    hubLabel="My hub"
-    renderers={defineHubViewRenderers(MY_HUB_SUPPORTED_VIEWS, {
-      "data-table": <DataTable … />,
-      "calendar-with-toolbar": toolbarShell(<ListPageCalendarView rows={tableState.rows} getEventDate={…} />),
-    })}
-  />
-)
-```
-
-**Checklist for a new view type:** registry tile → `data-views/` component → update each `*-supported-views.ts` that should expose it → add renderer in each `*-table.tsx` (via `defineHubViewRenderers`) → Properties drawer copy in `table-properties/drawer.tsx` if needed → `table-state-lifecycle` picks up types via `DATA_LIST_VIEW_TILES` (no separate allowlist).
-
 ## Architecture
 
 - **Page shell** — `ListPageTemplate` owns the views toolbar (tabs), optional metrics, and export drawer. Content for the active tab is rendered via `renderContent`.
-- **Per–lifecycle (or category) data** — `DataListTable` swaps **columns** and **row sets** based on `lifecycleTabId` (e.g. All / Upcoming / Ongoing / Completed). Each lifecycle tab gets its **own** `DataListTable` instance (`key={tab.filterId}`) so `useTableState` resets correctly when columns change.
+- **Per–lifecycle (or category) data** — `PlacementsTable` swaps **columns** and **row sets** based on `lifecycleTabId` (e.g. All / Upcoming / Ongoing / Completed). Each lifecycle tab gets its **own** `PlacementsTable` instance (`key={tab.filterId}`) so `useTableState` resets correctly when columns change.
 - **Shared table state** — `useTableState` holds sort, search, filters, grouping, column order/visibility/pins/widths, row height, gridlines, and pagination flags. **Table**, **list**, **board**, and **dashboard** all read the same state so switching view type keeps behavior aligned.
 
 ## Mock data and connected views
@@ -94,10 +61,10 @@ return (
 
 | Concern | Table | List | Board | Dashboard (view tab) |
 | --- | --- | --- | --- | --- |
-| Primary surface | `DataTable` | `PlacementsListView` / entity list | `PlacementsBoardView` / entity board | **`KeyMetrics`** (+ optional charts via shared dashboard components) |
+| Primary surface | `DataTable` | `DataRowList` + entity row body (e.g. `PlacementListRowContent`) wired via `HubTable.renderListRow` | `PlacementsBoardView` / entity board | **`KeyMetrics`** (+ optional charts via shared dashboard components) |
 | Data source | `useTableState` | **`tableState.rows`** | **`tableState.rows`** | **`tableState.rows`** via KPI helpers |
 | Column headers / labels | `showColumnLabels` | Same source columns, list layout | Phase columns + optional board column menu | N/A (metrics from same columns/filters) |
-| Row click / navigation | From `DataListTable` | From list shell | Card `onOpen` | N/A |
+| Row click / navigation | From `PlacementsTable` | From list shell | Card `onOpen` | N/A |
 | Pagination | Optional `PaginationBar` + `CountSyncer` | Same pattern | N/A (board uses phase columns) | N/A |
 
 ## Toolbar and properties
@@ -124,20 +91,20 @@ return (
 - **Status (Team & Compliance)** — `lib/list-status-badges.ts` — single source for label strings + badge `className` tails for **table, list, and board**. Do **not** pair with `uppercase` on the Badge (labels are sentence case, aligned with Placements `BoardStatusBadge`).
 - **Owner initials** — `lib/initials-from-name.ts` when mock rows have a display name but no `initials` field.
 - **Shared column shell** — `components/data-views/list-page-board-template.tsx` — `ListPageBoardTemplate` + `ListPageBoardColumnDef<T>`: define columns with `filter` predicates, `renderCard`, `getRowKey`. Used by **Team** and **Compliance** boards; new hubs should start here before custom chrome.
-- **Placement card** — `components/data-views/placement-board-card.tsx` — `BoardPlacementCard` composes **`ListPageBoardCard`** parts with `ColumnDef<Placement>` and lifecycle layout helpers from `lib/placement-board-card-layout.ts`. Placements keeps richer column headers (search, menus); still uses the same primitives.
+- **Library board** — `components/library-board-view.tsx` — composes **`ListPageBoardCard`** parts with `BoardCardTwoLineBlock` for the body and `ListHubStatusBadge` for the status row. Use this as the reference for any new domain board card.
 - New entities should add their own card component that composes **`ListPageBoardCard`** + primitives rather than duplicating column scroll/layout or ad-hoc card chrome.
 
 ## Dashboard view (list pages)
 
-- **Reuse the dashboard chart bundle** — `components/dashboard-report-charts.tsx` — `DashboardReportCharts`: flat `KeyMetrics` + middle chart section + period comparison `KeyMetrics` card. **`ChartsOverview`** (placement-themed demo gallery) is the default middle section for `/dashboard` and **Placements**. **Team** passes **`chartsSection={<TeamDashboardChartsSection members={tableState.rows} />}`** so charts reflect roster data, not placements. List hubs use `ListPageDashboardCharts` (`metricsSingleRow`). Chart **style** can follow `ChartVariantProvider` when using `ChartsOverview`.
-- **Data tab canvas charts** (`data-view-dashboard-charts*.tsx`) share **`ChartFigure`**, **`ChartCard`**, and **`ChartDataTable`** with `charts-overview.tsx`. **Layout** for Placements / Team / Compliance is stored in one place: **`lib/data-view-dashboard-storage.ts`** (see `AGENTS.md` §4.3). **Keyboard-selected bars/slices** must use **`lib/chart-keyboard-selection.ts`** (`activeBar` / `activeShape`) so behavior matches the gallery — not opacity-only `Cell` dimming.
+- **Reuse the dashboard chart bundle** — `components/dashboard-report-charts.tsx` — `DashboardReportCharts`: flat `KeyMetrics` + middle chart section + period comparison `KeyMetrics` card. **`ChartsOverview`** is the default middle section for `/dashboard`. Hubs pass **`chartsSection={<MyDashboardChartsSection rows={tableState.rows} />}`** so charts reflect the hub's own row set. Reference: **`LibraryDashboardChartsSection`** in `components/library-dashboard-charts.tsx`. Chart **style** can follow `ChartVariantProvider` when using `ChartsOverview`.
+- **Data tab canvas charts** share **`ChartFigure`**, **`ChartCard`**, and **`ChartDataTable`** with `charts-overview.tsx`. **Layout** is stored in one place: **`lib/data-view-dashboard-storage.ts`** under a per-hub scope (see `AGENTS.md` §4.3). **Keyboard-selected bars/slices** must use **`lib/chart-keyboard-selection.ts`** (`activeBar` / `activeShape`) so behavior matches the gallery — not opacity-only `Cell` dimming.
 
 ## Persistence
 
-- **Page-level** (`lib/data-list-persistence.ts`, key `exxat-ds:data-list:page:v1`): `displayOptions`, `showMetrics`, `tabs`, `activeTabId`. Loaded in `DataListClient` with `useLayoutEffect`, saved debounced on change. `ListPageTemplate` runs in **controlled** mode when `tabs` / `onTabsChange` / `activeTabId` / `onActiveTabChange` are passed.
-- **Per–lifecycle tab** (key `exxat-ds:data-list:lifecycle:v1:<filterId>`): sort, search, filters, group by, column order/hidden/widths/pins/wrap, column menu search map, row height, gridlines, filter bar visibility, search popover, conditional rules, pagination toggle and page/size. Hydrated in `DataListTable` with `useLayoutEffect`; saved debounced when those fields change.
+- **Page-level** (`lib/data-list-persistence.ts`, key `exxat-ds:data-list:page:v1`): `displayOptions`, `showMetrics`, `tabs`, `activeTabId`. Loaded in `PlacementsClient` with `useLayoutEffect`, saved debounced on change. `ListPageTemplate` runs in **controlled** mode when `tabs` / `onTabsChange` / `activeTabId` / `onActiveTabChange` are passed.
+- **Per–lifecycle tab** (key `exxat-ds:data-list:lifecycle:v1:<filterId>`): sort, search, filters, group by, column order/hidden/widths/pins/wrap, column menu search map, row height, gridlines, filter bar visibility, search popover, conditional rules, pagination toggle and page/size. Hydrated in `PlacementsTable` with `useLayoutEffect`; saved debounced when those fields change.
 
-To add a new page: copy the `DataListClient` pattern (controlled `ListPageTemplate` + storage key namespace) or call `schedulePageSave` / `scheduleLifecycleSave` with your own keys.
+To add a new page: copy the `PlacementsClient` pattern (controlled `ListPageTemplate` + storage key namespace) or call `schedulePageSave` / `scheduleLifecycleSave` with your own keys.
 
 ## Rules of thumb
 
@@ -165,13 +132,13 @@ Below the threshold, these may be omitted unless the page is a primary data hub
 
 ## Data pages: primary CTA + More + Export
 
-If the page **has exportable data** (rows, members, placements, etc.), follow the **Placements** header pattern:
+If the page **has exportable data** (rows, members, library items, etc.), follow the **Library** header pattern:
 
-1. **Primary action** — One default (filled) button for the main task (e.g. **New placement**, **Invite member**). Do **not** use `variant="outline"` for that primary action.
+1. **Primary action** — One default (filled) button for the main task (e.g. **New question**, **Invite collaborator**, **Add token**). Do **not** use `variant="outline"` for that primary action.
 2. **More (⋯)** — An outline **icon** button opening a menu that includes **Export** (and other overflow actions). Wire **Export** to `ExportDrawer` (or equivalent).
 3. **Subtitle** — Prefer a short line with **count + freshness** (e.g. `24 records · Last updated now`), matching `PlacementsPageHeader`.
 
-Reference: `components/placements-page-header.tsx`, `components/team-page-header.tsx`, `components/team-client.tsx`.
+Reference: `components/library-page-header.tsx`, `components/library-hub-client.tsx`.
 
 ---
 
@@ -181,13 +148,11 @@ Reference: `components/placements-page-header.tsx`, `components/team-page-header
 
 **When to use a new page (route):** The flow is **primary**, **long-form**, **multi-step**, or should have its **own URL** / bookmark / history **without** the parent page behind it — e.g. full create/edit, wizards, or detail that *is* the task.
 
-**Focused workflow shell:** For dedicated create/edit, wizards, and sectioned settings, use **`FocusedWorkflowPageTemplate`** + layouts in **`focused-workflow-layouts.tsx`** — see **`docs/focused-workflow-page-pattern.md`** and **`AGENTS.md` §14**. **Not** for list hubs (**`ListPageTemplate`**) or Miller-column explorers.
-
-**Rule of thumb:** **Context + quick** → **drawer**; **blocking short choice** → **dialog**; **primary / long / wizard / settings** → **focused workflow route** (or other dedicated page).
+**Rule of thumb:** **Context + quick** → **drawer**; **blocking short choice** → **dialog**; **otherwise** → **new page**.
 
 **Modal vs side panel (same route):** When the overlay stays on the same URL, prefer **`docs/drawer-vs-dialog-pattern.md`** and **`.cursor/rules/exxat-drawer-vs-dialog.mdc`** — drawers keep the hub visible; dialogs trap focus for confirms.
 
-Canonical rules: **`AGENTS.md` §6.4**, **§14**, root **`.cursor/rules/exxat-page-vs-drawer.mdc`**, **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**, **`.cursor/rules/exxat-focused-workflow-page.mdc`**.
+Canonical rules: **`AGENTS.md` §6.4**, root **`.cursor/rules/exxat-page-vs-drawer.mdc`**, **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**.
 
 ---
 
@@ -195,7 +160,7 @@ Canonical rules: **`AGENTS.md` §6.4**, **§14**, root **`.cursor/rules/exxat-pa
 
 When a route is a **primary** destination in nav (main hub for an entity) **and** the dataset is **large** or **highly interactive**:
 
-- Use the **primary page template**: `ListPageTemplate` (tabs, metrics strip, export drawer at template level) + data client pattern as in **`DataListClient`** / **`DataListTable`** — not a minimal `PageHeader`-only layout.
+- Use the **primary page template**: `ListPageTemplate` (tabs, metrics strip, export drawer at template level) + data client pattern as in **`PlacementsClient`** / **`PlacementsTable`** — not a minimal `PageHeader`-only layout.
 - Smaller satellite pages may use **`PageHeader` + section content**; once the dataset grows past the dense-list threshold, add the toolbar rules above and consider promoting to the full template if the page becomes a main hub.
 
 ---
@@ -207,7 +172,7 @@ When a route is a **primary** destination in nav (main hub for an entity) **and*
 - [ ] **>10 items** → search, filter, sort, properties (per surface type above).
 - [ ] **Has data to export** → **More** menu with **Export** + shared `ExportDrawer` pattern.
 - [ ] **Primary + large / main hub** → `ListPageTemplate`-style shell where applicable.
-- [ ] **Page vs drawer vs dialog (§6.4)** — Quick with parent **context** → drawer/sheet; **blocking** confirm → **dialog**; primary or long flows → **focused workflow route** (`docs/focused-workflow-page-pattern.md`, **§14**) or other dedicated page (`docs/drawer-vs-dialog-pattern.md`).
+- [ ] **Page vs drawer vs dialog (§6.4)** — Quick with parent **context** → drawer/sheet; **blocking** confirm → **dialog**; primary or long flows → **new route** (`docs/drawer-vs-dialog-pattern.md`).
 - [ ] **Primary button** → `Button` default variant (`size="lg"` for parity with Placements), not outline.
 - [ ] **Dashboard view tab** → `KeyMetrics` + shared KPI helpers from **`tableState.rows`**; no duplicate one-off metric cards.
 - [ ] **Data view charts** → `ChartFigure` + `chart-keyboard-selection`; layout persistence via **`data-view-dashboard-storage`** (see `AGENTS.md` §4.3).

package/template/docs/drawer-vs-dialog-pattern.md

@@ -30,15 +30,13 @@
 
 Use when the work is **primary**, **long**, **multi-step**, or deserves its **own URL** — see **`exxat-page-vs-drawer.mdc`** and **`AGENTS.md` §6.4**.
 
-For **large forms, wizards, and sectioned settings**, use **`FocusedWorkflowPageTemplate`** and body layouts — **`docs/focused-workflow-page-pattern.md`**, **`AGENTS.md` §14**, **`.cursor/skills/exxat-focused-workflow-page/SKILL.md`**.
-
 ## Quick matrix
 
 | Need | Drawer | Dialog | Route |
 | --- | --- | --- | --- |
 | Keep hub visible | Yes | No (blocks) | No |
 | Short confirm / alert | Rare | Yes | Overkill |
-| Long form / wizard | Cramped | No | Yes — **`FocusedWorkflowPageTemplate`** |
+| Long form / wizard | Cramped | No | Yes |
 | Properties tied to a table | Yes | Too small | Optional |
 
 ## Accessibility

package/template/docs/glossary.md

@@ -0,0 +1,58 @@
+# Exxat DS — Glossary
+
+> Shared vocabulary. When a rule or pattern uses a term in **bold**, it's defined here. Add a term when you find yourself explaining the same word twice in PR review.
+
+| Term | Definition | See also |
+|---|---|---|
+| **Active view** | The currently selected view tab on a hub (table, list, board, dashboard, …). Drives which `HubTableRenderers` entry mounts and what the **Properties drawer** shows in its view-type tile grid. | `exxat-table-properties-drawer.mdc` |
+| **Bare Kbd** | The `<Kbd variant="bare">` rendering — no background, no border, inherits `currentColor` at 70 %. Used inline **inside** a button so the chord doesn't look pasted on. The default `tile` variant is reserved for tooltips and menu shortcut slots. | `exxat-kbd-shortcuts.mdc` |
+| **Blueprint** | Framework-agnostic spec for one UI pattern. Says *what* the pattern is and *what* it must do without committing to React. See `docs/blueprints/`. | `docs/blueprints/README.md` |
+| **Board card** | The kanban-style card surface on a board view. Composed of `ListPageBoardCard` (shell), `ListPageBoardCardTitleRow`, optional `ListPageBoardCardAvatar`, optional badge row with `ListHubStatusBadge` (`surface="board"`), and a body using `BoardCardTwoLineBlock` / `BoardCardIconRow`. | `exxat-board-cards.mdc` |
+| **Brand glow** | The OKLCH-mixed brand tint applied as a soft halo behind a surface (KPI flat band, secondary panel). Not a hard background — the tint **adds**, the underlying surface still reads. | `docs/kpi-flat-band-pattern.md`, `docs/shell-surface-elevation-pattern.md` |
+| **Bulk-actions slot** | The floating action bar that appears when one or more rows are selected in a `HubTable`. Wired via `bulkActionsSlot={(selected) => …}`. | `packages/ui/src/components/data-views/hub-table.tsx` |
+| **Cell pattern** | One column's rendering recipe — built by composing existing primitives (`Badge`, `AvatarInitials`, `ListHubStatusBadge`, `ToggleSwitch`, FA glyphs, `Tip`, `Tooltip`, `DropdownMenu`). The canonical catalog of patterns lives in `apps/web/components/columns-showcase.tsx`; the live demo is at `/columns`. | `docs/reference-implementations.md` |
+| **Cell primitive** | One of the named, importable `ColumnDef['cell']` renderers exported from `@/components/data-views` (re-exported from `apps/web/components/data-views/table-cells.tsx`): `ProgressCell`, `CurrencyCell`, `NumericCell`, `RatingCell`, `SignalBarsCell`, `BooleanToggleCell`, `AttachmentCountCell`, `ExternalLinkCell`, `RelativeTimeCell`, `PeopleAvatarRailCell`, `PillCell`, `TagListCell`, `RowActionsCell`. Every cell renderer in the showcase comes from this module; new hubs **must** import these instead of inlining the same JSX. | `.cursor/skills/exxat-token-economy/SKILL.md` §3, `exxat-data-tables.mdc` |
+| **Centralized list dataset** | The rule that **one** `useTableState` row bag drives **every** view (table, list, board, dashboard, panel, tree, …) on a given hub. No parallel mock arrays per view. | `exxat-centralized-list-dataset.mdc` |
+| **Coach mark** | The onboarding overlay that highlights a UI element and explains it. State managed by `useCoachMark`. Dismissals stick per flow id. | `apps/web/lib/coach-mark-registry.ts` |
+| **Collaboration variant** | The `PageHeader` flavor that exposes the face rail + Invite-people overflow item for shared hubs. | `exxat-collaboration-access.mdc` |
+| **Column def (`ColumnDef`)** | The typed column shape consumed by `DataTable` / `HubTable`. Adding `filter:` to a column auto-generates a filter chip and toolbar dropdown entry. | `packages/ui/src/components/data-table/types.ts` |
+| **Conditional rule** | A `ColumnDef`-level rule that applies a background tint to a cell when its value matches an operator + value (e.g. "score < 60 → red"). Authored in the **Properties drawer**. | `packages/ui/src/components/table-properties/` |
+| **Content rail** | The centered, max-width column the `PrimaryPageTemplate` reserves for primary content. Width comes from the template, not the page; don't override per-page. | `apps/web/components/templates/primary-page-template.tsx` |
+| **DataTable** | The low-level table primitive in `packages/ui`. Mount this **only** outside a hub (drawer-body mini-grids, modal sub-tables). Inside `ListPageTemplate`, use `HubTable`. | `exxat-data-tables.mdc` |
+| **`delta`** | The KPI **count** of change (e.g. `"+5"`, `-3`, `"+12 %"`) on a `MetricItem`. Pass `""` or `0` to suppress the trend chip. Never prose. | `exxat-kpi-trends.mdc` |
+| **`description`** | The KPI **caption** beneath the value and trend row on a `MetricItem`. Use this for prose like `"left + right"` or `"vs last week"`. Never a delta count. | `exxat-kpi-trends.mdc` |
+| **Display options** | Per-table preferences (toolbar search visibility, density, gridlines, pagination toggle, …) that flow through `DataListDisplayOptions`. `HubTable` owns the state by default; the hub client can take it over with `displayOptions` + `onDisplayOptionsChange`. | `packages/ui/src/components/table-properties/` |
+| **Empty state** | The text + icon + (optional) action shown when a view body has zero rows after filters. Distinct from "no data ever" (use `EmptyTableState`) vs "no matches" (filter-aware copy). | `docs/voice-and-tone.md` |
+| **Face rail** | The small overlapping-faces row on a `PageHeader` (collaboration variant) showing collaborators. Click to open the invite drawer. | `exxat-collaboration-access.mdc` |
+| **Filter chip** | The dismissible chip rendered above a `HubTable` body for each active filter. Auto-generated from `ColumnDef.filter`. | `exxat-data-tables.mdc` |
+| **Flat band (KPI)** | `KeyMetrics variant="flat"` — transparent cell, brand glow only, hairline cell borders. The shape used on every primary hub metrics strip. | `exxat-kpi-flat-band.mdc` |
+| **Hairline** | A 1 px border at exactly `--border` color used to separate KPI cells, table cells, surface divisions. Never thicker for hierarchy — use spacing or color instead. | `docs/kpi-flat-band-pattern.md` |
+| **HubTable** | The canonical hub view body. Wraps `useTableState`, the toolbar (search + filter chips + filter dropdown + sort), `TablePropertiesDrawerButton`, view-type tiles, bulk-actions, and conditional rules. Always use this inside `ListPageTemplate.renderContent`. | `exxat-data-tables.mdc` |
+| **Hub primitive** | Synonym for `HubTable` — the single primitive that produces a "hub-shaped" view body. | same |
+| **Inspector** | A side-anchored drawer that shows a single record's details without leaving the hub. Resolved against the same `tableState.rows` as the grid. | `exxat-centralized-list-dataset.mdc` |
+| **`KeyMetrics`** | The KPI strip / band component. Accepts `MetricItem[]` (≤ 4) and a single `MetricInsight`. Use `variant="flat"` on hubs; `variant="card"` for embedded analytics cards. | `exxat-kpi-flat-band.mdc`, `exxat-kpi-max-four.mdc` |
+| **KPI strip** | The horizontal KPI row at the top of a hub. ≤ 4 tiles. | `exxat-kpi-max-four.mdc` |
+| **Lifecycle tab label** | The string shown under "Properties" in the drawer header (e.g. "Library", "Tokens & themes", "Columns"). Set on `HubTable.lifecycleTabLabel`. | `packages/ui/src/components/table-properties/drawer-button.tsx` |
+| **List hub status badge** | The shared status chip + icon used everywhere status appears (table rows, board cards, list rows). Colors and icons live in `lib/list-status-badges.ts`. `surface="table"` for grid; `surface="board"` for cards. | `exxat-board-cards.mdc` |
+| **List page template** | The hub frame component. Owns the page header slot, metrics strip slot, view-tabs row, and the `renderContent(tab, updateTab)` body callback. | `packages/ui/src/components/templates/list-page.tsx` |
+| **Mono ID** | A system-generated identifier shown in `font-mono tabular-nums` so digits align and the ID is visibly distinct from prose. Mono **only** the ID token in a mixed line. | `exxat-mono-ids.mdc` |
+| **OKLCH** | The perceptually uniform color space used by the brand-tint mix and the glow tokens. Surfaces stack: page → secondary panel → sidebar. | `docs/shell-surface-elevation-pattern.md` |
+| **Pattern** | Long-form narrative that explains a UI behavior in prose: when to use it, how it composes, anti-patterns, references. Lives in `docs/*-pattern.md`. Complements (but doesn't replace) a blueprint or rule. | `docs/HANDBOOK.md` |
+| **`PrimaryPageTemplate`** | The page chrome: breadcrumbs, site header, content rail with the project's standard max-width. Wrap every primary route in this. | `apps/web/components/templates/primary-page-template.tsx` |
+| **Progressive disclosure** | The principle that complexity is exposed only when the user opts into it. KPIs default visible, filters default folded into the toolbar, conditional rules live in the Properties drawer, etc. | `docs/HANDBOOK.md` §1 |
+| **Properties drawer** | The right-side `Sheet` opened from the table toolbar, hosting view-type tiles, column visibility, density, sort, group-by, filters, conditional rules, and pagination toggle. Mounted automatically by `HubTable`. | `exxat-table-properties-drawer.mdc` |
+| **Reference page** | A canonical full implementation of a hub or pattern in `apps/web/components/*.tsx` (e.g. `columns-showcase.tsx`, `tokens-themes-client.tsx`, `library-table.tsx`). Listed in `docs/reference-implementations.md`. Copy from these before inventing. | `docs/reference-implementations.md` |
+| **Rule (binding)** | A `.cursor/rules/*.mdc` doc with MUST / MUST NOT. Binds the AI agent and the human reviewer. Wins over patterns and narratives. | `docs/HANDBOOK.md` §4 |
+| **Secondary panel** | A scoped navigation rail (e.g. "Library → All / Mine / Tree", "Tokens & themes → Colors / Radius / Motion / …") that sits between the main sidebar and the page. Opening one collapses the main sidebar; closing one restores the previous sidebar state. | `exxat-primary-nav-secondary-panel.mdc` |
+| **Site header** | The top bar on a primary route (org/product switcher + breadcrumbs + actions). Owned by `PrimaryPageTemplate`. | `apps/web/components/templates/primary-page-template.tsx` |
+| **Skill** | A `.cursor/skills/<name>/SKILL.md` (mirrored in `.claude/skills/`) workflow + checklist for a recurring agent task. Use a skill when the same checklist would be repeated across many sessions. | `apps/web/AGENTS.md` |
+| **`supportedViewTypes`** | The allowlist of `DataListViewType` values a hub implements. Passed to `HubTable.supportedViewTypes` so the Properties drawer never offers a view the hub can't render. | `packages/ui/src/components/data-views/hub-table.tsx` |
+| **Trend polarity** | `MetricItem.trendPolarity` says whether "up" is good (`higher_is_better`, default), bad (`lower_is_better`), or value-neutral (`informational`). The arrow's tint follows the polarity, not the sign. | `exxat-kpi-trends.mdc` |
+| **`useTableState`** | The state hook that owns rows, filters, search, sort, pagination, group-by, and column visibility. Always one instance per hub. | `exxat-centralized-list-dataset.mdc` |
+| **View tab** | A tab on `ListPageTemplate` representing one view of the same dataset (table, list, board, dashboard, folder, panel, tree, …). Each tab carries a `viewType` and the `renderContent` callback receives it. | `exxat-list-page-connected-views.mdc` |
+| **View type (`DataListViewType`)** | The enum of view shapes the design system supports — `"table" \| "list" \| "board" \| "dashboard" \| "folder" \| "panel" \| "tree"`. Each tab declares one. | `apps/web/lib/data-list-view.ts` |
+| **Voice & tone** | The microcopy rules for the product: empty states, errors, banners, buttons, validation. See `docs/voice-and-tone.md`. | `docs/voice-and-tone.md` |
+
+---
+
+*Missing a term? Add it. Glossary entries are short — link to the rule or pattern for depth, don't restate it here.*

package/template/docs/kpi-flat-band-pattern.md

@@ -24,7 +24,7 @@ List hubs and the main dashboard mix view use **`KeyMetrics variant="flat"`** as
 
 ## MUST NOT
 
-- Add **`--key-metrics-flat-band-linear`** back into `flatBandStyle` or hub inline styles (e.g. question-bank hub hero).
+- Add **`--key-metrics-flat-band-linear`** back into `flatBandStyle` or hub inline styles (e.g. library hub hero).
 - Use **`variant="card"`** on **`ListPageTemplate`** metrics when the design calls for a **flat strip** on the page background.
 - Duplicate KPI numbers in ad-hoc **`Card`** grids on the same hub.
 - Set **`variant="mutedSuffix"`** on product wordmarks to grey out the **suffix** in dark mode — suffix stays **Exxat pink** (`wordmarkColor`); see **`lib/product-brand.ts`**.
@@ -42,9 +42,9 @@ Dark mode (`.dark`): same rules — transparent cells, radial glow only, no line
 
 ## Reference implementations
 
-- `components/question-bank-client.tsx` — `KeyMetrics variant="flat" metricsSingleRow`
+- `components/library-client.tsx` — `KeyMetrics variant="flat" metricsSingleRow`
 - `components/dashboard-tabs.tsx` — mix view flat band + insight
-- `components/placements-client.tsx`, `team-client.tsx`, `compliance-client.tsx` — list hub metrics slot
+- `components/library-hub-client.tsx`, `columns-client.tsx`, `tokens-themes-client.tsx` — list hub metrics slot
 
 ## Insight rail (flat + side-by-side)
 

package/template/docs/kpi-trend-pattern.md

@@ -13,10 +13,23 @@
 | Field | Role |
 | --- | --- |
 | `value` | Current bucket total or rate (formatted string or number). |
-| `delta` | Human-readable delta for the selected period, e.g. `+5`, `-3`, `+12%`, `—` when no comparison. |
-| `trend` | **Visual direction** of that delta: more → `up`, less → `down`, flat / N/A → `neutral`. |
+| `delta` | **Count change for the trend chip**, e.g. `+5`, `-3`, `+12%`. Pass `""` (or `0`) when there is no comparison this period — the chip is then **hidden**, not rendered as `—`. **Never** put captions or labels like `"left + right"` here. |
+| `description` | Optional **caption** rendered **below** the value + trend row (muted, small). Use for *what* moved or *how* the value breaks down — `"left + right"`, `"vs last week"`, `"across 4 sites"`, `"scheduled for removal"`. |
+| `trend` | **Visual direction** of the delta: more → `up`, less → `down`, flat / N/A → `neutral`. Combined with an empty `delta`, `neutral` collapses the chip. |
 | `trendPolarity` | Optional. **`higher_is_better`** (default) \| **`lower_is_better`** \| **`informational`**. |
 
+### Layout
+
+```
+┌─────────────────────────────────────────────┐
+│ Pinned columns                              │  ← label
+│ 2  ↑ +1                                     │  ← value + (delta in chip)
+│ left + right                                │  ← description (caption)
+└─────────────────────────────────────────────┘
+```
+
+The **only** thing next to the arrow is the **count**. Prose lives **below** the value as a description. When there is no direction *and* no count, the chip is **suppressed** entirely (no `—` placeholder).
+
 ## Polarity cheat sheet
 
 | `trendPolarity` | Use when | Up arrow tint | Down arrow tint |
@@ -36,7 +49,9 @@
 
 - Forcing **`trend: "up"`** green because “up feels good” when the metric is **defects** or **flags** — set **`lower_is_better`** instead.
 - Hiding a worsening metric by flipping the arrow without changing **`trend`** — arrows must match the data.
-- Using **`informational`** for KPIs that **do** have an agreed quality bar — pick a polarity or omit the trend chip (`delta: "—"`, `trend: "neutral"`).
+- Using **`informational`** for KPIs that **do** have an agreed quality bar — pick a polarity instead.
+- Rendering an **empty `—`** chip just for layout symmetry. The component already hides the chip when there is no direction *and* no count; leave `delta: ""` + `trend: "neutral"` and use `description` for the supporting caption.
+- Putting captions like **`"left + right"`**, **`"hidden"`**, **`"shown"`**, **`"vs last week"`** in **`delta`**. Those are not deltas. Use **`description`**.
 
 ## Related surfaces