@exxatdesignux/ui 0.2.15 → 0.2.16

package/CHANGELOG.md

@@ -15,6 +15,18 @@ After the user bumps `@exxatdesignux/ui`, do this in order:
 
 ---
 
+## [0.2.16] - 2026-05-15
+
+### Changed
+
+- **Tokens**: `globals.css` / `theme.css` refinements and starter **`template/`** parity with the web app (layout, Question bank hub chrome, navigation).
+- **Consumer extras**: Cursor skills + pattern docs refreshed for collaboration / Question bank hub header.
+
+### Chore (monorepo)
+
+- **Dependabot**: version updates for `apps/web`, `packages/ui`, workspace root, and grouped Next.js + GitHub Actions bumps (see repo `.github/dependabot.yml`).
+- **Web app**: Next.js **16.2.6** (security patches), primary shell scroll fixes, `SiteHeader` chrome alignment.
+
 ## [0.2.15] - 2026-05-13
 
 ### Fixed

package/consumer-extras/cursor-skills/exxat-collaboration-access/SKILL.md

@@ -8,7 +8,8 @@ user-invocable: true
 
 **Handbook:** `apps/web/AGENTS.md` §4.7  
 **Narrative:** `apps/web/docs/collaboration-access-pattern.md`  
-**Cursor rule:** `.cursor/rules/exxat-collaboration-access.mdc`
+**Cursor rule:** `.cursor/rules/exxat-collaboration-access.mdc`  
+**Related (Question bank folder scope + ⋯ Customize folder):** `.cursor/rules/exxat-question-bank-hub-header.mdc` · `docs/question-bank-hub-header-pattern.md`
 
 ## Wiring checklist
 
@@ -19,6 +20,7 @@ user-invocable: true
 5. **Access maps** — `lib/collaborator-access.ts` for Owner / Editor / Commenter / Viewer, invite options, and **`COLLABORATION_HEADER_ADD_LABEL`**.
 6. **Header** — empty roster → outline **Add collaborator**; non-empty → face rail; both open the invite sheet.
 7. **Invite sheet** — `InviteCollaboratorsDrawer`: export-style **`Sheet`**, combined email + access menu, grouped roster (name → email → role tags → access badge).
+8. **Question bank — folder URL scope** — When **`?scope=folder`**, **`QuestionBankPageHeader`** **⋯** also lists **Customize folder**; **`QuestionBankNewFolderSheet`** on **`QuestionBankClient`** — **`.cursor/rules/exxat-question-bank-hub-header.mdc`**, **`docs/question-bank-hub-header-pattern.md`**.
 
 ## MUST NOT
 

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

@@ -22,6 +22,7 @@ description: >
 - **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`**.
+- **Question bank folder-scoped header (rule + doc):** **`.cursor/rules/exxat-question-bank-hub-header.mdc`** and **`docs/question-bank-hub-header-pattern.md`** — pair with **`exxat-primary-nav-secondary-panel`** when URL **`scope=folder`** drives the hub title.
 - **Consumer repos (npm install of `@exxatdesignux/ui`):** After a version bump, read **`node_modules/@exxatdesignux/ui/CHANGELOG.md`**, run **`npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras`** so **`docs/exxat-ds/consumer-upgrade-checklist.md`** and Cursor skills match the tarball, and diff the host app against **`node_modules/@exxatdesignux/ui/template/`** for anything new to port (routes, re-exports, AGENTS). Use **`exxat-ui changelog`**, **`exxat-ui update`**, and **`exxat-ui doctor`** for CLI guidance.
 
 ---
@@ -255,6 +256,8 @@ Use `PageHeader` from `@/components/page-header` for the content-area header (be
 
 When a hub is **shared**, use **`PageHeader` `variant="collaboration"`**: **empty roster** → outline **Add collaborator**; **non-empty** → face rail (faces / **`+N`** open the invite sheet). **Invite people** also lives under the entity header **⋯ More** and opens **`InviteCollaboratorsDrawer`** via **`CollaborationAccessFlow`** when possible. Library access (Owner / Editor / Commenter / Viewer) comes from **`lib/collaborator-access.ts`**; directory tags (Faculty, Program coordinator, Director) use **`PageHeaderCollaborator.roles`**.
 
+**Question bank library — folder URL scope:** When **`?scope=folder&folderId=`** applies, **⋯ More** must also offer **Customize folder** (**`QuestionBankPageHeader`** **`onCustomizeFolder`**) and the **`QuestionBankNewFolderSheet`** must be mounted on **`QuestionBankClient`** so it works on every **`ListPageTemplate`** view tab. **`.cursor/rules/exxat-question-bank-hub-header.mdc`** · **`docs/question-bank-hub-header-pattern.md`** (app: **`apps/web/docs/...`**).
+
 **Handbook:** `apps/web/AGENTS.md` §4.7 · **Doc:** `docs/collaboration-access-pattern.md` · **Skill:** `.cursor/skills/exxat-collaboration-access/SKILL.md` · **Reference:** Question bank header + client.
 
 ---

package/consumer-extras/cursor-skills/exxat-primary-nav-secondary-panel/SKILL.md

@@ -15,7 +15,8 @@ user-invocable: true
 2. **`components/secondary-panel.tsx`** — add **`PANELS["<id>"]`** → panel shell (title, optional search) + secondary nav component.
 3. **Hub client** — mount **`*PanelActivator`** with **`useAutoPanel("<id>")`** (same id) for the lifetime of the route (e.g. `QuestionBankPanelActivator`).
 4. **Data** — keep **one** **`useTableState`** / **`tableState.rows`**; drive scope from **URL** + small helpers (see **`lib/question-bank-nav.ts`**).
-5. **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`**).
+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`**).
 
 ## MUST NOT
 
@@ -26,3 +27,4 @@ user-invocable: true
 
 - `components/app-sidebar.tsx` — `openPanel` on same-route primary click.
 - `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/collaboration-access-pattern.md

@@ -2,6 +2,8 @@
 
 Shared UI for **who can access a hub** (face stack in the header) and **inviting people** (floating sheet). **Reference:** Question bank — `QuestionBankPageHeader`, `QuestionBankClient`, `InviteCollaboratorsDrawer`.
 
+**Folder-scoped question bank:** When the library URL selects a folder (`?scope=folder&folderId=`), the same header **⋯ More** menu also exposes **Customize folder** (name / color / icon) via **`QuestionBankNewFolderSheet`** mounted on **`QuestionBankClient`** so it works on every view tab. See **`docs/question-bank-hub-header-pattern.md`** and **`.cursor/rules/exxat-question-bank-hub-header.mdc`**.
+
 ## When to use
 
 - A list hub or library is **shared** across people (not a private directory).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exxatdesignux/ui",
-  "version": "0.2.15",
+  "version": "0.2.16",
   "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/globals.css

@@ -165,6 +165,19 @@ html[data-text-size="large"] {
   --brand-preview-one:   var(--brand-tint);
   --brand-preview-prism: oklch(0.57 0.24 342);
 
+  /**
+   * Ask Leo panel tints (same mixes as the vertical wash). Use for blobs, cards, etc.
+   * `--leo-surface-gradient` is the full linear wash on `AskLeoSidebar`.
+   */
+  --leo-surface-tint-a: color-mix(in oklch, var(--brand-color) 4%, var(--background));
+  --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));
+
   /* ── Surfaces ────────────────────────────────────────────────── */
   --background:         oklch(1 0 0);
   --foreground:         oklch(0.145 0 0);           /* ≈ #1A1A1A — 17:1 on white ✓ */
@@ -243,7 +256,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));
-  --secondary-panel-bg:         oklch(0.99 0.008 286.1);
+  /* 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));
 
   /* Browser UI (meta theme-color) — aligned with --brand-tint */
   --theme-color-chrome: #f3f2f8;
@@ -351,6 +365,10 @@ 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));
+
   /* Borders — visible but not washed out on dark surfaces */
   --border:            oklch(0.38 0.008 270);
   --border-control:    oklch(0.72 0.012 270);
@@ -399,7 +417,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));
-  --secondary-panel-bg:         oklch(0.23 0.02 270);
+  /* 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%);
   --theme-color-chrome:         #2f2d36;
 
   /* Lifted scrim on dark — white-tinted veil, not heavy black */

package/src/theme.css

@@ -219,7 +219,8 @@
   --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));
-  --secondary-panel-bg:         oklch(0.99 0.008 286.1);
+  /* 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));
 
   /* Browser UI (meta theme-color) — aligned with --brand-tint */
   --theme-color-chrome: #f3f2f8;
@@ -345,7 +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));
-  --secondary-panel-bg:         oklch(0.23 0.02 270);
+  /* 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%);
   --theme-color-chrome:         #2f2d36;
 
   /* Lifted scrim on dark — white-tinted veil, not heavy black */

package/template/AGENTS.md

@@ -162,7 +162,9 @@ Thread **`view`** and **`onViewChange`** from the **client** → **table / toolb
 
 **MUST NOT:** Set **`secondaryPanel`** without **`PANELS[id]`** and **`useAutoPanel`** — users see **collapsed** main nav with **no** panel body.
 
-**Cursor rule:** **`.cursor/rules/exxat-primary-nav-secondary-panel.mdc`**. **Icons in panel:** **`.cursor/rules/exxat-fontawesome-icons.mdc`**.
+**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`**.
+
+**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)
 
@@ -534,7 +536,7 @@ New pages **SHOULD** namespace keys and version JSON (`v: 1`) for future migrati
 | Data view charts: **`ChartFigure`** + **`ChartDataTable`**; keyboard highlight via **`chart-keyboard-selection`** (§4.3); layout via **`data-view-dashboard-storage`** | Ad-hoc `localStorage` keys for dashboard layout; opacity-only “selection” without `activeBar`/`activeShape` |
 | Board cards: **`ListPageBoardCard`** shell; status via **`ListHubStatusBadge`** + **`lib/list-status-badges`**; no **`uppercase`** on status chips (§4.4) | One-off board card markup; status as plain body text; duplicated status maps outside **`list-status-badges`**; **empty placeholder** primary hubs (§4.1) |
 | **§4.5** — Non-table view bodies use **`ListPageViewFrame`** (+ **`data-views/`** shells); new grids are generic components, not route-only markup | Duplicated `mx-4` / `max-w-*` per hub; wrapping **`DataTable`** so inset **doubles** (**§5**) |
-| **§4.6** — **`secondaryPanel`** + **`PANELS`** + **`useAutoPanel`** together for nested scope nav | **`secondaryPanel`** id with no panel component or activator |
+| **§4.6** — **`secondaryPanel`** + **`PANELS`** + **`useAutoPanel`** together for nested scope nav; **folder URL scope** → header **⋯** **Customize folder** + client-mounted **`QuestionBankNewFolderSheet`** (**`exxat-question-bank-hub-header.mdc`**) | **`secondaryPanel`** id with no panel component or activator; folder scope with customize **only** inside a single view tab’s subtree |
 | **§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 |
@@ -570,7 +572,7 @@ 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`**.
+- [ ] **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`**.
 - [ ] **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`**.
@@ -578,4 +580,4 @@ Copy and complete when implementing or reviewing:
 
 ---
 
-*Last updated: 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: 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.*

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

@@ -4,11 +4,15 @@ import * as React from "react"
 import { usePathname } from "next/navigation"
 
 import { useSecondaryPanel } from "@/components/secondary-panel"
-import { QUESTION_BANK_ENTRY_PATH } from "@/lib/question-bank-nav"
+import {
+  QUESTION_BANK_ENTRY_PATH,
+  QUESTION_BANK_HUB_FIND_PATH,
+  QUESTION_BANK_LIST_PATH,
+} from "@/lib/question-bank-nav"
 
 /**
- * Keeps the nested secondary panel open across library / list / find navigations.
- * The discovery hub (`/question-bank`) is full-width — no secondary bar there.
+ * Keeps the nested secondary panel open across library navigations.
+ * **Question hub** (`/question-bank`) and **Search** (`/find`, `/list`) stay full-width — no secondary rail.
  */
 export default function QuestionBankLayout({ children }: { children: React.ReactNode }) {
   const pathname = usePathname()
@@ -30,7 +34,10 @@ export default function QuestionBankLayout({ children }: { children: React.React
     const isDiscoveryHubRoot =
       pathname === QUESTION_BANK_ENTRY_PATH || pathname === `${QUESTION_BANK_ENTRY_PATH}/`
 
-    if (isDiscoveryHubRoot) {
+    const isDedicatedSearchSurface =
+      pathname === QUESTION_BANK_HUB_FIND_PATH || pathname === QUESTION_BANK_LIST_PATH
+
+    if (isDiscoveryHubRoot || isDedicatedSearchSurface) {
       closePanelRef.current({ mainSidebar: "leave" })
       return undefined
     }

package/template/app/globals.css

@@ -151,6 +151,14 @@ html[data-text-size="large"] {
      via a scoped class, not globally on :root. */
   /* Minimum readable UI copy: 11px (`text-xs` / --text-xs). Do not use smaller arbitrary sizes. */
 
+  /* ── Layout ─────────────────────────────────────────────────── */
+  /* SiteHeader / breadcrumb height. Mirrored on the SidebarProvider for
+     descendants; declared here too so JS that reads from documentElement
+     (e.g. DataTable sticky-head offset) can resolve it. Plain px so
+     `parseFloat` can read it as a number. Keep in sync with `headerHeight`
+     in components/sidebar-shell.tsx (currently `calc(var(--spacing) * 12)` = 48px). */
+  --header-height: 48px;
+
   /* ── Typography ─────────────────────────────────────────────── */
   /* Ivy Presto loaded via Adobe Fonts Kit wuk5wqn (use.typekit.net) */
   --font-heading: "ivypresto-text";
@@ -171,6 +179,19 @@ html[data-text-size="large"] {
   --brand-preview-one:   var(--brand-tint);
   --brand-preview-prism: oklch(0.57 0.24 342);
 
+  /**
+   * Ask Leo panel tints (same mixes as the vertical wash). Use for blobs, cards, etc.
+   * `--leo-surface-gradient` is the full linear wash on `AskLeoSidebar`.
+   */
+  --leo-surface-tint-a: color-mix(in oklch, var(--brand-color) 4%, var(--background));
+  --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));
+
   /* ── Surfaces ────────────────────────────────────────────────── */
   --background:         oklch(1 0 0);
   --foreground:         oklch(0.145 0 0);           /* ≈ #1A1A1A — 17:1 on white ✓ */
@@ -249,7 +270,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));
-  --secondary-panel-bg:         oklch(0.99 0.008 286.1);
+  /* 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));
 
   /* Browser UI (meta theme-color) — aligned with --brand-tint */
   --theme-color-chrome: #f3f2f8;
@@ -357,6 +379,10 @@ 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));
+
   /* Borders — visible but not washed out on dark surfaces */
   --border:            oklch(0.38 0.008 270);
   --border-control:    oklch(0.72 0.012 270);
@@ -405,7 +431,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));
-  --secondary-panel-bg:         oklch(0.23 0.02 270);
+  /* 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%);
   --theme-color-chrome:         #2f2d36;
 
   /* Lifted scrim on dark — white-tinted veil, not heavy black */

package/template/components/app-sidebar.tsx

@@ -52,6 +52,7 @@ import {
 import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
 import { Badge } from "@/components/ui/badge"
 import { StatusBadge } from "@/components/ui/status-badge"
+import { Separator } from "@/components/ui/separator"
 import {
   Tooltip,
   TooltipContent,
@@ -108,7 +109,8 @@ function normalizedLocationHash(locationHash: string): string {
 /**
  * Whether `pathname` (+ optional `location.hash`) matches a sidebar `href`.
  * When several links share the same path (e.g. `/settings`), disambiguate with `#fragment`
- * and require an empty hash for the “default” row (`/settings` with no `#`).
+ * in each `href` — those rows use the `frag !== null` branch below.
+ * For `href` without `#…`, an in-page hash (e.g. QB view tabs) does not clear the match.
  */
 function isNavActive(pathname: string, url: string, locationHash = ""): boolean {
   const pathOnly = navUrlPath(url)
@@ -129,7 +131,8 @@ function isNavActive(pathname: string, url: string, locationHash = ""): boolean
   }
 
   if (pathOnly === "/") return pathname === "/" && h === ""
-  if (pathname === pathOnly) return h === ""
+  /** Exact path match — ignore `location.hash` when the nav `href` has no `#…` fragment (QB view tabs use hash). */
+  if (pathname === pathOnly) return true
   // Design system library — active on hub and detail routes.
   if (pathOnly === "/library") {
     return pathname.startsWith("/library/")
@@ -165,6 +168,16 @@ function isCollapsibleChildActive(
 
   if (!isNavActive(pathname, child.url, locationHash)) return false
 
+  /** Hub entry (`/question-bank`) must not stay “active” on `/question-bank/library` etc. */
+  if (parent.primaryHubChildKey && child.key === parent.primaryHubChildKey) {
+    const hubPath = navUrlPath(parent.url)
+    if (hubPath) {
+      const normalized =
+        pathname.length > 1 && pathname.endsWith("/") ? pathname.slice(0, -1) : pathname
+      if (normalized !== hubPath) return false
+    }
+  }
+
   const urls = children.map(c => c.url)
   const allSameUrl = urls.length > 1 && urls.every(u => u === urls[0])
   if (allSameUrl) {
@@ -176,6 +189,32 @@ function isCollapsibleChildActive(
   return true
 }
 
+/**
+ * “Selected” styling on a collapsible **parent** row — not the same as “a descendant route is open”.
+ * When a child row is the current destination (e.g. Library on `/question-bank/library`), the parent
+ * should stay visually neutral while the child carries `data-active`. Only highlight the parent when
+ * the active child is the hub row whose `href` matches the parent (e.g. Question hub on `/question-bank`),
+ * or when no child matches but the parent URL still matches (edge routes).
+ */
+function isCollapsibleParentMenuButtonActive(
+  pathname: string,
+  item: NavLinkItem,
+  locationHash: string,
+): boolean {
+  const children = item.children
+  if (!children?.length) return isNavActive(pathname, item.url, locationHash)
+
+  const activeChildren = children.filter(c =>
+    isCollapsibleChildActive(pathname, item, c, locationHash),
+  )
+  if (activeChildren.length === 0) {
+    return isNavActive(pathname, item.url, locationHash)
+  }
+  if (activeChildren.length !== 1) return false
+  const [child] = activeChildren
+  return navUrlPath(child.url) === navUrlPath(item.url)
+}
+
 /** Accessible suffix for sidebar badges (badge is rendered outside the link node). */
 function badgeAccessibleSuffix(badge: number | string): string {
   if (typeof badge === "number") return `${badge} items`
@@ -183,30 +222,40 @@ function badgeAccessibleSuffix(badge: number | string): string {
 }
 
 /** Child row for expandable nav items — shared by inline sub-menu and collapsed-rail popover. */
-function SidebarNavChildLink({
-  parent,
-  child,
-  pathname,
-  locationHash,
-  onNavigate,
-  linkClassName,
-}: {
-  parent: NavLinkItem
-  child: NavLinkItem
-  pathname: string
-  locationHash: string
-  onNavigate?: () => void
-  /** Popover uses surface tokens; inline sub-menu uses `SidebarMenuSubButton`. */
-  linkClassName?: string
-}) {
+const SidebarNavChildLink = React.forwardRef<
+  HTMLAnchorElement,
+  {
+    parent: NavLinkItem
+    child: NavLinkItem
+    pathname: string
+    locationHash: string
+    onNavigate?: () => void
+    /** Popover uses surface tokens; inline sub-menu uses `SidebarMenuSubButton`. */
+    linkClassName?: string
+  } & Omit<React.ComponentPropsWithoutRef<typeof Link>, "href">
+>(function SidebarNavChildLink(
+  {
+    parent,
+    child,
+    pathname,
+    locationHash,
+    onNavigate,
+    linkClassName,
+    className: incomingClassName,
+    onClick,
+    ...linkRest
+  },
+  ref,
+) {
   const { openPanel } = useSecondaryPanel()
   const childActive = isCollapsibleChildActive(pathname, parent, child, locationHash)
   const childPath = navUrlPath(child.url)
 
   return (
     <Link
+      ref={ref}
       href={child.url}
-      className={cn("flex min-w-0 items-center gap-2", linkClassName)}
+      className={cn("flex min-w-0 items-center gap-2", linkClassName, incomingClassName)}
       aria-current={childActive ? "page" : undefined}
       onClick={e => {
         onNavigate?.()
@@ -218,15 +267,18 @@ function SidebarNavChildLink({
           e.preventDefault()
           openPanel(parent.secondaryPanel)
         }
+        onClick?.(e)
       }}
+      {...linkRest}
     >
       <span className="size-4 shrink-0 inline-flex items-center justify-center" aria-hidden="true">
-        {child.icon}
+        {childActive && child.iconActive ? child.iconActive : child.icon}
       </span>
       <span className="min-w-0 flex-1 truncate">{child.title}</span>
     </Link>
   )
-}
+})
+SidebarNavChildLink.displayName = "SidebarNavChildLink"
 
 /**
  * CollapsibleNavItem — isolated component so each collapsible has its own
@@ -235,19 +287,17 @@ function SidebarNavChildLink({
  * server (SSR) vs the client (router not yet available).
  */
 function CollapsibleNavItem({ item, pathname }: { item: NavLinkItem; pathname: string }) {
-  const locationHash     = useLocationHash()
-  const isActive         = isNavActive(pathname, item.url, locationHash)
+  const locationHash = useLocationHash()
   const isAnyChildActive =
     item.children?.some(c => isCollapsibleChildActive(pathname, item, c, locationHash)) ?? false
+  const parentMenuButtonActive = isCollapsibleParentMenuButtonActive(pathname, item, locationHash)
   const { state, isMobile } = useSidebar()
-  const { openPanel } = useSecondaryPanel()
   const [open, setOpen] = React.useState(false)
   const [flyoutOpen, setFlyoutOpen] = React.useState(false)
   const flyoutTitleId = React.useId()
   const iconRailCollapsed = state === "collapsed" && !isMobile
-  const showActiveStyle = isActive || isAnyChildActive
   const triggerIcon =
-    showActiveStyle && item.iconActive ? item.iconActive : item.icon
+    parentMenuButtonActive && item.iconActive ? item.iconActive : item.icon
 
   React.useEffect(() => {
     setOpen(isAnyChildActive)
@@ -267,23 +317,20 @@ function CollapsibleNavItem({ item, pathname }: { item: NavLinkItem; pathname: s
           open={flyoutOpen}
           onOpenChange={next => {
             setFlyoutOpen(next)
-            if (next && item.secondaryPanel) {
-              openPanel(item.secondaryPanel)
-            }
           }}
         >
           <Tooltip>
             <TooltipTrigger asChild>
               <PopoverTrigger asChild>
                 <SidebarMenuButton
-                  isActive={showActiveStyle}
+                  isActive={parentMenuButtonActive}
                   aria-haspopup="dialog"
                   aria-label={`${item.title} — open subpages`}
                 >
                   <span
                     className={cn(
                       "size-4 shrink-0 flex items-center justify-center",
-                      showActiveStyle &&
+                      parentMenuButtonActive &&
                         "[animation:sidebar-icon-pop_380ms_cubic-bezier(0.34,1.56,0.64,1)_both]",
                     )}
                     aria-hidden="true"
@@ -341,9 +388,6 @@ function CollapsibleNavItem({ item, pathname }: { item: NavLinkItem; pathname: s
       open={open}
       onOpenChange={next => {
         setOpen(next)
-        if (next && item.secondaryPanel) {
-          openPanel(item.secondaryPanel)
-        }
       }}
       asChild
     >
@@ -351,12 +395,12 @@ function CollapsibleNavItem({ item, pathname }: { item: NavLinkItem; pathname: s
         <Tooltip>
           <TooltipTrigger asChild>
             <CollapsibleTrigger asChild>
-              <SidebarMenuButton isActive={showActiveStyle}>
+              <SidebarMenuButton isActive={parentMenuButtonActive}>
                 <span
-                  key={showActiveStyle ? "active" : "idle"}
+                  key={parentMenuButtonActive ? "active" : "idle"}
                   className={cn(
                     "size-4 shrink-0 flex items-center justify-center",
-                    showActiveStyle &&
+                    parentMenuButtonActive &&
                       "[animation:sidebar-icon-pop_380ms_cubic-bezier(0.34,1.56,0.64,1)_both]",
                   )}
                   aria-hidden="true"
@@ -769,10 +813,7 @@ function ProductLogoButton() {
             >
               {iconRail ? (
                 <span className="flex size-8 shrink-0 items-center justify-center">
-                  <ExxatProductMark
-                    product={current.id}
-                    className="size-7 max-h-none"
-                  />
+                  <ExxatProductMark product={current.id} className="size-7" />
                 </span>
               ) : (
                 <span className="flex min-h-0 min-w-0 flex-1 items-stretch gap-2">
@@ -901,6 +942,13 @@ export function AppSidebar({ ...props }: React.ComponentProps<typeof Sidebar>) {
                   <ProductLogoButton />
                 </SidebarMenuItem>
               </SidebarMenu>
+              <div className="flex w-full justify-center px-2">
+                <Separator
+                  orientation="horizontal"
+                  decorative
+                  className="my-1.5 h-px w-full max-w-none shrink-0 bg-sidebar-border group-data-[collapsible=icon]:w-8"
+                />
+              </div>
               <TeamSwitcher />
             </SidebarHeaderStack>
           </SidebarHeader>

package/template/components/ask-leo-sidebar.tsx

@@ -286,8 +286,7 @@ export function AskLeoSidebar() {
       style={
         open
           ? {
-              background:
-                "linear-gradient(180deg, color-mix(in oklch, var(--brand-color) 4%, var(--background)) 0%, color-mix(in oklch, var(--brand-color) 8%, var(--background)) 100%)",
+              background: "var(--leo-surface-gradient)",
             }
           : undefined
       }

package/template/components/data-views/finder-panel-view.tsx

@@ -3,7 +3,7 @@
 /**
  * FinderPanelView — Miller-style 3-column split for list-page hubs.
  *
- * Visual shell matches Question bank panel (`ListPageTreeColumnHeader`, `bg-muted/15` columns,
+ * Visual shell matches Question bank panel (`ListPageTreeColumnHeader`, `LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS`,
  * shared resizable handles) — see `list-page-split-hub-tokens.ts`.
  */
 
@@ -142,7 +142,7 @@ export function FinderGroupStrip({
     <div
       role="toolbar"
       aria-label={ariaLabel}
-      className="flex min-h-10 flex-wrap items-center gap-1.5 border-b border-border bg-muted/15 px-2 py-2"
+      className="flex min-h-10 flex-wrap items-center gap-1.5 border-b border-border bg-card px-2 py-2"
     >
       {groups.map(group => {
         const isSelected = group.id === selectedGroupId

package/template/components/data-views/index.ts

@@ -47,6 +47,25 @@ export {
   type ListPageTreeColumnHeaderProps,
 } from "@/components/data-views/list-page-tree-column-header"
 
+/** VS Code–style outline tree chrome — mirrors shadcn `SidebarMenuSub` (see module doc). */
+export {
+  OutlineTreeCollapsibleContentRail,
+  OutlineTreeLeafButton,
+  OutlineTreeMenu,
+  OutlineTreeMenuItem,
+  OutlineTreeSub,
+  OutlineTreeSubItem,
+  OUTLINE_TREE_COLLAPSIBLE_CONTENT_RAIL_CLASS,
+  OUTLINE_TREE_CHEVRON_GUIDE_SPACER_CLASS,
+  OUTLINE_TREE_SUB_ROW_SHIFT_CLASS,
+  type OutlineTreeGuideLayout,
+  type OutlineTreeLeafButtonProps,
+  type OutlineTreeSurface,
+} from "@/components/data-views/outline-tree-menu"
+
+export { QuestionBankFolderTreeBranch } from "@/components/data-views/question-bank-folder-tree-branch"
+export type { QuestionBankFolderTreeBranchProps } from "@/components/data-views/question-bank-folder-tree-branch"
+
 export {
   LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS,
   LIST_PAGE_SPLIT_MILLER_DETAIL_PANEL_CLASS,