@exxatdesignux/ui 0.2.19 → 0.4.0

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

@@ -0,0 +1,155 @@
+---
+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

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

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

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

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

package/template/docs/migrations/0003-globals-css-canonical.md

@@ -0,0 +1,110 @@
+# 0003 — `packages/ui/src/globals.css` is now the only CSS source of truth
+
+**Status:** Landed
+**Date:** 2026-05-19
+**Author:** Exxat DS hardening sweep
+**Breaking?** Yes for any external consumer of `@exxatdesignux/ui` that
+imported `@exxatdesignux/ui/theme.css` directly. The package is **not yet
+shipped**, so customer impact is zero. Internal consumers updated as part
+of this PR.
+
+## Why
+
+Until now, the design system kept the same theme tokens duplicated across
+**four** CSS files:
+
+| File | Purpose | Status |
+|---|---|---|
+| `packages/ui/src/theme.css`     | "thin" package CSS without Tailwind imports | dead — never `@import`-ed by code |
+| `packages/ui/src/globals.css`   | "full" package CSS (Tailwind imports + tokens) | drifted (older `--input` value, missing `--header-height`) |
+| `apps/web/app/globals.css`      | consumer of the package | up-to-date copy |
+| `packages/ui/template/app/globals.css` | starter template (auto-synced from apps/web) | up-to-date copy |
+
+Each token change required up to **three** manual mirror edits, and the
+files had **already silently drifted**: `--input` value differed between
+the package and apps/web (one was `oklch(0.62 0.01 264.52)`, the other
+`oklch(0.6694 0.0063 264.52)`).
+
+This is exactly the maintenance trap SLDS deliberately avoids by having
+one source file. Now that the package is not yet shipped, the breaking
+change is free.
+
+## What changed
+
+1. **`packages/ui/src/globals.css` is now canonical.** It carries
+   `@import "tailwindcss"`, `@import "tw-animate-css"`, the
+   `@custom-variant` declarations, the full `@theme inline` block (L2),
+   every `:root` / `.dark` / `.theme-*` / `[data-contrast="high"]` block
+   (L0 + L1 + L3), the `@layer base` rules, and the `@font-face`
+   declarations. No `@source` directive — that lives in the consumer.
+
+2. **`apps/web/app/globals.css` is now a 20-line shell.** It does:
+   ```css
+   @import "@exxatdesignux/ui/globals.css";
+   @source "../../../packages/ui/src";
+   ```
+   Nothing else. All previous content moved into the package.
+
+3. **`packages/ui/template/app/globals.css` is the same shell** with the
+   `@source` path patched to `../node_modules/@exxatdesignux/ui/src` (the
+   `sync-template-from-web.mjs` script already does this rewrite).
+
+4. **`packages/ui/src/theme.css` is deleted.** It was a stale, smaller
+   copy of `globals.css` that no code `@import`-ed (only docs referenced
+   it). The `./theme.css` entry was removed from `package.json` exports.
+
+5. **`packages/ui/scripts/build-tokens-index.mjs` now parses
+   `globals.css` only** (instead of theme.css + globals.css). Token
+   count went from 163 → **195** because the canonical file now captures
+   tokens that previously lived only in `apps/web/app/globals.css`
+   (`--header-height`, `--theme-color-chrome`, scoped overlays, etc.).
+   Namespace count went from 36 → **41**.
+
+## Migration recipe
+
+### Internal consumers (this monorepo)
+
+Nothing to do. The shells already `@import "@exxatdesignux/ui/globals.css"`.
+
+### External consumers (post-publish)
+
+If you previously had:
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "@exxatdesignux/ui/theme.css";   /* ❌ no longer exported */
+@source "...";
+```
+
+Change it to:
+```css
+/* app/globals.css */
+@import "@exxatdesignux/ui/globals.css"; /* brings Tailwind + tw-animate-css + tokens + base layer */
+@source "../node_modules/@exxatdesignux/ui/src";
+```
+
+The package globals.css now carries the `@import "tailwindcss"` /
+`@import "tw-animate-css"` for you — your shell only needs `@source`
+plus any app-specific additions.
+
+## Verification
+
+- `pnpm --filter @exxatdesignux/ui tokens:index` → 195 tokens / 41 namespaces, no errors.
+- `pnpm --filter @exxat-ds/web lint` → no new violations.
+- Grep for stale `theme.css` references → only this migration + the 0002 link.
+
+## Follow-ups (optional)
+
+- Document the canonical-file rule in `apps/web/AGENTS.md` § token
+  taxonomy (already updated).
+- Add a CI check to `tokens:check` that fails when the consumer shell
+  contains anything other than `@import` + `@source` + comments, so the
+  shell stays thin.
+
+## See also
+
+- [`docs/token-taxonomy.md`](../token-taxonomy.md) — layered token model.
+- [`0002-exxat-token-namespace.md`](./0002-exxat-token-namespace.md) — the
+  L0 namespace introduction (which now lives in `globals.css`, not
+  `theme.css`).

package/template/docs/migrations/README.md

@@ -0,0 +1,100 @@
+# Exxat DS — Migrations
+
+**Inspired by:** SLDS [v1 → v2 uplift skill](https://www.lightningdesignsystem.com/2e1ef9c7e/v/1604/p/9929fa-uplift-skill).
+
+Every breaking change in `@exxatdesignux/ui` (token rename, component prop
+removal, deprecated pattern) lives here as a numbered migration entry. The
+**first entry of any release that breaks API or tokens** must land alongside
+the change.
+
+---
+
+## How migrations work
+
+```
+docs/migrations/
+├── README.md           ← this file (active deprecations + index)
+└── NNNN-<slug>.md      ← one file per migration
+```
+
+| Field | Meaning |
+|---|---|
+| `NNNN` | Zero-padded 4-digit sequence number (`0001`, `0002`, …) |
+| `<slug>` | Short kebab-case identifier — what is changing |
+
+**One file per migration.** Two unrelated changes in the same release get two
+files.
+
+---
+
+## Lifecycle of a deprecation
+
+1. **Plan** — Open a migration file even before the release ships. Author the
+   `Why` and `Before/After` sections; leave `Released in` blank.
+2. **Announce** — When the change lands, fill `Released in` (e.g. `v0.3.0`),
+   add the `@deprecated` comment in `packages/ui/src/globals.css` or the component file:
+   ```css
+   /* @deprecated v0.3.0 — use --brand-color-dark; remove in v0.4.0 */
+   ```
+   Make sure `pnpm --filter @exxatdesignux/ui tokens:index` picks it up
+   (`tokens/hooks-index.json` will mark `deprecated: true`).
+3. **Migrate** — Land the migration script (if scriptable) under
+   `packages/ui/scripts/migrate-NNNN-<slug>.mjs`; otherwise document the manual
+   grep + replace.
+4. **Remove** — When the deprecation window closes (named in the comment),
+   delete the deprecated token / component. Set `Removed in` in the migration
+   file. The file stays in the repo forever as a record.
+
+---
+
+## Active deprecations
+
+> _None yet._ Update this table when announcing a deprecation.
+
+| Migration | Token / Component | Deprecated in | Remove in |
+|---|---|---|---|
+| — | — | — | — |
+
+---
+
+## Migration template
+
+Copy [`_template.md`](./_template.md) when adding a migration:
+
+```
+# Migration NNNN — <Title>
+
+> **Released in:** vX.Y.Z · **Removed in:** vX.Y.Z (or "planned") · **Owner:** <person/team>
+
+## Why
+…
+## Affected surface
+…
+## Before
+…
+## After
+…
+## Migration recipe
+…
+## Verification
+…
+```
+
+---
+
+## Index
+
+| # | Slug | Released | Removed |
+|---|---|---|---|
+| [0001](./0001-brand-deep-alias-stabilization.md) | `brand-deep-alias-stabilization` | v0.2.18 | — (no removal — stabilization) |
+| [0002](./0002-exxat-token-namespace.md) | `exxat-token-namespace` | v0.2.19 | — (additive — L1 stays) |
+| [0003](./0003-globals-css-canonical.md) | `globals-css-canonical` | v0.2.20 | `theme.css` removed |
+
+---
+
+## See also
+
+- [`token-taxonomy.md`](../token-taxonomy.md) — naming + deprecation policy (§5)
+- [`packages/ui/CHANGELOG.md`](../../../packages/ui/CHANGELOG.md) — release notes
+- [`.cursor/rules/exxat-token-discipline.mdc`](../../../.cursor/rules/exxat-token-discipline.mdc) — lint rule for deprecated tokens
+- [`packages/ui/tokens/hooks-index.json`](../../../packages/ui/tokens/hooks-index.json) — machine-readable index (includes `deprecated: true`)