@nxgt/material 3.10.1 → 3.11.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/navigation-and-layout.md

@@ -295,7 +295,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/illustrations.md

@@ -41,6 +41,13 @@ with `data-scene`, `data-size` and `data-animated`). A bad icon name or style
 never crashes the page: outside production it warns once in the console, and
 the scene's built-in art is drawn instead.
 
+Two data attributes say what was drawn, for a test or a style:
+`data-plated` is on the `<svg>` once the plate has drawn (the disc that stands
+in while the chunk loads has none), and `data-fallback` is on the built-in art
+that stands in when the scene cannot be drawn (a bad icon, or a chunk that
+failed to load). On an `EmptyState` or `ErrorState` it is on the box
+(`data-slot="illustration"`) or the `<svg>` inside it.
+
 The sprites are read from `/assets/icons/sprites/`, or from the base of the
 nearest `IconSpritesProvider`. An icon whose name the sprite does not hold is
 blank: keep to names every style you use has (the suggested ones are the
@@ -51,6 +58,11 @@ arrives, in a box of the same size, so the page does not move. A streaming
 server render includes the plate; `renderToString` sends the disc and the
 browser draws the plate once the chunk has loaded.
 
+If a chunk fails to load (a flaky network, or a tab kept open across a deploy
+whose old hashed files are gone), the illustration draws the built-in art of the
+scene's kind instead of throwing: the page, and the `EmptyState` around it,
+stay. There is no retry; outside production the console warns once.
+
 ## Use them in the states
 
 `EmptyState`, `ErrorState` and the `DataTable` empty row draw today's built-in

package/docs/guides/theming.md

@@ -35,6 +35,8 @@ at the top are needed is in [getting started](../getting-started.md#styles).
   `AttributeForm` and `AttributeValuesForm`, and the required-field mark drawn
   after a `Label` (the first three are dependencies, the rest ship in
   `lib/components/`);
+- the **type scale**: `--text-<role>-<size>` tokens and the `text-title-md` and
+  `text-title-md-em` utilities ([Type scale](#type-scale));
 - the **tokens**: CSS variables on `:root`, and their dark values on `.dark`
   and `[data-theme="dark"]`;
 - an `@theme inline` block that maps each token to a Tailwind colour, so
@@ -664,6 +666,55 @@ does not set it: without it the title uses the body face. Set it on `:root`
 }
 ```
 
+## Type scale
+
+The text sizes are the Material 3 type scale: five roles (`display`, `headline`,
+`title`, `body`, `label`) in three sizes (`lg`, `md`, `sm`), as Tailwind 4
+tokens in `styles.css`. Each step has a size, a line height, a tracking and a
+weight, and an emphasized (heavier) weight:
+
+```css
+--text-title-md: 1rem;
+--text-title-md--line-height: 1.5rem;
+--text-title-md--letter-spacing: 0.0094em;
+--text-title-md--font-weight: 500;
+--text-title-md--font-weight-em: 680;
+```
+
+They are real Tailwind utilities, so your own markup uses the same steps as
+`Typography`, `Button` and the bare headings:
+
+```tsx
+<h2 className="text-headline-sm">Orders</h2>
+<p className="text-body-md">12 orders are waiting.</p>
+<span className="text-title-md-em">Next delivery</span>
+```
+
+`text-title-md` sets size, line height, tracking and weight; `text-title-md-em`
+keeps the first three and takes the emphasized weight. `font-bold`,
+`leading-*` and `tracking-*` still win over them. Retune a step with CSS
+variables, on `:root` for the app or on a zone for one part of the page; there
+is no `defineTheme` key:
+
+```css
+:root {
+  --text-body-md: 0.9375rem;
+  --text-body-md--line-height: 1.4rem;
+}
+
+.dense-table {
+  --text-title-md--font-weight-em: 600;
+}
+```
+
+Weights are numeric and read on a variable font's `wght` axis (Inter Variable
+covers 100 to 900); the library sets no `font-variation-settings`, and
+`font-optical-sizing` stays at the browser's `auto`. The bare `h1` to `h6` are
+`headline-md`, `headline-sm`, `title-lg`, `title-md`, `title-sm` and
+`label-md` at weight 500, so a retuned step retunes them too. The
+[Typography component](../components/primitives.md#typography) has the table of
+values and the deprecated names.
+
 ## Overriding tokens
 
 Redefine the variables **after** the import, for light and dark separately:

package/docs/roadmap.md

@@ -123,6 +123,18 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Next
 
+- **`ButtonGroup` standard look by default, and the old `Typography` names
+  removed (4.0)** — `ButtonGroup`'s Material 3 Expressive look (`look="standard"`)
+  becomes the default, with `look="legacy"` to keep the original group. The
+  fifteen deprecated `Typography` variants (`huge-*`, `headline-larger`,
+  `headline-large`... `caption`) are removed in favour of the type scale's
+  names, once the other component families read the scale
+  ([Typography](components/primitives.md#typography)).
+
+- **IconButton: `round` or `square` like Button** — a `shape` of `round` or
+  `square` on `IconButton`, with the same press morph, beside the expressive
+  shape names it takes today.
+
 - **DataGrid: row selection on phones** — the phone list gets the selection
   control the grid has with `enableRowSelection`: a checkbox per item and a
   select-all, with the same `rowSelection` state.
@@ -220,10 +232,11 @@ version they shipped in, and planned entries may name the major they target.
 - **`CircularProgress` at Material 3's size** — the default `size` becomes
   Material 3's 40 px (48 px when `wavy`) instead of 100 px. Pass `size` today
   to keep a size across the change.
-- **`Button` on the expressive size scale** — `xs` becomes 28 px (was
-  24) and `lg` 44 px (was 40), the scale `SplitButton` and `ToggleGroup`
-  already follow, so a `Button` and a `SplitButton` of the same size line
-  up.
+- **`Button` `xs` and `lg` on the `SplitButton` scale** — 3.11 keeps `Button`
+  at 24, 32, 36 and 40 px (and adds `xl` 56 and `2xl` 96); `xs` becoming 28 px
+  and `lg` 44 px, the scale `SplitButton` and `ToggleGroup` follow, so a
+  `Button` and a `SplitButton` of the same size line up, stays a possible
+  change for a major.
 - **A CSP without `style-src-attr 'unsafe-inline'`** — the four form controls'
   hidden inputs and the `Checkbox` indicator no longer need it;
   `SelectValue`, the `RadioGroup` root, `Slider` and popper positioning still
@@ -295,6 +308,24 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **Buttons and the type scale in Material 3 Expressive** — `Typography` takes
+  the Material 3 scale (`display`, `headline`, `title`, `body`, `label`, each
+  `lg`, `md` and `sm`, plus `emphasized`) as Tailwind tokens: `text-title-md`
+  and `text-title-md-em` are utilities, and an app or a zone retunes a step
+  with CSS variables. The former variants are deprecated aliases (their sizes
+  changed) and the bare `h1` to `h6` read the scale. `Button` gains the `xl`
+  (56 px) and `2xl` (96 px) sizes, `shape` `round` or `square` with a spring
+  press morph, and `selected` (a toggle with an inverted shape and a solid
+  fill); every button has a 2 px focus outline, a neutral disabled look and a
+  44 px hit area on a coarse pointer. `IconButton` gets `size` `xs` to `xl`
+  and `width` `narrow`, `default` or `wide`, on Button's look and the shared
+  toggle fill. `ButtonGroup` gets `look="standard"` (the pressed button widens,
+  its neighbours give the width back) and a `size` its buttons share. Nothing
+  changes in core. React only; the Vue port is a `vue` issue. 3.11.0.
+  ([Buttons & actions](components/buttons-and-actions.md),
+  [Typography](components/primitives.md#typography),
+  [Type scale](guides/theming.md#type-scale))
+
 - **Icon backgrounds, celestial presets and illustrations** — `Background
   preset="icons"` draws a pattern of icons from the packs, `iconStyle` taking
   one style or a list and `iconMotif` choosing the layout.

package/docs/troubleshooting.md

@@ -86,6 +86,10 @@ words in your error.
 - [A test of the editor's More panel finds nothing (`[data-editor-more]`)](#a-test-of-the-editors-more-panel-finds-nothing-data-editor-more)
 - [An editor, a composer or `PdfReader` looks different after upgrading, and fewer tools fit before More](#an-editor-a-composer-or-pdfreader-looks-different-after-upgrading-and-fewer-tools-fit-before-more)
 - [An `IconButton` with `aria-pressed` now widens and fills when pressed](#an-iconbutton-with-aria-pressed-now-widens-and-fills-when-pressed)
+- [Text got bigger or smaller after upgrading to 3.11 (`Typography` `huge-*`, `headline-*`, `title-*`, `caption`)](#text-got-bigger-or-smaller-after-upgrading-to-311-typography-huge--headline--title--caption)
+- [`Type '"icon"' is not assignable to type '"xs" | "sm" | "default" | "lg" | "xl"'` when spreading Button props into an `IconButton`](#type-icon-is-not-assignable-to-type-xs--sm--default--lg--xl-when-spreading-button-props-into-an-iconbutton)
+- [A pill `IconButton` toggle is the wrong width with a `size-*` class](#a-pill-iconbutton-toggle-is-the-wrong-width-with-a-size--class)
+- [A `Button` with a height class of your own has the wrong corner radius](#a-button-with-a-height-class-of-your-own-has-the-wrong-corner-radius)
 
 **Feedback**
 
@@ -425,6 +429,7 @@ words in your error.
 **Illustrations**
 
 - [`Illustration: … Drawing the built-in art instead.`](#illustration--drawing-the-built-in-art-instead)
+- [`Failed to fetch dynamically imported module` from an empty state or an illustration](#failed-to-fetch-dynamically-imported-module-from-an-empty-state-or-an-illustration)
 
 - [Reporting a bug](#reporting-a-bug)
 
@@ -1241,7 +1246,7 @@ inside the child element is clipped without one.
 **Fix:** update. Then pick, for each long label: leave the ellipsis (give a
 `title` so a sighted user can read it whole; the accessible name already
 is), let it break onto lines with `wrap`, or give the button a width of
-your own through `className`. With `asChild`, put the label in a `<span>`:
+your own through `className`. With `asChild`, put the label in a `<span>` (on a touch screen in Safari an `asChild` host is not clipped, to keep its 44 px hit area, so only a span gets the ellipsis):
 
 ```tsx
 <Button title="Continue to the payment details">Continue to the payment details</Button>
@@ -1630,7 +1635,7 @@ screen.getByRole('button', { name: 'Bold', pressed: true });
 ### An `IconButton` with `aria-pressed` now widens and fills when pressed
 
 **When:** after upgrading, an icon toggle (an `IconButton` with `aria-pressed`) grows into a filled pill when pressed and pushes its neighbours by 14 px.
-**Fix:** `morph="round"` keeps a filled circle that does not widen. A test that read the quiet pressed item's `::after` bar should read its background instead, or query the state: `getByRole('button', { name: 'Favourite', pressed: true })`.
+**Fix:** `morph="round"` keeps a filled circle that does not widen (a pill toggle's width follows its `size`: see [the wrong width with a `size-*` class](#a-pill-iconbutton-toggle-is-the-wrong-width-with-a-size--class)). A test that read the quiet pressed item's `::after` bar should read its background instead, or query the state: `getByRole('button', { name: 'Favourite', pressed: true })`.
 
 ```tsx
 <IconButton morph="round" aria-label="Favourite" aria-pressed={on} onClick={toggle}>
@@ -1657,6 +1662,58 @@ A dialog opened from a bar button that is showing returns the focus to that butt
 
 A tool that toggles is a `menuitemcheckbox`, a plain action or a dialog a `menuitem` (a dialog's has `aria-haspopup="dialog"`), the text colour, the highlight and the emoji a `menuitem` that opens their popover at More (a `dialog` named as the tool). The block type, the font, the callout types and the image's upload are submenus; the block type and the font list `menuitemradio` rows, and the submenu's row shows the current one after its name. A folded group of two or more rows is a `group` named by its label; a group of one row lists that row alone, with no group around it; a single-choice group stays a named radio group, even with one row. The alignments are a radio group named "Alignment" of `menuitemradio` rows, the current one checked (`getByRole('menuitemradio', { name: 'Align left' })`), while the bar keeps them as `aria-pressed` buttons. The text and highlight colour pickers are now a `dialog` (the library `Popover`, named as the tool), not a `menu`, in the bar too; a test of `[data-group-id="…"]` waits for its `hidden` attribute, not for it to leave. In the rail the groups are `data-slot="toolbar-group"` (they were `editor-toolbar-group`, which only `layout="wrap"` keeps) and the separators `data-slot="toolbar-separator"`: select a group by `data-group` or `data-group-id`.
 
+### Text got bigger or smaller after upgrading to 3.11 (`Typography` `huge-*`, `headline-*`, `title-*`, `caption`)
+
+**When:** after the upgrade, a heading, a stat or a caption set with a `Typography` `variant` such as `title-medium` (18 to 16 px), `title-large` (20 to 22 px), `headline-large` (36 to 32 px), `huge-large` (96 to 57 px) or `caption` (10 to 11 px) has another size, line height and weight, and so do the bare `h1` to `h6` (`h1` 24 to 28 px, `h2` 20 to 24, `h3` 18 to 22).
+**Why:** `Typography` moved to the Material 3 type scale. The fifteen former variants are kept, deprecated, as aliases of the scale by name, so the sizes follow the scale; the headings read it too.
+**Fix:** pick the step you want by its scale name, which also silences the deprecation. The table of former names and sizes is in [Typography](components/primitives.md#typography); to keep an old size in one place, retune the step with CSS variables:
+
+```tsx
+// before
+<Typography variant="title-medium">Next delivery</Typography>
+// after: the same step, written in the scale
+<Typography variant="title-md" emphasized>Next delivery</Typography>
+```
+
+```css
+/* or keep 18 px for one zone */
+.invoice { --text-title-md: 1.125rem; --text-title-md--line-height: 1.75rem; }
+```
+
+### `Type '"icon"' is not assignable to type '"xs" | "sm" | "default" | "lg" | "xl"'` when spreading Button props into an `IconButton`
+
+**When:** a wrapper spreads a `Button`'s props (`ComponentProps<typeof Button>`, `ButtonProps`) into an `IconButton` or `IconLinkButton`, and the compiler rejects `size` after the upgrade, or `shape`.
+**Why:** `IconButton` has its own typed `size` (`xs` to `xl`), which the `Button`'s `icon`, `icon-xs`, `icon-sm`, `icon-lg` and `2xl` are not; and `Button`'s `shape` is `round` or `square` where `IconButton`'s is an expressive shape name.
+**Fix:** drop `size` and `shape` before spreading, or pass the ones `IconButton` takes:
+
+```tsx
+const { size, shape, ...rest } = props;
+return <IconButton size="lg" {...rest} />;
+```
+
+### A pill `IconButton` toggle is the wrong width with a `size-*` class
+
+**When:** an `IconButton` toggle (`aria-pressed`, `morph="pill"`) given a `size-*` class of your own (`size-12`) is as wide as its `size` says, not as your class does, when pressed.
+**Why:** the pill's pressed width follows the button's `size` (24 to 56 px, 36 px unset), so it is the same at every size without the old `::before`.
+**Fix:** give the button a `size` instead of a `size-*` class; use `width="wide"` for a longer resting button.
+
+```tsx
+<IconButton size="xl" aria-pressed={on} aria-label="Favourite">
+	<Star />
+</IconButton>
+```
+
+### A `Button` with a height class of your own has the wrong corner radius
+
+**When:** a `Button` given a height of its own (`className="h-11"`) is a pill whose corners are those of its `size`: a 44 px button with the 18 px radius of a 36 px one, or a squarer pill than expected, and the corners spring toward the wrong size when pressed.
+**Why:** a round button's radius is half of `--btn-h`, which its `size` sets (36 px without one); a height class changes the box and not that variable.
+**Fix:** set `--btn-h` with your height class, or use `size`:
+
+```tsx
+<Button className="[--btn-h:44px] h-(--btn-h)">Save</Button>
+<Button size="xl">Save</Button>
+```
+
 ## Feedback
 
 ### An `EmptyState` with no `kind` shows "No Data Found" where it showed "Something Went Wrong"
@@ -7233,6 +7290,18 @@ import { HEALTH_SCENES } from '@nxgt/material/illustrations/health';
 <Illustration scene="patient-record" scenes={HEALTH_SCENES} iconStyle="duotone-light" />;
 ```
 
+### `Failed to fetch dynamically imported module` from an empty state or an illustration
+
+**When:** a page that shows an `EmptyState`, an `ErrorState`, a `DataTable` empty state or an `Illustration` with a scene loses its content to the error boundary, with `Failed to fetch dynamically imported module` (or `error loading dynamically imported module`) naming an illustration chunk. Seen on a flaky network, and in a tab kept open across a deploy whose old hashed chunk is gone. Versions before the release that carries this fix (3.10.0 and earlier).
+**Why:** the scene and the plate load on demand, and a rejected import was not caught inside the component, so it reached the route's error boundary.
+**Fix:** upgrade to the release that carries the fix. A failed illustration chunk then draws the built-in art of the state's kind (no retry), and outside production the console warns once with `Illustration: the "…" chunk failed to load`. In a test, `data-fallback` marks the built-in art and `data-plated` marks a drawn plate:
+
+```tsx
+expect(container.querySelector('[data-fallback]')).not.toBeNull();
+```
+
+Before upgrading, precaching the illustration chunks in the service worker narrows the window.
+
 ---
 
 ## Reporting a bug