@tailor-platform/app-shell 1.16.0 → 1.18.0

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

@@ -10,6 +10,8 @@ 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) |
 | 1.11.0        | [React 19.2.7 and React Router v8 required](#1110-react-1927-and-react-router-v8-are-now-required)                           |
@@ -21,6 +23,46 @@ 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`.
+
+1.17.0 adds semantic colour roles, `--{info|success|warning|danger|neutral}-{surface|surface-hover|border|solid|solid-hover|text|contrast|indicator}`, bridged as Tailwind colours such as `bg-success-surface` and `text-danger-text`. The old `--status-*` and `--alert-*` tokens still exist and still work, but they no longer hold their own colours: each one now resolves to a role (for example `--status-completed` is `var(--success-solid)`). They are deprecated and will be removed in the next major. Nothing errors. Three things change silently:
+
+- **Colours change.** `bg-status-*` and `bg-alert-*` resolve to the role values. For example `bg-status-completed` is `#15803d` instead of `#22c55e`. `--status-default` follows `--muted-foreground` instead of a fixed `#737373`.
+- **Component recolouring moves to the roles.** `Badge`, `Alert`, `CsvImporter` and `MetricCard` read the roles directly. A theme that overrides `--status-*` or `--alert-*` no longer changes these components; override `--{intent}-*` instead. `Badge` `error` / `subtle-error` and `Alert` `error` read `--danger-*`, so overriding `--destructive` no longer reaches them either. `Button variant="destructive"` and `text-destructive` still follow `--destructive`.
+- **`text-status-*` loses contrast in dark mode.** The `--status-*` values are now the step-9 fills, which are below 4.5:1 as text on the dark card.
+
+How to detect it: search the app for `status-`, `alert-` and theme overrides of `--status-`, `--alert-` and `--destructive`. Compare `Badge` and `Alert` in light and dark mode after upgrading.
+
+What to change:
+
+- Replace `text-status-completed` with `text-success-text`, `text-status-attention` with `text-warning-text`, `text-status-danger` with `text-danger-text`, and `text-status-neutral` with `text-info-text`.
+- Replace `bg-status-completed/10 border-status-completed/30` style tints with `bg-success-surface border-success-border`. The same applies to the other intents and to `bg-alert-*` / `border-alert-*`.
+- In a theme that recolours the status components, set the roles (`--success-solid`, `--danger-text`, ...) instead of `--status-*`, `--alert-*` or `--destructive`.
+
+The roles are documented in [Styling & theming](https://github.com/tailor-platform/app-shell/blob/main/docs/concepts/styling-theming.md#semantic-color-roles). The decision record is `decisions/semantic-color-roles.md`.
+
 ## 1.15.0: Base UI 1.8.0 breaks closed-`Select` and dialog-click tests
 
 **Applies to:** apps with unit tests that assert `Select` options without opening the `Select`, and apps with Playwright tests that click buttons inside a `Dialog` or `AlertDialog`.
@@ -158,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/pages/document-detail.md

@@ -183,7 +183,7 @@ time, and the record is unblocked only once every one is released.
 ### 4. Line items
 
 `Card.Root` → `Card.Header` (title, plus a one-line description where the
-columns need explaining) → `Card.Content className="px-0!"` → `Table.Root`.
+columns need explaining) → `Card.Content padding="none"` → `Table.Root`.
 
 Fetch the line items with the record, sorted explicitly so the order is stable
 across reloads, and render them as a plain `Table`. For the typical document —
@@ -773,7 +773,7 @@ export default function PurchaseOrderDetailPage({
       would have been a link field on the summary instead. */}
       <Card.Root>
         <Card.Header title="Source requisitions" />
-        <Card.Content className="px-0!">
+        <Card.Content padding="none">
           <Table.Root>
             <Table.Header>
               <Table.Row>
@@ -808,7 +808,7 @@ export default function PurchaseOrderDetailPage({
       enough to page. No container padding; the cells inset themselves. */}
       <Card.Root>
         <Card.Header title="Line items" />
-        <Card.Content className="px-0!">
+        <Card.Content padding="none">
           {order.lineItems.length === 0 ? (
             <p className="px-6 text-sm text-muted-foreground">No line items on this order.</p>
           ) : (
@@ -875,7 +875,7 @@ export default function PurchaseOrderDetailPage({
       relationship is possible, so the reader learns it exists. */}
       <Card.Root>
         <Card.Header title="Goods receipts" />
-        <Card.Content className="px-0!">
+        <Card.Content padding="none">
           {order.goodsReceipts.length === 0 ? (
             <p className="px-6 text-sm text-muted-foreground">
               No goods receipts linked to this order.
@@ -997,7 +997,7 @@ export default function PurchaseOrderDetailPage({
                   title="Journal entry"
                   description="Booked when this order was posted."
                 />
-                <Card.Content className="px-0!">
+                <Card.Content padding="none">
                   <Table.Root>
                     <Table.Header>
                       <Table.Row>
@@ -1096,7 +1096,7 @@ enforced across every detail screen once settled.
 ## Constraints
 
 - **Every main-column section sits in a `Card.Root`** — except `DescriptionCard`, which contains itself, and `Alert`, which is a banner. No bare `<div>` sections.
-- **A table in a card needs ONE geometry change, not two.** Zero the card's padding (`Card.Content className="px-0!"`, or drop `Card.Content`) and leave the table container alone. `Table.Head` and `Table.Cell` already inset their own first and last cells by 24px; padding on the table container stacks on top of that and pushes the first column 24px right of the card title.
+- **A table in a card goes in `Card.Content padding="none"`, and nothing else changes.** Don't drop `Card.Content` or zero its padding with a class instead: the prop also keeps row backgrounds inside the card's rounded corners and removes a nested `DataTable`'s own border. Leave the table container alone too. `Table.Head` and `Table.Cell` already inset their own first and last cells by 24px; padding on the table container stacks on top of that and pushes the first column 24px right of the card title.
 - **Bare `YYYY-MM-DD` dates must not use `type: "date"`.** `DescriptionCard` hands the value to `new Date(...)`, which reads a date-only string as UTC midnight and renders the previous day west of Greenwich. Pre-format those as text via `render`. Real timestamps keep `type: "date"`, with `emptyBehavior: "hide"` when nullable.
 - **`ActionPanel` is workflow-only.** No navigation, no "view related record" — those are links in the cards that hold them.
 - **Never rely on a query cap to bound the line-items table.** If the cap can be reached, page the lines.

package/skills/app-shell-patterns/references/patterns/form-modal.md

@@ -28,32 +28,36 @@ function ModalForm() {
           <Dialog.Title>Add address</Dialog.Title>
           <Dialog.Description>Add a shipping address to this order.</Dialog.Description>
         </Dialog.Header>
-        <form
-          onSubmit={(event) => {
-            event.preventDefault();
-            const data = new FormData(event.currentTarget);
-            window.alert(`Saving ${data.get("label") ?? ""}`);
-          }}
+        {/*
+         * `onFormSubmit` fires only after validation passes and receives the
+         * registered field values — no `<form onSubmit>` + `new FormData(...)`.
+         */}
+        <Form<AddressDraft>
+          noValidate
+          onFormSubmit={(values) => window.alert(`Saving ${values.label}`)}
         >
           <div className="flex flex-col gap-4 py-4">
             <Field.Root name="label">
               <Field.Label>Label</Field.Label>
-              <Field.Control render={<Input />} />
+              <Field.Control required />
+              <Field.Error match="valueMissing">Label is required.</Field.Error>
             </Field.Root>
             <Field.Root name="street">
               <Field.Label>Street</Field.Label>
-              <Field.Control render={<Input />} />
+              <Field.Control required />
+              <Field.Error match="valueMissing">Street is required.</Field.Error>
             </Field.Root>
             <Field.Root name="city">
               <Field.Label>City</Field.Label>
-              <Field.Control render={<Input />} />
+              <Field.Control required />
+              <Field.Error match="valueMissing">City is required.</Field.Error>
             </Field.Root>
           </div>
           <Dialog.Footer>
-            <Dialog.Close render={<Button variant="ghost" />}>Cancel</Dialog.Close>
+            <Dialog.Close render={<Button type="button" variant="ghost" />}>Cancel</Dialog.Close>
             <Button type="submit">Save</Button>
           </Dialog.Footer>
-        </form>
+        </Form>
       </Dialog.Content>
     </Dialog.Root>
   );
@@ -86,27 +90,28 @@ function ModalFormRouted() {
           <Dialog.Header>
             <Dialog.Title>Create product</Dialog.Title>
           </Dialog.Header>
-          <form
-            onSubmit={(event) => {
-              event.preventDefault();
-              const data = new FormData(event.currentTarget);
-              window.alert(`Saving ${data.get("name") ?? ""}`);
+          <Form<ProductDraft>
+            noValidate
+            onFormSubmit={(values) => {
+              window.alert(`Saving ${values.name}`);
               setCreateOpen(false);
             }}
           >
             <div className="flex flex-col gap-4 py-4">
               <Field.Root name="name">
                 <Field.Label>Name</Field.Label>
-                <Field.Control render={<Input />} />
+                <Field.Control required />
+                <Field.Error match="valueMissing">Name is required.</Field.Error>
               </Field.Root>
             </div>
             <Dialog.Footer>
-              <Button variant="ghost" onClick={() => setCreateOpen(false)}>
+              {/* Inside a `<Form>` an untyped button submits — Cancel must be `type="button"`. */}
+              <Button type="button" variant="ghost" onClick={() => setCreateOpen(false)}>
                 Cancel
               </Button>
               <Button type="submit">Save</Button>
             </Dialog.Footer>
-          </form>
+          </Form>
         </Dialog.Content>
       </Dialog.Root>
     </Layout>
@@ -133,7 +138,8 @@ placeholder.
 - **`Form` + `Field` is the default stack.** They wrap Base UI and ship with AppShell — no extra
   dependency.
 - **Submit via `onFormSubmit(values)`.** It fires only after validation passes. Do not hand-roll
-  `<form onSubmit>` + `new FormData(...)` — that skips validation and server-error routing.
+  `<form onSubmit>` + `new FormData(...)` — that bypasses `Form`'s field validation and server-error
+  routing.
 - **`onFormSubmit` reads registered `Field.Root`s, not the DOM.** So every control — including
   `Select`, `Combobox`, and `Autocomplete` — just needs wrapping in a `Field.Root name="…"`. They
   need **no `name` of their own and no `useState`**. Mirroring field values into React state is the

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