@exxatdesignux/ui 0.5.10 → 0.5.12

package/template/docs/reference-implementations.md

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

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

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

package/template/docs/token-taxonomy.md

@@ -1,416 +0,0 @@
-# Exxat DS — Token Taxonomy
-
-**Status:** Authoritative · **Audience:** humans + AI agents · **Standard:** WCAG 2.1 AA
-**Machine-readable index:** [`packages/ui/tokens/hooks-index.json`](../../packages/ui/tokens/hooks-index.json) (generated)
-**Defining file (canonical):** [`packages/ui/src/globals.css`](../../packages/ui/src/globals.css). Consumer apps (`apps/web/app/globals.css`, the `create-exxat-app` starter at `packages/ui/template/app/globals.css`) are thin shells that `@import "@exxatdesignux/ui/globals.css"` and only declare their own `@source` directive. The dedicated `packages/ui/src/theme.css` file has been **retired** — see [`docs/migrations/0003-globals-css-canonical.md`](./migrations/0003-globals-css-canonical.md).
-
-This document formalizes the **naming, layering, and ownership** of every CSS
-custom property the design system ships. It is the answer to "what do I name a
-new token?" and "is there already a token for this?". If something here
-disagrees with the CSS, the CSS wins — and this file needs an edit.
-
----
-
-## 1. Layering — where a token lives
-
-Tokens are declared in **four** layers. Higher layers may consume lower ones;
-they MUST NOT redefine names from a higher layer with a different meaning.
-
-| Layer | File | Purpose | Edit when |
-|---|---|---|---|
-| **L0 — Exxat canonical** | `packages/ui/src/globals.css` `:root` (block tagged `Exxat L0 — canonical namespace`) | SLDS-style flat namespace (`--exxat-color-surface-1`, `--exxat-radius-2`, …). The **official** names the DS scales on. Today these are `var()` aliases of L1; the canonical OKLCH will move here over time. | New product surface tokens, broader brand picker, anything you would otherwise put under "L1 with an Exxat brand prefix" |
-| **L1 — shadcn semantic** | `packages/ui/src/globals.css` `:root`/`.dark` | OKLCH literals + back-compat vocabulary (`--background`, `--foreground`, `--brand-color`, …). Required for the upstream shadcn primitives in `components/ui/*`. **Frozen** — do not extend; new tokens go to L0. | Brand color changes, accessibility-driven contrast lifts, new chip/chart slot tied to shadcn names |
-| **L2 — Tailwind bridge** | `packages/ui/src/globals.css` `@theme inline` block | Maps primitives to `--color-*` and `--radius-*` so Tailwind v4 emits utility classes (`bg-brand`, `bg-surface-1`, `text-chip-3`, `rounded-2`, …) | Whenever an L0/L1 token needs a Tailwind utility class |
-| **L3 — Surface override** | Theme blocks (`.theme-one`, `.theme-prism`, `[data-contrast="high"]`, `[data-text-size]`) | Per-brand / per-mode rebindings of L1 names — never new names | New brand, new contrast mode, new density step |
-
-> **Rules:**
-> 1. A token is **introduced exactly once**. New product tokens land in **L0**.
-> 2. L1 (shadcn names) is **frozen** — keep working, do not extend.
-> 3. L2 bridges L0/L1 → Tailwind utilities, exactly once per name.
-> 4. L3 re-binds existing L1 OKLCH values per theme. L0 inherits via `var(L1)` automatically.
-
----
-
-## 2. Namespace map (all current prefixes)
-
-Every prefix below has a clear role. **New tokens MUST land in one of these
-prefixes** — if you cannot place a token, the design system is missing a
-prefix; propose one in a PR and document it here first.
-
-### 2.0 Exxat L0 — canonical namespace (`--exxat-*`)
-
-The **official** name layer. Mirrors the SLDS `--slds-g-*` pattern but flat
-(no `-g-` for "global" yet, since we have a single product namespace). Today
-these resolve to L1 via `var(...)` so every existing theme override flows
-through automatically. New components SHOULD prefer L0 names; the linter will
-not yet *force* this, but `apps/web/docs/migrations/0002-exxat-token-namespace.md`
-tracks the rollout.
-
-| Category | L0 token | Resolves to L1 |
-|---|---|---|
-| Surface | `--exxat-color-surface-1` … `-3` | `--background` / `--card` / `--popover` |
-| Surface | `--exxat-color-surface-muted` / `-accent` / `-secondary` / `-sidebar` / `-input` | `--muted` / `--accent` / `--secondary` / `--sidebar` / `--input-background` |
-| Ink | `--exxat-color-ink-1` / `-2` | `--foreground` / `--muted-foreground` |
-| Ink | `--exxat-color-ink-on-surface-2` / `-on-surface-3` | `--card-foreground` / `--popover-foreground` |
-| Ink | `--exxat-color-ink-on-brand` / `-on-primary` / `-on-secondary` / `-on-accent` / `-on-destructive` | foreground tokens |
-| Brand | `--exxat-color-brand-1` / `-2` / `-3` / `-deep` | `--brand-color` / `-dark` / `-light` / `-deep` |
-| Brand | `--exxat-color-brand-tint-1` / `-2` / `-3` | `--brand-tint` / `-subtle` / `-light` |
-| Action | `--exxat-color-action-primary` / `-secondary` / `-destructive` | `--primary` / `--secondary` / `--destructive` |
-| Border | `--exxat-color-border-1` / `-control-subtle` / `-control-1` / `-control-2` | `--border` ladder (see §6) |
-| Focus | `--exxat-color-focus-ring` | `--ring` |
-| Overlay | `--exxat-color-overlay` | `--overlay` |
-| Chart | `--exxat-color-chart-1` … `-5` | `--chart-1` … `-5` |
-| Chip | `--exxat-color-chip-1` … `-5` / `-destructive` | `--chip-1` … `-5` / `-destructive` |
-| Radius | `--exxat-radius-1` … `-6` | `4px` / `8px` / `12px` / `16px` / `20px` / `24px` |
-| Spacing | `--exxat-spacing-1` / `-2` / `-3` / `-4` / `-5` / `-6` / `-8` / `-12` | Tailwind base scale |
-| Control | `--exxat-control-height-1` / `-2` / `-3` | `--control-height-sm` / `-` / `-touch` |
-
-**Tailwind utilities** are emitted via L2 bridges in `@theme inline`:
-
-| L0 token | Tailwind utility |
-|---|---|
-| `--exxat-color-surface-1` | `bg-surface-1`, `text-surface-1`, `border-surface-1`, … |
-| `--exxat-color-ink-1` / `-2` | `text-ink-1`, `text-ink-2` |
-| `--exxat-color-brand-1` … `-3` | `bg-brand-1`, `bg-brand-2`, `bg-brand-3` |
-| `--exxat-color-brand-tint-1` … `-3` | `bg-brand-tint-1`, … |
-| `--exxat-color-border-1` | `border-1` |
-| `--exxat-color-focus-ring` | `ring-focus-ring` |
-| `--exxat-radius-1` … `-6` | `rounded-1` … `rounded-6` |
-
-> The existing `bg-background`, `bg-brand`, `rounded-md`, etc. are not going
-> away — they alias to the same OKLCH. Both forms work side-by-side; **new code**
-> should reach for the L0 form for clarity and grep-ability (`grep --exxat-`
-> finds every product token without false positives from shadcn names).
-
-### 2.1 Semantic surface (shadcn core, L1 — frozen)
-
-Inherited from shadcn / Radix and treated as the **stable** semantic vocabulary
-across every shadcn component. Do not rename — downstream `components/ui/*`
-expects these.
-
-| Token | Role |
-|---|---|
-| `--background` / `--foreground` | Page canvas + ink |
-| `--card` / `--card-foreground` | Raised card surfaces |
-| `--popover` / `--popover-foreground` | Floating menus, tooltips, dropdowns |
-| `--primary` / `--primary-foreground` | Default CTA color (neutral charcoal, **not** brand — see §3) |
-| `--secondary` / `--secondary-foreground` | Secondary button + de-emphasized surface |
-| `--muted` / `--muted-foreground` | Muted body copy, subtle backgrounds |
-| `--accent` / `--accent-foreground` | Hovered list rows, low-contrast chips |
-| `--destructive` / `--destructive-foreground` | Errors, delete confirms |
-| `--border` | Decorative dividers (no AA requirement) |
-| `--border-control` / `--border-control-3` / `--border-control-35` / `--control-border` | Form-field borders — see §6 for the contrast ladder |
-| `--input` / `--input-background` | Input outline + fill |
-| `--ring` | Focus ring (≥ 3:1, SC 2.4.11) |
-| `--overlay` | Modal / sheet / drawer scrim |
-
-### 2.2 Brand (`--brand-*`)
-
-The **product accent** — different from `--primary` (which is neutral). Exxat
-ships **two** brand themes (Exxat One = lavender 286.1, Exxat Prism = rose 343)
-plus user-picked custom brand.
-
-| Token | Role |
-|---|---|
-| `--brand-color` | Solid brand fill (used on chips, links, charts when product) |
-| `--brand-color-light` / `--brand-color-dark` / `--brand-color-deep` | Brand scale (light / dark / deepest) |
-| `--brand-foreground` | Ink on a solid brand fill |
-| `--brand-tint` / `--brand-tint-light` / `--brand-tint-subtle` | Wash surfaces (sidebar, secondary panel) |
-| `--brand-preview-one` / `--brand-preview-prism` | Fixed swatches for the brand picker — **never change with the active theme** |
-
-### 2.3 Sidebar + secondary panel (`--sidebar-*`, `--secondary-panel-bg`)
-
-Three-level brand chrome stack. See `docs/shell-surface-elevation-pattern.md`.
-
-| Token | Role |
-|---|---|
-| `--sidebar` / `--sidebar-foreground` | Primary sidebar (= `--brand-tint` on product themes) |
-| `--sidebar-primary` / `--sidebar-primary-foreground` | Solid pill / active hint on sidebar |
-| `--sidebar-accent` / `--sidebar-accent-foreground` | Hovered/active row in sidebar |
-| `--sidebar-border` | Inner divider |
-| `--sidebar-ring` | Focus ring inside sidebar |
-| `--sidebar-section-label-foreground` | Section title — mixed against real `--sidebar`, not `--background` |
-| `--secondary-panel-bg` | Nested panel (Library) — level 1 between sidebar and canvas |
-
-### 2.4 Chips / badges (`--chip-*`)
-
-A five-slot **AA-compliant** palette for tags, kanban badges, and small status
-chips. All slots maintain ≥ 4.5:1 against `--background`.
-
-| Token | Hue (light) |
-|---|---|
-| `--chip-1` | indigo (264) |
-| `--chip-2` | teal (184) |
-| `--chip-3` | slate (227) |
-| `--chip-4` | amber (84) |
-| `--chip-5` | orange (70) |
-| `--chip-destructive` | red (25) |
-
-Use through `lib/list-status-badges.ts` (`LIST_HUB_STATUS_TINT_*`). Do not pick a
-chip slot to mean "this entity uses indigo" — pick by **semantic intent**
-(success / warning / neutral / danger / info).
-
-### 2.5 Charts (`--chart-*`)
-
-Five slots scoped for `recharts` series. They are **darker** than chip slots
-because chart areas are larger and need denser pigment.
-
-| Token | Hue |
-|---|---|
-| `--chart-1` | blue (264) |
-| `--chart-2` | green-teal (184) |
-| `--chart-3` | slate (227) |
-| `--chart-4` | amber (84) |
-| `--chart-5` | orange (70) |
-
-Insights derived from charts use `--insight-severity-*-bg` / `-fg` (KPI strip).
-
-### 2.6 Interactive hover (`--interactive-hover-*`)
-
-Single source for ghost-button hover, list-row hover, table chrome hover.
-Replaces ad-hoc `hover:bg-muted` so theming + dark mode flip together.
-
-| Token | Role |
-|---|---|
-| `--interactive-hover` | Default opaque hover fill |
-| `--interactive-hover-foreground` | Ink on hover |
-| `--interactive-hover-subtle` / `-soft` / `-medium` / `-strong` | Opacity ladder (50 / 40 / 60 / 70 mix) |
-| `--interactive-hover-row` | List/table row hover (accent-mixed) |
-
-### 2.7 DataTable (`--dt-*`)
-
-Pinned cells must be **opaque** so they sit above scrolled rows. These tokens
-exist because `var(--muted)` alone gives translucent surfaces in dark mode.
-
-| Token | Role |
-|---|---|
-| `--dt-row-bg` | Base row fill (opaque) |
-| `--dt-row-hover` | Hovered row |
-| `--dt-row-selected` / `--dt-row-selected-fg` | Selection state |
-| `--dt-header-bg` | Header row |
-| `--dt-group-bg` | Group / divider row |
-| `--dt-new-row-bg` / `--dt-new-row-border` | "Just created" highlight |
-
-### 2.8 KPI strip (`--key-metrics-*`, `--insight-severity-*`)
-
-Used by `KeyMetrics` (both `variant="flat"` and `variant="card"`). See
-`docs/kpi-flat-band-pattern.md`.
-
-| Token | Role |
-|---|---|
-| `--key-metrics-flat-cell-bg` | Transparent on `variant="flat"` |
-| `--key-metrics-flat-divider` | Cell-border hairline |
-| `--key-metrics-flat-band-radial` | OKLCH brand glow at bottom |
-| `--key-metrics-flat-band-shadow` | `none` on flat |
-| `--key-metrics-card-glow-radial` | Card-variant glow |
-| `--insight-severity-warning-bg` / `-fg` | Yellow severity (chart-4 mix) |
-| `--insight-severity-info-bg` / `-fg` | Blue severity (chart-1 mix) |
-
-### 2.9 Conditional formatting (`--conditional-rule-*`)
-
-Row backgrounds for table conditional-format rules. Already six slots — adding
-more requires expanding the rule type in `lib/table-conditional-format.ts`.
-
-### 2.10 Icon discs (`--icon-disc-*`)
-
-Soft tinted backgrounds for icon "discs" (KPI cards, banner avatars).
-Bg ≈ 14% mix, fg from `--chip-*` / `--brand-color-dark`.
-
-### 2.11 Avatar (`--avatar-initials-*`)
-
-Bg + fg for initials avatars in `DataTable` cells. Pair brand wash with deep
-brand ink for ≥ 4.5:1 on white rows.
-
-### 2.12 Leo (Ask Leo) (`--leo-*`)
-
-| Token | Role |
-|---|---|
-| `--leo-surface-tint-a` / `-b` | Top / bottom of the AI panel wash |
-| `--leo-surface-gradient` | Full linear wash |
-
-### 2.13 Layout + density (`--header-height`, `--control-*`, `--table-row-height`, `--scaling`)
-
-Sized in **px** so JS can `parseFloat` them. Multiply by `--scaling` for future
-density modes.
-
-### 2.14 Border radius (`--radius`, `--radius-sm`/`-md`/`-lg`/`-xl`/`-2xl`/`-3xl`)
-
-`--radius` is the **base** (8px). The named scale lives at L2 (`@theme inline`)
-so Tailwind emits `rounded-sm`, `rounded-md`, etc.
-
-### 2.15 Shadows + transitions (`--shadow-*`, `--transition-*`)
-
-| Token | Role |
-|---|---|
-| `--shadow-sm` / `-md` / `-lg` | Three-step elevation |
-| `--transition-fast` / `-normal` / `-colors` | Standard durations |
-| `--sticky-edge-fade` | Edge-of-pinned-column gradient |
-
-### 2.16 Promo / banner (`--banner-prism-bg`)
-
-Rose hue 343, used **universally** as the Exxat Prism promo highlight — does
-not flip with the active theme.
-
-### 2.17 OS chrome (`--theme-color-chrome`)
-
-Mirrored into `<meta name="theme-color">` so the browser titlebar matches the
-sidebar. Hex literal here is **intentional** — it is consumed by the browser
-parser, not CSS.
-
----
-
-## 3. Color identity rules
-
-1. **`--primary` is neutral**, not brand. The product accent is `--brand-color`.
-   This matches Exxat's design language (neutral charcoal CTAs, lavender/rose
-   reserved for surfaces and chips). When a button **must** carry the brand,
-   use `bg-brand-color text-brand-foreground` — not `bg-primary`.
-2. **Brand washes (`--brand-tint*`) are surfaces; brand colors
-   (`--brand-color*`) are ink/fills.** Mixing the roles produces low-contrast
-   chips and washed-out sidebars.
-3. **Chip ≠ chart.** Chip tokens are sized for inline chips; chart tokens are
-   sized for filled SVG areas. Re-use a chip color on a chart fill (or vice
-   versa) only when the design explicitly calls for it.
-4. **Every theme MUST keep `--brand-preview-one` and `--brand-preview-prism`
-   fixed.** They drive the brand picker swatch — flipping them with the
-   selected theme defeats the picker.
-
----
-
-## 4. Naming a new token — checklist
-
-Run this list **before** opening `globals.css`:
-
-- [ ] **Does an L0 alias already exist?** (`--exxat-color-surface-1`,
-      `--exxat-color-brand-1`, `--exxat-radius-2`, …) — prefer L0 for new
-      consumers; the L1 shadcn name is the back-compat alias.
-- [ ] If the token is new, **name it at L0 first** (`--exxat-<category>-<slot>`).
-      Add an L1 mirror **only** if a shadcn primitive in `components/ui/*`
-      needs it — that's the only place L1 is still required.
-- [ ] Can it be expressed with an existing semantic token? (`--exxat-color-surface-muted`
-      instead of `--exxat-color-surface-4`, `--brand-color-dark` instead of
-      `--brand-deeper`)
-- [ ] Does it belong to a **scoped surface** (`KeyMetrics`, `DataTable`, Leo,
-      sidebar, secondary panel)? If yes, **prefix with that surface**, e.g.
-      `--key-metrics-*`, `--dt-*`, `--leo-*`. Do **not** drop scoped tokens at
-      the top level.
-- [ ] Is it a **decoration** or a **decision**? Decorations (gradients, fades,
-      shadows) live alongside the surface tokens they decorate. Decisions
-      (semantic intent: warning, info, success) live with chips / charts /
-      insight tokens.
-- [ ] Does it need a Tailwind utility (`bg-*`, `text-*`, `border-*`)? If yes,
-      add the `--color-<name>` bridge in `@theme inline` in **both** globals
-      files.
-- [ ] Does dark mode / high contrast / Prism need different OKLCH? Override at
-      L3 — never branch by emitting a new token name.
-- [ ] Is it derived (e.g. 14% mix of `--brand-color`)? Use `color-mix(in oklch,
-      …)` so theme overrides cascade automatically.
-- [ ] Add the bridge in `packages/ui/src/globals.css` `@theme inline`. App
-      consumers @import that file, so a single edit is enough — no manual
-      mirroring across `apps/web/app/globals.css` / `template/app/globals.css`.
-
-If you tick all the boxes, also:
-
-1. Add an entry to this file (the right §).
-2. Re-run `pnpm --filter @exxatdesignux/ui tokens:index` (see §7) to refresh
-   `packages/ui/tokens/hooks-index.json`.
-
----
-
-## 5. Deprecation policy
-
-Tokens follow the same **add → mark deprecated → remove** lifecycle as code:
-
-1. **Add** the new token; switch components to consume it.
-2. **Mark deprecated** in `packages/ui/src/globals.css` with a comment:
-   ```css
-   /* @deprecated v0.2.18 — use --brand-color-dark; remove in v0.4.0 */
-   --brand-deep: var(--brand-color-dark);
-   ```
-3. **Migrate** consumers (script + grep + manual review). Document in
-   `docs/migrations/<NNNN>-<slug>.md`.
-4. **Remove** in the version named in the deprecation comment. Bump
-   `@exxatdesignux/ui` major or document in `CHANGELOG.md`.
-
-Active deprecations are listed in `docs/migrations/README.md`.
-
----
-
-## 6. Form-field border contrast ladder
-
-Form-field borders are a recurring source of WCAG SC 1.4.11 (3:1 UI contrast)
-failures. Use the right rung — do not guess:
-
-| Token | OKLCH L | Contrast vs `oklch(1 0 0)` | When to use |
-|---|---|---|---|
-| `--border` | 0.92 | < 3:1 | **Decorative only** — card dividers, list separators |
-| `--border-control` | 0.82 | < 3:1 | Layout chrome where contrast is not required |
-| `--border-control-3` | 0.62 | ≈ 3:1 | Form-field border **minimum** — passes AA |
-| `--border-control-35` | 0.25 | > 3.5:1 | Form-field border **recommended** — passes AA + 16% buffer |
-| `--control-border` (alias of `--border-control-3`) | — | — | Default form-field border slot |
-
-If you find yourself reaching for `--border` on an `<input>`, stop — use
-`--control-border`.
-
----
-
-## 7. Machine-readable hooks index
-
-Tooling (linters, codegens, design-tool sync) needs to discover tokens
-programmatically. Run:
-
-```bash
-pnpm --filter @exxatdesignux/ui tokens:index
-```
-
-This regenerates [`packages/ui/tokens/hooks-index.json`](../../packages/ui/tokens/hooks-index.json),
-which mirrors SLDS's `hooks-index.json` shape. The current index contains
-**195 tokens** across **41 namespaces** (including the 12 Exxat L0 sub-namespaces
-`exxat-surface`, `exxat-ink`, `exxat-brand`, `exxat-action`, `exxat-border`,
-`exxat-focus`, `exxat-overlay`, `exxat-chart`, `exxat-chip`, `exxat-radius`,
-`exxat-spacing`, `exxat-control`):
-
-```jsonc
-{
-  "version": "0.2.18",
-  "source": "packages/ui/src/globals.css",
-  "generatedAt": "ISO-8601",
-  "tokens": {
-    "--exxat-color-brand-1": {
-      "namespace": "exxat-brand",
-      "category": "color",
-      "values": { "light": "var(--brand-color)" },
-      "tailwindUtilities": ["bg-brand-1", "text-brand-1", "border-brand-1", "ring-brand-1"],
-      "deprecated": false
-    },
-    "--brand-color": {
-      "namespace": "brand",
-      "category": "color",
-      "values": {
-        "light":           "oklch(0.50 0.14 286.1)",
-        "dark":            "oklch(0.50 0.14 286.1)",
-        "theme-one":       "oklch(0.50 0.14 286.1)",
-        "theme-prism":     "oklch(0.57 0.24 342)",
-        "high-contrast":   "oklch(0.06 0 0)"
-      },
-      "tailwindUtilities": ["bg-brand", "text-brand", "border-brand", "ring-brand"],
-      "deprecated": false
-    }
-  }
-}
-```
-
-CI runs `tokens:index` and fails if the committed JSON is stale.
-
----
-
-## 8. References
-
-- `packages/ui/src/globals.css` — **single source of truth** for L1 / L2 / L3 primitives + Tailwind bridges
-- `apps/web/app/globals.css`, `packages/ui/template/app/globals.css` — thin shells (`@import` + `@source`)
-- `apps/web/docs/shell-surface-elevation-pattern.md` — sidebar / secondary panel
-- `apps/web/docs/kpi-flat-band-pattern.md` — `--key-metrics-flat-*`
-- `apps/web/docs/kpi-trend-pattern.md` — `--insight-severity-*` polarity
-- `.cursor/rules/exxat-token-discipline.mdc` — enforcement rule (don't ship hex
-  literals, don't use deprecated tokens)
-- `docs/migrations/` — token rename + removal history