@nxgt/material 3.10.2 → 3.12.0

package/dist/{use-material-translation-DkxcLbLM.js → use-material-translation-B3V_bz-5.js}

@@ -1,5 +1,5 @@
 import { r as e } from "./i18n-provider-C6HhBw34.js";
-import { t } from "./translate-material-CGZljjp1.js";
+import { t } from "./translate-material-Bd_KgfB8.js";
 import { useCallback as n } from "react";
 //#region lib/i18n/use-material-translation.ts
 function r() {

package/dist/{utils-Bcd2Z3ea.js → utils-BLfntITJ.js}

@@ -1733,7 +1733,20 @@ var n = (e, t) => {
 }, Pe = (e, t, n) => {
 	let r = t[n];
 	r !== void 0 && (e[n] = e[n] ? e[n].concat(r) : r);
-}, Fe = ((e, ...t) => typeof e == "function" ? k(Ae, e, ...t) : k(() => je(Ae(), e), ...t))({ extend: { theme: { radius: ["field", "field-inner"] } } });
+}, Fe = ((e, ...t) => typeof e == "function" ? k(Ae, e, ...t) : k(() => je(Ae(), e), ...t))({ extend: { theme: {
+	radius: ["field", "field-inner"],
+	text: [
+		"display",
+		"headline",
+		"title",
+		"body",
+		"label"
+	].flatMap((e) => [
+		"lg",
+		"md",
+		"sm"
+	].flatMap((t) => [`${e}-${t}`, `${e}-${t}-em`]))
+} } });
 function Ie(...e) {
 	return Fe(t(e));
 }

package/docs/components/buttons-and-actions.md

@@ -6,9 +6,9 @@ and language switches. Everything is imported from `@nxgt/material/components`.
 
 | | Component | What it does |
 | --- | --- | --- |
-| <img src="../previews/buttons-actions-button.webp" width="96" alt=""> | [Button](#button) | Five variants in seven colours and eight sizes, with a loading state |
-| <img src="../previews/buttons-actions-iconbutton.webp" width="96" alt=""> | [IconButton](#iconbutton) | Icon-only button with an optional tooltip |
-| <img src="../previews/buttons-actions-buttongroup.webp" width="96" alt=""> | [ButtonGroup](#buttongroup) | Joins adjacent buttons into one control |
+| <img src="../previews/buttons-actions-button.webp" width="96" alt=""> | [Button](#button) | Five variants in seven colours, six sizes, a round or square shape and a selected state, with a loading state |
+| <img src="../previews/buttons-actions-iconbutton.webp" width="96" alt=""> | [IconButton](#iconbutton) | Icon-only button in five sizes and three widths, with an optional tooltip |
+| <img src="../previews/buttons-actions-buttongroup.webp" width="96" alt=""> | [ButtonGroup](#buttongroup) | Joins adjacent buttons into one control; the expressive look widens the pressed one |
 | <img src="../previews/buttons-actions-splitbutton.webp" width="96" alt=""> | [SplitButton](#splitbutton) | Main action plus a menu of related ones, Material 3 Expressive |
 | <img src="../previews/buttons-actions-fab.webp" width="96" alt=""> | [Fab](#fab) | The screen's main action, floating; extended with its label, folds on scroll |
 | <img src="../previews/buttons-actions-fabmenu.webp" width="96" alt=""> | [FabMenu](#fabmenu) | A FAB that opens a few related actions as pills |
@@ -28,7 +28,7 @@ and language switches. Everything is imported from `@nxgt/material/components`.
 
 ![Button](../previews/buttons-actions-button.webp)
 
-Filled, tonal, outlined, ghost or link button in seven colours, four sizes and four square icon sizes, with a loading state.
+Filled, tonal, outlined, ghost or link button in seven colours, six sizes (24 to 96 px) and four square icon sizes, round or square, with a selected state and a loading state.
 
 ```tsx
 import { Button } from '@nxgt/material/components';
@@ -43,6 +43,7 @@ import { Mail } from 'lucide-react';
 	</Button>
 	<Button loading>Saving</Button>
 	<Button size="sm">Small</Button>
+	<Button size="xl" shape="square">Big and square</Button>
 	<Button size="icon" aria-label="Email">
 		<Mail />
 	</Button>
@@ -52,8 +53,10 @@ import { Mail } from 'lucide-react';
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `variant` | `'filled' \| 'tonal' \| 'outlined' \| 'ghost' \| 'link'` | `'filled'` | the style |
-| `color` | `'primary' \| 'secondary' \| 'success' \| 'info' \| 'warning' \| 'error' \| 'default'` | `'primary'` | the colour; `default` is the foreground colour. A `ghost` button in `secondary`, `success`, `info`, `warning` or `error` takes that colour's text and a tint of it on hover, at 4.5:1 on the page and on a card in both themes; in `primary` or `default` it keeps the foreground text |
-| `size` | `'xs' \| 'sm' \| 'default' \| 'lg' \| 'icon-xs' \| 'icon-sm' \| 'icon' \| 'icon-lg'` | — | height: 24, 32, 36 and 40 px; the `icon*` sizes are square, for a button holding only an icon (give it an `aria-label`). Unset, the button keeps its content's height, as before sizes existed |
+| `color` | `'primary' \| 'secondary' \| 'success' \| 'info' \| 'warning' \| 'error' \| 'default'` | `'primary'` | the colour; `default` is the foreground colour. A `ghost` button in `secondary`, `success`, `info`, `warning` or `error` takes that colour's text and a tint of it on hover, at 4.5:1 on the page and on a card in both themes; without a `color` (or with `default`) it keeps the foreground text, neutral; `color="primary"` set on a ghost button is tinted and takes the primary text |
+| `size` | `'xs' \| 'sm' \| 'default' \| 'lg' \| 'xl' \| '2xl' \| 'icon-xs' \| 'icon-sm' \| 'icon' \| 'icon-lg'` | — | height: 24, 32, 36, 40, 56 and 96 px, with a label from the type scale (`label-md` to `headline-lg`, heavier as the size grows) and an icon that follows (14, 16, 18, 20, 28 and 44 px); the `icon*` sizes are square, for a button holding only an icon (give it an `aria-label`). Unset, the button keeps its content's height and its 16 px padding, as before sizes existed |
+| `shape` | `'round' \| 'square'` | `'round'` | `round` is a pill (radius half the height); `square` has a corner of 6 px at `xs` to 28 px at `2xl`. A press springs to the other shape and scales to .97 (.985 at `2xl`); reduced motion keeps the colour change only |
+| `selected` | `boolean` | — | makes it a toggle: `aria-pressed` and `data-selected`, the other shape and a solid fill of its `color` (a `ghost` toggle without a `color` is a neutral tint of the text colour). Unset: a plain button. Ignored with `asChild` (a warning in development): set `aria-pressed` on the child |
 | `loading` | `boolean` | — | busy: a spinner, `aria-busy="true"` and `aria-disabled="true"`, and every click cancelled — a submit button submits neither on a click nor on Enter in a field. It stays focusable (no native `disabled`), so focus is not lost |
 | `lockOnClick` | `boolean` | — | a click makes the button busy at once, until `loading` has turned true and back (or for one second when it never does): for a `loading` that turns true only after an `await` |
 | `spinnerVariant` | `SpinnerProps['variant']` | `'2'` | which spinner `loading` shows |
@@ -62,7 +65,19 @@ import { Mail } from 'lucide-react';
 | `asChild` | `boolean` | `false` | styles its only child instead of rendering a `<button>` |
 | `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | not `submit` by default — pass it inside a form |
 
-The classes are exported as `buttonVariants` for styling your own element.
+The classes are exported as `buttonVariants` for styling your own element (Pagination, AlertDialog and the calendar's date picker use them).
+
+**The look.** The label is set in the type scale and is heavier than before (weights 560 at `xs` to 700 at `2xl`). The focus is a 2 px outline in the button's colour, 2 px off the button (the error colour with `aria-invalid`). A disabled button has neutral text (40 % of the text colour) and a neutral 12 % fill, none on `ghost` and `link`. `outlined` is a 1.5 px line inside the box at 55 % of the colour, and keeps a `ButtonText` outline in forced colours, where the inset shadow is removed. A `ghost` button is neutral without a `color`, and takes the tone of one it is given. On a coarse pointer every size has a 44 px hit area.
+
+```tsx
+const [on, setOn] = useState(false);
+
+<Button selected={on} onClick={() => setOn(!on)}>
+	<Star />
+	Favourite
+</Button>;
+<Button size="2xl" shape="square" variant="tonal">Start</Button>;
+```
 
 **On a phone.** A button is never wider than its container, and keeps its
 content's width in a column: a label too
@@ -71,7 +86,7 @@ accessible name — and a `title` you give it — keep the whole text. Give a
 label that must be read in full `wrap`, or a width of your own (`w-full`).
 The text is put in a `<span data-slot="button-label">` (one per run of
 text) that shrinks and ends in the ellipsis; it needs the text to be the button's own child; with `asChild`,
-put the label in a `<span>` inside the child element.
+put the label in a `<span>` inside the child element. On a touch screen in Safari (no `overflow-clip-margin`) an `asChild` host does not clip, to keep its 44 px hit area, so it has no ellipsis at all: a label that needs one goes in a `<span>` with `truncate`.
 
 ```tsx
 <Button title="Continue to the payment details">Continue to the payment details</Button>;
@@ -110,7 +125,7 @@ A test finds a busy button by its state, not by `disabled`:
 `expect(button).toHaveAttribute('aria-busy', 'true')` (`toBeDisabled()` is
 false: it is still focusable).
 
-**Storybook:** `Buttons & actions/Button` (`Submits Once`, `Lock On Click`), `Buttons & actions/Button/Phone` · **Vue:** `Button`
+**Storybook:** `Buttons & actions/Button` (`Submits Once`, `Lock On Click`), `Buttons & actions/Button/Expressive` (`SizesLadder`, `Shape`, `Selected`), `Buttons & actions/Button/Press and motion` (`PressMorph`, `ReducedMotion`), `Buttons & actions/Button/States` (`FocusOutline`, `Disabled`, `GhostSelectedNeutral`, `SelectedForcedColours`, `OutlinedForcedColours`, `PhoneBigSizes`), `Buttons & actions/Button/Phone`, `Guides/Buttons expressive` · **Vue:** `Button` (no `xl`, `2xl`, `shape` or `selected`)
 
 ---
 
@@ -136,14 +151,16 @@ import { Pencil, Trash2 } from 'lucide-react';
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `variant` | `'filled' \| 'tonal' \| 'outlined' \| 'ghost' \| 'link'` | `'filled'` | the style; a round 36 px button |
+| `variant` | `'filled' \| 'tonal' \| 'outlined' \| 'ghost' \| 'link'` | `'filled'` | the style; a round button |
 | `color` | as `Button` | `'primary'` | the colour; a `ghost` one in a colour other than `primary` or `default` draws its icon in it, as `Button` does |
+| `size` | `'xs' \| 'sm' \| 'default' \| 'lg' \| 'xl'` | — | 24, 32, 36, 40 or 56 px, icons of 14, 16, 18, 20 or 28 px (for a glyph without its own `size-*` class; an `Icon` is 16 px unless sized). Unset: the 36 px button with a 16 px icon it always was, so an explicit `default` has an 18 px icon |
+| `width` | `'narrow' \| 'default' \| 'wide'` | `'default'` | 0.78, 1 or 1.45 times the height, always a pill. Ignored with `shape` (a warning in development) |
 | `tooltip` | `ReactNode` | — | wraps it in a `Tooltip`; a string tooltip also becomes the `aria-label` |
 | `aria-label` | `string` | the tooltip, if a string | give one when there is no string tooltip |
 | `shape` | `ShapeName` | — | draws the button as one of the expressive shapes (`cookie-9`, `sunny`, `squircle`…) instead of a circle; changing it morphs. Unset: the round button, unchanged |
 | `morph` | `'round' \| 'pill' \| 'none'` | `'pill'` | what a **toggle** (`aria-pressed` set) does when pressed: `pill` fills with its colour and widens by 14 px into a pill, `round` fills and stays a circle, `none` keeps the look your classes give it. Not set on a button without `aria-pressed`, one with a `shape`, or a Toolbar item (the Toolbar's own look) |
 
-**A toggle button** takes the Toolbar morph's motion (`--nxgt-spring-fast`) and tokens: the fill is the button's `color` (`primary` by default), a pointer down squeezes the corners, the focus ring follows the pill. Its neighbours move by the 14 px, any size class works (`size-8`, `size-14`). Below 600 px wide only the colour changes, so a phone row never reflows; `prefers-reduced-motion` keeps the colour change only; in forced colours the pressed fill is `SelectedItem`. The pressed fill and corners are the button's own (a `bg-*` or `rounded-*` class on a pressed toggle does not apply); a ghost toggle without a `color` fills with `primary`. The morph works with a `tooltip` too (the styles match `data-icon-button`, which the tooltip trigger does not replace). The date picker's input-mode switch uses `morph="round"`; `PasswordField`'s eye, which sits inside its field, and `RichChatComposer`'s format toggle, which draws its own pressed look, use `morph="none"`; the mini player's move button and the Gallery viewer's repeat are pills too, white with a black icon on their dark chrome. `CodeEditor`'s word-wrap pill takes the editor theme's tint.
+**A toggle button** fills with the button's `color` (`primary` by default) through `data-selected` and the fill `Button` shares, and a pointer down squeezes the corners; `pill` widens the button itself by 14 px (its neighbours move by the 14 px), at any `size` (give the button a `size`, not a `size-*` class: the pressed width follows the `size`, see [troubleshooting](../troubleshooting.md#a-pill-iconbutton-toggle-is-the-wrong-width-with-a-size--class)). Below 600 px wide only the colour changes, so a phone row never reflows; `prefers-reduced-motion` keeps the colour change only; in forced colours the pressed fill is `SelectedItem`. The pressed fill and corners are the button's own (a `bg-*` or `rounded-*` class on a pressed toggle does not apply); a ghost toggle without a `color` is neutral when selected (a tint of the text colour), and primary only with a `color`. The focus is a 2 px outline 2 px off the button, a disabled button has a neutral 12 % fill (none on `ghost` and `link`), and on a coarse pointer every size has a 44 px hit area. The morph works with a `tooltip` too (the styles match `data-icon-button`, which the tooltip trigger does not replace). The date picker's input-mode switch uses `morph="round"`; `PasswordField`'s eye, which sits inside its field, and `RichChatComposer`'s format toggle, which draws its own pressed look, use `morph="none"`; the mini player's move button and the Gallery viewer's repeat are pills too, white with a black icon on their dark chrome. `CodeEditor`'s word-wrap pill takes the editor theme's tint.
 
 ```tsx
 import { IconButton } from '@nxgt/material/components';
@@ -214,7 +231,9 @@ built this way. A `Contacts` badge is `role="img"`, named by the contact type.
 
 The classes are exported as `iconButtonVariants`.
 
-**Storybook:** `Buttons & actions/IconButton` (`Shapes`, `ShapeToggle`), `Buttons & actions/IconButton/Morph` (`Frozen`, `WidensOrStaysRound`, `Contrast`, `Unaffected`, `WithTooltip`), `Buttons & actions/IconButton/Shapes` (`InsideAGroup`) · **Vue:** `IconButton` (no `shape`)
+**Forced colours.** An `outlined` button keeps a `ButtonText` outline and a pressed toggle, `Button` or `IconButton`, fills with `SelectedItem` (its text and icon in `SelectedItemText`); the focus outline follows the system colours.
+
+**Storybook:** `Buttons & actions/IconButton` (`Shapes`, `ShapeToggle`), `Buttons & actions/IconButton/Sizes and widths` (`SizesLadder`, `Widths`, `Colours`), `Buttons & actions/IconButton/States` (`FocusOutline`, `Disabled`, `GhostToggleNeutral`, `SelectedForcedColours`), `Buttons & actions/IconButton/Toggle and motion` (`SizedToggle`, `ReducedMotion`, `PressMorph`), `Buttons & actions/IconButton/Morph` (`Frozen`, `WidensOrStaysRound`, `Contrast`), `Buttons & actions/IconButton/Morph unaffected` (`Unaffected`, `WithTooltip`), `Buttons & actions/IconButton/Shapes` (`InsideAGroup`) · **Vue:** `IconButton` (no `shape`)
 
 ---
 
@@ -222,7 +241,7 @@ The classes are exported as `iconButtonVariants`.
 
 ![ButtonGroup](../previews/buttons-actions-buttongroup.webp)
 
-Joins adjacent buttons into one control.
+Joins adjacent buttons into one control; `look="standard"` is the Material 3 Expressive action group.
 
 ```tsx
 import { Button, ButtonGroup } from '@nxgt/material/components';
@@ -236,12 +255,42 @@ import { Button, ButtonGroup } from '@nxgt/material/components';
 </ButtonGroup>;
 ```
 
-A `<div>` taking its props. It stretches to its container (`w-full`); mark the
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `look` | `'standard'` | — | the Material 3 Expressive group (see below). Unset: the original group, which becomes the `standard` one by default in the next major, with `look="legacy"` to keep it |
+| `size` | `'xs' \| 'sm' \| 'default' \| 'lg' \| 'xl'` | — | the `size` every `Button` and `IconButton` in the group takes through a context; a child's own `size` wins. Works with either look |
+| `...div` | `ComponentProps<'div'>` | — | the host's props; `data-slot="button-group"`, `data-look` and `data-size` are set on it |
+
+A `<div>` taking its props. Without `look` it stretches to its container (`w-full`); mark the
 current button with `data-state="active"`: it fills with the primary colour and
 its label and icons switch to the primary foreground, so every button can stay
 `tonal` and only the attribute moves.
 
-**Storybook:** `Buttons & actions/ButtonGroup` · **Vue:** `ButtonGroup`
+`look="standard"` is the Material 3 Expressive group: the buttons keep their own
+look, 8px apart, and a pressed one widens by 14px on each side while its
+neighbours give the width back, so the group's width never changes (7, 10 and
+11px at `xs`, `sm` and `default`, which have less padding to give; none with
+reduced motion; an icon-only neighbour at the end of the group keeps its icon and may give back less). `size` is shared by every `Button` and `IconButton` in the group
+(a child's own `size` wins) and works with either look. It sets
+`data-look` and `data-size` on the host; mark the group with `role="group"` and a
+name when it is one control.
+
+```tsx
+<ButtonGroup look="standard" size="lg" role="group" aria-label="Actions">
+	<Button variant="tonal">Save</Button>
+	<Button variant="tonal">Share</Button>
+	<IconButton variant="tonal" aria-label="More">
+		<MoreHorizontal />
+	</IconButton>
+</ButtonGroup>
+```
+
+On a coarse pointer the standard group's gap is `max(8px, 44px - the height of its size)`
+(20px at `xs`, 12px at `sm`, 8px from `default`), so every button, in a row or
+across wrapped rows, keeps a 44px hit area that touches no neighbour's. A child with its own smaller `size` in a standard group keeps the group's gap, so its coarse 44px hit area can overlap a neighbour's: give the group the smallest `size` instead. Without
+`look` the group is unchanged.
+
+**Storybook:** `Buttons & actions/ButtonGroup`, `Buttons & actions/ButtonGroup/Standard`, `Buttons & actions/ButtonGroup/Standard toggles`, `Buttons & actions/ButtonGroup/Standard phone and motion`, `Guides/Buttons expressive` · **Vue:** `ButtonGroup` (no `look` or `size`)
 
 ---
 

package/docs/components/data-display.md

@@ -9,7 +9,7 @@ from `@nxgt/material/components`.
 | <img src="../previews/data-display-avatar.webp" width="96" alt=""> | [Avatar](#avatar) | Image with a fallback and an optional online / offline dot |
 | <img src="../previews/data-display-avatargroup.webp" width="96" alt=""> | [AvatarGroup](#avatargroup) | Overlapping avatars with a `+N` overflow |
 | <img src="../previews/data-display-shape.webp" width="96" alt=""> | [Shape](#shape) | Material 3 Expressive's shapes as a backdrop, an icon container or a mask for a photo |
-| <img src="../previews/data-display-badge.webp" width="96" alt=""> | [Badge](#badge) | Pill label in seven tones |
+| <img src="../previews/data-display-badge.webp" width="96" alt=""> | [Badge](#badge) | Status pill, 20 px, in seven tones, soft or outlined |
 | <img src="../previews/data-display-countbadge.webp" width="96" alt=""> | [CountBadge](#countbadge) | Count in the corner of its children |
 | <img src="../previews/data-display-dayseparator.webp" width="96" alt=""> | [DaySeparator](#dayseparator) | "Today", "Yesterday" or the date between two hairlines |
 | <img src="../previews/data-display-periodcards.webp" width="96" alt=""> | [PeriodCards](#periodcards) | Consecutive date ranges (terms, sprints) as cards, with a current marker and an optional link per card |
@@ -210,20 +210,25 @@ and no lazy loading: give `src` the size you need.
 
 ![Badge](../previews/data-display-badge.webp)
 
-Pill label: default, secondary, error, success, info, warning, outlined.
+Status badge: a 20 px pill with the `label-sm` text, compact padding and no hover or pointer affordance. Use `soft` (a tonal fill from the tone tokens) for a state; `outlined` is a thin 1 px line at 40 % of the tone. Every tone stays at 4.5:1 or more in the light and dark themes and follows the theme presets.
 
 ```tsx
 import { Badge } from '@nxgt/material/components';
 
-<Badge variant="success">Paid</Badge>
+<Badge variant="soft" tone="success">Paid</Badge>
+<Badge variant="outlined" tone="error">Late</Badge>
+<Badge variant="success">New</Badge>
 ```
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `variant` | `'default' \| 'secondary' \| 'error' \| 'success' \| 'info' \| 'warning' \| 'outlined'` | `'default'` | tone |
+| `variant` | `'default' \| 'secondary' \| 'error' \| 'success' \| 'info' \| 'warning' \| 'soft' \| 'outlined'` | `'default'` | the filled tones, `soft` (recommended for a state) or `outlined` |
+| `tone` | the eight named tones, or a tone of your own declared in `AppTones` | `'neutral'` | the colour of a `soft` or `outlined` badge; ignored by the filled variants |
 | `asChild` | `boolean` | `false` | renders its child (a link) with the badge styles |
 
-**Storybook:** `Data display/Badge` · **Vue:** `Badge`
+A `Badge` link (`asChild`) no longer fades on hover: a badge is a status, not a button. Put a `Chip` or a `Button` where the user acts.
+
+**Storybook:** `Data display/Badge` (Soft, SoftContrast) · **Vue:** `Badge` (without `soft` and `tone` yet)
 
 ---
 
@@ -428,12 +433,22 @@ import { StatCard } from '@nxgt/material/components';
 | `tone` | the eight named tones, or a tone of your own declared in `AppTones` | — | the value is drawn in the tone's text colour and the icon sits on a chip of its container. Without one the card is as before |
 | `variant` | `'outlined' \| 'tonal' \| 'filled'` | `'outlined'` | `tonal` paints the card with the tone's container and a fine outline in its text colour (3:1 against the page); `filled` paints it with the tone and draws everything on it in the on-colour. Both use `neutral` when there is no `tone`. Every text is 4.5:1 or more. In a [calm zone](../guides/theming.md#calm-zone), a `tonal` or `filled` card is the card's own surface with the tone's ring, and its icon chip a ring |
 | `valueSize` | `'default' \| 'display'` | `'default'` | `display` draws the value larger (`headline-large`) |
+| `size` | `'default' \| 'sm'` | `'default'` | `sm` is a compact tile for a band or a header (see below); it ignores `hint`, `delta` and `valueSize` |
 
 ```tsx
 <StatCard tone="success" variant="tonal" valueSize="display" label="Revenue" value="€48,200" delta={12.4} icon={<CreditCard />} />
 ```
 
-Parts: the root carries `data-slot="stat-card"`, `data-variant` and, when a tone applies, `data-tone` (the tone, or `neutral` on a `tonal` or `filled` card without one); the icon wrapper carries `data-slot="stat-card-icon"`. The types `StatCardProps`, `StatCardVariant` and `StatCardValueSize` are exported.
+**Compact tile (`size="sm"`).** For figures in a header band: a tile 40 to 56 px tall that hugs its content, the optional icon chip, then the value (tabular figures) over its label. It takes the same `tone` and `variant` (`tonal`, `outlined`, `filled`); `hint`, `delta` and `valueSize` are ignored (nothing is drawn for them, and `loading` shows a skeleton in place of the value only). Tiles in a `flex flex-wrap gap-2` row sit side by side and wrap on a phone.
+
+```tsx
+<div className="flex flex-wrap gap-2">
+  <StatCard size="sm" variant="tonal" tone="primary" label="Students" value={22} />
+  <StatCard size="sm" variant="tonal" tone="tertiary" label="Classes" value={6} />
+</div>
+```
+
+Parts: the root carries `data-slot="stat-card"`, `data-variant` and, when a tone applies, `data-tone` (the tone, or `neutral` on a `tonal` or `filled` card without one); the icon wrapper carries `data-slot="stat-card-icon"`. The compact tile adds `data-size="sm"`. The types `StatCardProps`, `StatCardVariant`, `StatCardValueSize` and `StatCardSize` are exported.
 
 In `filled`, the delta and its trend arrow take the on-colour too (the arrow and the sign still say up or down). The outline's share is `--stat-card-ring-share` (`68%`, or `--nxgt-tone-ring-share` for every ring); it draws the tonal card's border, the filled card's edge in a calm zone and the hairline round the icon chip. Known limit: the dark theme's primary `filled` card has an edge of about 2.3:1 on a `Card` and 2.5:1 on the page (its text is 7:1); a `tonal` card avoids it. See [App tones](../guides/theming.md#app-tones-on-shape-fab-avatar-statcard-and-the-metric-cards).
 
@@ -618,10 +633,24 @@ import { Badge, EntityHeader } from '@nxgt/material/components';
 | `title` | `ReactNode` | — | the `h1`; optional: without it no heading is rendered (see below) |
 | `icon`, `status` | `ReactNode` | — | before and after the title; `icon` is decoration, shown in an `aria-hidden` badge, so put nothing meaningful or focusable there |
 | `metadata` | `{ label: string; value: ReactNode }[]` | `[]` | facts under the title, a description list: a muted label beside its value, no colon; a link in a value is drawn in the primary text colour (`text-primary-text`), not the prose link's info blue, and `nxgt-plain-link` still opts out |
+| `stats` | `EntityStat[]` | `[]` | figures (counts, a mean) as compact `size="sm"` [StatCard](#statcard) tiles in a wrapping row under the metadata; a `tone` paints a tile, `0` is a figure, an empty value drops the tile (see Stats below) |
 | `actions` | `ResponsiveButtonProps[] \| ReactNode` | `[]` | an array becomes responsive buttons (icon-only on phones) |
 
 The root carries `data-slot="entity-header"`; the metadata is a `dl` with `data-slot="entity-metadata"` (a muted `dt` label beside its `dd` value, no colon), and the actions sit in `data-slot="entity-header-actions"` (absent when there are none). Inside an EntityHeader that replaces the old `summary-data` slot and its `Label:` text, so update a selector or a test that read "Label: value".
 
+**Stats.** Figures (counts, a mean) go in `stats`, shown as compact [StatCard](#statcard) tiles (`size="sm"`) in a wrapping row under the metadata; facts (dates, names) stay in `metadata`. A `tone` paints a tile (tonal), none leaves it outlined; `0` is a figure, an empty value drops the tile. The row is `data-slot="entity-stats"`, and the type `EntityStat` is exported.
+
+```tsx
+<EntityHeader
+  title="Class 6A"
+  metadata={[{ label: 'Year', value: '2026-2027' }]}
+  stats={[
+    { label: 'Students', value: 24, tone: 'primary' },
+    { label: 'Coefficient', value: 2 },
+  ]}
+/>
+```
+
 `title` is optional. A record page whose `h1` is the app bar's title (`handle.title`, `AppShellHandle.title`, see the [app shell guide](../guides/app-shell.md#the-pages-title-in-the-app-bar)) uses EntityHeader without it, so the page keeps a single heading:
 
 ```tsx
@@ -653,15 +682,17 @@ With a title, in a narrow container (under `@sm`) the order is title, metadata,
 Row with leading / trailing slots, title and subtitle; becomes a link or button when interactive. `size="sm"` is the dense row.
 
 ```tsx
-import { ChevronRight } from 'lucide-react';
 import { ListTile } from '@nxgt/material/components';
 
-<ListTile title="Notifications" subtitle="Email and push" trailing={<ChevronRight />} href="/settings/notifications" />
+<ListTile title="Notifications" subtitle="Email and push" href="/settings/notifications" />
 ```
 
+A tile with an `href` ends with a discreet chevron after `trailing`: decorative (`aria-hidden`, so the link's name stays its text) and flipped in right-to-left. `chevron={false}` opts out; `chevron` on a button tile (an `onClick` that navigates) opts in.
+
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `href` | `string` | — | renders an `<a>` |
+| `href` | `string` | — | renders an `<a>`, with a chevron by default |
+| `chevron` | `boolean` | `true` with an `href`, else `false` | the decorative chevron after `trailing` |
 | `linkComponent` | `AppShellLinkComponent` | plain `<a>` | the link element, as in the app shell: takes `href`, spreads every other prop, forwards `ref` |
 | `onClick` | `MouseEventHandler` | — | renders a `<button>` |
 | `selected` | `boolean` | `false` | highlighted row |

package/docs/components/feedback-and-status.md

@@ -7,7 +7,7 @@ centre.
 | | Component | What it does |
 | --- | --- | --- |
 | <img src="../previews/feedback-status-alert.webp" width="96" alt=""> | [Alert](#alert) | Callout with icon, title and description in seven tones |
-| <img src="../previews/feedback-status-banner.webp" width="96" alt=""> | [Banner](#banner) | Dismissible banner with an action |
+| <img src="../previews/feedback-status-banner.webp" width="96" alt=""> | [Banner](#banner) | Dismissible banner with an action, in the look of Alert |
 | <img src="../previews/feedback-status-alertdialog.webp" width="96" alt=""> | [AlertDialog](#alertdialog) | Parts for a blocking confirmation dialog |
 | <img src="../previews/feedback-status-confirmdialog.webp" width="96" alt=""> | [ConfirmDialog](#confirmdialog) | Confirm / cancel dialog, `ConfirmationDialog`, `CustomAlertDialog` |
 | <img src="../previews/feedback-status-customdialog.webp" width="96" alt=""> | [CustomDialog](#customdialog) | Ready-made dialog with trigger, icon, title, body and footer |
@@ -63,6 +63,13 @@ The root carries `data-slot="alert"`, the title `data-slot="alert-title"` and th
 
 Dismissible info / success / warning / error banner with an action.
 
+A Banner looks like an [Alert](#alert): the same light tone surface, start
+accent bar, tone-coloured icon, title and description typography and padding.
+They are built on one shared variants module, so they cannot drift. What a
+Banner adds is its role: page level (full width), an `action` and a dismiss
+button. Before 3.12 it was a solid tinted fill with a full tone border and
+rounded corners.
+
 ```tsx
 import { Banner, Button } from '@nxgt/material/components';
 
@@ -754,6 +761,10 @@ longer than the toast (a URL) breaks at its edge instead of pushing the
 action out. With a long message and an action, the action and the X go under
 the text; the icon stays 40px and never squeezes the text.
 
+In a collapsed stack only the front toast's action and X are reachable; the
+ones behind it appear when the stack opens on hover or when focus is inside
+the toaster.
+
 The toast id defaults to the title, so two toasts with the same title
 replace each other; pass `options: { id }` to show both. `Toaster` wraps
 Sonner's and takes its props (`position`, `expand`, `richColors`…), all

package/docs/components/navigation-and-layout.md

@@ -7,7 +7,7 @@ documentation-site shell. Everything is imported from
 
 | | Component | What it does |
 | --- | --- | --- |
-| <img src="../previews/navigation-layout-appshell.webp" width="96" alt=""> | [ActivityLayout](#activitylayout) | App shell: sidebar, header, breadcrumbs, titled page; a route's `handle.title` is the page's `h1` in the app bar (it labels `main`; `usePageTitleFocus()` focuses it after a navigation), `breadcrumbRoot` a text root crumb, `context` the tenant line atop the phone's menu sheet; `menuOpen` / `onMenuOpenChange` control the phone's menu sheet, which closes itself on a followed link or any location change |
+| <img src="../previews/navigation-layout-appshell.webp" width="96" alt=""> | [ActivityLayout](#activitylayout) | App shell: sidebar, header, breadcrumbs, titled page; a route's `handle.title` is the page's `h1` in the app bar (it labels `main`; `usePageTitleFocus()` focuses it after a navigation), `breadcrumbRoot` a text root crumb, `breadcrumb={false}` no trail, `context` the tenant line atop the phone's menu sheet; `menuOpen` / `onMenuOpenChange` control the phone's menu sheet, which closes itself on a followed link or any location change |
 | <img src="../previews/navigation-layout-accountmenu.webp" width="96" alt=""> | [AccountMenu](#accountmenu) | The app bar's avatar menu: the account, the app's links, Sign out |
 | <img src="../previews/navigation-layout-authcard.webp" width="96" alt=""> | [AuthCard](#authcard) | Signed-out page frame: one `main`, a centred card, its title the `h1` |
 | <img src="../previews/navigation-layout-sidebar.webp" width="96" alt=""> | [Sidebar](#sidebar) | Collapsible navigation sidebar |
@@ -64,7 +64,7 @@ phone's menu sheet pad clear of `env(safe-area-inset-*)`, as classes; see the
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `items` | `MenuItem[]` | — | `label` (already translated), `url`, `icon`, `footer`, `badge` (`true` a dot, a number a count up to "99+"), `badgeLabel` (see [Badges](../guides/app-shell.md#badges)) |
+| `items` | `MenuItem[]` | — | `label` (already translated), `url`, `icon`, `footer`, `display` (`'icon'`: a round icon-only button, the label as tooltip and name; see the [app shell guide](../guides/app-shell.md)), `badge` (`true` a dot, a number a count up to "99+"), `badgeLabel` (see [Badges](../guides/app-shell.md#badges)) |
 | `linkComponent` | `AppShellLinkComponent` | React Router `Link` | The link each menu entry renders, given `href`; see the [app shell guide](../guides/app-shell.md) |
 | `logo`, `name` | `AppLogo` (`ReactNode \| string \| AppLogoImage`, `AppLogoImage` = `{ src, alt? }`), `string` | — | the app's logo alone in the collapsed rail, named by `name` (also its tooltip); logo and name side by side in the phone's menu sheet |
 | `context` | `ReactNode` | — | a line at the top of the phone's menu sheet, above the brand: the current tenant's name; `name` stays the app's brand; `AppHeader` and `AppSidebar` take it too (see the [app shell guide](../guides/app-shell.md#the-brand-logo-and-name)) |
@@ -72,6 +72,7 @@ phone's menu sheet pad clear of `env(safe-area-inset-*)`, as classes; see the
 | `avatar` | `ReactNode` | — | an image URL or a node, in the header |
 | `headerTitle` | `ReactNode` | — | the header's leading title (the context: an organisation's name), after the phone's menu button, truncated when long; when it is cut off, its full text is the `title` tooltip (#629) |
 | `handle.title` | `ReactNode \| (match: UIMatch) => ReactNode` | — | on a route: the page's title in the app bar, its one `h1`, in the first server HTML; `ActivityContent` leaves its own title out while it is set (see the [app shell guide](../guides/app-shell.md#the-pages-title-in-the-app-bar)) |
+| `breadcrumb` | `boolean` | `true` | `false` hides the breadcrumb trail (an error page); it is also hidden when every matched `handle.breadcrumb` renders `null`; see the [app shell guide](../guides/app-shell.md#breadcrumbs) |
 | `breadcrumbRoot` | `{ label: ReactNode; to: string }` | — | the breadcrumb's first crumb, a text link in place of the home icon (`AppBreadcrumb`'s `root`); see the [app shell guide](../guides/app-shell.md#breadcrumbs) |
 | `headerActions` | `ReactNode` | — | header, before the avatar |
 | `title`, `subtitle`, `actions` | `ReactNode` | — | `ActivityContent`'s header card; `title` is left out while a route's `handle.title` puts the page's title in the app bar |
@@ -295,7 +296,7 @@ import { BottomAppBar, IconButton, TopAppBar, Typography } from '@nxgt/material/
 
 <TopAppBar>
   <IconButton variant="ghost" aria-label="Open menu"><Menu /></IconButton>
-  <Typography variant="title-medium" className="flex-1">Inbox</Typography>
+  <Typography variant="title-md" emphasized className="flex-1">Inbox</Typography>
   <IconButton variant="ghost" aria-label="Search"><Search /></IconButton>
 </TopAppBar>
 

package/docs/components/primitives.md

@@ -10,7 +10,7 @@ other pages are built from these.
 | <img src="../previews/primitives-accordion.webp" width="96" alt=""> | [Accordion](#accordion) | Collapsible sections with a rotating chevron and animated content |
 | <img src="../previews/primitives-collapsible.webp" width="96" alt=""> | [Collapsible](#collapsible) | A single show / hide region and its trigger |
 | <img src="../previews/primitives-card.webp" width="96" alt=""> | [Card](#card) | Card surface with header, action slot, content and footer |
-| <img src="../previews/primitives-typography.webp" width="96" alt=""> | [Typography](#typography) | Text in the Material type scale |
+| <img src="../previews/primitives-typography.webp" width="96" alt=""> | [Typography](#typography) | Text in the Material 3 type scale, with an emphasized weight |
 | <img src="../previews/primitives-anchorheading.webp" width="96" alt=""> | [AnchorHeading](#anchorheading) | Heading with a hover copy-link |
 | <img src="../previews/primitives-label.webp" width="96" alt=""> | [Label](#label) | Form label with an optional required asterisk |
 | <img src="../previews/primitives-helpertext.webp" width="96" alt=""> | [HelperText](#helpertext) | Hint or error message under a field |
@@ -171,36 +171,78 @@ with `as` (`<CardTitle as="h2">`), so `getByRole('heading', { name })` finds it.
 
 ![Typography](../previews/primitives-typography.webp)
 
-Text in the Material type scale (headline, title, body, caption…).
+Text in the Material 3 type scale: five roles, three sizes each, and an emphasized weight.
 
 ```tsx
 import { Typography } from '@nxgt/material/components';
 
 <>
-	<Typography variant="headline-small">Orders</Typography>
-	<Typography variant="body-medium">12 orders are waiting to ship.</Typography>
-	<Typography variant="caption">Updated a minute ago</Typography>
+	<Typography variant="headline-sm">Orders</Typography>
+	<Typography>12 orders are waiting to ship.</Typography>
+	<Typography variant="label-sm" tone="muted">Updated a minute ago</Typography>
+	<Typography variant="title-md" emphasized>Next delivery</Typography>
 </>;
 ```
 
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
-| `variant` | `'huge-large' \| 'huge-medium' \| 'huge-small' \| 'headline-larger' \| 'headline-large' \| 'headline-medium' \| 'headline-small' \| 'title-large' \| 'title-medium' \| 'title-small' \| 'body-medium' \| 'body-small' \| 'caption' \| 'normal'` | `'normal'` | size and weight; `caption` is also muted |
+| `variant` | `` `${'display' \| 'headline' \| 'title' \| 'body' \| 'label'}-${'lg' \| 'md' \| 'sm'}` `` | `'body-md'` | the step of the scale: size, line height, tracking and weight together. The fifteen former names still work, deprecated (see below) |
+| `emphasized` | `boolean` | `false` | the heavier weight of the same step (`text-<step>-em`); same size, line height and tracking. No effect on a deprecated alias that is emphasized already |
 | `tone` | `'default' \| 'muted' \| 'primary' \| 'error'` | `'default'` | text colour: `muted` is `text-muted-foreground`, `primary` is `text-primary-text` (primary lightened in dark), `error` is `text-error-text`; `default` inherits (a `className` colour still wins) |
 | `as` | an intrinsic tag name (`keyof JSX.IntrinsicElements`) | `'div'` | the element to render, keeping the variant, e.g. `as="h2"` or `as="span"` |
 | `asChild` | `boolean` | `false` | merge the classes onto the single child instead of rendering an element |
 
+**The scale.** Sizes are in px, then line height; the weight is 400 except `title-md`, `title-sm` and the three `label` steps (500).
+
+| Role | `lg` | `md` | `sm` |
+| --- | --- | --- | --- |
+| `display` | 57 / 64 | 45 / 52 | 36 / 44 |
+| `headline` | 32 / 40 | 28 / 36 | 24 / 32 |
+| `title` | 22 / 28 | 16 / 24 | 14 / 20 |
+| `body` | 16 / 24 | 14 / 20 | 12 / 16 |
+| `label` | 14 / 20 | 12 / 16 | 11 / 16 |
+
+`emphasized` weights: `display` 540, `headline` 560, `title-lg` 580, `title-md` and `title-sm` 680, `body` 520, `label` 700. A variable font such as Inter reads them on its `wght` axis; any other font rounds to the nearest weight it has.
+
+**The tokens.** The scale is Tailwind 4 tokens in `styles.css` (`--text-<role>-<size>` with `--line-height`, `--letter-spacing`, `--font-weight` and `--font-weight-em`), so `text-title-md` and `text-title-md-em` are utilities for your own markup, and an app or a zone retunes a step with CSS variables alone (no `defineTheme` key). The [theming guide](../guides/theming.md#type-scale) has the details.
+
+```tsx
+<Typography variant="title-md" emphasized className="[--text-title-md:1.5rem] [--text-title-md--line-height:2rem]">
+	Larger inside this element
+</Typography>
+```
+
 It renders a `<div>` unless `as` or `asChild` says otherwise. Use `as="span"` inside a `<button>` or a link, where a `<div>` is invalid HTML. It sets no `overflow`, so it is never a scroll region: text with break points wraps, while an unbreakable string can overflow its box (add `wrap-anywhere` or `min-w-0`; put your own wrapper with `overflow-auto` and `tabIndex={0}` around it to scroll):
 
 ```tsx
-<Typography as="span" variant="title-small">Inline</Typography>
-<Typography asChild variant="body-medium"><a href="/docs">Docs</a></Typography>
-<Typography tone="muted" variant="body-medium">Jan 3 to Jan 9</Typography>
+<Typography as="span" variant="title-sm" emphasized>Inline</Typography>
+<Typography asChild><a href="/docs">Docs</a></Typography>
+<Typography tone="muted">Jan 3 to Jan 9</Typography>
 ```
 
+**Deprecated names.** The fifteen former variants are aliases of the scale by name, removed in 4.0. Their **sizes changed** in 3.11 (the weights and line heights follow the scale too):
+
+| Former variant | Use | Size before → after |
+| --- | --- | --- |
+| `normal`, `body-medium` | `body-md` | 14 → 14 px (weight 400, which `Typography` now sets itself instead of inheriting its parent's) |
+| `body-small` | `body-sm` | 12 → 12 px |
+| `caption` | `label-sm` with `tone="muted"` | 10 → 11 px |
+| `title-small` | `title-sm` emphasized | 16 → 14 px |
+| `title-medium` | `title-md` emphasized | 18 → 16 px |
+| `title-large` | `title-lg` emphasized | 20 → 22 px |
+| `headline-small` | `headline-sm` emphasized | 24 → 24 px |
+| `headline-medium` | `headline-md` emphasized | 30 → 28 px |
+| `headline-large` | `headline-lg` emphasized | 36 → 32 px |
+| `headline-larger` | `display-sm` emphasized | 48 → 36 px |
+| `huge-small` | `display-sm` emphasized | 60 → 36 px |
+| `huge-medium` | `display-md` emphasized | 72 → 45 px |
+| `huge-large`, `huge-larger` | `display-lg` emphasized | 96 → 57 px |
+
+The bare `h1` to `h6` elements follow the scale too: `headline-md`, `headline-sm`, `title-lg`, `title-md`, `title-sm` and `label-md`, at weight 500.
+
 The variants are also exported as `typographyVariants` for use on your own elements.
 
-**Storybook:** `Primitives/Typography` · **Vue:** `Typography`
+**Storybook:** `Primitives/Typography` (`Scale`), `Primitives/Typography/Type scale` (`Emphasized`, `Aliases`, `ZoneOverride`) · **Vue:** `Typography` (no scale)
 
 ---
 

package/docs/guides/app-shell.md

@@ -82,6 +82,7 @@ type MenuItem = {
   url: string;
   icon: IconName;     // a symbol of the duotone sprite, see Getting started › Icons
   footer?: boolean;   // pin to the sidebar footer
+  display?: 'icon';   // a round, icon-only button; see below
   badge?: number | boolean | ReactNode; // see Badges
   badgeLabel?: string; // the badge's text in the link's name, already translated
 };
@@ -103,6 +104,22 @@ type MenuItem = {
 
 - **`footer: true` pins an entry to the footer.** Being last in the list does
   not: appending an entry never moves another one out of the footer.
+- **`display: 'icon'` draws the entry as a round, icon-only button.** Meant
+  for the footer's "Settings": in the collapsed rail, the expanded sidebar and
+  the phone's menu sheet alike, it is an `IconButton` (the Button family's
+  look, ghost, tonal when it is the active entry) with the label as its
+  tooltip and, visually hidden, its accessible name, `aria-current="page"`
+  when active, and a 44px target on a coarse pointer. The entries without it
+  keep their icon and label. An icon entry draws no `badge`.
+
+  ```tsx
+  { label: t('menu.settings'), url: '/settings', icon: 'gear', footer: true, display: 'icon' }
+  ```
+
+- The active entry's icon and label are in primary on the rail: a darker
+  primary in light (85 % of its lightness, so the label reads 4.5:1 on its
+  pill for every theme preset) and a lavender of its hue in dark; see
+  [the sidebar tokens](./theming.md).
 - The icons are drawn with `Icon type="duotone"`, so the duotone sprite must
   be served ([getting started](../getting-started.md#icons)).
 
@@ -183,6 +200,7 @@ partitionMenu(items);                              // { content, footer }
 | `avatar` | `ReactNode` | — | End of the header. A `string` is used as the image URL of an `Avatar`; anything else is rendered as-is |
 | `linkComponent` | `AppShellLinkComponent` | React Router `Link` | The link each menu entry renders, given `href` (see below) |
 | `headerTitle` | `ReactNode` | — | The header's leading title: the context the app is in (the active organisation's name), right after the phone's menu button, truncated when long; when it is cut off, its full text is the `title` tooltip (#629) |
+| `breadcrumb` | `boolean` | `true` | `false` hides the breadcrumb trail, for an error page whose matched routes would show a misleading one (see [Breadcrumbs](#breadcrumbs)) |
 | `breadcrumbRoot` | `AppBreadcrumbRoot` (`{ label: ReactNode; to: string }`) | — | The breadcrumb's first crumb, in place of the home icon: a text link to `to` (see [Breadcrumbs](#breadcrumbs)) |
 | `headerActions` | `ReactNode` | — | In the header, before the avatar: notifications, help, `ThemeToggle` |
 | `children` | `ReactNode` | — | The routed content, usually `<Outlet />` |
@@ -498,11 +516,23 @@ or an `NxgtTheme` zone around it; see [Themes](./theming.md#the-provider-and-zon
 | `backdrop={<Background … />}` | that node, for this screen |
 | `backdrop={false}` | no background and no blobs: a plain page (`data-plain` on the root) |
 
-The theme's shapes (the motif and illustrated presets) stay whole: a shape that
-would cross the layer's edge, or reach the app bar, the breadcrumb, the header
-card or an `EntityHeader`, is not drawn, and nothing shows until that first
-check has run. Full-width textures such as `waves` and the gradient are not
-shapes and are not filtered. A `Background` passed as `backdrop` is kept whole the same way; any other node is left as it is.
+**Where the shapes go.** The theme's shapes (the motif and illustrated presets)
+are drawn whole or not at all, and only in empty space. A shape that would cross the layer's edge,
+or reach the app bar, the breadcrumb, the header card or an `EntityHeader`, is
+not drawn (a permanent exclusion). A shape that lies over (or within 8px of) the page's text or
+controls (inputs, buttons, links, images, and every line of text) is hidden: it
+fades out in 150ms (none under `prefers-reduced-motion`) and fades back once
+the content moves away, for instance when the page scrolls or a list changes.
+Shapes are hidden, never moved. The check reads the content when it changes or
+resizes and keeps the boxes, so a scroll only shifts them (one `requestAnimationFrame`-throttled
+pass, well under a millisecond on a typical page; text past the first 6000 boxes is not collected, so a shape may be drawn over it). A moon, a planet or an eclipse counts as one shape: it is hidden whole, with its halo. Limits: a sticky element is measured where it is laid out, not where it sticks, and a late font or image, or an inner scroller, triggers a new check a moment later. Nothing shows until the first
+check has run, so no shape flashes over the content. On a phone, where the
+content fills the width, the shapes you see are the ones in the empty part of
+the page, usually below the content. Full-width textures such as `waves` and the
+gradient are not shapes and are not filtered. A `Background` passed as
+`backdrop` follows the same rule; any other node is left as it is. The layer is
+below the content in z-order (`-z-10` in the column's own stacking context), so
+a dialog, a sheet or a sticky header is always above it.
 
 `backdrop={false}` used to draw the built-in gradient, as if it were left out;
 it now removes it. To keep the gradient, leave `backdrop` out. A theme's
@@ -522,7 +552,7 @@ to know the theme on the server (a cookie, passed to `defaultTheme`).
 
 The shell draws the gradient with three blurred blobs behind its frame. To use
 one of the 50 presets of `@nxgt/material/backgrounds` instead, pass it as
-`backdrop`:
+`backdrop` (behind the shell its shapes show only in empty space, see [Where the shapes go](#the-themes-background)):
 
 ```tsx
 import { Outlet } from 'react-router';
@@ -559,7 +589,7 @@ export function Shell({ items }: { items: MenuItem[] }) {
   `scroll="container"` alike.
 - **The chrome is lightly translucent and frosted.** Under a `backdrop`, the
   app bar, the breadcrumb (a pill as wide as its crumbs) and the tabs strip
-  show a shape faintly through their fill, over a 6px blur that keeps it from
+  show the backdrop faintly through their fill, over a 6px blur that keeps it from
   competing with a text. The lists and tables (band and rows), the segmented
   `ToggleGroup`, the list bar, the phone tiles and the cards stay opaque, so no
   shape runs behind a row. The sidebar is frosted too (87%), but the layer is
@@ -797,7 +827,21 @@ to the router's root, then adds one crumb per matched route that has a
 the trail. The last crumb is text (`aria-current="page"`); the others are
 links, each inside its `<li>`. The home icon is itself the link, named "Home"
 (`material.app-shell.home`, translated): `getByRole('link', { name: 'Home' })`.
-The trail is hidden when no route has a breadcrumb.
+The trail is hidden when no route has a breadcrumb. A crumb whose
+`handle.breadcrumb` returns `null` (or `undefined`, `false`) is left out with
+its separator, as `handle.title` accepts `null`, so the trail is hidden too
+when every matched route returns `null`.
+
+An error page rendered by `ActivityLayout` still matches the failed route, so
+it would show its trail ("Home > Section" on a 404). Pass `breadcrumb={false}`
+to render the layout without the trail:
+
+```tsx
+// the root route's errorElement
+<ActivityLayout items={items} breadcrumb={false}>
+  <ActivityContent title="Page not found" />
+</ActivityLayout>
+```
 
 A multi-tenant app whose root is the current tenant passes `breadcrumbRoot`
 (`AppBreadcrumb`'s `root`) to replace the home icon with a text link,