@exxatdesignux/ui 0.2.16 → 0.2.18

package/consumer-extras/cursor-skills/exxat-ds-skill/references/data-table-pattern.md

@@ -0,0 +1,382 @@
+# Data Table Pattern — Full Implementation Guide
+
+Reference implementation: `components/team-table.tsx` (Team) and `components/data-list-table.tsx` (Placements).
+
+---
+
+## Stack Summary
+
+```
+DataTable                         ← base table component
+  └── useTableState               ← manages sort/filter/column/group state
+  └── toolbarSlot                 ← renders the properties button + drawer
+        └── TablePropertiesDrawer ← columns, density, filters, sort, conditional rules
+```
+
+All imports:
+```ts
+import { DataTable } from "@/components/data-table"
+import type { ColumnDef } from "@/components/data-table/types"
+import { useTableState } from "@/components/data-table/use-table-state"
+import { TablePropertiesDrawer } from "@/components/table-properties"
+import type {
+  ConditionalRule,
+  FilterFieldDef,
+  FilterOperator,
+} from "@/components/table-properties/types"
+import {
+  DEFAULT_DATA_LIST_DISPLAY_OPTIONS,
+  type DataListDisplayOptions,
+} from "@/lib/data-list-display-options"
+```
+
+---
+
+## Column Definition Patterns
+
+### Text column with filter
+```ts
+{
+  key: "name",
+  label: "Name",
+  width: 240,
+  minWidth: 160,
+  sortable: true,
+  sortKey: "name",
+  defaultPin: "left",          // pin to left (optional)
+  filter: {
+    type: "text",
+    icon: "fa-user",
+    operators: ["contains", "not_contains"],
+  },
+  cell: row => (
+    <span className="text-sm font-medium text-foreground truncate">{row.name}</span>
+  ),
+}
+```
+
+### Select (enum) column with filter
+```ts
+{
+  key: "status",
+  label: "Status",
+  width: 120,
+  minWidth: 100,
+  sortable: true,
+  sortKey: "status",
+  filter: {
+    type: "select",
+    icon: "fa-circle-dot",
+    operators: ["is", "is_not"],
+    options: [
+      { value: "active", label: "Active" },
+      { value: "inactive", label: "Inactive" },
+    ],
+  },
+  cell: row => (
+    <Badge variant="outline" className={cn("text-[10px] font-medium uppercase tracking-wide", STATUS_BADGE[row.status])}>
+      {STATUS_LABEL[row.status]}
+    </Badge>
+  ),
+}
+```
+
+### Select column (pinned right, no filter)
+```ts
+{
+  key: "select",
+  label: "",
+  width: 40,
+  minWidth: 40,
+  defaultPin: "left",
+  lockPin: true,
+}
+```
+
+### Actions column (pinned right)
+```ts
+{
+  key: "actions",
+  label: "",
+  width: 48,
+  minWidth: 48,
+  defaultPin: "right",
+  lockPin: true,
+  cell: row => (
+    <div className="flex items-center justify-center">
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button size="icon-sm" variant="ghost" aria-label={`Actions for ${row.name}`}>
+            <i className="fa-light fa-ellipsis text-sm" aria-hidden="true" />
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end" className="w-40">
+          <DropdownMenuItem disabled>
+            <i className="fa-light fa-pen" aria-hidden="true" />
+            Edit
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  ),
+}
+```
+
+---
+
+## Status Badge Pattern
+
+```ts
+const STATUS_LABEL: Record<MyType["status"], string> = {
+  active: "Active",
+  inactive: "Inactive",
+  pending: "Pending",
+}
+
+const STATUS_BADGE: Record<MyType["status"], string> = {
+  active:   "bg-emerald-500/15 text-emerald-800 dark:text-emerald-200 border-emerald-500/20",
+  inactive: "bg-slate-500/10 text-slate-700 dark:text-slate-200 border-border",
+  pending:  "bg-amber-500/15 text-amber-900 dark:text-amber-100 border-amber-500/20",
+}
+```
+
+---
+
+## Filter Field Derivation
+
+Convert column defs to filter field defs for the drawer:
+
+```ts
+function columnToFilterFieldDef(c: ColumnDef<T>): FilterFieldDef | null {
+  if (!c.filter) return null
+  const f = c.filter
+  const defaultOps: FilterOperator[] =
+    f.type === "select" || f.type === "date" ? ["is", "is_not"] : ["contains", "not_contains"]
+  return {
+    key: c.key,
+    label: c.label,
+    icon: f.icon ?? "fa-filter",
+    type: f.type,
+    operators: (f.operators ?? defaultOps) as FilterOperator[],
+    options: f.options,
+  }
+}
+```
+
+---
+
+## Drawer Toolbar Component
+
+The `toolbarSlot` renders the Properties button and the drawer. Full pattern:
+
+```tsx
+function FooDrawerToolbar({ state, totalRows, filterFields, fieldDefinitionsForDrawer, resolveColumnLabel, displayOptions, onDisplayOptionsChange, conditionalRules, onAddConditionalRule, onRemoveConditionalRule, onUpdateConditionalRule }) {
+  const { sheetOpen, setSheetOpen, showGridlines, setShowGridlines, rowHeight, setRowHeight,
+    activeFilters, addFilter, updateFilter, removeFilter, getConnector, toggleConnector,
+    filterBarVisible, setFilterBarVisible, drawerExpandedFilters, setDrawerExpandedFilters,
+    rows, sortRules, setSortRules, addSortRule, removeSortRule, toggleSortDir,
+    colOrder, setColOrder, hiddenCols, toggleColVisibility, moveCol, groupBy, setGroupBy, sortKey,
+  } = state
+
+  return (
+    <>
+      <TooltipProvider>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button
+              type="button" variant="ghost" size="icon-sm" aria-label="Properties"
+              onClick={() => setSheetOpen(true)}
+              className={cn(sheetOpen ? "bg-accent text-accent-foreground" : "text-muted-foreground hover:text-interactive-hover-foreground hover:bg-interactive-hover")}
+            >
+              <i className="fa-light fa-sliders text-[13px]" aria-hidden="true" />
+            </Button>
+          </TooltipTrigger>
+          <TooltipContent side="bottom">Properties</TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+
+      <TablePropertiesDrawer
+        open={sheetOpen} onOpenChange={setSheetOpen}
+        showGridlines={showGridlines} onShowGridlinesChange={setShowGridlines}
+        rowHeight={rowHeight} onRowHeightChange={setRowHeight}
+        pagination={false} onPaginationChange={() => {}}
+        activeFilters={activeFilters} onAddFilter={k => addFilter(k, true)}
+        onUpdateFilter={updateFilter} onRemoveFilter={removeFilter}
+        getFilterConnector={getConnector} onToggleFilterConnector={toggleConnector}
+        filterBarVisible={filterBarVisible} onFilterBarVisibleChange={setFilterBarVisible}
+        drawerExpandedFilters={drawerExpandedFilters} onDrawerExpandedFiltersChange={setDrawerExpandedFilters}
+        totalRows={totalRows} filteredRows={rows.length}
+        sortRules={sortRules} onSortRulesChange={setSortRules}
+        onAddSortRule={addSortRule} onRemoveSortRule={removeSortRule} onToggleSortDir={toggleSortDir}
+        colOrder={colOrder} onColOrderChange={setColOrder}
+        hiddenCols={hiddenCols} onToggleColVisibility={toggleColVisibility} onMoveCol={moveCol}
+        groupBy={groupBy} onGroupByChange={setGroupBy} primarySortKey={sortKey}
+        conditionalRules={conditionalRules}
+        onAddConditionalRule={onAddConditionalRule}
+        onRemoveConditionalRule={onRemoveConditionalRule}
+        onUpdateConditionalRule={onUpdateConditionalRule}
+        filterFields={filterFields}
+        lifecycleTabLabel="Foo"      // ← change to entity name
+        fieldDefinitions={fieldDefinitionsForDrawer}
+        resolveColumnLabel={resolveColumnLabel}
+        displayOptions={displayOptions}
+        onDisplayOptionsChange={onDisplayOptionsChange}
+      />
+    </>
+  )
+}
+```
+
+---
+
+## Full Table Component Skeleton
+
+```tsx
+"use client"
+
+import * as React from "react"
+// ... all imports above
+
+export interface FooTableHandle {
+  openPropertiesDrawer: () => void
+}
+
+export const FooTable = React.forwardRef<FooTableHandle, { items: Foo[] }>(
+  function FooTable({ items }, ref) {
+    const columns = React.useMemo(() => buildFooColumns(), [])
+    const filterFields = React.useMemo(() => columnsToFilterFields(columns), [columns])
+    const fieldDefinitionsForDrawer = React.useMemo(
+      () => columns.filter(c => c.key !== "select" && c.key !== "actions")
+                   .map(c => ({ key: c.key, label: c.label, sortable: !!(c.sortable && (c.sortKey ?? c.key)) })),
+      [columns],
+    )
+    const resolveColumnLabel = React.useCallback((key: string) => columns.find(c => c.key === key)?.label ?? key, [columns])
+
+    const [displayOptions, setDisplayOptions] = React.useState<DataListDisplayOptions>(DEFAULT_DATA_LIST_DISPLAY_OPTIONS)
+    const patchDisplay = React.useCallback((patch: Partial<DataListDisplayOptions>) => setDisplayOptions(prev => ({ ...prev, ...patch })), [])
+
+    const [conditionalRules, setConditionalRules] = React.useState<ConditionalRule[]>([])
+    const addConditionalRule = React.useCallback((rule: Omit<ConditionalRule, "id">) => setConditionalRules(prev => [...prev, { ...rule, id: `cr-${Date.now()}` }]), [])
+    const removeConditionalRule = React.useCallback((id: string) => setConditionalRules(prev => prev.filter(r => r.id !== id)), [])
+    const updateConditionalRule = React.useCallback((id: string, patch: Partial<ConditionalRule>) => setConditionalRules(prev => prev.map(r => r.id === id ? { ...r, ...patch } : r)), [])
+
+    const tableState = useTableState(items, columns, { key: "name", dir: "asc" })
+
+    React.useImperativeHandle(ref, () => ({
+      openPropertiesDrawer: () => tableState.setSheetOpen(true),
+    }), [tableState.setSheetOpen])
+
+    return (
+      <div className="pb-6">
+        <DataTable<Foo>
+          data={items}
+          columns={columns}
+          getRowId={row => row.id}
+          getRowSelectionLabel={row => row.name}
+          selectable
+          searchable={displayOptions.showToolbarSearch}
+          showColumnHeaders={displayOptions.showColumnLabels}
+          groupable
+          defaultSort={{ key: "name", dir: "asc" as const }}
+          emptyState={<p className="text-sm text-muted-foreground">No items found.</p>}
+          conditionalRules={conditionalRules}
+          state={tableState}
+          toolbarSlot={s => (
+            <FooDrawerToolbar
+              state={s} totalRows={items.length} filterFields={filterFields}
+              fieldDefinitionsForDrawer={fieldDefinitionsForDrawer} resolveColumnLabel={resolveColumnLabel}
+              displayOptions={displayOptions} onDisplayOptionsChange={patchDisplay}
+              conditionalRules={conditionalRules} onAddConditionalRule={addConditionalRule}
+              onRemoveConditionalRule={removeConditionalRule} onUpdateConditionalRule={updateConditionalRule}
+            />
+          )}
+          bulkActionsSlot={selected => {
+            if (selected.size === 0) return null
+            return (
+              <>
+                <span className="sr-only">{selected.size} selected</span>
+                <Tip label="Export selection (demo)">
+                  <Button size="sm" variant="outline" type="button">
+                    <i className="fa-light fa-arrow-down-to-line" aria-hidden="true" />
+                    Export
+                  </Button>
+                </Tip>
+              </>
+            )
+          }}
+        />
+      </div>
+    )
+  }
+)
+
+FooTable.displayName = "FooTable"
+```
+
+---
+
+## ListPageTemplate Client Skeleton
+
+```tsx
+"use client"
+
+import * as React from "react"
+import { ListPageTemplate, type ViewTab } from "@/components/templates/list-page"
+import { FooPageHeader } from "@/components/foo-page-header"
+import { FooTable, type FooTableHandle } from "@/components/foo-table"
+import { KeyMetrics } from "@/components/key-metrics"
+import { FOO_ITEMS } from "@/lib/mock/foo"
+import { fooKpiInsight, fooKpiMetrics } from "@/lib/mock/foo-kpi"
+import { dataListViewIcon } from "@/lib/data-list-view"
+import { Button } from "@/components/ui/button"
+
+const DEFAULT_TABS: ViewTab[] = [
+  { id: "all", label: "All Foos", viewType: "table", icon: "fa-table", filterId: "all" },
+]
+
+export function FooClient() {
+  const [exportOpen, setExportOpen] = React.useState(false)
+  const [showMetrics, setShowMetrics] = React.useState(true)
+  const tableRef = React.useRef<FooTableHandle>(null)
+
+  const metrics = React.useMemo(() => fooKpiMetrics(FOO_ITEMS), [])
+  const insight = React.useMemo(() => fooKpiInsight(FOO_ITEMS), [])
+
+  return (
+    <ListPageTemplate
+      defaultTabs={DEFAULT_TABS}
+      getTabCount={() => FOO_ITEMS.length}
+      onEditView={(tab, { updateTab }) => {
+        const mustSwitch = tab.viewType !== "table" && tab.viewType !== "list" && tab.viewType !== "board"
+        if (mustSwitch) updateTab({ viewType: "table", icon: dataListViewIcon("table") })
+        window.setTimeout(() => tableRef.current?.openPropertiesDrawer(), mustSwitch ? 160 : 0)
+      }}
+      header={
+        <FooPageHeader
+          itemCount={FOO_ITEMS.length}
+          onAdd={() => {}}
+          onExport={() => setExportOpen(true)}
+          showMetrics={showMetrics}
+          onToggleMetrics={() => setShowMetrics(v => !v)}
+        />
+      }
+      metrics={<KeyMetrics variant="flat" metrics={metrics} insight={insight} showHeader={false} metricsSingleRow />}
+      showMetrics={showMetrics}
+      exportOpen={exportOpen}
+      onExportOpenChange={setExportOpen}
+      exportTotalRows={FOO_ITEMS.length}
+      renderContent={(tab, updateTab) => {
+        if (tab.viewType === "table") return <FooTable key={tab.id} ref={tableRef} items={FOO_ITEMS} />
+        return (
+          <div className="px-4 py-12 text-center lg:px-6">
+            <p className="text-sm font-medium text-foreground">{tab.viewType === "list" ? "List" : "Board"} view is not wired in this demo.</p>
+            <Button type="button" className="mt-4" size="sm" onClick={() => updateTab({ viewType: "table", icon: dataListViewIcon("table") })}>
+              Switch to table
+            </Button>
+          </div>
+        )
+      }}
+    />
+  )
+}
+```

package/consumer-extras/cursor-skills/exxat-kpi-flat-band/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: exxat-kpi-flat-band
+description: KeyMetrics variant flat — transparent KPI strip, OKLCH brand glow only, cell-border hairlines (no grid surface). Use when wiring ListPageTemplate metrics, dashboard mix KPIs, or fixing flat band looking like a grey box.
+user-invocable: true
+---
+
+# Exxat DS — KPI flat band
+
+**Rule:** `.cursor/rules/exxat-kpi-flat-band.mdc`  
+**Doc:** `apps/web/docs/kpi-flat-band-pattern.md`
+
+## Checklist
+
+- [ ] `variant="flat"` on hub / mix view — not `card` for list-page strip.
+- [ ] `flatBandStyle` = **only** `var(--key-metrics-flat-band-radial)`; shadow **`none`**.
+- [ ] No `--key-metrics-flat-band-linear` in component or hub inline `style`.
+- [ ] Cells **`bg-transparent`**; grid uses **`flatMetricsHairlineClass(count, halfLayout)`** — borders only, **no** `gap-px` fill.
+- [ ] **4 KPIs:** verticals between 1|2|3|4 when wide; 2×2 dividers only below `@[max-width:29.99rem]` container.
+- [ ] Divider + glow tokens stay **OKLCH** (`--key-metrics-flat-divider`, `color-mix(in oklch, var(--brand-color) …)`).
+- [ ] **≤ 4** `MetricItem` — `docs/kpi-strip-max-four-pattern.md`.
+- [ ] KPI helpers use **`tableState.rows`** on connected hubs.
+
+## MUST NOT
+
+- Grey/lavender **panel** behind metrics (removed linear wash + gap fill).
+- Duplicate KPI **`Card`** wall for same numbers.
+- Mute product suffix to grey in dark (`mutedSuffix` does **not** change `wordmarkColor`).
+
+## Code pointers
+
+- `apps/web/components/key-metrics.tsx` — `flatMetricsHairlineClass`, `flatBandStyle`
+- `apps/web/app/globals.css` — `--key-metrics-flat-*`
+- `question-bank-client.tsx`, `dashboard-tabs.tsx` — reference usage
+
+## Pair with
+
+- `exxat-kpi-max-four`, `exxat-kpi-trends`, `exxat-list-page-connected-views`
+- `docs/shell-surface-elevation-pattern.md` — sidebar vs page (not the KPI band)

package/consumer-extras/cursor-skills/exxat-mono-ids/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: exxat-mono-ids
+description: Monospace typography for Exxat DS record IDs, question IDs, and system identifiers — font-mono tabular-nums, mixed subtitle lines, table meta. Use when adding or changing questionId, record id columns, header subtitles with IDs, or any copy-pasteable system key in apps/web UI.
+user-invocable: true
+---
+
+# Exxat DS — monospace IDs
+
+**Cursor rule:** `.cursor/rules/exxat-mono-ids.mdc`  
+**Handbook:** `apps/web/AGENTS.md` (§1, §13 checklist)
+
+## Standard classes
+
+```tsx
+// Default secondary ID (table meta, list subline, inspector)
+<span className="font-mono tabular-nums text-xs text-muted-foreground">{id}</span>
+
+// ID in a page subtitle next to sans prose
+<>
+  <span className="font-mono tabular-nums">{questionId}</span>
+  {" · V1 · Last updated just now"}
+</>
+```
+
+Always include **`tabular-nums`** with **`font-mono`** so fixed-width digits align in tables and subtitles.
+
+## MUST
+
+1. **Every visible system ID** in product UI uses **`font-mono tabular-nums`** (plus contextual size/color).
+2. **Mixed lines** — mono only on the identifier substring, not the whole sentence.
+3. **Tables / lists / boards** — ID column or subline under a title: mono + usually **`text-xs text-muted-foreground`**.
+
+## MUST NOT
+
+- Mono on **display names**, **emails** (unless the column is explicitly “Principal ID”), **dates**, **KPI values**, or **status text**.
+- Mono on **UI chrome** that is not an identifier (badges, buttons, nav labels).
+
+## Reference implementations
+
+| Surface | File |
+|---------|------|
+| Question bank table | `components/question-bank-table.tsx` — `row.questionId` |
+| Question bank list | `components/question-bank-list-view.tsx` |
+| New question subtitle | `components/new-question-composer.tsx` — `questionId` in `PageHeader` subtitle |
+| Sites record id | `components/sites-table.tsx` — `row.id` |
+| OS folder tiles | `components/question-bank-os-folder-view.tsx` |
+
+## Review checklist
+
+- [ ] New or changed **ID** fields use **`font-mono tabular-nums`**.
+- [ ] Subtitle / description lines mono-wrap **only** the ID token.
+- [ ] No mono applied to names, statuses, or numeric metrics that are not identifiers.
+
+## See also
+
+- `.cursor/rules/exxat-person-identity-display.mdc` — name + email (sans, not mono for email unless ID column)

package/consumer-extras/cursor-skills/exxat-primary-nav-secondary-panel/SKILL.md

@@ -17,14 +17,33 @@ user-invocable: true
 4. **Data** — keep **one** **`useTableState`** / **`tableState.rows`**; drive scope from **URL** + small helpers (see **`lib/question-bank-nav.ts`**).
 5. **Folder-scoped hub header (Question bank library)** — When **`scope === "folder"`** in the URL, **`QuestionBankPageHeader`** **⋯ More** includes **Customize folder**; mount **`QuestionBankNewFolderSheet`** on **`QuestionBankClient`** so it works on **all** **`ListPageTemplate`** view tabs — **`.cursor/rules/exxat-question-bank-hub-header.mdc`**, **`docs/question-bank-hub-header-pattern.md`**.
 6. **Collapse control** — the nested rail header uses **`collapseActiveSecondaryPanel()`** (angles-left icon), not “close”, so the panel stays dismissed until **`openPanel`** runs again (nav, scope hook, or hub re-entry). Layout effects that auto-call **`openPanel`** must respect **`secondaryPanelAutoReopenSuppressed`** (see **`app/(app)/question-bank/layout.tsx`** + **`SecondaryPanelProvider`**).
+7. **Surface elevation** — secondary panel = **level 1** (lighter than sidebar, darker than page). Use **`--secondary-panel-bg`** on **`NestedSecondaryPanelShell`**; derive from **`--brand-tint*`** per active product (**One** indigo, **Prism** rose). See **`docs/shell-surface-elevation-pattern.md`**.
 
 ## MUST NOT
 
 - Set **`secondaryPanel`** without **`PANELS[id]`** + **`useAutoPanel`** — broken empty rail.
 - Use this for full product areas that belong as **primary** or **collapsible child** rows.
+- Invent a parallel zoom / reflow hook for the secondary rail — reuse **`useSidebarReflowZoom`** (the provider already wires it; see §"High-zoom auto-collapse" below).
+- Set secondary panel **`bg-sidebar`** or a fixed rose mix for every product — breaks **One** indigo chrome.
+
+## High-zoom auto-collapse
+
+`SecondaryPanelProvider` reads **`useSidebarReflowZoom()`** (zoom ≥ 200% or very short viewport — same WCAG 1.4.10 signal the primary sidebar uses). On entering high zoom it sets `secondaryPanelCompact = true` so the 16 rem rail drops to the 3 rem icon variant and frees up content space. The user can still re-expand manually (via the icon rail's "Show labels" affordance or any `openPanel` trigger); the next zoom-out → zoom-in cycle re-collapses it. `openPanel` itself opens directly in compact mode when high zoom is already active so newly-navigated panels don't flash expanded.
+
+Custom panel content (anything you register under `PANELS[id]`) should **read `secondaryPanelCompact` from the provider context** and render an icon-only layout in that branch — `QuestionBankPanel` / `QuestionBankSecondaryNav` are the reference.
+
+## Pair with
+
+- **Collapsible parent ↔ children sidebar pattern** (§3.2 of `exxat-ds-skill`) — when the same primary row also lists sub-routes inline.
 
 ## Reference
 
 - `components/app-sidebar.tsx` — `openPanel` on same-route primary click.
+- `components/secondary-panel.tsx` — `SecondaryPanelProvider`, `PANELS` registry, **high-zoom auto-collapse**.
+- `hooks/use-sidebar-reflow-zoom.ts` — shared zoom / reflow signal.
+- `components/templates/nested-secondary-panel-shell.tsx` — expanded vs `compact` (icon rail) widths; **`bg-[var(--secondary-panel-bg)]`**.
+- `app/globals.css` — `--secondary-panel-bg`, `--sidebar`, product **`theme-one`** / **`theme-prism`** blocks.
+- `contexts/product-context.tsx` — `accentOverrideActive`, theme class on `<html>`.
+- **`docs/shell-surface-elevation-pattern.md`**
 - `components/question-bank-secondary-nav.tsx` + `lib/question-bank-nav.ts`.
 - **Folder-scoped header customize:** `components/question-bank-page-header.tsx`, `components/question-bank-client.tsx` — **`docs/question-bank-hub-header-pattern.md`**, **`.cursor/rules/exxat-question-bank-hub-header.mdc`**.

package/consumer-extras/patterns/data-views-pattern.md

@@ -18,6 +18,8 @@ This document describes how list pages combine **views**, **toolbar** behavior,
 | **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** |
 

package/consumer-extras/patterns/kpi-flat-band-pattern.md

@@ -0,0 +1,57 @@
+# KPI flat band (`KeyMetrics` `variant="flat"`)
+
+> **Component:** `components/key-metrics.tsx` — **`flatMetricsHairlineClass`**, **`flatBandStyle`**.  
+> **Tokens:** `app/globals.css` — `--key-metrics-flat-*`.  
+> **Cursor:** `.cursor/rules/exxat-kpi-flat-band.mdc` · `.cursor/skills/exxat-kpi-flat-band/SKILL.md`  
+> **Related:** `docs/kpi-strip-max-four-pattern.md`, `docs/kpi-trend-pattern.md`
+
+## Intent
+
+List hubs and the main dashboard mix view use **`KeyMetrics variant="flat"`** as a **metrics strip without a surface**: users see KPI copy and deltas on the **page canvas**, with a **brand-colored glow** under the band only. This is **not** a card, tinted panel, or `gap-px` grid fill.
+
+## MUST
+
+1. **No band surface** — The `<section>` background is **only** `var(--key-metrics-flat-band-radial)`. **Do not** stack `--key-metrics-flat-band-linear`, opaque gradients, or `box-shadow` fills that read as a grey/lavender box.
+2. **Transparent cells** — `metricsCellSurfaceClassName` is **`bg-transparent`** for `variant="flat"`. **Do not** use `bg-background`, `bg-card`, or `gap-px` + `bg-border` / `bg-foreground/*` on the grid (that paints tile surfaces).
+3. **Hairlines = borders only** — Use **`flatMetricsHairlineClass(itemCount, metricsHalfWidthLayout)`** in `key-metrics.tsx`:
+   - **2 tiles:** `border-r` on the first cell only.
+   - **4 tiles, wide strip (default):** `border-r` on cells 1–3 (verticals between all columns); **no** horizontal rule.
+   - **4 tiles, narrow `@container` (&lt; 30rem, 2×2 grid):** odd-column `border-r` + `border-b` on the top row only (via `@[max-width:29.99rem]` overrides).
+4. **Divider color (OKLCH)** — `--key-metrics-flat-divider: color-mix(in oklch, var(--sidebar-border) 55%, transparent)`; apply on children with `[&>*]:border-[color:var(--key-metrics-flat-divider)]`. Dividers follow **active product** hue (`--sidebar-border`), not neutral grey alone.
+5. **Glow (OKLCH)** — Radial stops use `color-mix(in oklch, var(--brand-color) …%, transparent)` so **Exxat One / Prism / Assessment / `theme-custom`** each tint correctly. **Do not** hardcode rose/indigo literals on theme blocks unless documenting a one-off.
+6. **List page usage** — Prefer **`showHeader={false}`**, **`metricsSingleRow`** when four KPIs share one row; pass **`insight`** only when the insight rail is product-required (same row uses `lg:grid-cols-[3fr_2fr]`).
+7. **Cap at four tiles** — See **`docs/kpi-strip-max-four-pattern.md`**.
+
+## MUST NOT
+
+- Add **`--key-metrics-flat-band-linear`** back into `flatBandStyle` or hub inline styles (e.g. question-bank 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`**.
+
+## Tokens (`app/globals.css`)
+
+| Token | Role |
+|--------|------|
+| `--key-metrics-flat-band-radial` | Bottom brand glow (only layer on flat `<section>`) |
+| `--key-metrics-flat-band-shadow` | **`none`** for flat band (no faux surface lift) |
+| `--key-metrics-flat-cell-bg` | **`transparent`** |
+| `--key-metrics-flat-divider` | OKLCH hairline between cells |
+
+Dark mode (`.dark`): same rules — transparent cells, radial glow only, no linear fill to `--background`.
+
+## Reference implementations
+
+- `components/question-bank-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
+
+## Insight rail (flat + side-by-side)
+
+When **`insight`** is shown beside KPIs, the insight **`Card`** may keep its own surface; the **KPI grid** stays transparent. **Do not** add `lg:border-l` on the insight column for flat band — the insight card ring is the separator (`key-metrics.tsx`).
+
+## See also
+
+- **`docs/kpi-strip-max-four-pattern.md`**
+- **`docs/kpi-trend-pattern.md`**
+- **`docs/shell-surface-elevation-pattern.md`** — sidebar / secondary panel / page stack

package/consumer-extras/patterns/shell-surface-elevation-pattern.md

@@ -0,0 +1,52 @@
+# Shell surface elevation (sidebar · secondary panel · page)
+
+> **Tokens:** `app/globals.css` — `--sidebar`, `--secondary-panel-bg`, `--background`, `--brand-tint*`.  
+> **Shell:** `components/templates/nested-secondary-panel-shell.tsx` — `bg-[var(--secondary-panel-bg)]`.  
+> **Cursor:** `.cursor/rules/exxat-primary-nav-secondary-panel.mdc` · `.cursor/skills/exxat-primary-nav-secondary-panel/SKILL.md`
+
+## Stack (back → front)
+
+| Level | Surface | Token / class | Notes |
+|-------|---------|---------------|--------|
+| **0** | Primary icon rail + app chrome | `--sidebar` (= `--brand-tint` on light product themes) | Darkest brand wash in the shell |
+| **1** | Nested secondary panel (Library, etc.) | `--secondary-panel-bg` | **Lighter** than level 0; **same product hue** |
+| **2** | Main page / inset content | `--background` | Lightest (white canvas light; dark charcoal dark) |
+
+**MUST** derive secondary panel fill from **`--brand-tint` / `--brand-tint-light`**, not a fixed rose or neutral grey. When the user selects **Exxat One**, both levels use **indigo hue ~286**; **Prism** uses **rose ~342**; **`theme-custom`** follows `--custom-product-brand-color` via `ProductProvider`.
+
+## OKLCH formulas (light)
+
+```css
+--sidebar: var(--brand-tint);
+--secondary-panel-bg: color-mix(in oklch, var(--background) 40%, var(--brand-tint-light) 60%);
+```
+
+## OKLCH formulas (dark)
+
+```css
+--secondary-panel-bg: color-mix(in oklch, var(--card) 32%, var(--brand-tint) 68%);
+```
+
+Per-product **dark** theme blocks (`.theme-one.dark`, `.theme-prism.dark`, …) set **`--brand-tint-light`** where needed so mixes stay on-hue.
+
+## Implementation
+
+- **`NestedSecondaryPanelShell`** — `bg-[var(--secondary-panel-bg)]`, `ring-sidebar-border` (not generic `ring-border` alone).
+- **Do not** set secondary panel to `bg-sidebar` (same as level 0 — loses elevation).
+- **Do not** use `color-mix(… var(--sidebar) …)` without brand tokens if it drifts from active product theme.
+
+## Product theme classes
+
+- **`theme-one`** / **`theme-prism`** / **`theme-assessment`** — built-in OKLCH brand scales in `globals.css`.
+- **`theme-custom`** — when user picks an accent in Settings; driven by `--custom-product-brand-color`.
+- **`ProductProvider`** — applies `theme-one` vs `theme-prism` vs `theme-custom`; accent override only when it **differs** from the product default (see `accentOverrideActive` in `contexts/product-context.tsx`).
+
+## Logo vs chrome
+
+- **Chrome** (sidebar, secondary panel, KPI glow) follows **`--brand-tint` / `--brand-color`** per product.
+- **Logo art** (mark + suffix) stays **Exxat pink** via `wordmarkColor` / `markGradient` in `lib/product-brand.ts` — recolouring a product in Settings changes **theme accent**, not corporate logo pink.
+
+## See also
+
+- **`docs/kpi-flat-band-pattern.md`** — flat KPI strip uses brand glow only, no surface
+- **`apps/web/AGENTS.md` §4.6** — secondary panel wiring

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exxatdesignux/ui",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "description": "Exxat shared design system (components, hooks, tokens). Monorepo setup: clone repo then pnpm bootstrap at workspace root — see github.com/ExxatDesign/Exxat-DS-Workspace README.",
   "type": "module",
   "engines": {
@@ -68,7 +68,7 @@
     "react-hook-form": "^7.72.0",
     "react-payment-inputs": "^1.2.0",
     "recharts": "^2.15.4",
-    "shadcn": "^4.1.0",
+    "shadcn": "^4.7.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.5.0",
     "tw-animate-css": "^1.4.0",
@@ -80,7 +80,7 @@
     "@tailwindcss/postcss": "^4.2.1",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "postcss": "^8",
+    "postcss": "^8.5.14",
     "tailwindcss": "^4.2.1",
     "typescript": "^5.9.3"
   },