@exxatdesignux/ui 0.5.11 → 0.5.12

package/template-vite/.cursor/rules/exxat-tabs-chrome.mdc

@@ -0,0 +1,33 @@
+---
+description: Exxat DS — Tabs and view toolbars must not stretch full width; use ListPageTemplate for hub views. Auto-attaches when editing React surfaces with tabs or view toolbars.
+globs: apps/web/{components,app}/**/*.{tsx,ts}
+alwaysApply: false
+appliesTo: [react]
+---
+
+# 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
+
+- **`apps/web/docs/blueprints/page-header.md`** — header never carries view tabs
+- **`apps/web/docs/data-views-pattern.md`** — `ListPageTemplate` view toolbar

package/template-vite/.cursor/rules/exxat-token-discipline.mdc

@@ -0,0 +1,109 @@
+---
+description: Token discipline — no hex literals, prefer Exxat L0 tokens (--exxat-color-*, --exxat-radius-*, --exxat-spacing-*), no deprecated tokens. ESLint enforces via @exxatdesignux/eslint-plugin.
+alwaysApply: true
+appliesTo: [universal]
+---
+
+# Exxat DS — token discipline
+
+**Authoritative reference:** [`apps/web/docs/token-taxonomy.md`](mdc:apps/web/docs/token-taxonomy.md).
+**Machine-readable index:** [`packages/ui/tokens/hooks-index.json`](mdc:packages/ui/tokens/hooks-index.json) (163 tokens · 36 namespaces; regenerate via `pnpm --filter @exxatdesignux/ui tokens:index`).
+**Enforcement:** [`@exxatdesignux/eslint-plugin`](mdc:packages/eslint-plugin-exxat-ds/README.md) (rules `exxat-ds/no-hex-color`, `exxat-ds/no-deprecated-tokens`).
+
+Use this rule when adding **any** color, spacing, radius, shadow, or
+transition value to JSX, CSS, or Tailwind class strings.
+
+## MUST
+
+1. **Prefer the Exxat L0 namespace** for new code — `var(--exxat-color-surface-1)`,
+   `bg-surface-1`, `bg-brand-1`, `rounded-2`, `--exxat-spacing-4`, … (taxonomy §2.0).
+   L1 shadcn names (`--background`, `bg-brand`, `rounded-md`, …) remain as
+   back-compat aliases and continue to work — but new product surfaces should
+   read in the canonical brand-prefixed namespace.
+2. **Reach for a semantic token first.** If the value carries semantic intent
+   ("danger", "warning", "muted text", "card surface"), use the matching
+   token family from §2 of the taxonomy. Never reinvent semantic colors.
+3. **Use Tailwind utilities backed by tokens** (e.g. `bg-card`,
+   `text-muted-foreground`, `border-border-control`, `ring-ring`,
+   `bg-chip-2`, `text-chart-4`, **`bg-surface-1`**, **`bg-brand-1`**,
+   **`rounded-2`**). The L2 bridges in `globals.css` already wire
+   `--color-*` → `var(--*)` so utilities flip with theme + dark mode.
+3. **Brand accent comes from `--brand-color` / `bg-brand`** (and its family),
+   **not** `--primary` / `bg-primary`. Primary is **neutral charcoal** in
+   Exxat — see taxonomy §3.
+4. **Form-field borders** use `--control-border` (or `border-control-3` /
+   `border-control-35`) — never `--border` (which is decorative and < 3:1
+   contrast). Taxonomy §6.
+5. **Status chips and badges** route through
+   [`lib/list-status-badges.ts`](mdc:apps/web/lib/list-status-badges.ts)
+   (`LIST_HUB_STATUS_TINT_*` + `ListHubStatusBadge`) — not direct
+   `bg-green-500` / `bg-red-500` / hex literals.
+6. **KPI tints** route through `--insight-severity-*` (info / warning) — not
+   direct chart-color reuse. Trend polarity is set via
+   `MetricItem.trendPolarity` ([`exxat-kpi-trends.mdc`](mdc:.cursor/rules/exxat-kpi-trends.mdc)).
+7. **Scoped surface tokens stay scoped.** `--dt-*` is `DataTable` only,
+   `--key-metrics-*` is `KeyMetrics` only, `--leo-*` is Ask Leo only,
+   `--secondary-panel-bg` is the nested panel only. Do **not** reuse these
+   tokens outside their owning surface.
+8. **Adding a new token** — Follow the checklist in
+   [`token-taxonomy.md` §4](mdc:apps/web/docs/token-taxonomy.md). Declare
+   the primitive in `packages/ui/src/globals.css` (canonical CSS), bridge it in the same file's `@theme inline`
+   files when Tailwind utilities are needed, document it in the taxonomy,
+   and regenerate `tokens/hooks-index.json`.
+
+## MUST NOT
+
+1. **No raw hex / rgb / hsl color literals** in JSX `className` strings,
+   inline `style={{...}}`, or `.css` files outside of `globals.css` /
+   `globals.css` / theme overrides. The only places hex is legal are:
+   - `--theme-color-chrome` (consumed by `<meta name="theme-color">`)
+   - Status icon SVG paths that are part of a vendored asset
+   - **Documentation** examples (this rule, blueprints, migrations)
+2. **No raw `oklch(...)` literals** in component code — those belong in
+   `globals.css` theme blocks only. If you need a derived value, use
+   `color-mix(in oklch, var(--token) <pct>%, var(--other))` inside a token
+   declaration, not at the call site.
+3. **No deprecated tokens.** Inspect
+   [`tokens/hooks-index.json`](mdc:packages/ui/tokens/hooks-index.json) —
+   any entry with `"deprecated": true` is removed at the version named in
+   `deprecatedMessage`. Migrate before the removal window per
+   `apps/web/docs/migrations/`.
+4. **No ad-hoc Tailwind shades** for product chrome (e.g. `bg-slate-50`,
+   `text-zinc-600`, `border-gray-200`) when an Exxat semantic equivalent
+   exists. Tailwind shade utilities are reserved for transient prototyping
+   only; product code uses the semantic tokens.
+5. **No `text-primary` for the brand accent.** That maps to neutral charcoal
+   (see MUST #3).
+6. **No utility-class typos that look like tokens.** Examples that look
+   right but aren't:
+   - `bg-brand-color` — that's the *raw L1 name*; the L2 utility is `bg-brand`.
+   - `border-control` — there's no such utility; the field-border alias is `border-control-3` (3:1) or `border-control-35` (3.5:1+), or `border-[var(--control-border)]`.
+   - `text-foreground-muted` — the token is `--muted-foreground` (note the order).
+7. **No SLDS tokens** (`--slds-g-color-*`) — see
+   [`exxat-no-slds-leakage.mdc`](mdc:.cursor/rules/exxat-no-slds-leakage.mdc).
+
+## Aliases that ARE official
+
+Some L2 bridges intentionally use a **shorter alias** than the L1 primitive
+because the long name would be awkward in Tailwind utilities. Use the alias
+form, but be aware of the underlying primitive:
+
+| Alias (use in code) | L0 canonical | L1 primitive | Notes |
+|---|---|---|---|
+| `bg-brand` / `text-brand` | `--exxat-color-brand-1` | `--brand-color` | Brand accent |
+| `bg-brand-deep` / `text-brand-deep` | `--exxat-color-brand-deep` | `--brand-color-deep` | Coach marks, hero callouts |
+| `bg-brand-tint` | `--exxat-color-brand-tint-1` | `--brand-tint` | Sidebar wash |
+| `bg-surface-1` / `text-ink-1` | `--exxat-color-surface-1` / `--exxat-color-ink-1` | `--background` / `--foreground` | Page canvas + primary text — new code SHOULD prefer L0 form |
+| `rounded-1` … `rounded-6` | `--exxat-radius-1` … `--exxat-radius-6` | (no L1 equivalent — L0 is canonical for radius) | Numeric radius scale (4 / 8 / 12 / 16 / 20 / 24 px) |
+
+The full alias table is in [`token-taxonomy.md` §2.0](mdc:apps/web/docs/token-taxonomy.md) and [§2.2](mdc:apps/web/docs/token-taxonomy.md).
+
+## See also
+
+- [`apps/web/docs/token-taxonomy.md`](mdc:apps/web/docs/token-taxonomy.md) — full namespace + naming rules
+- [`apps/web/docs/migrations/`](mdc:apps/web/docs/migrations) — deprecation index
+- [`packages/ui/tokens/hooks-index.json`](mdc:packages/ui/tokens/hooks-index.json) — machine-readable
+- [`.cursor/rules/exxat-no-slds-leakage.mdc`](mdc:.cursor/rules/exxat-no-slds-leakage.mdc)
+- [`.cursor/rules/exxat-kpi-trends.mdc`](mdc:.cursor/rules/exxat-kpi-trends.mdc)
+- [`.cursor/rules/exxat-kpi-flat-band.mdc`](mdc:.cursor/rules/exxat-kpi-flat-band.mdc)
+- [`.cursor/rules/exxat-no-toast.mdc`](mdc:.cursor/rules/exxat-no-toast.mdc)

package/template-vite/.cursor/rules/exxat-ux-discovery-protocol.mdc

@@ -0,0 +1,202 @@
+---
+description: Exxat DS — STOP before code on any surface design (new, rebuild, redesign, replace); output a design brief and WAIT for user go-ahead
+alwaysApply: true
+appliesTo: [universal]
+---
+
+# Exxat DS — UX discovery protocol
+
+## STOP — read before you write any file
+
+If the user's prompt asks you to **design, create, build, rebuild, redesign,
+replace, redo, refresh, modernize, re-imagine, or "make a new version of"**
+any **page, route, screen, hub, detail view, wizard, settings section,
+dashboard, dialog, sheet, drawer, panel, layout, or significant component**:
+
+1. **Do NOT write code, do NOT edit files, do NOT call edit tools yet.**
+2. **Output the design brief** (template below) in chat.
+3. **Wait for the user to reply** with `yes` / `proceed` / `ship it` / edits.
+4. **Only then** move to implementation.
+
+If your next tool call would be `write_file`, `str_replace`, `create_file`,
+or any code-mutating action **and** you have not posted a brief and received
+go-ahead, you are violating this rule. **Stop and post the brief.**
+
+## When this gate fires (and when it doesn't)
+
+This gate fires on **any task that decides what a surface should look like
+or how it works** — whether the surface exists today or not. Treat
+"replace what we have" and "create from scratch" identically — both need a
+brief, because both make a design decision.
+
+**Fires (brief required):**
+
+- "Create a new student detail page."
+- "Rebuild the dashboard."
+- "Redesign the settings screen instead of what we have."
+- "Make a new version of the placements table."
+- "Replace the current onboarding flow."
+- "Build a wizard for adding a site."
+- "Design a sheet for inviting collaborators."
+- User attaches a screenshot / mockup / Figma link and asks to "build this".
+
+**Does NOT fire (brief not required, edit freely):**
+
+- Single-class restyle of an existing surface that already follows DS rules.
+- Copy / label edits.
+- Bug fixes (a11y violation, broken state, wrong data).
+- Dependency bumps, ESLint passes, type fixes, test-only changes.
+- Adding a new column / filter to an *existing* `HubTable` that doesn't
+  change the page's IA.
+
+When in doubt, ask: **"Am I deciding what this surface should be?"** Yes →
+brief. No → edit.
+
+## MUST
+
+0. **Output the brief, then WAIT.** The brief is a checkpoint, not a
+   preamble. Do not bundle the brief and the first file edit in the same
+   turn. After posting the brief, end your turn with an explicit
+   "Ready to build — confirm or edit." prompt. Resume only on the user's
+   next message.
+1. **No code without a confirmed brief.** "Confirmed" means the user wrote
+   `yes`, `proceed`, `ship it`, `LGTM`, `build it`, accepted edits, or asked
+   a follow-up that implies acceptance. Silence is not consent.
+2. **Cite a reference.** Every brief names **one repo reference** + **two
+   modern SaaS analogues** (Linear / Notion / Stripe / Figma / Vercel /
+   Linear / Airtable / Coda / Height / 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
+
+- **Skip the brief because the prompt sounds like a refactor.** "Rebuild",
+  "redesign", "replace", "instead of what we have", and "from scratch" are
+  design decisions, not refactors. Brief required.
+- **Post a brief and then write 8 files in the same turn.** That's not a
+  brief — that's a press release. End the turn after the brief.
+- 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.
+
+## Closing artifact: the design → engineering handoff
+
+When the build is complete (files written, surface working in dev), produce
+**one filled-in handoff document** before declaring the task done.
+
+**Template** lives at:
+
+- Workspace: `apps/web/docs/templates/handoff.md` (or workspace root if not yet copied — copy from `packages/ui/consumer-extras/templates/handoff.md`)
+- Consumer apps (after `exxat-ui sync-extras`): `docs/exxat-ds/templates/handoff.md`
+
+**Fill it in** with the actual primitives, tokens, icons, and shortcuts the
+build used. Save the filled copy at:
+
+- `apps/web/docs/handoff/<surface-slug>.md` (workspace)
+- `docs/exxat-ds/handoff/<surface-slug>.md` (consumer)
+
+Attach the filled handoff to the PR description (or paste inline). The
+engineer reads it once, runs `exxat-ui audit <generated-file>` to verify
+the floor, and is done.
+
+**MUST sections:** 1 (job-to-be-done), 3 (pattern + IA), 5 (DS components
+used), 6 (tokens), 8 (a11y checklist — every box ticked), 11 (keyboard map),
+12 (any deviations from P9–P20).
+
+If the handoff is incomplete or hand-wavy, the design task is not finished.
+
+## 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
+- **Closing artifact:** `packages/ui/consumer-extras/templates/handoff.md`

package/template-vite/.cursor/rules/exxat-ux-principles.mdc

@@ -0,0 +1,187 @@
+---
+description: Exxat DS UX principles — what to follow, when to break, why
+alwaysApply: true
+appliesTo: [universal]
+---
+
+# 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