@exxatdesignux/ui 0.5.11 → 0.5.13

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>

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

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

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

@@ -1,64 +0,0 @@
-# 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 / Library)
-
-## 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/modern-saas-patterns.md

@@ -1,165 +0,0 @@
-# Modern SaaS patterns — the canon Exxat DS works against
-
-> **Audience:** humans + AI agents.
-> **Companion to:** [`exxat-senior-ux/SKILL.md`](../../../.cursor/skills/exxat-senior-ux/SKILL.md),
-> [`exxat-ux-principles.mdc`](../../../.cursor/rules/exxat-ux-principles.mdc),
-> [`jobs/`](./jobs/).
-
-A senior designer recognizes the work. This doc names the patterns the best
-products converged on in 2024–2026, so the agent can pattern-match instead
-of inventing. **Cite by name + code** when you reference one in a design brief
-(e.g. `Linear issue detail (M1, M4, M7)`).
-
-## Canon products — cite by product, not by URL
-
-| Product | What to learn from it |
-|---------|-----------------------|
-| **Linear** | Issue detail, command palette spine, density, keyboard-first, presence, "less chrome" |
-| **Notion** | Inline editing, property panels, page-as-database, blocks, slash-commands |
-| **Stripe Dashboard** | Record home, status chips, activity log, money-grade precision |
-| **Figma** | Multiplayer, presence, side panel inspector, infinite-canvas chrome discipline |
-| **Vercel** | Type-first hierarchy, dark-first, minimal chrome, log streams |
-| **Height** | View tabs (table/board/timeline), custom fields, view parity |
-| **Plain / Pylon** | Support detail = identity + timeline + actions; conversation-as-document |
-| **Cron / Amie** | Keyboard-only flows, dense calendar, command surface |
-| **Raycast** | Command palette as full app, extension surface, deep keyboard |
-| **Arc Browser** | Control-stripped, content-first, sidebar as the only chrome |
-
-## The 12 patterns that make products feel modern
-
-### M1. Content-first chrome
-The data is the star. Sidebars collapse to icons. Headers stay 48–56px. Page
-surfaces are generous. No purple gradient on the top bar.
-
-- **In DS:** `SiteHeader` ~h-12; `PrimaryPageTemplate` body has generous
-  `max-w-[1440px]`; sidebar collapsible (`SidebarTrigger`).
-
-### M2. Command palette as the spine
-`⌘K` opens search + navigation + AI + recent. It is the primary navigation
-for power users. The sidebar exists for orientation, not speed.
-
-- **In DS:** `CommandMenu` (⌘K) + Ask Leo split (⌘⌥K).
-  Rule: `exxat-command-menu.mdc`.
-
-### M3. Side-panel detail over modal dialog
-For non-destructive context-keeping actions (properties, export, invite,
-preview, single-step compose), use a slide-in sheet — never a centered modal.
-
-- **In DS:** `Sheet` (no Vaul).
-  Rule: `exxat-drawer-vs-dialog.mdc`. Pattern:
-  `apps/web/docs/drawer-vs-dialog-pattern.md`.
-
-### M4. Status as a first-class citizen
-Colored dots, chips, counts visible everywhere data appears. Status isn't
-hidden in a detail page; it appears on rows, cards, headers, navigation.
-
-- **In DS:** `ListHubStatusBadge` + `lib/list-status-badges.ts`. Available per
-  row, board card, detail header, breadcrumb count slot.
-
-### M5. Inline editing where data is read
-Click the value, edit it. No bounce to forms for single-field changes.
-
-- **In DS:** Inline-edit primitive emerging; until then, use a `Sheet` for
-  multi-field, popover or contenteditable for single-field. Principle: P15.
-
-### M6. Optimistic UI + undo
-Low-risk actions (favorite, archive, status flip) feel instant; reconcile on
-error. Undo via banner or in-place affordance — **never** toast
-(`exxat-no-toast.mdc`).
-
-- **In DS:** Optimistic state in `useTableState` selection ops; undo via
-  `LocalBanner` with action.
-
-### M7. Activity timeline on every record
-Who did what when. The audit log is also a navigation device.
-
-- **In DS:** `ActivityTimeline` primitive emerging. Compose from
-  `lib/mock/activity` shape until then.
-
-### M8. Empty states with one CTA + one sentence
-Illustration optional. One sentence of context. One primary action. Never a
-wall of help text or a tutorial inline.
-
-- **In DS:** `EmptyState` primitive; voice from `docs/voice-and-tone.md`.
-
-### M9. Skeleton, not spinner
-Loading shapes content. Spinners only for indeterminate < 200ms.
-
-- **In DS:** `Skeleton` primitive; suspense boundaries shape the body.
-
-### M10. Type-first hierarchy
-Weight, size, color do the heavy lifting before borders, boxes, or tints.
-Ornament is rare and intentional.
-
-- **In DS:** Token scale; body in `Inter`; display in `Ivy Presto` (only on
-  `PageHeader` H1 by default).
-
-### M11. Real-time presence + collaboration as default
-If the product is shared, show who else is here — face rails, cursors,
-status. Inviting others is one click from the page.
-
-- **In DS:** `PageHeader variant="collaboration"` face rail +
-  `InviteCollaboratorsDrawer`.
-  Rule: `exxat-collaboration-access.mdc`.
-
-### M12. AI as opt-in sidecar
-Ask Leo style — never the primary path, never auto-runs on a record, always
-discoverable, always cancellable. Deterministic path still exists.
-
-- **In DS:** `AskLeoSidebar` + `⌘⌥K` toggle; never a "magic" button on a
-  destructive surface.
-
----
-
-## The anti-modern signals (what NOT to do)
-
-| Signal | Why it's dated |
-|--------|----------------|
-| Toasts everywhere | Modern products use inline + banner + undo. Toasts get missed. |
-| Full-width tab bars stretched edge-to-edge | 2010s pattern. Modern uses `w-fit` segmented controls. |
-| Centered modals for everything | Sheets and routes carry more without breaking flow. |
-| Color-coded sidebar sections | Modern is monochrome chrome + status color on data. |
-| Modal wizards with progress bar | If it has > 3 steps, give it a route. |
-| Spinners on initial load | Skeleton the content shape instead. |
-| Hover-only affordances | Touch + keyboard need parity. |
-| Icons without text labels in primary nav | Recognition fails for new users. |
-| "Beautiful" gradients on chrome | Data should be beautiful; chrome should disappear. |
-| Aggressive empty-state illustrations | One sentence + one action beats illustration + 5 tips. |
-| Edit-takes-you-to-a-form for single fields | Inline edit (M5). |
-| "Back to <parent>" button alongside breadcrumb | P1 — choose one. |
-| Auto-running AI on record open | M12 — opt-in only. |
-
----
-
-## Density layers (Linear / Vercel model)
-
-| Layer | When |
-|-------|------|
-| **Cozy** (default) | Most surfaces; balances scan + breathing room |
-| **Compact** | Power users on daily workflow; tables, command results |
-| **Comfortable** | Accessibility (low-vision, motor); marketing-adjacent |
-
-Provide a user-level setting where audiences differ; default to **cozy**.
-Don't fork stacks per density.
-
----
-
-## How to use this doc in a design brief
-
-```
-Reference (modern): Linear issue detail (M1, M4, M7),
-                    Stripe customer record (M4, M11)
-```
-
-Cite the **patterns (Mx)** the agent applied, not just the product. Forces
-clear thinking and lets reviewers verify intent.
-
-## See also
-
-- [`../../../.cursor/skills/exxat-senior-ux/SKILL.md`](../../../.cursor/skills/exxat-senior-ux/SKILL.md) — persona
-- [`../../../.cursor/rules/exxat-ux-discovery-protocol.mdc`](../../../.cursor/rules/exxat-ux-discovery-protocol.mdc) — brief gate
-- [`../../../.cursor/rules/exxat-ux-principles.mdc`](../../../.cursor/rules/exxat-ux-principles.mdc) — principles + breaks
-- [`./jobs/`](./jobs/) — canonical reference per job type
-- [`./component-selection-guide.md`](./component-selection-guide.md) — picking the composition
-- [`./blueprints/`](./blueprints/) — framework-agnostic surface specs
-- [`./voice-and-tone.md`](./voice-and-tone.md) — copy rules