@exxatdesignux/ui 0.2.16 → 0.2.18

package/src/components/ui/banner.tsx

@@ -153,6 +153,7 @@ export function SystemBanner({
       <a
         href={action.href}
         className="inline-flex shrink-0 items-center gap-1 text-xs font-semibold underline underline-offset-2 hover:no-underline"
+        suppressHydrationWarning
       >
         {action.label}
         <i className="fa-light fa-arrow-right text-xs" aria-hidden="true" />
@@ -185,6 +186,7 @@ export function SystemBanner({
         ...(variant === "promo" ? { boxShadow: promoOuterShadow } : null),
         ...style,
       }}
+      suppressHydrationWarning
       {...props}
     >
       {decorativeOverlay ? (

package/src/components/ui/chart.tsx

@@ -69,6 +69,50 @@ function ChartContainer({
   )
 }
 
+/**
+ * Conservative validators for the two values interpolated into a `<style>`
+ * block via `dangerouslySetInnerHTML`.
+ *
+ * `ChartConfig.color` is typed as a free `string` and may be authored by
+ * downstream consumers of `@exxatdesignux/ui` who could pass user-controlled
+ * data. To prevent CSS injection (escaping the property value, closing the
+ * block, or injecting `</style>`) we accept only a documented allowlist of
+ * CSS color syntaxes and reject anything that contains rule-terminating or
+ * markup-sensitive characters.
+ *
+ * Keys come from `ChartConfig` and become CSS custom-property names, so they
+ * are restricted to a safe identifier alphabet.
+ */
+const CSS_KEY_PATTERN = /^[A-Za-z0-9_-]+$/
+
+const SAFE_COLOR_PATTERN = new RegExp(
+  [
+    /^#[0-9a-fA-F]{3,8}$/,                              // #rgb / #rrggbb / #rrggbbaa
+    /^rgba?\([^;{}<>"'\\]*\)$/,                         // rgb()/rgba()
+    /^hsla?\([^;{}<>"'\\]*\)$/,                         // hsl()/hsla()
+    /^hwb\([^;{}<>"'\\]*\)$/,                           // hwb()
+    /^lab\([^;{}<>"'\\]*\)$/,                           // lab()
+    /^lch\([^;{}<>"'\\]*\)$/,                           // lch()
+    /^oklab\([^;{}<>"'\\]*\)$/,                         // oklab()
+    /^oklch\([^;{}<>"'\\]*\)$/,                         // oklch()
+    /^color\([^;{}<>"'\\]*\)$/,                         // color()
+    /^color-mix\([^;{}<>"'\\]*\)$/,                     // color-mix()
+    /^var\(--[A-Za-z0-9_-]+(?:\s*,[^;{}<>"'\\]+)?\)$/,  // var(--token[, fallback])
+    /^[a-zA-Z]+$/,                                      // named colors + currentColor/transparent
+  ]
+    .map((re) => re.source)
+    .join("|"),
+)
+
+function sanitizeChartColor(color: string): string | null {
+  const trimmed = color.trim()
+  if (!trimmed) return null
+  // Defence-in-depth: any of these characters could break out of the value
+  // and turn the inline `<style>` block into an injection sink.
+  if (/[;{}<>"'\\]/.test(trimmed)) return null
+  return SAFE_COLOR_PATTERN.test(trimmed) ? trimmed : null
+}
+
 const ChartStyle = ({ id, config }: { id: string; config: ChartConfig }) => {
   const colorConfig = Object.entries(config).filter(
     ([, config]) => config.theme || config.color
@@ -78,6 +122,13 @@ const ChartStyle = ({ id, config }: { id: string; config: ChartConfig }) => {
     return null
   }
 
+  // `id` is generated from `React.useId()` in `ChartContainer`, but consumers
+  // can override it via the `id` prop, so we still verify the shape before
+  // interpolating it into a CSS selector.
+  if (!CSS_KEY_PATTERN.test(id)) {
+    return null
+  }
+
   return (
     <style
       dangerouslySetInnerHTML={{
@@ -87,11 +138,15 @@ const ChartStyle = ({ id, config }: { id: string; config: ChartConfig }) => {
 ${prefix} [data-chart=${id}] {
 ${colorConfig
   .map(([key, itemConfig]) => {
-    const color =
+    if (!CSS_KEY_PATTERN.test(key)) return null
+    const rawColor =
       itemConfig.theme?.[theme as keyof typeof itemConfig.theme] ||
       itemConfig.color
-    return color ? `  --color-${key}: ${color};` : null
+    if (!rawColor) return null
+    const safeColor = sanitizeChartColor(rawColor)
+    return safeColor ? `  --color-${key}: ${safeColor};` : null
   })
+  .filter(Boolean)
   .join("\n")}
 }
 `

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)) => {
@@ -490,6 +490,7 @@ function SidebarMenuItem({ className, ...props }: React.ComponentProps<"li">) {
     <li
       data-slot="sidebar-menu-item"
       data-sidebar="menu-item"
+      suppressHydrationWarning
       className={cn(
         "group/menu-item relative",
         /* Icon rail: center the square menu control in the column (footer + primary). */

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

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/.cursor/rules/exxat-mono-ids.mdc

@@ -0,0 +1,30 @@
+---
+description: Exxat DS — monospace typography for record IDs, question IDs, and other system identifiers
+globs: apps/web/**/*.tsx
+alwaysApply: false
+---
+
+# Exxat DS — monospace IDs
+
+Use this when rendering **system identifiers** — values a user copies, searches, or matches in APIs and tables (not human-readable names or prose).
+
+## MUST
+
+1. **Class** — Wrap identifier text in **`font-mono tabular-nums`**. Add size/color from context: typically **`text-xs text-muted-foreground`** (secondary line, table meta) or **`text-sm`** when the ID is the primary label in a narrow cell.
+2. **What counts as an ID** — Question IDs (`questionId`, `Q-YYMM-XXXX`), record/entity keys shown in UI, folder/surface technical keys when displayed as identifiers, hex tokens in pickers, audit/log principals, site/row **`id`** columns meant for lookup.
+3. **Mixed lines** — When an ID sits beside prose (e.g. page subtitle), only the ID segment is mono; keep separators and labels in the default sans stack.
+
+## SHOULD
+
+- Match existing hubs: **`question-bank-table.tsx`**, **`question-bank-list-view.tsx`**, **`new-question-composer.tsx`** (header subtitle), **`sites-table.tsx`** (`row.id`).
+- Prefer **`truncate`** / **`min-w-0`** on mono IDs in tight layouts so long tokens do not blow out columns.
+
+## MUST NOT
+
+- Apply **`font-mono`** to **person names**, **folder display names**, **status labels**, **dates**, **counts**, **currency**, or **body copy** — only the identifier token.
+- Use mono for **option letters** (A/B/C) or **step numbers** unless they are literal system IDs.
+
+## See also
+
+- **`.cursor/skills/exxat-mono-ids/SKILL.md`**
+- **`apps/web/AGENTS.md`** — §1 item on IDs, §13 checklist

package/template/AGENTS.md

@@ -18,23 +18,26 @@ Cross-cutting Cursor rules also live in the repo root `.cursor/rules/` (data tab
 6. **Before** adding or changing **board (kanban) cards** on list hubs, read **§4.4** and the **`exxat-board-cards`** skill (**`.cursor/skills/`** or **`.claude/skills/`** at repo root — same content).
 7. **Before** adding **folder, panel, or other non-table view bodies** (centered grids, reusable shells), read **§4.5** and **`.cursor/rules/exxat-list-page-view-shells.mdc`** / **`.cursor/skills/exxat-list-page-view-shells/SKILL.md`**.
 8. **Before** adding or changing **Font Awesome** icons in app UI, read **`.cursor/rules/exxat-fontawesome-icons.mdc`** (Kit subsetting, weights, **`aria-hidden`** on **`<i>`**).
-9. **Before** adding a **primary nav row** that opens a **nested secondary nav panel** (Question bank style), read **§4.6** and **`.cursor/rules/exxat-primary-nav-secondary-panel.mdc`**.
-10. **Before** adding **shared access / invite collaborators** on a hub (face stack + invite sheet), read **§4.7** and **`.cursor/rules/exxat-collaboration-access.mdc`** / **`.cursor/skills/exxat-collaboration-access/SKILL.md`**.
-11. **Before** adding **onboarding tours, feature walkthroughs, or coach marks**, read **§11** and `references/coach-marks.md`.
-12. **Before** changing the **global command palette (⌘K)** or search/AI entry UX, read **§7.1** and **`docs/command-menu-pattern.md`**.
-13. **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).
-14. **Before** adding **success/error/confirmation feedback**, read **§6.5** and **`.cursor/rules/exxat-no-toast.mdc`** (no toast or snackbars).
-15. Prefer **composing existing components** over new one-off UI. If something is missing, **extend** shared components under `components/`, not a single page file.
+9. **Before** rendering **record IDs, question IDs, or other system identifiers**, read **`.cursor/rules/exxat-mono-ids.mdc`** and **`.cursor/skills/exxat-mono-ids/SKILL.md`** (**`font-mono tabular-nums`**).
+10. **Before** adding a **primary nav row** that opens a **nested secondary nav panel** (Question bank style), read **§4.6** and **`.cursor/rules/exxat-primary-nav-secondary-panel.mdc`**.
+11. **Before** adding **shared access / invite collaborators** on a hub (face stack + invite sheet), read **§4.7** and **`.cursor/rules/exxat-collaboration-access.mdc`** / **`.cursor/skills/exxat-collaboration-access/SKILL.md`**.
+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.
     - **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**).
     - **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).
-16. **Match** naming, imports, and patterns of the nearest reference implementation (usually Placements).
-17. **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).
-18. **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`**.
-19. **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).
-20. **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.
+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** 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).
 
 ---
 
@@ -42,8 +45,8 @@ Cross-cutting Cursor rules also live in the repo root `.cursor/rules/` (data tab
 
 1. **User / task instructions** in the current session (highest).
 2. This **`AGENTS.md`** for Exxat DS product patterns.
-3. **`.cursor/rules/*.mdc`** at repo root (`exxat-data-tables`, `exxat-list-page-connected-views`, `exxat-centralized-list-dataset`, `exxat-list-page-view-shells`, `exxat-table-properties-drawer`, `exxat-board-cards`, `exxat-page-vs-drawer`, `exxat-drawer-vs-dialog`, `exxat-card-vs-list-rows`, `exxat-kpi-max-four`, `exxat-reuse-before-custom`, `exxat-no-toast`, `exxat-kbd-shortcuts`, `exxat-accessibility`, `exxat-fontawesome-icons`, `exxat-primary-nav-secondary-panel`, `exxat-collaboration-access`, `exxat-ds-agents`) and any rules under **`exxat-ds/.cursor/rules/`** (including **`exxat-dashboard-view-charts`** for Data view charts).
-4. Project **skills** under `.cursor/skills/` when relevant — e.g. **shadcn**, **exxat-accessibility** (WCAG / ARIA / touch / contrast), **exxat-board-cards** (kanban card shell, status badges, primitives), **exxat-list-page-view-shells** (centered view bodies, **`ListPageViewFrame`**), **exxat-centralized-list-dataset** (one **`useTableState`** row bag + shared maps across all list-hub views and **`TablePropertiesDrawer`**), **exxat-collaboration-access** (face rail + invite sheet + library access), **exxat-dedicated-search-surfaces** (landing vs results split, **`DedicatedSearch*`** templates + recents without hydration drift), **exxat-drawer-vs-dialog**, **exxat-card-vs-list-rows**, **exxat-kpi-max-four**.
+3. **`.cursor/rules/*.mdc`** at repo root (`exxat-data-tables`, `exxat-list-page-connected-views`, `exxat-centralized-list-dataset`, `exxat-list-page-view-shells`, `exxat-table-properties-drawer`, `exxat-board-cards`, `exxat-page-vs-drawer`, `exxat-drawer-vs-dialog`, `exxat-card-vs-list-rows`, `exxat-kpi-max-four`, `exxat-reuse-before-custom`, `exxat-no-toast`, `exxat-kbd-shortcuts`, `exxat-accessibility`, `exxat-fontawesome-icons`, **`exxat-mono-ids`**, `exxat-primary-nav-secondary-panel`, `exxat-collaboration-access`, `exxat-ds-agents`) and any rules under **`exxat-ds/.cursor/rules/`** (including **`exxat-dashboard-view-charts`** for Data view charts).
+4. Project **skills** under `.cursor/skills/` when relevant — e.g. **shadcn**, **exxat-accessibility** (WCAG / ARIA / touch / contrast), **exxat-board-cards** (kanban card shell, status badges, primitives), **exxat-list-page-view-shells** (centered view bodies, **`ListPageViewFrame`**), **exxat-centralized-list-dataset** (one **`useTableState`** row bag + shared maps across all list-hub views and **`TablePropertiesDrawer`**), **exxat-collaboration-access** (face rail + invite sheet + library access), **exxat-dedicated-search-surfaces** (landing vs results split, **`DedicatedSearch*`** templates + recents without hydration drift), **exxat-drawer-vs-dialog**, **exxat-card-vs-list-rows**, **exxat-kpi-max-four**, **`exxat-mono-ids`** (monospace system identifiers).
 
 If two documents conflict, prefer the **more specific** rule for the file type, then **newer** team decisions captured in `AGENTS.md`.
 
@@ -164,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)
@@ -509,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`**
@@ -540,6 +547,7 @@ New pages **SHOULD** namespace keys and version JSON (`v: 1`) for future migrati
 | **§4.7** — **`PageHeader` `variant="collaboration"`** + **`CollaborationAccessFlow`** / **`InviteCollaboratorsDrawer`**; empty **Add collaborator** + non-empty face rail; roster + invite from **`collaborator-access.ts`** | Extra invite beside a populated face rail; per-person roster cards; forked access enums; toast on invite |
 | **§4.8** — **`DedicatedSearch*`** templates + composer + recents; **no** `localStorage` in **`useState`** initial paint; hub-specific **`patchSearchParams`** only | Forked `*QuestionBank*SearchLanding*` shells for another entity; hydration mismatch on recents |
 | **Font Awesome** — Kit in **`app/layout.tsx`**; **`fa-light` / `fa-solid`** conventions; **`aria-hidden`** on decorative **`<i>`**; run **`fa:subset-audit`** when adding glyphs (**`exxat-fontawesome-icons.mdc`**) | Parallel icon libraries for the same product chrome |
+| **System IDs** — **`font-mono tabular-nums`** on question/record keys; mono **only** the ID token in mixed subtitles (**`exxat-mono-ids.mdc`**) | Mono on names, statuses, dates, or whole subtitle lines |
 
 ---
 
@@ -572,12 +580,14 @@ 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`**.
 - [ ] **Font Awesome:** New glyphs covered by **`fa:subset-audit`** / Kit subset; decorative **`<i>`** has **`aria-hidden`**; icon-only controls follow **§8.6** — **`.cursor/rules/exxat-fontawesome-icons.mdc`**.
+- [ ] **System IDs:** Visible **`questionId`**, record keys, and copy-pasteable identifiers use **`font-mono tabular-nums`**; mixed lines mono-wrap **only** the ID — **`.cursor/rules/exxat-mono-ids.mdc`**, **`.cursor/skills/exxat-mono-ids/SKILL.md`**.
 
 ---
 
-*Last updated: 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)/data-list/page.tsx

@@ -1,10 +1,10 @@
-import { DataListClient } from "@/components/data-list-client"
+import { PlacementsClient } from "@/components/placements-client"
 import { PrimaryPageTemplate } from "@/components/templates/primary-page-template"
 
 export default function DataListPage() {
   return (
     <PrimaryPageTemplate siteHeader={{ title: "List hub" }}>
-      <DataListClient />
+      <PlacementsClient />
     </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)/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)/question-bank/layout.tsx

@@ -10,17 +10,31 @@ import {
   QUESTION_BANK_LIST_PATH,
 } from "@/lib/question-bank-nav"
 
+/** Full-page focused flows under `/question-bank/*` that suppress the secondary panel. */
+const QUESTION_BANK_FOCUSED_FLOW_PATHS: readonly string[] = ["/question-bank/new"]
+
+function isQuestionBankFocusedFlow(pathname: string): boolean {
+  return QUESTION_BANK_FOCUSED_FLOW_PATHS.some(p => pathname === p || pathname.startsWith(`${p}/`))
+}
+
 /**
  * Keeps the nested secondary panel open across library navigations.
- * **Question hub** (`/question-bank`) and **Search** (`/find`, `/list`) stay full-width — no secondary rail.
+ * **Question hub** (`/question-bank`), **Search** (`/find`, `/list`), and
+ * focused authoring routes (`/new`) stay full-width — no secondary rail.
  */
 export default function QuestionBankLayout({ children }: { children: React.ReactNode }) {
   const pathname = usePathname()
   const { openPanel, closePanel, activePanel } = useSecondaryPanel()
   const closePanelRef = React.useRef(closePanel)
   const openPanelRef = React.useRef(openPanel)
-  closePanelRef.current = closePanel
-  openPanelRef.current = openPanel
+  // "Latest ref" pattern — keep callbacks current without re-running the
+  // route effect below on every render. `useEffect` (no deps) updates the
+  // refs after each render; React's `refs` rule disallows direct ref writes
+  // during render so the assignment lives here instead.
+  React.useEffect(() => {
+    closePanelRef.current = closePanel
+    openPanelRef.current = openPanel
+  })
 
   /** Leaving `/question-bank/*` entirely — close nested panel without forcing primary sidebar open (⌘B / cookie). */
   React.useEffect(() => {
@@ -37,7 +51,7 @@ export default function QuestionBankLayout({ children }: { children: React.React
     const isDedicatedSearchSurface =
       pathname === QUESTION_BANK_HUB_FIND_PATH || pathname === QUESTION_BANK_LIST_PATH
 
-    if (isDiscoveryHubRoot || isDedicatedSearchSurface) {
+    if (isDiscoveryHubRoot || isDedicatedSearchSurface || isQuestionBankFocusedFlow(pathname)) {
       closePanelRef.current({ mainSidebar: "leave" })
       return undefined
     }
@@ -46,7 +60,6 @@ export default function QuestionBankLayout({ children }: { children: React.React
       openPanelRef.current("question-bank")
     }
     return undefined
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- pathname + activePanel drive when to ensure panel id
   }, [pathname, activePanel])
 
   return children