@exxatdesignux/ui 0.2.17 → 0.2.18

package/CHANGELOG.md

@@ -15,6 +15,21 @@ After the user bumps `@exxatdesignux/ui`, do this in order:
 
 ---
 
+## [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/cursor-skills/exxat-ds-skill/SKILL.md

@@ -551,7 +551,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-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

@@ -17,12 +17,14 @@ user-invocable: true
 4. **Data** — keep **one** **`useTableState`** / **`tableState.rows`**; drive scope from **URL** + small helpers (see **`lib/question-bank-nav.ts`**).
 5. **Folder-scoped hub header (Question bank library)** — When **`scope === "folder"`** in the URL, **`QuestionBankPageHeader`** **⋯ More** includes **Customize folder**; mount **`QuestionBankNewFolderSheet`** on **`QuestionBankClient`** so it works on **all** **`ListPageTemplate`** view tabs — **`.cursor/rules/exxat-question-bank-hub-header.mdc`**, **`docs/question-bank-hub-header-pattern.md`**.
 6. **Collapse control** — the nested rail header uses **`collapseActiveSecondaryPanel()`** (angles-left icon), not “close”, so the panel stays dismissed until **`openPanel`** runs again (nav, scope hook, or hub re-entry). Layout effects that auto-call **`openPanel`** must respect **`secondaryPanelAutoReopenSuppressed`** (see **`app/(app)/question-bank/layout.tsx`** + **`SecondaryPanelProvider`**).
+7. **Surface elevation** — secondary panel = **level 1** (lighter than sidebar, darker than page). Use **`--secondary-panel-bg`** on **`NestedSecondaryPanelShell`**; derive from **`--brand-tint*`** per active product (**One** indigo, **Prism** rose). See **`docs/shell-surface-elevation-pattern.md`**.
 
 ## MUST NOT
 
 - Set **`secondaryPanel`** without **`PANELS[id]`** + **`useAutoPanel`** — broken empty rail.
 - Use this for full product areas that belong as **primary** or **collapsible child** rows.
 - Invent a parallel zoom / reflow hook for the secondary rail — reuse **`useSidebarReflowZoom`** (the provider already wires it; see §"High-zoom auto-collapse" below).
+- Set secondary panel **`bg-sidebar`** or a fixed rose mix for every product — breaks **One** indigo chrome.
 
 ## High-zoom auto-collapse
 
@@ -39,6 +41,9 @@ Custom panel content (anything you register under `PANELS[id]`) should **read `s
 - `components/app-sidebar.tsx` — `openPanel` on same-route primary click.
 - `components/secondary-panel.tsx` — `SecondaryPanelProvider`, `PANELS` registry, **high-zoom auto-collapse**.
 - `hooks/use-sidebar-reflow-zoom.ts` — shared zoom / reflow signal.
-- `components/templates/nested-secondary-panel-shell.tsx` — expanded vs `compact` (icon rail) widths.
+- `components/templates/nested-secondary-panel-shell.tsx` — expanded vs `compact` (icon rail) widths; **`bg-[var(--secondary-panel-bg)]`**.
+- `app/globals.css` — `--secondary-panel-bg`, `--sidebar`, product **`theme-one`** / **`theme-prism`** blocks.
+- `contexts/product-context.tsx` — `accentOverrideActive`, theme class on `<html>`.
+- **`docs/shell-surface-elevation-pattern.md`**
 - `components/question-bank-secondary-nav.tsx` + `lib/question-bank-nav.ts`.
 - **Folder-scoped header customize:** `components/question-bank-page-header.tsx`, `components/question-bank-client.tsx` — **`docs/question-bank-hub-header-pattern.md`**, **`.cursor/rules/exxat-question-bank-hub-header.mdc`**.

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

@@ -18,6 +18,8 @@ This document describes how list pages combine **views**, **toolbar** behavior,
 | **Team page (primary template)** | `TeamClient` = `ListPageTemplate` + `KeyMetrics` + `TeamPageHeader` + `TeamTable` (same composition as `DataListClient`) | `components/team-client.tsx`, `lib/mock/team-kpi.ts` |
 | **Team roster** | `TeamTable` — `DataTable` + `useTableState` + `TablePropertiesDrawer`; list/board/dashboard read **`tableState.rows`** | `components/team-table.tsx` |
 | **Dashboard view (list tab)** | **`KeyMetrics`** (`variant="flat"` or `"card"`) — same KPI system as the template metrics strip; **do not** add ad-hoc `Card` grids for entity summaries | `TeamTable` dashboard branch, `lib/mock/team-kpi.ts` |
+| **List hub metrics strip** | **`KeyMetrics variant="flat"`** — transparent cells, OKLCH brand glow only, border hairlines (**no** grey panel) | **`docs/kpi-flat-band-pattern.md`**, Placements / Team / Question bank clients |
+| **Secondary panel chrome** | **`--secondary-panel-bg`** on **`NestedSecondaryPanelShell`** (lighter than sidebar, follows active product) | **`docs/shell-surface-elevation-pattern.md`**, Question bank |
 | **Export** | `ExportDrawer` | `ListPageTemplate` export props; `DataListClient` |
 | **View body layout** (gutter + centered max-width for folder / icon / panel-style content) | **`ListPageViewFrame`** (`components/data-views/list-page-view-frame.tsx`, re-exported from `components/data-views`) | **`FolderGridView`** (uses the frame); **`QuestionBankOsFolderView`** — see **`AGENTS.md` §4.5** |
 

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

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exxatdesignux/ui",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "description": "Exxat shared design system (components, hooks, tokens). Monorepo setup: clone repo then pnpm bootstrap at workspace root — see github.com/ExxatDesign/Exxat-DS-Workspace README.",
   "type": "module",
   "engines": {

package/src/components/ui/sidebar.tsx

@@ -80,9 +80,9 @@ function SidebarProvider({
     if (typeof window === "undefined") return
     if (window.matchMedia(SIDEBAR_COOKIE_VIEWPORT_MQ).matches) return
     const fromCookie = readSidebarStateCookie()
-    if (fromCookie === undefined) return
+    if (fromCookie === undefined || fromCookie === open) return
     _setOpen(fromCookie)
-  }, [openProp])
+  }, [openProp, open])
 
   const setOpen = React.useCallback(
     (value: boolean | ((value: boolean) => boolean)) => {

package/src/globals.css

@@ -173,10 +173,21 @@ html[data-text-size="large"] {
   --leo-surface-tint-b: color-mix(in oklch, var(--brand-color) 8%, var(--background));
   --leo-surface-gradient: linear-gradient(180deg, var(--leo-surface-tint-a) 0%, var(--leo-surface-tint-b) 100%);
 
-  /* KeyMetrics `variant="flat"` — soft KPI band (lavender wash → canvas; dark: subtle brand lift) */
-  --key-metrics-flat-grad-top: color-mix(in oklch, var(--brand-tint-light) 90%, var(--background));
-  --key-metrics-flat-grad-mid: color-mix(in oklch, var(--brand-tint) 34%, var(--background));
-  --key-metrics-flat-cell-bg: color-mix(in oklch, var(--background) 80%, var(--brand-tint-light));
+  /* KeyMetrics `variant="flat"` — no band surface; bottom brand glow only (OKLCH). */
+  --key-metrics-flat-cell-bg: transparent;
+  --key-metrics-flat-divider: color-mix(in oklch, var(--sidebar-border) 55%, transparent);
+  --key-metrics-flat-band-radial: radial-gradient(
+    ellipse 120% 68% at 50% 100%,
+    color-mix(in oklch, var(--brand-color) 20%, transparent) 0%,
+    color-mix(in oklch, var(--brand-color) 8%, transparent) 42%,
+    transparent 72%
+  );
+  --key-metrics-flat-band-shadow: none;
+  --key-metrics-card-glow-radial: radial-gradient(
+    ellipse 110% 90% at 50% 100%,
+    color-mix(in oklch, var(--brand-color) 18%, transparent) 0%,
+    transparent 65%
+  );
 
   /* ── Surfaces ────────────────────────────────────────────────── */
   --background:         oklch(1 0 0);
@@ -256,8 +267,8 @@ html[data-text-size="large"] {
   --sidebar-ring:               oklch(0.25 0 0);
   /* Nav section titles — ≥4.5:1 vs --sidebar (not vs page white) */
   --sidebar-section-label-foreground: color-mix(in oklch, var(--sidebar-foreground) 58%, var(--sidebar));
-  /* Nested secondary rail — soft brand wash on canvas (not pure `--background`, not full `--sidebar`). */
-  --secondary-panel-bg:         color-mix(in oklch, var(--brand-tint) 34%, var(--background));
+  /* Nested secondary rail — elevation 1: brand wash, lighter than `--brand-tint` / sidebar. */
+  --secondary-panel-bg:         color-mix(in oklch, var(--background) 40%, var(--brand-tint-light) 60%);
 
   /* Browser UI (meta theme-color) — aligned with --brand-tint */
   --theme-color-chrome: #f3f2f8;
@@ -365,9 +376,20 @@ html[data-text-size="large"] {
   --destructive:        oklch(0.65 0.20 25);      /* brighter for dark bg */
   --destructive-foreground: oklch(0.10 0 0);
 
-  --key-metrics-flat-grad-top: color-mix(in oklch, var(--brand-color) 14%, var(--background));
-  --key-metrics-flat-grad-mid: color-mix(in oklch, var(--muted) 42%, var(--background));
-  --key-metrics-flat-cell-bg: color-mix(in oklch, var(--background) 88%, var(--brand-color));
+  /* KeyMetrics flat band — no surface; bottom brand glow only (OKLCH). */
+  --key-metrics-flat-cell-bg: transparent;
+  --key-metrics-flat-band-radial: radial-gradient(
+    ellipse 120% 68% at 50% 100%,
+    color-mix(in oklch, var(--brand-color) 26%, transparent) 0%,
+    color-mix(in oklch, var(--brand-color) 10%, transparent) 42%,
+    transparent 72%
+  );
+  --key-metrics-flat-band-shadow: none;
+  --key-metrics-card-glow-radial: radial-gradient(
+    ellipse 110% 90% at 50% 100%,
+    color-mix(in oklch, var(--brand-color) 22%, transparent) 0%,
+    transparent 62%
+  );
 
   /* Borders — visible but not washed out on dark surfaces */
   --border:            oklch(0.38 0.008 270);
@@ -417,8 +439,8 @@ html[data-text-size="large"] {
   --sidebar-border:             oklch(0.38 0.010 270);
   --sidebar-ring:               oklch(0.85 0 0);
   --sidebar-section-label-foreground: color-mix(in oklch, var(--sidebar-foreground) 48%, var(--sidebar));
-  /* Nested secondary rail — dark: subtle brand lift on canvas (not flat `--background` only). */
-  --secondary-panel-bg:         color-mix(in oklch, var(--background) 82%, var(--brand-color) 18%);
+  /* Nested secondary rail — elevation 1: brand stack, lifted toward `--card` / page. */
+  --secondary-panel-bg:         color-mix(in oklch, var(--card) 32%, var(--brand-tint) 68%);
   --theme-color-chrome:         #2f2d36;
 
   /* Lifted scrim on dark — white-tinted veil, not heavy black */
@@ -464,6 +486,12 @@ html[data-text-size="large"] {
   --secondary:      oklch(0.95 0.012 286.1);
   --accent:         oklch(0.925 0.015 286.1);
   --muted:          oklch(0.945 0.008 286.1);
+  --key-metrics-flat-band-radial: radial-gradient(
+    ellipse 120% 68% at 50% 100%,
+    oklch(0.50 0.14 286.1 / 0.22) 0%,
+    oklch(0.50 0.14 286.1 / 0.09) 42%,
+    transparent 72%
+  );
 }
 
 .theme-one.dark,
@@ -479,6 +507,12 @@ html[data-text-size="large"] {
   --secondary:        oklch(0.31 0.04 286.1);
   --muted:            oklch(0.31 0.04 286.1);
   --accent:           oklch(0.33 0.06 286.1);
+  --key-metrics-flat-band-radial: radial-gradient(
+    ellipse 120% 68% at 50% 100%,
+    oklch(0.50 0.14 286.1 / 0.28) 0%,
+    oklch(0.50 0.14 286.1 / 0.1) 42%,
+    transparent 72%
+  );
 }
 
 /* ==========================================================================
@@ -487,9 +521,14 @@ html[data-text-size="large"] {
    ========================================================================== */
 .theme-prism,
 .theme-rose {
-  --brand-color:      oklch(0.57 0.24 342);   /* Prism rose */
-  --brand-color-dark: oklch(0.42 0.24 342);
-  --ring:             var(--brand-color-dark);
+  --brand-tint:         oklch(0.97 0.02 343);
+  --brand-tint-light:   oklch(0.992 0.01 343);
+  --brand-tint-subtle:  oklch(0.93 0.028 343);
+  --brand-color:        oklch(0.57 0.24 342);   /* Prism rose */
+  --brand-color-light:  oklch(0.78 0.14 342);
+  --brand-color-dark:   oklch(0.42 0.24 342);
+  --brand-color-deep:   oklch(0.32 0.20 342);
+  --ring:               var(--brand-color-dark);
 }
 
 .theme-prism:not(.dark),
@@ -502,6 +541,12 @@ html[data-text-size="large"] {
   --muted:            oklch(0.945 0.008 343);
   --banner-prism-bg:  oklch(0.97 0.02 343);
   --theme-color-chrome: #fff5f9;
+  --key-metrics-flat-band-radial: radial-gradient(
+    ellipse 120% 68% at 50% 100%,
+    oklch(0.57 0.24 342 / 0.22) 0%,
+    oklch(0.57 0.24 342 / 0.09) 42%,
+    transparent 72%
+  );
 }
 
 .theme-prism.dark,
@@ -517,6 +562,12 @@ html[data-text-size="large"] {
   --muted:              oklch(0.31 0.04 342);
   --accent:             oklch(0.33 0.06 342);
   --theme-color-chrome: #2a2428;
+  --key-metrics-flat-band-radial: radial-gradient(
+    ellipse 120% 68% at 50% 100%,
+    oklch(0.57 0.24 342 / 0.28) 0%,
+    oklch(0.57 0.24 342 / 0.1) 42%,
+    transparent 72%
+  );
 }
 
 /* ==========================================================================

package/src/theme.css

@@ -220,7 +220,7 @@
   /* Nav section titles — ≥4.5:1 vs --sidebar (not vs page white) */
   --sidebar-section-label-foreground: color-mix(in oklch, var(--sidebar-foreground) 58%, var(--sidebar));
   /* Nested secondary rail — soft brand wash on canvas (not pure `--background`, not full `--sidebar`). */
-  --secondary-panel-bg:         color-mix(in oklch, var(--brand-tint) 34%, var(--background));
+  --secondary-panel-bg:         color-mix(in oklch, var(--background) 50%, var(--sidebar) 50%);
 
   /* Browser UI (meta theme-color) — aligned with --brand-tint */
   --theme-color-chrome: #f3f2f8;
@@ -346,8 +346,8 @@
   --sidebar-border:             oklch(0.38 0.010 270);
   --sidebar-ring:               oklch(0.85 0 0);
   --sidebar-section-label-foreground: color-mix(in oklch, var(--sidebar-foreground) 48%, var(--sidebar));
-  /* Nested secondary rail — dark: subtle brand lift on canvas (not flat `--background` only). */
-  --secondary-panel-bg:         color-mix(in oklch, var(--background) 82%, var(--brand-color) 18%);
+  /* Nested secondary rail — dark: neutral step between page canvas and sidebar (no per-product brand wash). */
+  --secondary-panel-bg:         color-mix(in oklch, var(--background) 58%, var(--sidebar) 42%);
   --theme-color-chrome:         #2f2d36;
 
   /* Lifted scrim on dark — white-tinted veil, not heavy black */

package/template/.cursor/rules/exxat-kbd-shortcuts.mdc

@@ -66,7 +66,7 @@ Use `@/components/ui/kbd` (`Kbd` + `KbdGroup`) anywhere users discover actions b
 | Duplicate | ⌘/Ctrl + **D** |
 | Review / Info | ⌘/Ctrl + **I** |
 | Remove / Delete | ⌘/Ctrl + **⌫** |
-| Add view (1..n) | ⌘/Ctrl + **⇧/Shift** + **1..9** |
+| Add view (1..n) | **1..9** (plain digit; skipped in inputs / open dialogs) |
 | **Submit a workflow** (Create, Save, Export, Apply) | **Enter** (⏎) — scoped to the form/drawer/dialog |
 | **Cancel / dismiss** a workflow | **Esc** (Radix handles for Dialog/Sheet) |
 | **Advance a multi-step wizard** | ⌘/Ctrl + **Enter** (plain Enter stays in the input) |

package/template/AGENTS.md

@@ -33,9 +33,11 @@ Cross-cutting Cursor rules also live in the repo root `.cursor/rules/` (data tab
 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.
+21. **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).
+22. **Before** changing **secondary panel** or **sidebar** brand chrome, read **`docs/shell-surface-elevation-pattern.md`** and **§4.6** ( **`--secondary-panel-bg`**, active product theme).
+23. **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/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).
 
 ---
 
@@ -165,6 +167,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)
@@ -510,6 +514,8 @@ New pages **SHOULD** namespace keys and version JSON (`v: 1`) for future migrati
 - **Drawer vs dialog (same route):** `docs/drawer-vs-dialog-pattern.md` — **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**
 - **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`**
@@ -574,7 +580,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 +590,4 @@ 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.*
+*Last updated: KPI flat band + shell surface elevation pattern docs/rules/skills; §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)/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)/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/global-error.tsx

@@ -0,0 +1,63 @@
+"use client"
+
+import * as React from "react"
+
+import "./globals.css"
+import { isChunkLoadError } from "@/lib/chunk-load-error"
+
+/**
+ * Root error boundary — catches failures outside the (app) segment layout.
+ */
+export default function GlobalError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string }
+  reset: () => void
+}) {
+  const chunkStale = isChunkLoadError(error)
+
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === "development") {
+      console.error(error)
+    }
+  }, [error])
+
+  return (
+    <html lang="en">
+      <body className="bg-background font-sans text-foreground">
+        <div
+          className="flex min-h-svh flex-col items-center justify-center gap-4 px-4 py-12 text-center"
+          role="alert"
+        >
+          <h1 className="text-lg font-semibold">Something went wrong</h1>
+          <p className="max-w-md text-sm text-muted-foreground">
+            {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 className="flex flex-wrap items-center justify-center gap-2">
+            {chunkStale ? (
+              <button
+                type="button"
+                className="inline-flex h-9 items-center justify-center rounded-md bg-primary px-4 text-sm font-medium text-primary-foreground"
+                onClick={() => window.location.reload()}
+              >
+                Reload page
+              </button>
+            ) : null}
+            <button
+              type="button"
+              className="inline-flex h-9 items-center justify-center rounded-md border border-input bg-background px-4 text-sm font-medium"
+              onClick={() => reset()}
+            >
+              Try again
+            </button>
+          </div>
+          </div>
+      </body>
+    </html>
+  )
+}