@exxatdesignux/ui 0.5.5 → 0.5.6

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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

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,13 +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**; **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.
+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
 
@@ -57,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-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/patterns/jobs/README.md

@@ -0,0 +1,59 @@
+# Exxat DS — Jobs library
+
+> **What:** Canonical reference per **job-to-be-done**, not per component.
+> **Why:** Components answer "how to render". Jobs answer "what to build".
+> **Who:** Humans + AI agents writing design briefs
+> ([`exxat-ux-discovery-protocol.mdc`](../../../.cursor/rules/exxat-ux-discovery-protocol.mdc)).
+
+A **job** is what the user is trying to accomplish — not the screen they end
+up on. Two products with the same component stack can ship different jobs;
+two products with different stacks can ship the same job. **The job is the
+contract.**
+
+## When to use this library
+
+- The user prompt names a screen ("student detail", "settings page", "compose
+  form"). Map it to a **job** first, then pick the reference.
+- Before building, the design brief MUST cite the relevant job doc as a
+  reference.
+- If no job doc matches, **write one** (even short) as part of the work.
+
+## Job → screen mapping
+
+| Job | Doc | Canonical references |
+|-----|-----|----------------------|
+| **Review a record's full state** | [`record-detail.md`](./record-detail.md) | Students / Placements / Library detail |
+| **Triage a list of records** (find at-risk / actionable) | *future* | `PlacementsClient`, `ComplianceClient` |
+| **Compose / create a new record** | *future* | `new-library-item-form.tsx` |
+| **Configure preferences or workspace settings** | *future* | `app/(app)/settings/page.tsx` |
+| **Scan many metrics for anomalies** | *future* | Dashboard route, `DashboardTabs` |
+| **Search / find anything** | *future* | `CommandMenu`, `DedicatedSearch*` |
+| **Onboarding / first-run setup** | *future* | `getting-started.tsx`, `CoachMark` |
+| **Approve / review submitted work** | *future* | (TBD) |
+
+## How a job doc is structured
+
+Every job doc must include:
+
+1. **The job** — one paragraph; user pain, decision, action.
+2. **When this job applies** — triggers, scale, frequency.
+3. **Pattern: route vs sheet vs inline** — with a decision table.
+4. **Information architecture** — ASCII diagram of the IA.
+5. **Layers, in priority order** — identity → status → groups → activity →
+   related.
+6. **When to use tabs / subsections.**
+7. **Navigation — the way back** (P1 enforcement).
+8. **Actions** — primary, overflow, inline.
+9. **States** — loading, empty, error, stale.
+10. **Accessibility** — A11y concerns specific to the job.
+11. **Modern SaaS analogues** — cite by product + Mx codes.
+12. **Anti-patterns** — what NOT to do.
+13. **Quick checklist** for the post-build audit.
+
+## See also
+
+- [`../modern-saas-patterns.md`](../modern-saas-patterns.md) — the canon
+- [`../component-selection-guide.md`](../component-selection-guide.md) —
+  decision tree from job → composition
+- [`../blueprints/`](../blueprints/) — framework-agnostic specs
+- [`../../../.cursor/skills/exxat-senior-ux/SKILL.md`](../../../.cursor/skills/exxat-senior-ux/SKILL.md)