@exxatdesignux/ui 0.2.17 → 0.2.19

package/CHANGELOG.md

@@ -15,6 +15,36 @@ After the user bumps `@exxatdesignux/ui`, do this in order:
 
 ---
 
+## [0.2.19] - 2026-05-19
+
+### Added
+
+- **Design tokens (CSS modules):** Split theme surface into `src/tokens/` (`base.css`, `themes.css`, `high-contrast.css`, `layers.css`, `tailwind-bridge.css`). Entry points `globals.css` / `theme.css` re-export only — **no token value changes**.
+- **Package export:** `@exxatdesignux/ui/tokens/*` for consumers that import token partials alongside Tailwind v4.
+
+### Changed
+
+- **Starter `template/`** and **consumer extras:** List hub shell, secondary panel registry, route-aware loading skeletons, focused-workflow settings layout, KPI flat band + shell elevation docs/skills — synced from `apps/web`.
+
+### Chore (monorepo)
+
+- Package **`version`** **0.2.19** — publish with tag **`ui-v0.2.19`**.
+
+## [0.2.18] - 2026-05-19
+
+### Fixed
+
+- **`Sidebar`**: Read `sidebar_state` on the server for `defaultOpen` so the documents **Resources** heading and rail chrome match the first client paint (fixes hydration warnings). Skip redundant cookie restore when state already matches.
+- **`TablePropertiesDrawer`**: Portaled **Add filter / sort / rule** menus use `z-[90]` above the properties sheet (`z-[80]`); `Sheet` and dropdowns use `modal={false}`; filter updates apply synchronously (no `startTransition` deferral). Drawer button routes column/display handlers through refs for the portaled sheet.
+
+### Changed
+
+- **Starter `template/`** and **consumer extras**: KPI flat band + shell surface elevation patterns/skills; table-properties and hub parity with `apps/web`.
+
+### Chore (monorepo)
+
+- Package **`version`** set to **0.2.18** for npm publish (tag **`ui-v0.2.18`**).
+
 ## [0.2.17] - 2026-05-18
 
 ### Changed

package/consumer-extras/AGENTS.md

@@ -0,0 +1,76 @@
+# Exxat DS — consumer app handbook
+
+**Purpose:** Guide for **product repositories** that depend on **`@exxatdesignux/ui`** from npm. The monorepo **`apps/web`** app is the full reference implementation; this file is what ships in the package for consumers.
+
+**Path after sync:** `docs/exxat-ds/AGENTS-consumer.md` or merge sections into your app handbook via **`exxat-ui sync-extras`**.
+
+---
+
+## 1. How to use this file (for AI agents)
+
+1. **Before** upgrading **`@exxatdesignux/ui`**, read **`consumer-upgrade-checklist.md`** and **`CHANGELOG.md`** in the installed package.
+2. **Before** adding a **list / table / board hub**, read **`data-views-pattern.md`** (view registry + connected bodies), **`consumer-app-pattern.md`**, and skill **`exxat-centralized-list-dataset`**.
+3. **Before** a **dedicated form / wizard / settings route**, read **`focused-workflow-page-pattern.md`** and **`exxat-focused-workflow-page`** skill.
+4. **Before** nested **Library / scope** nav, read **`exxat-primary-nav-secondary-panel`** skill and **`shell-surface-elevation-pattern.md`**.
+5. Run **`exxat-ui sync-extras`** after every DS version bump so **`.cursor/skills/exxat-*`** match the tarball.
+
+---
+
+## 2. What ships in the package
+
+| Artifact | Location in npm | Use |
+|----------|-----------------|-----|
+| Components + tokens | `@exxatdesignux/ui` | Import UI, hooks, CSS |
+| Reference app | `node_modules/@exxatdesignux/ui/template/` | Diff / port routes and hub clients |
+| Cursor skills | `consumer-extras/cursor-skills/` → sync to `.cursor/skills/` | AI checklists |
+| Pattern docs | `consumer-extras/patterns/` → sync to `docs/exxat-ds/` | Human + AI narrative |
+
+**`sync-extras` does not** modify your product routes — you port intentionally from **`template/`**.
+
+---
+
+## 3. List hub stack (centralized)
+
+**MUST:**
+
+- **`lib/mock/<entity>.ts`** — one row type + seed data.
+- **`lib/<hub>-supported-views.ts`** — allowlist shared by **`ListPageTemplate`** and **`TablePropertiesDrawer`**.
+- **`useTableState`** — **`tableState.rows`** feeds table, list, board, dashboard, folder, panel, tree.
+- **`ListPageConnectedViewBody`** + **`defineHubViewRenderers`** — no silent dashboard fallback.
+- **`ListPageViewFrame`** / **`components/data-views/`** for non-table bodies.
+
+**MUST NOT:** Second mock array per view; **`ListPageTemplate`** on a dedicated create/edit URL.
+
+**Rule/skill (sync from package):** `exxat-centralized-list-dataset`, `exxat-list-page-connected-views`, `exxat-list-page-view-shells`.
+
+---
+
+## 4. Shell elevation
+
+| Level | Token |
+|-------|--------|
+| Primary sidebar | `--sidebar` |
+| Secondary panel (Library) | `--secondary-panel-bg` |
+| Page | `--background` |
+
+Dark mode secondary panel **MUST** use **`color-mix(… var(--sidebar-accent) …)`**, not light **`--brand-tint`**. See **`shell-surface-elevation-pattern.md`**.
+
+---
+
+## 5. Consumer app checklist (copy for PRs)
+
+- [ ] **`@exxatdesignux/ui`** version recorded; **`exxat-ui sync-extras`** run if skills/docs changed.
+- [ ] Template diff reviewed for new **`template/`** files relevant to this feature.
+- [ ] List hub: **`supportedViewTypes`** aligned; **`ListPageConnectedViewBody`**; **`tableState.rows`** everywhere.
+- [ ] Form/wizard route: **`FocusedWorkflowPageTemplate`** (not list hub shell).
+- [ ] Secondary panel: **`--secondary-panel-bg`** on **`NestedSecondaryPanelShell`**; dark mode spot-checked.
+- [ ] Product switcher: collapsed sidebar opens menu (**`SidebarMenuButton` `tooltip`**, not nested Tooltip + DropdownMenu).
+- [ ] No toast — banners / inline / dialog.
+
+---
+
+## 6. See also
+
+- **`consumer-app-pattern.md`**
+- **`consumer-upgrade-checklist.md`**
+- Monorepo **`apps/web/AGENTS.md`** (full product handbook when you have the design-system repo)

package/consumer-extras/README.md

@@ -8,7 +8,9 @@ touching product routes or pages.
 |----------------------|-------------------------------------------|
 | `CHANGELOG.md` (package root) | Stay in `node_modules/…` — read for release notes; **`exxat-ui changelog`** prints it |
 | `cursor-skills/exxat-*` | `.cursor/skills/exxat-*` (replaced) |
-| `patterns/*.md` | `docs/exxat-ds/*.md` (replaced) — includes **`consumer-upgrade-checklist.md`** for upgrades + AI handoff |
+| `patterns/*.md` | `docs/exxat-ds/*.md` (replaced) — includes **`consumer-upgrade-checklist.md`**, **`consumer-app-pattern.md`**, view-registry + shell docs |
+| `AGENTS.md` (this folder) | Copy or merge into your app handbook as **`AGENTS-consumer.md`** |
+| `cursor-skills/exxat-consumer-app` | Consumer-repo checklist (npm install, template diff) |
 
 **Components and hooks** still come only from `node_modules/@exxatdesignux/ui`
 via normal semver installs — `sync-extras` does not copy TS source into your app.
@@ -20,3 +22,5 @@ pnpm --filter @exxatdesignux/ui vendor:consumer-extras
 ```
 
 …then bump `packages/ui` version and publish so consumers get the new bundle.
+
+**List-page stack** (registry, `ListPageConnectedViewBody`, `supportedViewTypes`) lives in **`template/`** inside the tarball — not in `@exxatdesignux/ui` component exports. After changing **`apps/web`** or **`packages/ui/template`**, diff both trees and re-publish so consumer apps that copy from **`node_modules/@exxatdesignux/ui/template/`** stay aligned.

package/consumer-extras/cursor-skills/exxat-centralized-list-dataset/SKILL.md

@@ -60,7 +60,18 @@ Goal: **one row model**, **one filtered bag** (`tableState.rows`), **one place f
 
 ---
 
-## 6. Implementation checklist (new hub or new view)
+## 6. View registry + connected body (required)
+
+- [ ] **`lib/<hub>-supported-views.ts`** — same array on **`ListPageTemplate`** (`supportedViewTypes`) and **`TablePropertiesDrawerButton`**.
+- [ ] **`ListPageConnectedViewBody`** + **`defineHubViewRenderers(supported, { … })`** — one renderer per **`DataListViewRenderKind`**; missing → **`ListPageViewNotConfigured`** (never silent dashboard).
+- [ ] Branch on **`getDataListViewRenderKind(view)`** via the connected body — not long **`if (view === "table")`** chains in the table file.
+- [ ] **`lib/data-list-view-registry.ts`** — labels/icons/render kinds stay centralized.
+
+**Canon:** `docs/data-views-pattern.md` § “View registry and connected bodies”, **`AGENTS.md` §4.1.1**.
+
+---
+
+## 7. Implementation checklist (new hub or new view)
 
 - [ ] Exactly **one** primary row array shape in **`lib/mock/<entity>.ts`** (or API).
 - [ ] **`useTableState`** seeded from that array; **child views** receive **`tableState.rows`** (or equivalent), **not** a fresh import of the mock list.
@@ -72,7 +83,7 @@ Goal: **one row model**, **one filtered bag** (`tableState.rows`), **one place f
 
 ---
 
-## 7. Reference implementations
+## 8. Reference implementations
 
 - **`components/data-list-client.tsx`** + **`data-list-table.tsx`** — Placements pattern.
 - **`components/team-client.tsx`** + **`team-table.tsx`**.
@@ -80,7 +91,7 @@ Goal: **one row model**, **one filtered bag** (`tableState.rows`), **one place f
 
 ---
 
-## 8. Centralized presentation (with the same dataset)
+## 9. Centralized presentation (with the same dataset)
 
 **Layout:** Non-table view branches wrap in **`ListPageViewFrame`** (constants in **`list-page-view-frame.tsx`**) — see **`.cursor/rules/exxat-list-page-view-shells.mdc`**.
 

package/consumer-extras/cursor-skills/exxat-consumer-app/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: exxat-consumer-app
+description: Build or upgrade product apps that install @exxatdesignux/ui from npm — sync-extras, diff template/, centralized list hubs, focused workflow routes, shell elevation. Use when working outside the design-system monorepo or after pnpm add @exxatdesignux/ui.
+user-invocable: true
+---
+
+# Exxat DS — consumer app
+
+**Pattern:** `consumer-app-pattern.md` (in `docs/exxat-ds/` after sync)  
+**Handbook:** `AGENTS-consumer.md` or `consumer-app-pattern.md` parent **`AGENTS.md`** in package extras  
+**Upgrade:** `consumer-upgrade-checklist.md`
+
+## When this applies
+
+- Repo has **`@exxatdesignux/ui`** in **`package.json`**, not the design-system monorepo **`apps/web`**.
+- Task is **porting** a hub, shell, or route from **`node_modules/@exxatdesignux/ui/template/`**.
+
+## Checklist
+
+- [ ] Read installed **`CHANGELOG.md`**; run **`exxat-ui sync-extras`** after bump.
+- [ ] Diff **`template/`** vs your app for the feature (client, table, mocks, layout).
+- [ ] **List hub:** `lib/<hub>-supported-views.ts` + **`ListPageConnectedViewBody`** + **`defineHubViewRenderers`** + one **`useTableState`** row bag.
+- [ ] **Same** `supportedViewTypes` on **`ListPageTemplate`** and **`TablePropertiesDrawer`**.
+- [ ] **Form/wizard/settings URL:** **`FocusedWorkflowPageTemplate`** — not **`ListPageTemplate`**.
+- [ ] **Secondary panel:** `NestedSecondaryPanelShell` + **`--secondary-panel-bg`**; verify **dark mode** (no light rose panel).
+- [ ] **Product switcher (collapsed):** `DropdownMenuTrigger` → **`SidebarMenuButton`** with **`tooltip=`** — do not nest **`Tooltip`** outside **`DropdownMenuTrigger`**.
+- [ ] CSS: import DS globals; product theme classes on **`<html>`** via **`ProductProvider`** pattern from template.
+
+## MUST NOT
+
+- Fork **`DataTable`** / view-tab stack when template already has the hub pattern.
+- Import raw **`ENTITY_ROWS`** into folder/board views while the table filters **`useTableState`**.
+- Skip **`exxat-ui sync-extras`** and rely on stale **`.cursor/skills`**.
+
+## Pair with
+
+- **`exxat-centralized-list-dataset`**, **`exxat-list-page-view-shells`**, **`exxat-focused-workflow-page`**, **`exxat-primary-nav-secondary-panel`**

package/consumer-extras/cursor-skills/exxat-ds-skill/SKILL.md

@@ -21,7 +21,7 @@ description: >
 - **Stack:** Next.js 16 (App Router), React, TypeScript, Tailwind CSS, shadcn/ui primitives, Font Awesome icons
 - **App root:** `exxat-ds/app/(app)/` — route group that wraps all authenticated pages
 - **Single source of truth:** `exxat-ds/AGENTS.md` for full prose explanations; this skill is the actionable summary
-- **Companion skills (narrow topics):** `exxat-fontawesome-icons`, `exxat-mono-ids`, `exxat-primary-nav-secondary-panel`, `exxat-centralized-list-dataset`, `exxat-list-page-view-shells`, `exxat-dedicated-search-surfaces`, `exxat-accessibility`, `exxat-board-cards`, `exxat-collaboration-access` — live under `.cursor/skills/`; vetted copies ship with **`@exxatdesignux/ui`** in `consumer-extras/cursor-skills/` after **`pnpm --filter @exxatdesignux/ui vendor:consumer-extras`**.
+- **Companion skills (narrow topics):** `exxat-fontawesome-icons`, `exxat-mono-ids`, `exxat-primary-nav-secondary-panel`, `exxat-centralized-list-dataset`, `exxat-list-page-view-shells`, `exxat-dedicated-search-surfaces`, `exxat-focused-workflow-page`, `exxat-accessibility`, `exxat-board-cards`, `exxat-collaboration-access` — live under `.cursor/skills/`; vetted copies ship with **`@exxatdesignux/ui`** in `consumer-extras/cursor-skills/` after **`pnpm --filter @exxatdesignux/ui vendor:consumer-extras`**.
 - **Question bank folder-scoped header (rule + doc):** **`.cursor/rules/exxat-question-bank-hub-header.mdc`** and **`docs/question-bank-hub-header-pattern.md`** — pair with **`exxat-primary-nav-secondary-panel`** when URL **`scope=folder`** drives the hub title.
 - **Consumer repos (npm install of `@exxatdesignux/ui`):** After a version bump, read **`node_modules/@exxatdesignux/ui/CHANGELOG.md`**, run **`npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras`** so **`docs/exxat-ds/consumer-upgrade-checklist.md`** and Cursor skills match the tarball, and diff the host app against **`node_modules/@exxatdesignux/ui/template/`** for anything new to port (routes, re-exports, AGENTS). Use **`exxat-ui changelog`**, **`exxat-ui update`**, and **`exxat-ui doctor`** for CLI guidance.
 
@@ -259,8 +259,21 @@ ListPageTemplate
 ```
 
 **Reference implementations:**
-- `components/team-client.tsx` + `components/team-table.tsx` — canonical pattern
-- `components/data-list-client.tsx` + `components/data-list-table.tsx` — Placements (most complete)
+- **`apps/web`:** `components/list-hub-client.tsx` + `list-hub-table.tsx`, `question-bank-client.tsx` + `question-bank-table.tsx`
+- **`packages/ui/template/`** (ships with npm): `placements-client.tsx` + `placements-table.tsx`, `team-client.tsx` + `team-table.tsx` — diff template on upgrade
+
+### 4.1 View registry (do not fork `if (view === …)`)
+
+1. **`lib/data-list-view.ts`** — `DATA_LIST_VIEW_TILES` (labels/icons).
+2. **`lib/data-list-view-registry.ts`** — `renderKind`, `showsListPageHubMetricsStrip`, `dataListViewTilesForHub`.
+3. **`lib/foo-supported-views.ts`** — `export const FOO_SUPPORTED_VIEWS = ["table", "list", …] as const`.
+4. **`ListPageTemplate`** — `supportedViewTypes={FOO_SUPPORTED_VIEWS}`.
+5. **`foo-table.tsx`** — `ListPageConnectedViewBody` with renderers per kind; **`TablePropertiesDrawerButton`** gets the same **`supportedViewTypes`**.
+6. Generic bodies under **`components/data-views/`** — calendar, board template, folder grid, etc.
+
+**MUST NOT** default unknown views to dashboard KPIs — missing renderers use **`ListPageViewNotConfigured`**.
+
+**Narrative:** `docs/data-views-pattern.md` § “View registry and connected bodies”.
 
 **Files to create for a new hub page `Foo`:**
 | File | Purpose |
@@ -268,8 +281,9 @@ ListPageTemplate
 | `lib/mock/foo.ts` | Mock data + TypeScript interface (12+ rows) |
 | `lib/mock/foo-kpi.ts` | `fooKpiMetrics()` + `fooKpiInsight()` |
 | `components/foo-page-header.tsx` | `PageHeader` + primary CTA + ⋯ menu |
-| `components/foo-table.tsx` | `DataTable` + `useTableState` + `TablePropertiesDrawer` |
-| `components/foo-client.tsx` | `ListPageTemplate` orchestrator |
+| `lib/foo-supported-views.ts` | Views this hub implements (registry allowlist) |
+| `components/foo-table.tsx` | `ListPageConnectedViewBody` + `DataTable` + `useTableState` + Properties |
+| `components/foo-client.tsx` | `ListPageTemplate` + `supportedViewTypes` |
 | `app/(app)/foo/page.tsx` | Thin server component |
 
 **Do not** ship a **nav-linked hub** as an **empty page** or a single “replace this later” paragraph. If the route appears in **`lib/mock/navigation.tsx`**, implement the full hub (mock rows, **`ListPageTemplate`**, connected views per **`exxat-ds/AGENTS.md` §4.1**) unless the product explicitly defines a non-data shell.
@@ -279,8 +293,9 @@ ListPageTemplate
 - **Drawer / sheet** — Use when the user needs **the current page behind them** *and* a **quick view**, **quick actions**, or a **short step** (e.g. properties, export, glance at a row).
 - **Dialog** — **Blocking** confirm/alert/short choice — **`docs/drawer-vs-dialog-pattern.md`**, **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**.
 - **New page** — Use **otherwise**: **primary**, **long-form**, **multi-step**, or flows that need their **own URL** without the hub visible.
+- **Focused workflow route** — **`FocusedWorkflowPageTemplate`** + **`FocusedWorkflowSingleColumn`** | **`FocusedWorkflowStepForm`** | **`FocusedWorkflowSidebarSections`** | **`FocusedWorkflowEmptyState`** — **`docs/focused-workflow-page-pattern.md`**, **`AGENTS.md` §14**, **`exxat-focused-workflow-page`** skill. **Not** list hubs; **not** Miller columns.
 
-Align with **`exxat-ds/AGENTS.md` §6.4**, **`docs/data-views-pattern.md`**, **`docs/drawer-vs-dialog-pattern.md`**, **`.cursor/rules/exxat-page-vs-drawer.mdc`**, **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**.
+Align with **`exxat-ds/AGENTS.md` §6.4**, **§14**, **`docs/data-views-pattern.md`**, **`docs/drawer-vs-dialog-pattern.md`**, **`docs/focused-workflow-page-pattern.md`**, **`.cursor/rules/exxat-page-vs-drawer.mdc`**, **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**, **`.cursor/rules/exxat-focused-workflow-page.mdc`**.
 
 ---
 
@@ -551,7 +566,7 @@ import { DropdownMenuItem, Shortcut } from "@/components/ui/dropdown-menu"
 | Duplicate | ⌘/Ctrl + D |
 | Review / Info | ⌘/Ctrl + I |
 | Remove / Delete item | ⌘/Ctrl + ⌫ |
-| Add view (1..n) | ⌘/Ctrl + ⇧/Shift + 1..9 |
+| Add view (1..n) | **1..9** (plain digit; `dataListViewAddShortcut`) |
 | **Submit a workflow** (Create, Save, Export, Apply) | **Enter** ⏎ — scoped to the open form/drawer/dialog |
 | **Cancel / dismiss** a workflow | **Esc** (Radix Dialog/Sheet/AlertDialog already bind this) |
 | **Advance a multi-step wizard** | ⌘/Ctrl + Enter (plain Enter must not submit mid-flow) |

package/consumer-extras/cursor-skills/exxat-focused-workflow-page/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: exxat-focused-workflow-page
+description: FocusedWorkflowPageTemplate — dedicated routes for large forms, multi-step wizards, and sectioned settings (single column, steps, sidebar nav). Not list hubs or Miller-column explorers. Use when adding create/edit routes, settings pages, or empty workflow placeholders.
+user-invocable: true
+---
+
+# Exxat DS — focused workflow page
+
+**Rule:** `.cursor/rules/exxat-focused-workflow-page.mdc`  
+**Doc:** `docs/focused-workflow-page-pattern.md` (app / consumer-extras `patterns/`)  
+**Handbook:** `AGENTS.md` §6.4, **§14** checklist
+
+## When to use
+
+| Use **focused workflow** | Use something else |
+| --- | --- |
+| Own URL; primary create/edit; multi-step wizard; sectioned settings | **List hub** → `ListPageTemplate` + `DataTable` |
+| Large form that should not sit in a drawer | **Quick hub adjunct** → drawer (`ExportDrawer`, `TablePropertiesDrawer`) |
+| | **Blocking confirm** → dialog |
+| | **Finder / folder columns** → `ListPageSplitHubChrome`, `ListPageFolderColumnsPanel` |
+
+## Checklist
+
+- [ ] Route uses **`FocusedWorkflowPageTemplate`** — not raw `SidebarInset` copy-paste; not **`PrimaryPageTemplate`** / **`ListPageTemplate`**.
+- [ ] **`siteHeader`**: `back` or `breadcrumbs` + `title`; parent trail stays in header, not duplicated in body.
+- [ ] **`maxWidth`**: `md` simple forms · `lg` settings / wide fields · `xl` only when justified.
+- [ ] **One body layout** from `focused-workflow-layouts.tsx`:
+  - **`FocusedWorkflowSingleColumn`** — default stack
+  - **`FocusedWorkflowStepForm`** + **`FocusedWorkflowWizardFooter`** — wizard
+  - **`FocusedWorkflowSidebarSections`** — left section nav (`id` on `<section>` matches `sections[].id`)
+  - **`FocusedWorkflowEmptyState`** — not configured / coming soon
+- [ ] **Footers:** **`FocusedWorkflowActionFooter`** or **`FocusedWorkflowWizardFooter`** with **`Shortcut`** + **`<Kbd variant="bare">`** in buttons (**`exxat-kbd-shortcuts.mdc`**).
+- [ ] Domain UI in **`*-composer.tsx`** / **`*-client.tsx`**; keep **`FocusedWorkflow*`** names generic (not product-specific).
+- [ ] Long forms: optional **`beforeSiteHeader={<SidebarAutoCollapse />}`** (see `/question-bank/new`).
+- [ ] **No** **`ListPageTemplate`** view tabs, **no** Miller columns, **no** **`ListPageFolderColumnsPanel`** inside this shell.
+- [ ] **No toast** for outcomes — banners, inline, or dialog (**`exxat-no-toast.mdc`**).
+
+## MUST NOT
+
+- Ship a **full create/edit wizard** only in a drawer when it needs bookmarkable URL / long focus.
+- Use **`ListPageTemplate`** for a dedicated “new record” route.
+- Name shared templates after one feature (`NewQuestionPageTemplate`, etc.).
+
+## Code pointers
+
+| Piece | Path |
+| --- | --- |
+| Shell | `components/templates/focused-workflow-page-template.tsx` |
+| Layouts + footers | `components/templates/focused-workflow-layouts.tsx` |
+| Showcase | `components/examples/focused-workflow-showcase.tsx`, `/examples/focused-workflow` |
+| Single column | `app/(app)/question-bank/new/page.tsx` + `new-question-composer.tsx` |
+| Sidebar sections | `app/(app)/settings/page.tsx` + `settings-client.tsx` |
+
+## Pair with
+
+- **`exxat-page-vs-drawer`**, **`exxat-drawer-vs-dialog`**, **`exxat-kbd-shortcuts`**
+- **`exxat-reuse-before-custom`** — extend layouts before forking shell markup

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-primary-nav-secondary-panel/SKILL.md

@@ -12,17 +12,19 @@ user-invocable: true
 ## Wiring checklist
 
 1. **`lib/mock/navigation.tsx`** — set **`secondaryPanel: "<id>"`** on the primary **`NavLinkItem`**; **`url`** = hub route.
-2. **`components/secondary-panel.tsx`** — add **`PANELS["<id>"]`** → panel shell (title, optional search) + secondary nav component.
+2. **`components/secondary-panels/registry.tsx`** — add **`SECONDARY_PANELS["<id>"]`** → panel shell (title) + hub-specific nav component (e.g. **`list-hub-panel.tsx`**, **`question-bank-panel.tsx`**). Do not add new hubs inside **`question-bank-*.tsx`**.
 3. **Hub client** — mount **`*PanelActivator`** with **`useAutoPanel("<id>")`** (same id) for the lifetime of the route (e.g. `QuestionBankPanelActivator`).
 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
 
@@ -37,8 +39,13 @@ Custom panel content (anything you register under `PANELS[id]`) should **read `s
 ## Reference
 
 - `components/app-sidebar.tsx` — `openPanel` on same-route primary click.
-- `components/secondary-panel.tsx` — `SecondaryPanelProvider`, `PANELS` registry, **high-zoom auto-collapse**.
+- `components/secondary-panel.tsx` — `SecondaryPanelProvider`, **high-zoom auto-collapse**.
+- `components/secondary-panels/registry.tsx` — **`SECONDARY_PANELS`** map (`question-bank`, `list-hub`, …).
+- `lib/list-hub-nav.ts` + `components/list-hub-secondary-nav.tsx` — second hub reference implementation.
 - `hooks/use-sidebar-reflow-zoom.ts` — shared zoom / reflow signal.
-- `components/templates/nested-secondary-panel-shell.tsx` — expanded vs `compact` (icon rail) widths.
+- `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/consumer-app-pattern.md

@@ -0,0 +1,39 @@
+# Consumer app pattern (`@exxatdesignux/ui`)
+
+> **Audience:** Product repos that **install** the design system from npm — not the `apps/web` monorepo reference app.  
+> **Handbook:** `packages/ui/consumer-extras/AGENTS.md` · **Upgrade:** `consumer-upgrade-checklist.md` · **Skill:** `.cursor/skills/exxat-consumer-app/SKILL.md`
+
+## Intent
+
+A **consumer app** composes **`@exxatdesignux/ui`** primitives and copies **patterns** from the published **`template/`** tree. It does **not** fork parallel table stacks, view routers, or shell tokens.
+
+## MUST
+
+1. **Install** — `@exxatdesignux/ui` + peers; import DS CSS once (`@exxatdesignux/ui/globals.css` or documented entry).
+2. **Sync extras** — After version bumps: `npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras` → `.cursor/skills/exxat-*` + `docs/exxat-ds/*.md`.
+3. **Diff template** — Compare `node_modules/@exxatdesignux/ui/template/` for new files (layouts, `ListPageConnectedViewBody`, `FocusedWorkflowPageTemplate`, mocks).
+4. **List hubs** — One **`useTableState`** row bag; **`ListPageConnectedViewBody`** + **`defineHubViewRenderers`**; same **`supportedViewTypes`** on **`ListPageTemplate`** and **`TablePropertiesDrawer`**.
+5. **Shell tokens** — Sidebar / secondary panel / page elevation via **`--sidebar`**, **`--secondary-panel-bg`**, **`--background`** — see **`shell-surface-elevation-pattern.md`**.
+6. **Focused workflows** — Dedicated create/edit/settings routes use **`FocusedWorkflowPageTemplate`** — **`focused-workflow-page-pattern.md`**.
+
+## MUST NOT
+
+- Copy only components without porting **AGENTS**, **rules**, and **pattern docs** when behavior changes.
+- Ship hub view tabs with long **`if (view === "table")`** chains instead of **`ListPageConnectedViewBody`**.
+- Keep a second mock array per view while the grid uses **`useTableState`**.
+- Set secondary panel to **`bg-sidebar`** or light **`--brand-tint`** mixes in dark mode.
+
+## Checklist (new consumer feature)
+
+- [ ] Read **`consumer-upgrade-checklist.md`** for the installed UI version.
+- [ ] Run **`exxat-ui sync-extras`** if skills/patterns are stale.
+- [ ] Find the closest **`template/`** hub or page; port file names and imports to your app paths.
+- [ ] **List hub:** `lib/<hub>-supported-views.ts`, `lib/data-list-view-registry.ts`, `ListPageConnectedViewBody`, centralized **`tableState.rows`**.
+- [ ] **Form route:** `FocusedWorkflowPageTemplate` + one body layout from **`focused-workflow-layouts.tsx`**.
+- [ ] **Nav + secondary panel:** `secondaryPanel` on nav item, `PANELS` registry, `useAutoPanel` — **`exxat-primary-nav-secondary-panel`** skill.
+- [ ] Re-run **`fa:subset-audit`** when adding Font Awesome glyphs.
+
+## See also
+
+- Monorepo reference: `apps/web/` (full product demo)
+- **`.cursor/rules/exxat-consumer-app.mdc`** (when working inside a consumer repo that synced rules)

package/consumer-extras/patterns/consumer-upgrade-checklist.md

@@ -25,6 +25,26 @@ The npm package includes a full Next.js reference under:
 
 Use it when you need to know **what files exist**, **how shims re-export** `@exxatdesignux/ui`, or **what AGENTS / layout** patterns look like for the current release. Porting is manual: diff template vs your repo and apply intentional changes (imports, new components, CSS entrypoints).
 
+### List-page view registry (required for data hubs)
+
+After upgrading, confirm each hub table uses **`ListPageConnectedViewBody`** (not long **`if (view === …)`** chains) and that these stay aligned:
+
+| File | Purpose |
+|------|---------|
+| `lib/data-list-view-registry.ts` | Render kinds + hub KPI strip rules |
+| `lib/<hub>-supported-views.ts` | What the hub can add/switch to |
+| `components/templates/list-page.tsx` | `supportedViewTypes` on Add view + shortcuts |
+| `components/data-views/list-page-connected-view-body.tsx` | View router |
+| `lib/hub-connected-view-renderers.ts` | **`defineHubViewRenderers(supported, { … })`** — dev warnings when a supported view has no body |
+| `components/data-views/list-page-folder-columns-panel.tsx` | Generic Miller columns for **panel** view (hub wrapper for QB colors/actions) |
+
+Pass the **same** `supportedViewTypes` array to **`ListPageTemplate`** and **`TablePropertiesDrawerButton`**. Wrap hub renderers with **`defineHubViewRenderers`**. Import **question-bank-only** tree/folder nav from hub files, not the generic **`data-views`** barrel. See **`docs/exxat-ds/data-views-pattern.md`** § “View registry and connected bodies” and **`consumer-app-pattern.md`** for the full consumer-app checklist.
+
+### Shell + sidebar (after DS token changes)
+
+- [ ] Dark mode **secondary panel** uses **`--secondary-panel-bg`** from DS globals (sidebar-accent mix) — spot-check Question bank **Library** rail.
+- [ ] Collapsed **product switcher** — **`SidebarMenuButton` `tooltip=`** + **`DropdownMenuTrigger`** only (no outer **`Tooltip`** wrapping the trigger).
+
 ## 4. Dependency and Node
 
 - Keep **`@exxatdesignux/ui`** on the same semver your team tested; prefer explicit **`^x.y.z`** or pinned **`x.y.z`**.

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** |
 
@@ -36,6 +38,41 @@ 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`.
@@ -144,11 +181,13 @@ 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.
 
-**Rule of thumb:** **Context + quick** → **drawer**; **blocking short choice** → **dialog**; **otherwise** → **new page**.
+**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).
 
 **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**, root **`.cursor/rules/exxat-page-vs-drawer.mdc`**, **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**.
+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`**.
 
 ---
 
@@ -168,7 +207,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 → **new route** (`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 → **focused workflow route** (`docs/focused-workflow-page-pattern.md`, **§14**) or other dedicated page (`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).