@exxatdesignux/ui 0.5.10 → 0.5.11

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.5.11
+
+### Patch Changes
+
+- **Senior-UX discovery gate now actually gates.** The 0.5.6 senior-UX layer was missing two enforcement teeth that made it skippable in practice — confirmed by a real-world failure where the agent was prompted "create new page of student details page instead of what we have currently" and immediately wrote 4 files without posting a brief. The fix tightens three documents:
+  - **`.cursor/rules/exxat-ux-discovery-protocol.mdc`** — gains a literal **`STOP — read before you write any file`** banner before the H1, an explicit fires-on / does-not-fire-on table (rebuild / redesign / replace / "instead of what we have" / "from scratch" all fire), and a new **MUST #0**: *"Output the brief, then WAIT. Do not bundle the brief and the first file edit in the same turn. After posting the brief, end your turn with 'Ready to build — confirm or edit.' Resume only on the user's next message."* Adds an explicit MUST NOT for "Skip the brief because the prompt sounds like a refactor."
+  - **`.cursor/skills/exxat-senior-ux/SKILL.md`** — description string now lists the trigger verbs that previously slipped through (`rebuild`, `redesign`, `replace`, `redo`, `refresh`, `modernize`, `re-imagine`, `"make a new version"`, `"instead of what we have"`, `"from scratch"`) so Cursor's skill auto-discovery picks up refactor-shaped prompts. Adds a new **Hard gate** section under "When to load" and restructures the five-step protocol as **sequential checkpoints** with **step 3 (Synthesis) ending the turn** — the user's reply is the green light to step 4 (Build).
+  - **`.cursor/rules/exxat-ds-agents.mdc` Top-of-stack** — renamed the brief instruction from a passive bullet to a bold **"Brief-before-code is a CHECKPOINT, not a preamble"** sub-section that lists the protocol as three numbered actions and ends with: *"If your next tool call would be `write_file` / `str_replace` / `create_file` and you have not posted a brief + received user confirmation, you are violating the protocol. Stop, post the brief, end the turn."*
+- **Why it failed silently before:** the rule's trigger language was "**new** route, page, template, wizard" — the agent reading "create new page of student details page **instead of what we have currently**" semantically parsed "instead of what we have" as a refactor of an existing route, so the gate didn't fire. The MUST list also said "before writing files" which the agent could satisfy by writing the brief + 200 lines of code in the same turn — not a checkpoint.
+- **Consumer impact:** `npx exxat-ui sync-extras` overwrites `.cursor/rules/exxat-ux-discovery-protocol.mdc`, `.cursor/rules/exxat-ds-agents.mdc`, and `.cursor/skills/exxat-senior-ux/SKILL.md` with the tightened versions. No code changes in the UI library; no app routes are modified.
+
 ## 0.5.10
 
 ### Patch Changes

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

@@ -15,12 +15,22 @@ Before implementing or reviewing **list / table / board / dashboard / data-heavy
 
 **`.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-discovery-protocol.mdc`** — brief-before-code gate + question bank per surface type. **`alwaysApply: true`** — fires on every design task automatically.
 - **`.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.
+### Brief-before-code is a CHECKPOINT, not a preamble
+
+On any task that **decides what a surface should be** — including *new* pages **and** *rebuilds / redesigns / replacements of existing pages* — the protocol is:
+
+1. **Post the brief in chat. END THE TURN with "Ready to build — confirm or edit."**
+2. **Wait for the user's next message.** Silence is not consent until the next user reply arrives.
+3. **Only then** call code-mutating tools.
+
+Treat **"rebuild X"**, **"redesign X"**, **"replace what we have"**, **"make a new version of X"**, **"from scratch"**, and **"instead of what we currently have"** identically to "create new X" — all of them make a design decision, all of them require the brief checkpoint. The only exempt edits are trivial ones (copy tweaks, single-class restyles, bug fixes, dep bumps, ESLint passes, adding a column to an existing `HubTable` without changing IA).
+
+If your next tool call would be `write_file` / `str_replace` / `create_file` and you have not posted a brief + received user confirmation, **you are violating the protocol**. Stop, post the brief, end the turn.
 
 **Reviewing existing work?** Load **`.cursor/skills/exxat-ux-audit/SKILL.md`** instead. It runs an EXISTING surface (route / file / component / customer-app path / screenshot) through the same P1–P20 / M1–M12 rubric and outputs a **Blocker / Issue / Nit** findings report with code citations, a fix plan, and an offer to auto-apply text-only Blocker fixes. Triggers: "audit X", "review the X page", "is this following DS?", "what's wrong with this screen", "do a UX review", or a route URL with a symptom.
 

package/consumer-extras/cursor-rules/exxat-ux-discovery-protocol.mdc

@@ -1,25 +1,72 @@
 ---
-description: Exxat DS — output a design brief before writing files for any new surface; question bank by surface type
+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
 ---
 
 # 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.
+## 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
 
-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.
+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 / 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)`).
+   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.
@@ -30,6 +77,11 @@ BEFORE writing files. Brief format is defined in
 
 ## 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

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

@@ -1,11 +1,16 @@
 ---
 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.
+  Make the agent behave like a senior UX designer — STOP before writing
+  code, understand the problem, study how modern SaaS solves the same job,
+  propose a design brief, WAIT for user go-ahead, then build. Load FIRST
+  on ANY task that decides what a surface should be — create, build, design,
+  rebuild, redesign, replace, redo, refresh, modernize, re-imagine, "make a
+  new version", "instead of what we have", "from scratch" — for any page,
+  route, hub, detail view, wizard, settings section, dashboard, dialog,
+  sheet, drawer, panel, layout, or significant component. Also load when
+  the user attaches a screenshot / mockup / Figma link and asks to build
+  it. Load BEFORE opening AGENTS.md, blueprints, or any other DS doc.
 user-invocable: true
 ---
 
@@ -17,15 +22,32 @@ 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.
+Load on **any task that decides what a surface should be** — whether the
+surface exists today or not. The user's verb is the strongest signal:
 
-Do **not** load on: typo fixes, dependency bumps, ESLint passes, single-class
-restyles of an existing surface that already follows DS rules.
+| Phrase in the prompt | Load? |
+|---|---|
+| "create / build / make / add a new page / hub / detail / wizard / dashboard" | **Yes** |
+| "rebuild / redesign / replace / redo / refresh / modernize / re-imagine X" | **Yes** |
+| "make a new version of X" / "instead of what we have currently" / "from scratch" | **Yes** |
+| "design X" / "how should I build X" / "make it modern" | **Yes** |
+| User attaches a screenshot, mockup, Figma link, or legacy app capture | **Yes** |
+| "Move that button up two pixels" / "change copy" / "fix the type error" | **No** |
+| "Bump dep" / "ESLint pass" / "single-class restyle of a DS-compliant page" | **No** |
+| "Add a column to the existing HubTable" / "another filter chip" | **No** *(unless IA changes)* |
+
+When in doubt, ask yourself: **"Am I deciding what this surface should be,
+or am I editing what's already decided?"** Decide → load. Edit → don't.
+
+## Hard gate (read this if you remember nothing else)
+
+If you loaded this skill, your **next message must be the design brief**
+(template in §3.1). It must NOT also contain `write_file` / `str_replace`
+/ `create_file` / edit tool calls. End the turn after the brief with
+"Ready to build — confirm or edit." The user's reply is your green light.
+
+Silence, a thumbs-up, or "ok" all count as confirmation. A new design
+question or "actually let's change X" means revise the brief, don't build.
 
 ## Mindset (5 lines, memorize)
 
@@ -38,7 +60,11 @@ restyles of an existing surface that already follows DS rules.
 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)
+## The five-step protocol (mandatory on any surface decision)
+
+The five steps are **sequential checkpoints**, not a single turn. Each
+checkpoint ends with you yielding to the user — except step 4 (Build) and
+step 5 (Audit), which run together.
 
 ### 1. Discovery — ask, infer, or state assumptions
 
@@ -50,10 +76,37 @@ 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.
+assumptions.
 
 ### 2. Research — recognize the pattern, don't reinvent
 
+Run research **before posting the brief in step 3**, so the brief can name
+specific references. (See research methods below.)
+
+### 3. Synthesis — post the brief and STOP
+
+After research, post the brief (template below). **End your turn here** with
+the explicit prompt:
+
+> *Ready to build — confirm or edit.*
+
+Do **not** call any code-mutating tool (`write_file`, `str_replace`,
+`create_file`, `edit_notebook`, MCP write tools) in this turn. The user's
+next message is your green light.
+
+Acceptable confirmations:
+
+- Plain `yes`, `proceed`, `ship it`, `LGTM`, `build it`, `go ahead`.
+- Implicit acceptance — a follow-up question that assumes the brief
+  (e.g. "and add a section for X").
+- Silence followed by a new design question — treat as accepted.
+
+If the user replies with edits ("change the pattern to a sheet", "drop the
+timeline section"), revise the brief and post again. Only build after a
+confirmed brief.
+
+### Research methods (used inside step 2)
+
 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**
@@ -67,7 +120,7 @@ assumptions, then build.
 5. Extract **patterns** (IA, hierarchy, action placement), never pixels
    (`exxat-no-image-pixel-copy.mdc`).
 
-### 3. Synthesis — output a one-screen brief
+### 3.1 Brief template (copy verbatim into chat)
 
 ```
 Problem:            <one sentence — the user's pain, not the feature>
@@ -82,7 +135,7 @@ 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.
+End the turn with: *Ready to build — confirm or edit.*
 
 ### 4. Build — compose, don't invent
 

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exxatdesignux/ui",
-  "version": "0.5.10",
+  "version": "0.5.11",
   "description": "Exxat shared design system (components, hooks, tokens). Monorepo setup: clone repo then pnpm bootstrap at workspace root — see github.com/ExxatDesign/Exxat-DS-Workspace README.",
   "license": "UNLICENSED",
   "author": "Exxat Design",