@exxatdesignux/ui 0.2.17 → 0.2.19

package/template/AGENTS.md

@@ -24,18 +24,21 @@ Cross-cutting Cursor rules also live in the repo root `.cursor/rules/` (data tab
 12. **Before** adding **onboarding tours, feature walkthroughs, or coach marks**, read **§11** and `references/coach-marks.md`.
 13. **Before** changing the **global command palette (⌘K)** or search/AI entry UX, read **§7.1** and **`docs/command-menu-pattern.md`**.
 14. **Before** choosing **drawer vs dialog vs new page** for a task flow, read **§6.4**, **`docs/data-views-pattern.md`** (Page vs drawer), and **`docs/drawer-vs-dialog-pattern.md`** (modal vs side panel on the same route).
-15. **Before** adding **success/error/confirmation feedback**, read **§6.5** and **`.cursor/rules/exxat-no-toast.mdc`** (no toast or snackbars).
-16. Prefer **composing existing components** over new one-off UI. If something is missing, **extend** shared components under `components/`, not a single page file.
+15. **Before** adding or changing a **dedicated form, wizard, or sectioned settings route**, read **`docs/focused-workflow-page-pattern.md`**, **`.cursor/rules/exxat-focused-workflow-page.mdc`**, **`.cursor/skills/exxat-focused-workflow-page/SKILL.md`**, and run **§14** checklist.
+16. **Before** adding **success/error/confirmation feedback**, read **§6.5** and **`.cursor/rules/exxat-no-toast.mdc`** (no toast or snackbars).
+17. Prefer **composing existing components** over new one-off UI. If something is missing, **extend** shared components under `components/`, not a single page file.
     - **MUST** scan `components/` (especially `components/ui/`, `components/data-views/`, `components/templates/`, `components/key-metrics.tsx`, `components/page-header.tsx`, and the charts/banner/dot-pattern surfaces) **before** writing any new UI. If a primitive or composition already exists, **use it** — don't build a parallel one.
-    - **Examples of existing surfaces to reuse:** card grid → `ListPageBoardCard` + `BoardCardIconRow` / `BoardCardTwoLineBlock`; AI / dot animation → `AiThinkingOverlay` + `DotPattern`; search input → `InputGroup` + `InputGroupAddon` + `InputGroupInput`; page title → `PageHeader` (serif via `font-heading`); list hub shell → `ListPageTemplate` (`metrics`, `defaultTabs`, `renderContent`); metrics strip → `KeyMetrics`; **view body gutter + centered max-width** → **`ListPageViewFrame`** (**§4.5**); **shared access / invite** → **`PageHeader` `variant="collaboration"`** + **`InviteCollaboratorsDrawer`** (**§4.7**).
+    - **Examples of existing surfaces to reuse:** card grid → `ListPageBoardCard` + `BoardCardIconRow` / `BoardCardTwoLineBlock`; AI / dot animation → `AiThinkingOverlay` + `DotPattern`; search input → `InputGroup` + `InputGroupAddon` + `InputGroupInput`; page title → `PageHeader` (serif via `font-heading`); list hub shell → `ListPageTemplate` (`metrics`, `defaultTabs`, `renderContent`); **dedicated form / wizard / settings route** → **`FocusedWorkflowPageTemplate`** + **`focused-workflow-layouts.tsx`** (**§14**); metrics strip → `KeyMetrics`; **view body gutter + centered max-width** → **`ListPageViewFrame`** (**§4.5**); **shared access / invite** → **`PageHeader` `variant="collaboration"`** + **`InviteCollaboratorsDrawer`** (**§4.7**).
     - **If** nothing fits and you would add a **new shared primitive or large bespoke widget**: **ask the user** for direction first — **`.cursor/rules/exxat-reuse-before-custom.mdc`** (unless the task already explicitly approved a greenfield build).
-17. **Match** naming, imports, and patterns of the nearest reference implementation (usually Placements).
-18. **Before** adding entity **mock data**, a **new view tab**, or **detail/inspector** panels on a list hub, read **`.cursor/rules/exxat-centralized-list-dataset.mdc`** and **`.cursor/skills/exxat-centralized-list-dataset/SKILL.md`** (single **`useTableState`** row bag for every view; **no** parallel mock arrays per view).
-19. **Before** choosing **cards vs table rows vs simple lists** for a hub, read **`docs/card-vs-rows-pattern.md`** and **`.cursor/rules/exxat-card-vs-list-rows.mdc`**.
-20. **Before** adding **`KeyMetrics`** strips on list hubs or dashboard key-metrics cards, read **`docs/kpi-strip-max-four-pattern.md`** and **`.cursor/rules/exxat-kpi-max-four.mdc`** (at most **four** tiles).
-21. **Before** adding **new shared UI primitives** or bespoke widgets when nothing in **`components/`** fits after scanning, follow **`.cursor/rules/exxat-reuse-before-custom.mdc`** — **ask the user** for direction unless the task already approved a greenfield build.
+18. **Match** naming, imports, and patterns of the nearest reference implementation (usually Placements).
+19. **Before** adding entity **mock data**, a **new view tab**, or **detail/inspector** panels on a list hub, read **`.cursor/rules/exxat-centralized-list-dataset.mdc`** and **`.cursor/skills/exxat-centralized-list-dataset/SKILL.md`** (single **`useTableState`** row bag for every view; **no** parallel mock arrays per view).
+20. **Before** choosing **cards vs table rows vs simple lists** for a hub, read **`docs/card-vs-rows-pattern.md`** and **`.cursor/rules/exxat-card-vs-list-rows.mdc`**.
+21. **Before** adding **`KeyMetrics`** strips on list hubs or dashboard key-metrics cards, read **`docs/kpi-strip-max-four-pattern.md`** and **`.cursor/rules/exxat-kpi-max-four.mdc`** (at most **four** tiles).
+22. **Before** styling **`KeyMetrics variant="flat"`** (list hub metrics strip, dashboard mix KPI band), read **`docs/kpi-flat-band-pattern.md`** and **`.cursor/rules/exxat-kpi-flat-band.mdc`** / **`.cursor/skills/exxat-kpi-flat-band/SKILL.md`** (transparent band, OKLCH glow, border hairlines only).
+23. **Before** changing **secondary panel** or **sidebar** brand chrome, read **`docs/shell-surface-elevation-pattern.md`** and **§4.6** ( **`--secondary-panel-bg`**, active product theme).
+24. **Before** adding **new shared UI primitives** or bespoke widgets when nothing in **`components/`** fits after scanning, follow **`.cursor/rules/exxat-reuse-before-custom.mdc`** — **ask the user** for direction unless the task already approved a greenfield build.
 
-**Longer narrative and architecture:** `docs/data-views-pattern.md`, `docs/drawer-vs-dialog-pattern.md`, `docs/card-vs-rows-pattern.md`, `docs/kpi-strip-max-four-pattern.md`, `docs/command-menu-pattern.md`, `docs/collaboration-access-pattern.md` (keep in sync with this handbook for big refactors).
+**Longer narrative and architecture:** `docs/data-views-pattern.md`, `docs/drawer-vs-dialog-pattern.md`, **`docs/focused-workflow-page-pattern.md`**, `docs/card-vs-rows-pattern.md`, `docs/kpi-strip-max-four-pattern.md`, **`docs/kpi-flat-band-pattern.md`**, **`docs/shell-surface-elevation-pattern.md`**, `docs/command-menu-pattern.md`, `docs/collaboration-access-pattern.md` (keep in sync with this handbook for big refactors).
 
 ---
 
@@ -73,7 +76,7 @@ If two documents conflict, prefer the **more specific** rule for the file type,
 
 **MUST:** If the main surface is a **`DataTable`** (or equivalent data grid), wrap it in **`ListPageTemplate`** so the **views toolbar** exists (tabs, add view, per-tab settings). Do **not** place `DataTable` only under `PageHeader` without the tab shell.
 
-**Reference implementations:** `components/data-list-client.tsx` (Placements), `components/team-client.tsx` (Team).
+**Reference implementations:** `components/list-hub-client.tsx` (List hub), `components/question-bank-client.tsx` (Question bank). Template mirror: `packages/ui/template/components/list-hub-*.tsx`, `question-bank-*.tsx`.
 
 **Rationale:** Consistent navigation, saved views, per-tab view type (table / list / board / dashboard), export at template level.
 
@@ -91,6 +94,19 @@ If two documents conflict, prefer the **more specific** rule for the file type,
 
 **Details:** `docs/data-views-pattern.md` (mock data, connected views, dashboard view).
 
+### 4.1.1 View registry + `ListPageConnectedViewBody` (required for new hubs)
+
+**MUST** route view bodies through the shared registry — **MUST NOT** use `if (view === "board")` chains with a dashboard fallback.
+
+| Step | Action |
+|------|--------|
+| **Register** | Add the tile in **`lib/data-list-view.ts`**; capabilities derive in **`lib/data-list-view-registry.ts`** (`renderKind`, `showsListPageHubMetricsStrip`). |
+| **Declare hub** | **`lib/<hub>-supported-views.ts`** — pass the same array to **`ListPageTemplate`** (`supportedViewTypes`) and **`TablePropertiesDrawerButton`** (`supportedViewTypes`). |
+| **Render** | Hub **`*-table.tsx`** returns **`ListPageConnectedViewBody`** with **`defineHubViewRenderers(supportedViewTypes, { … })`** — one entry per **`DataListViewRenderKind`**; dev warns on gaps; missing kinds show **`ListPageViewNotConfigured`** (never silent dashboard). |
+| **Bodies** | Generic UI in **`components/data-views/`** (`ListPageCalendarView`, `ListPageBoardTemplate`, `ListPageFolderColumnsPanel`, `FolderGridView`, …); entity wiring in thin hub wrappers (e.g. **`QuestionBankFolderColumnsPanel`**). **MUST NOT** export QB-only tree branches from the generic **`data-views`** barrel. |
+
+**Golden references (this app):** `components/list-hub-table.tsx`, `components/question-bank-table.tsx`. **Template** (`packages/ui/template/`): same list-hub + question-bank stack — keep in sync when publishing **`@exxatdesignux/ui`**.
+
 ### 4.2 `TablePropertiesDrawer` and the active view
 
 **MUST:** Any page that uses **`ListPageTemplate`** with **`tab.viewType`** (table / list / board / dashboard) and renders **`TablePropertiesDrawer`** **MUST** pass:
@@ -99,10 +115,11 @@ If two documents conflict, prefer the **more specific** rule for the file type,
 |------|--------|
 | **`currentView`** | The same **`DataListViewType`** as the tab’s active view (e.g. **`view={tab.viewType}`** on the table component). |
 | **`onViewChange`** | From **`renderContent={(tab, updateTab) => ...}`**: **`(v) => updateTab({ viewType: v, icon: dataListViewIcon(v) })`** — import **`dataListViewIcon`** from **`@/lib/data-list-view`**. |
+| **`supportedViewTypes`** | Same **`lib/<hub>-supported-views.ts`** array as **`ListPageTemplate`** — limits Properties view tiles and **⌘1–9** Add-view shortcuts to views the hub implements. |
 
-Thread **`view`** and **`onViewChange`** from the **client** → **table / toolbar wrapper** → **`TablePropertiesDrawer`**. If **`currentView`** is omitted, the drawer defaults to **table** labels and controls even on **Board**, which is incorrect.
+Thread **`view`**, **`onViewChange`**, and **`supportedViewTypes`** from the **client** → **table / toolbar wrapper** → **`TablePropertiesDrawer`**. If **`currentView`** is omitted, the drawer defaults to **table** labels and controls even on **Board**, which is incorrect.
 
-**Reference:** `components/data-list-table.tsx`, `components/team-table.tsx`, `components/compliance-table.tsx`. Root **`.cursor/rules/exxat-table-properties-drawer.mdc`**.
+**Reference:** `components/list-hub-table.tsx`, `components/question-bank-table.tsx`; template **`components/placements-table.tsx`**, **`team-table.tsx`**. Root **`.cursor/rules/exxat-table-properties-drawer.mdc`**.
 
 ### 4.3 Data view dashboard — charts, customisation, and parity with the gallery
 
@@ -165,6 +182,8 @@ Thread **`view`** and **`onViewChange`** from the **client** → **table / toolb
 
 **Folder-scoped library (Question bank):** When the URL is scoped to a folder (**`scope === "folder"`** + **`folderId`** via **`lib/question-bank-nav.ts`**), the hub **`QuestionBankPageHeader`** **⋯ More** menu **MUST** include **Customize folder** and open **`QuestionBankNewFolderSheet`** from the **hub client** so the action works on **every** **`ListPageTemplate`** view tab — not only inside **`QuestionBankTable`** branches that mount their own sheet. **Pattern:** **`docs/question-bank-hub-header-pattern.md`**. **Cursor rule:** **`.cursor/rules/exxat-question-bank-hub-header.mdc`**.
 
+**Surface elevation:** Secondary panel = **level 1** between primary sidebar (**`--sidebar`**, level 0) and page canvas (**`--background`**, level 2). **`NestedSecondaryPanelShell`** uses **`bg-[var(--secondary-panel-bg)]`** — OKLCH mix from **`--brand-tint*`** per active product (**One** indigo, **Prism** rose, **`theme-custom`** when accent differs from default). **MUST NOT** set panel to **`bg-sidebar`** or a fixed rose fill for all products. **`docs/shell-surface-elevation-pattern.md`**.
+
 **Cursor rule (panel wiring):** **`.cursor/rules/exxat-primary-nav-secondary-panel.mdc`**. **Icons in panel:** **`.cursor/rules/exxat-fontawesome-icons.mdc`**.
 
 ### 4.7 Collaboration & access (shared hubs)
@@ -247,7 +266,9 @@ Match **Placements**:
 
 **Rationale:** Drawers preserve **spatial context**; dialogs enforce **focus**; full pages avoid cramming complex work into overlays.
 
-**Details:** `docs/data-views-pattern.md` (Page vs drawer), **`docs/drawer-vs-dialog-pattern.md`** (drawer vs modal on the same route). Root **`.cursor/rules/exxat-page-vs-drawer.mdc`**, **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**.
+**Details:** `docs/data-views-pattern.md` (Page vs drawer), **`docs/drawer-vs-dialog-pattern.md`** (drawer vs modal on the same route), **`docs/focused-workflow-page-pattern.md`** (dedicated form/wizard/settings shell — **`FocusedWorkflowPageTemplate`** + body layouts). Root **`.cursor/rules/exxat-page-vs-drawer.mdc`**, **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**, **`.cursor/rules/exxat-focused-workflow-page.mdc`**, **`.cursor/skills/exxat-focused-workflow-page/SKILL.md`**.
+
+**Focused workflow routes:** Primary / long / multi-step / sectioned settings on an **own URL** → **`FocusedWorkflowPageTemplate`** (§14 checklist) — **not** **`ListPageTemplate`**, **not** Miller-column explorers.
 
 ### 6.5 Messaging — no toast
 
@@ -421,11 +442,14 @@ Reference: `components/new-placement-form.tsx` (Next/Back buttons); full shortcu
 
 | Need | Reuse | Where |
 |------|--------|--------|
-| View tabs + shell | `ListPageTemplate` | `components/templates/list-page.tsx` |
+| View tabs + shell | `ListPageTemplate` (+ **`supportedViewTypes`**) | `components/templates/list-page.tsx` |
+| Focused form / wizard / settings route | `FocusedWorkflowPageTemplate` + layouts in `focused-workflow-layouts.tsx` | `components/templates/focused-workflow-page-template.tsx` — **`docs/focused-workflow-page-pattern.md`** |
+| View router | `ListPageConnectedViewBody`, `defineHubViewRenderers`, `data-list-view-registry` | `components/data-views/list-page-connected-view-body.tsx`, `lib/hub-connected-view-renderers.ts`, `lib/data-list-view-registry.ts` |
 | Table + toolbar | `DataTable`, `DataTableToolbar`, `useTableState` | `components/data-table/` |
-| Properties | `TablePropertiesDrawer` (+ **`currentView`** / **`onViewChange`** when using view tabs — §4.2) | `@/components/table-properties` |
-| Placements flow | `DataListClient`, `DataListTable` | `components/data-list-client.tsx`, `components/data-list-table.tsx` |
-| Team flow | `TeamClient`, `TeamTable`, `TeamPageHeader` | `components/team-client.tsx`, etc. |
+| Properties | `TablePropertiesDrawer` (+ **`currentView`** / **`onViewChange`** / **`supportedViewTypes`** — §4.2) | `@/components/table-properties` |
+| List hub (golden) | `ListHubClient`, `ListHubTable` | `components/list-hub-client.tsx`, `list-hub-table.tsx` |
+| Question bank | `QuestionBankClient`, `QuestionBankTable` | `components/question-bank-client.tsx`, `question-bank-table.tsx` |
+| Template-only hubs (npm) | Placements, Team, Compliance, Sites | `packages/ui/template/components/*` — diff on upgrade |
 | Dashboard view tab (KPIs + charts) | **`DashboardReportCharts`**; default **`ChartsOverview`** (placement demo). **Team** passes **`chartsSection`** (`TeamDashboardChartsSection`) so graphs match roster rows. KPIs from **`tableState.rows`** | `components/dashboard-report-charts.tsx`, `data-view-dashboard-charts-team.tsx`, `data-list-table.tsx` |
 | Data view layout + graph keyboard tokens | **`loadDataViewLayout` / `saveDataViewLayout`**, **`CHART_KBD_ACTIVE_BAR`**, **`CHART_KBD_ACTIVE_PIE_SHAPE`** | `lib/data-view-dashboard-storage.ts`, `lib/chart-keyboard-selection.ts` |
 | Customize dashboard coach marks | Shared steps in **`lib/dashboard-customize-coach-mark.ts`**; flows **`placements-dashboard-customize`**, **`team-dashboard-customize`**, **`compliance-dashboard-customize`** | `hooks/use-coach-mark.ts` (`enabled`, `dependsOnDismissedFlowId`), `data-list-table.tsx`, `team-table.tsx`, `compliance-table.tsx` |
@@ -508,8 +532,12 @@ New pages **SHOULD** namespace keys and version JSON (`v: 1`) for future migrati
 
 - **Deep dive:** `docs/data-views-pattern.md` (includes **Page vs drawer** with **§6.4**)
 - **Drawer vs dialog (same route):** `docs/drawer-vs-dialog-pattern.md` — **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**
+- **Focused workflow (form / wizard / settings route):** `docs/focused-workflow-page-pattern.md` — **`.cursor/rules/exxat-focused-workflow-page.mdc`**, **`.cursor/skills/exxat-focused-workflow-page/SKILL.md`**
+- **Consumer app (npm):** `docs/consumer-app-pattern.md` — **`packages/ui/consumer-extras/AGENTS.md`**, **`.cursor/rules/exxat-consumer-app.mdc`**, **`.cursor/skills/exxat-consumer-app/SKILL.md`**
 - **Cards vs table rows:** `docs/card-vs-rows-pattern.md` — **`.cursor/rules/exxat-card-vs-list-rows.mdc`**
 - **KPI strip (max four tiles):** `docs/kpi-strip-max-four-pattern.md` — **`.cursor/rules/exxat-kpi-max-four.mdc`**
+- **KPI flat band (list hubs):** `docs/kpi-flat-band-pattern.md` — **`.cursor/rules/exxat-kpi-flat-band.mdc`**
+- **Shell surfaces (sidebar · secondary panel · page):** `docs/shell-surface-elevation-pattern.md`
 - **KPI deltas & trend arrows:** `docs/kpi-trend-pattern.md` (`MetricItem.trendPolarity`, `KeyMetrics`, chart mini-metrics)
 - **Global command palette (⌘K):** `docs/command-menu-pattern.md`
 - **No toast / snackbars:** **§6.5**, root **`.cursor/rules/exxat-no-toast.mdc`**
@@ -527,7 +555,7 @@ New pages **SHOULD** namespace keys and version JSON (`v: 1`) for future migrati
 | Match Placements for export + primary CTA + More menu | Outline button as the single primary CTA on exportable pages |
 | Pair `Kbd` hints with real shortcuts | Browser-reserved chords for app actions |
 | Global palette: **§7.1** — search + quick in-menu AI vs **Ask Leo**; **`dataGroups`** + **`searchOnly`** for bulky indexes | Palette as link-only dump; AI that belongs in **Ask Leo** forced into the palette; mounting full **`dataGroups`** on open when **`searchOnly`** should hide them |
-| **§6.4** — **drawer** when **page context + quick** view/actions; **dialog** for **blocking** confirm/alert/short choice; **new page** for primary / long / own-URL flows | Forcing **full workflows** into a drawer when a route fits; using a **dialog** when users must **reference** the grid (prefer drawer); **routing** for tasks that are only quick glances over a hub |
+| **§6.4** — **drawer** when **page context + quick** view/actions; **dialog** for **blocking** confirm/alert/short choice; **focused workflow route** (`FocusedWorkflowPageTemplate`) for primary / long / wizard / sectioned settings | Forcing **full workflows** into a drawer when a route fits; using a **dialog** when users must **reference** the grid (prefer drawer); **`ListPageTemplate`** or Miller columns on dedicated create/edit routes |
 | **KPI strips** — **≤ 4** `MetricItem` per **`KeyMetrics`** on template metrics + Data-tab key-metrics cards (**`KEY_METRICS_KPI_COUNT_MAX`**) | Fifth+ headline tile in the same strip; duplicate tiles to pad count |
 | **Cards vs rows** — **DataTable** for dense comparable hubs; **`ListPageBoardCard`** / **`ListPageViewFrame`** when visual/kanban/folder — **`docs/card-vs-rows-pattern.md`** | Card walls for **50+** homogeneous records where the product expects **sort/filter/compare** without a deliberate UX exception |
 | **Reuse before custom** — scan **`components/`** + **§9**; **ask the user** before new shared primitives or large bespoke widgets — **`exxat-reuse-before-custom.mdc`** | Parallel stacks; silent new “table” or metric systems when **`DataTable`** / **`KeyMetrics`** already apply |
@@ -550,6 +578,7 @@ New pages **SHOULD** namespace keys and version JSON (`v: 1`) for future migrati
 Copy and complete when implementing or reviewing:
 
 - [ ] **Centralized dataset:** One **`useTableState`** / **`tableState.rows`** for **all** view tabs and inspectors; **TablePropertiesDrawer** on the **same** `DataTable`; **no** parallel mock arrays per view — **`.cursor/rules/exxat-centralized-list-dataset.mdc`**.
+- [ ] **View registry (§4.1.1):** **`lib/<hub>-supported-views.ts`**; **`ListPageConnectedViewBody`** + **`defineHubViewRenderers`**; same **`supportedViewTypes`** on template + Properties; no silent dashboard fallback — **`docs/data-views-pattern.md`**.
 - [ ] **Reuse:** `ListPageTemplate`, `DataTable` / `useTableState`, `TablePropertiesDrawer` — no parallel bespoke tabs/filters. **New shared primitives:** **ask the user** after scanning **`components/`** + **§9** — **`.cursor/rules/exxat-reuse-before-custom.mdc`**.
 - [ ] **Tabs:** Any main `DataTable` sits under `ListPageTemplate` with appropriate view tabs.
 - [ ] **Inset:** No double horizontal padding around `DataTable`.
@@ -562,7 +591,7 @@ Copy and complete when implementing or reviewing:
 - [ ] **Data view dashboard (Placements / Team / Compliance):** Charts use **`ChartFigure`** + **`ChartDataTable`**; **Edit layout** on toolbar; **`activeBar` / `activeShape`** keyboard styling from **`lib/chart-keyboard-selection`** — not opacity-only **`Cell`** hacks (§4.3).
 - [ ] **Dashboard layout persistence:** **`lib/data-view-dashboard-storage`** (or **`saveDashboardLayout`** / **`loadDashboardLayout`** on Placements); **`mergeDashboardLayout`** on load — no new ad-hoc storage keys for the same layout (§4.3).
 - [ ] **⌘K palette (§7.1):** If adding or changing **`dataGroups`**, map rows in **`lib/command-menu-search-data.ts`** (not `command-menu.tsx`); use **`searchOnly`** on bulky groups; keep **`docs/command-menu-pattern.md`** aligned.
-- [ ] **Page vs drawer vs dialog (§6.4):** Quick auxiliary with **parent context** and interactable hub → **drawer/sheet**; **blocking** short confirm → **dialog**; primary or long flows → **new route** — **`docs/data-views-pattern.md`**, **`docs/drawer-vs-dialog-pattern.md`**.
+- [ ] **Page vs drawer vs dialog (§6.4):** Quick auxiliary with **parent context** and interactable hub → **drawer/sheet**; **blocking** short confirm → **dialog**; primary or long flows → **focused workflow route** or other dedicated page — **`docs/data-views-pattern.md`**, **`docs/drawer-vs-dialog-pattern.md`**, **`docs/focused-workflow-page-pattern.md`**.
 - [ ] **Cards vs rows:** Primary sortable hub with many homogeneous records → **`DataTable`**; kanban / visual tiles → **`ListPageBoardCard`** — **`docs/card-vs-rows-pattern.md`**, **`.cursor/rules/exxat-card-vs-list-rows.mdc`**.
 - [ ] **KPI count (max four):** **`entityKpiMetrics`** (and any static **`MetricItem[]`** for the same strip) has **≤ 4** tiles for template metrics + Data-tab key-metrics — **`docs/kpi-strip-max-four-pattern.md`**, **`.cursor/rules/exxat-kpi-max-four.mdc`**.
 - [ ] **No toast (§6.5):** No **`toast()`** / Sonner / snackbars — use banners, inline status, or dialogs.
@@ -574,7 +603,8 @@ Copy and complete when implementing or reviewing:
 - [ ] **Accessibility:** §8 — tablist/toolbar patterns, **≥24px** targets for icon-only controls, contrast on tinted surfaces, dialog/sheet/drawer **titles**; **every icon that communicates info has a text alternative** — adjacent label (preferred) OR `aria-label` + `Tooltip` (§8.6 Case A/B/C, covers informational icons like calendar-for-date, status dots, AND icon-only buttons); **kbd inside a button uses `<Kbd variant="bare">`** (§8.7); re-run **axe** on Placements when changing views toolbar.
 - [ ] **Coach marks (§11):** `CoachMark` + `useCoachMark`; register in **`coach-mark-registry`**; use **`enabled`** / **`dependsOnDismissedFlowId`** when a tour must wait for another flow or a specific view (e.g. **dashboard**); customize-dashboard flows use **`lib/dashboard-customize-coach-mark.ts`**.
 - [ ] **Application sidebar (§9.1):** **`ExxatProductLogo`** for product; **`logoDevUrl`** for schools; team switcher **`DropdownMenuContent`** keeps the explicit wide school/program surface (**`!w-max`** + min/max width); expanded switcher **`h-auto min-h-12`**; no **`CollapsibleTrigger` → `SidebarMenuButton` with `tooltip` prop**; child links **popover** on icon rail; profile **`stockPortraitUrl`** + **`referrerPolicy="no-referrer"`** on **`AvatarImage`**.
-- [ ] **Secondary panel (§4.6):** If **`NavLinkItem.secondaryPanel`** is set — **`PANELS[id]`** in **`secondary-panel.tsx`**, hub mounts **`useAutoPanel(id)`**, scope syncs to URL + **`tableState.rows`** — **`.cursor/rules/exxat-primary-nav-secondary-panel.mdc`**. **Question bank folder scope:** header **⋯** → **Customize folder** + **`QuestionBankNewFolderSheet`** on **`QuestionBankClient`** — **`docs/question-bank-hub-header-pattern.md`**, **`.cursor/rules/exxat-question-bank-hub-header.mdc`**.
+- [ ] **Secondary panel (§4.6):** If **`NavLinkItem.secondaryPanel`** is set — **`PANELS[id]`** in **`secondary-panel.tsx`**, hub mounts **`useAutoPanel(id)`**, scope syncs to URL + **`tableState.rows`** — **`.cursor/rules/exxat-primary-nav-secondary-panel.mdc`**. Panel shell uses **`--secondary-panel-bg`** (brand OKLCH, not **`bg-sidebar`**) — **`docs/shell-surface-elevation-pattern.md`**. **Question bank folder scope:** header **⋯** → **Customize folder** + **`QuestionBankNewFolderSheet`** on **`QuestionBankClient`** — **`docs/question-bank-hub-header-pattern.md`**, **`.cursor/rules/exxat-question-bank-hub-header.mdc`**.
+- [ ] **Flat KPI strip:** **`KeyMetrics variant="flat"`** — transparent cells, radial glow only, **`flatMetricsHairlineClass`** borders — **`docs/kpi-flat-band-pattern.md`**, **`.cursor/rules/exxat-kpi-flat-band.mdc`**.
 - [ ] **Collaboration & access (§4.7):** Shared hubs use **`variant="collaboration"`**, empty **Add collaborator** / non-empty face rail, **⋯ → Invite people**, **`CollaborationAccessFlow`** or **`InviteCollaboratorsDrawer`**, **`lib/collaborator-access.ts`**, roster **name → email → role tags** — **`.cursor/rules/exxat-collaboration-access.mdc`**.
 - [ ] **Dedicated search (§4.8):** Landing uses **`DedicatedSearchLandingTemplate`**; results use **`DedicatedSearchResultsHeaderChrome`** + outer **`DEDICATED_SEARCH_RESULTS_OUTER_CONTENT_CLASSNAME`**; **`DedicatedSearchUrlComposer`** + **`DedicatedSearchRecents`** with **`createDedicatedSearchRecentsController`** — **`.cursor/rules/exxat-dedicated-search-surfaces.mdc`**.
 - [ ] **KPI trends:** **`MetricItem.trend`** matches the delta direction; **`trendPolarity`** set for “more is worse” metrics (flags, defects, overdue) — **`docs/kpi-trend-pattern.md`**, **`.cursor/rules/exxat-kpi-trends.mdc`**.
@@ -583,4 +613,19 @@ Copy and complete when implementing or reviewing:
 
 ---
 
-*Last updated: monospace system IDs rule/skill; question bank folder-scoped header Customize + rule/skill; drawer vs dialog / card vs rows / KPI max-four pattern docs + rules + skills; §6.4 table; §4.8 dedicated search templates; §4.7 collaboration & access; §4.1 centralized dataset + presentation; §4.5–§4.6 view shells + secondary panel; Font Awesome rule; §9.1 application sidebar shell; §4.4 board cards; §6.5 no toast; §7.1 command palette; §13 checklist.*
+## 14. AI execution checklist (focused workflow route)
+
+Copy and complete when implementing or reviewing a **dedicated form, wizard, or settings** page (not a list hub):
+
+- [ ] **`FocusedWorkflowPageTemplate`** on **`app/(app)/…/page.tsx`** — **`siteHeader`** with **`back`** or **`breadcrumbs`** + **`title`**.
+- [ ] **`maxWidth`**: **`md`** | **`lg`** | **`xl`** — not list-hub **`max-w-[1440px]`**.
+- [ ] **One body layout:** **`FocusedWorkflowSingleColumn`** | **`FocusedWorkflowStepForm`** | **`FocusedWorkflowSidebarSections`** | **`FocusedWorkflowEmptyState`**.
+- [ ] **Wizard / actions:** **`FocusedWorkflowWizardFooter`** or **`FocusedWorkflowActionFooter`** + **`Shortcut`** + **`<Kbd variant="bare">`** (**`exxat-kbd-shortcuts.mdc`**).
+- [ ] **Domain UI** in **`*-composer.tsx`** / **`*-client.tsx`**; **`FocusedWorkflow*`** names stay generic.
+- [ ] **No** **`ListPageTemplate`**, **no** **`ListPageFolderColumnsPanel`**, **no** Miller-column split explorer in this shell.
+- [ ] **No toast (§6.5)** for product feedback on this route.
+- [ ] **Reference:** **`/examples/focused-workflow`**, **`docs/focused-workflow-page-pattern.md`**, **`.cursor/skills/exxat-focused-workflow-page/SKILL.md`**.
+
+---
+
+*Last updated: focused workflow page pattern + §14 checklist + rule/skill; KPI flat band + shell surface elevation; §4.6 secondary panel OKLCH; monospace system IDs; question bank folder header; drawer vs dialog / card vs rows / KPI max-four; §4.8 dedicated search; §4.7 collaboration; §4.1 centralized dataset; §4.5 view shells; Font Awesome; §9.1 sidebar; §4.4 board cards; §6.5 no toast; §7.1 command palette; §13 checklist.*

package/template/app/(app)/dashboard/loading.tsx

@@ -1,18 +1,6 @@
-import { Skeleton } from "@/components/ui/skeleton"
+import { DashboardLoadingFallback } from "@/components/templates/page-loading-shell"
 
-/** Route-level fallback while the dashboard shell + tabs chunk load. */
+/** Dashboard route — same shell as `app/(app)/loading` dashboard variant. */
 export default function DashboardLoading() {
-  return (
-    <div className="flex flex-col gap-4 p-4 md:p-6" aria-busy="true" aria-label="Loading dashboard">
-      <Skeleton className="h-9 w-56 max-w-full" />
-      <Skeleton className="h-11 w-full max-w-xl" />
-      <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-4">
-        <Skeleton className="h-24 rounded-xl" />
-        <Skeleton className="h-24 rounded-xl" />
-        <Skeleton className="h-24 rounded-xl" />
-        <Skeleton className="h-24 rounded-xl" />
-      </div>
-      <Skeleton className="min-h-[320px] w-full rounded-xl" />
-    </div>
-  )
+  return <DashboardLoadingFallback />
 }

package/template/app/(app)/dashboard/page.tsx

@@ -1,24 +1,12 @@
 import dynamic from "next/dynamic"
 import { PrimaryPageTemplate } from "@/components/templates/primary-page-template"
-import { Skeleton } from "@/components/ui/skeleton"
+import { DashboardLoadingBody } from "@/components/templates/page-loading-shell"
 import { DASHBOARD_METRICS, DASHBOARD_INSIGHT } from "@/lib/mock/dashboard"
 
 const DashboardTabs = dynamic(
   () => import("@/components/dashboard-tabs").then(m => ({ default: m.DashboardTabs })),
   {
-    loading: () => (
-      <div className="flex flex-col gap-4 p-4 md:p-6" aria-busy="true" aria-label="Loading dashboard">
-        <Skeleton className="h-9 w-56 max-w-full" />
-        <Skeleton className="h-11 w-full max-w-xl" />
-        <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-4">
-          <Skeleton className="h-24 rounded-xl" />
-          <Skeleton className="h-24 rounded-xl" />
-          <Skeleton className="h-24 rounded-xl" />
-          <Skeleton className="h-24 rounded-xl" />
-        </div>
-        <Skeleton className="min-h-[320px] w-full rounded-xl" />
-      </div>
-    ),
+    loading: () => <DashboardLoadingBody />,
   },
 )
 

package/template/app/(app)/data-list/layout.tsx

@@ -0,0 +1,43 @@
+"use client"
+
+import * as React from "react"
+import { usePathname } from "next/navigation"
+
+import { useSecondaryPanel } from "@/components/secondary-panel"
+import { LIST_HUB_PATH } from "@/lib/list-hub-nav"
+
+/**
+ * Keeps the List hub secondary panel open on `/data-list` while scope links update in place.
+ */
+export default function DataListLayout({ children }: { children: React.ReactNode }) {
+  const pathname = usePathname()
+  const { openPanel, closePanel, activePanel } = useSecondaryPanel()
+  const closePanelRef = React.useRef(closePanel)
+  const openPanelRef = React.useRef(openPanel)
+
+  React.useEffect(() => {
+    closePanelRef.current = closePanel
+    openPanelRef.current = openPanel
+  })
+
+  React.useEffect(() => {
+    return () => {
+      closePanelRef.current({ mainSidebar: "leave" })
+    }
+  }, [])
+
+  React.useEffect(() => {
+    const normalized =
+      pathname.length > 1 && pathname.endsWith("/") ? pathname.slice(0, -1) : pathname
+    if (normalized !== LIST_HUB_PATH) {
+      closePanelRef.current({ mainSidebar: "leave" })
+      return undefined
+    }
+    if (activePanel !== "list-hub") {
+      openPanelRef.current("list-hub")
+    }
+    return undefined
+  }, [pathname, activePanel])
+
+  return children
+}

package/template/app/(app)/data-list/page.tsx

@@ -1,10 +1,10 @@
-import { PlacementsClient } from "@/components/placements-client"
+import { ListHubClient } from "@/components/list-hub-client"
 import { PrimaryPageTemplate } from "@/components/templates/primary-page-template"
 
 export default function DataListPage() {
   return (
     <PrimaryPageTemplate siteHeader={{ title: "List hub" }}>
-      <PlacementsClient />
+      <ListHubClient />
     </PrimaryPageTemplate>
   )
 }

package/template/app/(app)/error.tsx

@@ -4,6 +4,7 @@ import * as React from "react"
 import { AlertCircle } from "lucide-react"
 
 import { Button } from "@/components/ui/button"
+import { isChunkLoadError } from "@/lib/chunk-load-error"
 
 /**
  * Route error boundary for the signed-in app shell. Lets users retry without a full reload.
@@ -15,6 +16,8 @@ export default function AppRouteError({
   error: Error & { digest?: string }
   reset: () => void
 }) {
+  const chunkStale = isChunkLoadError(error)
+
   React.useEffect(() => {
     if (process.env.NODE_ENV === "development") {
       console.error(error)
@@ -30,14 +33,27 @@ export default function AppRouteError({
       <div className="space-y-2">
         <h1 className="text-lg font-semibold text-foreground">Something went wrong</h1>
         <p className="max-w-md text-sm text-muted-foreground">
-          {process.env.NODE_ENV === "development"
-            ? error.message
-            : "Please try again. If the problem continues, contact support."}
+          {chunkStale
+            ? "The app loaded an outdated script bundle (common after a dev-server rebuild). Reload the page to fetch the latest chunks."
+            : process.env.NODE_ENV === "development"
+              ? error.message
+              : "Please try again. If the problem continues, contact support."}
         </p>
       </div>
-      <Button type="button" onClick={() => reset()}>
-        Try again
-      </Button>
+      <div className="flex flex-wrap items-center justify-center gap-2">
+        {chunkStale ? (
+          <Button type="button" onClick={() => window.location.reload()}>
+            Reload page
+          </Button>
+        ) : null}
+        <Button
+          type="button"
+          variant={chunkStale ? "outline" : "default"}
+          onClick={() => reset()}
+        >
+          Try again
+        </Button>
+      </div>
     </div>
   )
 }

package/template/app/(app)/examples/focused-workflow/page.tsx

@@ -0,0 +1,5 @@
+import { FocusedWorkflowShowcase } from "@/components/examples/focused-workflow-showcase"
+
+export default function FocusedWorkflowExamplePage() {
+  return <FocusedWorkflowShowcase />
+}

package/template/app/(app)/examples/page.tsx

@@ -7,6 +7,7 @@ const LINKS = [
   { href: "/data-list", label: "List hub", description: "Table, list, board, and dashboard views on shared state." },
   { href: "/question-bank", label: "Question bank", description: "Discovery hub for browsing folders, recents, and AI-assisted create/import flows." },
   { href: "/question-bank/library", label: "Question library", description: "Folders, OS folder view, panel, and tree demos on mock items." },
+  { href: "/examples/focused-workflow", label: "Focused workflow", description: "Empty, step wizard, and sidebar section layouts for large forms." },
   { href: "/settings", label: "Settings", description: "Appearance, tours, and shell preferences." },
   { href: "/help", label: "Help", description: "Support and documentation entry points." },
 ] as const

package/template/app/(app)/layout.tsx

@@ -1,6 +1,10 @@
-import * as React       from "react"
+import { cookies } from "next/headers"
 import { AppSidebar }   from "@/components/app-sidebar"
 import { SidebarShell } from "@/components/sidebar-shell"
+import {
+  SIDEBAR_STATE_COOKIE_NAME,
+  sidebarDefaultOpenFromCookie,
+} from "@/lib/sidebar-state-cookie"
 import { DashboardViewProvider } from "@/contexts/dashboard-view-context"
 import { ChartVariantProvider }  from "@/contexts/chart-variant-context"
 import { AskLeoProvider, AskLeoSidebar } from "@/components/ask-leo-sidebar"
@@ -20,11 +24,14 @@ import { COMMAND_MENU_SEARCH_DATA_GROUPS } from "@/lib/command-menu-search-data"
  * The SystemBanner is configured from Settings (persisted to localStorage
  * via SystemBannerProvider) — no hardcoded copy here.
  */
-export default function AppLayout({ children }: { children: React.ReactNode }) {
-  const commandMenuConfig = React.useMemo(
-    () => buildCommandMenuConfig({ dataGroups: COMMAND_MENU_SEARCH_DATA_GROUPS }),
-    [],
+export default async function AppLayout({ children }: { children: React.ReactNode }) {
+  const cookieStore = await cookies()
+  const sidebarDefaultOpen = sidebarDefaultOpenFromCookie(
+    cookieStore.get(SIDEBAR_STATE_COOKIE_NAME)?.value,
   )
+  const commandMenuConfig = buildCommandMenuConfig({
+    dataGroups: COMMAND_MENU_SEARCH_DATA_GROUPS,
+  })
 
   return (
     <DashboardViewProvider>
@@ -33,7 +40,7 @@ export default function AppLayout({ children }: { children: React.ReactNode }) {
     <SystemBannerProvider>
     <CommandMenuProvider value={commandMenuConfig}>
 
-    <SidebarShell wrapperClassName="flex min-h-svh flex-col">
+    <SidebarShell defaultOpen={sidebarDefaultOpen} wrapperClassName="flex min-h-svh flex-col">
       {/* ⌘K command palette */}
       <CommandMenu />
       <SystemBannerSlot />

package/template/app/(app)/loading.tsx

@@ -1,18 +1 @@
-import { Skeleton } from "@/components/ui/skeleton"
-
-/**
- * Default loading UI for app routes (sidebar chrome stays; main column shows this fallback).
- */
-export default function AppRouteLoading() {
-  return (
-    <div
-      className="flex flex-col gap-4 p-6 md:p-8"
-      aria-busy="true"
-      aria-label="Loading page"
-    >
-      <Skeleton className="h-8 w-48" />
-      <Skeleton className="h-32 w-full max-w-3xl" />
-      <Skeleton className="h-64 w-full" />
-    </div>
-  )
-}
+export { AppRouteLoading as default } from "@/components/app-route-loading"

package/template/app/(app)/question-bank/find/page.tsx

@@ -1,11 +1,12 @@
 import { Suspense } from "react"
 
 import { QuestionBankClient } from "@/components/question-bank-client"
+import { DedicatedSearchLoadingFallback } from "@/components/templates/page-loading-shell"
 
 /** Discovery hub composer results — same hub chrome as the library, distinct from `/question-bank/list`. */
 export default function QuestionBankHubFindPage() {
   return (
-    <Suspense fallback={null}>
+    <Suspense fallback={<DedicatedSearchLoadingFallback />}>
       <QuestionBankClient />
     </Suspense>
   )

package/template/app/(app)/question-bank/library/page.tsx

@@ -1,10 +1,11 @@
 import { Suspense } from "react"
 
 import { QuestionBankClient } from "@/components/question-bank-client"
+import { PrimaryListHubLoadingFallback } from "@/components/templates/page-loading-shell"
 
 export default function QuestionBankLibraryPage() {
   return (
-    <Suspense fallback={null}>
+    <Suspense fallback={<PrimaryListHubLoadingFallback />}>
       <QuestionBankClient />
     </Suspense>
   )

package/template/app/(app)/question-bank/list/page.tsx

@@ -1,11 +1,12 @@
 import { Suspense } from "react"
 
 import { QuestionBankClient } from "@/components/question-bank-client"
+import { DedicatedSearchLoadingFallback } from "@/components/templates/page-loading-shell"
 
 /** Question bank list surface — same hub as `/question-bank/library`, optimized for `?q=` search landings. */
 export default function QuestionBankListPage() {
   return (
-    <Suspense fallback={null}>
+    <Suspense fallback={<DedicatedSearchLoadingFallback />}>
       <QuestionBankClient />
     </Suspense>
   )

package/template/app/(app)/question-bank/new/page.tsx

@@ -1,22 +1,14 @@
 /**
  * `/question-bank/new` — full-page authoring composer.
  *
- * Mirrors focused flows: `SiteHeader` back nav (← Question hub) + `PageHeader` title
- *   • `SidebarAutoCollapse` mounted in `beforeSiteHeader` so the main sidebar
- *     collapses on enter and restores to its prior state on leave
- *   • A wider max-width than the placement form (the composer carries a
- *     two-column document + metadata-rail layout)
- *
- * The body is `NewQuestionComposer` — see `components/new-question-composer.tsx`.
- *
- * Folder pre-selection: callers may pass `?folderId=<id>` so users dropped into
- * the composer from a folder-scoped library land with that folder pre-selected
- * in the metadata rail.
+ * Pattern: `FocusedWorkflowPageTemplate` + `NewQuestionComposer` (single column).
+ * Folder pre-selection: `?folderId=<id>` from a folder-scoped library link.
  */
 
 import { NewQuestionComposer } from "@/components/new-question-composer"
 import { SidebarAutoCollapse } from "@/components/sidebar-auto-collapse"
-import { PrimaryPageTemplate } from "@/components/templates/primary-page-template"
+import { FocusedWorkflowPageTemplate } from "@/components/templates/focused-workflow-page-template"
+import { FocusedWorkflowSingleColumn } from "@/components/templates/focused-workflow-layouts"
 import {
   DEFAULT_QUESTION_BANK_FOLDERS,
   type QuestionBankFolder,
@@ -40,19 +32,19 @@ export default async function NewQuestionPage({ searchParams }: NewQuestionPageP
   const draftQuestionId = generateDraftQuestionId()
 
   return (
-    <PrimaryPageTemplate
+    <FocusedWorkflowPageTemplate
       beforeSiteHeader={<SidebarAutoCollapse />}
       siteHeader={{ back }}
-      bodyClassName="min-h-0 flex-1 overflow-y-auto overscroll-y-contain"
-      maxWidthClassName="mx-auto w-full max-w-[1100px]"
-      contentClassName="px-8 py-4 pb-16"
+      maxWidth="lg"
     >
-      <NewQuestionComposer
-        draftQuestionId={draftQuestionId}
-        defaultFolderId={defaultFolderId}
-        backHref={back.href}
-        folders={folders}
-      />
-    </PrimaryPageTemplate>
+      <FocusedWorkflowSingleColumn>
+        <NewQuestionComposer
+          draftQuestionId={draftQuestionId}
+          defaultFolderId={defaultFolderId}
+          backHref={back.href}
+          folders={folders}
+        />
+      </FocusedWorkflowSingleColumn>
+    </FocusedWorkflowPageTemplate>
   )
 }

package/template/app/(app)/question-bank/page.tsx

@@ -1,10 +1,11 @@
 import { Suspense } from "react"
 
 import { QuestionBankHubClient } from "@/components/question-bank-hub-client"
+import { QuestionBankHubLoadingFallback } from "@/components/templates/page-loading-shell"
 
 export default function QuestionBankHubPage() {
   return (
-    <Suspense fallback={null}>
+    <Suspense fallback={<QuestionBankHubLoadingFallback />}>
       <QuestionBankHubClient />
     </Suspense>
   )

package/template/app/(app)/settings/page.tsx

@@ -1,17 +1,16 @@
-import { PrimaryPageTemplate } from "@/components/templates/primary-page-template"
 import { SettingsClient } from "@/components/settings-client"
+import { FocusedWorkflowPageTemplate } from "@/components/templates/focused-workflow-page-template"
 
 export default function SettingsPage() {
   return (
-    <PrimaryPageTemplate
-      maxWidthClassName="max-w-3xl"
-      contentClassName="px-8 pt-10 pb-32"
+    <FocusedWorkflowPageTemplate
+      maxWidth="lg"
       siteHeader={{
         breadcrumbs: [{ label: "Dashboard", href: "/dashboard" }],
         title: "Settings",
       }}
     >
       <SettingsClient />
-    </PrimaryPageTemplate>
+    </FocusedWorkflowPageTemplate>
   )
 }