@tailor-platform/app-shell 1.17.0 → 1.19.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.
 
@@ -208,17 +217,24 @@ Each intent has eight roles. The intents are `info`, `success`, `warning`, `dang
 <span className="rounded-md bg-success-surface px-2 py-0.5 text-success-text">Paid</span>
 ```
 
-In the default palette, `text` on `surface` and `contrast` on `solid` and `solid-hover` are at least 4.5:1 for the four hue intents, in light and dark mode, on `--card` and `--background`. A unit test checks this from the shipped CSS. `text` on `surface-hover` is held at 4.2:1 by the same test; it is below 4.5:1 for `danger` and `success` in light mode. The test does not cover the `cream` and `bloom` palettes or the `neutral` intent.
+The hue roles have the same values in every shipped palette. `cream` and `bloom` change brand and surface colors, not status colors. The `neutral` roles follow the palette, because they read the system tokens.
+
+**Contrast.** AppShell's thresholds are 4.5:1 for text (WCAG 1.4.3) and 3:1 for non-text (WCAG 1.4.11). In every shipped palette (`default`, `cream`, `bloom`), in light and dark mode, on `--card` and `--background`, `text` on `surface` and `contrast` on `solid` and `solid-hover` are at least 4.5:1 for the four hue intents, and `danger` `solid` (the invalid-input border) is at least 3:1. A browser test checks this in Chromium against the built stylesheet. Known exceptions:
+
+- `text` on `surface-hover` is below 4.5:1 for `danger` and `success` in light mode. The test holds it at 4.2:1 or more.
+- In `cream` and `bloom`, the main content area is transparent over the shell gradient. At the top of the `bloom` light gradient, `text` on `surface` is 4.49:1 for `success` and 4.48:1 for `danger`. Put status content on a card when it needs to pass.
+- `warning` `solid` and `indicator` are 2.15:1 against a light card. Use them with a label, not as the only sign of a state.
+- The `neutral` intent reads the system tokens and is not checked.
 
 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
 
 `--sidebar`, `--sidebar-foreground`, `--sidebar-border`, `--sidebar-primary(-foreground)`, `--sidebar-accent(-foreground)`, `--sidebar-ring` → `bg-sidebar`, `text-sidebar-foreground`, and so on. These let a palette tint the shell independently of page content.
 
-`--chart-1` … `--chart-5` → `bg-chart-1`, `text-chart-1`, `fill-chart-1`. Use them in order for categorical series.
+`--chart-1` … `--chart-5` → `bg-chart-1`, `text-chart-1`, `fill-chart-1`. Use them in order for categorical series. They tell series apart and carry no status, so they are not semantic roles and have literal values.
 
 #### Alerts
 
@@ -274,7 +290,7 @@ There are 8 core roles and 2 relaxed body variants:
 | `heading-sm`      | `text-heading-sm`      | 14px / 20px        | 600    | Sub-section heading                             |
 | `body-md`         | `text-body-md`         | 14px / 20px        | 400    | Body copy, descriptions                         |
 | `body-sm`         | `text-body-sm`         | 12px / 16px        | 400    | Caption, timestamp, metadata                    |
-| `label-md`        | `text-label-md`        | 14px / 20px        | 500    | Field label, short UI text, figures in a table  |
+| `label-md`        | `text-label-md`        | 14px / 20px        | 500    | Field label, short UI text                      |
 | `label-sm`        | `text-label-sm`        | 12px / 16px        | 500    | Small label, badge text                         |
 | `code-sm`         | `text-code-sm`         | 12px / 18px        | 400    | ID and code. Use with `font-mono`               |
 | `body-md-relaxed` | `text-body-md-relaxed` | 14px / 24px        | 400    | Long text, such as a chat message or a document |
@@ -288,11 +304,11 @@ 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`           |
-| Numeric value in a table or field | `text-label-md tabular-nums`                   |
+| Numeric value in a table or field | `text-body-md tabular-nums`                    |
 | ID, code                          | `font-mono text-code-sm text-muted-foreground` |
 
 <example-preview name="typography-roles"></example-preview>
@@ -395,23 +411,31 @@ function TypographyRoles() {
 }
 ```
 
+For headings, body copy, labels, and captions, use the [`Text`](../components/text.md) component. Do not style a bare `p`, `h1` to `h6`, or `span` with `text-sm`, `text-xs`, or `font-*`. A form field label is [`Field.Label`](../components/form.md), which already has the `label-md` role. `Text` 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). To set the element, such as the heading level, use an element component (`Text.h1` to `Text.h6`, `Text.p`, `Text.span`, `Text.div`):
+
+```tsx
+<Text.h3 variant="heading-md">Line items</Text.h3>
+<Text variant="body-md" className="text-muted-foreground">Description copy</Text>
+<Text variant="body-sm" className="text-muted-foreground">Updated 2h ago</Text>
+```
+
+Use the role utility when you style an element that you render yourself, such as a table header cell or a link:
+
 ```tsx
-<h2 className="text-heading-md">Section</h2>
-<p className="text-body-md text-muted-foreground">Description copy</p>
-<span className="text-body-sm text-muted-foreground">Updated 2h ago</span>
+<th className="text-label-md text-muted-foreground">Amount</th>
 ```
 
-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.
+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 use the roles: content text renders with `Text`, and controls use the role utility.
 
 **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 +444,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 +793,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`. In JS and TS files, the `no-deprecated-tokens` rule in `@tailor-platform/eslint-plugin-app-shell` reports these names and the role to use instead. The rule is available from version 0.2.0 of the plugin, and it does not read CSS files. 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`.
@@ -32,7 +53,7 @@ Each entry states which versions are affected, what breaks, how to detect it, an
 - **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.
+How to detect it: search the app for `status-`, `alert-` and theme overrides of `--status-`, `--alert-` and `--destructive`. In JS and TS files, the `no-deprecated-tokens` rule in `@tailor-platform/eslint-plugin-app-shell` reports these names and the role to use instead. The rule is available from version 0.2.0 of the plugin, and it does not read CSS files. Compare `Badge` and `Alert` in light and dark mode after upgrading.
 
 What to change:
 
@@ -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/pages/document-detail.md

@@ -209,7 +209,7 @@ saying so, and it is never a substitute for scrolling or paging.
 
 Columns, left to right:
 
-1. **Identity** — the item name, with the SKU beneath it in muted mono `text-xs`. Two facts, one column.
+1. **Identity** — the item name, with the SKU beneath it in muted `code-sm`. Two facts, one column.
 2. **The record's own numbers** — quantity, unit of measure, unit price. Every document has these.
 3. **Numbers from related records**, where they exist and the reader needs them (see below).
 4. **Subtotal**, derived, last.
@@ -535,7 +535,7 @@ says "clickable" without a hover, and the resting underline is noise. Add
 - **Internal** (another route in the app) → the `Link` exported by app-shell, with `to`. Never a bare `<a href>` for an in-app route.
 - **External** (another system) → `<a target="_blank" rel="noopener noreferrer">` with a lucide `ExternalLink` at `size-3` after the label, so the new tab is signposted. There is no dedicated external-link component; this is the whole recipe.
 - **Identifiers** keep their `font-mono` on top of the link style.
-- **A `render` field owns its typography.** `DescriptionCard` applies none of its value styling to custom output, so a bare string from `render` reads a size larger than the values around it. Wrap it in `text-sm font-medium text-foreground` — the reference implementation's `Value` helper.
+- **A `render` field owns its typography.** `DescriptionCard` applies none of its value styling to custom output, so a bare string from `render` does not match the values around it. Wrap it in `Text` with `variant="body-md"` and `text-foreground`, the same role the built-in values use — the reference implementation's `Value` helper.
 
 ## Patterns for the parts
 
@@ -571,6 +571,7 @@ import {
   Link,
   Table,
   Tabs,
+  Text,
 } from "@tailor-platform/app-shell";
 import type { ActionPanelProps } from "@tailor-platform/app-shell";
 import {
@@ -614,15 +615,17 @@ const formatDay = (value: string) =>
 
 /**
  * A `render` field owns its own presentation — DescriptionCard applies none of
- * the built-in value typography to it — so match that style here or the two
- * dates read a size larger than every other value on the card.
+ * the built-in value typography to it — so use the same role here (`body-md`)
+ * or the two dates do not match every other value on the card.
  */
 const Value = ({ children }: { children: React.ReactNode }) => (
-  <span className="text-sm font-medium text-foreground">{children}</span>
+  <Text variant="body-md" className="text-foreground" render={<span />}>
+    {children}
+  </Text>
 );
 
 /** House link: primary colour at rest, underline only on hover. */
-const DOC_LINK = "font-mono text-xs text-primary underline-offset-4 hover:underline";
+const DOC_LINK = "font-mono text-code-sm text-primary underline-offset-4 hover:underline";
 
 export default function PurchaseOrderDetailPage({
   order,
@@ -676,16 +679,18 @@ export default function PurchaseOrderDetailPage({
           destructive: it's a problem to clear, not information to read.
           Each hold is released on its own, beside its own reason. */}
       {order.holds.length > 0 && (
-        <Card.Root className="border-destructive">
+        <Card.Root className="border-danger-solid">
           <Card.Header title="On hold" />
           <Card.Content className="flex flex-col gap-3">
             {order.holds.map((hold) => (
               <div key={hold.id} className="flex items-start justify-between gap-4">
                 <div>
-                  <p className="text-sm font-medium text-foreground">{hold.reason}</p>
-                  <p className="text-xs text-muted-foreground">
+                  <Text variant="label-md" className="text-foreground" render={<p />}>
+                    {hold.reason}
+                  </Text>
+                  <Text variant="body-sm" className="text-muted-foreground">
                     Placed by {hold.placedBy} on {formatDay(hold.placedAt)}
-                  </p>
+                  </Text>
                 </div>
                 <Button
                   size="sm"
@@ -810,7 +815,9 @@ export default function PurchaseOrderDetailPage({
         <Card.Header title="Line items" />
         <Card.Content padding="none">
           {order.lineItems.length === 0 ? (
-            <p className="px-6 text-sm text-muted-foreground">No line items on this order.</p>
+            <Text variant="body-md" className="px-6 text-muted-foreground">
+              No line items on this order.
+            </Text>
           ) : (
             <Table.Root>
               <Table.Header>
@@ -829,9 +836,9 @@ export default function PurchaseOrderDetailPage({
                     {/* Two facts, one column. */}
                     <Table.Cell>
                       <span className="block">{line.itemName}</span>
-                      <span className="block font-mono text-xs text-muted-foreground">
+                      <Text variant="code-sm" className="block text-muted-foreground">
                         {line.sku}
-                      </span>
+                      </Text>
                     </Table.Cell>
                     <Table.Cell align="right" className="tabular-nums">
                       {line.qty}
@@ -844,9 +851,13 @@ export default function PurchaseOrderDetailPage({
                     <Table.Cell align="right" className="tabular-nums">
                       {line.received}
                       {line.received !== line.qty && (
-                        <span className="ml-1 text-xs text-muted-foreground">
+                        <Text
+                          variant="body-sm"
+                          className="ml-1 text-muted-foreground"
+                          render={<span />}
+                        >
                           ({line.qty - line.received})
-                        </span>
+                        </Text>
                       )}
                     </Table.Cell>
                     <Table.Cell align="right" className="tabular-nums">
@@ -877,9 +888,9 @@ export default function PurchaseOrderDetailPage({
         <Card.Header title="Goods receipts" />
         <Card.Content padding="none">
           {order.goodsReceipts.length === 0 ? (
-            <p className="px-6 text-sm text-muted-foreground">
+            <Text variant="body-md" className="px-6 text-muted-foreground">
               No goods receipts linked to this order.
-            </p>
+            </Text>
           ) : (
             <Table.Root>
               <Table.Header>
@@ -922,15 +933,15 @@ export default function PurchaseOrderDetailPage({
                 href={file.href}
                 target="_blank"
                 rel="noopener noreferrer"
-                className="inline-flex items-center gap-2 text-sm text-primary underline-offset-4 hover:underline"
+                className="inline-flex items-center gap-2 text-body-md text-primary underline-offset-4 hover:underline"
               >
                 <FileText className="size-4 shrink-0" />
                 {file.name}
                 <ExternalLink className="size-3 shrink-0" />
               </a>
-              <span className="shrink-0 text-xs text-muted-foreground">
+              <Text variant="body-sm" className="shrink-0 text-muted-foreground" render={<span />}>
                 {file.sizeLabel} · {formatDay(file.uploadedAt)}
-              </span>
+              </Text>
             </div>
           ))}
         </Card.Content>
@@ -1011,9 +1022,9 @@ export default function PurchaseOrderDetailPage({
                         <Table.Row key={line.id}>
                           <Table.Cell>
                             <span className="block">{line.account}</span>
-                            <span className="block font-mono text-xs text-muted-foreground">
+                            <Text variant="code-sm" className="block text-muted-foreground">
                               {line.accountCode}
-                            </span>
+                            </Text>
                           </Table.Cell>
                           <Table.Cell align="right" className="tabular-nums">
                             {line.debit === null ? "—" : `${line.debit.toLocaleString()}`}
@@ -1047,14 +1058,14 @@ export default function PurchaseOrderDetailPage({
                 href={externalSource.href}
                 target="_blank"
                 rel="noopener noreferrer"
-                className="inline-flex items-center gap-1 text-sm text-primary underline-offset-4 hover:underline"
+                className="inline-flex items-center gap-1 text-body-md text-primary underline-offset-4 hover:underline"
               >
                 {externalSource.recordLabel}
                 <ExternalLink className="size-3" />
               </a>
-              <p className="mt-1 text-xs text-muted-foreground">
+              <Text variant="body-sm" className="mt-1 text-muted-foreground">
                 Synced {externalSource.syncedAt.toLocaleDateString()}
-              </p>
+              </Text>
             </Card.Content>
           </Card.Root>
         )}

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

@@ -147,7 +147,9 @@ placeholder.
   render_ — a submit gate, a dependent placeholder, a live character count. That state is
   load-bearing, not mirrored; see `form/composer`.
 - **`Field.Control` is already a styled input.** Write `<Field.Control />`, not
-  `<Field.Control render={<Input />} />`.
+  `<Field.Control render={<Input />} />`. Every other control — `Select`, `Combobox`,
+  `Autocomplete`, `Checkbox`, `Textarea`, `DateField`, `DatePicker` — goes directly under
+  `Field.Root`. Passing one to `Field.Control`'s `render` draws a second frame around it.
 - **Object items need `itemToStringValue`.** Items shaped `{ value, label }` submit `value`
   automatically; any other object submits as a JSON string unless you supply it.
 - **Server errors go through `Form`'s `errors` prop**, keyed by field `name` — not a toast or a
@@ -165,4 +167,5 @@ placeholder.
 - Registering the create path as a separate top-level route — that unmounts the parent list
 - Reaching for React Hook Form on a form this size — `onFormSubmit` already covers it
 - Holding a `Select`/`Combobox` value in `useState` just to submit it — `Field.Root` already does
+- Wrapping a `Select`/`Combobox` in `Field.Control` (`render={<Select />}`) — a double frame
 - Surfacing API validation failures in a toast or banner instead of routing them via `errors`

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