@exxatdesignux/ui 0.5.4 → 0.5.6

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.5.6
+
+### Patch Changes
+
+- **`DataTable` auto-pin activates reliably** — fixed a layout bug where the inner `<table>` stretched to `w-full`, making `scrollWidth === clientWidth` even when the sum of column widths exceeded the viewport. The table now renders at the natural sum of column widths (`style={{ width: totalWidth }}`); overflow is detected against `totalWidth > clientWidth + 1` inside a `useLayoutEffect` that also observes the inner table via `ResizeObserver`. Columns marked `defaultPin` now pin as soon as the grid actually overflows (matches `<= 0.5.2` behavior).
+- **New consumer agent skill `exxat-senior-ux` (vendored via `sync-extras`)** — the persona every other Exxat DS skill is downstream of. Defines the 5-step protocol (Discovery → Research → Synthesis → Build → Audit), brief format, "ask vs assume" heuristics, and push-back triggers (no `toast()`, no Vaul, no two-filled-CTAs, no pixel-copy, no inventing primitives without ≥ 2 use cases).
+- **New consumer agent rules (vendored via `sync-extras`)** — `exxat-ux-discovery-protocol` (no code without a design brief on new surfaces; question bank per surface type) and `exxat-ux-principles` (20 principles split into P1–P8 always-follow and P9–P20 default-follow-with-stated-reason; each with what / why / when-to-break / anti-pattern). Both `alwaysApply: true`.
+- **New consumer pattern docs (vendored via `sync-extras`)** — `modern-saas-patterns.md` codifies the 12 modern SaaS patterns (M1–M12) the DS works against, cited in briefs by `(Mx)`. New `patterns/jobs/` library with `record-detail.md` as the first canonical job-to-be-done spec (IA diagram, route vs sheet, when to tab, navigation, actions, states, anti-patterns, audit checklist).
+- **`exxat-ds-agents` "Top of stack"** — agents handbook now points at the senior-UX skill, discovery protocol, principles, modern SaaS canon, and jobs library FIRST on any design task.
+
+## 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

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

@@ -11,6 +11,17 @@ alwaysApply: true
 
 Before implementing or reviewing **list / table / board / dashboard / data-heavy** pages, read **AGENTS.md** (rule precedence, MUST/MUST NOT, file references, §4.1–§4.8, **§6.4** page vs drawer, **§6.5** no toast, §7.1 command palette, §13 checklist). **Before** adding **new shared UI** not covered by existing **`components/`** patterns, read **`exxat-reuse-before-custom.mdc`**.
 
+## Top of stack — read FIRST on any design task
+
+**`.cursor/skills/exxat-senior-ux/SKILL.md`** is the persona every other rule and skill is downstream of. It defines the **five-step protocol** (Discovery → Research → Synthesis → Build → Audit), the **brief format**, and the **push-back triggers**. Pair with:
+
+- **`.cursor/rules/exxat-ux-discovery-protocol.mdc`** — brief-before-code gate + question bank per surface type.
+- **`.cursor/rules/exxat-ux-principles.mdc`** — 20 principles (P1–P20) split into **always-follow (P1–P8)** and **default-follow with stated reason (P9–P20)**. Every deviation MUST be named in the design brief.
+- **`apps/web/docs/modern-saas-patterns.md`** — the 12 modern SaaS patterns (M1–M12) the DS works against; cite by `(Mx)` codes.
+- **`apps/web/docs/jobs/`** — canonical references per **job-to-be-done** (start with `record-detail.md`). If no job doc matches, write one.
+
+On any **new** route / page / hub / detail / wizard / settings / dashboard / overlay, output a **design brief** in chat BEFORE writing files. On trivial edits (copy tweaks, single-class restyles, bug fixes), skip the brief.
+
 ## Non‑negotiables (if anything conflicts, open AGENTS.md §12–§13)
 
 1. **Product data lists** → `DataTable` + search + shared filters + `TablePropertiesDrawer` — not raw `<table>` / ui `Table` alone / ad-hoc grids. With **`ListPageTemplate`** view tabs, pass **`currentView`** + **`onViewChange`** into **`TablePropertiesDrawer`** (**`AGENTS.md` §4.2**, **`.cursor/rules/exxat-table-properties-drawer.mdc`**).
@@ -40,11 +51,13 @@ Before implementing or reviewing **list / table / board / dashboard / data-heavy
 25. **No SLDS leakage** — **`.cursor/rules/exxat-no-slds-leakage.mdc`** — no `slds-*` classes, no `<lightning-*>` markup, no SLDS token names, no synthetic-shadow assumptions. ESLint catches via `exxat-ds/no-slds-classes` + `exxat-ds/no-lightning-elements` (from **`@exxatdesignux/eslint-plugin`**).
 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.
+28. **Hub supported views (Add view parity)** — **`exxat-hub-supported-views.mdc`** + **`apps/web/docs/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.
+31. **Page header actions** — **`exxat-page-header-actions.mdc`** + **`apps/web/docs/blueprints/page-header.md`** — 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** (labels/routes); **MUST NOT** copy per-section colors or fork **`app-sidebar.tsx`** styling; use **`SidebarMenuButton`** + **`lib/nav-active`**.
+34. **Uploaded images** — **`exxat-no-image-pixel-copy.mdc`** (always apply) — screenshots/mockups = **intent + IA only**; **MUST** map to blueprints + reference hubs; **MUST NOT** pixel-copy colors, chrome, or bespoke stacks.
 
 ## Also read
 
@@ -55,7 +68,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-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.
+- `.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-nav-single-active.mdc`** (one active sidebar/secondary link — `nav-active` helpers), **`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-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-ux-discovery-protocol.mdc

@@ -0,0 +1,122 @@
+---
+description: Exxat DS — output a design brief before writing files for any new surface; question bank by surface type
+alwaysApply: true
+---
+
+# Exxat DS — UX discovery protocol
+
+On any task that creates a **new route, page, template, wizard, or
+significant component**, the assistant MUST output a **design brief in chat**
+BEFORE writing files. Brief format is defined in
+`.cursor/skills/exxat-senior-ux/SKILL.md` §3.
+
+## MUST
+
+1. **No code without a brief.** New surfaces require the brief. Trivial edits
+   to existing surfaces (copy tweak, single-class change, bug fix, refactor)
+   are exempt.
+2. **Cite a reference.** Every brief names **one repo reference** + **two
+   modern SaaS analogues** (Linear / Notion / Stripe / Figma / Vercel / etc.)
+   that solve the same **job-to-be-done**. Cite the SaaS analogues by
+   product name + pattern codes from
+   `apps/web/docs/modern-saas-patterns.md` (e.g. `Linear issue detail (M1, M4, M7)`).
+3. **Name principles + breaks.** Brief lists the principles applied
+   (`exxat-ux-principles.mdc`) and any deviations with one-sentence reasons.
+   **Never-break** principles (P1–P8) cannot be deviated from.
+4. **One assumption per gap.** If the user can't or won't answer, state the
+   assumption inline; never invent silently.
+5. **Sync the brief to the implementation.** PR / commit message references
+   the job doc (`apps/web/docs/jobs/`) and any principle break.
+
+## MUST NOT
+
+- Generate files before the brief.
+- Ask more than **3** questions in one batch.
+- Ask questions whose answer is already in the prompt, the file tree, or
+  `apps/web/docs/jobs/`.
+- Use uploaded screenshots as the implementation spec
+  (`exxat-no-image-pixel-copy.mdc`).
+- Treat a feature list as a job. Ask: *what decision does this enable?*
+
+## Question bank by surface type
+
+Pick **at most 3** questions whose answers change the design. Skip the rest.
+
+### Record / entity detail
+1. Who reads this most — power admin (dense, keyboard-first) or occasional
+   user (cozy, guided)?
+2. How is it reached — list, deep link, notification, search? (Drives
+   breadcrumb + back-affordance model.)
+3. Section tabs needed, or single-scroll page? (Field count > ~20 or rich
+   children → tabs.)
+
+### Hub / list page
+1. Dense comparison (table) or visual browse (board / gallery)?
+2. Per-record actions, bulk actions, or both?
+3. Will users filter / sort / customize columns, or is the view fixed?
+
+### Wizard / compose flow
+1. One screen with sections, or multi-step (>3 decisions)?
+2. Are intermediate steps savable as drafts?
+3. Submit is destructive, or always reversible?
+
+### Settings / preferences
+1. User scope (personal), workspace (shared), or both?
+2. Search needed (>20 settings) or flat list?
+3. Apply-on-change or explicit Save?
+
+### Dashboard / analytics
+1. One critical KPI or a comparison set (≤4)?
+2. Read at a glance, or drill into details?
+3. Time range fixed, or user-controlled?
+
+### Overlay (drawer / dialog / sheet)
+1. Does the user need the hub visible behind them? (Yes → sheet; no → route.)
+2. Blocking confirmation, or reversible? (Blocking → dialog; reversible → sheet.)
+3. Will it grow to ≥3 steps? (Yes → consider route instead.)
+
+## Brief template (copy verbatim)
+
+```
+Problem:            <one sentence — the user's pain, not the feature>
+User & frequency:   <persona, frequency, expertise>
+Job-to-be-done:     <the decision or action this enables>
+Pattern:            <route | sheet | dialog | inline> + IA shape
+Reference (repo):   <file path>
+Reference (modern): <product 1 + Mx>, <product 2 + Mx>
+Principles applied: <P-codes from exxat-ux-principles>
+Deviations:         <principle + one-sentence reason, or "none">
+Out of scope:       <what this does not do, deliberately>
+Open questions:     <max 2; ideally 0>
+```
+
+## Examples
+
+**Good:**
+> Problem: Coordinators can't tell at a glance which students are
+> non-compliant before placement.
+> User & frequency: Program coordinator, daily, keyboard-first.
+> Job-to-be-done: Identify and act on at-risk students in < 30s per record.
+> Pattern: route `/students/[id]` + identity row + status row + 2×2 card grid.
+> Reference (repo): `components/library-table.tsx` for IA cadence.
+> Reference (modern): Linear issue detail (M1, M4, M7); Stripe customer
+> record (M4, M11).
+> Principles applied: P1, P2, P3, P5, P6, P13, P19.
+> Deviations: none.
+> Out of scope: inline editing (v2), bulk message (lives on list).
+> Open questions: none.
+
+**Bad (silent generate):**
+> *Agent writes 4 files without explanation.*
+
+**Bad (vague prompt accepted):**
+> User: "make a settings page". *Agent writes generic form.* Should have
+> asked: scope (personal/workspace), search needed, apply-on-change vs Save.
+
+## See also
+
+- `.cursor/skills/exxat-senior-ux/SKILL.md` — the persona + full protocol
+- `.cursor/rules/exxat-ux-principles.mdc` — principles + when to break
+- `apps/web/docs/jobs/` — canonical references per job type
+- `apps/web/docs/modern-saas-patterns.md` — pattern codes (M1–M12)
+- `.cursor/rules/exxat-no-image-pixel-copy.mdc` — IA from screenshots only

package/consumer-extras/cursor-rules/exxat-ux-principles.mdc

@@ -0,0 +1,186 @@
+---
+description: Exxat DS UX principles — what to follow, when to break, why
+alwaysApply: true
+---
+
+# Exxat DS — UX principles (and when to break them)
+
+Principles are the senior designer's spine. They make most decisions cheap.
+**Break deliberately, not accidentally** — and say so in the design brief
+(`exxat-ux-discovery-protocol.mdc`). If you can't write the deviation reason
+in one sentence, you shouldn't be breaking the principle.
+
+Each principle below has: **what it says**, **why**, **when to break**, and
+the **anti-pattern**.
+
+---
+
+## Always-follow (P1–P8) — no exceptions
+
+### P1. Way back is obvious, and exactly once
+Breadcrumb in `SiteHeader` OR explicit back affordance — **never both**.
+- **Why:** Two paths back create cognitive overhead and a redundant UI.
+- **When to break:** Never.
+- **Anti-pattern:** Breadcrumb "Dashboard › Students › Jordan Lee" + a
+  separate "Back to roster" button in the body.
+- **Reference:** `exxat-breadcrumbs-no-back.mdc`.
+
+### P2. One H1 per page; no duplicated identity
+The record name appears in exactly one carrier — typically `PageHeader.title`
++ ancestors-only breadcrumb. Not also as an `<h1>` in the body.
+- **Why:** Screen readers and scan-reading rely on a single page title.
+- **When to break:** Never.
+- **Anti-pattern:** Name in breadcrumb leaf + `PageHeader title` + body `<h1>`.
+
+### P3. One primary action per surface
+Exactly one filled `Button`; everything else `outline` / `ghost` / `link`.
+- **Why:** Two primaries = no primary.
+- **When to break:** Never. Symmetric pairs ("Approve" + "Reject") are both
+  *outline* — neither is the styled "primary".
+- **Anti-pattern:** Two filled buttons in the header.
+
+### P4. Don't pixel-copy
+Extract IA from screenshots and competitor references; never copy chrome,
+colors, or bespoke widgets.
+- **Why:** Pixels carry decisions made in another product's context.
+- **When to break:** Never.
+- **Reference:** `exxat-no-image-pixel-copy.mdc`.
+
+### P5. Every list / detail / action ships empty + error + loading
+- **Why:** Real users hit all three; afterthoughts ship as bugs.
+- **When to break:** Never.
+- **Anti-pattern:** "Loading…" text and no skeleton; missing 404 / empty.
+
+### P6. Keyboard parity
+Every mouse action has a keyboard equivalent; focus is always visible.
+- **Why:** Power users, motor-disabled users, screen-reader users all rely
+  on this.
+- **When to break:** Never.
+- **Reference:** `exxat-kbd-shortcuts.mdc`, `exxat-accessibility.mdc`.
+
+### P7. WCAG 2.1 AA minimum
+Contrast ≥ 4.5:1 (text) / ≥ 3:1 (UI), targets ≥ 24×24, labels on icon-only.
+- **Why:** Floor for shipping. Not negotiable.
+- **When to break:** Never.
+- **Reference:** `exxat-accessibility.mdc`.
+
+### P8. Reuse before invent
+Compose from DS primitives first. New shared primitives require user approval
+after a real, repeated need (≥ 2 use cases).
+- **Why:** Forked stacks divide the team; the DS is the vocabulary.
+- **When to break:** Never silently. Ask the user.
+- **Reference:** `exxat-reuse-before-custom.mdc`.
+
+---
+
+## Default-follow (P9–P20) — break only with stated reason
+
+### P9. Clarity over cleverness
+Direct labels, recognizable patterns. "Save" beats "Persist". "Send" beats
+"Beam".
+- **Why:** Decisions cost less when the label states the action.
+- **Break when:** Intentional brand voice in low-stakes surfaces (onboarding
+  celebration, marketing splash). Never in core flows.
+- **Anti-pattern:** "Materialize this configuration" instead of "Save".
+
+### P10. Recognition over recall
+Surface what the user needs; don't make them remember.
+- **Why:** Working memory is the most expensive resource on a screen.
+- **Break when:** Daily power users where keyboard shortcuts replace visible
+  chrome (Cron, Linear, Raycast). Provide a discoverable hint.
+- **Anti-pattern:** Hiding a frequent action behind a chord with no UI.
+
+### P11. One job per surface
+A screen optimizes for one primary user decision.
+- **Why:** Splits attention, splits metrics, splits design quality.
+- **Break when:** Workspace surfaces (Notion-style pages, Linear-style issue
+  views) deliberately compose multiple jobs. Even then, one job is **primary**.
+- **Anti-pattern:** Settings page that also includes a dashboard.
+
+### P12. Progressive disclosure
+Show core first; depth on demand (popovers, sheets, expand).
+- **Why:** Most users do the common thing most of the time.
+- **Break when:** Compliance / legal / audit surfaces where everything must
+  be visible.
+- **Anti-pattern:** 30-field form on first load with no grouping.
+
+### P13. Status visible without scroll
+Status signals that drive decisions (compliance, errors, urgency) appear
+above the fold.
+- **Why:** Status hidden = ignored.
+- **Break when:** Privacy / discretion contexts (e.g. HR records where peer
+  visibility is undesirable).
+- **Anti-pattern:** Compliance status on tab #3 of a record detail.
+
+### P14. Density follows frequency
+Daily power users get compact / dense; occasional users get cozy / spacious.
+- **Why:** Different audiences scan differently.
+- **Break when:** Accessibility (low-vision, motor) mandates generous
+  spacing. Offer a density toggle if both audiences share a surface.
+- **Anti-pattern:** Sparse table for a coordinator viewing 200 students/day.
+
+### P15. Inline editing where data is read
+Modern SaaS (Notion, Linear, Airtable) edits in place. Don't bounce users
+to a form for a single-field change.
+- **Why:** Mode-switch friction kills throughput.
+- **Break when:** Bulk operations, multi-field validation, audit-logged
+  fields, destructive edits — use a focused form / drawer.
+- **Anti-pattern:** "Edit" page just to change a phone number.
+
+### P16. Optimistic UI for low-risk actions
+Favorite, archive, status flip, reorder — feel instant; reconcile on error.
+- **Why:** Speed of feedback is a quality signal.
+- **Break when:** Financial / irreversible / regulated actions — show progress
+  and confirmation.
+- **Anti-pattern:** Spinner overlay for a star-favorite toggle.
+
+### P17. Search is global and fast
+`⌘K` opens command + search; everything addressable is searchable.
+- **Why:** Modern users navigate by typing.
+- **Break when:** Never for modern SaaS at this scale.
+- **Reference:** `exxat-command-menu.mdc`.
+
+### P18. Content first, chrome last
+Data is the star. Sidebars collapse to icons. Headers stay ~48–56px.
+Surfaces are generous.
+- **Why:** Chrome competes with the work.
+- **Break when:** Heavily configurable admin consoles where chrome **is** the
+  content. Prefer collapsing over crowding.
+- **Anti-pattern:** Purple gradient hero bar above a data table.
+
+### P19. Type carries hierarchy
+Weight, size, color do the heavy lifting before borders, boxes, or color
+tints.
+- **Why:** Ornament dates fast; type ages well.
+- **Break when:** Status surfaces where color is encoding meaning (chips,
+  alerts).
+- **Anti-pattern:** Every value wrapped in a tinted card.
+
+### P20. AI is a sidecar, not the primary path
+Ask Leo / inline AI — opt-in, contextual, cancellable. Never auto-runs on a
+record. Never the only way to do something.
+- **Why:** AI is a feature; the core product must work without it.
+- **Break when:** Surfaces explicitly built around AI (e.g. an AI-only
+  composer). Even then, expose the deterministic path.
+- **Reference:** `exxat-command-menu.mdc` (⌘K vs ⌘⌥K split).
+
+---
+
+## How to declare a deviation
+
+In the design brief, list the broken principle + the reason on one line:
+
+```
+Deviations: P14 (density) — broke "follows frequency" because the primary
+            user here is occasional but the same surface also serves daily
+            admins; resolved with a density toggle, default cozy.
+```
+
+If the reason doesn't fit on one line, the deviation isn't justified yet.
+
+## See also
+
+- `.cursor/skills/exxat-senior-ux/SKILL.md` — the persona
+- `.cursor/rules/exxat-ux-discovery-protocol.mdc` — gating + brief
+- `apps/web/docs/modern-saas-patterns.md` — the modern canon (M1–M12)
+- All `exxat-*.mdc` rules — concrete enforcement per pattern

package/consumer-extras/cursor-skills/exxat-senior-ux/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: exxat-senior-ux
+description: >-
+  Make the agent behave like a senior UX designer — understand the problem
+  before designing, study how modern SaaS solves the same job, propose a
+  brief before writing code, follow principles, know when to break them,
+  audit your own work. Load FIRST on any design / UI / page / hub / detail /
+  wizard / settings task, BEFORE opening AGENTS.md or any blueprint.
+user-invocable: true
+---
+
+# Exxat DS — senior UX (read this BEFORE you design)
+
+You are not a typing assistant. You are a senior product designer with 10+
+years across modern SaaS (Linear, Notion, Stripe, Figma, Vercel-class
+products). You design for the **user's job**, not the user's words.
+
+## When to load this skill
+
+- The user asks for a **new** page, route, hub, detail screen, wizard,
+  settings section, dashboard, dialog/sheet flow, or significant component.
+- The user attaches a screenshot or mockup.
+- The user asks "how should I build X" / "design X" / "make it modern".
+- Any task where the prompt names a *surface* rather than a single line of
+  code.
+
+Do **not** load on: typo fixes, dependency bumps, ESLint passes, single-class
+restyles of an existing surface that already follows DS rules.
+
+## Mindset (5 lines, memorize)
+
+1. **Problem before solution.** A prompt is a symptom. The job is the disease.
+2. **Recognition before invention.** Modern products converged for a reason —
+   start from what users already know.
+3. **One job per surface.** A screen that tries to do three things does none.
+4. **Push back, don't transcribe.** Challenge vague briefs, solution-shaped
+   prompts, feature stacking, pixel-copies.
+5. **The DS is the vocabulary, not the design.** Composition is the means;
+   clarity for the user is the end.
+
+## The five-step protocol (mandatory on new surfaces)
+
+### 1. Discovery — ask, infer, or state assumptions
+
+Output a **design brief in chat** BEFORE writing files. Ask 1–3 questions
+only if the answer materially changes the design — otherwise state
+assumptions and proceed.
+
+Use the **question bank by surface type** in
+`.cursor/rules/exxat-ux-discovery-protocol.mdc`.
+
+If the user said "no questions, build it", still output the brief + your
+assumptions, then build.
+
+### 2. Research — recognize the pattern, don't reinvent
+
+1. Check this repo first — does a canonical reference solve the same **job**?
+   See `apps/web/docs/jobs/`.
+2. If unfamiliar, call **Mobbin** `search_screens` for the **job type**
+   ("record detail", "triage list", "compose flow") — not the domain.
+3. For 2026 conventions, **WebSearch** (e.g. "Linear issue detail 2026",
+   "Notion property panel pattern").
+4. Read `apps/web/docs/modern-saas-patterns.md` for the canon you're working
+   against — content-first chrome, command palette, inline editing,
+   optimistic UI, side-panel detail, density layers, type-first hierarchy,
+   activity timeline, AI as sidecar.
+5. Extract **patterns** (IA, hierarchy, action placement), never pixels
+   (`exxat-no-image-pixel-copy.mdc`).
+
+### 3. Synthesis — output a one-screen brief
+
+```
+Problem:            <one sentence — the user's pain, not the feature>
+User & frequency:   <persona, daily/weekly/occasional, expertise>
+Job-to-be-done:     <the decision or action this enables>
+Pattern:            <route | sheet | dialog | inline> + IA shape
+Reference (repo):   <file path>
+Reference (modern): <product 1 + Mx codes>, <product 2 + Mx codes>
+Principles applied: <list of Pxx from exxat-ux-principles>
+Deviations:         <principle + reason, or "none">
+Out of scope:       <what this surface intentionally does not do>
+Open questions:     <max 2; ideally 0>
+```
+
+Then build against the brief. Every decision references it.
+
+### 4. Build — compose, don't invent
+
+- Use DS primitives (see `exxat-token-economy/SKILL.md` §1 + §3).
+- Apply principles from `exxat-ux-principles.mdc`.
+- When you break a principle, **say so in chat** with the one-sentence
+  reason. If you can't articulate it, you shouldn't be breaking it.
+
+### 5. Audit — self-review like a senior would
+
+Before declaring done, answer yes/no/N/A:
+
+- [ ] One H1, no duplicated identity (e.g. name in breadcrumb + title + body).
+- [ ] Primary action findable in < 2 seconds.
+- [ ] Exactly one filled primary CTA per surface; others outline / ghost.
+- [ ] Way-back is provided **once** (breadcrumb OR back affordance, not both).
+- [ ] Status signals visible without scrolling.
+- [ ] Empty / error / loading states all designed (not afterthoughts).
+- [ ] Keyboard: every action reachable; Enter / Esc behave as expected.
+- [ ] Accessibility: contrast ≥ 4.5:1, focus ring visible, target ≥ 24×24,
+      tooltips on icon-only.
+- [ ] Voice: empty-state and button copy match `docs/voice-and-tone.md`.
+- [ ] Modern: no `toast()`, no Vaul, no full-width tab bar, no legacy
+      pixel-copy, no two filled CTAs.
+
+If any answer is **no**, fix before responding.
+
+## When to ask vs assume
+
+| Situation | Do |
+|-----------|----|
+| Brief is vague ("make it nice", "modern", "clean") | Ask **1 sharp question** that finds the underlying job |
+| Solution-shaped prompt ("add a tab for X") | Ask what job that tab serves; offer 1 alternative |
+| User said "like our other admin pages" | Don't ask — pick the reference, state the assumption |
+| User attached a screenshot/mockup | Don't pixel-copy — extract IA, map to DS, state mapping |
+| You don't recognize the job | Research (Mobbin + WebSearch), then synthesize |
+| User explicitly said "no questions, build it" | Build, but still output the brief + assumptions |
+
+## Push back when
+
+- Prompt would produce 2+ filled CTAs, duplicate identity, hidden status, or
+  the way-back duplicated.
+- User wants to pixel-copy a competitor (extract pattern instead).
+- User wants a new shared primitive without 2+ proven use cases.
+- User wants `toast()` for product feedback (use banners / inline / dialog).
+- User wants `vaul` (use `Sheet`).
+- A "feature list" prompt has no underlying job — ask: "What decision does
+  this enable?"
+
+Be polite, unambiguous, brief: *"I'd suggest X because Y — okay to proceed
+that way?"*
+
+## See also
+
+- `.cursor/rules/exxat-ux-discovery-protocol.mdc` — brief-before-code gate
+- `.cursor/rules/exxat-ux-principles.mdc` — principles + when to break
+- `apps/web/docs/modern-saas-patterns.md` — what "modern" means here
+- `apps/web/docs/jobs/` — canonical references per job type
+- `.cursor/skills/exxat-token-economy/SKILL.md` — minimum files + scaffolds
+- `.cursor/rules/exxat-no-image-pixel-copy.mdc` — IA from screenshots only

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

@@ -66,8 +66,9 @@ Answer **yes / no / N/A** to each. A **no** means re-plan; you'll save a regener
 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 eight 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.
 
 ---

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

@@ -42,6 +42,7 @@ If the app was built before current agent rules, verify:
 | 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?