@tailor-platform/app-shell 1.19.0 → 1.20.0

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

@@ -219,12 +219,11 @@ Each intent has eight roles. The intents are `info`, `success`, `warning`, `dang
 
 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:
+**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 all five intents, `text` on `surface-hover` is at least 4.5:1 for `neutral`, 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.
+- `text` on `surface-hover` is below 4.5:1 for `danger` and `success` in light mode. This is on purpose: a lighter step would make the tinted background hard to tell apart from the page, and the hover harder to see. 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.
 
@@ -411,7 +410,7 @@ 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`):
+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-*`. The `prefer-text-components` rule in `@tailor-platform/eslint-plugin-app-shell` reports a size on these elements, and a weight, line height, or letter spacing that is set without a role. It is not in `recommended`, so enable it in your `oxlint.config.ts`. 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>
@@ -530,21 +529,22 @@ Always give motion a reduced-motion escape (`motion-reduce:transition-none`, or
 
 ### Z-index
 
-These exist as raw `:root` variables in the shipped base layer, but are **not** bridged into Tailwind — `z-sidebar` is not a class. Use the stock numeric utility, or reference the variable when you need it to track AppShell's layering:
+These exist as raw `:root` variables in the shipped base layer, but are **not** bridged into Tailwind — `z-nav` is not a class. Use the stock numeric utility, or reference the variable when you need it to track AppShell's layering:
 
-| Token              | Value | Use                           |
-| ------------------ | ----- | ----------------------------- |
-| `--z-sidebar`      | 10    | persistent sidebar            |
-| `--z-sidebar-rail` | 20    | sidebar collapsed rail        |
-| `--z-popup`        | 50    | menu, tooltip, popover        |
-| `--z-overlay`      | 50    | modal, sheet, dialog backdrop |
+| Token        | Value | Use                                                   |
+| ------------ | ----- | ----------------------------------------------------- |
+| `--z-nav`    | 10    | persistent sidebar                                    |
+| `--z-portal` | 50    | menu, tooltip, popover, modal, sheet, dialog backdrop |
+| `--z-toast`  | 100   | toast, always above overlays                          |
+
+The old names still resolve: `--z-sidebar` is an alias of `--z-nav`, and `--z-popup` and `--z-overlay` are aliases of `--z-portal`. They are deprecated and will be removed in the next major. `--z-sidebar-rail` (20) is a value inside the sidebar, not a layer.
 
 ```tsx
 <div className="z-50" />
-<div className="z-[var(--z-popup)]" />
+<div className="z-[var(--z-portal)]" />
 ```
 
-Never invent a z value — `z-index: 9999` is always wrong. Popups and overlays share `50` intentionally: sequencing comes from DOM order, not z escalation.
+Never invent a z value — `z-index: 9999` is always wrong. Popups and overlays share `50` intentionally: sequencing comes from DOM order, not z escalation. Every floating AppShell component (dialog, sheet, menu, select, combobox, tooltip, toast) renders through a portal to the end of `body`, and the layout root is `isolation: isolate`, so a z-index inside the page never reaches them. The toast is the one layer above the band: it is always visible over an open dialog or sheet.
 
 ### Icons
 

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.20.0        | [z-index tokens renamed; old names are aliases](#1200-z-index-tokens-renamed-old-names-are-aliases)                          |
 | 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) |
@@ -23,6 +24,25 @@ 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.20.0: z-index tokens renamed; old names are aliases
+
+**Applies to:** apps whose theme overrides `--z-sidebar`, `--z-sidebar-rail`, `--z-popup` or `--z-overlay`, and apps that reference those names on their own elements.
+
+1.20.0 names the z-index tokens by layer: `--z-nav` (10), `--z-portal` (50) and `--z-toast` (100). The old names keep working: `--z-sidebar` is now `var(--z-nav)`, and `--z-popup` and `--z-overlay` are both `var(--z-portal)`. They are deprecated and will be removed in the next major. Nothing errors, and nothing moves. Two things change silently:
+
+- **Themes that override an old name no longer reach the components.** The sidebar reads `--z-nav`; dialogs, sheets, menus, selects, comboboxes and tooltips read `--z-portal`. An override of `--z-popup` or `--z-overlay` still changes `z-[var(--z-popup)]` on your own elements, but not AppShell's layers. There is one token for the whole portal band because popups and overlays share the value on purpose: the order inside the band is the order of opening, so a `Select` inside a `Dialog` is above it. Raising one above the other puts a `Select` or `Menu` opened inside a `Dialog` behind the dialog.
+- **`--z-sidebar-rail` is no longer read by AppShell.** The sidebar rail orders itself inside the sidebar. The variable is still declared (20) for elements of your own that reference it, and it leaves the documented table.
+
+How to detect it: search the app for `--z-sidebar`, `--z-popup` and `--z-overlay` in class names and in theme CSS. Open a `Dialog` with a `Select` inside it, a `Dialog` over a `Sheet`, and fire a toast over each after upgrading; the order should not change.
+
+What to change:
+
+- Replace `--z-sidebar` with `--z-nav`, and `--z-popup` and `--z-overlay` with `--z-portal`, in class names such as `z-[var(--z-portal)]` and in theme CSS.
+- In a theme that moves AppShell's layers, set `--z-nav`, `--z-portal` or `--z-toast` instead of the old names. Remove the old names from the theme.
+- Do not set `--z-sidebar-rail`; it no longer affects the rail.
+
+The tokens are documented in [Styling & theming](https://github.com/tailor-platform/app-shell/blob/main/docs/concepts/styling-theming.md#z-index). The decision record is `decisions/floating-ui-stacking.md`.
+
 ## 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`.

package/skills/app-shell-patterns/references/pages/document-detail.md

@@ -619,9 +619,9 @@ const formatDay = (value: string) =>
  * or the two dates do not match every other value on the card.
  */
 const Value = ({ children }: { children: React.ReactNode }) => (
-  <Text variant="body-md" className="text-foreground" render={<span />}>
+  <Text.span variant="body-md" className="text-foreground">
     {children}
-  </Text>
+  </Text.span>
 );
 
 /** House link: primary colour at rest, underline only on hover. */
@@ -685,9 +685,9 @@ export default function PurchaseOrderDetailPage({
             {order.holds.map((hold) => (
               <div key={hold.id} className="flex items-start justify-between gap-4">
                 <div>
-                  <Text variant="label-md" className="text-foreground" render={<p />}>
+                  <Text.p variant="label-md" className="text-foreground">
                     {hold.reason}
-                  </Text>
+                  </Text.p>
                   <Text variant="body-sm" className="text-muted-foreground">
                     Placed by {hold.placedBy} on {formatDay(hold.placedAt)}
                   </Text>
@@ -851,13 +851,9 @@ export default function PurchaseOrderDetailPage({
                     <Table.Cell align="right" className="tabular-nums">
                       {line.received}
                       {line.received !== line.qty && (
-                        <Text
-                          variant="body-sm"
-                          className="ml-1 text-muted-foreground"
-                          render={<span />}
-                        >
+                        <Text.span variant="body-sm" className="ml-1 text-muted-foreground">
                           ({line.qty - line.received})
-                        </Text>
+                        </Text.span>
                       )}
                     </Table.Cell>
                     <Table.Cell align="right" className="tabular-nums">
@@ -939,9 +935,9 @@ export default function PurchaseOrderDetailPage({
                 {file.name}
                 <ExternalLink className="size-3 shrink-0" />
               </a>
-              <Text variant="body-sm" className="shrink-0 text-muted-foreground" render={<span />}>
+              <Text.span variant="body-sm" className="shrink-0 text-muted-foreground">
                 {file.sizeLabel} · {formatDay(file.uploadedAt)}
-              </Text>
+              </Text.span>
             </div>
           ))}
         </Card.Content>

package/skills/app-shell-patterns/references/patterns/interaction-multi-select.md

@@ -112,7 +112,7 @@ function InteractionMultiSelect() {
               cancelled; shipped orders are excluded. Cancelled orders can't be reopened.
             </Dialog.Description>
           </Dialog.Header>
-          {cancelError && <p role="alert">{cancelError}</p>}
+          {cancelError && <Text.p role="alert">{cancelError}</Text.p>}
           <Dialog.Footer>
             <Dialog.Close render={<Button variant="outline" disabled={cancelling} />}>
               Keep orders