@tailor-platform/app-shell 1.7.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/app-shell",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "An opinionated React application framework for building ERP applications on Tailor Platform",
   "keywords": [
     "app-shell",
@@ -44,13 +44,15 @@
   },
   "dependencies": {
     "@base-ui/react": "^1.5.0",
+    "@internationalized/date": "3.12.2",
     "@standard-schema/spec": "^1.1.0",
-    "@tailor-platform/auth-public-client": "^0.5.0",
+    "@tailor-platform/auth-public-client": "^0.5.1",
     "change-case": "^5.4.4",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "encoding-japanese": "^2.2.0",
     "lucide-react": "^1.8.0",
+    "openai": "6.45.0",
     "papaparse": "^5.5.3",
     "react-router": "^7.14.1",
     "sonner": "^2.0.7",

package/skills/app-shell-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: app-shell-patterns
-description: UI pattern catalog for building pages with @tailor-platform/app-shell components
+description: "Best-practice UI patterns and correct component usage for building pages in apps that use @tailor-platform/app-shell. Use when: building or editing any screen, page, list, table, detail view, form, modal, dialog, wizard, or bulk/confirm/toast interaction in an app with @tailor-platform/app-shell installed — or when choosing the right AppShell component, layout, or design token for a UI."
 ---
 
 # App-Shell Patterns
@@ -13,41 +13,41 @@ Select and implement the correct UI pattern using @tailor-platform/app-shell com
 
 These are the foundational rules that underpin all patterns. All patterns build on top of these references.
 
-| File | Description |
-| ---- | ----------- |
-| [components.md](references/fundamental/components.md) | components reference |
+| File                                                        | Description             |
+| ----------------------------------------------------------- | ----------------------- |
+| [components.md](references/fundamental/components.md)       | components reference    |
 | [design-system.md](references/fundamental/design-system.md) | design-system reference |
-| [graphql.md](references/fundamental/graphql.md) | graphql reference |
+| [graphql.md](references/fundamental/graphql.md)             | graphql reference       |
 
 ## Available Patterns
 
 ### detail
 
-| Slug | Name | Description |
-| ---- | ---- | ----------- |
+| Slug                                                                          | Name                     | Description                                                           |
+| ----------------------------------------------------------------------------- | ------------------------ | --------------------------------------------------------------------- |
 | [`detail/hero-with-actions`](references/patterns/detail-hero-with-actions.md) | Hero With Actions Detail | Single-record detail view with workflow actions and activity timeline |
 
 ### form
 
-| Slug | Name | Description |
-| ---- | ---- | ----------- |
-| [`form/modal`](references/patterns/form-modal.md) | Modal Form | Default form pattern for Create/Edit — keeps user in context on the parent screen |
-| [`form/sectioned`](references/patterns/form-sectioned.md) | Sectioned Form | Complex form with 15+ fields organized into named fieldset sections |
-| [`form/single-page`](references/patterns/form-single-page.md) | Single Page Form | Routed full-page form for moderate field count (6-15) without natural sectioning |
-| [`form/wizard`](references/patterns/form-wizard.md) | Wizard Form | Multi-stage create flow with 3-7 steps and per-step validation gates |
+| Slug                                                          | Name             | Description                                                                       |
+| ------------------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------- |
+| [`form/modal`](references/patterns/form-modal.md)             | Modal Form       | Default form pattern for Create/Edit — keeps user in context on the parent screen |
+| [`form/sectioned`](references/patterns/form-sectioned.md)     | Sectioned Form   | Complex form with 15+ fields organized into named fieldset sections               |
+| [`form/single-page`](references/patterns/form-single-page.md) | Single Page Form | Routed full-page form for moderate field count (6-15) without natural sectioning  |
+| [`form/wizard`](references/patterns/form-wizard.md)           | Wizard Form      | Multi-stage create flow with 3-7 steps and per-step validation gates              |
 
 ### interaction
 
-| Slug | Name | Description |
-| ---- | ---- | ----------- |
-| [`interaction/confirm`](references/patterns/interaction-confirm.md) | Confirm | Confirmation dialog before destructive or irreversible actions |
-| [`interaction/multi-select`](references/patterns/interaction-multi-select.md) | Multi Select | Floating bottom action bar for bulk operations on selected list rows |
-| [`interaction/toast`](references/patterns/interaction-toast.md) | Toast | Lightweight feedback after mutations — success or error notifications |
+| Slug                                                                          | Name         | Description                                                           |
+| ----------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------- |
+| [`interaction/confirm`](references/patterns/interaction-confirm.md)           | Confirm      | Confirmation dialog before destructive or irreversible actions        |
+| [`interaction/multi-select`](references/patterns/interaction-multi-select.md) | Multi Select | Floating bottom action bar for bulk operations on selected list rows  |
+| [`interaction/toast`](references/patterns/interaction-toast.md)               | Toast        | Lightweight feedback after mutations — success or error notifications |
 
 ### list
 
-| Slug | Name | Description |
-| ---- | ---- | ----------- |
+| Slug                                                        | Name            | Description                                                                                             |
+| ----------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------- |
 | [`list/dense-scan`](references/patterns/list-dense-scan.md) | Dense Scan List | High-density scannable list backed by GraphQL connections with DataTable, sort, filters, and pagination |
 
 ## How to Use
@@ -65,3 +65,15 @@ These are the foundational rules that underpin all patterns. All patterns build
 - NEVER mix patterns in a single page component
 - ALWAYS use AppShell components — do NOT use raw HTML or third-party UI libraries
 - If no entry matches, compose directly from fundamental references
+
+### Cross-cutting UX rules (apply to every screen)
+
+Full rationale in [`design-system.md`](references/fundamental/design-system.md) → Composition & emphasis rules.
+
+- **One primary action per view:** at most one primary/filled `Button`; everything else is `outline`/`secondary`/`ghost`.
+- **Status badges by semantic color:** a **filled** semantic variant for the record's primary/lifecycle status, **`outline-*`** for secondary statuses, **`subtle-*`** for tags; reserve brand `default` for non-status emphasis.
+- **No duplicate actions:** an action lives in exactly one place — never repeat the same action in both `Layout.Header` and `ActionPanel`.
+- **Action placement:** primary CTA + status in `Layout.Header`; workflow actions in `ActionPanel`; back/navigation in the breadcrumb — never in `ActionPanel`.
+- **Metric tiles always go in a `Grid`** (`columns={{ initial: 1, md: 2, xl: 4 }}`) — never one-per-row.
+- **Forms default to `form/modal`** — only build a routed full-page form when the design explicitly calls for one.
+- **Handle every state:** loading (skeleton), empty (labelled empty state), and error (inline + retry) — never ship only the happy path.

package/skills/app-shell-patterns/references/fundamental/components.md

@@ -1,6 +1,6 @@
 # AppShell Components
 
-> **AppShell version:** `0.36.0` (matches `packages/erp-kit/templates/scaffold/app/*/frontend/package.json` pinned `@tailor-platform/app-shell` semver)
+> **AppShell version:** `1.7.0` (matches `packages/erp-kit/templates/scaffold/app/*/frontend/package.json` pinned `@tailor-platform/app-shell` semver)
 > **Source of truth:** `@tailor-platform/app-shell` exports
 > **Update process:** see "Keeping this file in sync" at the bottom
 
@@ -47,7 +47,9 @@ For the full upstream API of any component, follow the link to the published ref
 
 **Import:** `import { Layout } from '@tailor-platform/app-shell'`
 **Purpose:** Standard page container with header + 1–N column body. The most-used component — every page wraps content in `<Layout>`.
-**API:** `Layout` (root) + `Layout.Column` + `Layout.Header`. `LayoutProps`: `columns` (number, default auto-detected from children), `gap`, `title`, `actions`, `className`, `style`.
+**API:** `Layout` (root) + `Layout.Column` + `Layout.Header`. `LayoutProps`: `fill` (boolean), `columns` (number, default auto-detected from children), `gap`, `title`, `actions`, `className`, `style`.
+
+**`fill`** — stretches the layout to the available height and bounds the column row so children can scroll internally instead of growing the page. Use on table-first pages (`<Layout fill>` + `DataTable`): the title, table toolbar, sticky column headers, and pagination footer stay pinned while only the rows scroll — see **`patterns/list-dense-scan.md`**. Omit on pages that should flow and scroll naturally (forms, dashboards).
 
 **Column-count → width rules** (column count is auto-detected from `Layout.Column` children):
 
@@ -79,8 +81,8 @@ import { Button, Layout, Tabs } from "@tailor-platform/app-shell";
   <Layout.Header title="Purchase orders" actions={[<Button key="create">Create</Button>]}>
     <Tabs.Root value={bucket} onValueChange={setBucket}>
       <Tabs.List>
-        <Tabs.Trigger value="all">All</Tabs.Trigger>
-        <Tabs.Trigger value="open">Open</Tabs.Trigger>
+        <Tabs.Tab value="all">All</Tabs.Tab>
+        <Tabs.Tab value="open">Open</Tabs.Tab>
       </Tabs.List>
     </Tabs.Root>
   </Layout.Header>
@@ -107,19 +109,55 @@ import { Button, Layout, Tabs } from "@tailor-platform/app-shell";
 
 **Used in patterns:** every page pattern (`list/*`, `detail/*`, `form/*`).
 
+### `Grid`
+
+**Import:** `import { Grid } from '@tailor-platform/app-shell'`
+**Purpose:** Presentational CSS-Grid container for laying tiles/cards into equal or custom columns with responsive reflow — the canonical wrapper for **metric / KPI strips** and card galleries. Purely layout; makes no data assumptions.
+**API:** `GridProps` — `columns` (number | CSS track string like `"280px 1fr"` | responsive object `{ initial, sm, md, lg, xl }`), `gap` (spacing step, default `3`) plus `gapX` / `gapY`, `minChildWidth` (auto-fit: as many ≥Npx columns as fit, no breakpoints needed), `rows`, `flow`, `align`, `justify`. Sub-component **`Grid.Item`** for spanning/placement — `colSpan`, `rowSpan`, `colStart`, `colEnd` (all responsive). Root carries `data-slot="grid"`.
+**Example — responsive KPI grid:**
+
+```tsx
+import { Grid, MetricCard } from "@tailor-platform/app-shell";
+
+<Grid columns={{ initial: 1, md: 2, xl: 4 }} gap={4}>
+  <MetricCard title="Net total" value="$1,500" trend={{ direction: "up", value: "+5%" }} />
+  <MetricCard title="Open orders" value="42" />
+  <MetricCard title="Overdue" value="7" />
+  <MetricCard title="Suppliers" value="18" />
+</Grid>;
+```
+
+**Used in patterns:** metric / KPI strips on `detail/*` and dashboards; any equal-column card layout.
+
+**Notes:** Metric tiles and KPI cards **always** go in a `Grid` — never stacked one-per-row or in a single column. Use a responsive `columns` object (e.g. `{ initial: 1, md: 2, xl: 4 }`) so tiles reflow at smaller widths; reach for `minChildWidth` when the tile count is dynamic.
+
 ### `SidebarLayout`
 
 **Import:** `import { SidebarLayout } from '@tailor-platform/app-shell'`
 **Purpose:** Top-level layout that mounts the sidebar and renders the page outlet.
-**API:** `SidebarLayoutProps` — sidebar config, header config, content slot. Used in `App.tsx`.
+**API:** `SidebarLayoutProps` — `sidebar`, `header`, and `children` are full-region slots (each defaults to a built-in). `sidebar` defaults to `SidebarLayout.DefaultSidebar`; `header` defaults to `SidebarLayout.DefaultHeader`. Used in `App.tsx`.
 **Used in patterns:** consumed by AppShell init, not directly by page patterns. See `project-setup.md`.
 
-### `DefaultSidebar`, `SidebarGroup`, `SidebarItem`, `SidebarSeparator`
+### `SidebarLayout.DefaultHeader` (`DefaultHeader`)
+
+**Import:** `import { SidebarLayout } from '@tailor-platform/app-shell'` → `SidebarLayout.DefaultHeader` (also top-level `DefaultHeader`)
+**Purpose:** The built-in top bar (trigger + breadcrumb, plus an `actions` cluster). Drop into `SidebarLayout`'s `header` slot to extend the header without rebuilding it.
+**API:** `actions?: ReactNode | ReactNode[]` — the right-hand cluster (opinionated flex row). **Defaults to `[<AppearanceSwitcher />]`, and passing `actions` REPLACES the switcher** — include `<AppearanceSwitcher />` in the array to keep it. `actions={[]}` = empty right side.
+**Used in patterns:** project-level header customization (notification bell, user menu). See `project-setup.md`.
 
-**Import:** `import { DefaultSidebar, SidebarGroup, SidebarItem, SidebarSeparator } from '@tailor-platform/app-shell'`
+### `SidebarLayout.DefaultSidebar` (`DefaultSidebar`), `SidebarGroup`, `SidebarItem`, `SidebarSeparator`
+
+**Import:** `import { SidebarLayout, SidebarGroup, SidebarItem, SidebarSeparator } from '@tailor-platform/app-shell'` → `SidebarLayout.DefaultSidebar` (also top-level `DefaultSidebar`)
 **Purpose:** Sidebar composition. `DefaultSidebar` auto-resolves nav items from `appShellPageProps.meta` on each page; the others let you customize manually.
 **Used in patterns:** sidebar is a project-level concern. See `project-setup.md`.
 
+### `AppearanceSwitcher`
+
+**Import:** `import { AppearanceSwitcher } from '@tailor-platform/app-shell'`
+**Purpose:** Palette-icon dropdown for Light/Dark/System color mode. The default `SidebarLayout.DefaultHeader` action; also usable standalone (e.g. a sidebar footer). Include it in `DefaultHeader`'s `actions` array when customizing the header to keep it visible.
+**API:** No props — reads/writes theme via `useTheme`.
+**Used in patterns:** project-level. See `project-setup.md`.
+
 ### `CommandPalette`
 
 **Import:** `import { CommandPalette } from '@tailor-platform/app-shell'`
@@ -250,6 +288,28 @@ import { Button, Link } from '@tailor-platform/app-shell';
 **API:** Compound — `Tooltip.Root`, `Tooltip.Trigger`, `Tooltip.Content`.
 **Used in patterns:** any pattern with icon-only buttons (must have `aria-label` AND a tooltip).
 
+### `Tabs`
+
+**Import:** `import { Tabs } from '@tailor-platform/app-shell'`
+**Purpose:** In-page tab navigation — split one record's sections (Overview / Line items / Activity) or bucket a list (All / Open / …) into switchable panels. Presentational; owns only the active-tab state.
+**API:** Compound — `Tabs.Root` (`variant`: `default | line | capsule`; controlled `value` + `onValueChange`, or uncontrolled `defaultValue`), `Tabs.List`, `Tabs.Tab` (`value`), `Tabs.Panel` (`value`). Note: the sub-component is **`Tabs.Tab`**, not `Tabs.Trigger`.
+**Example:**
+
+```tsx
+<Tabs.Root defaultValue="overview" variant="line">
+  <Tabs.List>
+    <Tabs.Tab value="overview">Overview</Tabs.Tab>
+    <Tabs.Tab value="items">Line items</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel value="overview">{/* … */}</Tabs.Panel>
+  <Tabs.Panel value="items">{/* … */}</Tabs.Panel>
+</Tabs.Root>
+```
+
+**Used in patterns:** `list-dense-scan` (bucket tabs composed **above** `DataTable.Root`, synced to `useCollectionVariables` — see the `DataTable` "Bucket tabs" note), `detail/*` (sectioned record content).
+
+**Notes:** For lists, AppShell's own filtering surface is **toolbar chips** (`DataTable.Filters`), not tabs — reach for `Tabs` only when the business genuinely thinks in a small set of named buckets. Don't render a `Tab` per enum value where a filter chip belongs.
+
 ---
 
 ## Display
@@ -260,14 +320,27 @@ import { Button, Link } from '@tailor-platform/app-shell';
 
 **Import:** `import { Badge } from '@tailor-platform/app-shell'`
 **Purpose:** Status labels and small categorical chips.
-**API:** `BadgeProps` — `variant`: `default | success | warning | neutral | error | destructive`. Plus `badgeVariants` CVA for custom-styled siblings.
+**API:** `BadgeProps` — `variant` (15 total):
+
+- **Filled** (high emphasis): `default` (primary), `success`, `warning`, `error`, `neutral`, `info`
+- **Subtle** (low emphasis, tinted): `subtle-success`, `subtle-warning`, `subtle-error`, `subtle-info`
+- **Outline** (renders a status dot — for row/list statuses): `outline-success`, `outline-warning`, `outline-error`, `outline-info`, `outline-neutral`
+
+Plus `badgeVariants` CVA for custom-styled siblings.
 **Example:**
 
 ```tsx
-<Badge variant="success">Active</Badge>
+// Primary / lifecycle status — filled semantic variant
+<Badge variant="success">Confirmed</Badge>
+// Secondary status (delivery, billing) — outline with status dot
+<Badge variant="outline-warning">Partially received</Badge>
+// Tag / label — subtle
+<Badge variant="subtle-info">New</Badge>
 ```
 
-**Used in patterns:** `list/*` (status column), `detail/*` (header status).
+**Used in patterns:** `list/*` (status column → `outline-*`), `detail/*` (header status).
+
+**Notes:** Encode status by **semantic color** with a primary/secondary split: a record's **primary/lifecycle status** uses a **filled** semantic variant (one per row / one in a detail header); **secondary statuses** (delivery, billing) use **`outline-*`** (status dot); tags use **`subtle-*`**. Reserve **`default`** (brand) for non-status emphasis. Full rule: **`design-system.md`** → Composition & emphasis rules.
 
 ### `Table`
 
@@ -275,7 +348,7 @@ import { Button, Link } from '@tailor-platform/app-shell';
 
 **Import:** `import { Table } from '@tailor-platform/app-shell'`
 **Purpose:** Semantic data table with scrollable container.
-**API:** Compound — `Table.Root`, `Table.Header`, `Table.Body`, `Table.Footer`, `Table.Row`, `Table.Head`, `Table.Cell`, `Table.Caption`. `Table.Root` accepts `containerClassName` for the outer wrapper, `className` for the inner `<table>`.
+**API:** Compound — `Table.Root`, `Table.Header`, `Table.Body`, `Table.Footer`, `Table.Row`, `Table.Head`, `Table.Cell`, `Table.Caption`. `Table.Root` accepts `containerClassName` for the outer wrapper, `className` for the inner `<table>`. `Table.Head` and `Table.Cell` accept **`align`** (`"left" | "center" | "right"`, default `"left"`) — prefer this over ad-hoc `className="astw:text-right"` and pair the same alignment on the head and its column's cells (right for numeric/money, center for compact status/icon columns).
 **Example:**
 
 ```tsx
@@ -284,7 +357,7 @@ import { Button, Link } from '@tailor-platform/app-shell';
     <Table.Row>
       <Table.Head>Order</Table.Head>
       <Table.Head>Status</Table.Head>
-      <Table.Head className="astw:text-right">Total</Table.Head>
+      <Table.Head align="right">Total</Table.Head>
     </Table.Row>
   </Table.Header>
   <Table.Body>
@@ -294,7 +367,7 @@ import { Button, Link } from '@tailor-platform/app-shell';
         <Table.Cell>
           <Badge variant={statusVariant(o.status)}>{o.status}</Badge>
         </Table.Cell>
-        <Table.Cell className="astw:text-right">{formatMoney(o.total)}</Table.Cell>
+        <Table.Cell align="right">{formatMoney(o.total)}</Table.Cell>
       </Table.Row>
     ))}
   </Table.Body>
@@ -346,6 +419,8 @@ const table = useDataTable({
 </DataTable.Root>;
 ```
 
+**Column alignment:** each `Column` accepts **`align`** (`"left" | "right"`) applied to both header and body cell. Numeric `type` columns (`"number"`, `"money"`) default to `"right"` automatically so digits align on the decimal place — pass `align="left"` to opt out; everything else defaults to `"left"`.
+
 **Metadata path:** Prefer `createColumnHelper` + `inferColumns(tableMetadata.order)` (`@tailor-platform/app-shell-sdk-plugin` codegen) when available so enum/datetime/string filters bind to the right editors.
 
 **Bucket tabs / segmented UX:** AppShell defines **toolbar chips**, not lifecycle tabs. When design places **`Tabs`** (All / Draft / …) inside the card, compose them **above** `DataTable.Root` and synchronize tab-driven bucket state with **`useCollectionVariables`** (`variables.query` / filters)—see **`patterns/list/dense-scan.md`**.
@@ -410,25 +485,31 @@ const table = useDataTable({
 **Import:** `import { MetricCard } from '@tailor-platform/app-shell'`
 **Purpose:** KPI tile for dashboards or hero metric strip.
 **API:** `MetricCardProps` — `title`, `value`, `trend: { direction, value }`, `description`, `icon`.
-**Example:**
+**Example:** metric tiles are laid out in a `Grid` (never one-per-row):
 
 ```tsx
-<MetricCard
-  title="Net total"
-  value="$1,500"
-  trend={{ direction: "up", value: "+5%" }}
-  description="vs last month"
-  icon={<DollarSign />}
-/>
+<Grid columns={{ initial: 1, md: 2, xl: 4 }} gap={4}>
+  <MetricCard
+    title="Net total"
+    value="$1,500"
+    trend={{ direction: "up", value: "+5%" }}
+    description="vs last month"
+    icon={<DollarSign />}
+  />
+  <MetricCard title="Open orders" value="42" />
+  {/* …more tiles */}
+</Grid>
 ```
 
 **Used in patterns:** KPI tiles, dashboards, **`detail/*`** metric strips where specs call for them.
 
+**Notes:** Always wrap metric tiles in **`Grid`** (see the `Grid` entry) — a column of single-width `MetricCard`s stacked one-per-row is an anti-pattern.
+
 ### `DocumentProgressCard`
 
 **Import:** `import { DocumentProgressCard } from '@tailor-platform/app-shell'`
-**Purpose:** Generic document lifecycle/fulfilment state — optional percentage, stacked progress bar, status legend; arbitrary `segments`.
-**API:** `DocumentProgressCardProps` — `segments` (`{ label, value, color? }[]`), `title?`, `percent?`, `legend?` (defaults to `segments`), `total?` (bar denominator; larger than the sum leaves an empty track), `className?`. View-only — `percent` is explicit.
+**Purpose:** Presentational card for a document's lifecycle / fulfilment state — an optional headline percentage, a stacked progress bar, and a status legend. Domain-agnostic and view-only: pass an arbitrary set of `segments` (e.g. shipped / returned / pending) plus an explicit `percent`; derive both in the consumer.
+**API:** `DocumentProgressCardProps` — `segments` (required; array of `{ label, value, color }`), `percent?` (0–100, headline shown top-right), `title?`, `legend?` (defaults to `segments`; supply only when the legend should differ from the bar, e.g. overlapping buckets), `total?` (bar denominator; defaults to the sum of segment values — a larger value leaves an unfilled remainder), `className?`. Segment `color`: `indigo | pink | green | amber | red | blue | neutral`.
 **Example:**
 
 ```tsx
@@ -443,7 +524,7 @@ const table = useDataTable({
 />
 ```
 
-**Used in patterns:** **`detail/*`** right-rail cards for arbitrary status breakdowns (shipped/cancelled/pending, PO received/returned/yet-to-receive, etc.). For the purchase-order fulfilment recipe (derived %, net-received/returned bar split, legend override), see `docs/components/document-progress-card.md`.
+**Used in patterns:** `detail/*` — fulfilment / lifecycle summary cards (e.g. a purchase-order receipt progress) in the main column or right rail.
 
 ### `Avatar`
 
@@ -504,6 +585,24 @@ const table = useDataTable({
 **API:** Compound — `ActivityCard.Root`, `ActivityCard.Items` (generic over item type), plus `ActivityCardProps`, `ActivityCardItem`, `ActivityCardItemProps`. Items render with timestamp + actor + description.
 **Used in patterns:** `detail/hero-with-actions` (right column or bottom section).
 
+### `Alert`
+
+**Import:** `import { Alert } from '@tailor-platform/app-shell'`
+**Purpose:** Inline, in-page banner for a persistent status message — a form/record error, a warning, or a success/info notice attached to a section. (Transient notifications use `useToast`; blocking confirmations use `Dialog` — see `interaction/confirm`.)
+**API:** Compound — `Alert.Root` (`variant`: `neutral | success | warning | error | info`, default `neutral`; a matching icon is rendered automatically; optional `action?: ReactNode`, `dismissible?: boolean`, `onDismiss?: () => void`), `Alert.Title`, `Alert.Description`.
+**Example:**
+
+```tsx
+<Alert.Root variant="error">
+  <Alert.Title>Couldn't load line items</Alert.Title>
+  <Alert.Description>Check your connection and try again.</Alert.Description>
+</Alert.Root>
+```
+
+**Used in patterns:** any data-backed screen's **error** state (inline error + retry) and record-level warnings — the error affordance the composition rules require (**`design-system.md`** → Composition & emphasis rules → States).
+
+**Notes:** Encode severity by `variant` (semantic color), same discipline as `Badge` — don't use `error` for a routine notice. Pair a retry/next-step control via `action` rather than a separate stray button.
+
 ---
 
 ## Forms
@@ -544,6 +643,7 @@ const table = useDataTable({
 **Import:** `import { Select } from '@tailor-platform/app-shell'`
 **Purpose:** Dropdown for fixed enumerations.
 **API:** Compound. Sync version (small option lists). For async/typeahead, see `Combobox` and `Autocomplete`. Type: `SelectAsyncFetcher<T>` for the async variant.
+**Accessible name:** inside a `Form` the field label provides it automatically. When used **standalone** (outside a `Form`), pass `aria-label` (or `aria-labelledby` / `id`) — these now forward to the underlying combobox element, so it isn't left named only by its current value. Same applies to `Combobox` and `Autocomplete`.
 **Used in patterns:** all `form/*` (enum fields).
 
 ### `Combobox`
@@ -626,7 +726,7 @@ Types for authoring guard functions used by `WithGuard` and `appShellPageProps.g
 
 ### `RouteParams`, `PageComponent`, `PageMeta`, `AppShellPageProps`, `AppShellRegister`, `ContextData` (types)
 
-Types for declaring page props (`appShellPageProps = { meta, guards, loader }`), reading typed route params, and registering route types globally. See `project-setup.md` for usage.
+Types for declaring page props (`appShellPageProps = { meta, guards }`), reading typed route params, and registering route types globally. See `project-setup.md` for usage.
 
 ---
 

package/skills/app-shell-patterns/references/fundamental/design-system.md

@@ -353,3 +353,27 @@ When a custom component proves reusable across 2+ apps, promote it upstream into
 | Two-column detail at <1024         | right column collapses below main — do not override                                                                   |
 | Inline ID, code, table number      | `text-mono`                                                                                                           |
 | Timestamp, label, subtle metadata  | `text-caption text-fg-subtle`                                                                                         |
+
+### Composition & emphasis rules
+
+These are visual-composition rules every screen must follow, regardless of pattern. They exist because emphasis only works when it is scarce.
+
+**Emphasis budget.** Attention is a budget you spend once per scan region.
+
+- **One primary action per view.** A screen (or a card/section) has at most one filled/primary `Button`; everything else is `outline`, `secondary`, or `ghost`. If two things look equally important, neither reads as important.
+- **Badges** encode status by semantic color, with a clear primary/secondary split:
+  - A record's **primary / lifecycle status** (PO status, SO status) → a **filled semantic** variant (`success` / `warning` / `error` / `info` / `neutral`) — one per row in a list, one in a detail header.
+  - **Secondary statuses** (delivery, billing, fulfilment) and dense supporting columns → **`outline-*`** (with status dot).
+  - **Tags / labels** ("New", "Returned") → **`subtle-*`**.
+  - Reserve **`default`** (brand fill) for non-status emphasis — never the brand color as a routine status. The defect to avoid: making _every_ chip a loud fill, or giving secondary statuses the same weight as the primary one. (Variants: **`components.md`** → `Badge`.)
+- **Color:** status colors (`success`/`warning`/`error`/`info`) signal meaning, not decoration — don't tint neutral content.
+
+**Hierarchy.** One `h1` per page (the `Layout.Header` title). Section headings step down (`h2` → `h3`); never skip levels for size — pick the role token (`design-system.md` §4 Typography), not the pixel size.
+
+**States — never ship only the happy path.** Every data-backed screen handles:
+
+- **Loading** — skeleton/placeholder, not a blank flash.
+- **Empty** — a labelled empty state (what it is, how to add the first record), not a bare empty table.
+- **Error** — an inline error with a retry affordance, not a silent failure.
+
+**Spacing rhythm.** Use the spacing scale (§4) consistently — equal gaps between sibling sections, consistent card padding. A one-off `gap` or `padding` that doesn't match its siblings reads as a mistake.

package/skills/app-shell-patterns/references/fundamental/graphql.md

@@ -191,7 +191,7 @@ Every page component:
    };
    ```
 
-3. Uses `appShellPageProps.guards` for permission gates and `appShellPageProps.loader` for route loaders. See [project-setup.md](project-setup.md).
+3. Uses `appShellPageProps.guards` for permission gates. See [project-setup.md](project-setup.md).
 
 ## Quick reference
 

package/skills/app-shell-patterns/references/patterns/detail-hero-with-actions.md

@@ -5,7 +5,21 @@ category: pattern
 subcategory: detail
 description: Single-record detail view with workflow actions and activity timeline
 requiredImports:
-  [Layout, Badge, Button, Menu, DescriptionCard, Card, Table, ActionPanel, ActivityCard]
+  [
+    Layout,
+    Badge,
+    Button,
+    Menu,
+    DescriptionCard,
+    Card,
+    Table,
+    ActionPanel,
+    ActivityCard,
+    Grid,
+    MetricCard,
+    DocumentProgressCard,
+    Alert,
+  ]
 tags: [detail, actions, timeline, workflow, two-column]
 do:
   - Single-record detail view (Order #1234, Supplier ABC, Product SKU-42)
@@ -51,6 +65,33 @@ Composition rules:
 
 Responsive: <1024 collapses to single column with right column rendered below main; 1024–1280 two columns with narrow side; >1280 two columns at full width.
 
+## Layout variants
+
+Choose the column structure from the **record** — the pattern is "hero + workflow + (optional) history," and the layout flexes. The skill never mandates a fixed column count.
+
+- **Main + right rail** (most common) — the record has workflow actions and/or activity/related summaries → right `Layout.Column area="right"` holds `ActionPanel`, `ActivityCard`, integration cards.
+- **Single main column** — the record is mostly descriptive with few/no workflow actions and no meaningful history → one `Layout.Column`. Don't invent a rail just to fill space.
+- **Main + left rail** (`area="left"`, wider 320px) — when a persistent section index / summary should lead the reading order.
+- Either column holds **N cards** as the record requires.
+
+## Optional cards
+
+Add these only when the record calls for them — none is mandatory. Each is a card like any other in the columns above.
+
+- **Metric strip** — when the record has headline KPIs (totals, counts), lead the main column with `MetricCard`s wrapped in a `Grid` (never one per row). See the `Grid` and `MetricCard` entries in `components.md`.
+
+  ```tsx
+  <Grid columns={{ initial: 1, md: 2, xl: 4 }} gap={4}>
+    <MetricCard title="Net total" value="$12,480" trend={{ direction: "up", value: "+4%" }} />
+    <MetricCard title="Lines" value="18" />
+    <MetricCard title="Received" value="11" />
+    <MetricCard title="Outstanding" value="7" />
+  </Grid>
+  ```
+
+- **`DocumentProgressCard`** — when the record has a fulfilment / lifecycle breakdown (received vs returned vs pending, shipment status). Sits in the main column or the right rail; derive `percent` and `segments` in the consumer.
+- **`Alert`** — a record-level inline banner (blocking error, on-hold warning) above the columns; use the **error** variant for the pattern's required error state. Transient feedback uses `useToast`, not `Alert`.
+
 ## Page Implementation
 
 ```tsx
@@ -109,16 +150,16 @@ export default function HeroWithActionsDetail({ order, onApprove, onCancel }: Pr
               <Table.Header>
                 <Table.Row>
                   <Table.Head>SKU</Table.Head>
-                  <Table.Head>Qty</Table.Head>
-                  <Table.Head>Total</Table.Head>
+                  <Table.Head align="right">Qty</Table.Head>
+                  <Table.Head align="right">Total</Table.Head>
                 </Table.Row>
               </Table.Header>
               <Table.Body>
                 {order.lineItems.map((item) => (
                   <Table.Row key={item.id}>
                     <Table.Cell>{item.sku}</Table.Cell>
-                    <Table.Cell>{item.qty}</Table.Cell>
-                    <Table.Cell>${item.total.toLocaleString()}</Table.Cell>
+                    <Table.Cell align="right">{item.qty}</Table.Cell>
+                    <Table.Cell align="right">${item.total.toLocaleString()}</Table.Cell>
                   </Table.Row>
                 ))}
               </Table.Body>
@@ -143,9 +184,10 @@ export default function HeroWithActionsDetail({ order, onApprove, onCancel }: Pr
 
 ## Constraints
 
-- More than 2 primary actions in the header → move overflow into a `Menu`.
+- **Header carries the single primary CTA + the status `Badge`** — not workflow actions. Workflow actions (Approve, Reject, Archive, …) live in the `ActionPanel`. If the header needs more than ~2 actions, move the overflow into a `Menu`.
+- **Never duplicate an action** across `Layout.Header` and `ActionPanel` — each action has exactly one home.
 - Every content section MUST sit inside `Card.Root` (or `DescriptionCard`, which already self-contains). Raw divs are not allowed.
-- `ActionPanel` is workflow-only — never back-navigation.
+- `ActionPanel` is workflow-only — never back-navigation (that lives in the breadcrumb).
 - `Table.Root` inside a Card requires `containerClassName="astw:px-6"`.
 
 ## Anti-patterns
@@ -155,3 +197,5 @@ export default function HeroWithActionsDetail({ order, onApprove, onCancel }: Pr
 - Bare `<div>` sections in the main column — every content section MUST sit inside `Card.Root`.
 - `ActionPanel` containing back-navigation (e.g. "Back to Product List") — back navigation lives in `Layout.Header`'s breadcrumb.
 - A `Table.Root` inside a Card without `containerClassName="astw:px-6"` — the first column lands flush against the card edge.
+- The same action in both `Layout.Header` and the `ActionPanel` — duplicating it makes neither read as canonical. Pick one home.
+- Giving every status the same loud weight — the record's primary/lifecycle status is a **filled** semantic badge; secondary statuses (fulfilment, billing) use **`outline-*`** (see `design-system.md` → Composition & emphasis rules).