@exxatdesignux/ui 0.2.18 → 0.3.0

package/template/docs/component-selection-guide.md

@@ -0,0 +1,224 @@
+# Exxat DS — Component Selection Guide
+
+**Audience:** humans + AI agents. **Companion to:** [`token-taxonomy.md`](./token-taxonomy.md), [`blueprints/`](./blueprints/).
+
+When you're about to build a UI, **start here**. Follow the decision tree
+to find the right composition before you write any markup. The rule is
+always: **compose existing components first**; only create a new shared
+primitive after asking the user
+([`exxat-reuse-before-custom.mdc`](../../.cursor/rules/exxat-reuse-before-custom.mdc)).
+
+---
+
+## 0. Quick chart
+
+```
+                ┌─────────────────────────────────────┐
+                │ What is the surface?               │
+                └──┬──────────────────────────────────┘
+                   │
+       ┌───────────┴────────────────────────────┐
+       │                                        │
+   PRIMARY HUB                               OVERLAY / SECONDARY
+   (route w/ many records,                   (on top of a hub,
+   filters, properties)                      modal task, side panel)
+       │                                        │
+       │                                        ▼
+       │                                  See § 3
+       ▼
+   See § 1
+```
+
+---
+
+## 1. Building a primary hub (route with records)
+
+```
+   Q: Is the data > ~10 comparable records?
+   ─────────────────────────────────────────
+   │ yes ──────────────────────────────► DataTable inside ListPageTemplate (§1.1)
+   │ no  ──┬─ all rows shown at once?
+   │       │ yes ── simple `<dl>` / card list (no Properties / Filters needed)
+   │       │ no  ── still use DataTable — future growth is expected
+   └─────►
+```
+
+### 1.1 DataTable hub (canonical)
+
+| Need | Use |
+|---|---|
+| Browsable grid | **`DataTable`** + **`useTableState`** ([blueprint](./blueprints/data-table.md)) |
+| View tabs (table/list/board/dashboard) | **`ListPageTemplate`** + connected views ([`exxat-list-page-connected-views.mdc`](../../.cursor/rules/exxat-list-page-connected-views.mdc)) |
+| Column/density/properties | **`TablePropertiesDrawer`** (pass `currentView` + `onViewChange`) |
+| Filters | Shared `FilterFieldDef` chips |
+| Find-in-list | Toolbar search (`⌘K`) |
+| Metrics strip | **`KeyMetrics`** `variant="flat"` ([`kpi-flat-band-pattern.md`](./kpi-flat-band-pattern.md)) — **max 4 tiles** ([`exxat-kpi-max-four.mdc`](../../.cursor/rules/exxat-kpi-max-four.mdc)) |
+| Export | Filled primary CTA + `⋯` → `ExportDrawer` |
+| Kanban view body | **`ListPageBoardCard`** + `ListPageBoardTemplate` ([`exxat-board-cards.mdc`](../../.cursor/rules/exxat-board-cards.mdc)) |
+| Folder / panel view body | **`FolderGridView`** / **`FinderPanelView`** wrapped in **`ListPageViewFrame`** ([`exxat-list-page-view-shells.mdc`](../../.cursor/rules/exxat-list-page-view-shells.mdc)) |
+| Dashboard view body | **`KeyMetrics variant="card"`** + chart sections from `data-view-dashboard-charts*.tsx` |
+| Nested scope nav (All / Mine / tree) | **`secondaryPanel`** + `PANELS` + `useAutoPanel` ([`exxat-primary-nav-secondary-panel.mdc`](../../.cursor/rules/exxat-primary-nav-secondary-panel.mdc)) |
+| Shared hub w/ invite | **`PageHeader` `variant="collaboration"`** + `InviteCollaboratorsDrawer` |
+| Dedicated search (empty `?q=` vs results) | **`DedicatedSearchLandingTemplate`** + **`DedicatedSearchResultsHeaderChrome`** |
+
+**Reference:** `PlacementsClient` (Placements) is the most complete example.
+
+### 1.2 Visual-browse hub (kanban / gallery)
+
+If the product wants a **kanban-first** experience and the table is the
+fallback rather than primary:
+
+```
+ListPageTemplate
+├── PageHeader
+├── KeyMetrics (optional, ≤4)
+└── viewType="board" → ListPageBoardTemplate + ListPageBoardCard
+```
+
+Even here, **back the board with `useTableState`** so switching to the table
+tab is consistent. Don't fork the data.
+
+---
+
+## 2. Naming a card / row / list
+
+| Pattern | What to reach for |
+|---|---|
+| Dense comparable rows | `DataTable` row (don't card-wall it — see [`card-vs-rows-pattern.md`](./card-vs-rows-pattern.md)) |
+| Kanban column card | `ListPageBoardCard` + `BoardCardTwoLineBlock` + `BoardCardIconRow` |
+| OS-folder grid | `FolderGridView` in `ListPageViewFrame` |
+| Finder split (list + preview) | `FinderPanelView` |
+| Sidebar nav row | `SidebarMenuButton` (do not roll your own) |
+| KPI tile | `KeyMetrics` `MetricItem` — never a custom `Card` w/ number |
+| Coach mark tile | `CoachMark` step — never an ad-hoc onboarding popover |
+
+---
+
+## 3. Same-route overlay vs new route
+
+Always ask: **does the user need the hub visible behind them?**
+
+```
+                ┌────────────────────────────┐
+                │ Does the user need the hub │
+                │   visible behind them?     │
+                └─────────────┬──────────────┘
+                              │
+              ┌───── YES ─────┴───── NO ─────┐
+              ▼                              ▼
+        Same route                     New route
+       (overlay)                     (own URL)
+              │                              │
+        ┌─────┴──────┐                       │
+        │ Is the task│                       │
+        │   short +  │                       │
+        │  blocking? │                       │
+        └─────┬──────┘                       │
+              │                              │
+        ┌─ YES ┴ NO ──┐                      │
+        ▼              ▼                      ▼
+     Dialog        Drawer / Sheet         Page route
+   (AlertDialog,  (TablePropertiesDrawer,  (full create/edit
+   delete confirm)  ExportDrawer,           wizard, deep detail)
+                   InviteCollaboratorsDrawer)
+```
+
+See [`drawer-vs-dialog-pattern.md`](./drawer-vs-dialog-pattern.md) and
+[`exxat-page-vs-drawer.mdc`](../../.cursor/rules/exxat-page-vs-drawer.mdc).
+
+---
+
+## 4. Search / Find / Command
+
+| Need | Use | Shortcut |
+|---|---|---|
+| Find inside a table | `DataTableToolbar` search | `⌘K` / `Ctrl K` (no Alt) |
+| Find inside a hub (across tabs/views) | Same `⌘K` while focus is on the hub | `⌘K` |
+| Global navigation + AI starter | `CommandMenu` ([`command-menu-pattern.md`](./command-menu-pattern.md)) | `⌘K` while no input has focus |
+| Long AI / chat | `AskLeoSidebar` | `⌘⌥K` |
+| Dedicated search page (results view) | `DedicatedSearchLandingTemplate` + `DedicatedSearchResultsHeaderChrome` | — |
+
+---
+
+## 5. Feedback / messaging
+
+| Need | Use |
+|---|---|
+| Persistent banner ("system maintenance") | `SystemBanner` |
+| Per-page contextual info | `LocalBanner` |
+| Per-control success/error | Inline text next to the field |
+| Confirm a destructive action | `AlertDialog` |
+| **Never** | `toast()` / Sonner / snackbars ([`exxat-no-toast.mdc`](../../.cursor/rules/exxat-no-toast.mdc)) |
+
+---
+
+## 6. Icons
+
+| Use case | Pattern |
+|---|---|
+| Icon next to a label | FA glyph + `aria-hidden` (Case A) |
+| Icon standing alone (meaning-bearing) | `<span role="img" aria-label="…" tabIndex={0}>` + `Tooltip` (Case B) |
+| Icon-only button / link | `<button aria-label="…">` wrapped in `Tooltip` (Case C) |
+| Product mark | `ExxatProductLogo` |
+| School / org mark | `logoDevUrl()` |
+
+Source: `apps/web/AGENTS.md` §8.6.
+
+---
+
+## 7. KPIs / metrics
+
+| Need | Use |
+|---|---|
+| Hub metric strip on top of `ListPageTemplate` | `KeyMetrics variant="flat"` |
+| Dashboard view tab key-metrics card | `KeyMetrics variant="card"` (1–4 tiles) |
+| Chart + mini-metric next to it | `ChartCard` + chart's own KPI helpers |
+| Trend arrow on a metric | Set `MetricItem.trend` to match delta sign; set `trendPolarity` when "up" is bad |
+
+Cap visible KPIs at **4** ([`exxat-kpi-max-four.mdc`](../../.cursor/rules/exxat-kpi-max-four.mdc)).
+
+---
+
+## 8. Identifiers and typography
+
+| Carries | Use |
+|---|---|
+| System ID (`questionId`, record key) | `font-mono tabular-nums` ([`exxat-mono-ids.mdc`](../../.cursor/rules/exxat-mono-ids.mdc)) |
+| Page title | `<h1>` with `font-heading` (Ivy Presto) inside `PageHeader` |
+| Body | Default Inter, ≥ 11px (`text-xs` minimum) |
+| Status label | `ListHubStatusBadge` from `lib/list-status-badges.ts` — never raw text |
+| Currency / counts | `tabular-nums` (no `font-mono`) |
+
+---
+
+## 9. When NOTHING here fits
+
+You are now in the territory covered by
+[`exxat-reuse-before-custom.mdc`](../../.cursor/rules/exxat-reuse-before-custom.mdc):
+
+1. Re-scan `apps/web/components/`, `packages/ui/src/components/`, and `apps/web/components/data-views/`.
+2. Check `AGENTS.md` §9 architecture table.
+3. If still no fit, **ask the user** with a short option list:
+   - extend an existing primitive (preferred),
+   - add a new component under `components/data-views/` or `components/templates/`,
+   - or open a packaged shared primitive in `packages/ui`.
+
+---
+
+## 10. Cheat sheet — one-line rules
+
+- **Data list, > 10 rows** → `DataTable` + `ListPageTemplate`.
+- **Visual browse / kanban** → `ListPageBoardCard`.
+- **Folder / panel / OS-folder view** → `data-views/` primitive in `ListPageViewFrame`.
+- **Quick auxiliary task with hub behind** → drawer.
+- **Blocking short confirm** → dialog.
+- **Primary / long / own-URL flow** → new route.
+- **Global ⌘K** → `CommandMenu` (search + quick AI).
+- **Long AI** → Ask Leo (`⌘⌥K`).
+- **Feedback** → banner / inline / dialog — **never** toast.
+- **Icon-only button** → `aria-label` + `Tooltip` (Case C).
+- **System ID** → `font-mono tabular-nums`.
+- **KPI strip** → ≤ 4 tiles, `variant="flat"` on hubs.
+- **Hex color in code** → no. Use a token.
+
+See also: [`AGENTS.md` §13 checklist](../AGENTS.md) — run it before shipping a hub.

package/template/docs/components-audit-2026-05.md

@@ -0,0 +1,158 @@
+# `apps/web/components/` audit — 2026-05
+
+**Author:** Exxat DS hardening sweep · **Scope:** observation only — no code moved.
+
+This audit was triggered by formalizing the design system (token taxonomy +
+blueprints + selection guide + ESLint guardrails) so that any future
+component refactor has a clear target structure. **No file is moved or
+deleted by this audit itself.** Treat each finding as a follow-up PR
+candidate; bundle them as you like.
+
+## 1. Sizes & shape
+
+| Bucket | Count | Notes |
+|---|---|---|
+| Top-level `components/*.tsx` | **99** | Mix of hub clients, hub tables, hub views, page headers, dashboard charts, sidebar bits, leaf primitives |
+| `components/data-table/` | 5 | Correct — base table stack |
+| `components/data-views/` | 14 | Correct — generic view primitives + board card |
+| `components/onboarding/` | 5 (4 demos + index) | Demo variants of `GettingStarted` |
+| `components/table-properties/` | (drawer + parts) | Correct |
+| `components/templates/` | 7 | Correct — page-level templates |
+| `components/ui/` | 40+ | Reserved for shadcn primitives bridged from `packages/ui` |
+
+## 2. Findings
+
+### 2.1 Dead components (zero importers found)
+
+> **Resolved 2026-05-19.** A re-verification scan confirmed that
+> `form-layout-01.tsx` and `section-cards.tsx` are **not present** in either
+> `apps/web/components/` or `packages/ui/template/components/` — the audit's
+> initial finding was based on a stale snapshot. No action needed.
+
+### 2.2 Onboarding components split between two locations
+
+> **Resolved 2026-05-19.** Option A landed:
+> - `getting-started.tsx` moved into `components/onboarding/getting-started.tsx`
+>   (both `apps/web/` and `packages/ui/template/`).
+> - Deprecated shims `dashboard-onboarding.tsx` and
+>   `dashboard-onboarding-gallery.tsx` deleted in both locations
+>   (no consumers outside themselves).
+> - `components/onboarding/index.ts` now re-exports `GettingStarted`,
+>   `GettingStartedProgressCard`, `GettingStartedVariantView`,
+>   `renderGettingStartedVariant`, `GETTING_STARTED_STORAGE_KEY`, and
+>   the `Onboarding01`–`Onboarding04` variant cards.
+> - Dashboard consumers (`dashboard-tabs.tsx`, `dashboard-report-charts.tsx`)
+>   import via `@/components/onboarding/getting-started`; intra-folder
+>   variants use the relative `./getting-started` path.
+
+### 2.3 Sidebar shell — high top-level density
+
+> **Resolved 2026-05-19.** All 11 sidebar files relocated into
+> `components/sidebar/` (both `apps/web/` and `packages/ui/template/`):
+>
+> ```
+> components/sidebar/
+> ├── index.ts            ← barrel re-export
+> ├── app-sidebar.tsx
+> ├── app-sidebar-dynamic.tsx
+> ├── sidebar-shell.tsx
+> ├── sidebar-auto-collapse.tsx
+> ├── sidebar-auto-open.tsx
+> ├── nav-main.tsx
+> ├── nav-secondary.tsx
+> ├── nav-documents.tsx
+> ├── nav-user.tsx
+> ├── secondary-nav.tsx
+> └── secondary-panel.tsx
+> ```
+>
+> **External consumers** now import via the barrel:
+> `import { AppSidebar, SidebarShell, useSecondaryPanel } from "@/components/sidebar"`.
+> Per-file paths still resolve (escape hatch), e.g.
+> `@/components/sidebar/secondary-panel`.
+>
+> **Intra-folder** imports use relative paths (`./nav-user`, `./secondary-panel`)
+> so internal restructure does not ripple out.
+>
+> Dead-import audit at completion: zero references to `@/components/<sidebar-file>"`
+> remain outside the new folder.
+>
+> `nav-main`, `nav-secondary`, `nav-documents`, `sidebar-auto-open` are
+> currently zero-import (only mentioned in docs/skills). They were moved for
+> directory consistency; pruning truly dead files is a separate concern.
+
+### 2.4 Dedicated-search files — naming consistent
+
+`dedicated-search-recents.tsx`, `dedicated-search-url-composer.tsx`,
+`components/templates/dedicated-search-{landing,results}-template.tsx` —
+generic family already lives across `templates/` + top-level. **No action.**
+
+### 2.5 Entity-bound views — correctly at top level
+
+`*-list-view.tsx`, `*-board-view.tsx`, `*-page-header.tsx`, `*-client.tsx`,
+`*-table.tsx`, `*-dashboard-charts*.tsx`, `*-os-folder-view.tsx`,
+`*-panel-activator.tsx` — these are entity-specific compositions that
+**must** stay co-located with the hub they serve. **No action.**
+
+### 2.6 Possibly generic — re-evaluate during reuse work
+
+- `tinted-icon-disc.tsx` — used in KPI/empty states. If the API has stabilized,
+  consider moving to `components/data-views/` or `packages/ui/src/components/ui/`.
+- `task-list-panel.tsx`, `task-priority-badge.tsx` — generic-sounding but
+  bound to a Task entity. Confirm scope before any move.
+- `tree-panel-view.tsx`-style: `hub-tree-panel-view.tsx`,
+  `folder-details-shell.tsx` — already generic-sounding. If imported by
+  ≥ 2 hubs, move under `data-views/`.
+
+A quick rule of thumb:
+
+> If a component is imported by **only one** hub, it stays at the top level
+> next to that hub.
+> If it is (or could be) imported by **≥ 2** hubs, promote it into
+> `components/data-views/` (record-bearing) or `components/templates/`
+> (page chrome).
+
+### 2.7 `packages/ui/template/` parity
+
+Most top-level files are mirrored under `packages/ui/template/components/`
+(starter scaffold for `create-exxat-app`). When a file moves in
+`apps/web/components/`, `pnpm --filter @exxatdesignux/ui sync-template`
+will also move it under `template/`. **Always run `sync-template` after any
+refactor under §2.3 / §2.6** so the published starter stays buildable.
+
+## 3. Non-findings — what's already healthy
+
+- **`components/ui/`** is reserved for shadcn-aligned primitives; no
+  duplicates appear at the top level (e.g. no rogue `button.tsx` next to the
+  one in `ui/`).
+- **`components/data-views/`** is the right home for generic record-bearing
+  surfaces (`FolderGridView`, `FinderPanelView`, `ListPageBoardCard`).
+  Entity-specific board cards (`placement-board-card.tsx`) correctly stay
+  at top level.
+- **`components/templates/`** is the right home for page-level wrappers
+  (`ListPageTemplate`, `DedicatedSearch*Template`,
+  `SecondaryPanelHubTemplate`, `DiscoveryHubTemplate`). No drift.
+- **No `components/lightning/`** folder anywhere — `exxat-no-slds-leakage`
+  rule already passes.
+- **No second toast surface** — only `components/ui/sonner.tsx` exists, and
+  it's gated by `exxat-no-toast` + the new `exxat-ds/no-sonner-toast` lint.
+
+## 4. Suggested follow-up PRs
+
+| # | Title | Scope | Risk |
+|---|---|---|---|
+| 1 | Remove dead `form-layout-01.tsx` + `section-cards.tsx` from `apps/web/` and `packages/ui/template/` | Trivial | Low |
+| 2 | Consolidate `getting-started.tsx` + `dashboard-onboarding*.tsx` under `components/onboarding/` | Small | Low (import rename) |
+| 3 | ~~Move sidebar files into `components/sidebar/`~~ — **done 2026-05-19** (§2.3) | Medium | — |
+| 4 | Promote `tinted-icon-disc.tsx`, `hub-tree-panel-view.tsx`, `folder-details-shell.tsx` to `data-views/` if used by ≥ 2 hubs | Small per file | Low |
+| 5 | Run `sync-template` after each of 1–4 to keep `packages/ui/template/` aligned | Single command | Low |
+
+None of these is urgent. They become valuable when the top-level file count
+exceeds ~110 or when a new hub joins the codebase.
+
+## 5. References
+
+- [`apps/web/AGENTS.md`](../AGENTS.md) §9 — architecture pointers
+- [`apps/web/docs/component-selection-guide.md`](./component-selection-guide.md)
+- [`.cursor/rules/exxat-reuse-before-custom.mdc`](../../.cursor/rules/exxat-reuse-before-custom.mdc) — ask before adding new primitives
+- [`.cursor/rules/exxat-list-page-view-shells.mdc`](../../.cursor/rules/exxat-list-page-view-shells.mdc) — when to extract to `data-views/`

package/template/docs/data-views-pattern.md

@@ -10,17 +10,17 @@ This document describes how list pages combine **views**, **toolbar** behavior,
 
 | Need | Reuse | Where Placements uses it |
 | --- | --- | --- |
-| **View tabs** (table / list / board, lifecycle filters) | `ListPageTemplate` (`ViewTab`, `renderContent`, optional metrics + export) | `components/data-list-client.tsx` + `components/templates/list-page.tsx` |
-| **Table shell** (search, filter bar, sort, grouping, columns, pagination) | `DataTable`, `DataTableToolbar`, `useTableState` | `components/data-table/`, `components/data-list-table.tsx` |
-| **Properties drawer** (display, columns, filters, sort, view type tiles) | `TablePropertiesDrawer` from `@/components/table-properties` | `DrawerToolbar` / list–board shells in `data-list-table.tsx` |
-| **Board / list** | `PlacementsBoardView`, `PlacementsListView` + same `useTableState` | `DataListTable` |
+| **View tabs** (table / list / board, lifecycle filters) | `ListPageTemplate` (`ViewTab`, `renderContent`, optional metrics + export) | `components/placements-client.tsx` + `components/templates/list-page.tsx` |
+| **Table shell** (search, filter bar, sort, grouping, columns, pagination) | `DataTable`, `DataTableToolbar`, `useTableState` | `components/data-table/`, `components/placements-table.tsx` |
+| **Properties drawer** (display, columns, filters, sort, view type tiles) | `TablePropertiesDrawer` from `@/components/table-properties` | `DrawerToolbar` / list–board shells in `placements-table.tsx` |
+| **Board / list** | `PlacementsBoardView`, `PlacementListRowContent` (wrapped by `HubTable.renderListRow` → `DataRowList`) + same `useTableState` | `PlacementsTable` |
 | **Page header** (primary CTA + More ⋯ + export) | `PlacementsPageHeader` or `TeamPageHeader` | `components/placements-page-header.tsx`, `components/team-page-header.tsx` |
-| **Team page (primary template)** | `TeamClient` = `ListPageTemplate` + `KeyMetrics` + `TeamPageHeader` + `TeamTable` (same composition as `DataListClient`) | `components/team-client.tsx`, `lib/mock/team-kpi.ts` |
+| **Team page (primary template)** | `TeamClient` = `ListPageTemplate` + `KeyMetrics` + `TeamPageHeader` + `TeamTable` (same composition as `PlacementsClient`) | `components/team-client.tsx`, `lib/mock/team-kpi.ts` |
 | **Team roster** | `TeamTable` — `DataTable` + `useTableState` + `TablePropertiesDrawer`; list/board/dashboard read **`tableState.rows`** | `components/team-table.tsx` |
 | **Dashboard view (list tab)** | **`KeyMetrics`** (`variant="flat"` or `"card"`) — same KPI system as the template metrics strip; **do not** add ad-hoc `Card` grids for entity summaries | `TeamTable` dashboard branch, `lib/mock/team-kpi.ts` |
 | **List hub metrics strip** | **`KeyMetrics variant="flat"`** — transparent cells, OKLCH brand glow only, border hairlines (**no** grey panel) | **`docs/kpi-flat-band-pattern.md`**, Placements / Team / Question bank clients |
 | **Secondary panel chrome** | **`--secondary-panel-bg`** on **`NestedSecondaryPanelShell`** (lighter than sidebar, follows active product) | **`docs/shell-surface-elevation-pattern.md`**, Question bank |
-| **Export** | `ExportDrawer` | `ListPageTemplate` export props; `DataListClient` |
+| **Export** | `ExportDrawer` | `ListPageTemplate` export props; `PlacementsClient` |
 | **View body layout** (gutter + centered max-width for folder / icon / panel-style content) | **`ListPageViewFrame`** (`components/data-views/list-page-view-frame.tsx`, re-exported from `components/data-views`) | **`FolderGridView`** (uses the frame); **`QuestionBankOsFolderView`** — see **`AGENTS.md` §4.5** |
 
 **Rules:** (1) Import and compose these components; pass **props** and **column defs** for your entity. (2) If something is missing, **extend the shared component** under `components/` (e.g. a new optional slot on `DataTableToolbar`) rather than copying markup into a single page. (3) Card-only or lightweight pages may use a smaller **Properties** sheet only when there is **no** table—otherwise use `TablePropertiesDrawer` with `DataTable` (see Team).
@@ -29,7 +29,7 @@ This document describes how list pages combine **views**, **toolbar** behavior,
 
 If the page uses a **`DataTable`** (or equivalent data grid) as the main surface, it **must** sit under **`ListPageTemplate`** so users get the **views toolbar** (tabs, add view, per-tab settings). The default `ViewTab` entries should include at least one tab whose `viewType` is **`table`** when the primary experience is tabular data. **Do not** render a `DataTable` alone under only `PageHeader` + body.
 
-- **Reference:** `DataListClient` (Placements) and `TeamClient` (Team).
+- **Reference:** `PlacementsClient` (Placements) and `TeamClient` (Team).
 - **Rationale:** Consistent navigation, saved views, per-tab view type (table / list / board), and export at the template level.
 
 ## View layout frame (centered, reusable)
@@ -41,7 +41,7 @@ Non-table view branches (e.g. **folder** icon grid, **panel** finder, OS-style f
 ## Architecture
 
 - **Page shell** — `ListPageTemplate` owns the views toolbar (tabs), optional metrics, and export drawer. Content for the active tab is rendered via `renderContent`.
-- **Per–lifecycle (or category) data** — `DataListTable` swaps **columns** and **row sets** based on `lifecycleTabId` (e.g. All / Upcoming / Ongoing / Completed). Each lifecycle tab gets its **own** `DataListTable` instance (`key={tab.filterId}`) so `useTableState` resets correctly when columns change.
+- **Per–lifecycle (or category) data** — `PlacementsTable` swaps **columns** and **row sets** based on `lifecycleTabId` (e.g. All / Upcoming / Ongoing / Completed). Each lifecycle tab gets its **own** `PlacementsTable` instance (`key={tab.filterId}`) so `useTableState` resets correctly when columns change.
 - **Shared table state** — `useTableState` holds sort, search, filters, grouping, column order/visibility/pins/widths, row height, gridlines, and pagination flags. **Table**, **list**, **board**, and **dashboard** all read the same state so switching view type keeps behavior aligned.
 
 ## Mock data and connected views
@@ -59,10 +59,10 @@ Non-table view branches (e.g. **folder** icon grid, **panel** finder, OS-style f
 
 | Concern | Table | List | Board | Dashboard (view tab) |
 | --- | --- | --- | --- | --- |
-| Primary surface | `DataTable` | `PlacementsListView` / entity list | `PlacementsBoardView` / entity board | **`KeyMetrics`** (+ optional charts via shared dashboard components) |
+| Primary surface | `DataTable` | `DataRowList` + entity row body (e.g. `PlacementListRowContent`) wired via `HubTable.renderListRow` | `PlacementsBoardView` / entity board | **`KeyMetrics`** (+ optional charts via shared dashboard components) |
 | Data source | `useTableState` | **`tableState.rows`** | **`tableState.rows`** | **`tableState.rows`** via KPI helpers |
 | Column headers / labels | `showColumnLabels` | Same source columns, list layout | Phase columns + optional board column menu | N/A (metrics from same columns/filters) |
-| Row click / navigation | From `DataListTable` | From list shell | Card `onOpen` | N/A |
+| Row click / navigation | From `PlacementsTable` | From list shell | Card `onOpen` | N/A |
 | Pagination | Optional `PaginationBar` + `CountSyncer` | Same pattern | N/A (board uses phase columns) | N/A |
 
 ## Toolbar and properties
@@ -99,10 +99,10 @@ Non-table view branches (e.g. **folder** icon grid, **panel** finder, OS-style f
 
 ## Persistence
 
-- **Page-level** (`lib/data-list-persistence.ts`, key `exxat-ds:data-list:page:v1`): `displayOptions`, `showMetrics`, `tabs`, `activeTabId`. Loaded in `DataListClient` with `useLayoutEffect`, saved debounced on change. `ListPageTemplate` runs in **controlled** mode when `tabs` / `onTabsChange` / `activeTabId` / `onActiveTabChange` are passed.
-- **Per–lifecycle tab** (key `exxat-ds:data-list:lifecycle:v1:<filterId>`): sort, search, filters, group by, column order/hidden/widths/pins/wrap, column menu search map, row height, gridlines, filter bar visibility, search popover, conditional rules, pagination toggle and page/size. Hydrated in `DataListTable` with `useLayoutEffect`; saved debounced when those fields change.
+- **Page-level** (`lib/data-list-persistence.ts`, key `exxat-ds:data-list:page:v1`): `displayOptions`, `showMetrics`, `tabs`, `activeTabId`. Loaded in `PlacementsClient` with `useLayoutEffect`, saved debounced on change. `ListPageTemplate` runs in **controlled** mode when `tabs` / `onTabsChange` / `activeTabId` / `onActiveTabChange` are passed.
+- **Per–lifecycle tab** (key `exxat-ds:data-list:lifecycle:v1:<filterId>`): sort, search, filters, group by, column order/hidden/widths/pins/wrap, column menu search map, row height, gridlines, filter bar visibility, search popover, conditional rules, pagination toggle and page/size. Hydrated in `PlacementsTable` with `useLayoutEffect`; saved debounced when those fields change.
 
-To add a new page: copy the `DataListClient` pattern (controlled `ListPageTemplate` + storage key namespace) or call `schedulePageSave` / `scheduleLifecycleSave` with your own keys.
+To add a new page: copy the `PlacementsClient` pattern (controlled `ListPageTemplate` + storage key namespace) or call `schedulePageSave` / `scheduleLifecycleSave` with your own keys.
 
 ## Rules of thumb
 
@@ -158,7 +158,7 @@ Canonical rules: **`AGENTS.md` §6.4**, root **`.cursor/rules/exxat-page-vs-draw
 
 When a route is a **primary** destination in nav (main hub for an entity) **and** the dataset is **large** or **highly interactive**:
 
-- Use the **primary page template**: `ListPageTemplate` (tabs, metrics strip, export drawer at template level) + data client pattern as in **`DataListClient`** / **`DataListTable`** — not a minimal `PageHeader`-only layout.
+- Use the **primary page template**: `ListPageTemplate` (tabs, metrics strip, export drawer at template level) + data client pattern as in **`PlacementsClient`** / **`PlacementsTable`** — not a minimal `PageHeader`-only layout.
 - Smaller satellite pages may use **`PageHeader` + section content**; once the dataset grows past the dense-list threshold, add the toolbar rules above and consider promoting to the full template if the page becomes a main hub.
 
 ---

package/template/docs/migrations/0001-brand-deep-alias-stabilization.md

@@ -0,0 +1,95 @@
+# Migration 0001 — `brand-deep` alias stabilization
+
+> **Released in:** v0.2.18 · **Removed in:** — (no removal — alias is now official) · **Owner:** Exxat DS core
+> **Type:** stabilization (clarifies an existing naming convention)
+
+## Why
+
+`bg-brand-deep` / `text-brand-deep` Tailwind utilities are used throughout
+`CoachMark` and several skill docs, but the **only** declared primitive is
+`--brand-color-deep`. The bridge `--color-brand-deep: var(--brand-color-deep)`
+in `theme.css @theme inline` made the utilities work — but contributors kept
+asking "is `--brand-deep` a real token or a typo of `--brand-color-deep`?".
+
+This migration **does not rename anything**. It documents the alias as
+**official** and codifies the rule for similar future cases:
+
+> A Tailwind utility may use a **short, semantic alias** at the L2 bridge,
+> distinct from the L1 primitive name, **only when the alias prevents an
+> awkward utility class** (e.g. `bg-brand-color-deep` is unwieldy; `bg-brand-deep`
+> reads naturally). The alias MUST be listed in `docs/token-taxonomy.md` and
+> in the generated `hooks-index.json`.
+
+Without this migration entry, future contributors might "fix" `bg-brand-deep`
+by renaming it to `bg-brand-color-deep`, breaking every coach mark.
+
+## Affected surface
+
+| Surface | Was | Becomes |
+|---|---|---|
+| Tailwind utility | `bg-brand-deep`, `text-brand-deep` | **unchanged** (stabilized) |
+| CSS custom prop (L2 bridge) | `--color-brand-deep` | **unchanged** (stabilized as alias) |
+| CSS custom prop (L1 primitive) | `--brand-color-deep` | **unchanged** (canonical name) |
+| Doc | _undocumented alias_ | Documented in `docs/token-taxonomy.md` §2.2 |
+
+## Before
+
+```css
+/* packages/ui/src/theme.css */
+@theme inline {
+  --color-brand-deep: var(--brand-color-deep);   /* alias — was undocumented */
+}
+
+:root {
+  --brand-color-deep: oklch(0.28 0.085 286.1);  /* L1 primitive */
+}
+```
+
+```tsx
+// packages/ui/src/components/ui/coach-mark.tsx — already correct
+<div className="bg-brand-deep text-white">…</div>
+```
+
+The risk was that someone would "tidy up" `--color-brand-deep` to
+`--color-brand-color-deep`, breaking `bg-brand-deep`.
+
+## After
+
+Same code; same tokens; **plus** an authoritative entry in
+[`docs/token-taxonomy.md`](../token-taxonomy.md) §2.2 listing every L1 → L2
+short-alias pair, and a regenerated [`packages/ui/tokens/hooks-index.json`](../../../packages/ui/tokens/hooks-index.json)
+that exposes `--brand-color-deep` with `tailwindUtilities:
+["bg-brand-deep", "text-brand-deep", …]` so tooling can discover the link.
+
+## Migration recipe
+
+### Automatic
+
+None needed — this migration changes documentation only.
+
+### Manual
+
+For **future** short-alias additions, follow this pattern:
+
+1. Declare the L1 primitive: `--brand-<name>: oklch(...)` in `:root` and any
+   theme overrides in `.dark` / `.theme-prism` / etc.
+2. Declare the L2 alias in `@theme inline`: `--color-<short>: var(--brand-<name>)`.
+3. Add a row to `docs/token-taxonomy.md` §2.2 listing the alias.
+4. Run `pnpm --filter @exxatdesignux/ui tokens:index` and commit.
+5. Use the alias **only** for the case where the long name is awkward; do
+   **not** create aliases for ergonomics alone.
+
+## Verification
+
+- [x] `pnpm --filter @exxatdesignux/ui tokens:index` runs and emits the alias
+      under `tailwindUtilities` for `--brand-color-deep`.
+- [x] `docs/token-taxonomy.md` §2.2 lists `--brand-color-deep` and its alias.
+- [x] `coach-mark.tsx` continues to render the deep-brand background.
+
+## References
+
+- `packages/ui/src/theme.css` — lines declaring `--brand-color-deep` and the alias
+- `packages/ui/src/components/ui/coach-mark.tsx`
+- `apps/web/docs/token-taxonomy.md` §2.2 (Brand)
+- `apps/web/docs/blueprints/page-header.md` (uses `--brand-color-*` family)
+- `.cursor/rules/exxat-token-discipline.mdc` (codifies the alias rule)