@exxatdesignux/ui 0.5.11 → 0.5.13

package/template/docs/perf-memory-pattern.md

@@ -1,206 +0,0 @@
-# Dev memory tuning for Next.js + Node 24
-
-> **Audience:** humans + AI agents.
-> **Companion to:** [`HANDBOOK.md`](./HANDBOOK.md). Read this when `next dev`
-> RSS climbs past ~3 GB, when two `next-server` processes total > 5 GB, or
-> when adopting Node 24.
-
-A fresh `next dev` against this app stabilizes around **~1.4 GB RSS** with
-the settings below. Without them, the same app drifts to **3–6 GB per
-process** and pm2 will eventually swap or OOM.
-
-## 1. The six knobs
-
-| # | Knob | Why it matters | Where it lives |
-|---|------|----------------|----------------|
-| 1 | `NODE_OPTIONS="--max-old-space-size=6144 --max-semi-space-size=64"` | Caps V8 old-space at 6 GB (default on macOS is ~94% of system RAM = unbounded for practical purposes). With a ceiling, V8 GC pressure kicks in earlier and steady-state heap is lower. `--max-semi-space-size=64` widens the young generation so short-lived render allocations don't promote to old-space. | `package.json` `dev*` scripts + `ecosystem.config.cjs` `env` |
-| 2 | `turbopack.memoryLimit: 4 GiB` | Hard cap on the Turbopack worker process. Without this, Turbopack's module graph + mmap'd FS cache files grow unbounded — we observed 3.2 GB on disk and 5+ GB RSS per process with no cap. 4 GiB is generous for apps with < ~1000 routes. | `next.config.mjs` `turbopack` |
-| 3 | `experimental.preloadEntriesOnStart: false` | Next compiles routes on first visit instead of pre-warming every entry on dev start. Dev TTFB drops from ~15s → ~2s; steady-state heap is ~30% lower. | `next.config.mjs` |
-| 4 | `experimental.optimizePackageImports: [...]` | Re-export barrels (`lucide-react`, `@tabler/icons-react`, `motion`, `@dnd-kit/*`, `recharts`) get tree-shaken to leaf imports. Cuts the dev server's parsed-module count by ~40%. | `next.config.mjs` |
-| 5 | `experimental.webpackMemoryOptimizations: true` | Drops large in-memory webpack caches at the cost of slightly slower rebuilds. **Only the `pnpm dev:webpack` fallback uses webpack** — Turbopack ignores this flag. Keep it on for the rare cases where the webpack path is needed. | `next.config.mjs` |
-| 6 | `target: ES2022` (tsconfig) | The TS compiler emits less polyfill scaffolding for `async/await`, optional chaining, nullish coalescing, etc. tsserver in-memory AST shrinks proportionally. Safe with React 19 + Next 16 + Node 24. | `tsconfig.json` |
-
-## 2. NODE_OPTIONS propagation
-
-`NODE_OPTIONS` is read by **every Node process** the moment it boots. The npm
-parent doesn't read it (npm is a shell wrapper), but its child `next-server`
-processes inherit and honour it.
-
-- **Local dev:** set inline in `package.json` `scripts`. Cross-shell safe
-  because Next dev is only run from POSIX shells.
-- **PM2 daemon:** set in `ecosystem.config.cjs` `env` (which becomes the child
-  environment).
-- **CI:** set in the workflow `env:` block on the same step that runs `next`.
-- **VS Code / Cursor terminals:** these inherit the parent shell env, so the
-  `package.json` script is enough.
-
-## 3. Turbopack file-system cache (Next ≥ 16.1)
-
-Since Next 16.1, **`experimental.turbopackFileSystemCacheForDev` defaults to `true`** — Turbopack writes compilation artifacts to `.next/dev/cache/turbopack/<hash>/*.meta` and mmaps them across dev sessions. This is what makes the second `next dev` start in ~1 s instead of ~15 s.
-
-**The trade-off** is that the cache grows linearly with the number of unique routes / modules you've touched. After a few weeks of feature work it's normal to see:
-
-```bash
-du -sh .next
-# 3.2G  .next
-```
-
-Each `.meta` file is mmap'd by the running `next-server`, so the cache size is roughly the floor of the dev process's RSS until the OS evicts pages.
-
-**Do not disable** the FS cache (`turbopackFileSystemCacheForDev: false`) — cold-start dev becomes painful (~15–30 s every restart on this app). Instead, **bust the cache** when it grows past 1–2 GB:
-
-```bash
-pnpm clean:cache  # removes .next/dev/cache and .next/dev/trace
-pnpm dev:fresh    # bust + restart in one command
-```
-
-The `dev:fresh` script is the right move whenever:
-
-- A pnpm install changed `@exxatdesignux/ui` or any framework dep.
-- `.next` is > 2 GB and dev memory is climbing.
-- HMR starts skipping updates or compilation gets stuck on a stale module.
-
-For a full nuke (build artifacts too):
-
-```bash
-pnpm clean
-```
-
-`turbopack.memoryLimit` (knob #2) prevents the cache from blowing past 4 GiB of RAM even when the on-disk cache is large.
-
-## 4. Don't run two dev servers at the same time
-
-**This is the #1 cause of memory exhaustion in practice.** A single `next-server` (parent + render worker) stabilizes at ~2 GB total RSS with the knobs above. Two parallel servers stabilize at ~4 GB, three at ~6 GB, and so on — they don't share any caches.
-
-If you see two `next-server` lineages in `ps`, check:
-
-```bash
-ps aux | grep next-server | grep -v grep
-lsof -p <pid> | grep '\.next/dev/cache' | head -5  # which checkout owns it
-```
-
-Common dual-server scenarios:
-
-| Scenario | Symptom | Fix |
-|----------|---------|-----|
-| Two checkouts of the same monorepo (e.g. `DS_Workspace/` and `Exxat-DS-Workspace/`) both running `pnpm dev:web` | Two `next-server` parents, both in `apps/web/.next/...` paths but on different absolute roots | Quit one. Pin to a single checkout per machine. |
-| A customer app (e.g. `test-9`) + the monorepo `apps/web` running at the same time | Different cache hashes (`ee6e79b1/`) under different roots | Stop whichever you're not actively touching: `pm2 stop exxat-ds` or `Ctrl+C` |
-| A stale pm2 daemon from a prior `nvm use 22` session left running after upgrading to Node 24 | One Node-22 + one Node-24 dev server | `pm2 delete exxat-ds` then `pnpm dev:daemon` to re-launch under Node 24 |
-| `next build` running in another tab while `next dev` is up | Three or four `next-server` for the duration of the build | Wait for the build, or kill the dev server until the build is done |
-
-## 5. Two `next-server` processes per app is normal
-
-Next 16 splits dev into:
-
-- **`next-server` (main)** — HTTP entry, watcher, router.
-- **`next-server` (render worker)** — RSC + SSR pipeline.
-
-Both inherit `NODE_OPTIONS`, so the 6 GB cap applies to **each**. With the
-config in this app the totals stabilize around **~1.4 GB + ~0.6 GB ≈ 2 GB**.
-If you ever see a third or fourth `next-server`, that's the build worker
-spawning during a route compile — they exit when the build completes.
-
-## 6. Diagnose a memory regression
-
-When dev RSS climbs past 4 GB and stays there:
-
-```bash
-# First, check the boring stuff
-du -sh .next                                         # > 2 GB → run pnpm clean:cache
-ps aux | grep next-server | grep -v grep | wc -l     # > 2 lines → you have two dev servers
-lsof -p <pid> | wc -l                                # > 5000 FDs → cache is mmap-flooding
-
-# Then profile a 60s window — heap snapshots to .next/diagnostics/
-pnpm dev:profile
-
-# Open the latest .heapprofile in Chrome DevTools → Memory → "Load"
-ls -lt .next/diagnostics | head -3
-```
-
-Common culprits and their signatures:
-
-| Symptom | Likely cause | Fix |
-|---------|--------------|-----|
-| `.next` is > 2 GB on disk; many `.meta` files | Turbopack FS cache bloat over weeks | `pnpm clean:cache` then `pnpm dev` (see §3) |
-| Two or more `next-server` parents in `ps` | Dual dev server across checkouts / apps | Stop the one you aren't using (see §4) |
-| Many copies of `lucide-react.js` / `recharts.js` retained in heap | Missing entry in `optimizePackageImports` | Add the package to the list (knob 4) |
-| Compiled chunks for routes you never visited | `preloadEntriesOnStart` is `true` | Set to `false` (knob 3) |
-| Heap grows on every HMR cycle, never shrinks | RSC HMR cache + import.meta.hot leak | `experimental.serverComponentsHmrCache: false` (try only if knob 3 is already on) |
-| Single retainer chain holds 100 MB+ | A module-level `Map` / `Set` in app code never gets cleared | Move to request-scoped storage |
-| tsserver alone is > 1.5 GB | TS strict + large lib check | `skipLibCheck: true` (already on), drop `allowJs` if not needed |
-| Turbopack worker RSS keeps growing past 4 GiB | `turbopack.memoryLimit` not set | Apply knob 2 |
-
-## 7. Node 24 features we leverage
-
-Node 24 (LTS-track) is required by `engines.node` in `package.json` and
-pinned in `.nvmrc`. Specifically:
-
-- **V8 13.6 with Maglev JIT default-on** — faster startup, lower base heap.
-  Steady-state RSS for the `next dev` parent is ~12% lower vs Node 22.
-- **Improved incremental marking GC** — fewer long pauses during HMR; the
-  perceived "stutter" when saving a large file is gone.
-- **Permission model (`--permission`)** — not enabled in dev (Next reads
-  too many paths to make `--permission` ergonomic), but available for
-  hardening production scripts.
-- **`node --run <script>`** — replaces `npm run` for one-off scripts with
-  ~30 ms less per-invocation overhead. Use it in any CI step that runs a
-  workspace script directly: `node --run typecheck`. Not yet wired into
-  this repo's pm2 / package scripts because pm2 itself spawns `npm`.
-- **`--heap-prof` / `--cpu-prof` always-on** — the `dev:profile` script in
-  `package.json` uses these to drop snapshots into `.next/diagnostics/`
-  without any third-party profiler dependency.
-- **`--experimental-strip-types`** — Node 24 can run `.ts` files directly,
-  but Next still uses tsc + swc, so this only helps for stand-alone
-  scripts under `apps/web/scripts/` (e.g. `fa:subset-audit`) if they're
-  converted from `.mjs` to `.ts`.
-- **Smaller initial heap allocations** — V8 13.6 starts with ~50 MB less
-  reserved arena vs V8 12.x. Most visible in fast CI test runs.
-
-## 8. Anti-patterns
-
-| Anti-pattern | Why it's wrong |
-|--------------|----------------|
-| Setting `NODE_OPTIONS` only in `.env.local` | `.env.local` is read by Next, not by Node. The dev server's own runtime never sees it. |
-| Setting `--max-old-space-size` to the system RAM amount | Defeats the cap. The point is to force GC pressure, not raise the ceiling. |
-| Running multiple `next dev` instances on the same machine without unique ports | Each instance ignores the others' caches and the total RSS is N × steady-state. Use the dedicated `dev:3001` / `dev:3005` scripts. |
-| `NODE_OPTIONS=--inspect` in normal dev | Allocates an extra inspector arena per process (~200 MB). Use only when actively debugging. |
-| Adding `nodemon` on top of `next dev` | Next has its own watcher; nodemon doubles the file-system event handlers. |
-| Importing `@exxatdesignux/ui` from the package root for every icon | Defeats `optimizePackageImports`. Always import from the leaf path the DS exposes. |
-| Running pm2 without `max_memory_restart` | A wedged worker stays wedged. The 7 GB ceiling lets pm2 recycle before the OS swaps. |
-| Disabling `turbopackFileSystemCacheForDev` because "cache is the problem" | Cold starts go from ~1s to ~15–30s every restart. Bust with `pnpm clean:cache` instead. |
-| Two checkouts of the same monorepo both running dev | Caches don't share — 2× total RSS. Pin to one checkout per machine. |
-
-## 9. Upgrading an existing customer app
-
-If your app was scaffolded before `@exxatdesignux/ui@0.5.10`, copy the diffs
-below from `node_modules/@exxatdesignux/ui/template/`:
-
-1. `.nvmrc` — set to `24`.
-2. `package.json` — `engines.node: ">=24.0.0"` + the `NODE_OPTIONS` /
-   `NEXT_TELEMETRY_DISABLED` prefix on every `dev*` script + the new
-   `dev:profile`, `dev:fresh`, `clean`, `clean:cache` scripts.
-3. `next.config.mjs` — add the `turbopack: { memoryLimit }` block, the
-   expanded `experimental.optimizePackageImports` array,
-   `experimental.preloadEntriesOnStart: false`,
-   `experimental.webpackMemoryOptimizations: true`, and the
-   `onDemandEntries` block.
-4. `tsconfig.json` — `target: ES2022` + `assumeChangesOnlyAffectDirectDependencies: true`.
-5. `ecosystem.config.cjs` (if used) — add the `env` block with
-   `NODE_OPTIONS` + `NEXT_TELEMETRY_DISABLED` and `max_memory_restart: "7G"`.
-6. Run `nvm install 24 && nvm use` (or your Node manager equivalent).
-7. **First run after upgrading:** `pnpm clean && pnpm dev` to drop the
-   pre-0.5.10 Turbopack cache (it was written without the memory cap and
-   may carry stale mmap layouts).
-
-Restart the dev server. You should see steady-state RSS settle in the
-1.5–2 GB range within ~30 s of the first navigation. If you still see
-> 3 GB per process: re-read §4 — you almost certainly have a second
-dev server running somewhere.
-
-## See also
-
-- [`HANDBOOK.md`](./HANDBOOK.md) — workspace orientation
-- [`consumer-upgrade-checklist.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/packages/ui/consumer-extras/patterns/consumer-upgrade-checklist.md) — what to do after `pnpm add @exxatdesignux/ui@latest`
-- [Next.js — Reducing dev memory usage](https://nextjs.org/docs/app/building-your-application/optimizing/memory-usage)
-- [Node.js — Diagnostics](https://nodejs.org/api/cli.html#--heap-profheap_dir)
-- [V8 — Maglev](https://v8.dev/blog/maglev)

package/template/docs/reference-implementations.md

@@ -1,153 +0,0 @@
-# Exxat DS — Reference implementations
-
-> When a rule says "see the canonical hub" or "see the catalog page", **this is the index**. Open the file. Copy. Don't reinvent.
-
-Reference pages are the **canonical working implementations** of a pattern. They're the source of truth that rules + blueprints summarize. If a rule conflicts with a reference page, the bug is in the rule — open a PR.
-
----
-
-## How to use this page
-
-1. Find the row that matches the pattern you're building.
-2. Open the **Reference page** column — that file is the template.
-3. Read the linked **Blueprint** for the framework-agnostic spec.
-4. Read the linked **Rule** for the binding MUST / MUST NOT.
-5. Read the linked **Pattern** for the long-form "why".
-
-If you find yourself diverging from the reference page, ask **why** before shipping.
-
----
-
-## Primary hubs
-
-| Pattern | Reference page | Blueprint | Rule(s) | Pattern doc |
-|---|---|---|---|---|
-| Full hub: table + board + dashboard + list + paginated + conditional rules + dashboard customize | `apps/web/components/library-table.tsx` + `library-hub-client.tsx` | [`list-page-template`](./blueprints/list-page-template.md), [`data-table`](./blueprints/data-table.md), [`board-card`](./blueprints/board-card.md), [`key-metrics`](./blueprints/key-metrics.md) | [`exxat-data-tables`](../../../.cursor/rules/exxat-data-tables.mdc), [`exxat-list-page-connected-views`](../../../.cursor/rules/exxat-list-page-connected-views.mdc), [`exxat-centralized-list-dataset`](../../../.cursor/rules/exxat-centralized-list-dataset.mdc) | [`data-views-pattern`](./data-views-pattern.md) |
-| Hub with secondary panel scope (folder rail) | `apps/web/components/library-hub-client.tsx` + `library-secondary-nav.tsx` | [`list-page-template`](./blueprints/list-page-template.md) | [`exxat-primary-nav-secondary-panel`](../../../.cursor/rules/exxat-primary-nav-secondary-panel.mdc), [`exxat-library-hub-header`](../../../.cursor/rules/exxat-library-hub-header.mdc) | [`library-hub-header-pattern`](./library-hub-header-pattern.md) |
-| Hub with secondary panel scope (URL-driven category rail) — **smallest** secondary-panel reference + built-in pagination chrome | `apps/web/components/tokens-themes-client.tsx` + `tokens-secondary-nav.tsx` | [`list-page-template`](./blueprints/list-page-template.md) | [`exxat-primary-nav-secondary-panel`](../../../.cursor/rules/exxat-primary-nav-secondary-panel.mdc) | [`shell-surface-elevation-pattern`](./shell-surface-elevation-pattern.md) |
-| Cell-pattern catalog — **18 SaaS cell patterns** via custom `columnDefs`; **seven views** via **`LibraryTable`** (same Add view as Library). | `apps/web/components/columns-showcase.tsx` + `columns-client.tsx` | [`list-page-template`](./blueprints/list-page-template.md), [`data-table`](./blueprints/data-table.md), [`hub-supported-views-pattern`](./hub-supported-views-pattern.md) | [`exxat-data-tables`](../../../.cursor/rules/exxat-data-tables.mdc), [`exxat-hub-supported-views`](../../../.cursor/rules/exxat-hub-supported-views.mdc) | — |
-
-> **First-time hub builder:** copy **`library-table.tsx`** + **`library-client.tsx`** for seven-view wiring; use **`columns-showcase.tsx`** for custom columns on **`LibraryItem`**; use **`tokens-themes-client.tsx`** + **`tokens-hub-auxiliary-views.tsx`** for token rows. Read **`hub-supported-views-pattern.md`** before changing Add view.
-
----
-
-## Cell primitives (importable)
-
-Every cell renderer below is exported from `@/components/data-views` (re-exported from `apps/web/components/data-views/table-cells.tsx`). The live catalog page is `/columns`. **Do not re-implement these inside a `ColumnDef['cell']`** — import the name.
-
-| Cell | Renders | Import |
-|------|---------|--------|
-| `ProgressCell` | Track + filled bar with auto-tone in thirds; `value`, `max`, `tone`, `label` | `@/components/data-views` |
-| `CurrencyCell` | Right-aligned `tabular-nums`; `value`, `currency` (USD), `locale`, `maximumFractionDigits` | same |
-| `NumericCell` | Right-aligned plain count; `value`, `fractionDigits` | same |
-| `RatingCell` | N of `max` FA stars + value; color + glyph paired (WCAG 1.4.1) | same |
-| `SignalBarsCell` | Wi-Fi-style ordinal bars; `level`, `max`, `tone`, `label` (required) | same |
-| `BooleanToggleCell` | Inline `ToggleSwitch` with `checked` + `onChange(next)`; stops row click propagation | same |
-| `AttachmentCountCell` | Paperclip + count chip; muted dash on `0` | same |
-| `ExternalLinkCell` | Truncated host + new-tab icon; `url`, `label?`; `Tip` shows full URL | same |
-| `RelativeTimeCell` | "3 hours ago" with `Tip(absolute)`; `iso`, `now?` (deterministic snapshots) | same |
-| `PeopleAvatarRailCell` | Face rail with `+N` overflow; `people: PersonStub[]`, **non-overlapping** | same |
-| `PillCell` | Outlined badge + leading FA icon; `label`, `icon?` | same |
-| `TagListCell` | Soft badges with `+N` overflow; `tags`, `visibleMax?`, `formatLabel?` | same |
-| `RowActionsCell<TRow>` | `⋯` overflow dropdown; `row`, `actions: RowActionDef<TRow>[]` (label, icon, onSelect, variant, shortcut, disabled) | same |
-| `EMPTY_DASH` | Aria-hidden `—` placeholder for null/undefined cells | same |
-
-**Anti-references** (do NOT copy):
-- ❌ Inlining `Intl.NumberFormat`, `[1,2,3,4,5].map(s => …)` star loops, raw `<a target="_blank">`, `new URL(…).hostname`, or `Intl.RelativeTimeFormat` inside a `cell:`. Import the named cell.
-- ❌ Re-implementing `RowActionsCell` per hub with a custom `DropdownMenu`. The generic `RowActionsCell<TRow>` covers `Open / Edit / Duplicate / Archive`-style menus.
-
----
-
-## Hub chrome
-
-| Pattern | Reference page | Blueprint | Rule(s) |
-|---|---|---|---|
-| Page header — primary hub | `apps/web/components/library-page-header.tsx` | [`page-header`](./blueprints/page-header.md) | [`exxat-collaboration-access`](../../../.cursor/rules/exxat-collaboration-access.mdc), [`exxat-mono-ids`](../../../.cursor/rules/exxat-mono-ids.mdc) |
-| Page header — entity / record (no view tabs) | `apps/web/components/page-header.tsx` (variants) | [`page-header`](./blueprints/page-header.md) | — |
-| KPI flat band on a hub (clickable tiles + insight card) | `apps/web/components/columns-client.tsx`, `apps/web/components/tokens-themes-client.tsx` | [`key-metrics`](./blueprints/key-metrics.md) | [`exxat-kpi-flat-band`](../../../.cursor/rules/exxat-kpi-flat-band.mdc), [`exxat-kpi-max-four`](../../../.cursor/rules/exxat-kpi-max-four.mdc), [`exxat-kpi-trends`](../../../.cursor/rules/exxat-kpi-trends.mdc) |
-| Properties drawer wiring (auto via `HubTable`) | `apps/web/components/library-table.tsx`, `apps/web/components/columns-showcase.tsx` | — | [`exxat-table-properties-drawer`](../../../.cursor/rules/exxat-table-properties-drawer.mdc) |
-| Pagination chrome (auto via `HubTable` when `pagination` is toggled) | `apps/web/components/columns-showcase.tsx`, `apps/web/components/tokens-themes-client.tsx` | [`data-table`](./blueprints/data-table.md) | [`exxat-data-tables`](../../../.cursor/rules/exxat-data-tables.mdc) |
-| Export drawer + ⋯ menu | `apps/web/components/library-page-header.tsx` + `export-drawer.tsx` | — | [`exxat-drawer-vs-dialog`](../../../.cursor/rules/exxat-drawer-vs-dialog.mdc) |
-
----
-
-## Board, list, dashboard views
-
-| Pattern | Reference page | Blueprint | Rule(s) |
-|---|---|---|---|
-| Board card (kanban) | `apps/web/components/library-board-view.tsx` | [`board-card`](./blueprints/board-card.md) | [`exxat-board-cards`](../../../.cursor/rules/exxat-board-cards.mdc), [`exxat-card-vs-list-rows`](../../../.cursor/rules/exxat-card-vs-list-rows.mdc) |
-| List row (single-column) | `apps/web/components/library-table.tsx` (`renderListRow`) | [`board-card`](./blueprints/board-card.md) (row layout) | [`exxat-card-vs-list-rows`](../../../.cursor/rules/exxat-card-vs-list-rows.mdc) |
-| Dashboard view with charts + KPI band | `apps/web/components/library-dashboard-charts.tsx` | [`key-metrics`](./blueprints/key-metrics.md) | [`exxat-dashboard-view-charts`](../.cursor/rules/exxat-dashboard-view-charts.mdc) |
-
----
-
-## Search
-
-| Pattern | Reference page | Rule(s) | Pattern doc |
-|---|---|---|---|
-| Global command palette (⌘K) | `apps/web/components/command-menu.tsx` + `lib/command-menu-config.ts` | [`exxat-command-menu`](../../../.cursor/rules/exxat-command-menu.mdc) | [`command-menu-pattern`](./command-menu-pattern.md) |
-| Dedicated search (landing + results) | `apps/web/components/dedicated-search-*.tsx` | [`exxat-dedicated-search-surfaces`](../../../.cursor/rules/exxat-dedicated-search-surfaces.mdc) | — |
-| In-table search (toolbar) | wired by `HubTable` automatically | [`exxat-data-tables`](../../../.cursor/rules/exxat-data-tables.mdc) | [`data-views-pattern`](./data-views-pattern.md) |
-
----
-
-## Collaboration
-
-| Pattern | Reference page | Rule(s) | Pattern doc |
-|---|---|---|---|
-| Face rail + invite drawer | `apps/web/components/collaboration-access-flow.tsx`, `invite-collaborators-drawer.tsx` | [`exxat-collaboration-access`](../../../.cursor/rules/exxat-collaboration-access.mdc) | [`collaboration-access-pattern`](./collaboration-access-pattern.md) |
-
----
-
-## Overlays and confirmations
-
-| Pattern | Reference page | Rule(s) | Pattern doc |
-|---|---|---|---|
-| Side drawer (long auxiliary flow) | `apps/web/components/export-drawer.tsx`, `invite-collaborators-drawer.tsx`, `apps/web/components/table-properties/drawer.tsx` | [`exxat-drawer-vs-dialog`](../../../.cursor/rules/exxat-drawer-vs-dialog.mdc), [`exxat-page-vs-drawer`](../../../.cursor/rules/exxat-page-vs-drawer.mdc) | [`drawer-vs-dialog-pattern`](./drawer-vs-dialog-pattern.md) |
-| Dialog (blocking short confirm / destructive) | `apps/web/components/ui/alert-dialog.tsx` consumers (search `<AlertDialog`) | [`exxat-drawer-vs-dialog`](../../../.cursor/rules/exxat-drawer-vs-dialog.mdc) | [`drawer-vs-dialog-pattern`](./drawer-vs-dialog-pattern.md) |
-| Coach mark / onboarding | `apps/web/lib/coach-mark-registry.ts` consumers (Library dashboard customize) | — | — |
-
----
-
-## Settings, tokens, themes
-
-| Pattern | Reference page | Rule(s) |
-|---|---|---|
-| Settings page (preferences + sections) | `apps/web/app/(app)/settings/page.tsx` | — |
-| Tokens & themes hub (secondary panel + categories + visualizers) | `apps/web/components/tokens-themes-client.tsx`, `tokens-themes-section.tsx`, `tokens-secondary-nav.tsx` | [`exxat-token-discipline`](../../../.cursor/rules/exxat-token-discipline.mdc), [`exxat-primary-nav-secondary-panel`](../../../.cursor/rules/exxat-primary-nav-secondary-panel.mdc) |
-
----
-
-## Anti-references (what NOT to copy)
-
-These exist but are **not** canonical. They predate a rule, are scoped to a one-off, or use a legacy primitive. **Don't copy from them.**
-
-| Anti-reference | Why not | What to use instead |
-|---|---|---|
-| Raw `<DataTable>` mounted directly in `ListPageTemplate.renderContent` (historical) | Loses filter chips, Properties drawer, and the new built-in pagination chrome | `HubTable` (see `columns-showcase.tsx`, `tokens-themes-client.tsx`, `library-table.tsx`) |
-| Hub-side `PaginationBar` + `CountSyncer` wiring around `DataTable` (the old Placements pattern) | `HubTable` now mounts pagination chrome automatically when the hub passes `pagination` + `onPaginationChange` | Pass `pagination` / `onPaginationChange` / optional `paginationInitialPageSize` / `paginationPageSizeOptions` to `HubTable` |
-| Custom search input above a `DataTable` | `HubTable`'s toolbar already does this; duplicating leads to drift | Configure `ColumnDef.filter` + use `HubTable` |
-| `toast()` / Sonner / snackbar | Forbidden — see [`exxat-no-toast.mdc`](../../../.cursor/rules/exxat-no-toast.mdc) | `LocalBanner` / `SystemBanner` or inline status |
-| Negative-margin overlapping avatars | Forbidden — see [`exxat-person-identity-display.mdc`](../../../.cursor/rules/exxat-person-identity-display.mdc) | `AvatarGroup` (gapped by default) |
-| Legacy customer sidebar screenshots (rainbow section text, pink wash, custom pills) | Visual spec for old product — **not** Exxat DS chrome | **`AppSidebar`** + **`SidebarMenuButton`** + **`lib/mock/navigation.tsx`** — [`exxat-sidebar-shell.mdc`](../../../.cursor/rules/exxat-sidebar-shell.mdc) |
-| Uploaded screenshots / mockups treated as pixel spec | Images show **intent** (labels, fields, flows) — DS blueprints + reference hubs define **implementation** | [`exxat-no-image-pixel-copy.mdc`](../../../.cursor/rules/exxat-no-image-pixel-copy.mdc) + **`component-selection-guide.md`** |
-
----
-
-## Adding a new reference page
-
-If you build a pattern that **other hubs will copy**, list it here. A reference page is canonical when:
-
-1. It satisfies the matching blueprint or rule end-to-end.
-2. It passes the §13 PR-review checklist in [`AGENTS.md`](../AGENTS.md).
-3. The file has a top-level doc comment that names what it's the reference for (e.g. *"Tokens & themes hub — table + secondary-panel category rail; thin wrapper around `<HubTable>` with the new built-in pagination chrome."*).
-4. The matching rule's "Reference implementations" list points back to it.
-
----
-
-## See also
-
-- [`HANDBOOK.md`](./HANDBOOK.md) — start-here doc map
-- [`blueprints/README.md`](./blueprints/README.md) — what a blueprint is
-- [`component-selection-guide.md`](./component-selection-guide.md) — decision tree across blueprints
-- [`apps/web/AGENTS.md` §13](../AGENTS.md) — full PR-review checklist

package/template/docs/shell-surface-elevation-pattern.md

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