@exxatdesignux/ui 0.2.18 → 0.2.19

package/CHANGELOG.md

@@ -15,6 +15,21 @@ 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

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`**.
 
 ---
 

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

@@ -12,7 +12,7 @@ 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`**.
@@ -39,7 +39,9 @@ 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; **`bg-[var(--secondary-panel-bg)]`**.
 - `app/globals.css` — `--secondary-panel-bg`, `--sidebar`, product **`theme-one`** / **`theme-prism`** blocks.

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

@@ -38,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`.
@@ -146,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`**.
 
 ---
 
@@ -170,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).

package/consumer-extras/patterns/focused-workflow-page-pattern.md

@@ -0,0 +1,84 @@
+# Focused workflow page (dedicated routes)
+
+> **Related:** **`AGENTS.md` §6.4** (page vs drawer vs dialog), **§14** (AI checklist), **`docs/drawer-vs-dialog-pattern.md`**, **`.cursor/rules/exxat-page-vs-drawer.mdc`**, **`.cursor/rules/exxat-focused-workflow-page.mdc`**, **`.cursor/skills/exxat-focused-workflow-page/SKILL.md`**.
+
+## Intent
+
+Use **`FocusedWorkflowPageTemplate`** for **large or multi-step work** on its **own route** — create/edit forms, wizards, and sectioned settings. The shell is **narrower** than list hubs and **does not** use Miller-column / split-panel explorers.
+
+| Surface | Use instead |
+| --- | --- |
+| Browsable record hubs (table, board, dashboard tabs) | **`PrimaryPageTemplate`** + **`ListPageTemplate`** |
+| Finder / folder columns / split hub chrome | **`ListPageSplitHubChrome`**, **`ListPageFolderColumnsPanel`** |
+| Quick properties or export beside a grid | **Drawer** (`TablePropertiesDrawer`, `ExportDrawer`) |
+| Blocking confirm on the same route | **Dialog** |
+
+## Surface matrix (§6.4)
+
+| Need | Drawer | Dialog | **Focused workflow route** |
+| --- | --- | --- | --- |
+| Keep hub visible while acting | Yes | No | No |
+| Own URL / bookmark / history | Rare | No | **Yes** |
+| Multi-step wizard | Cramped | No | **Yes** |
+| Sectioned settings (left nav) | Awkward | No | **Yes** |
+| Short delete confirm | No | **Yes** | Overkill |
+
+## Shell
+
+**`FocusedWorkflowPageTemplate`** (`components/templates/focused-workflow-page-template.tsx`):
+
+- **`SidebarInset`** + **`SiteHeader`** (breadcrumb back link + title).
+- Centered column: **`max-w-3xl` / `max-w-4xl` / `max-w-5xl`** via **`maxWidth`** (`md` | `lg` | `xl`).
+- Default padding: **`FOCUSED_WORKFLOW_CONTENT_PADDING_CLASS`**.
+
+Optional **`beforeSiteHeader`** (e.g. **`SidebarAutoCollapse`** on long forms).
+
+## Body layouts
+
+Import from **`components/templates/focused-workflow-layouts.tsx`**:
+
+| Layout | When |
+| --- | --- |
+| **`FocusedWorkflowSingleColumn`** | Default stack — header, form sections, footer actions (e.g. question authoring). |
+| **`FocusedWorkflowStepForm`** + **`FocusedWorkflowWizardFooter`** | Multi-step wizard with progress list and sticky footer (placement-style flows). |
+| **`FocusedWorkflowSidebarSections`** | Sectioned form with **left nav rail** (settings-style); put **`id`** on each `<section>` matching **`sections[].id`**. |
+| **`FocusedWorkflowEmptyState`** | Placeholder / not-yet-configured route body. |
+| **`FocusedWorkflowActionFooter`** | Single-step Cancel (Esc) + primary (Enter) without step chrome. |
+
+Keyboard: wizard and action footers pair **`Shortcut`** with inline **`<Kbd variant="bare">`** per **`.cursor/rules/exxat-kbd-shortcuts.mdc`**.
+
+## Golden references
+
+| Route | Variant |
+| --- | --- |
+| **`/question-bank/new`** | Shell + **`FocusedWorkflowSingleColumn`** + domain composer |
+| **`/settings`** | Shell (`maxWidth="lg"`) + **`FocusedWorkflowSidebarSections`** |
+| **`/examples/focused-workflow`** | Showcase: empty, steps, sidebar (toggle) |
+
+## Wiring checklist (implementers)
+
+1. **Route** under **`app/(app)/…/page.tsx`** — thin server page; heavy UI in a **client** component.
+2. **`siteHeader`**: **`back`** or **`breadcrumbs`** + **`title`**; avoid duplicating the trail in the body.
+3. Pick **`maxWidth`**: **`md`** for simple forms, **`lg`** for settings / wide fields.
+4. Choose **one** body layout; do **not** nest Miller columns or **`ListPageTemplate`** view tabs inside this shell.
+5. Domain logic stays in **`*-composer.tsx`** / **`*-client.tsx`**; templates stay generic **`FocusedWorkflow*`**.
+6. Run **§14** in **`AGENTS.md`** when reviewing.
+
+## AI execution checklist (copy for PRs)
+
+- [ ] **`FocusedWorkflowPageTemplate`** on the route — not ad-hoc **`SidebarInset`** / list-hub shell.
+- [ ] Correct body variant: **single column** | **step form** | **sidebar sections** | **empty**.
+- [ ] Wizard/action footers use **`Shortcut`** + bare **`Kbd`** in buttons.
+- [ ] **No** list-hub view tabs, **no** folder-column explorer inside the page.
+- [ ] Template/component names remain **generic** (not tied to one entity).
+- [ ] **§6.5** — no toast for product feedback.
+
+## Pair with
+
+- **`exxat-page-vs-drawer.mdc`**, **`exxat-drawer-vs-dialog.mdc`**, **`exxat-kbd-shortcuts.mdc`**
+- **`exxat-reuse-before-custom.mdc`** — extend **`focused-workflow-layouts.tsx`** before forking a second shell
+
+## See also
+
+- **`components/examples/focused-workflow-showcase.tsx`**
+- **`packages/ui/consumer-extras/patterns/focused-workflow-page-pattern.md`** (npm consumers)

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

@@ -1,7 +1,7 @@
 # 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)]`.  
+> **Shell:** `components/templates/nested-secondary-panel-shell.tsx` — `bg-secondary-panel-bg` + `[data-slot="secondary-panel"]` rule in `globals.css`.  
 > **Cursor:** `.cursor/rules/exxat-primary-nav-secondary-panel.mdc` · `.cursor/skills/exxat-primary-nav-secondary-panel/SKILL.md`
 
 ## Stack (back → front)
@@ -24,14 +24,16 @@
 ## OKLCH formulas (dark)
 
 ```css
---secondary-panel-bg: color-mix(in oklch, var(--card) 32%, var(--brand-tint) 68%);
+--secondary-panel-bg: color-mix(in oklch, var(--background) 32%, var(--sidebar-accent) 68%);
 ```
 
+**Do not** mix with light-mode **`--brand-tint`** in dark — product theme classes keep a light **`--brand-tint`** for logos/KPI glow; the secondary rail must use **`--sidebar-accent`** so the Library panel stays on-hue and dark.
+
 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).
+- **`NestedSecondaryPanelShell`** — `bg-secondary-panel-bg` (token + `[data-slot="secondary-panel"][data-state="open"]` in `globals.css`), `border-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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exxatdesignux/ui",
-  "version": "0.2.18",
+  "version": "0.2.19",
   "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": {
@@ -27,6 +27,7 @@
     },
     "./globals.css": "./src/globals.css",
     "./theme.css": "./src/theme.css",
+    "./tokens/*": "./src/tokens/*",
     "./components/*": {
       "types": "./src/components/ui/*.tsx",
       "import": "./src/components/ui/*.tsx",