@exxatdesignux/ui 0.5.5 → 0.5.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exxatdesignux/ui",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "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/src/components/data-table/index.tsx

@@ -797,7 +797,9 @@ function DataTableInner<TData extends Record<string, unknown>>({
   } = state
 
   // Mount overflow check + scrollport width for sticky group headers on horizontal scroll.
-  React.useEffect(() => {
+  // Re-run when column widths / visibility change — scrollWidth alone is unreliable when
+  // the table used to stretch with `w-full` (scrollWidth === clientWidth even with many cols).
+  React.useLayoutEffect(() => {
     const syncScrollport = () => {
       const el = scrollRef.current
       if (el) {
@@ -810,9 +812,10 @@ function DataTableInner<TData extends Record<string, unknown>>({
     if (!el) return
     const ro = new ResizeObserver(syncScrollport)
     ro.observe(el)
+    const table = el.querySelector("table")
+    if (table) ro.observe(table)
     return () => ro.disconnect()
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [])
+  }, [totalWidth, displayCols.length, checkOverflow])
 
   /** Pending action queued from a column-menu item that should run *after* the menu
    * has fully closed. The Properties drawer is a non-modal Radix Sheet (`modal=false`)
@@ -1109,11 +1112,12 @@ function DataTableInner<TData extends Record<string, unknown>>({
         )}
       >
         <table
-          className="w-full text-sm border-separate border-spacing-0"
+          className="text-sm border-separate border-spacing-0"
           style={{
             tableLayout: "fixed",
-            minWidth: totalWidth,
-            width: headerIsStuck ? floatingHeaderTableWidth : undefined,
+            // Explicit column-sum width — `w-full` made the grid stretch to the scrollport
+            // so scrollWidth === clientWidth and the overflow-gated pin rule never fired.
+            width: totalWidth,
           }}
         >
           <colgroup>

package/src/components/data-table/use-table-state.ts

@@ -536,23 +536,6 @@ export function useTableState<TData extends Record<string, unknown>>(
       .map(([key, groupRows]) => ({ groupKey: key, groupLabel: key, rows: groupRows }))
   }, [rows, groupBy])
 
-  // ── Effective pins (respect overflow) ─────────────────────────────────────
-  const LOCKED_KEYS = React.useMemo(() => new Set(Object.keys(lockedPins)), [lockedPins])
-
-  // When the table fits within its container (not overflowing) there is no need
-  // to sticky-pin any column — even locked ones.  Pins only activate once the
-  // user has to scroll horizontally so the selection / action edges stay visible.
-  // In reflow viewports (high zoom), disable all column stickies — shadow + sticky
-  // fight the short viewport and overlap content.
-  const effectivePins = React.useMemo(() => {
-    if (isReflowViewport || !isOverflowing) return {}
-    const result: Record<string, "left" | "right"> = {}
-    for (const [key, pin] of Object.entries(colPins)) {
-      result[key] = pin
-    }
-    return result
-  }, [colPins, isOverflowing, isReflowViewport])
-
   // ── Display columns ───────────────────────────────────────────────────────
   const displayCols = React.useMemo(() => {
     const leftPinned: string[] = []
@@ -574,6 +557,28 @@ export function useTableState<TData extends Record<string, unknown>>(
     return out
   }, [colOrder, colPins, hiddenCols, columnsByKey])
 
+  const totalWidth = React.useMemo(
+    () => displayCols.reduce((s, c) => s + (colWidths[c.key] ?? c.width ?? 100), 0),
+    [displayCols, colWidths],
+  )
+
+  // ── Effective pins (respect overflow) ─────────────────────────────────────
+  const LOCKED_KEYS = React.useMemo(() => new Set(Object.keys(lockedPins)), [lockedPins])
+
+  // When the table fits within its container (not overflowing) there is no need
+  // to sticky-pin any column — even locked ones.  Pins only activate once the
+  // user has to scroll horizontally so the selection / action edges stay visible.
+  // In reflow viewports (high zoom), disable all column stickies — shadow + sticky
+  // fight the short viewport and overlap content.
+  const effectivePins = React.useMemo(() => {
+    if (isReflowViewport || !isOverflowing) return {}
+    const result: Record<string, "left" | "right"> = {}
+    for (const [key, pin] of Object.entries(colPins)) {
+      result[key] = pin
+    }
+    return result
+  }, [colPins, isOverflowing, isReflowViewport])
+
   // ── Column actions ────────────────────────────────────────────────────────
   function startResize(key: string, e: React.MouseEvent) {
     e.preventDefault()
@@ -629,19 +634,26 @@ export function useTableState<TData extends Record<string, unknown>>(
   }
 
   // ── Scroll handlers ───────────────────────────────────────────────────────
-  function checkOverflow() {
+  const checkOverflow = React.useCallback(() => {
     const el = scrollRef.current
     if (!el) return
-    setIsOverflowing(el.scrollWidth > el.clientWidth + 1)
-  }
+    // Compare declared column width to scrollport — not scrollWidth, which matched
+    // clientWidth when the table stretched with `w-full`.
+    setIsOverflowing(totalWidth > el.clientWidth + 1)
+  }, [totalWidth])
+
   function handleScroll() {
     const el = scrollRef.current
     if (!el) return
     setScrolled(el.scrollLeft > 1)
     setScrollEnd(el.scrollLeft >= el.scrollWidth - el.clientWidth - 1)
-    setIsOverflowing(el.scrollWidth > el.clientWidth + 1)
+    setIsOverflowing(totalWidth > el.clientWidth + 1)
   }
 
+  React.useLayoutEffect(() => {
+    checkOverflow()
+  }, [checkOverflow])
+
   // ── Selection helpers ─────────────────────────────────────────────────────
   function getRowId(row: TData, index: number, getIdFn?: (r: TData, i: number) => string | number): string | number {
     return getIdFn ? getIdFn(row, index) : (row.id as string | number ?? index)
@@ -711,11 +723,6 @@ export function useTableState<TData extends Record<string, unknown>>(
     [effectivePins, isReflowViewport, stickyOffsets],
   )
 
-  const totalWidth = React.useMemo(
-    () => displayCols.reduce((s, c) => s + (colWidths[c.key] ?? c.width ?? 100), 0),
-    [displayCols, colWidths],
-  )
-
   return {
     // Sort
     sortRules, setSortRules,

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

package/template/docs/jobs/record-detail.md

@@ -0,0 +1,177 @@
+# Job: Review a record's full state
+
+> **Surface type:** Standalone route OR side-panel sheet.
+> **Examples in product:** Student profile, Placement record, Library item,
+> Site profile, Team member profile.
+
+## 1. The job
+
+The user lands on a single record and needs to **understand its current
+state** in order to **decide what to do next**. Decisions can include:
+contact someone, edit a field, change status, place / unplace, archive,
+follow up later, or simply confirm correctness before another action.
+
+This job is **not**: edit (separate flow), bulk action (lives on the list),
+configure workspace settings.
+
+## 2. When this job applies
+
+- The record has > ~5 displayable fields.
+- The user reaches it from a list, search, deep link, or notification.
+- The user's next action depends on the record's state (status, ownership,
+  data freshness).
+- The record may have children (placements, attachments, comments) that
+  matter to the decision.
+
+## 3. Pattern: route vs sheet vs inline
+
+| Pattern | When | DS comp |
+|---------|------|---------|
+| **Standalone route** (`/students/[id]`) | Deep link from email / notifications / reports; user may keep tab open; record has > 10 fields | `PrimaryPageTemplate` + `PageHeader` |
+| **Sheet over hub** | User is triaging from a list and may open many records in sequence | `Sheet` over `ListPageTemplate` |
+| **Inline expansion** (`HoverCard`) | Read-only quick preview; < 5 fields | `HoverCard` on row hover |
+
+Pick **route** by default. Pick **sheet** if the user's primary path is
+triaging from a list and they typically open many in a single session.
+
+## 4. Information architecture
+
+```
+┌─ SiteHeader (breadcrumb only) ──────────────────────────────────┐
+│  Dashboard › Students › Jordan Lee                              │  ← ancestors + title (P1, P2)
+└──────────────────────────────────────────────────────────────────┘
+┌─ Identity row ──────────────────────────────────────────────────┐
+│  [Avatar] Jordan Lee                              [Edit] [⋯]    │  ← name, ID, primary action + overflow
+│          STU-2026-1042 · jordan.lee@example.edu                 │
+└──────────────────────────────────────────────────────────────────┘
+┌─ Status row (above the fold, P13) ──────────────────────────────┐
+│  ● Active   ✓ Compliant   ⊕ Placed at Sinai                     │
+└──────────────────────────────────────────────────────────────────┘
+┌─ Field groups (2-col card grid) ────────────────────────────────┐
+│  Program     │  Academic                                         │
+│  Placement   │  Compliance                                       │
+└──────────────────────────────────────────────────────────────────┘
+┌─ Activity timeline (M7, optional) ──────────────────────────────┐
+│  Today · Compliance status updated by Maria                      │
+│  Tue · Placement assigned · Sinai Hospital                       │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### Layers, in priority order
+
+1. **Identity** — name, system ID (mono), avatar, primary contact link.
+2. **Status** — every status badge that drives a decision; visible without
+   scrolling (P13).
+3. **Field groups** — 2-column card grid by default. Group by **conceptual
+   coherence** (Program / Academic / Placement / Compliance), not by table
+   structure.
+4. **Activity timeline** — if the record changes over time and the history
+   matters (M7).
+5. **Related lists** — placements, comments, attachments — if they exist for
+   this entity.
+
+### When to use section tabs
+
+- **Don't tab** if total field count is ≤ ~20 and groups are ≤ 4. Single
+  scroll is faster.
+- **Do tab** if the record has rich children (placements history,
+  supervisors, contracts, conversation threads) and the user typically
+  deep-dives into one section.
+- Tabs use `Tabs` + `TabsList` `w-fit` `variant="line"` — never full-width
+  (`exxat-tabs-chrome.mdc`).
+
+## 5. Navigation — the way back
+
+**Exactly one path back** (P1).
+
+| Reached from | Way back |
+|--------------|----------|
+| List route | `SiteHeader` breadcrumb (`Students`) |
+| Deep link / email | `SiteHeader` breadcrumb to the canonical parent |
+| Sheet from hub | `Sheet` close (X / Esc) |
+| Notification | Breadcrumb to canonical parent (not "Back to notification") |
+
+**Never** add a body-level "Back to <parent>" button when the breadcrumb is
+present (`exxat-breadcrumbs-no-back.mdc`).
+
+## 6. Actions
+
+| Slot | Component | What goes here |
+|------|-----------|----------------|
+| Primary | `PageHeader.primaryAction` (`Button variant="default" size="lg"`) | The single most common next action — "Edit", "Place", "Approve" |
+| Overflow | `Button variant="outline" size="icon-lg"` → `DropdownMenu` | Export, Archive, Duplicate, Share, dangerous-but-rare actions |
+| Inline | Icon-only buttons with tooltip | Copy email, dial phone, open site |
+| Status flip | `Sheet` or inline `Select` | Status changes that are audited (multi-step) |
+
+Exactly **one** filled CTA per surface (P3).
+
+## 7. States
+
+| State | What to show |
+|-------|--------------|
+| **Loading** | `Skeleton` matching the IA shape (identity → status → cards) — M9 |
+| **Empty / not found** | `EmptyState` + "Return to <list>" outline button |
+| **Error** | `LocalBanner` inside the body; identity row still renders if available |
+| **Stale data** | Subtle "Updated <relative>" in identity meta |
+
+## 8. Accessibility
+
+- One `<h1>` (P2) — typically `PageHeader.title`.
+- Status row is a `role="list"`; each badge is `role="listitem"` (already in
+  `ListHubStatusBadge`).
+- Inline mailto / tel links are real `<a>`s, not buttons.
+- Tab order: breadcrumb → identity → primary action → overflow → status →
+  fields → activity → related.
+- Icon-only actions carry `aria-label` + a tooltip with the same text.
+
+## 9. Modern SaaS analogues
+
+| Product | What to study |
+|---------|---------------|
+| **Linear** issue detail | Identity + status + properties + activity; sheet variant for triage |
+| **Stripe Dashboard** customer / charge | Identity + status badges + grouped data + audit log |
+| **Notion** page-as-database row | Inline editing (M5), property panel |
+| **Plain / Pylon** ticket | Conversation-as-document for support records |
+
+Cite these in the design brief by name + Mx codes:
+`Linear issue detail (M1, M4, M7)`.
+
+## 10. Anti-patterns
+
+| Anti-pattern | Use instead |
+|--------------|-------------|
+| `<h1>` + `PageHeader title` + breadcrumb leaf all repeating the name | One carrier: `PageHeader title` + ancestors-only breadcrumb (P2) |
+| "Back to <parent>" button alongside the breadcrumb | Breadcrumb only (P1) |
+| Two filled CTAs in the header ("Save" + "Submit") | One filled, others outline (P3) |
+| Status only in detail (hidden on list / breadcrumb count) | Status visible everywhere the record appears (M4) |
+| Status communicated by color only | Color + icon + label (`ListHubStatusBadge`) |
+| Full-width section tab bar | `Tabs` `w-fit` (`exxat-tabs-chrome.mdc`) |
+| Centered modal for "Edit name" | Inline edit (M5) or `Sheet` (M3) |
+| Spinner overlay for initial load | `Skeleton` matched to IA (M9) |
+| Activity timeline buried in a tab nobody opens | Show inline below cards, or remove it |
+| New shared "ProfileHero" component invented per entity | Compose: `PageHeader` + identity-row primitives (P8) |
+| `toast()` on save | Inline button label change + `LocalBanner` if persistent |
+
+## 11. Quick checklist (post-build audit)
+
+- [ ] Breadcrumb shows ancestors + title; no duplicate name.
+- [ ] No body "Back to <parent>" button.
+- [ ] One H1.
+- [ ] Status row visible without scrolling.
+- [ ] One filled primary action; overflow has the rest.
+- [ ] 2-col card grid for fields (or tabs if ≥ 4 sections / 20+ fields).
+- [ ] `Skeleton` matches the IA on load; empty state designed for "not found".
+- [ ] Tab order: breadcrumb → identity → primary → overflow → fields.
+- [ ] All status chips use `ListHubStatusBadge` + `lib/list-status-badges.ts`.
+- [ ] No `toast()`, no Vaul, no pixel-copy of legacy.
+
+## 12. Reference
+
+- [`../../../.cursor/skills/exxat-senior-ux/SKILL.md`](../../../.cursor/skills/exxat-senior-ux/SKILL.md)
+- [`../../../.cursor/rules/exxat-ux-discovery-protocol.mdc`](../../../.cursor/rules/exxat-ux-discovery-protocol.mdc)
+- [`../../../.cursor/rules/exxat-ux-principles.mdc`](../../../.cursor/rules/exxat-ux-principles.mdc)
+- [`../../../.cursor/rules/exxat-breadcrumbs-no-back.mdc`](../../../.cursor/rules/exxat-breadcrumbs-no-back.mdc)
+- [`../../../.cursor/rules/exxat-tabs-chrome.mdc`](../../../.cursor/rules/exxat-tabs-chrome.mdc)
+- [`../modern-saas-patterns.md`](../modern-saas-patterns.md)
+- [`../blueprints/page-header.md`](../blueprints/page-header.md)
+- [`../component-selection-guide.md`](../component-selection-guide.md) §1

package/template/docs/modern-saas-patterns.md

@@ -0,0 +1,165 @@
+# Modern SaaS patterns — the canon Exxat DS works against
+
+> **Audience:** humans + AI agents.
+> **Companion to:** [`exxat-senior-ux/SKILL.md`](../../../.cursor/skills/exxat-senior-ux/SKILL.md),
+> [`exxat-ux-principles.mdc`](../../../.cursor/rules/exxat-ux-principles.mdc),
+> [`jobs/`](./jobs/).
+
+A senior designer recognizes the work. This doc names the patterns the best
+products converged on in 2024–2026, so the agent can pattern-match instead
+of inventing. **Cite by name + code** when you reference one in a design brief
+(e.g. `Linear issue detail (M1, M4, M7)`).
+
+## Canon products — cite by product, not by URL
+
+| Product | What to learn from it |
+|---------|-----------------------|
+| **Linear** | Issue detail, command palette spine, density, keyboard-first, presence, "less chrome" |
+| **Notion** | Inline editing, property panels, page-as-database, blocks, slash-commands |
+| **Stripe Dashboard** | Record home, status chips, activity log, money-grade precision |
+| **Figma** | Multiplayer, presence, side panel inspector, infinite-canvas chrome discipline |
+| **Vercel** | Type-first hierarchy, dark-first, minimal chrome, log streams |
+| **Height** | View tabs (table/board/timeline), custom fields, view parity |
+| **Plain / Pylon** | Support detail = identity + timeline + actions; conversation-as-document |
+| **Cron / Amie** | Keyboard-only flows, dense calendar, command surface |
+| **Raycast** | Command palette as full app, extension surface, deep keyboard |
+| **Arc Browser** | Control-stripped, content-first, sidebar as the only chrome |
+
+## The 12 patterns that make products feel modern
+
+### M1. Content-first chrome
+The data is the star. Sidebars collapse to icons. Headers stay 48–56px. Page
+surfaces are generous. No purple gradient on the top bar.
+
+- **In DS:** `SiteHeader` ~h-12; `PrimaryPageTemplate` body has generous
+  `max-w-[1440px]`; sidebar collapsible (`SidebarTrigger`).
+
+### M2. Command palette as the spine
+`⌘K` opens search + navigation + AI + recent. It is the primary navigation
+for power users. The sidebar exists for orientation, not speed.
+
+- **In DS:** `CommandMenu` (⌘K) + Ask Leo split (⌘⌥K).
+  Rule: `exxat-command-menu.mdc`.
+
+### M3. Side-panel detail over modal dialog
+For non-destructive context-keeping actions (properties, export, invite,
+preview, single-step compose), use a slide-in sheet — never a centered modal.
+
+- **In DS:** `Sheet` (no Vaul).
+  Rule: `exxat-drawer-vs-dialog.mdc`. Pattern:
+  `apps/web/docs/drawer-vs-dialog-pattern.md`.
+
+### M4. Status as a first-class citizen
+Colored dots, chips, counts visible everywhere data appears. Status isn't
+hidden in a detail page; it appears on rows, cards, headers, navigation.
+
+- **In DS:** `ListHubStatusBadge` + `lib/list-status-badges.ts`. Available per
+  row, board card, detail header, breadcrumb count slot.
+
+### M5. Inline editing where data is read
+Click the value, edit it. No bounce to forms for single-field changes.
+
+- **In DS:** Inline-edit primitive emerging; until then, use a `Sheet` for
+  multi-field, popover or contenteditable for single-field. Principle: P15.
+
+### M6. Optimistic UI + undo
+Low-risk actions (favorite, archive, status flip) feel instant; reconcile on
+error. Undo via banner or in-place affordance — **never** toast
+(`exxat-no-toast.mdc`).
+
+- **In DS:** Optimistic state in `useTableState` selection ops; undo via
+  `LocalBanner` with action.
+
+### M7. Activity timeline on every record
+Who did what when. The audit log is also a navigation device.
+
+- **In DS:** `ActivityTimeline` primitive emerging. Compose from
+  `lib/mock/activity` shape until then.
+
+### M8. Empty states with one CTA + one sentence
+Illustration optional. One sentence of context. One primary action. Never a
+wall of help text or a tutorial inline.
+
+- **In DS:** `EmptyState` primitive; voice from `docs/voice-and-tone.md`.
+
+### M9. Skeleton, not spinner
+Loading shapes content. Spinners only for indeterminate < 200ms.
+
+- **In DS:** `Skeleton` primitive; suspense boundaries shape the body.
+
+### M10. Type-first hierarchy
+Weight, size, color do the heavy lifting before borders, boxes, or tints.
+Ornament is rare and intentional.
+
+- **In DS:** Token scale; body in `Inter`; display in `Ivy Presto` (only on
+  `PageHeader` H1 by default).
+
+### M11. Real-time presence + collaboration as default
+If the product is shared, show who else is here — face rails, cursors,
+status. Inviting others is one click from the page.
+
+- **In DS:** `PageHeader variant="collaboration"` face rail +
+  `InviteCollaboratorsDrawer`.
+  Rule: `exxat-collaboration-access.mdc`.
+
+### M12. AI as opt-in sidecar
+Ask Leo style — never the primary path, never auto-runs on a record, always
+discoverable, always cancellable. Deterministic path still exists.
+
+- **In DS:** `AskLeoSidebar` + `⌘⌥K` toggle; never a "magic" button on a
+  destructive surface.
+
+---
+
+## The anti-modern signals (what NOT to do)
+
+| Signal | Why it's dated |
+|--------|----------------|
+| Toasts everywhere | Modern products use inline + banner + undo. Toasts get missed. |
+| Full-width tab bars stretched edge-to-edge | 2010s pattern. Modern uses `w-fit` segmented controls. |
+| Centered modals for everything | Sheets and routes carry more without breaking flow. |
+| Color-coded sidebar sections | Modern is monochrome chrome + status color on data. |
+| Modal wizards with progress bar | If it has > 3 steps, give it a route. |
+| Spinners on initial load | Skeleton the content shape instead. |
+| Hover-only affordances | Touch + keyboard need parity. |
+| Icons without text labels in primary nav | Recognition fails for new users. |
+| "Beautiful" gradients on chrome | Data should be beautiful; chrome should disappear. |
+| Aggressive empty-state illustrations | One sentence + one action beats illustration + 5 tips. |
+| Edit-takes-you-to-a-form for single fields | Inline edit (M5). |
+| "Back to <parent>" button alongside breadcrumb | P1 — choose one. |
+| Auto-running AI on record open | M12 — opt-in only. |
+
+---
+
+## Density layers (Linear / Vercel model)
+
+| Layer | When |
+|-------|------|
+| **Cozy** (default) | Most surfaces; balances scan + breathing room |
+| **Compact** | Power users on daily workflow; tables, command results |
+| **Comfortable** | Accessibility (low-vision, motor); marketing-adjacent |
+
+Provide a user-level setting where audiences differ; default to **cozy**.
+Don't fork stacks per density.
+
+---
+
+## How to use this doc in a design brief
+
+```
+Reference (modern): Linear issue detail (M1, M4, M7),
+                    Stripe customer record (M4, M11)
+```
+
+Cite the **patterns (Mx)** the agent applied, not just the product. Forces
+clear thinking and lets reviewers verify intent.
+
+## See also
+
+- [`../../../.cursor/skills/exxat-senior-ux/SKILL.md`](../../../.cursor/skills/exxat-senior-ux/SKILL.md) — persona
+- [`../../../.cursor/rules/exxat-ux-discovery-protocol.mdc`](../../../.cursor/rules/exxat-ux-discovery-protocol.mdc) — brief gate
+- [`../../../.cursor/rules/exxat-ux-principles.mdc`](../../../.cursor/rules/exxat-ux-principles.mdc) — principles + breaks
+- [`./jobs/`](./jobs/) — canonical reference per job type
+- [`./component-selection-guide.md`](./component-selection-guide.md) — picking the composition
+- [`./blueprints/`](./blueprints/) — framework-agnostic surface specs
+- [`./voice-and-tone.md`](./voice-and-tone.md) — copy rules

package/tokens/hooks-index.json

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