@tailor-platform/app-shell 1.17.0 → 1.18.0

package/skills/app-shell-patterns/references/concepts/styling-theming.md

@@ -159,17 +159,26 @@ Colors follow shadcn-style semantic naming: a surface token and its matching `-f
 | `--border`                           | hairlines, dividers           | `border-border`                          |
 | `--input`                            | form control borders          | `border-input`                           |
 | `--ring`                             | focus rings                   | `ring-ring` / `outline-ring`             |
+| `--backdrop`                         | dim layer behind a modal      | `bg-backdrop`                            |
 
 Surfaces are named by **role**, not by depth — there is no numbered `surface-1/2/3` ladder, and no third tier of body text below `muted-foreground`. Stack depth with `background` → `card` → `muted` plus a border or shadow, and reach for `popover` when the surface actually floats.
 
+`--backdrop` is the dim layer behind `Dialog` and `Sheet` (black at 50% in both modes). Use `bg-backdrop` for your own modal layers instead of `bg-black/50`. Palettes inherit it; override it on `:root` to change every backdrop at once.
+
+In the default palette, the surface, text and line tokens in this table read the internal gray scale, a white step, and white alpha steps (dark-mode lines), so their values match the gray used across the palette. `--backdrop` reads a black alpha step, and `--ring` is mixed from `--primary`. The other palettes set their own values.
+
 #### Brand & action
 
-| Token                                        | Use                              | Tailwind                                     |
-| -------------------------------------------- | -------------------------------- | -------------------------------------------- |
-| `--primary` / `--primary-foreground`         | primary buttons, emphasis        | `bg-primary` / `text-primary-foreground`     |
-| `--secondary` / `--secondary-foreground`     | secondary buttons, neutral chips | `bg-secondary` / `text-secondary-foreground` |
-| `--accent` / `--accent-foreground`           | hover and selected nav states    | `bg-accent` / `text-accent-foreground`       |
-| `--destructive` / `--destructive-foreground` | destructive actions, errors      | `bg-destructive` / `text-destructive`        |
+| Token                                        | Use                                         | Tailwind                                     |
+| -------------------------------------------- | ------------------------------------------- | -------------------------------------------- |
+| `--primary` / `--primary-foreground`         | primary buttons, emphasis                   | `bg-primary` / `text-primary-foreground`     |
+| `--secondary` / `--secondary-foreground`     | secondary buttons, neutral chips            | `bg-secondary` / `text-secondary-foreground` |
+| `--accent` / `--accent-foreground`           | hover and selected nav states               | `bg-accent` / `text-accent-foreground`       |
+| `--destructive` / `--destructive-foreground` | deprecated alias of danger solid / contrast | `bg-destructive` / `text-destructive`        |
+
+**Deprecated.** `--destructive`, `--destructive-foreground` and their utilities remain for existing code and will be removed in the next major. New code uses the danger roles: `bg-danger-solid`, `text-danger-contrast`, and `text-danger-text` for text. `Button variant="destructive"` is not deprecated yet; the next major renames it to `danger`.
+
+`--destructive` and `--destructive-foreground` are aliases of the danger `solid` and `contrast` roles ([semantic color roles](#semantic-color-roles)), so `bg-destructive` is the danger solid fill in both modes and `Button variant="destructive"` reads the danger roles directly. `text-destructive` still works and resolves to the solid. For text, use `text-danger-text`, which meets 4.5:1 on `--card` and `--background`; the solid is `#dc2626` in dark mode, 3.71:1 on the dark card. To recolour destructive actions, override `--danger-solid` (and the other danger roles), not `--destructive`.
 
 There are no `-hover` or `-active` brand tokens. Express interaction states with Tailwind variants and opacity — `hover:bg-primary/90`, `active:bg-primary/80` — which is what AppShell's own components do.
 
@@ -212,7 +221,7 @@ In the default palette, `text` on `surface` and `contrast` on `solid` and `solid
 
 Most `surface` and `border` values are translucent tints, so an opacity modifier compounds rather than replaces — `bg-info-surface/50` halves the tint's alpha instead of setting it to 50%. Some light-mode values are opaque instead of translucent: the `warning` surface, surface-hover and border, the `info` border and the `danger` surface-hover. They do not blend with a tinted parent. All dark-mode values are translucent.
 
-`Badge`, `Alert`, `CsvImporter` and `MetricCard` read these roles directly, not `--status-*` or `--alert-*`. To recolour them, override the roles. `Badge` `error` and `subtle-error`, and `Alert` `error`, follow `--danger-*`. They no longer follow `--destructive`, which still drives `Button` and `text-destructive`.
+`Badge`, `Alert`, `CsvImporter` and `MetricCard` read these roles directly, not `--status-*` or `--alert-*`. To recolour them, override the roles. `Badge` `error` and `subtle-error`, and `Alert` `error`, follow `--danger-*`. `Button variant="destructive"`, invalid input borders and error text follow `--danger-*` too, and `--destructive` is an alias of `--danger-solid`.
 
 #### Sidebar & charts
 
@@ -288,7 +297,7 @@ Pair a role with a color token from the Color section above. These pairings are
 | --------------------------------- | ---------------------------------------------- |
 | Page title (`Layout.Header`)      | `text-heading-lg`                              |
 | Section heading                   | `text-heading-md`                              |
-| Card title (`div` or `span`)      | `text-heading-md leading-none`                 |
+| Card title                        | `text-heading-md leading-none`                 |
 | Body copy                         | `text-body-md`                                 |
 | Secondary copy, descriptions      | `text-body-md text-muted-foreground`           |
 | Caption, timestamp, metadata      | `text-body-sm text-muted-foreground`           |
@@ -401,17 +410,24 @@ function TypographyRoles() {
 <span className="text-body-sm text-muted-foreground">Updated 2h ago</span>
 ```
 
+The [`Text`](../components/text.md) component applies the same roles with a `variant` prop. It renders a default element for each role (`h2` for headings, `p` for body text, `span` for the others), and its `render` prop sets the element, such as the heading level:
+
+```tsx
+<Text variant="heading-md" render={<h3 />}>Line items</Text>
+<Text variant="body-md" className="text-muted-foreground">Description copy</Text>
+```
+
 On an `h1` to `h6` element, the `cream` and `bloom` palettes replace the role's line height and letter spacing, including `leading-none`; see "Change a role" below. AppShell's own components still use the stock utilities (`text-sm`, `font-medium`, and so on) today. They will move to the roles in later changes, so the two sets can appear side by side for now.
 
 **Rules**
 
 - **A role carries no color.** Set the color with a token such as `text-muted-foreground`.
-- **A role does not choose the HTML element.** Pick `h2`, `p`, or `span` from the document structure, not from the size.
+- **A role does not choose the HTML element.** Pick `h2`, `p`, or `span` from the document structure, not from the size. With `Text`, set the element with `render`.
 - **A role sets weight and letter spacing on its own element.** It does not inherit them from a parent. Put an emphasis or tracking class on the element that has the role, not on its parent.
 - **Four modifiers may be combined with a role.** All are stock Tailwind utilities:
   - Compact line height: `leading-none`. Use it only for single-line text, such as a card title. Write it after the role when you merge with `cn()`.
   - Tabular figures: `tabular-nums`.
-  - Emphasis on inline text: `font-medium` or `font-semibold`.
+  - Emphasis on inline text: `font-semibold`. Do not use `font-medium`; on a label role it makes no change.
   - Uppercase: `uppercase`.
 - **Do not combine a role with other `leading-*`, `tracking-*`, or `text-[Npx]` values.** If none of the roles fits, use the nearest role.
 - **12px is the minimum size.** Do not use smaller text.
@@ -420,12 +436,12 @@ On an `h1` to `h6` element, the `cream` and `bloom` palettes replace the role's
 
 Always use `tabular-nums` for numbers that stack in a column — without it, digits jitter between rows.
 
-**Change a role.** Each role is four CSS variables named `--app-shell-type-<role>-<size|line-height|weight|letter-spacing>`. Override them on `:root` to change a role for the whole app. Typography has no dark variant, so one override applies to light and dark mode.
+**Change a role.** Each role is four CSS variables named `--type-<role>-<size|line-height|weight|letter-spacing>`. Override them on `:root` to change a role for the whole app. Typography has no dark variant, so one override applies to light and dark mode. 1.17.0 named these variables `--app-shell-type-*`. The old names still work, but they are deprecated and will be removed in the next major; rename them to `--type-*`.
 
 ```css
 :root {
-  --app-shell-type-heading-lg-size: 1.75rem;
-  --app-shell-type-heading-lg-line-height: calc(36 / 28);
+  --type-heading-lg-size: 1.75rem;
+  --type-heading-lg-line-height: calc(36 / 28);
 }
 ```
 
@@ -769,7 +785,7 @@ These are visual-composition rules every screen must follow, regardless of patte
 
 | Intent                             | Pick                                                                                                    |
 | ---------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| Destructive action (delete, void)  | `Button variant="destructive"`; `bg-destructive` on custom surfaces; confirm in a dialog at `shadow-lg` |
+| Destructive action (delete, void)  | `Button variant="destructive"`; `bg-danger-solid` on custom surface; confirm in a dialog at `shadow-lg` |
 | Non-blocking caution               | `Badge variant="warning"`, or `bg-warning-surface text-warning-text`                                    |
 | Confirmation / completed state     | `Badge variant="success"`, or `bg-success-surface text-success-text`                                    |
 | Informational callout              | `Badge variant="info"`, or `Alert variant="info"`                                                       |

package/skills/app-shell-patterns/references/migrations.md

@@ -10,6 +10,7 @@ Each entry states which versions are affected, what breaks, how to detect it, an
 
 | Version       | Change                                                                                                                       |
 | ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| 1.18.0        | [Destructive colours now resolve to the danger roles](#1180-destructive-colours-now-resolve-to-the-danger-roles)             |
 | 1.17.0        | [Status and alert tokens now resolve to the colour roles](#1170-status-and-alert-tokens-now-resolve-to-the-colour-roles)     |
 | 1.15.0        | [Base UI 1.8.0 breaks closed-`Select` and dialog-click tests](#1150-base-ui-180-breaks-closed-select-and-dialog-click-tests) |
 | 1.12.0        | [`DateField` / `DatePicker` field chrome moved to `Field.Root`](#1120-datefield--datepicker-field-chrome-moved-to-fieldroot) |
@@ -22,6 +23,26 @@ Each entry states which versions are affected, what breaks, how to detect it, an
 | 1.0.2         | [`Toaster` no longer accepts `richColors`](#102-toaster-no-longer-accepts-richcolors)                                        |
 | before 1.0    | [Pre-1.0 breaking changes](#before-10)                                                                                       |
 
+## 1.18.0: destructive colours now resolve to the danger roles
+
+**Applies to:** apps that show `Button variant="destructive"` in dark mode, apps that use `text-destructive`, `border-destructive` or `bg-destructive` on their own elements, and apps whose theme overrides `--destructive` or `--destructive-foreground`.
+
+1.18.0 makes `--destructive` and `--destructive-foreground` aliases of `--danger-solid` and `--danger-contrast`. The names, `Button variant="destructive"` and `text-destructive` keep working. Nothing errors. `--destructive`, `--destructive-foreground` and their utilities are deprecated and will be removed in the next major; `Button variant="destructive"` will be renamed to `danger` then. Three things change silently:
+
+- **Dark-mode `Button variant="destructive"` is a full `#dc2626` fill.** It was `#f87171` at 60% opacity. The text is `--danger-contrast` (white) and the hover fill is `--danger-solid-hover` instead of 90% opacity. Light mode keeps `#dc2626`.
+- **`text-destructive` resolves to the solid.** In dark mode it changes from `#f87171` to `#dc2626`, which is 3.71:1 on the dark card, below 4.5:1 for text. Components shipped with AppShell now use `text-danger-text` for error text, and invalid borders and focus rings read `--danger-solid`. In dark mode the invalid border changes from `#f87171` to `#dc2626`.
+- **Themes that override `--destructive` no longer reach the components.** `Button`, invalid `Input`, `Textarea`, `Checkbox`, `Field` and `DateField` borders and rings, error text and the `CsvImporter` error cells read `--danger-*`. An override of `--destructive` still changes `bg-destructive` and `text-destructive` on your own elements, so the two reds can drift apart. The `cream` and `bloom` palettes no longer set `--destructive`; their values were the same as the default.
+
+How to detect it: search the app for `destructive` in class names and in theme CSS, including Theme Generator output that sets `--destructive`. Compare `Button variant="destructive"`, an invalid `Input` and an error message in light and dark mode after upgrading.
+
+What to change:
+
+- For text, replace `text-destructive` with `text-danger-text`. For fills, replace `bg-destructive` with `bg-danger-solid`, and `text-destructive-foreground` with `text-danger-contrast`.
+- For tints and borders, use `bg-danger-surface` and `border-danger-border` instead of `bg-destructive/10` and `border-destructive/30`.
+- In a theme that recolours destructive actions, set `--danger-solid` (and `--danger-solid-hover`, `--danger-text`, `--danger-contrast` as needed) instead of `--destructive`. Remove `--destructive` and `--destructive-foreground` from the theme.
+
+The roles are documented in [Styling & theming](https://github.com/tailor-platform/app-shell/blob/main/docs/concepts/styling-theming.md#brand--action). The decision record is `decisions/semantic-color-roles.md`.
+
 ## 1.17.0: status and alert tokens now resolve to the colour roles
 
 **Applies to:** apps that use `bg-status-*`, `text-status-*` or `bg-alert-*` utilities, and apps whose theme overrides `--status-*`, `--alert-*` or `--destructive` to recolour `Badge`, `Alert`, `CsvImporter` or `MetricCard`.
@@ -179,7 +200,7 @@ body {
 
 Toggle dark mode and confirm a real surface changes: inspect a `Card` and watch its computed `background-color` go from `rgb(255, 255, 255)` to `rgb(23, 23, 23)` on the default palette.
 
-Reading the token directly also works — `getComputedStyle(document.documentElement).getPropertyValue("--card")` returns the winning declaration, so a stale copy shows up as its own value. Just compare against the authored notation: AppShell writes `rgba(23, 23, 23, 1)`, not `#171717`, and the computed value preserves that form.
+Reading the token directly also works — `getComputedStyle(document.documentElement).getPropertyValue("--card")` returns the winning declaration, so a stale copy shows up as its own value. Compare against the value the default palette resolves to: in dark mode `--card` returns `#171717`, the gray step it reads. (1.17.0 and earlier return `rgba(23, 23, 23, 1)`.) A copy in your own CSS shows up in the notation you wrote.
 
 ## 1.5.0: `loader` removed from file-based page definitions
 

package/skills/app-shell-patterns/references/patterns/i18n-labels.md

@@ -0,0 +1,139 @@
+---
+title: i18n Labels
+description: Decide UI language before implementation and keep display labels separate from stable data
+---
+
+<!-- GENERATED by docs-kit from docs-src/patterns/i18n-labels.docs.outline.md — do not edit by hand. -->
+
+# i18n Labels
+
+## When to Use
+
+Read this cross-cutting pattern **before implementing a screen**, alongside its page or layout pattern. It applies to single-language apps as well as apps with a language selector. For the complete API and fallback rules, see [defineI18nLabels](../api/define-i18n-labels.md).
+
+## Decide the UI Language First
+
+Record the UI language in the screen or app specification independently of the language used to write the document. An English specification, field name, or enum does not imply English UI copy.
+
+For a Japanese-only app, explicitly pass `locale="ja"` (or `"ja-JP"`) to the root `AppShell`; do not rely on each developer's browser preferences. Keep the same policy across navigation, headings, forms, dialogs, accessibility labels, empty/loading/error states, validation, and notifications. Browser detection is appropriate only when that is the intended product behavior.
+
+Use `defineI18nLabels` by default, including for single-language apps, to avoid a later screen-by-screen extraction. Its current API always requires an `en` base, even when the app selects `ja`. A project may explicitly opt out of catalog-based labels for a deliberately single-language app; record that decision and keep its chosen UI language consistent. AppShell does not force catalog adoption or generate missing translations.
+
+## Key Granularity and Naming
+
+- Use a **flat** map with semantic dotted keys, such as `"requests.list.title"`, `"requests.actions.approve"`, and `"requests.status.PENDING"`. Dots are a naming convention, not nested objects.
+- Name the key after its purpose, not the current wording. Copy edits should not rename keys.
+- One key represents one independently translated message. Translate a whole sentence using typed props rather than joining fragments, so each language controls word order and pluralization.
+- Share genuinely equivalent operations such as `"actions.cancel"`; do not reuse a key merely because two English strings currently happen to match. A navigation group, page heading, and permission description can require different wording.
+- Keep IDs, route segments, field names, enum values, and comparison values untranslated. Translate only their user-facing presentation. User-entered content and proper names are data, not catalog keys.
+
+## Split by Feature, Not by Locale
+
+Start with one `i18n-labels.ts` per feature, containing all of that feature's supported locales. Keep a small shared catalog for genuinely common copy. Export each factory result and its Hook; alias the Hook at import sites when a component needs several catalogs.
+
+```text
+src/
+  i18n-labels.ts                    # shared actions and generic feedback
+  features/
+    requests/
+      i18n-labels.ts                # request keys, with en + ja together
+      request-list.tsx
+    users/
+      i18n-labels.ts                # user keys, with en + ja together
+```
+
+Avoid a global catalog that every feature must edit, but do not create a separate catalog for every small component. Keep definitions at module scope, outside React render functions. Do not add a new wrapper, global translator, or dictionary-merging framework: each `defineI18nLabels` result already supplies its own typed resolvers.
+
+## Example: Stable Status, Localized Display
+
+The shared setup for the runnable example is a feature catalog in `features/requests/i18n-labels.ts`:
+
+```tsx
+import { defineI18nLabels } from "@tailor-platform/app-shell";
+
+export const labels = defineI18nLabels({
+  en: {
+    "requests.list.title": "Requests",
+    "requests.actions.approve": "Approve",
+    "requests.status.PENDING": "Pending approval",
+    "requests.status.APPROVED": "Approved",
+    "requests.status.unknown": "Unknown status",
+  },
+  ja: {
+    "requests.list.title": "申請一覧",
+    "requests.actions.approve": "承認",
+    "requests.status.PENDING": "承認待ち",
+    "requests.status.APPROVED": "承認済み",
+    "requests.status.unknown": "不明な状態",
+  },
+});
+
+export const useRequestT = labels.useT;
+```
+
+Import `useRequestT` from that module in the screen below. Here, `request` stands in for a validated server record; its ID and status remain unchanged in every locale.
+
+<example-preview name="localized-request"></example-preview>
+
+```tsx
+function LocalizedRequest() {
+  const t = useRequestT();
+  const request = { id: "REQ-1042", status: "PENDING" };
+  const canApprove = request.status === "PENDING";
+
+  return (
+    <Layout>
+      <Layout.Header
+        title={t("requests.list.title")}
+        actions={[
+          <Button key="approve" disabled={!canApprove}>
+            {t("requests.actions.approve")}
+          </Button>,
+        ]}
+      />
+      <Layout.Column>
+        <div className="flex items-center gap-2">
+          <span>{request.id}</span>
+          <Badge variant={canApprove ? "warning" : "success"}>
+            {t.dynamic(`requests.status.${request.status}`, t("requests.status.unknown"))}
+          </Badge>
+        </div>
+      </Layout.Column>
+    </Layout>
+  );
+}
+```
+
+The comparison uses `"PENDING"`, never `t("requests.status.PENDING")`. The runtime-key fallback is itself translated. For a known key, prefer `t(key)` to `t.dynamic()` so TypeScript checks it. For a function-valued label, use `t(key, props)`; `t.dynamic()` cannot supply props.
+
+Navigation definitions use the same catalog's `labels.t("requests.list.title")`, not the component Hook. Pass it to `meta.title` or `meta.breadcrumbTitle` so AppShell resolves it with its current locale. Other component props that accept only strings use the Hook's `t()` instead.
+
+## Server-originated Text
+
+Keep **machine-readable meaning** separate from **display copy**:
+
+| Server data                                      | Frontend treatment                                                                                                                    |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
+| Stable enum or status code                       | Keep the value unchanged; map it to a display label                                                                                   |
+| Domain error code plus structured parameters     | Validate the response, select a known label by code, and pass parameters to a function-valued label                                   |
+| Unknown error code or unexpected response shape  | Show a localized generic failure message; preserve a safe support identifier when available                                           |
+| User-authored text, identifiers, or proper names | Display as data, not as a label key                                                                                                   |
+| English prose with no usable code/parameters     | It cannot be reliably localized or used for matching; show a localized fallback and treat structured errors as a backend prerequisite |
+
+For example, an `APPROVAL_ROUTE_BLOCKED` code plus a separate `routeName` parameter can select a message like `"requests.errors.routeBlocked"` with `{ routeName }`. Do not find the route name by parsing an English sentence, translate arbitrary server text as a catalog key, or compare translated error messages to decide behavior.
+
+If a transport collapses all domain codes into `PIPELINE_ERROR`, the frontend cannot recover the lost meaning. Fixing error propagation is a platform concern, not something this pattern or `defineI18nLabels` solves. Do not pretend that a generic code identifies a specific domain failure. Avoid showing raw technical error details to end users.
+
+## Validation and E2E
+
+- Compile catalogs and call sites: explicitly declared locales must supply the English base keys and compatible props. This checks structure, not the language or quality of the wording.
+- Verify the intended locale in the browser, including navigation, dialogs, empty/error states, accessibility names, notifications, and unknown-code fallbacks. Do not assume successful type checks prove the absence of mixed-language UI.
+- Test business state with stable codes. Test rendered labels in the selected locale; do not leave English display expectations in Japanese UI tests.
+- Scope E2E locators by role and region, such as a heading in `main` or a button inside a named dialog. A translated phrase can legitimately occur in the sidebar, breadcrumb, and page; an unscoped text locator can become ambiguous.
+- When adding a locale, review the app's catalogs **and** built-in component coverage. Custom catalog translations do not automatically translate AppShell's built-in labels.
+
+## Related
+
+- [defineI18nLabels](../api/define-i18n-labels.md) — `useT`, `t.dynamic`, function props, metadata, and fallback behavior
+- [useResolvedLocale](../api/use-resolved-locale.md) — full locale for date and number formatting
+- [Sidebar Navigation](../concepts/sidebar-navigation.md) — localized groups, sections, and item titles

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

@@ -68,6 +68,7 @@ Omit `fill` on pages that should flow and scroll naturally (forms, dashboards, a
 - **Tabs only above `DataTable`** — best when workflows are organized as obvious buckets
 - **Tabs + chips** — when buckets are primary and finer filters help
 - **Bulk actions** — `rowSelection.actions` on `useDataTable` turns `DataTable.Footer` into a bulk-action bar while rows are selected; see `interaction/multi-select`
+- **Targeted inline entry** — opt a typed column into `edit` for quantities, text, choices, or dates. Observe raw drafts with optional `onValueChange`; validate and adopt confirmed editor outputs with required `onValueCommitted`. The page owns persistence, optimistic updates, error feedback, and rollback, whether saving each field immediately or collecting confirmed rows for Save/Cancel. Use `canEdit(row, { selected })` for per-row control; see [DataTable inline editing](../components/data-table.md#inline-editing) and [consumer-owned saving patterns](../components/data-table.md#consumer-owned-saving-patterns).
 - **`Table` primitives** — small static lists without collection hooks
 
 ## Constraints
@@ -78,7 +79,7 @@ Omit `fill` on pages that should flow and scroll naturally (forms, dashboards, a
 - 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 go in the footer bar from `rowSelection.actions`, which appears only while ≥1 row is selected — never a separate toolbar or floating bar
-- Whole row is clickable via `onClickRow`; wrap the primary identifier cell in `<Link>` for keyboard/SR access. 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. Editable cells stop row-click navigation so users can enter a value without opening detail.
 - 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
 
@@ -89,5 +90,5 @@ Omit `fill` on pages that should flow and scroll naturally (forms, dashboards, a
 - Tabs that mutate only local UI state while pagination/filters assume the full server set
 - Using `<table>` directly instead of `<DataTable>` for live collections
 - Client-side filtering on 1000+ records without server-side support
-- Inline editable cells — use `pattern/detail/*` or `pattern/form/modal` instead
+- Treating inline entry as a full form or save framework: cross-field rules, business-error draft retention, and save/rollback orchestration belong to the page or a dedicated form; use `pattern/detail/*` or `pattern/form/modal` when that is the primary workflow
 - Per-row "View" / "Open" buttons duplicating the row-click navigation