@exxatdesignux/ui 0.5.4 → 0.5.5

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.5.5
+
+### Patch Changes
+
+- **New consumer agent rules (vendored via `sync-extras`):** `exxat-no-image-pixel-copy` (uploaded screenshots = IA only — never pixel-copy colors/chrome), `exxat-sidebar-shell` (DS `AppSidebar` chrome; no legacy rainbow nav styling).
+- **`exxat-ds-agents` §33–§34**, **`exxat-reuse-before-custom`**, **`exxat-token-economy` Q9** — image discipline + sidebar guardrails wired into pre-flight.
+- **`consumer-upgrade-checklist.md`** and **`reference-implementations.md`** — audit rows for screenshot copying and legacy sidebar anti-patterns.
+
 ## 0.5.4
 
 ### Patch Changes

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

@@ -45,6 +45,8 @@ Before implementing or reviewing **list / table / board / dashboard / data-heavy
 30. **Tabs chrome** — **`exxat-tabs-chrome.mdc`** — hub views = **`ListPageTemplate`** toolbar (`w-max`); record tabs = **`TabsList`** `w-fit`, never full-width stretch.
 31. **Page header actions** — **`exxat-page-header-actions.mdc`** — filled primary + outline overflow; no hand-built grey buttons.
 32. **Table row preview** — **`exxat-table-row-preview.mdc`** — **`HoverCard`** + DS badges/cells; no bespoke popover cards.
+33. **Sidebar shell** — **`exxat-sidebar-shell.mdc`** + **`AGENTS.md` §9.1** — legacy screenshots = **IA only**; **MUST NOT** copy rainbow section styling or fork **`app-sidebar.tsx`**.
+34. **Uploaded images** — **`exxat-no-image-pixel-copy.mdc`** — screenshots = intent/IA only; map to DS patterns; never pixel-copy.
 
 ## Also read
 

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-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?
 

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exxatdesignux/ui",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "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",

package/template/docs/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?
 

package/template/docs/reference-implementations.md

@@ -129,6 +129,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`](../../../.cursor/rules/exxat-sidebar-shell.mdc) |
+| Uploaded screenshots / mockups treated as pixel spec | Images show **intent** (labels, fields, flows) — DS blueprints + reference hubs define **implementation** | [`exxat-no-image-pixel-copy.mdc`](../../../.cursor/rules/exxat-no-image-pixel-copy.mdc) + **`component-selection-guide.md`** |
 
 ---
 

package/template/lib/mock/navigation.tsx

@@ -15,7 +15,7 @@ import {
 
 // ── Types ─────────────────────────────────────────────────────────────────────
 
-/** Flat sidebar link (screenshot: primary + Documents + utilities) */
+/** Flat sidebar link — primary + Documents + utilities groups (DS shell; not legacy screenshot styling) */
 export interface NavLinkItem {
   key: string
   title: string

package/tokens/hooks-index.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.5.4",
+  "version": "0.5.5",
   "source": "packages/ui/src/globals.css",
-  "generatedAt": "2026-05-22T11:42:41.710Z",
+  "generatedAt": "2026-05-22T12:39:10.883Z",
   "tokenCount": 197,
   "themeKeys": [
     "tailwind-bridge",