tailor-platform
diff --git a/‎packages/core/skills/app-shell-patterns/SKILL.md‎
Lines changed: 13 additions & 1 deletion b/‎packages/core/skills/app-shell-patterns/SKILL.md‎
Lines changed: 13 additions & 1 deletion
diff --git a/‎packages/core/skills/app-shell-patterns/references/fundamental/components.md‎
Lines changed: 121 additions & 16 deletions b/‎packages/core/skills/app-shell-patterns/references/fundamental/components.md‎
Lines changed: 121 additions & 16 deletions
diff --git a/‎packages/core/skills/app-shell-patterns/references/fundamental/design-system.md‎
Lines changed: 24 additions & 0 deletions b/‎packages/core/skills/app-shell-patterns/references/fundamental/design-system.md‎
Lines changed: 24 additions & 0 deletions
@@ -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
@@ -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.
@@ -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
 
@@ -79,8 +79,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,6 +107,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'`
@@ -250,6 +272,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,22 +304,35 @@ 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`
 
 > Full API: [https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/table.md](https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/table.md)
 
 **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 +341,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 +351,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 +403,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,19 +469,46 @@ 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:** metric tiles are laid out in a `Grid` (never one-per-row):
+
+```tsx
+<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:** 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
-<MetricCard
-  title="Net total"
-  value="$1,500"
-  trend={{ direction: "up", value: "+5%" }}
-  description="vs last month"
-  icon={<DollarSign />}
+<DocumentProgressCard
+  title="Shipment status"
+  percent={60}
+  segments={[
+    { label: "Shipped", value: 30, color: "green" },
+    { label: "Returned", value: 3, color: "red" },
+    { label: "Pending", value: 17, color: "neutral" },
+  ]}
 />
 ```
 
-**Used in patterns:** KPI tiles, dashboards, **`detail/*`** metric strips where specs call for them.
+**Used in patterns:** `detail/*` — fulfilment / lifecycle summary cards (e.g. a purchase-order receipt progress) in the main column or right rail.
 
 ### `Avatar`
 
@@ -483,6 +569,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
@@ -523,6 +627,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`
 
@@ -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.