@exxatdesignux/ui 0.2.15 → 0.2.17

package/consumer-extras/cursor-skills/exxat-ds-skill/references/data-table-pattern.md

@@ -0,0 +1,382 @@
+# Data Table Pattern — Full Implementation Guide
+
+Reference implementation: `components/team-table.tsx` (Team) and `components/data-list-table.tsx` (Placements).
+
+---
+
+## Stack Summary
+
+```
+DataTable                         ← base table component
+  └── useTableState               ← manages sort/filter/column/group state
+  └── toolbarSlot                 ← renders the properties button + drawer
+        └── TablePropertiesDrawer ← columns, density, filters, sort, conditional rules
+```
+
+All imports:
+```ts
+import { DataTable } from "@/components/data-table"
+import type { ColumnDef } from "@/components/data-table/types"
+import { useTableState } from "@/components/data-table/use-table-state"
+import { TablePropertiesDrawer } from "@/components/table-properties"
+import type {
+  ConditionalRule,
+  FilterFieldDef,
+  FilterOperator,
+} from "@/components/table-properties/types"
+import {
+  DEFAULT_DATA_LIST_DISPLAY_OPTIONS,
+  type DataListDisplayOptions,
+} from "@/lib/data-list-display-options"
+```
+
+---
+
+## Column Definition Patterns
+
+### Text column with filter
+```ts
+{
+  key: "name",
+  label: "Name",
+  width: 240,
+  minWidth: 160,
+  sortable: true,
+  sortKey: "name",
+  defaultPin: "left",          // pin to left (optional)
+  filter: {
+    type: "text",
+    icon: "fa-user",
+    operators: ["contains", "not_contains"],
+  },
+  cell: row => (
+    <span className="text-sm font-medium text-foreground truncate">{row.name}</span>
+  ),
+}
+```
+
+### Select (enum) column with filter
+```ts
+{
+  key: "status",
+  label: "Status",
+  width: 120,
+  minWidth: 100,
+  sortable: true,
+  sortKey: "status",
+  filter: {
+    type: "select",
+    icon: "fa-circle-dot",
+    operators: ["is", "is_not"],
+    options: [
+      { value: "active", label: "Active" },
+      { value: "inactive", label: "Inactive" },
+    ],
+  },
+  cell: row => (
+    <Badge variant="outline" className={cn("text-[10px] font-medium uppercase tracking-wide", STATUS_BADGE[row.status])}>
+      {STATUS_LABEL[row.status]}
+    </Badge>
+  ),
+}
+```
+
+### Select column (pinned right, no filter)
+```ts
+{
+  key: "select",
+  label: "",
+  width: 40,
+  minWidth: 40,
+  defaultPin: "left",
+  lockPin: true,
+}
+```
+
+### Actions column (pinned right)
+```ts
+{
+  key: "actions",
+  label: "",
+  width: 48,
+  minWidth: 48,
+  defaultPin: "right",
+  lockPin: true,
+  cell: row => (
+    <div className="flex items-center justify-center">
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button size="icon-sm" variant="ghost" aria-label={`Actions for ${row.name}`}>
+            <i className="fa-light fa-ellipsis text-sm" aria-hidden="true" />
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end" className="w-40">
+          <DropdownMenuItem disabled>
+            <i className="fa-light fa-pen" aria-hidden="true" />
+            Edit
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  ),
+}
+```
+
+---
+
+## Status Badge Pattern
+
+```ts
+const STATUS_LABEL: Record<MyType["status"], string> = {
+  active: "Active",
+  inactive: "Inactive",
+  pending: "Pending",
+}
+
+const STATUS_BADGE: Record<MyType["status"], string> = {
+  active:   "bg-emerald-500/15 text-emerald-800 dark:text-emerald-200 border-emerald-500/20",
+  inactive: "bg-slate-500/10 text-slate-700 dark:text-slate-200 border-border",
+  pending:  "bg-amber-500/15 text-amber-900 dark:text-amber-100 border-amber-500/20",
+}
+```
+
+---
+
+## Filter Field Derivation
+
+Convert column defs to filter field defs for the drawer:
+
+```ts
+function columnToFilterFieldDef(c: ColumnDef<T>): FilterFieldDef | null {
+  if (!c.filter) return null
+  const f = c.filter
+  const defaultOps: FilterOperator[] =
+    f.type === "select" || f.type === "date" ? ["is", "is_not"] : ["contains", "not_contains"]
+  return {
+    key: c.key,
+    label: c.label,
+    icon: f.icon ?? "fa-filter",
+    type: f.type,
+    operators: (f.operators ?? defaultOps) as FilterOperator[],
+    options: f.options,
+  }
+}
+```
+
+---
+
+## Drawer Toolbar Component
+
+The `toolbarSlot` renders the Properties button and the drawer. Full pattern:
+
+```tsx
+function FooDrawerToolbar({ state, totalRows, filterFields, fieldDefinitionsForDrawer, resolveColumnLabel, displayOptions, onDisplayOptionsChange, conditionalRules, onAddConditionalRule, onRemoveConditionalRule, onUpdateConditionalRule }) {
+  const { sheetOpen, setSheetOpen, showGridlines, setShowGridlines, rowHeight, setRowHeight,
+    activeFilters, addFilter, updateFilter, removeFilter, getConnector, toggleConnector,
+    filterBarVisible, setFilterBarVisible, drawerExpandedFilters, setDrawerExpandedFilters,
+    rows, sortRules, setSortRules, addSortRule, removeSortRule, toggleSortDir,
+    colOrder, setColOrder, hiddenCols, toggleColVisibility, moveCol, groupBy, setGroupBy, sortKey,
+  } = state
+
+  return (
+    <>
+      <TooltipProvider>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button
+              type="button" variant="ghost" size="icon-sm" aria-label="Properties"
+              onClick={() => setSheetOpen(true)}
+              className={cn(sheetOpen ? "bg-accent text-accent-foreground" : "text-muted-foreground hover:text-interactive-hover-foreground hover:bg-interactive-hover")}
+            >
+              <i className="fa-light fa-sliders text-[13px]" aria-hidden="true" />
+            </Button>
+          </TooltipTrigger>
+          <TooltipContent side="bottom">Properties</TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+
+      <TablePropertiesDrawer
+        open={sheetOpen} onOpenChange={setSheetOpen}
+        showGridlines={showGridlines} onShowGridlinesChange={setShowGridlines}
+        rowHeight={rowHeight} onRowHeightChange={setRowHeight}
+        pagination={false} onPaginationChange={() => {}}
+        activeFilters={activeFilters} onAddFilter={k => addFilter(k, true)}
+        onUpdateFilter={updateFilter} onRemoveFilter={removeFilter}
+        getFilterConnector={getConnector} onToggleFilterConnector={toggleConnector}
+        filterBarVisible={filterBarVisible} onFilterBarVisibleChange={setFilterBarVisible}
+        drawerExpandedFilters={drawerExpandedFilters} onDrawerExpandedFiltersChange={setDrawerExpandedFilters}
+        totalRows={totalRows} filteredRows={rows.length}
+        sortRules={sortRules} onSortRulesChange={setSortRules}
+        onAddSortRule={addSortRule} onRemoveSortRule={removeSortRule} onToggleSortDir={toggleSortDir}
+        colOrder={colOrder} onColOrderChange={setColOrder}
+        hiddenCols={hiddenCols} onToggleColVisibility={toggleColVisibility} onMoveCol={moveCol}
+        groupBy={groupBy} onGroupByChange={setGroupBy} primarySortKey={sortKey}
+        conditionalRules={conditionalRules}
+        onAddConditionalRule={onAddConditionalRule}
+        onRemoveConditionalRule={onRemoveConditionalRule}
+        onUpdateConditionalRule={onUpdateConditionalRule}
+        filterFields={filterFields}
+        lifecycleTabLabel="Foo"      // ← change to entity name
+        fieldDefinitions={fieldDefinitionsForDrawer}
+        resolveColumnLabel={resolveColumnLabel}
+        displayOptions={displayOptions}
+        onDisplayOptionsChange={onDisplayOptionsChange}
+      />
+    </>
+  )
+}
+```
+
+---
+
+## Full Table Component Skeleton
+
+```tsx
+"use client"
+
+import * as React from "react"
+// ... all imports above
+
+export interface FooTableHandle {
+  openPropertiesDrawer: () => void
+}
+
+export const FooTable = React.forwardRef<FooTableHandle, { items: Foo[] }>(
+  function FooTable({ items }, ref) {
+    const columns = React.useMemo(() => buildFooColumns(), [])
+    const filterFields = React.useMemo(() => columnsToFilterFields(columns), [columns])
+    const fieldDefinitionsForDrawer = React.useMemo(
+      () => columns.filter(c => c.key !== "select" && c.key !== "actions")
+                   .map(c => ({ key: c.key, label: c.label, sortable: !!(c.sortable && (c.sortKey ?? c.key)) })),
+      [columns],
+    )
+    const resolveColumnLabel = React.useCallback((key: string) => columns.find(c => c.key === key)?.label ?? key, [columns])
+
+    const [displayOptions, setDisplayOptions] = React.useState<DataListDisplayOptions>(DEFAULT_DATA_LIST_DISPLAY_OPTIONS)
+    const patchDisplay = React.useCallback((patch: Partial<DataListDisplayOptions>) => setDisplayOptions(prev => ({ ...prev, ...patch })), [])
+
+    const [conditionalRules, setConditionalRules] = React.useState<ConditionalRule[]>([])
+    const addConditionalRule = React.useCallback((rule: Omit<ConditionalRule, "id">) => setConditionalRules(prev => [...prev, { ...rule, id: `cr-${Date.now()}` }]), [])
+    const removeConditionalRule = React.useCallback((id: string) => setConditionalRules(prev => prev.filter(r => r.id !== id)), [])
+    const updateConditionalRule = React.useCallback((id: string, patch: Partial<ConditionalRule>) => setConditionalRules(prev => prev.map(r => r.id === id ? { ...r, ...patch } : r)), [])
+
+    const tableState = useTableState(items, columns, { key: "name", dir: "asc" })
+
+    React.useImperativeHandle(ref, () => ({
+      openPropertiesDrawer: () => tableState.setSheetOpen(true),
+    }), [tableState.setSheetOpen])
+
+    return (
+      <div className="pb-6">
+        <DataTable<Foo>
+          data={items}
+          columns={columns}
+          getRowId={row => row.id}
+          getRowSelectionLabel={row => row.name}
+          selectable
+          searchable={displayOptions.showToolbarSearch}
+          showColumnHeaders={displayOptions.showColumnLabels}
+          groupable
+          defaultSort={{ key: "name", dir: "asc" as const }}
+          emptyState={<p className="text-sm text-muted-foreground">No items found.</p>}
+          conditionalRules={conditionalRules}
+          state={tableState}
+          toolbarSlot={s => (
+            <FooDrawerToolbar
+              state={s} totalRows={items.length} filterFields={filterFields}
+              fieldDefinitionsForDrawer={fieldDefinitionsForDrawer} resolveColumnLabel={resolveColumnLabel}
+              displayOptions={displayOptions} onDisplayOptionsChange={patchDisplay}
+              conditionalRules={conditionalRules} onAddConditionalRule={addConditionalRule}
+              onRemoveConditionalRule={removeConditionalRule} onUpdateConditionalRule={updateConditionalRule}
+            />
+          )}
+          bulkActionsSlot={selected => {
+            if (selected.size === 0) return null
+            return (
+              <>
+                <span className="sr-only">{selected.size} selected</span>
+                <Tip label="Export selection (demo)">
+                  <Button size="sm" variant="outline" type="button">
+                    <i className="fa-light fa-arrow-down-to-line" aria-hidden="true" />
+                    Export
+                  </Button>
+                </Tip>
+              </>
+            )
+          }}
+        />
+      </div>
+    )
+  }
+)
+
+FooTable.displayName = "FooTable"
+```
+
+---
+
+## ListPageTemplate Client Skeleton
+
+```tsx
+"use client"
+
+import * as React from "react"
+import { ListPageTemplate, type ViewTab } from "@/components/templates/list-page"
+import { FooPageHeader } from "@/components/foo-page-header"
+import { FooTable, type FooTableHandle } from "@/components/foo-table"
+import { KeyMetrics } from "@/components/key-metrics"
+import { FOO_ITEMS } from "@/lib/mock/foo"
+import { fooKpiInsight, fooKpiMetrics } from "@/lib/mock/foo-kpi"
+import { dataListViewIcon } from "@/lib/data-list-view"
+import { Button } from "@/components/ui/button"
+
+const DEFAULT_TABS: ViewTab[] = [
+  { id: "all", label: "All Foos", viewType: "table", icon: "fa-table", filterId: "all" },
+]
+
+export function FooClient() {
+  const [exportOpen, setExportOpen] = React.useState(false)
+  const [showMetrics, setShowMetrics] = React.useState(true)
+  const tableRef = React.useRef<FooTableHandle>(null)
+
+  const metrics = React.useMemo(() => fooKpiMetrics(FOO_ITEMS), [])
+  const insight = React.useMemo(() => fooKpiInsight(FOO_ITEMS), [])
+
+  return (
+    <ListPageTemplate
+      defaultTabs={DEFAULT_TABS}
+      getTabCount={() => FOO_ITEMS.length}
+      onEditView={(tab, { updateTab }) => {
+        const mustSwitch = tab.viewType !== "table" && tab.viewType !== "list" && tab.viewType !== "board"
+        if (mustSwitch) updateTab({ viewType: "table", icon: dataListViewIcon("table") })
+        window.setTimeout(() => tableRef.current?.openPropertiesDrawer(), mustSwitch ? 160 : 0)
+      }}
+      header={
+        <FooPageHeader
+          itemCount={FOO_ITEMS.length}
+          onAdd={() => {}}
+          onExport={() => setExportOpen(true)}
+          showMetrics={showMetrics}
+          onToggleMetrics={() => setShowMetrics(v => !v)}
+        />
+      }
+      metrics={<KeyMetrics variant="flat" metrics={metrics} insight={insight} showHeader={false} metricsSingleRow />}
+      showMetrics={showMetrics}
+      exportOpen={exportOpen}
+      onExportOpenChange={setExportOpen}
+      exportTotalRows={FOO_ITEMS.length}
+      renderContent={(tab, updateTab) => {
+        if (tab.viewType === "table") return <FooTable key={tab.id} ref={tableRef} items={FOO_ITEMS} />
+        return (
+          <div className="px-4 py-12 text-center lg:px-6">
+            <p className="text-sm font-medium text-foreground">{tab.viewType === "list" ? "List" : "Board"} view is not wired in this demo.</p>
+            <Button type="button" className="mt-4" size="sm" onClick={() => updateTab({ viewType: "table", icon: dataListViewIcon("table") })}>
+              Switch to table
+            </Button>
+          </div>
+        )
+      }}
+    />
+  )
+}
+```

package/consumer-extras/cursor-skills/exxat-mono-ids/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: exxat-mono-ids
+description: Monospace typography for Exxat DS record IDs, question IDs, and system identifiers — font-mono tabular-nums, mixed subtitle lines, table meta. Use when adding or changing questionId, record id columns, header subtitles with IDs, or any copy-pasteable system key in apps/web UI.
+user-invocable: true
+---
+
+# Exxat DS — monospace IDs
+
+**Cursor rule:** `.cursor/rules/exxat-mono-ids.mdc`  
+**Handbook:** `apps/web/AGENTS.md` (§1, §13 checklist)
+
+## Standard classes
+
+```tsx
+// Default secondary ID (table meta, list subline, inspector)
+<span className="font-mono tabular-nums text-xs text-muted-foreground">{id}</span>
+
+// ID in a page subtitle next to sans prose
+<>
+  <span className="font-mono tabular-nums">{questionId}</span>
+  {" · V1 · Last updated just now"}
+</>
+```
+
+Always include **`tabular-nums`** with **`font-mono`** so fixed-width digits align in tables and subtitles.
+
+## MUST
+
+1. **Every visible system ID** in product UI uses **`font-mono tabular-nums`** (plus contextual size/color).
+2. **Mixed lines** — mono only on the identifier substring, not the whole sentence.
+3. **Tables / lists / boards** — ID column or subline under a title: mono + usually **`text-xs text-muted-foreground`**.
+
+## MUST NOT
+
+- Mono on **display names**, **emails** (unless the column is explicitly “Principal ID”), **dates**, **KPI values**, or **status text**.
+- Mono on **UI chrome** that is not an identifier (badges, buttons, nav labels).
+
+## Reference implementations
+
+| Surface | File |
+|---------|------|
+| Question bank table | `components/question-bank-table.tsx` — `row.questionId` |
+| Question bank list | `components/question-bank-list-view.tsx` |
+| New question subtitle | `components/new-question-composer.tsx` — `questionId` in `PageHeader` subtitle |
+| Sites record id | `components/sites-table.tsx` — `row.id` |
+| OS folder tiles | `components/question-bank-os-folder-view.tsx` |
+
+## Review checklist
+
+- [ ] New or changed **ID** fields use **`font-mono tabular-nums`**.
+- [ ] Subtitle / description lines mono-wrap **only** the ID token.
+- [ ] No mono applied to names, statuses, or numeric metrics that are not identifiers.
+
+## See also
+
+- `.cursor/rules/exxat-person-identity-display.mdc` — name + email (sans, not mono for email unless ID column)

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

@@ -15,14 +15,30 @@ 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
 
 - 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).
+
+## High-zoom auto-collapse
+
+`SecondaryPanelProvider` reads **`useSidebarReflowZoom()`** (zoom ≥ 200% or very short viewport — same WCAG 1.4.10 signal the primary sidebar uses). On entering high zoom it sets `secondaryPanelCompact = true` so the 16 rem rail drops to the 3 rem icon variant and frees up content space. The user can still re-expand manually (via the icon rail's "Show labels" affordance or any `openPanel` trigger); the next zoom-out → zoom-in cycle re-collapses it. `openPanel` itself opens directly in compact mode when high zoom is already active so newly-navigated panels don't flash expanded.
+
+Custom panel content (anything you register under `PANELS[id]`) should **read `secondaryPanelCompact` from the provider context** and render an icon-only layout in that branch — `QuestionBankPanel` / `QuestionBankSecondaryNav` are the reference.
+
+## Pair with
+
+- **Collapsible parent ↔ children sidebar pattern** (§3.2 of `exxat-ds-skill`) — when the same primary row also lists sub-routes inline.
 
 ## Reference
 
 - `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/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.17",
   "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": {
@@ -68,7 +68,7 @@
     "react-hook-form": "^7.72.0",
     "react-payment-inputs": "^1.2.0",
     "recharts": "^2.15.4",
-    "shadcn": "^4.1.0",
+    "shadcn": "^4.7.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.5.0",
     "tw-animate-css": "^1.4.0",
@@ -80,7 +80,7 @@
     "@tailwindcss/postcss": "^4.2.1",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "postcss": "^8",
+    "postcss": "^8.5.14",
     "tailwindcss": "^4.2.1",
     "typescript": "^5.9.3"
   },

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

@@ -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

@@ -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 */