@exxatdesignux/ui 0.5.11 → 0.5.12

package/template/docs/kpi-flat-band-pattern.md

@@ -1,57 +0,0 @@
-# KPI flat band (`KeyMetrics` `variant="flat"`)
-
-> **Component:** `components/key-metrics.tsx` — **`flatMetricsHairlineClass`**, **`flatBandStyle`**.  
-> **Tokens:** `app/globals.css` — `--key-metrics-flat-*`.  
-> **Cursor:** `.cursor/rules/exxat-kpi-flat-band.mdc` · `.cursor/skills/exxat-kpi-flat-band/SKILL.md`  
-> **Related:** `docs/kpi-strip-max-four-pattern.md`, `docs/kpi-trend-pattern.md`
-
-## Intent
-
-List hubs and the main dashboard mix view use **`KeyMetrics variant="flat"`** as a **metrics strip without a surface**: users see KPI copy and deltas on the **page canvas**, with a **brand-colored glow** under the band only. This is **not** a card, tinted panel, or `gap-px` grid fill.
-
-## MUST
-
-1. **No band surface** — The `<section>` background is **only** `var(--key-metrics-flat-band-radial)`. **Do not** stack `--key-metrics-flat-band-linear`, opaque gradients, or `box-shadow` fills that read as a grey/lavender box.
-2. **Transparent cells** — `metricsCellSurfaceClassName` is **`bg-transparent`** for `variant="flat"`. **Do not** use `bg-background`, `bg-card`, or `gap-px` + `bg-border` / `bg-foreground/*` on the grid (that paints tile surfaces).
-3. **Hairlines = borders only** — Use **`flatMetricsHairlineClass(itemCount, metricsHalfWidthLayout)`** in `key-metrics.tsx`:
-   - **2 tiles:** `border-r` on the first cell only.
-   - **4 tiles, wide strip (default):** `border-r` on cells 1–3 (verticals between all columns); **no** horizontal rule.
-   - **4 tiles, narrow `@container` (&lt; 30rem, 2×2 grid):** odd-column `border-r` + `border-b` on the top row only (via `@[max-width:29.99rem]` overrides).
-4. **Divider color (OKLCH)** — `--key-metrics-flat-divider: color-mix(in oklch, var(--sidebar-border) 55%, transparent)`; apply on children with `[&>*]:border-[color:var(--key-metrics-flat-divider)]`. Dividers follow **active product** hue (`--sidebar-border`), not neutral grey alone.
-5. **Glow (OKLCH)** — Radial stops use `color-mix(in oklch, var(--brand-color) …%, transparent)` so **Exxat One / Prism / Assessment / `theme-custom`** each tint correctly. **Do not** hardcode rose/indigo literals on theme blocks unless documenting a one-off.
-6. **List page usage** — Prefer **`showHeader={false}`**, **`metricsSingleRow`** when four KPIs share one row; pass **`insight`** only when the insight rail is product-required (same row uses `lg:grid-cols-[3fr_2fr]`).
-7. **Cap at four tiles** — See **`docs/kpi-strip-max-four-pattern.md`**.
-
-## MUST NOT
-
-- Add **`--key-metrics-flat-band-linear`** back into `flatBandStyle` or hub inline styles (e.g. library hub hero).
-- Use **`variant="card"`** on **`ListPageTemplate`** metrics when the design calls for a **flat strip** on the page background.
-- Duplicate KPI numbers in ad-hoc **`Card`** grids on the same hub.
-- Set **`variant="mutedSuffix"`** on product wordmarks to grey out the **suffix** in dark mode — suffix stays **Exxat pink** (`wordmarkColor`); see **`lib/product-brand.ts`**.
-
-## Tokens (`app/globals.css`)
-
-| Token | Role |
-|--------|------|
-| `--key-metrics-flat-band-radial` | Bottom brand glow (only layer on flat `<section>`) |
-| `--key-metrics-flat-band-shadow` | **`none`** for flat band (no faux surface lift) |
-| `--key-metrics-flat-cell-bg` | **`transparent`** |
-| `--key-metrics-flat-divider` | OKLCH hairline between cells |
-
-Dark mode (`.dark`): same rules — transparent cells, radial glow only, no linear fill to `--background`.
-
-## Reference implementations
-
-- `components/library-client.tsx` — `KeyMetrics variant="flat" metricsSingleRow`
-- `components/dashboard-tabs.tsx` — mix view flat band + insight
-- `components/library-hub-client.tsx`, `columns-client.tsx`, `tokens-themes-client.tsx` — list hub metrics slot
-
-## Insight rail (flat + side-by-side)
-
-When **`insight`** is shown beside KPIs, the insight **`Card`** may keep its own surface; the **KPI grid** stays transparent. **Do not** add `lg:border-l` on the insight column for flat band — the insight card ring is the separator (`key-metrics.tsx`).
-
-## See also
-
-- **`docs/kpi-strip-max-four-pattern.md`**
-- **`docs/kpi-trend-pattern.md`**
-- **`docs/shell-surface-elevation-pattern.md`** — sidebar / secondary panel / page stack

package/template/docs/kpi-strip-max-four-pattern.md

@@ -1,30 +0,0 @@
-# KPI strip — maximum four tiles
-
-> **Code:** `lib/dashboard-layout-merge.ts` — **`KEY_METRICS_KPI_COUNT_MIN`**, **`KEY_METRICS_KPI_COUNT_MAX`** (4), **`clampKeyMetricsKpiCount`**. **Component:** `KeyMetrics` in `components/key-metrics.tsx`.
-
-## Rule
-
-On **primary list hubs** (`ListPageTemplate` metrics slot) and on **dashboard “key metrics” cards** (Data tab chart bundles), **show at most four** `MetricItem` tiles at once.
-
-## Why four
-
-- **Scanning** — More than four headline numbers compete; users miss deltas and period context.
-- **Layout** — `KeyMetrics` wraps to multiple rows; four keeps one or two clean rows on common breakpoints (including **`metricsHalfWidthLayout`** on span-1 cards).
-- **Persistence** — Dashboard layout already stores **`keyMetricsKpiCount`** in **`1…4`**; list-page KPI helpers should **not** return a fifth tile expecting it to display.
-
-## Implementation
-
-1. **KPI builders** (`lib/mock/*-kpi.ts`) — Return **≤ 4** items, or **`.slice(0, 4)`** after prioritizing (hero total + top three drivers). Merge extras into **`MetricInsight`** copy instead of a fifth tile when possible.
-2. **Dashboard canvas** — Never raise **`KEY_METRICS_KPI_COUNT_MAX`**; use **`clampKeyMetricsKpiCount`** when reading saved JSON.
-3. **Full-page dashboards** — If more summaries are needed, add **sections** (charts, tables, secondary cards), not a fifth KPI in the same strip.
-
-## MUST NOT
-
-- Ship **five+** `MetricItem` entries in a single **`KeyMetrics`** band meant as the **primary** KPI row for a hub or the **key-metrics** dashboard card.
-- Duplicate the same metric as two tiles to pad count — prefer **insight rail** or **`MetricInsight`**.
-
-## See also
-
-- **`docs/kpi-trend-pattern.md`** — deltas, arrows, **`trendPolarity`**.
-- **`docs/kpi-flat-band-pattern.md`** — **`variant="flat"`** presentation (orthogonal to tile count).
-- **`.cursor/rules/exxat-kpi-max-four.mdc`**, **`.cursor/skills/exxat-kpi-max-four/SKILL.md`**

package/template/docs/kpi-trend-pattern.md

@@ -1,58 +0,0 @@
-# KPI trend arrows and deltas (`KeyMetrics`)
-
-> **Handbook:** [`AGENTS.md`](../AGENTS.md) (mock KPI helpers, `KeyMetrics`). **Component:** [`components/key-metrics.tsx`](../components/key-metrics.tsx). **Cursor:** [`.cursor/rules/exxat-kpi-trends.mdc`](../../.cursor/rules/exxat-kpi-trends.mdc). **Skill:** [`.cursor/skills/exxat-kpi-trends/SKILL.md`](../../.cursor/skills/exxat-kpi-trends/SKILL.md).
-
-## Goals
-
-1. **Contextual** — The **label**, **value format** (count, %, currency, days), and **comparison period** (e.g. “vs last week”) must read as one story. Do not paste a generic “+12%” without tying it to what moved.
-2. **Honest direction** — **`trend`** (`up` | `down` | `neutral`) always matches the **signed change** in the underlying metric so the **arrow** reflects reality.
-3. **Correct sentiment** — **`trendPolarity`** decides whether “up” is **good news** (tint + assistive copy), **bad news**, or **informational** (muted — direction only).
-
-## `MetricItem` fields
-
-| Field | Role |
-| --- | --- |
-| `value` | Current bucket total or rate (formatted string or number). |
-| `delta` | **Count change for the trend chip**, e.g. `+5`, `-3`, `+12%`. Pass `""` (or `0`) when there is no comparison this period — the chip is then **hidden**, not rendered as `—`. **Never** put captions or labels like `"left + right"` here. |
-| `description` | Optional **caption** rendered **below** the value + trend row (muted, small). Use for *what* moved or *how* the value breaks down — `"left + right"`, `"vs last week"`, `"across 4 sites"`, `"scheduled for removal"`. |
-| `trend` | **Visual direction** of the delta: more → `up`, less → `down`, flat / N/A → `neutral`. Combined with an empty `delta`, `neutral` collapses the chip. |
-| `trendPolarity` | Optional. **`higher_is_better`** (default) \| **`lower_is_better`** \| **`informational`**. |
-
-### Layout
-
-```
-┌─────────────────────────────────────────────┐
-│ Pinned columns                              │  ← label
-│ 2  ↑ +1                                     │  ← value + (delta in chip)
-│ left + right                                │  ← description (caption)
-└─────────────────────────────────────────────┘
-```
-
-The **only** thing next to the arrow is the **count**. Prose lives **below** the value as a description. When there is no direction *and* no count, the chip is **suppressed** entirely (no `—` placeholder).
-
-## Polarity cheat sheet
-
-| `trendPolarity` | Use when | Up arrow tint | Down arrow tint |
-| --- | --- | --- | --- |
-| **`higher_is_better`** (default) | Revenue, pass rate, completions, enrolled count, positive CSAT | Favorable (brand / chart positive token) | Unfavorable (destructive) |
-| **`lower_is_better`** | Error rate, overdue tasks, **low PBI / item quality flags**, time-on-task when minimizing, spend when cutting cost | Unfavorable | Favorable |
-| **`informational`** | Library size, mix %, neutral volume | Muted | Muted |
-
-**Psychometrics example:** Point-biserial (PBI) **dropping** usually helps discrimination — often good (`lower_is_better` on a *“low quality” count* is clearer: **count of items below a review threshold** rising → `trend: "up"` + `trendPolarity: "lower_is_better"` → arrow up with **unfavorable** tint).
-
-## Accessibility
-
-- **Never colour alone:** `KeyMetrics` keeps **icon + numeric delta**; `aria-label` on the chip uses **`metricTrendAriaQualifier`** (e.g. “increased, unfavorable +1”).
-- **Decorative icons** stay `aria-hidden`; meaning lives in the chip’s **`aria-label`** and visible delta text.
-
-## Anti-patterns
-
-- Forcing **`trend: "up"`** green because “up feels good” when the metric is **defects** or **flags** — set **`lower_is_better`** instead.
-- Hiding a worsening metric by flipping the arrow without changing **`trend`** — arrows must match the data.
-- Using **`informational`** for KPIs that **do** have an agreed quality bar — pick a polarity instead.
-- Rendering an **empty `—`** chip just for layout symmetry. The component already hides the chip when there is no direction *and* no count; leave `delta: ""` + `trend: "neutral"` and use `description` for the supporting caption.
-- Putting captions like **`"left + right"`**, **`"hidden"`**, **`"shown"`**, **`"vs last week"`** in **`delta`**. Those are not deltas. Use **`description`**.
-
-## Related surfaces
-
-- **`ChartCard`** `miniMetrics` / `kpi-chart` variant — optional **`trendPolarity`** on each mini metric; uses the same **`metricTrendTone`** helper from `key-metrics.tsx`.

package/template/docs/large-dataset-strategy.md

@@ -1,155 +0,0 @@
----
-title: Large dataset strategy
----
-
-# Large dataset strategy
-
-How the Exxat DS table stack scales as record counts grow — what works today, when to
-turn pagination on, and what to add when the dataset outgrows the browser. Cross-linked
-from [`apps/web/AGENTS.md`](../AGENTS.md) and [`data-views-pattern.md`](./data-views-pattern.md).
-
-## TL;DR
-
-| Row count | What to do |
-|---|---|
-| **≤ 200** | Default `HubTable` setup. No pagination. Filter / sort all in memory. |
-| **200 – 5K** | Turn pagination on (`pagination={true}` on `HubTable`). Default page size 10–25. List + board views auto-virtualize at 100 rows via `DataRowList`. |
-| **5K – 50K** | Stay client-side with pagination, but consider adding `@tanstack/react-virtual` to the `DataTable` `<tbody>` (follow-up; see below). Filtering all rows in memory still works — `useTableState` is sub-100ms at 50K on a typical laptop. |
-| **> 50K** | Switch to **server mode**: lift filters / sort / page out of `useTableState` via `paginationOverride` and fetch one page at a time. The hub composition (`ListPageTemplate` + `HubTable` + Properties drawer) does not change. |
-
-## Today (client mode, in-memory)
-
-The default `HubTable` rendering path is fully client-side:
-
-```mermaid
-flowchart LR
-  Mock["lib/mock/* (or API on first paint)"] --> Rows["rows: TRow[] (full dataset)"]
-  Rows --> UTS["useTableState(rows, columns, sort, paginationOverride?)"]
-  UTS --> FRows["state.rows (filtered + sorted)"]
-  UTS --> PRows["state.pagedRows (sliced when pagination is on)"]
-  FRows --> DT["DataTable body (renders every row in pagedRows)"]
-  FRows --> DRL["DataRowList (auto-virtualizes at 100 rows)"]
-  FRows --> Board["ListPageBoardTemplate (virtualizes per-column)"]
-  FRows --> Dash["Dashboard charts"]
-```
-
-Key properties:
-
-1. **One row bag, every view.** Table / list / board / dashboard / folder / panel all read
-   `tableState.rows` (already filtered + sorted). No parallel arrays — see
-   [`.cursor/rules/exxat-centralized-list-dataset.mdc`](../../.cursor/rules/exxat-centralized-list-dataset.mdc).
-2. **`useTableState` is the only filter pass.** Every keystroke in the toolbar search or any
-   filter-chip change re-runs the predicate set across the full input array. This is
-   in-memory `Array.filter` / `Array.sort` — fast enough to be invisible up to ~50K rows on
-   typical hardware.
-3. **Table grid does NOT virtualize today.** When pagination is off, `DataTable` renders
-   every row in `state.rows` as a `<tr>`. With pagination on, it only renders the current
-   page — typically 10–25 rows — so DOM cost is constant regardless of the dataset size.
-4. **List + board views DO virtualize.** `DataRowList` uses `@tanstack/react-virtual` with
-   a `virtualizeThreshold` (default 100) so 5K rows in the **list** tab paint instantly
-   even without pagination. `ListPageBoardTemplate` slices per column with the same
-   threshold.
-
-## When to turn on pagination
-
-`HubTable` accepts a `pagination={true}` prop that wires:
-
-- The Properties drawer's **Show pagination** toggle.
-- `CountSyncer` so filter changes reset to page 1.
-- `PaginationBar` glued to the bottom of the table card (sticky at viewport bottom on
-  overflow).
-
-```tsx
-<HubTable
-  rows={items}
-  columns={columns}
-  pagination
-  paginationInitialPageSize={25}
-  paginationPageSizeOptions={[10, 25, 50, 100]}
-  // …
-/>
-```
-
-Rule of thumb: **once the table no longer fits on one screen, enable pagination.** That's
-typically around 100 rows for product grids with avatars / two-line cells. Below that,
-scroll-everything feels lighter than chrome.
-
-## Beyond 50K — server mode
-
-`useTableState` accepts a `paginationOverride: { page, pageSize }` so the hub owner can
-lift page state out of the table. Pair that with a `fetcher(page, pageSize, filters,
-sort) => Promise<{ rows, total }>` and you have classic server-side pagination without
-touching any DS primitive.
-
-Skeleton (planned, not implemented today):
-
-```tsx
-function MyHubClient() {
-  const [page, setPage]         = useState(1)
-  const [pageSize, setPageSize] = useState(25)
-  const [filters, setFilters]   = useState<FilterStateShape>(EMPTY_FILTERS)
-  const [sort, setSort]         = useState<SortState>(DEFAULT_SORT)
-
-  // Server fetches one page at a time, returns 25 rows + total count
-  const { data, isLoading } = useQuery({
-    queryKey: ["my-hub", page, pageSize, filters, sort],
-    queryFn:  () => fetchMyHubPage({ page, pageSize, filters, sort }),
-  })
-
-  return (
-    <HubTable
-      rows={data?.rows ?? []}
-      paginationOverride={{ page, pageSize }}
-      // …filters / sort wired the same way
-    />
-  )
-}
-```
-
-What stays the same:
-
-- `HubTable` composition (toolbar + filter chips + Properties + view tabs).
-- `ColumnDef` shape, including `filter:` blocks.
-- The Properties drawer Display / Filter / Sort / Columns / Conditional rules panels.
-
-What changes:
-
-- The filter / sort / page state is **lifted** out of `useTableState`'s internal reducer
-  and into the hub client (so it can be threaded into the fetcher).
-- A loading row state in `DataTable` (already supported via `emptyState`; we'd add a
-  skeleton variant when the data array is empty but a fetch is in-flight).
-
-## Follow-up: row virtualization for `DataTable`
-
-For "infinite scroll" dense grids (Notion / Airtable feel) without pagination, add
-`@tanstack/react-virtual` to `DataTable`'s `<tbody>`:
-
-- The package is already a dependency (used by `DataRowList`).
-- The mechanics are very similar to `DataRowList` — measure visible viewport height,
-  render only the `<tr>` rows in the visible window, padding the head/tail with empty
-  rows of the right pixel height.
-- Caveats: row pinning (left / right sticky columns) needs care; row-detail "expanded"
-  rows complicate height estimation; `groupable` rows would need flat indexing.
-
-This is documented as a follow-up. Not on the critical path because pagination handles
-the same scaling concern with simpler ergonomics.
-
-## What we do NOT do
-
-- **No infinite-scroll-by-default on the table grid.** Pagination is explicit, keyboard
-  reachable, and links well. Infinite scroll on a primary product grid hurts deep-link
-  reachability and keyboard navigation.
-- **No per-cell async hydration.** Every cell render reads from the row prop synchronously.
-  Async cell content (e.g. user avatar from a separate endpoint) is a column-level
-  concern — the column's `cell:` renderer can `useQuery` for that data, but it should not
-  block the row from painting.
-- **No client-side fetch waterfalls.** When the dataset moves to server mode, fetch the
-  page once with the filter / sort / page key. Don't fan out per-row fetches.
-
-## See also
-
-- [`exxat-data-tables.mdc`](../../.cursor/rules/exxat-data-tables.mdc) — `HubTable` is the
-  only product-data-list stack.
-- [`exxat-centralized-list-dataset.mdc`](../../.cursor/rules/exxat-centralized-list-dataset.mdc)
-  — one `useTableState` row bag, every view.
-- [`data-views-pattern.md`](./data-views-pattern.md) — connected-view architecture.

package/template/docs/library-hub-header-pattern.md

@@ -1,25 +0,0 @@
-# Library hub header — folder scope + Customize folder
-
-**Audience:** Engineers extending the library library hub (`LibraryClient`, `LibraryPageHeader`, URL scope).
-
-## Problem
-
-The library uses **`ListPageTemplate`** with multiple **view tabs** (table, panel, tree, …). **`LibraryNewFolderSheet`** (customize mode) is also used inside **`LibraryTable`** for some views (e.g. panel columns). If **Customize folder** exists only there, users on **table** or other tabs **cannot** open the sheet from a consistent chrome entry point when the URL is scoped to a folder (`?scope=folder&folderId=…`).
-
-## Pattern
-
-1. **`LibraryPageHeader`** exposes optional **`onCustomizeFolder?: () => void`**. When **`navState.scope === "folder"`** and **`navState.folderId`** is set, the hub client passes a callback that opens customize mode for the matching **`LibraryFolder`**.
-2. **`LibraryClient`** (or equivalent hub client) mounts **`LibraryNewFolderSheet`** **once** beside **`SecondaryPanelHubTemplate` / `ListPageTemplate`**, with local state for **`open`** and **`customizingFolder`**. Saving updates **`folders`** the same way as table-embedded customize flows.
-3. The header **⋯ More** menu order stays aligned with **§4.7**: **Invite people** (when collaboration variant) → **Customize folder** (when folder-scoped) → **Export** → **Show / hide metric section** (when applicable).
-
-## References
-
-| Piece | Location |
-|-------|-----------|
-| Header prop + menu item | `components/library-page-header.tsx` |
-| Client wiring + sheet | `components/library-client.tsx` |
-| URL scope | `lib/library-nav.ts` (`parseLibraryNav`, `LibraryNavState`) |
-| Sheet UI | `components/library-new-folder-sheet.tsx` |
-
-**Cursor rule:** `.cursor/rules/exxat-library-hub-header.mdc`  
-**Handbook:** `AGENTS.md` §4.6 (folder-scoped hub chrome).

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

@@ -1,95 +0,0 @@
-# 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)

package/template/docs/migrations/0002-exxat-token-namespace.md

@@ -1,154 +0,0 @@
-# Migration 0002 — Exxat L0 canonical token namespace
-
-> **Released in:** v0.2.19 (next minor) · **Removed in:** _not planned (additive — L1 stays for shadcn primitives)_ · **Owner:** Design system
-
-## Why
-
-Until v0.2.18 the token system mixed two conventions:
-
-1. **shadcn names** inherited from upstream (`--background`, `--foreground`,
-   `--primary`, `--card`, `--popover`, `--ring`, …)
-2. **Exxat extensions** added next to them with assorted prefixes (`--brand-*`,
-   `--chip-*`, `--chart-*`, `--dt-*`, `--key-metrics-*`, `--sidebar-*`, …)
-
-This was readable but had three pain points:
-
-- **Discovery** — `grep -r "--brand"` finds product code but `grep -r "--exxat-"`
-  found nothing; there was no single prefix for "this is ours".
-- **Branding** — patterns docs and the SLDS comparison kept asking "where is
-  the `--exxat-color-surface-1`?" (the user's framing).
-- **Portability** — future non-React or non-shadcn consumers (Figma sync,
-  Penpot, native iOS/Android themes) need a clean namespace they can rename
-  without confusing it with upstream shadcn primitives.
-
-This migration introduces an **Exxat L0 canonical namespace** that gives every
-product token a single, flat, branded prefix — modeled on SLDS's
-`--slds-g-color-surface-1` style.
-
-## Affected surface
-
-- `packages/ui/src/globals.css` — L0 block in `:root` (61 aliases). *(Originally landed in `packages/ui/src/theme.css`; that file was retired in [`0003-globals-css-canonical.md`](./0003-globals-css-canonical.md), so the L0 block now lives in `globals.css`.)*
-- `packages/ui/src/globals.css` — added Tailwind bridges in `@theme inline`
-- `apps/web/app/globals.css` — mirror
-- `packages/ui/template/app/globals.css` — mirror
-- `packages/ui/tokens/hooks-index.json` — regenerated (102 → 163 tokens; 24 → 36 namespaces)
-- `apps/web/docs/token-taxonomy.md` — new §2.0 documenting L0
-- `packages/ui/scripts/build-tokens-index.mjs` — `exxat-*` namespace inference
-
-**No existing token was renamed.** L1 (shadcn names) and L3 (theme overrides)
-remain canonical OKLCH literals; L0 simply gives every consumer a `var(L1)`
-alias under the Exxat prefix.
-
-## Before
-
-```tsx
-// Direct CSS variable
-<div style={{ background: "var(--background)", color: "var(--foreground)" }} />
-
-// Tailwind utility
-<div className="bg-background text-foreground rounded-md border" />
-```
-
-Naming was inconsistent — `--background`, `--brand-color`, `--chip-1`,
-`--dt-row-bg` all live at the top level with no shared "this is Exxat"
-identifier.
-
-## After
-
-```tsx
-// Direct CSS variable — L0 canonical
-<div style={{ background: "var(--exxat-color-surface-1)", color: "var(--exxat-color-ink-1)" }} />
-
-// Tailwind utility — short utility forms backed by L0
-<div className="bg-surface-1 text-ink-1 rounded-2 border-1" />
-```
-
-Both forms above continue to work. The L0 forms are **encouraged for new code**
-because they are:
-
-- **Grep-able** — `grep --exxat-` finds every product token
-- **Portable** — non-React consumers can map the L0 prefix to their platform
-- **Self-documenting** — `--exxat-color-surface-1` reads as a designed slot,
-  not a shadcn implementation detail
-
-## Migration recipe
-
-> **Non-breaking.** No existing code needs to change. The migration is to use
-> L0 forms in **new** components and **opportunistically** in touched files.
-
-### Optional global pass (when you're already in the file)
-
-Search and replace inside the file you're editing — do **not** open a
-repo-wide rewrite PR; it adds noise without product value.
-
-| shadcn (L1) | Exxat (L0) | Tailwind |
-|---|---|---|
-| `var(--background)` | `var(--exxat-color-surface-1)` | `bg-surface-1` |
-| `var(--card)` | `var(--exxat-color-surface-2)` | `bg-surface-2` |
-| `var(--popover)` | `var(--exxat-color-surface-3)` | `bg-surface-3` |
-| `var(--muted)` | `var(--exxat-color-surface-muted)` | `bg-surface-muted` |
-| `var(--foreground)` | `var(--exxat-color-ink-1)` | `text-ink-1` |
-| `var(--muted-foreground)` | `var(--exxat-color-ink-2)` | `text-ink-2` |
-| `var(--brand-color)` | `var(--exxat-color-brand-1)` | `bg-brand-1` |
-| `var(--brand-color-dark)` | `var(--exxat-color-brand-2)` | `bg-brand-2` |
-| `var(--brand-tint)` | `var(--exxat-color-brand-tint-1)` | `bg-brand-tint-1` |
-| `var(--border)` | `var(--exxat-color-border-1)` | `border-1` |
-| `var(--ring)` | `var(--exxat-color-focus-ring)` | `ring-focus-ring` |
-| `var(--radius)` / `--radius-md` | `var(--exxat-radius-2)` | `rounded-2` |
-| `var(--radius-sm)` | `var(--exxat-radius-1)` | `rounded-1` |
-
-### What you SHOULD NOT migrate
-
-- **shadcn primitives in `components/ui/*`** still use L1 names (`--background`,
-  `--border`, `--ring`, …). They are the upstream contract and stay.
-- **Bridge tokens already aliased at L2** (`--color-brand`, `--color-chip-1`)
-  keep their existing utility shape (`bg-brand`, `text-chip-1`).
-
-## Verification
-
-```bash
-# Regenerate the hooks index, confirm 163 tokens / 36 namespaces.
-pnpm --filter @exxatdesignux/ui tokens:index
-
-# Confirm L0 tokens picked up the right namespaces.
-node -e "
-  const j = require('./packages/ui/tokens/hooks-index.json');
-  const buckets = {};
-  for (const [k, v] of Object.entries(j.tokens)) {
-    if (!k.startsWith('--exxat-')) continue;
-    buckets[v.namespace] = (buckets[v.namespace] || 0) + 1;
-  }
-  console.table(buckets);
-"
-```
-
-Expected counts: `exxat-surface=8`, `exxat-ink=9`, `exxat-brand=7`,
-`exxat-action=3`, `exxat-border=4`, `exxat-focus=1`, `exxat-overlay=1`,
-`exxat-chart=5`, `exxat-chip=6`, `exxat-radius=6`, `exxat-spacing=8`,
-`exxat-control=3`.
-
-Sanity check the Tailwind bridge by inspecting any L0 color token —
-`tailwindUtilities` must contain the short forms (`bg-surface-1`,
-`bg-brand-1`, …).
-
-## Future direction
-
-When all consumers have migrated to L0:
-
-1. Flip the canonical direction so **L0 holds the OKLCH literal** and **L1
-   becomes a `var(L0)` alias**.
-2. Move per-theme overrides in `.dark` / `.theme-one` / `.theme-prism` /
-   `[data-contrast]` to write L0 names.
-3. Mark L1 names `@deprecated` for the components/ui shadcn primitives that
-   still consume them, then remove or vendor-rename them inside the DS.
-
-That's a much bigger lift and **not** in scope here. This migration just makes
-the eventual flip possible — and gives the rest of the system a clean,
-brandable, portable namespace today.
-
-## References
-
-- [`token-taxonomy.md`](../token-taxonomy.md) §1 — layering, §2.0 — L0 map
-- [`packages/ui/tokens/hooks-index.json`](../../../packages/ui/tokens/hooks-index.json) — machine-readable index
-- [`.cursor/rules/exxat-token-discipline.mdc`](../../../.cursor/rules/exxat-token-discipline.mdc) — lint rule + ESLint plugin
-- SLDS v1 → v2 uplift skill (inspiration): <https://www.lightningdesignsystem.com/2e1ef9c7e/v/1604/p/9929fa-uplift-skill>