@open-mercato/ui 0.5.1-develop.2856.35de414092 → 0.5.1-develop.2874.77704bccbd

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
 Generated lucide registry with 134 icons -> /home/runner/work/open-mercato/open-mercato/packages/ui/src/backend/icons/lucideRegistry.generated.tsx
-[build:ui] found 264 entry points
+[build:ui] found 270 entry points
 [build:ui] built successfully

package/AGENTS.md

@@ -1,125 +1,213 @@
 # UI Package - Agent Guidelines
 
-This document captures UI usage patterns based on current implementations in the customers, sales, and staff (auth users/roles) modules. Use these as the default conventions when building new UI in `packages/ui` or when consuming UI components from other modules.
+UI usage patterns based on customers, sales, and staff modules. Use these defaults when building new UI in `packages/ui` or consuming from other modules.
+
+> **DS reference:** [`.ai/ds-rules.md`](../../.ai/ds-rules.md) — color tokens, typography, spacing, decision trees. **Component reference (variants/sizes/props/examples/MUST rules):** [`.ai/ui-components.md`](../../.ai/ui-components.md).
 
 ## Reference Modules
 
-- Customers: `packages/core/src/modules/customers/backend/customers/people/create/page.tsx`, `packages/core/src/modules/customers/backend/customers/people/page.tsx`, `packages/core/src/modules/customers/components/detail/TaskForm.tsx`
-- Sales: `packages/core/src/modules/sales/components/documents/SalesDocumentsTable.tsx`, `packages/core/src/modules/sales/components/documents/PaymentsSection.tsx`, `packages/core/src/modules/sales/components/documents/SalesDocumentForm.tsx`
-- Staff (auth users/roles): `packages/core/src/modules/auth/backend/users/page.tsx`, `packages/core/src/modules/auth/backend/users/create/page.tsx`, `packages/core/src/modules/auth/backend/roles/create/page.tsx`
+- Customers: `packages/core/src/modules/customers/backend/customers/people/create/page.tsx`, `…/people/page.tsx`, `…/components/detail/TaskForm.tsx`
+- Sales: `packages/core/src/modules/sales/components/documents/SalesDocumentsTable.tsx`, `…/PaymentsSection.tsx`, `…/SalesDocumentForm.tsx`
+- Staff: `packages/core/src/modules/auth/backend/users/page.tsx`, `…/users/create/page.tsx`, `…/roles/create/page.tsx`
+
+## Component quick reference
+
+When you need… use this. Details (variants, sizes, props, MUST rules) live in [`.ai/ui-components.md`](../../.ai/ui-components.md).
+
+| Need | Component | Import |
+|---|---|---|
+| Button with text label (with or without icon) | `Button` | `@open-mercato/ui/primitives/button` |
+| Icon-only button | `IconButton` | `@open-mercato/ui/primitives/icon-button` |
+| Inline link styled as button | `LinkButton` | `@open-mercato/ui/primitives/link-button` |
+| OAuth/sign-in button (brand-styled) | `SocialButton` | `@open-mercato/ui/primitives/social-button` |
+| Marketing CTA with brand gradient | `FancyButton` | `@open-mercato/ui/primitives/fancy-button` |
+| Checkbox primitive (with indeterminate) | `Checkbox` | `@open-mercato/ui/primitives/checkbox` |
+| Checkbox with label + description | `CheckboxField` | `@open-mercato/ui/primitives/checkbox-field` |
+| User / entity avatar | `Avatar`, `AvatarStack` | `@open-mercato/ui/primitives/avatar` |
+| Keyboard shortcut keys | `Kbd`, `KbdShortcut` | `@open-mercato/ui/primitives/kbd` |
+| Entity tag pill | `Tag` (with `TagMap`) | `@open-mercato/ui/primitives/tag` |
+| Wrap a `<Link>` as button | `Button asChild` / `IconButton asChild` | — |
+
+## Critical MUST rules (top of mind)
+
+1. **NEVER use raw `<button>` or `<input type="checkbox">`** — always use the primitives. Native checkboxes get `accent-color: var(--accent-indigo)` as a safety net for legacy code, but new code MUST use `Checkbox`.
+2. **Always pass `type="button"` explicitly** on non-submit `Button`/`IconButton` — HTML defaults to `submit`.
+3. **Same-row buttons MUST share `size`.** Mixing `sm` (h-8) + `default`/`icon` (h-9) is a regression. Standardized rows: DataTable toolbar = `default`/`icon` h-9, FormActionButtons = `default` h-9.
+4. **NEVER raw `<Link>` styled as a button** — wrap with `<Button asChild>` to inherit size + radius.
+5. **`<Button className="h-9">` is an anti-pattern** — redundant with default size, hides contract from grep.
+6. **`Checkbox` checked color is `--accent-indigo` (NOT `--primary`)** — matches Figma and distinguishes selection from primary actions.
 
-## Button and IconButton Usage
+## CrudForm Guidelines
 
-**MUST use `Button` or `IconButton` from `@open-mercato/ui` for every interactive button.** Never use raw `<button>` elements.
+- Use `CrudForm` as the default for create/edit flows and dialog forms.
+- If a backend page cannot use `CrudForm`, use `useGuardedMutation` from `@open-mercato/ui/backend/injection/useGuardedMutation` for every write (`POST`/`PUT`/`PATCH`/`DELETE`).
+- Always call writes through `runMutation({ operation, context, mutationPayload })` so global injection modules (e.g. record-lock conflict handling) can run `onBeforeSave`/`onAfterSave`, apply scoped headers, and receive errors consistently.
+- Use manual `useInjectionSpotEvents(GLOBAL_MUTATION_INJECTION_SPOT_ID)` only when `useGuardedMutation` is insufficient.
+- Keep `CrudForm` reusable — extract shared field/group builders and submit handlers into module-level helpers.
+- Drive validation with Zod and surface field errors via `createCrudFormError`.
+- With `CrudForm` + Zod, validation messages may be i18n keys (`CrudForm` translates them).
+- If you validate outside `CrudForm` or manually map `safeParse(...).error.issues`, you MUST translate `issue.message` before passing to `createCrudFormError`.
+- Keep `fields` and `groups` in memoized helpers.
+- Pass `entityIds` when custom fields are involved.
+- Use `createCrud`/`updateCrud`/`deleteCrud` for submit actions and call `flash()` for success/failure messaging.
 
-### When to Use Which
+## UI Interaction
+- Every new dialog must support `Cmd/Ctrl + Enter` as a primary action shortcut and `Escape` to cancel, mirroring the shared UX patterns used across modules.
+- Default to `CrudForm` for new forms and `DataTable` for tables displaying information unless a different component is explicitly required.
+- Use the `EventSelect` component from `@open-mercato/ui/backend/inputs/EventSelect` for event selection. It fetches declared events via the `/api/events` endpoint.
+- Never use `window.confirm` — use the shared `ConfirmDialog` and `useConfirmDialog` from `@open-mercato/ui/backend/confirm-dialog` for confirmation flows.
+- New CRUD forms should use `CrudForm` wired to CRUD factory/commands APIs and be shared between create/edit flows.
+- Prefer reusing components from the shared `packages/ui` package before introducing new UI primitives.
+- For new `DataTable` columns, set `meta.truncate` and `meta.maxWidth` in the column config when you need specific truncation behavior; only rely on defaults when those are not set.
+- When you create new UI check reusable components before creating UI from scratch (see [`.ai/specs/implemented/SPEC-001-2026-01-21-ui-reusable-components.md`](.ai/specs/implemented/SPEC-001-2026-01-21-ui-reusable-components.md))
+- For form/detail page headers and footers, use `FormHeader` and `FormFooter` from `@open-mercato/ui/backend/forms`. `FormHeader` supports two modes: `edit` (compact, used automatically by CrudForm) and `detail` (large title with entity type label, status badge, Actions dropdown). Delete/Cancel/Save are always standalone buttons; additional context actions (Convert, Send, etc.) go into the `menuActions` array rendered as an "Actions" dropdown. See [SPEC-016](.ai/specs/implemented/SPEC-016-2026-02-03-form-headers-footers.md) for full API.
 
-| Use case | Component | Example |
-|----------|-----------|---------|
-| Button with text label (with or without icon) | `Button` | Save, Cancel, Apply filters |
-| Icon-only button (no visible text) | `IconButton` | Close ✕, Settings ⚙, Trash 🗑 |
-| Button wrapping a `<Link>` | `IconButton asChild` or `Button asChild` | `<IconButton asChild><Link href="...">...</Link></IconButton>` |
+## Avatar
 
-### Imports
+`Avatar` displays a user or entity with a photo or auto-generated initials. `AvatarStack` overlaps multiple avatars with an overflow indicator.
+
+### Import
 
 ```typescript
-import { Button } from '@open-mercato/ui/primitives/button'
-import { IconButton } from '@open-mercato/ui/primitives/icon-button'
+import { Avatar, AvatarStack } from '@open-mercato/ui/primitives/avatar'
 ```
 
-### MUST Rules
+### Sizes
 
-1. **MUST always pass `type="button"` explicitly** on non-submit buttons. Neither `Button` nor `IconButton` sets a default type — HTML defaults to `type="submit"`, which causes accidental form submissions.
-2. **MUST NOT use raw `<button>` elements** anywhere in the codebase. Use `Button` or `IconButton` instead.
-3. **MUST use `IconButton`** (not `Button size="icon"`) for icon-only buttons. `IconButton` has fixed square dimensions optimized for icon-only content.
-4. **MUST add `hover:bg-transparent`** when using `variant="ghost"` for tab-style buttons with underline indicators, to suppress the default hover background.
-5. **MUST add `h-auto`** when using Button/IconButton in compact inline contexts (tag chips, toolbars, inline lists) where the fixed height from size variants would overflow the container.
+| Size | px | Use case |
+|---|---|---|
+| `sm` | 24px | Table rows, AvatarStack, inline lists |
+| `default` | 32px | Default — sidebar, comments, activity feed |
+| `md` | 40px | Section headers, assignee cards |
+| `lg` | 80px | Profile / detail page header |
 
-### Variant Reference
+### Usage
 
-**Button variants**: `default` (primary CTA), `destructive` (danger), `outline` (bordered), `secondary` (subdued), `ghost` (no border/bg), `muted` (dimmed text, ghost-like), `link` (underlined text).
+```tsx
+// Photo
+<Avatar src="/avatars/jan.jpg" name="Jan Kowalski" size="md" />
+
+// Initials (auto-generated from name)
+<Avatar name="Jan Kowalski" />        // → "JK"
+<Avatar name="Copperleaf Design" />   // → "CD"
+
+// Stack with overflow
+<AvatarStack max={3}>
+  <Avatar name="Jan Kowalski" size="sm" />
+  <Avatar name="Oliwia Z." size="sm" />
+  <Avatar name="Anna Nowak" size="sm" />
+  <Avatar name="Sarah Mitchell" size="sm" />
+</AvatarStack>
+// renders: JK · OZ · AN · +1
+```
 
-**Button sizes**: `default` (h-9 px-4), `sm` (h-8 px-3), `lg` (h-10 px-6), `icon` (size-9, square).
+### MUST rules
 
-**IconButton variants**: `outline` (bordered, default), `ghost` (no border/bg).
+- NEVER render `<div className="rounded-full bg-muted ...">` for avatars — use `Avatar`
+- `size="sm"` uses `text-[9px]` — DS exception for tiny initials (same as notification badge count)
+- `ring-2 ring-background` is built-in — provides the border needed for `AvatarStack` overlap
+- For unknown users or empty states: render `<Avatar />` (shows blank muted circle)
 
-**IconButton sizes**: `xs` (size-6 / 24px), `sm` (size-7 / 28px), `default` (size-8 / 32px), `lg` (size-9 / 36px).
+---
 
-### Common Patterns
+## Kbd
+
+`Kbd` renders a keyboard key. `KbdShortcut` renders a full shortcut sequence (`⌘ + Enter`).
+
+Use in dialog footers, tooltips, and empty states to communicate keyboard affordances required by our UX rules (every dialog MUST support `Cmd/Ctrl+Enter` submit and `Escape` cancel).
+
+### Import
+
+```typescript
+import { Kbd, KbdShortcut } from '@open-mercato/ui/primitives/kbd'
+```
+
+### Usage
 
 ```tsx
-// Sidebar / nav toggle
-<IconButton variant="outline" size="sm" type="button" onClick={toggle} aria-label="Toggle sidebar">
-  <PanelLeft className="size-4" />
-</IconButton>
-
-// Close / dismiss button
-<IconButton variant="ghost" size="sm" type="button" onClick={onClose} aria-label="Close">
-  <X className="size-4" />
-</IconButton>
-
-// Tab navigation (underline style)
-<Button
-  type="button"
-  variant="ghost"
-  size="sm"
-  className={cn(
-    'h-auto rounded-none border-b-2 px-0 py-1 hover:bg-transparent',
-    isActive ? 'border-primary text-foreground' : 'border-transparent text-muted-foreground'
-  )}
->
-  {label}
-</Button>
-
-// Dropdown menu item
-<Button variant="ghost" size="sm" type="button" className="w-full justify-start" role="menuitem">
-  <Icon className="size-4" /> {label}
-</Button>
-
-// Compact toolbar button (rich text editor)
-<Button variant="ghost" size="sm" type="button" className="h-auto px-2 py-0.5 text-xs">
-  Bold
-</Button>
-
-// Collapsible section header
-<Button variant="muted" type="button" className="w-full justify-between" onClick={toggle}>
-  <span>{sectionLabel}</span>
-  <ChevronDown className={cn('size-4 transition-transform', open && 'rotate-180')} />
-</Button>
-
-// Link-styled icon button (wrapping Next.js Link)
-<IconButton asChild variant="ghost" size="sm">
-  <Link href="/backend/settings">
-    <Settings className="size-4" />
-  </Link>
-</IconButton>
+// Single key
+<Kbd>Esc</Kbd>
+<Kbd>⌘</Kbd>
+
+// Shortcut sequence
+<KbdShortcut keys={['⌘', 'Enter']} />   // renders: ⌘ + Enter
+<KbdShortcut keys={['Ctrl', 'S']} />
+
+// In a dialog footer hint
+<span className="text-xs text-muted-foreground">
+  Press <KbdShortcut keys={['⌘', 'Enter']} /> to save or <Kbd>Esc</Kbd> to cancel
+</span>
 ```
 
-## CrudForm Guidelines
+### MUST rules
 
-- Use `CrudForm` as the default for create/edit flows and for dialog forms.
-- If a backend page cannot use `CrudForm`, use `useGuardedMutation` from `@open-mercato/ui/backend/injection/useGuardedMutation` for every write operation (`POST`/`PUT`/`PATCH`/`DELETE`).
-- Always call writes through `runMutation({ operation, context, mutationPayload })` so global injection modules (for example record-lock conflict handling) can run `onBeforeSave`/`onAfterSave`, apply scoped request headers, and receive mutation errors consistently.
-- Use manual `useInjectionSpotEvents(GLOBAL_MUTATION_INJECTION_SPOT_ID)` wiring only when you need behavior that `useGuardedMutation` does not support.
-- Keep `CrudForm` implementations reusable: extract shared field/group builders and submit handlers into module-level helpers when multiple pages or dialogs need the same shape.
-- Drive validation with a Zod schema and surface field errors via `createCrudFormError`.
-- When using `CrudForm` with Zod, validation messages may be i18n keys because `CrudForm` translates them before display.
-- If you validate outside `CrudForm` or manually map `safeParse(...).error.issues`, you MUST translate `issue.message` before passing it to `createCrudFormError` or rendering it in the UI.
-- Keep `fields` and `groups` in memoized helpers (see customers person form config).
-- Pass `entityIds` when custom fields are involved so form helpers load correct custom-field sets.
-- Use `createCrud`/`updateCrud`/`deleteCrud` for submit actions and call `flash()` for success or failure messaging.
-- For multi-step submit flows, keep the form submit handler focused and move secondary operations (like extra address writes) into isolated helpers with per-item error handling.
+- NEVER use raw `<span>` or `<code>` to display keyboard keys — use `Kbd`
+- Platform-specific keys (`⌘` vs `Ctrl`): detect with `navigator.platform` or use `Ctrl/⌘` text when cross-platform
 
-## UI Interaction
-- Every new dialog must support `Cmd/Ctrl + Enter` as a primary action shortcut and `Escape` to cancel, mirroring the shared UX patterns used across modules.
-- Default to `CrudForm` for new forms and `DataTable` for tables displaying information unless a different component is explicitly required.
-- Use the `EventSelect` component from `@open-mercato/ui/backend/inputs/EventSelect` for event selection. It fetches declared events via the `/api/events` endpoint.
-- Never use `window.confirm` — use the shared `ConfirmDialog` and `useConfirmDialog` from `@open-mercato/ui/backend/confirm-dialog` for confirmation flows.
-- New CRUD forms should use `CrudForm` wired to CRUD factory/commands APIs and be shared between create/edit flows.
-- Prefer reusing components from the shared `packages/ui` package before introducing new UI primitives.
-- For new `DataTable` columns, set `meta.truncate` and `meta.maxWidth` in the column config when you need specific truncation behavior; only rely on defaults when those are not set.
-- When you create new UI check reusable components before creating UI from scratch (see [`.ai/specs/implemented/SPEC-001-2026-01-21-ui-reusable-components.md`](.ai/specs/implemented/SPEC-001-2026-01-21-ui-reusable-components.md))
-- For form/detail page headers and footers, use `FormHeader` and `FormFooter` from `@open-mercato/ui/backend/forms`. `FormHeader` supports two modes: `edit` (compact, used automatically by CrudForm) and `detail` (large title with entity type label, status badge, Actions dropdown). Delete/Cancel/Save are always standalone buttons; additional context actions (Convert, Send, etc.) go into the `menuActions` array rendered as an "Actions" dropdown. See [SPEC-016](.ai/specs/implemented/SPEC-016-2026-02-03-form-headers-footers.md) for full API.
+---
+
+## Tag
+
+`Tag` is a static pill element representing a user-applied label on an entity (e.g. "Customer", "Hot", "Renewal"). Use it for entity tags — NOT for system status display (use `StatusBadge` for that).
+
+### Tag vs StatusBadge
+
+| | `Tag` | `StatusBadge` |
+|---|---|---|
+| Purpose | User-applied label / category | System status (active, pending, failed…) |
+| Shape | `rounded-full` pill | `rounded-full` pill |
+| Dot | optional (`dot` prop) | optional (`dot` prop) |
+| `brand` variant | ✅ (violet — for custom views/renewal tags) | ❌ |
+
+### Import
+
+```typescript
+import { Tag } from '@open-mercato/ui/primitives/tag'
+import type { TagMap } from '@open-mercato/ui/primitives/tag'
+```
+
+### Variants
+
+| Variant | Token | Example use |
+|---|---|---|
+| `default` | `border-border bg-background text-muted-foreground` | Generic / inactive tag |
+| `success` | `status-success-*` | Customer, Shipped, Active |
+| `warning` | `status-warning-*` | Renewal, At risk |
+| `error` | `status-error-*` | Hot, Overdue, Blocked |
+| `info` | `status-info-*` | Pending, In review |
+| `neutral` | `status-neutral-*` | Archived, Draft |
+| `brand` | `brand-violet/10` bg, `brand-violet/30` border, `text-brand-violet` | Custom views, Perspectives |
+
+### Usage
+
+```tsx
+<Tag variant="success" dot>Customer</Tag>
+<Tag variant="error" dot>Hot</Tag>
+<Tag variant="brand" dot>Renewal Q1 2026</Tag>
+<Tag variant="neutral">Inactive</Tag>
+```
+
+### TagMap helper
+
+```typescript
+import type { TagMap } from '@open-mercato/ui/primitives/tag'
+
+const leadTagMap: TagMap<'customer' | 'hot' | 'inactive' | 'renewal'> = {
+  customer: 'success',
+  hot: 'error',
+  inactive: 'neutral',
+  renewal: 'brand',
+}
+
+<Tag variant={leadTagMap[tag.type]} dot>{tag.label}</Tag>
+```
+
+### MUST rules
+
+- NEVER hardcode colors on `Tag` — use variants only
+- Use `dot` for tags that represent a status-like category (Customer, Hot); omit for purely descriptive labels
+- For "Manage tags" / add-tag affordances: use a `Button variant="ghost"` or dashed outline — NOT `Tag`
+- `brand` variant is for user-saved views and renewal/custom category tags only (see brand color rules in root AGENTS.md)
 
 ## DataTable Guidelines
 
@@ -129,10 +217,10 @@ import { IconButton } from '@open-mercato/ui/primitives/icon-button'
 - Populate `columns` with explicit renderers and set `meta.truncate`/`meta.maxWidth` where truncation is needed.
 - For filters, use `FilterBar`/`FilterOverlay` with async option loaders; keep `pageSize` at or below 100.
 - Support exports using `buildCrudExportUrl` and pass `exportOptions` to `DataTable`.
-- Use `RowActions` for per-row actions and include navigation via `onRowClick` or action links.
+- Use `RowActions` for per-row actions; navigate via `onRowClick` or action links.
 - Keep table state (paging, sorting, filters, search) in component state and reload on scope changes.
-- Keep `extensionTableId` stable and deterministic; host pages should not derive it from transient UI state.
-- Render injected row actions and bulk actions through `RowActions`/bulk action handlers so injected actions follow the same guard and i18n behavior as built-ins.
+- Keep `extensionTableId` stable and deterministic.
+- Render injected row actions and bulk actions through `RowActions`/bulk handlers so they follow the same guard and i18n behavior as built-ins.
 
 ## CrudForm Field Injection (UMES Phase G)
 
@@ -142,37 +230,37 @@ import { IconButton } from '@open-mercato/ui/primitives/icon-button'
 
 ## Menu Injection (UMES Phase A/B)
 
-- Use `useInjectedMenuItems(surfaceId)` to load declarative menu widgets for chrome surfaces (`menu:sidebar:*`, `menu:topbar:*`).
+- Use `useInjectedMenuItems(surfaceId)` for chrome surfaces (`menu:sidebar:*`, `menu:topbar:*`).
 - Merge built-in and injected items with `mergeMenuItems(builtIn, injected)` to preserve deterministic placement.
-- For relative positioning, rely on `InjectionPosition` + `relativeTo` IDs; if `relativeTo` is missing, insertion falls back to append.
-- Treat injected labels as i18n-first: prefer `labelKey` (with human fallback `label`) and `groupLabelKey` (with optional `groupLabel`) so keys never leak to UI.
-- Add stable attributes (`data-menu-item-id="<id>"`) when rendering merged items so integration tests can assert injected entries reliably.
-- When filtering menu items by `item.features` or route `requireFeatures`, MUST use the shared wildcard-aware matcher from `@open-mercato/shared/lib/auth/featureMatch`; do not rely on `Set.has(...)` or exact `includes(...)` checks because role grants may be `module.*`.
+- For relative positioning, use `InjectionPosition` + `relativeTo` IDs; if `relativeTo` is missing, insertion falls back to append.
+- Treat injected labels as i18n-first: prefer `labelKey` (with human fallback `label`) and `groupLabelKey`.
+- Add stable attributes (`data-menu-item-id="<id>"`) when rendering merged items so integration tests can assert injected entries.
+- When filtering menu items by `item.features` or route `requireFeatures`, MUST use the shared wildcard-aware matcher from `@open-mercato/shared/lib/auth/featureMatch` — `Set.has(...)`/`includes(...)` miss `module.*` grants.
 
 ## Loading, Empty, and Error States
 
 - For list/detail data loading, use `LoadingMessage` and `ErrorMessage` from `@open-mercato/ui/backend/detail`.
 - For record-backed backend detail/edit pages, treat `notFound` as a dedicated page state, separate from generic `error`.
-- When a record is missing, return early with a page-level state built on `ErrorMessage` and a clear recovery action such as "Back to list"; do not render `CrudForm`, detail sections, tabs, or record actions in that branch.
-- Do not use ad hoc centered `<div>` error markup for missing-record pages when the shared backend detail primitives can express the state.
-- Use `TabEmptyState` when a section is empty but otherwise healthy (see sales document sub-sections).
-- Keep loading flags local to the section and reset errors before each load.
+- When a record is missing, return early with a page-level `ErrorMessage` and a clear recovery action ("Back to list"); do not render `CrudForm`, detail sections, tabs, or record actions.
+- Don't use ad hoc centered `<div>` error markup when shared backend detail primitives can express the state.
+- Use `TabEmptyState` when a section is empty but otherwise healthy.
+- Keep loading flags local to the section; reset errors before each load.
 
 ## Flash Messages
 
 - Use `flash(message, 'success' | 'error')` from `@open-mercato/ui/backend/FlashMessages` for user feedback after CRUD operations.
-- Prefer specific translation keys and keep the message copy in module locale files.
-- For non-blocking errors in side effects (for example, creating secondary records), show a flash error and allow the main flow to complete.
+- Prefer specific translation keys; keep message copy in module locale files.
+- For non-blocking errors in side effects (e.g. creating secondary records), show a flash error and let the main flow complete.
 
 ## Notifications
 
 - Define notification types in `src/modules/<module>/notifications.ts` and client renderers in `notifications.client.ts`.
 - Define reactive notification handlers in `src/modules/<module>/notifications.handlers.ts` when notifications should trigger automatic side-effects.
 - Renderers live in `widgets/notifications/` and should use `useT()` for copy.
-- Use the shared action labels where possible (for example, `notifications.actions.dismiss`).
-- Prefer notification creation in commands or subscribers and keep UI renderers lightweight.
+- Use shared action labels where possible (e.g. `notifications.actions.dismiss`).
+- Prefer notification creation in commands or subscribers; keep UI renderers lightweight.
 - For component-scoped reactions, use `useNotificationEffect(notificationType, effect)` instead of module-specific polling loops.
-- When gating notification handlers or other UI runtime registries by `features`, MUST use the shared wildcard-aware matcher; `module.*` grants must enable matching handlers, sections, and actions.
+- When gating notification handlers by `features`, MUST use the shared wildcard-aware matcher.
 
 ## Component Reuse
 
@@ -184,7 +272,7 @@ import { IconButton } from '@open-mercato/ui/primitives/icon-button'
 
 ## Component Replacement (UMES Phase H)
 
-- When a host surface is replacement-aware, resolve implementations via `useRegisteredComponent(handle, Fallback)` instead of hardcoded component references.
+- When a host surface is replacement-aware, resolve implementations via `useRegisteredComponent(handle, Fallback)` instead of hardcoded references.
 - Prefer additive override modes (`wrapper`, `props`) before full `replace`; reserve `replace` for cases where compatibility is preserved.
 - Keep handle IDs stable and document them when introducing new replacement-aware surfaces.
 
@@ -204,7 +292,7 @@ The portal extensibility system lets app modules build customer-facing pages tha
 
 ### Portal Shell (`packages/ui/src/portal/PortalShell.tsx`)
 
-Shared layout with header, nav (built-in + injected), main content, and footer. Supports event bridge and component replacement handles.
+Shared layout with header, nav (built-in + injected), main, footer. Supports event bridge and component replacement handles.
 
 ```tsx
 import { PortalShell } from '@open-mercato/ui/portal/PortalShell'
@@ -224,8 +312,8 @@ function MyPage({ orgSlug }) {
 
 | Spot ID | Purpose |
 |---------|---------|
-| `menu:portal:sidebar:main` | Main portal navigation items |
-| `menu:portal:sidebar:account` | Account/settings navigation items |
+| `menu:portal:sidebar:main` | Main portal navigation |
+| `menu:portal:sidebar:account` | Account/settings navigation |
 | `menu:portal:header:actions` | Header action buttons |
 | `menu:portal:user-dropdown` | User dropdown menu items |
 
@@ -288,10 +376,7 @@ Reference: see `packages/core/src/modules/portal/frontend/[orgSlug]/portal/{dash
 
 ### Declarative Customer Role Features in setup.ts
 
-Modules can declare features to be merged into customer role ACLs:
-
 ```typescript
-// setup.ts
 export const setup: ModuleSetupConfig = {
   defaultCustomerRoleFeatures: {
     buyer: ['portal.orders.view', 'portal.orders.create'],
@@ -305,12 +390,10 @@ export const setup: ModuleSetupConfig = {
 Events with `portalBroadcast: true` are streamed to authenticated portal users via `/api/customer_accounts/portal/events/stream`.
 
 ```typescript
-// events.ts
 const events = [
   { id: 'sales.order.status_changed', label: 'Order Status Changed', portalBroadcast: true },
 ] as const
 
-// In portal component
 import { usePortalAppEvent } from '@open-mercato/ui/portal/hooks/usePortalAppEvent'
 usePortalAppEvent('sales.order.status_changed', (event) => { refetch() })
 ```

package/dist/backend/AppShell.js

@@ -7,6 +7,7 @@ import Image from "next/image";
 import { ChevronUp, ChevronDown } from "lucide-react";
 import { Button } from "../primitives/button.js";
 import { IconButton } from "../primitives/icon-button.js";
+import { Checkbox } from "../primitives/checkbox.js";
 import { FlashMessages } from "./FlashMessages.js";
 import { QueryProvider } from "../theme/QueryProvider.js";
 import { usePathname, useSearchParams } from "next/navigation";
@@ -564,7 +565,7 @@ function AppShellBody({ productName, logo, email, groups, rightHeaderSlot, child
     setSelectedRoleIds((prev) => prev.includes(roleId) ? prev.filter((id) => id !== roleId) : [...prev, roleId]);
   }, []);
   const asideWidth = effectiveCollapsed ? "72px" : expandedSidebarWidth;
-  const asideClassesBase = `border-r bg-background/60 py-4 min-h-svh`;
+  const asideClassesBase = `border-r bg-background/80 py-4 min-h-svh`;
   React.useEffect(() => {
     try {
       localStorage.setItem("om:sidebarCollapsed", collapsed ? "1" : "0");
@@ -703,18 +704,18 @@ function AppShellBody({ productName, logo, email, groups, rightHeaderSlot, child
         ] }) }) : null,
         /* @__PURE__ */ jsxs("div", { className: "flex flex-1 flex-col gap-3 pr-1", children: [
           /* @__PURE__ */ jsxs("div", { className: "space-y-3", children: [
-            /* @__PURE__ */ jsx("div", { className: "h-8 rounded bg-muted/60" }),
+            /* @__PURE__ */ jsx("div", { className: "h-8 rounded bg-muted/50" }),
             /* @__PURE__ */ jsxs("div", { className: "space-y-2 pl-1", children: [
               /* @__PURE__ */ jsx("div", { className: "h-8 rounded bg-muted/50" }),
-              /* @__PURE__ */ jsx("div", { className: "h-8 rounded bg-muted/40" }),
-              /* @__PURE__ */ jsx("div", { className: "h-8 rounded bg-muted/40" })
+              /* @__PURE__ */ jsx("div", { className: "h-8 rounded bg-muted/50" }),
+              /* @__PURE__ */ jsx("div", { className: "h-8 rounded bg-muted/50" })
             ] })
           ] }),
           /* @__PURE__ */ jsxs("div", { className: "space-y-3", children: [
-            /* @__PURE__ */ jsx("div", { className: "h-8 rounded bg-muted/60" }),
+            /* @__PURE__ */ jsx("div", { className: "h-8 rounded bg-muted/50" }),
             /* @__PURE__ */ jsxs("div", { className: "space-y-2 pl-1", children: [
-              /* @__PURE__ */ jsx("div", { className: "h-8 rounded bg-muted/40" }),
-              /* @__PURE__ */ jsx("div", { className: "h-8 rounded bg-muted/40" })
+              /* @__PURE__ */ jsx("div", { className: "h-8 rounded bg-muted/50" }),
+              /* @__PURE__ */ jsx("div", { className: "h-8 rounded bg-muted/50" })
             ] })
           ] })
         ] })
@@ -778,12 +779,10 @@ function AppShellBody({ productName, logo, email, groups, rightHeaderSlot, child
               /* @__PURE__ */ jsx("span", { className: "text-xs font-medium text-muted-foreground", children: placeholder }),
               /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
                 /* @__PURE__ */ jsx(
-                  "input",
+                  Checkbox,
                   {
-                    type: "checkbox",
-                    className: "h-4 w-4 accent-foreground",
                     checked: !hidden,
-                    onChange: (event) => setItemHidden(itemKey, !event.target.checked),
+                    onCheckedChange: (next) => setItemHidden(itemKey, next !== true),
                     disabled: savingPreferences,
                     "aria-label": t("appShell.sidebarCustomizationShowItem"),
                     title: t("appShell.sidebarCustomizationShowItem")
@@ -796,7 +795,7 @@ function AppShellBody({ productName, logo, email, groups, rightHeaderSlot, child
                     onChange: (event) => setItemLabel(itemKey, event.target.value),
                     placeholder,
                     disabled: savingPreferences,
-                    className: "h-8 flex-1 rounded border bg-background px-2 text-sm shadow-sm focus:outline-none focus:ring-2 focus:ring-ring disabled:opacity-60"
+                    className: "h-8 flex-1 rounded border bg-background px-2 text-sm shadow-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
                   }
                 )
               ] }),
@@ -807,7 +806,7 @@ function AppShellBody({ productName, logo, email, groups, rightHeaderSlot, child
         );
       });
     };
-    const customizationEditor = customizing ? customDraft ? /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-3 rounded border border-dashed bg-muted/20 p-3", children: [
+    const customizationEditor = customizing ? customDraft ? /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-3 rounded border border-dashed bg-muted/30 p-3", children: [
       /* @__PURE__ */ jsxs("div", { className: "flex flex-wrap items-center justify-between gap-2", children: [
         /* @__PURE__ */ jsx("div", { className: "text-sm font-semibold", children: t("appShell.sidebarCustomizationHeading") }),
         /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
@@ -844,7 +843,7 @@ function AppShellBody({ productName, logo, email, groups, rightHeaderSlot, child
         ] })
       ] }),
       /* @__PURE__ */ jsx("p", { className: "text-xs text-muted-foreground", children: t("appShell.sidebarCustomizationHint", { locale: localeLabel }) }),
-      canApplyToRoles ? /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-2 rounded border bg-background/70 p-3 shadow-sm", children: [
+      canApplyToRoles ? /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-2 rounded border bg-background/80 p-3 shadow-sm", children: [
         /* @__PURE__ */ jsxs("div", { children: [
           /* @__PURE__ */ jsx("div", { className: "text-sm font-semibold", children: t("appShell.sidebarApplyToRolesTitle") }),
           /* @__PURE__ */ jsx("p", { className: "text-xs text-muted-foreground", children: t("appShell.sidebarApplyToRolesDescription") })
@@ -852,14 +851,12 @@ function AppShellBody({ productName, logo, email, groups, rightHeaderSlot, child
         availableRoleTargets.length > 0 ? /* @__PURE__ */ jsx("div", { className: "flex flex-col gap-2", children: availableRoleTargets.map((role) => {
           const checked = selectedRoleIds.includes(role.id);
           const willClear = role.hasPreference && !checked;
-          return /* @__PURE__ */ jsxs("label", { className: "flex items-center gap-2 rounded border bg-background px-2 py-1 text-sm shadow-sm", children: [
+          return /* @__PURE__ */ jsxs("label", { className: "flex items-center gap-2 rounded-md border bg-background px-2 py-1 text-sm shadow-sm cursor-pointer", children: [
             /* @__PURE__ */ jsx(
-              "input",
+              Checkbox,
               {
-                type: "checkbox",
-                className: "h-4 w-4 accent-foreground",
                 checked,
-                onChange: () => toggleRoleSelection(role.id),
+                onCheckedChange: () => toggleRoleSelection(role.id),
                 disabled: savingPreferences
               }
             ),
@@ -886,7 +883,7 @@ function AppShellBody({ productName, logo, email, groups, rightHeaderSlot, child
                   onChange: (event) => setGroupLabel(groupId, event.target.value),
                   placeholder,
                   disabled: savingPreferences,
-                  className: "mt-1 h-8 w-full rounded border bg-background px-2 text-sm shadow-sm focus:outline-none focus:ring-2 focus:ring-ring disabled:opacity-60"
+                  className: "mt-1 h-8 w-full rounded border bg-background px-2 text-sm shadow-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
                 }
               )
             ] }),
@@ -920,7 +917,7 @@ function AppShellBody({ productName, logo, email, groups, rightHeaderSlot, child
           /* @__PURE__ */ jsx("div", { className: "flex flex-col gap-2", children: renderEditableItems(baseGroup.items, currentGroup.items) })
         ] }, groupId);
       }) })
-    ] }) : /* @__PURE__ */ jsx("div", { className: "rounded border border-dashed bg-muted/20 p-3 text-sm text-muted-foreground", children: t("appShell.sidebarCustomizationLoading") }) : null;
+    ] }) : /* @__PURE__ */ jsx("div", { className: "rounded border border-dashed bg-muted/30 p-3 text-sm text-muted-foreground", children: t("appShell.sidebarCustomizationLoading") }) : null;
     return /* @__PURE__ */ jsxs("div", { className: "flex flex-col min-h-full gap-3", children: [
       !hideHeader && /* @__PURE__ */ jsx("div", { className: `flex items-center ${compact ? "justify-center" : "justify-between"} mb-2`, children: /* @__PURE__ */ jsxs(Link, { href: "/backend", className: "flex items-center gap-2", "aria-label": t("appShell.goToDashboard"), children: [
         /* @__PURE__ */ jsx(Image, { src: logo?.src ?? "/open-mercato.svg", alt: logo?.alt ?? resolvedProductName, width: 32, height: 32, className: "rounded m-4" }),
@@ -1041,7 +1038,7 @@ function AppShellBody({ productName, logo, email, groups, rightHeaderSlot, child
           })
         ] }) });
       })() }),
-      /* @__PURE__ */ jsxs("div", { className: "sticky bottom-0 pt-4 border-t bg-background/60 backdrop-blur-sm pb-1", children: [
+      /* @__PURE__ */ jsxs("div", { className: "sticky bottom-0 pt-4 border-t bg-background/80 backdrop-blur-sm pb-1", children: [
         shouldRenderSidebarInjectionSpots ? /* @__PURE__ */ jsx(
           InjectionSpot,
           {
@@ -1149,7 +1146,7 @@ function AppShellBody({ productName, logo, email, groups, rightHeaderSlot, child
     /* @__PURE__ */ jsxs("div", { className: `min-h-svh lg:grid ${gridColsClass}`, children: [
       /* @__PURE__ */ jsx("aside", { className: `${asideClassesBase} ${effectiveCollapsed ? "px-2" : "px-3"} hidden lg:block`, style: { width: asideWidth }, children: renderSidebar(effectiveCollapsed) }),
       /* @__PURE__ */ jsxs("div", { className: "flex min-h-svh flex-col min-w-0", children: [
-        /* @__PURE__ */ jsxs("header", { className: "border-b bg-background/60 px-3 lg:px-4 py-2 lg:py-3 flex items-center justify-between gap-2", children: [
+        /* @__PURE__ */ jsxs("header", { className: "border-b bg-background/80 px-3 lg:px-4 py-2 lg:py-3 flex items-center justify-between gap-2", children: [
           /* @__PURE__ */ jsx(
             "div",
             {
@@ -1217,8 +1214,8 @@ function AppShellBody({ productName, logo, email, groups, rightHeaderSlot, child
             rightHeaderSlot ? rightHeaderSlot : /* @__PURE__ */ jsx("span", { className: "opacity-80", children: email || t("appShell.userFallback") })
           ] })
         ] }),
-        /* @__PURE__ */ jsx(ProgressTopBar, { t, className: "sticky top-0 z-10" }),
-        /* @__PURE__ */ jsxs("main", { className: "flex-1 p-4 lg:p-6", children: [
+        /* @__PURE__ */ jsx(ProgressTopBar, { t, className: "sticky top-0 z-sticky" }),
+        /* @__PURE__ */ jsxs("main", { className: "flex-1 p-4 lg:p-6 mx-auto w-full max-w-screen-2xl", children: [
           /* @__PURE__ */ jsx(InjectionSpot, { spotId: BACKEND_LAYOUT_TOP_INJECTION_SPOT_ID, context: injectionContext }),
           /* @__PURE__ */ jsx(FlashMessages, {}),
           /* @__PURE__ */ jsx(PartialIndexBanner, {}),
@@ -1236,7 +1233,7 @@ function AppShellBody({ productName, logo, email, groups, rightHeaderSlot, child
           children,
           /* @__PURE__ */ jsx(InjectionSpot, { spotId: BACKEND_LAYOUT_FOOTER_INJECTION_SPOT_ID, context: injectionContext })
         ] }),
-        /* @__PURE__ */ jsxs("footer", { className: "border-t bg-background/80 backdrop-blur supports-[backdrop-filter]:bg-background/50 px-4 py-3 flex flex-wrap items-center justify-end gap-4", children: [
+        /* @__PURE__ */ jsxs("footer", { className: "border-t bg-background/80 backdrop-blur supports-[backdrop-filter]:bg-background/80 px-4 py-3 flex flex-wrap items-center justify-end gap-4", children: [
           version ? /* @__PURE__ */ jsx("span", { className: "text-xs text-muted-foreground", children: t("appShell.version", { version }) }) : null,
           /* @__PURE__ */ jsxs("nav", { className: "flex items-center gap-3 text-xs text-muted-foreground", children: [
             /* @__PURE__ */ jsx(Link, { href: "/terms", className: "transition hover:text-foreground", children: t("common.terms") }),
@@ -1244,8 +1241,8 @@ function AppShellBody({ productName, logo, email, groups, rightHeaderSlot, child
           ] })
         ] })
       ] }),
-      mobileOpen && /* @__PURE__ */ jsxs("div", { className: "lg:hidden fixed inset-0 z-50", children: [
-        /* @__PURE__ */ jsx("div", { className: "absolute inset-0 bg-black/40", onClick: () => setMobileOpen(false), "aria-hidden": "true" }),
+      mobileOpen && /* @__PURE__ */ jsxs("div", { className: "lg:hidden fixed inset-0 z-modal", children: [
+        /* @__PURE__ */ jsx("div", { className: "absolute inset-0 bg-black/20", onClick: () => setMobileOpen(false), "aria-hidden": "true" }),
         /* @__PURE__ */ jsxs("aside", { className: "absolute left-0 top-0 flex h-full w-[260px] flex-col bg-background border-r overflow-hidden", children: [
           /* @__PURE__ */ jsxs("div", { className: "shrink-0 p-3 pb-2 flex items-center justify-between border-b", children: [
             /* @__PURE__ */ jsxs(Link, { href: "/backend", className: "flex items-center gap-2 text-sm font-semibold", onClick: () => setMobileOpen(false), "aria-label": t("appShell.goToDashboard"), children: [