@tailor-platform/app-shell 1.8.0 → 1.10.0

package/dist/themes/bloom.css

@@ -146,7 +146,8 @@ html
   background-color: transparent;
 }
 
-html [data-slot="button"][class*="astw:bg-background"][class*="astw:border"] {
+html [data-slot="button"][class*="astw:bg-background"][class*="astw:border"],
+html [data-slot="data-table-filter-chip"] {
   background-color: transparent;
   transition:
     background-color 0.12s ease,

package/dist/themes/cream.css

@@ -146,7 +146,8 @@ html
   background-color: transparent;
 }
 
-html [data-slot="button"][class*="astw:bg-background"][class*="astw:border"] {
+html [data-slot="button"][class*="astw:bg-background"][class*="astw:border"],
+html [data-slot="data-table-filter-chip"] {
   background-color: transparent;
   transition:
     background-color 0.12s ease,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/app-shell",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "An opinionated React application framework for building ERP applications on Tailor Platform",
   "keywords": [
     "app-shell",
@@ -46,7 +46,7 @@
     "@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",

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
 
@@ -81,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>
@@ -109,6 +109,28 @@ 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'`
@@ -266,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
@@ -276,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`
 
@@ -291,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
@@ -300,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>
@@ -310,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>
@@ -330,7 +387,7 @@ import { Button, Link } from '@tailor-platform/app-shell';
 
 **Import:** compound namespace + helpers from `'@tailor-platform/app-shell'`, e.g. `DataTable`, `useDataTable`, `useCollectionVariables`, `createColumnHelper`, and types such as `Column`, `UseDataTableReturn`.
 
-**Purpose:** Production list screens over GraphQL **connections**. Owns toolbar filter chips (**`DataTable.Filters`** from column `filter` configs), header sort, **`DataTable.Pagination`** (cursor-first; First/Last when `total` is provided), loading skeleton/error row, **`onClickRow`**, **`rowActions`** (kebab column), **`onSelectionChange`** (checkbox column).
+**Purpose:** Production list screens over GraphQL **connections**. Owns toolbar filter chips (**`DataTable.Filters`** from column `filter` configs), header sort, **`DataTable.Pagination`** (cursor-first; First/Last when `total` is provided), loading skeleton/error row, **`onClickRow`**, **`rowActions`** (kebab column), **`onSelectionChange`** (checkbox column), **column pinning** (`pin: "left" | "right"`) and built-in **column settings** (`<DataTable.Toolbar columnSettings>` — user show/hide + reorder + pin, persisted per-user via **`tableId`**).
 
 **Primitives:** Builds on low-level **`Table`**; do not reinvent pagination/filters manually unless the dataset is trivial.
 
@@ -347,12 +404,13 @@ const table = useDataTable({
   data: fetching ? undefined : mappedFromQuery,
   loading: fetching,
   control,
+  tableId: "purchase-orders", // persist user column layout to localStorage
   onClickRow: (row) => navigate(detailHref(row)),
   // onSelectionChange, rowActions, sort: …
 });
 
 <DataTable.Root value={table}>
-  <DataTable.Toolbar>
+  <DataTable.Toolbar columnSettings>
     <DataTable.Filters />
   </DataTable.Toolbar>
   <DataTable.Table />
@@ -362,6 +420,12 @@ const table = useDataTable({
 </DataTable.Root>;
 ```
 
+**Row navigation:** whole row is clickable via **`onClickRow`** → `navigate(detailHref(row))`; wrap the primary identifier cell in `<Link>` for keyboard/SR access. Never add a per-row "View" / "Open" / "→" button. (A first-class row-interaction API is under design — see the row-interaction tracking issue.)
+
+**Column pinning & settings:** set `pin: "left" | "right"` on a `Column` to freeze it during horizontal scroll — selection auto-pins left, row-actions auto-pins right (a `width` is optional but recommended for stable sizing). Pass **`columnSettings`** to **`DataTable.Toolbar`** to render the built-in "Columns" control (show/hide, reorder, re-pin) at the top-right; pass a stable, **unique** **`tableId`** to persist each user's layout to `localStorage` (a per-user preference — intentionally not in the URL like filters/sort).
+
+**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`**.
@@ -426,25 +490,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
@@ -459,7 +529,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`
 
@@ -520,6 +590,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
@@ -555,11 +643,20 @@ const table = useDataTable({
 **API:** `InputProps` — extends native `<input>` props.
 **Used in patterns:** all `form/*`.
 
+### `Checkbox`
+
+**Import:** `import { Checkbox } from '@tailor-platform/app-shell'`
+**Purpose:** Boolean form control. Maps to spec field type: `boolean`. Also used for row selection and filter toggles.
+**API:** `CheckboxProps` — extends Base UI `Checkbox.Root` (`checked`/`defaultChecked`, `onCheckedChange`, `indeterminate`, `disabled`, `required`, `name`, `inputRef`) and adds an inline `label`. Integrates with `Field` for invalid/disabled/label state exactly like `Input`/`Select` — no bespoke `error` prop.
+**Accessible name:** the inline `label` prop (enclosing) or a sibling `Field.Label`; for a bare box (e.g. a table row-select cell) pass `aria-label`.
+**Used in patterns:** `form/*` (boolean fields), `list/*` (row selection), DataTable filter/column controls.
+
 ### `Select`
 
 **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`
@@ -642,7 +739,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).

package/skills/app-shell-patterns/references/patterns/list-dense-scan.md

@@ -52,11 +52,13 @@ export type Order = {
   createdAt: string;
 };
 
+// Primary status column — filled semantic variants (one per row).
+// Secondary status columns (e.g. delivery, billing) use outline-* instead.
 const statusVariant = {
   draft: "neutral",
-  confirmed: "outline-info",
-  shipped: "outline-warning",
-  delivered: "outline-success",
+  confirmed: "info",
+  shipped: "warning",
+  delivered: "success",
 } as const;
 
 export const columns: Column<Order>[] = [
@@ -67,7 +69,10 @@ export const columns: Column<Order>[] = [
     render: (row) => <Badge variant={statusVariant[row.status]}>{row.status}</Badge>,
   },
   {
+    // Numeric columns right-align so digits line up. `type: "money" | "number"`
+    // auto-right; with a custom `render` set `align` explicitly.
     label: "Amount",
+    align: "right",
     render: (row) => `${row.amount.toLocaleString()}`,
   },
   { label: "Created", accessor: (row) => row.createdAt },
@@ -145,10 +150,12 @@ Omit `fill` on pages that should flow and scroll naturally (forms, dashboards, a
 - Column count: 4-8 recommended
 - Must include pagination — never render unbounded lists
 - Table-first pages use `<Layout fill>` so title/toolbar/header/footer stay pinned and only rows scroll
-- Status Badge colors must use design system tokens (variant prop)
+- Handle every state: `DataTable` renders the loading skeleton and error row; always provide a **labelled empty state** (what the list is + how to add the first record) rather than a bare empty table
+- Status Badge colors must use design system tokens (variant prop): the **primary** status column uses **filled** semantic variants; **secondary** status columns (delivery, billing) use **`outline-*`** (see `design-system.md` → Composition & emphasis rules)
 - Bulk actions toolbar appears only when ≥1 row is selected
-- Whole row is clickable via `onClickRow`; no per-row "View" / "Open" buttons
+- Whole row is clickable via `onClickRow`; wrap the primary identifier cell in `<Link>` for keyboard/SR access. No per-row "View" / "Open" buttons
 - Per-row `Menu` (overflow `…`) is reserved for non-navigation actions (Archive, Duplicate, Delete)
+- Wide lists (many columns / horizontal scroll): pin the column users scan by to the **left** — the record's identifier (invoice / order **reference**) or its **name** (customer, product) — so it stays anchored while the rest scrolls; optionally pin a single high-signal **status** or **total** to the **right**. Keep the pinned set small (≈1 left, at most 1 right) — over-pinning eats the scroll area. Let users override via `<DataTable.Toolbar columnSettings>` (show/hide + reorder + re-pin) with a stable `tableId` so each user's layout persists
 
 ## Anti-patterns