@exxatdesignux/ui 0.2.19 → 0.3.0

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

package/template/docs/migrations/_template.md

@@ -0,0 +1,64 @@
+# Migration NNNN — <Title>
+
+> **Released in:** vX.Y.Z · **Removed in:** vX.Y.Z (or _planned_) · **Owner:** <person / team>
+> **Type:** token rename · component rename · prop removal · pattern deprecation · stabilization
+
+## Why
+
+One paragraph. Explain the user-visible or developer-visible problem this
+migration addresses.
+
+## Affected surface
+
+| Surface | Was | Becomes |
+|---|---|---|
+| Tailwind utility | `text-foo` | `text-bar` |
+| CSS custom prop | `--foo` | `--bar` |
+| React component | `<OldName />` | `<NewName />` |
+| Pattern | … | … |
+
+## Before
+
+```tsx
+// Old usage
+```
+
+## After
+
+```tsx
+// New usage
+```
+
+## Migration recipe
+
+### Automatic
+
+```bash
+# Run from the monorepo root.
+node packages/ui/scripts/migrate-NNNN-<slug>.mjs
+```
+
+(Or note "manual only — no script.")
+
+### Manual
+
+1. Search for `<pattern>` across `apps/web/`, `packages/ui/src/`, and
+   `packages/ui/template/`.
+2. Replace per the table above.
+3. Re-run `pnpm --filter @exxatdesignux/ui tokens:index`.
+4. Re-run `pnpm --filter @exxat-ds/web lint`.
+
+## Verification
+
+- [ ] `pnpm typecheck` clean across workspace
+- [ ] `pnpm --filter @exxatdesignux/ui tokens:check` passes
+- [ ] No remaining matches for `<old pattern>` in code search (excluding this
+      migration file)
+- [ ] Visual regression sweep on affected hubs (Placements / Team /
+      Compliance / Question bank)
+
+## References
+
+- `packages/ui/CHANGELOG.md` (vX.Y.Z)
+- Related rule: `.cursor/rules/<rule>.mdc`
+- Related blueprint: `apps/web/docs/blueprints/<blueprint>.md`

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

@@ -1,7 +1,7 @@
 # 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-secondary-panel-bg` + `[data-slot="secondary-panel"]` rule in `globals.css`.  
+> **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)
@@ -24,16 +24,14 @@
 ## OKLCH formulas (dark)
 
 ```css
---secondary-panel-bg: color-mix(in oklch, var(--background) 32%, var(--sidebar-accent) 68%);
+--secondary-panel-bg: color-mix(in oklch, var(--card) 32%, var(--brand-tint) 68%);
 ```
 
-**Do not** mix with light-mode **`--brand-tint`** in dark — product theme classes keep a light **`--brand-tint`** for logos/KPI glow; the secondary rail must use **`--sidebar-accent`** so the Library panel stays on-hue and dark.
-
 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-secondary-panel-bg` (token + `[data-slot="secondary-panel"][data-state="open"]` in `globals.css`), `border-sidebar-border` (not generic `ring-border` alone).
+- **`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.