@exxatdesignux/ui 0.5.3 → 0.5.5

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.5.5
+
+### Patch Changes
+
+- **New consumer agent rules (vendored via `sync-extras`):** `exxat-no-image-pixel-copy` (uploaded screenshots = IA only — never pixel-copy colors/chrome), `exxat-sidebar-shell` (DS `AppSidebar` chrome; no legacy rainbow nav styling).
+- **`exxat-ds-agents` §33–§34**, **`exxat-reuse-before-custom`**, **`exxat-token-economy` Q9** — image discipline + sidebar guardrails wired into pre-flight.
+- **`consumer-upgrade-checklist.md`** and **`reference-implementations.md`** — audit rows for screenshot copying and legacy sidebar anti-patterns.
+
+## 0.5.4
+
+### Patch Changes
+
+- **Remove Vaul `Drawer` primitive** — side panels use **`Sheet`** only (`ExportDrawer`, `TablePropertiesDrawer`, invite/folder sheets). **`vaul`** dropped from package dependencies; consumers should remove it from their app and delete any `components/ui/drawer.tsx` shim.
+- **New consumer agent rules (vendored via `sync-extras`):** `exxat-no-vaul`, `exxat-tabs-chrome` (no full-width tab stretch), `exxat-page-header-actions`, `exxat-table-row-preview` (HoverCard + DS cells).
+- **`consumer-upgrade-checklist.md`** — Prism-style audit table (tabs, header buttons, popovers, hub views).
+- **Docs:** sheet-panel vs dialog pattern; landing page start-fresh three-step commands at `@0.5.3+`.
+
 ## 0.5.3
 
 ### Patch Changes

package/README.md

@@ -89,7 +89,7 @@ code are never touched.
 ## What's inside
 
 - **Primitives** (`@exxatdesignux/ui/components/<name>`) — Button, Input,
-  Select, Dialog, AlertDialog, Sheet, Drawer, Popover, DropdownMenu,
+  Select, Dialog, AlertDialog, Sheet, Popover, DropdownMenu,
   ContextMenu, Tabs, Accordion, Tooltip, Toast-free Banner, ScrollArea,
   Slider, HoverCard, Avatar, Badge, StatusBadge, Calendar, Kbd, …
 - **Hub stack** — `DataTable<TRow>`, `useTableState<TRow>`,

package/consumer-extras/cursor-rules/exxat-accessibility.mdc

@@ -17,7 +17,7 @@ alwaysApply: true
 4. **Touch targets (2.5.8):** interactive controls **≥ 24×24 CSS px** or **24px** spacing so hit areas do not overlap — use **`min-h-6 min-w-6` / `size-6`** for icon-only targets; avoid **`size-4`** as the sole target.
 5. **Contrast:** normal text **≥ 4.5:1**; UI components / focus where required **≥ 3:1**; muted text on tinted surfaces use tokens against the correct surface (e.g. sidebar), not only `--background`.
 6. **Minimum text size:** visible product copy **≥ 11px** — use **`text-xs`** or larger; **MUST NOT** use arbitrary Tailwind font sizes below that (see **`apps/web/AGENTS.md` §8.3**, **`apps/web/app/globals.css`** `--text-xs`).
-7. **Dialogs / sheets / drawers:** must expose a **Title** (`DialogTitle` / `SheetTitle` / `DrawerTitle`); use **`sr-only`** if visually hidden (shadcn pattern).
+7. **Dialogs / sheets:** must expose a **Title** (`DialogTitle` / `SheetTitle`); use **`sr-only`** if visually hidden (shadcn pattern).
 8. **Format hints are persistent, not placeholders (SC 3.3.2 Labels or Instructions, 1.3.1).** Any field that expects a specific format — **date, time, phone, currency, ID pattern, GPA scale, URL, hours, unit-bearing numbers** — MUST show the format as **persistent helper text** via **`FormDescription`** (or the field's description slot). Placeholders disappear on focus and are unreliable for AT, so **MUST NOT** be the sole carrier of the format. Example: GPA → "Out of 4.0"; Date → "MM/DD/YYYY"; Phone → "+1 (555) 555-0100"; Student ID → "STU-YYYY-####". Pair with `inputMode`, `pattern`, or a picker primitive (e.g. `DatePickerField`) where applicable; never rely on a free-text date input.
 9. **Every icon that communicates information MUST have a text alternative** — not just icon-only buttons. Three cases (SC 1.1.1 Non-text Content, 3.3.2 Labels or Instructions, 2.4.6 Headings and Labels):
 

package/consumer-extras/cursor-rules/exxat-drawer-vs-dialog.mdc

@@ -7,16 +7,16 @@ alwaysApply: true
 
 ## MUST
 
-1. **Drawer / sheet** — Hub-**adjacent** work where **parent context** (list, filters, selection) stays relevant: properties, export, invites, long option lists beside the grid.
+1. **Sheet panel** — Hub-**adjacent** work where **parent context** (list, filters, selection) stays relevant: properties, export, invites, long option lists beside the grid. Use **`Sheet`** (`showOverlay={false}`, floating inset) — **MUST NOT** add a Vaul `Drawer` primitive.
 2. **Dialog** — **Blocking**, **short** focus: destructive confirm, legal/acknowledgment, single-step choice, alert when the user must not interact with the page behind until resolved.
 3. **Route** — **Primary**, **long**, or **bookmarkable** flows — **`AGENTS.md` §6.4**, **`.cursor/rules/exxat-page-vs-drawer.mdc`**.
 
 ## MUST NOT
 
-- Put **irreversible delete** only in a dismissible toast — use **dialog** (or drawer with explicit confirm) per **`exxat-no-toast.mdc`**.
-- Use a **centered dialog** for **wide tables of export columns** when a **drawer** matches mental model and space.
+- Put **irreversible delete** only in a dismissible toast — use **dialog** (or sheet with explicit confirm) per **`exxat-no-toast.mdc`**.
+- Use a **centered dialog** for **wide tables of export columns** when a **sheet panel** matches mental model and space.
 
 ## See also
 
 - **`docs/drawer-vs-dialog-pattern.md`** · **`.cursor/skills/exxat-drawer-vs-dialog/SKILL.md`**
-- **`exxat-page-vs-drawer.mdc`** (drawer vs **route**)
+- **`exxat-page-vs-drawer.mdc`** (sheet vs **route**)

package/consumer-extras/cursor-rules/exxat-ds-agents.mdc

@@ -41,6 +41,12 @@ Before implementing or reviewing **list / table / board / dashboard / data-heavy
 26. **Blueprints + selection guide** — **`apps/web/docs/blueprints/`** + **`apps/web/docs/component-selection-guide.md`** — framework-agnostic specs + decision tree across the whole DS. Start there before composing a new hub.
 27. **Migrations** — **`apps/web/docs/migrations/`** — every deprecation gets a numbered entry (`NNNN-<slug>.md`). Token deprecations surface in `tokens/hooks-index.json` as `deprecated: true` and are lint-flagged.
 28. **Hub supported views (Add view parity)** — **`exxat-hub-supported-views.mdc`** + **`docs/exxat-ds/patterns/hub-supported-views-pattern.md`** — **`FULL_HUB_SUPPORTED_VIEWS`** (seven views, same as Library); sync **`ListPageTemplate`** + **`HubTable`**; real renderers per view; **`LibraryTable`** for **`LibraryItem`** catalogs; **`tokens-hub-auxiliary-views.tsx`** for tokens.
+29. **No Vaul** — **`exxat-no-vaul.mdc`** — side panels = **`Sheet`** only; remove **`vaul`** from consumer apps on **`@exxatdesignux/ui@0.5.3+`**.
+30. **Tabs chrome** — **`exxat-tabs-chrome.mdc`** — hub views = **`ListPageTemplate`** toolbar (`w-max`); record tabs = **`TabsList`** `w-fit`, never full-width stretch.
+31. **Page header actions** — **`exxat-page-header-actions.mdc`** — filled primary + outline overflow; no hand-built grey buttons.
+32. **Table row preview** — **`exxat-table-row-preview.mdc`** — **`HoverCard`** + DS badges/cells; no bespoke popover cards.
+33. **Sidebar shell** — **`exxat-sidebar-shell.mdc`** + **`AGENTS.md` §9.1** — legacy screenshots = **IA only**; **MUST NOT** copy rainbow section styling or fork **`app-sidebar.tsx`**.
+34. **Uploaded images** — **`exxat-no-image-pixel-copy.mdc`** — screenshots = intent/IA only; map to DS patterns; never pixel-copy.
 
 ## Also read
 
@@ -51,7 +57,7 @@ Before implementing or reviewing **list / table / board / dashboard / data-heavy
 - **`apps/web/docs/blueprints/`** — framework-agnostic specs (start: `page-header.md`, `data-table.md`).
 - **`apps/web/docs/migrations/`** — token rename + removal history.
 - **`packages/ui/tokens/hooks-index.json`** — machine-readable token index (regenerate via `pnpm --filter @exxatdesignux/ui tokens:index`).
-- `.cursor/rules/exxat-data-tables.mdc`, **`exxat-hub-supported-views.mdc`**, `exxat-list-page-connected-views.mdc`, **`exxat-centralized-list-dataset.mdc`**, **`exxat-list-page-view-shells.mdc`**, **`exxat-fontawesome-icons.mdc`**, **`exxat-mono-ids.mdc`**, **`exxat-primary-nav-secondary-panel.mdc`**, **`exxat-library-hub-header.mdc`**, **`exxat-collaboration-access.mdc`**, **`exxat-dedicated-search-surfaces.mdc`**, **`exxat-kpi-trends.mdc`**, **`exxat-kpi-flat-band.mdc`**, **`exxat-drawer-vs-dialog.mdc`**, **`exxat-card-vs-list-rows.mdc`**, **`exxat-kpi-max-four.mdc`**, **`exxat-reuse-before-custom.mdc`**, `exxat-table-properties-drawer.mdc`, **`exxat-board-cards.mdc`**, **`exxat-page-vs-drawer.mdc`**, **`exxat-no-toast.mdc`**, **`exxat-command-menu.mdc`**, `exxat-kbd-shortcuts.mdc`, `exxat-accessibility.mdc` at repo root; **`apps/web/.cursor/rules/exxat-dashboard-view-charts.mdc`** for Data tab charts.
+- `.cursor/rules/exxat-data-tables.mdc`, **`exxat-hub-supported-views.mdc`**, **`exxat-no-vaul.mdc`**, **`exxat-tabs-chrome.mdc`**, **`exxat-page-header-actions.mdc`**, **`exxat-table-row-preview.mdc`**, `exxat-list-page-connected-views.mdc`, **`exxat-centralized-list-dataset.mdc`**, **`exxat-list-page-view-shells.mdc`**, **`exxat-fontawesome-icons.mdc`**, **`exxat-mono-ids.mdc`**, **`exxat-primary-nav-secondary-panel.mdc`**, **`exxat-library-hub-header.mdc`**, **`exxat-collaboration-access.mdc`**, **`exxat-dedicated-search-surfaces.mdc`**, **`exxat-kpi-trends.mdc`**, **`exxat-kpi-flat-band.mdc`**, **`exxat-drawer-vs-dialog.mdc`**, **`exxat-card-vs-list-rows.mdc`**, **`exxat-kpi-max-four.mdc`**, **`exxat-reuse-before-custom.mdc`**, `exxat-table-properties-drawer.mdc`, **`exxat-board-cards.mdc`**, **`exxat-page-vs-drawer.mdc`**, **`exxat-no-toast.mdc`**, **`exxat-command-menu.mdc`**, `exxat-kbd-shortcuts.mdc`, `exxat-accessibility.mdc` at repo root; **`apps/web/.cursor/rules/exxat-dashboard-view-charts.mdc`** for Data tab charts.
 - **`apps/web/docs/kpi-flat-band-pattern.md`**, **`apps/web/docs/shell-surface-elevation-pattern.md`** — flat KPI strip + sidebar/secondary/page OKLCH stack.
 - **`apps/web/docs/library-hub-header-pattern.md`** — folder-scoped library header **Customize folder**.
 - **`apps/web/docs/collaboration-access-pattern.md`** — shared hub face rail + invite sheet.

package/consumer-extras/cursor-rules/exxat-no-image-pixel-copy.mdc

@@ -0,0 +1,35 @@
+---
+description: Uploaded screenshots/mockups are IA reference only — map to Exxat DS patterns; never pixel-copy
+alwaysApply: true
+---
+
+# Exxat DS — uploaded images are not the implementation spec
+
+When the user attaches a **screenshot**, **mockup**, **Figma export**, **legacy app capture**, or any **reference image**, treat it as **product intent** — **not** as code to transcribe.
+
+**Exxat DS rules, blueprints, and reference hubs always win** over what the image shows.
+
+## Allowed to take from an image (content / IA)
+
+- **Screen purpose**, **nav labels**, **routes**, **fields**, **columns**, **KPIs**, **actions**, **statuses**
+- **Icon suffix** (Font Awesome) — still use **`fa-light` / `fa-solid`** DS pairing
+- **Workflow intent** — export, invite, row → detail, etc.
+
+## MUST NOT copy from an image (visual / stack)
+
+- **Hex / RGB colors**, rainbow section text, custom sidebar washes, bespoke pills
+- **Shell forks** — sidebar, header, list toolbar, tabs that bypass DS components
+- **Bespoke widgets** when DS primitives exist — raw tables, custom popovers, Vaul, full-width tabs
+- **Pixel implementation “because it’s in the picture”** without citing a **DS pattern + reference hub**
+
+## REQUIRED workflow (before UI code)
+
+1. Classify via **`component-selection-guide`** + **`blueprints/`**
+2. Pick **`reference-implementations`** hub
+3. State mapping (screen → DS composition)
+4. Build with **`AGENTS.md`** + topic rules
+5. Image vs DS conflict → **DS wins**; ask one question only for true business gaps
+
+## See also
+
+- **`exxat-reuse-before-custom.mdc`**, **`exxat-sidebar-shell.mdc`**, **`exxat-token-economy`** §2

package/consumer-extras/cursor-rules/exxat-no-vaul.mdc

@@ -0,0 +1,25 @@
+---
+description: Exxat DS — no Vaul Drawer primitive; side panels use Sheet only
+alwaysApply: true
+---
+
+# Exxat DS — no Vaul
+
+## MUST
+
+- Side panels (export, properties, invite, folder create) use **`Sheet`** from `@exxatdesignux/ui/components/sheet` with the floating inset pattern (`showOverlay={false}`, `getFloatingSheetInsetProps`).
+- Product code names may end in `*Drawer` (`ExportDrawer`, `TablePropertiesDrawer`) — implementation is **`Sheet`**, not Vaul.
+
+## MUST NOT
+
+- Add **`vaul`** to `package.json` or import `@/components/ui/drawer` / Vaul `Drawer`.
+- Scaffold or extend the removed shadcn Vaul wrapper — it was deleted from `@exxatdesignux/ui@0.5.3+`.
+
+## Consumer apps
+
+After upgrading to **`@exxatdesignux/ui@0.5.3`**, remove **`vaul`** from the app `package.json`, delete any local `components/ui/drawer.tsx` re-export, and re-run **`exxat-ui sync-extras`**.
+
+## See also
+
+- **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**
+- **`docs/exxat-ds/patterns/drawer-vs-dialog-pattern.md`**

package/consumer-extras/cursor-rules/exxat-page-header-actions.mdc

@@ -0,0 +1,31 @@
+---
+description: Exxat DS — PageHeader actions slot; View as / overflow / primary CTA patterns
+alwaysApply: true
+---
+
+# Exxat DS — page header actions
+
+**Blueprint:** `docs/exxat-ds/handbook/HANDBOOK.md` + `node_modules/@exxatdesignux/ui/template/docs/blueprints/page-header.md`
+
+## Anatomy (actions slot only)
+
+| Control | DS pattern |
+|---------|------------|
+| **Primary CTA** | One **`Button`** `variant="default"` `size="lg"` (filled) — e.g. “Add student”, “Ask Leo” when it is the main action |
+| **Secondary / scope** (“View as”, “All students”) | **`Button variant="outline" size="lg"`** + chevron, or **`Select`** / **`DropdownMenu`** trigger styled as outline button — **not** plain grey rectangles or unstyled `<button>` |
+| **Overflow (⋯)** | **`Button variant="outline" size="icon-lg"`** (or `size="lg"` icon-only) opening **`DropdownMenu`** — Export, settings, invite |
+| **Collaboration** | **`PageHeader variant="collaboration"`** face rail — not a custom avatar row |
+
+## MUST
+
+- Compose **`PageHeader`** + pass **`actions`** as DS **`Button`** / **`DropdownMenu`** primitives.
+- Keep **one** filled primary; put Export and long-tail items under **⋯**.
+
+## MUST NOT
+
+- Hand-built header button rows that skip **`PageHeader`** and **`Button`** variants.
+- Multiple filled primaries beside each other (e.g. “Ask Leo” + “Add student” both solid black unless product explicitly documents hierarchy — prefer outline for secondary).
+
+## Reference
+
+- **`docs/exxat-ds/handbook/reference-implementations.md`**

package/consumer-extras/cursor-rules/exxat-reuse-before-custom.mdc

@@ -20,6 +20,8 @@ alwaysApply: true
 
 Do **not** silently ship a second stack for the same product pattern (e.g. another “table”, another metrics strip, another sidebar).
 
+When the user **uploads a screenshot or mockup**, read **`exxat-no-image-pixel-copy.mdc`** first — extract IA only; map to DS patterns; never pixel-copy colors or chrome.
+
 If the **user or task already explicitly** approved a greenfield component (“build a new X from scratch”), you may proceed without re-asking.
 
 ## MUST NOT

package/consumer-extras/cursor-rules/exxat-sidebar-shell.mdc

@@ -0,0 +1,35 @@
+---
+description: Application sidebar — DS shell only; legacy screenshots are IA reference, not visual spec
+globs: "**/app-sidebar.tsx,**/navigation*.tsx,**/lib/mock/navigation.tsx,**/lib/*-navigation.tsx"
+alwaysApply: false
+---
+
+# Exxat DS — application sidebar shell (MUST)
+
+Customer / legacy app **screenshots** may show **what links exist** — not **how the sidebar is styled**. Full policy: **`exxat-no-image-pixel-copy.mdc`**.
+
+## Screenshots are allowed to inform (content only)
+
+- Nav **labels**, **grouping**, **route paths**, **Font Awesome icon suffixes**
+- Whether a row needs **children**, a **secondary panel**, or a **badge**
+
+## Screenshots MUST NOT drive styling (MUST NOT)
+
+- **Per-section label colors** (magenta / teal / gold text on every row in a group)
+- **Custom active pills** (hand-built white `rounded-*` + shadow instead of `SidebarMenuButton` `data-active`)
+- **Non-token sidebar fills** (pink wash, `#hex` tints, inline `style={{ color: … }}`)
+- **Forking `app-sidebar.tsx` layout** for one product while rest of DS uses shared chrome
+- **Re-implementing `isNavActive`** in the app — use **`@exxatdesignux/ui/lib/nav-active`** (see **`exxat-nav-single-active.mdc`**)
+
+## MUST — DS sidebar chrome
+
+1. **Shell:** **`AppSidebar`** + **`SidebarMenuButton`** / **`SidebarGroup`** / **`SidebarGroupLabel`** from **`@exxatdesignux/ui`**. Reference: **`AGENTS.md` §9.1**, **`exxat-ds-skill` §3.1–§3.2**.
+2. **Typography:** Row labels **`text-sidebar-foreground`**. Section headings **`SidebarGroupLabel`** + **`text-sidebar-section-label`**.
+3. **Active state:** **`SidebarMenuButton` `isActive`** only — one active row in expanded rail; collapsible parent neutral when child active.
+4. **Icons:** **`fa-light`** / **`fa-solid`** on icons — do **not** recolor labels per module.
+5. **Nav data:** Extend **`lib/mock/navigation.tsx`** (or imported mock). **MUST NOT** paste legacy sidebar components from customer repos.
+6. **Consumer products:** Build in a **separate repo** with **`@exxatdesignux/ui`** — not DS monorepo sidebar forks.
+
+## Anti-pattern
+
+Legacy product sidebars with rainbow section text and bespoke selection chrome — **do not reproduce** on Exxat DS.

package/consumer-extras/cursor-rules/exxat-table-row-preview.mdc

@@ -0,0 +1,24 @@
+---
+description: Exxat DS — table row identity preview uses HoverCard + DS tokens, not bespoke Popover cards
+alwaysApply: false
+---
+
+# Exxat DS — table row preview (hover / click)
+
+When a **data table** cell opens a **rich preview** of a person or record (student, placement, team member):
+
+## MUST
+
+- Use **`HoverCard`** (`@/components/ui/hover-card`) for hover-driven previews, or **`Popover`** only when the preview is **click-pinned** and small.
+- Structure identity with **`AvatarInitials`**, name, **`font-mono tabular-nums`** on IDs only (**`exxat-mono-ids.mdc`**), **`ListHubStatusBadge`** + **`lib/list-status-badges.ts`** for status — **color + icon** (**`exxat-accessibility.mdc`** 1.4.1).
+- Reuse table cell patterns from **`@/components/data-views`** (`PeopleAvatarRailCell`, `PillCell`, progress cells) — see **`columns-showcase.tsx`**.
+
+## MUST NOT
+
+- Bespoke **`PopoverContent`** layouts with ad-hoc spacing, one-off progress bars, or status chips without the shared badge map.
+- Raw email as the only identifier when a display name exists (**`exxat-person-identity-display.mdc`**).
+
+## Reference
+
+- **`HoverCard`** docs in `packages/ui/src/components/ui/hover-card.tsx`
+- **`apps/web/docs/blueprints/data-table.md`**

package/consumer-extras/cursor-rules/exxat-tabs-chrome.mdc

@@ -0,0 +1,31 @@
+---
+description: Exxat DS — Tabs and view toolbars must not stretch full width; use ListPageTemplate for hub views
+alwaysApply: true
+---
+
+# Exxat DS — tabs chrome (no full-width stretch)
+
+## List hubs (All students, Placements, …)
+
+**MUST** use **`ListPageTemplate`** view toolbar — `role="toolbar"` + **`w-max`** segmented control (`viewSegmentedToolbarClass`), **not** Radix **`Tabs`** stretched across the page.
+
+- Reference: `packages/ui/src/components/templates/list-page.tsx` (views toolbar block).
+- **MUST NOT** build a custom full-width tab bar for “All students · 16” + Add view.
+
+## Entity / record detail (Overview, Academics, Placements, …)
+
+**MUST** use **`Tabs`**, **`TabsList`**, **`TabsTrigger`** from `@/components/ui/tabs`:
+
+- **`TabsList`** defaults to **`inline-flex w-fit`** — **MUST NOT** pass `className="w-full"` or wrap the list in a full-width flex container that forces triggers to **`flex-1`**.
+- Prefer **`variant="line"`** for record sub-nav under a **`PageHeader`** (`record-home` blueprint).
+- **`TabsTrigger`** may use `flex-1` only inside a **`w-fit`** list with a fixed number of tabs — never inside a bar that spans the content column.
+
+## MUST NOT
+
+- A single grey/white bar spanning the entire content width with tabs distributed edge-to-edge.
+- Mix hub **view tabs** (table/list/board) with entity **section tabs** (Overview/Academics) — different patterns.
+
+## See also
+
+- **`docs/exxat-ds/handbook/HANDBOOK.md`** — header never carries view tabs
+- **`docs/exxat-ds/patterns/data-views-pattern.md`** — `ListPageTemplate` view toolbar

package/consumer-extras/cursor-skills/exxat-drawer-vs-dialog/SKILL.md

@@ -1,6 +1,6 @@
 # Exxat DS — drawer vs dialog
 
-Use when choosing **Radix `Dialog` / `AlertDialog`** vs **`Sheet` / `Drawer`** vs **route** for a flow.
+Use when choosing **Radix `Dialog` / `AlertDialog`** vs **floating `Sheet` panels** vs **route** for a flow.
 
 ## Read first
 
@@ -10,11 +10,11 @@ Use when choosing **Radix `Dialog` / `AlertDialog`** vs **`Sheet` / `Drawer`** v
 
 ## Checklist
 
-1. **Must the user see the hub while acting?** Yes → **drawer/sheet** (properties, export, invite). No and short → **dialog**. Long / own URL → **route**.
-2. **Destructive confirm?** Prefer **dialog** (`AlertDialog`) unless the product explicitly keeps context in a drawer with the same safeguards.
-3. **Title + focus** — Dialog/drawer/sheet all need an accessible **title**; restore focus to trigger on close.
+1. **Must the user see the hub while acting?** Yes → **`Sheet`** panel (properties, export, invite). No and short → **dialog**. Long / own URL → **route**.
+2. **Destructive confirm?** Prefer **dialog** (`AlertDialog`) unless the product explicitly keeps context in a sheet with the same safeguards.
+3. **Title + focus** — Dialog and sheet both need an accessible **title**; restore focus to trigger on close.
 
 ## Repo references
 
-- `TablePropertiesDrawer`, `ExportDrawer`, `InviteCollaboratorsDrawer` — drawer-class.
+- `TablePropertiesDrawer`, `ExportDrawer`, `InviteCollaboratorsDrawer` — floating **`Sheet`** (names end in “Drawer” but implementation is `Sheet` only).
 - Delete / irreversible — dialog pattern, not toast (**`exxat-no-toast.mdc`**).

package/consumer-extras/cursor-skills/exxat-ds-skill/SKILL.md

@@ -622,7 +622,7 @@ Full checklist in `references/accessibility.md`. Summary of the most-violated ru
 ### Structure
 - One `<main id="main-content" tabIndex={-1}>` per page
 - One `<h1>` per page (via `PageHeader`) — `SiteHeader` title is NOT an h1
-- `DialogTitle` / `SheetTitle` / `DrawerTitle` always present (use `className="sr-only"` if visually hidden)
+- `DialogTitle` / `SheetTitle` always present (use `className="sr-only"` if visually hidden)
 
 ### ARIA roles
 - `role="tablist"` → only `role="tab"` children. **Never** put buttons, menus, or other controls inside `tablist`
@@ -879,7 +879,7 @@ Copy and complete for every list/table/hub page:
 - [ ] All icons: `aria-hidden="true"`; Ask Leo: `fa-duotone fa-solid fa-star-christmas text-brand`
 - [ ] **Every icon that communicates info has a text alternative** — Case A adjacent label (preferred), Case B `role="img"` + `aria-label` + `Tooltip` (calendar-for-date, status dot, trend arrow, icon-only legend), Case C `aria-label` + `Tooltip` on icon-only buttons; target ≥ 24×24 px. See §12 *Icons that communicate information*.
 - [ ] **`Kbd` inside a `Button` uses `variant="bare"`** (glue chords into one bare kbd); **`Kbd` inside `TooltipContent` uses the default tile** — see §11 Keyboard shortcuts
-- [ ] `DialogTitle`/`SheetTitle`/`DrawerTitle` present on every overlay
+- [ ] `DialogTitle`/`SheetTitle` present on every overlay
 - [ ] `role="tablist"` contains only tab-role children
 - [ ] No new shadcn components, no hardcoded colors, no duplicate component abstractions
 

package/consumer-extras/cursor-skills/exxat-ds-skill/references/accessibility.md

@@ -42,7 +42,7 @@ This is the single source of truth for all accessibility requirements in Exxat D
 - Heading hierarchy: one `<h1>` (via `PageHeader`), logical `<h2>` → `<h3>` (no skipping)
 - `SiteHeader` title in the breadcrumb bar is NOT an `<h1>`
 - Multiple `<nav>` elements: each must have `aria-label`
-- Modal/Sheet/Dialog: `DialogTitle`/`SheetTitle`/`DrawerTitle` ALWAYS present — use `sr-only` if visually hidden
+- Modal/Sheet/Dialog: `DialogTitle`/`SheetTitle` ALWAYS present — use `sr-only` if visually hidden
 - `<aside>` panels: `aria-label` (e.g. "Ask Leo assistant", "Rotation navigation")
 - Data tables: `<table>` + `<thead>` + `<th scope="col">`; sortable columns: `aria-sort` on `<th>`
 - Listbox: `role="listbox"` + `role="option"` + `aria-selected`

package/consumer-extras/cursor-skills/exxat-token-economy/SKILL.md

@@ -64,8 +64,11 @@ Answer **yes / no / N/A** to each. A **no** means re-plan; you'll save a regener
 4. **≤ 4 KPIs on the primary strip?** — `KEY_METRICS_KPI_COUNT_MAX = 4`. A fifth becomes a `MetricInsight` or a chart.
 5. **No toasts for product feedback?** — use `LocalBanner` / `SystemBanner` / inline status. Toasts are reserved for build-tool messages.
 6. **Seven views + real bodies?** — `FULL_HUB_SUPPORTED_VIEWS` on **`ListPageTemplate`** + **`HubTable`** (sync both); every allowed view has a renderer; list uses **`ListPageBoardCard`** — not `["table"]` / `PRIMARY_HUB_SUPPORTED_VIEWS` / empty `renderers={}`.
+7. **Sheet only (no Vaul)?** — side panels use **`Sheet`**; **`vaul`** must not be in `package.json`.
+8. **Header + tabs + table preview?** — **`PageHeader`** + DS **`Button`** variants for actions; hub views via **`ListPageTemplate`** (not full-width tabs); record tabs **`TabsList`** `w-fit`; row preview via **`HoverCard`** + shared cells — not custom popovers.
+9. **Uploaded image ≠ spec?** — If the user attached a screenshot/mockup: extract **IA only** (labels, routes, fields); map to **`component-selection-guide`** + a **reference hub**; **MUST NOT** pixel-copy colors, sidebar chrome, tabs, or bespoke widgets — **`exxat-no-image-pixel-copy.mdc`**.
 
-If all six are **yes**, generate. If any is **no**, either narrow the requirements
+If all nine are **yes**, generate. If any is **no**, either narrow the requirements
 with **one** clarifying question or fix the gap silently and note it in your response.
 
 ---
@@ -84,7 +87,7 @@ When the user says "X", reach for "Y". Save the search.
 | chip, badge, status, tag | `Badge`, `ListHubStatusBadge`, `StatusBadge` | `@/components/{ui/badge,list-hub-status-badge}` |
 | dropdown, menu, ⋯ | `DropdownMenu` family | `@/components/ui/dropdown-menu` |
 | tooltip, hint | `Tip` (or `Tooltip`) | `@/components/ui/tip` |
-| sheet, drawer | `Sheet` family, `ExportDrawer`, `TablePropertiesDrawer` | `@/components/ui/sheet` |
+| sheet, side panel | `Sheet` family, `ExportDrawer`, `TablePropertiesDrawer` | `@/components/ui/sheet` |
 | dialog, modal, confirm | `Dialog` family | `@/components/ui/dialog` |
 | table, list, grid (product data) | `HubTable` inside `ListPageTemplate` | `@/components/data-views` |
 | KPI, metric, stat | `KeyMetrics` + `MetricItem` | `@/components/key-metrics` |

package/consumer-extras/handbook/reference-implementations.md

@@ -131,6 +131,8 @@ These exist but are **not** canonical. They predate a rule, are scoped to a one-
 | 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`** |
+| Uploaded screenshots / mockups treated as pixel spec | Images show **intent** — DS blueprints + reference hubs define **implementation** | **`exxat-no-image-pixel-copy.mdc`** + **`component-selection-guide.md`** |
 
 ---
 

package/consumer-extras/patterns/consumer-upgrade-checklist.md

@@ -29,8 +29,22 @@ Use it when you need to know **what files exist**, **how shims re-export** `@exx
 
 - Keep **`@exxatdesignux/ui`** on the same semver your team tested; prefer explicit **`^x.y.z`** or pinned **`x.y.z`**.
 - Match **`engines.node`** in your app to the value declared in **`node_modules/@exxatdesignux/ui/package.json`** (see CHANGELOG if it changed).
+- **≥ 0.5.3:** Remove **`vaul`** from your app `package.json` and delete any `components/ui/drawer.tsx` shim — side panels use **`Sheet`** only (**`.cursor/rules/exxat-no-vaul.mdc`**).
 
-## 5. Still stuck?
+## 5. Consumer UI audit (after sync-extras)
+
+If the app was built before current agent rules, verify:
+
+| Symptom | Fix |
+|---------|-----|
+| Full-width tab bar on list hub | Use **`ListPageTemplate`** view toolbar — **`exxat-tabs-chrome.mdc`** |
+| Full-width Overview / Academics tabs | **`TabsList`** must stay **`w-fit`** — no `w-full` / `flex-1` stretch |
+| Grey custom header buttons | **`PageHeader`** + **`Button`** variants — **`exxat-page-header-actions.mdc`** |
+| Bespoke student popover in table | **`HoverCard`** + shared cells/badges — **`exxat-table-row-preview.mdc`** |
+| Custom hub table / trimmed Add view | **`HubTable`** + **`FULL_HUB_SUPPORTED_VIEWS`** — **`exxat-hub-supported-views.mdc`** |
+| Agent copied uploaded screenshots pixel-for-pixel | **`exxat-no-image-pixel-copy.mdc`** — images = IA only; map to blueprints + reference hubs |
+
+## 6. Still stuck?
 
 - **`npx --package=@exxatdesignux/ui@latest exxat-ui doctor`** — compares local CLI version vs npm **`latest`**.
 - **`npx --package=@exxatdesignux/ui@latest exxat-ui update`** — install commands and reminders.

package/consumer-extras/patterns/drawer-vs-dialog-pattern.md

@@ -0,0 +1,50 @@
+# Sheet panel vs dialog vs route
+
+> **Related:** `docs/data-views-pattern.md` (Page vs drawer), **`AGENTS.md` §6.4**, **`.cursor/rules/exxat-page-vs-drawer.mdc`**. **This doc** splits **floating `Sheet` panels** vs **modal dialog** when both stay on the same route.
+
+## Sheet (side panel — product “drawers”)
+
+**Use when:**
+
+- The **list or hub behind the panel** still matters (user compares, copies, or dismisses and continues browsing).
+- The flow is **medium length** — export options, table/column properties, invite collaborators, filters that mirror the grid.
+- **Width** helps — tables of options, multi-field forms that would feel cramped in a narrow dialog.
+
+**Implementation:** **`Sheet`** from `@exxatdesignux/ui/components/sheet` with the floating inset pattern (`showOverlay={false}`, `getFloatingSheetInsetProps`) — see `ExportDrawer`, `TablePropertiesDrawer`, `InviteCollaboratorsDrawer`, `LibraryNewFolderSheet`.
+
+**Avoid when:** The task is the **only** thing the user should focus on and the parent would distract (prefer **dialog** for a sharp confirm, or **route** for a full wizard).
+
+## Dialog (modal)
+
+**Use when:**
+
+- You need a **hard stop** — user must answer or dismiss before interacting with the page again (confirm delete, acknowledge legal, pick a single blocking choice).
+- The content is **short and focused** — one decision, one form step, or a compact message with primary/secondary actions.
+- **Destructive or irreversible** actions — pair with clear copy; **Esc** / Cancel returns safely.
+
+**Examples:** `AlertDialog`, confirm-before-remove, “Save changes?” when navigating away.
+
+**Avoid when:** Users need to **reference** the grid or copy values from the page while the panel is open — use a **sheet panel** or **inline** pattern instead.
+
+## Route (new page)
+
+Use when the work is **primary**, **long**, **multi-step**, or deserves its **own URL** — see **`exxat-page-vs-drawer.mdc`** and **`AGENTS.md` §6.4**.
+
+## Quick matrix
+
+| Need | Sheet panel | Dialog | Route |
+| --- | --- | --- | --- |
+| Keep hub visible | Yes | No (blocks) | No |
+| Short confirm / alert | Rare | Yes | Overkill |
+| Long form / wizard | Cramped | No | Yes |
+| Properties tied to a table | Yes | Too small | Optional |
+
+## Accessibility
+
+- **Dialog / sheet:** Must expose a **title** (`DialogTitle`, `SheetTitle`) — use `sr-only` if visually hidden.
+- **Focus trap** is expected in dialogs; sheet panels should still **restore focus** on close to the invoking control.
+
+## See also
+
+- **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**, **`.cursor/skills/exxat-drawer-vs-dialog/SKILL.md`**
+- **`exxat-no-toast.mdc`** — use dialog/banner/inline, not toasts, for outcomes that need acknowledgment.

package/dist/hooks/use-app-theme.d.ts

@@ -10,7 +10,7 @@ declare function useAppTheme(): {
     brand: Brand;
     setBrand: (b: Brand) => void;
     /** The user's preference: "system" | "normal" | "high" | "windows" */
-    contrastPref: "normal" | "high" | "system" | "windows";
+    contrastPref: "system" | "normal" | "high" | "windows";
     /** The resolved contrast mode actually applied to the DOM. */
     contrast: ContrastMode;
     /** Set the contrast preference. */

package/dist/index.d.ts

@@ -52,7 +52,6 @@ export { ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGr
 export { DATE_PICKER_ICON_CLASS, DatePickerField, DatePickerFieldProps, DateTextInputField, DateTextInputFieldProps } from './components/ui/date-picker-field.js';
 export { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger } from './components/ui/dialog.js';
 export { DragHandleGripIcon } from './components/ui/drag-handle-grip.js';
-export { Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerOverlay, DrawerPortal, DrawerTitle, DrawerTrigger } from './components/ui/drawer.js';
 export { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, Shortcut, useShortcut } from './components/ui/dropdown-menu.js';
 export { ExportDrawer, ExportDrawerProps } from './components/ui/export-drawer.js';
 export { HoverCard, HoverCardContent, HoverCardTrigger } from './components/ui/hover-card.js';
@@ -115,7 +114,6 @@ import 'react-day-picker';
 import 'recharts';
 import 'cmdk';
 import '@radix-ui/react-dialog';
-import 'vaul';
 import 'react-hook-form';
 import 'sonner';
 import 'clsx';