@nxgt/material 3.4.0 → 3.6.0

package/docs/components/data-display.md

@@ -60,7 +60,7 @@ Parts: `Avatar` (the composed one), `AvatarBase`, `AvatarImage`,
 | `shape` | `ShapeName` | — | clips the photo to one of the expressive shapes instead of a circle; the fallback is framed by it when there is no `src` or it fails to load. `alt` names it. Unset: the round avatar, unchanged |
 | `tone` | the eight named tones, or a tone of your own declared in `AppTones` | neutral | the fallback fills with the tone's container, draws its initials or icon in the tone's text colour (`--nxgt-tone-text`, also when there is no `tone`) and a hairline in it (3:1 against the page or card). A loaded photo is not tinted |
 
-The hairline's strength is `--avatar-ring-share`, the share of the tone's text colour mixed into the surface (default `65%`, from `--nxgt-tone-ring-share`; 3:1 or more at that value). Override it in your CSS:
+The hairline's strength is `--avatar-ring-share`, the share of the tone's text colour mixed into the surface (default `68%`, from `--nxgt-tone-ring-share`; 3:1 or more at that value). Override it in your CSS:
 
 ```css
 :root { --avatar-ring-share: 80%; }
@@ -435,7 +435,7 @@ import { StatCard } from '@nxgt/material/components';
 
 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.
 
-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` (`65%`, 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.4:1 on a `Card` and 2.7: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).
+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).
 
 **Storybook:** `Data display/StatCard`, `Data display/StatCard/Tones` · **Vue:** `StatCard`
 

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

@@ -81,6 +81,7 @@ phone's menu sheet pad clear of `env(safe-area-inset-*)`, as classes; see the
 | `titleAs` | `'h1'` … `'h6'` \| `'div'` | `'h1'` | `ActivityContent`: the title's heading level |
 | `inset` | `boolean` | `false` | `ActivityContent`: pads the content 1rem on each side. Off, it lines up with the app bar and the cards |
 | `align` | `'start' \| 'center'` | `'start'` | `ActivityLayout`, `AppSidebar`: the collapsed rail's entries sit right under the brand, or `'center'` for centred in the height below it |
+| `backdrop` | `ReactNode` | — | `ActivityLayout`: a decorative background behind the frame, in place of the gradient and its blobs: a `Background` preset from `@nxgt/material/backgrounds`. Rendered in an `inert`, `aria-hidden` layer that fills the layout. See [Use a background preset behind the shell](../guides/app-shell.md#use-a-background-preset-behind-the-shell) |
 | `routeTransition` | `boolean \| Omit<ViewTransitionProps, 'children' \| 'ref'>` | `true` | `ActivityLayout`: React's `<ViewTransition>` around the content region, so a navigation cross-fades it. `false` renders none (your app has its own boundary); an object passes `default` / `update` classes, `name`, callbacks through. See [Route transitions](../guides/app-shell.md#route-transitions) |
 
 The active entry is the longest match across the whole menu, segment-aware.

package/docs/guides/app-shell.md

@@ -191,6 +191,7 @@ partitionMenu(items);                              // { content, footer }
 | `align` | `'start' \| 'center'` | `'start'` | Where the collapsed rail's entries sit: right under the brand, or centred in the height below it |
 | `menuOpen` | `boolean` | — | Controls the phone's menu sheet: open while `true`. Leave it out and the layout manages the sheet. Only a phone shows the sheet |
 | `onMenuOpenChange` | `(open: boolean) => void` | — | Called for every change of the sheet: the menu button, Escape, the close button, a followed link, a new location |
+| `backdrop` | `ReactNode` | — | A decorative background drawn behind the frame in place of the built-in gradient and blobs: usually a `Background` preset from `@nxgt/material/backgrounds` (see [Use a background preset behind the shell](#use-a-background-preset-behind-the-shell)) |
 
 On a page with `viewport-fit=cover` (an installed PWA drawing under a
 notch and the home indicator), the shell pads clear of
@@ -483,6 +484,52 @@ while the sheet is open, so leave ids out of it. A link in `brand` (a home
 link around the logo) is the sheet's first focusable element, so it takes
 the focus when the sheet opens.
 
+## Use a background preset behind the shell
+
+The shell draws the gradient with three blurred blobs behind its frame. To use
+one of the 44 presets of `@nxgt/material/backgrounds` instead, pass it as
+`backdrop`:
+
+```tsx
+import { Outlet } from 'react-router';
+import { ActivityLayout, type MenuItem } from '@nxgt/material/components';
+import { Background, MOTIF_SHAPES_ALL } from '@nxgt/material/backgrounds';
+import '@nxgt/material/backgrounds.css'; // or one preset's backgrounds/<preset>.css
+
+export function Shell({ items }: { items: MenuItem[] }) {
+  return (
+    <ActivityLayout
+      items={items}
+      backdrop={<Background preset="shapes" motif={{ shapes: MOTIF_SHAPES_ALL }} />}
+    >
+      <Outlet />
+    </ActivityLayout>
+  );
+}
+```
+
+- **It replaces the gradient.** While `backdrop` is given the layout's root
+  carries `data-backdrop`, and the built-in gradient (its tint and three blobs) is not drawn (plain
+  CSS, no inline `style`). Without it the markup and the look are what they
+  were; `null`, `undefined` and `false` count as none.
+- **It sits behind everything.** The node is wrapped in a layer
+  (`[data-slot="activity-layout-backdrop"]`) that fills the layout, under the
+  sidebar, the header and the content. The layer is `inert`, `aria-hidden="true"`
+  and takes no pointer, so the preset is decoration only: put nothing
+  interactive in it.
+- **It fills the layout.** A `Background` in the layer is sized to the layer,
+  not to `100lvw × 100lvh`, so you need no `className` or `fill`. In
+  `scroll="document"` the layout grows with the content, and so does the preset.
+- **Readable by design.** The frame keeps `bg-background-paper` and the sidebar
+  and header their `bg-background/40`, so the content reads over a busy preset.
+  Tone it down with the preset's `intensity` (`subtle`) rather than by
+  restyling the frame.
+- **The stylesheet is yours to import.** `@nxgt/material/backgrounds` is a
+  separate entry, so `ActivityLayout` never pulls it in: import it where you
+  build the `backdrop`, and its `backgrounds.css` once.
+- The `--nxgt-bg-blob-1..3` variables recolour the built-in blobs only; the
+  `blobs` preset reads them too.
+
 ## Route transitions
 
 `ActivityLayout` wraps its content region (`data-slot="activity-content-region"`)

package/docs/guides/backgrounds.md

@@ -296,12 +296,18 @@ you can select on:
 The gradient ends on `--nxgt-bg-cp`, not `--nxgt-bg-c2`: to recolour it, set
 `--nxgt-bg-cp` too.
 
+## Behind the app shell
+
+`ActivityLayout` takes a preset as its `backdrop`, replacing the gradient and
+its blobs: `backdrop={<Background preset="shapes" motif={{ shapes: MOTIF_SHAPES_ALL }} />}`.
+See [Use a background preset behind the shell](./app-shell.md#use-a-background-preset-behind-the-shell).
+
 ## Recolour the blobs
 
 The gradient's three blobs have a public API: `--nxgt-bg-blob-1`, `--nxgt-bg-blob-2` and `--nxgt-bg-blob-3`.
 Each takes any colour. Unset, a blob keeps the tone's gradient, so adding the
 variables changes nothing until you set one. The `blobs` preset reads the same variables. `ActivityLayout` draws the same
-blobs, so set them on `[data-slot="activity-layout"]`:
+blobs (unless it has a `backdrop`), so set them on `[data-slot="activity-layout"]`:
 
 ```css
 [data-slot="activity-layout"] {

package/docs/guides/theming.md

@@ -90,6 +90,48 @@ container is the accent colour itself, the same as `bg-accent`.
 
 Put `text-foreground` on a container; it stays well above 4.5:1 in both themes.
 
+## The neutral palette
+
+The neutrals of both themes are softly tinted toward violet (hue 290, low
+chroma), to sit with the primary indigo instead of fighting it. The values:
+
+| Token | Light | Dark |
+| --- | --- | --- |
+| `--background` | `oklch(0.973 0.008 293.9)` | `oklch(0.192 0.016 290.5)` |
+| `--card`, `--popover` / `--sidebar` | white / `oklch(0.985 0.006 293.9)` | `oklch(0.232 0.019 289.4)` |
+| `--foreground` | `oklch(0.227 0.017 290)` | `oklch(0.943 0.012 291.3)` |
+| `--muted`, `--accent` | `oklch(0.955 0.012 292)`, `oklch(0.91 0.016 293)` | `oklch(0.27 0.022 290)` |
+| `--muted-foreground` | `oklch(0.478 0.032 292)` | `oklch(0.725 0.03 292.2)` |
+| `--border`, `--input` | `oklch(0.912 0.016 293.7)` | `oklch(0.301 0.025 291.4)`, `oklch(0.34 0.027 291.4)` |
+
+Earlier versions used a blue-slate neutral (hue 247 to 266; the dark
+background `oklch(0.14 0.036 258.53)` was a deep navy). To bring it back,
+redefine the tokens after the stylesheet import, under the same selectors;
+the main ones are below and the changelog of `@nxgt/material` 3.6.0 lists
+every old value (accent, ring, sidebar, tooltip, secondary and the others):
+
+```css
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.14 0.036 258.53);
+  --muted: oklch(0.968 0.007 247.896);
+  --muted-foreground: oklch(0.52 0.046 257.417);
+  --border: oklch(0.929 0.013 255.508);
+  --input: oklch(0.929 0.013 255.508);
+}
+.dark,
+[data-theme="dark"] {
+  --background: oklch(0.14 0.036 258.53);
+  --foreground: oklch(0.984 0.003 247.858);
+  --card: oklch(0.208 0.042 265.755);
+  --popover: oklch(0.208 0.042 265.755);
+  --muted: oklch(0.279 0.041 260.031);
+  --muted-foreground: oklch(0.66 0.046 257.417);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+}
+```
+
 ## Motion and shape tokens
 
 `styles.css` also carries Material 3 expressive motion and corner tokens, as
@@ -227,12 +269,12 @@ any tone, yours included:
 | `--nxgt-tone-on` | `text-tone-on` | what is drawn on it |
 | `--nxgt-tone-container` | `bg-tone-container` | a tint of it over the surface it sits on |
 | `--nxgt-tone-text` | `text-tone-text` | it as text on the page or its container |
-| `--nxgt-tone-ring-share` | — | the share of the text colour in the ring below (`65%`, set on `:root`) |
+| `--nxgt-tone-ring-share` | — | the share of the text colour in the ring below (`68%`, set on `:root`) |
 | `--nxgt-tone-ring` | `border-(--nxgt-tone-ring)` | a hairline: its text colour mixed into the surface at that share, 3:1 against it |
 
 The ring is drawn by: the `Avatar` fallback (the inset hairline, or the stroke of a shaped one); the tonal `StatCard` outline, the edges of its filled card and the ring round its icon chip; the outline and rank badge of a toned metric card; and, in a [calm zone](#calm-zone), the edge of a tonal `Shape`, an `Avatar`, a `StatCard` and a rank badge once their container steps back.
 
-Which knob changes which ring: `--nxgt-tone-ring-share` is the shared one, and being inherited it works on `:root` (`:root { --nxgt-tone-ring-share: 80%; }` makes every ring stronger) or on a wrapper (only the rings inside it). A component with a knob of its own, `--avatar-ring-share` or `--stat-card-ring-share`, takes it over for that component only: it applies to the component's own element, it is not inherited by a tone nested inside it, and `--stat-card-ring-share` draws every edge of the `StatCard`. Keep a ring at 3:1 or more against its surface (65 % does in light and dark) when you change the share.
+Which knob changes which ring: `--nxgt-tone-ring-share` is the shared one, and being inherited it works on `:root` (`:root { --nxgt-tone-ring-share: 80%; }` makes every ring stronger) or on a wrapper (only the rings inside it). A component with a knob of its own, `--avatar-ring-share` or `--stat-card-ring-share`, takes it over for that component only: it applies to the component's own element, it is not inherited by a tone nested inside it, and `--stat-card-ring-share` draws every edge of the `StatCard`. Keep a ring at 3:1 or more against its surface (68 % does in light and dark) when you change the share.
 
 ```tsx
 <span data-tone="success" className="bg-tone-container text-tone-text">
@@ -742,22 +784,22 @@ the rest yourself. Without the class the anchor keeps the prose style.
 ## Contrast and reduced motion
 
 **Contrast.** The shipped light palette keeps the text of every filled status
-colour at 4.5:1 or more (WCAG 1.4.3): `--secondary` 5.7:1, `--success` 5.6:1,
-`--info` 5.8:1 and `--warning` 5.5:1 against their `-foreground`, and
+colour at 4.5:1 or more (WCAG 1.4.3): `--secondary` 6.2:1, `--success` 6.1:1,
+`--info` 6.3:1 and `--warning` 5.5:1 against their `-foreground`, and
 `--secondary` as text (a `tonal`, `outlined` or `link` `Button`) 6.0:1 on
 `--background`, 4.8:1 on its own 15 % `tonal` tint.
 
 The dark theme keeps brighter values, read as text on the dark surfaces: the
-dark `--tertiary` (`oklch(0.7 0.15 310.75)`) is 7.0:1 on `--background` and
-6.3:1 on `--card`, with a dark `--tertiary-foreground` that keeps 7.0:1 on
+dark `--tertiary` (`oklch(0.7 0.15 310.75)`) is 6.5:1 on `--background` and
+5.9:1 on `--card`, with a dark `--tertiary-foreground` that keeps 6.5:1 on
 a filled tertiary surface (light: 7.6:1 under near-white). The dark
-`--secondary` (`oklch(0.66 0.1135 245.65)`) is 6.5:1 on `--background`
-and 5.8:1 on `--card` (a `tonal` secondary `Button` 5.4:1 and 4.6:1). Under
+`--secondary` (`oklch(0.675 0.1135 245.65)`) is 6.3:1 on `--background`
+and 5.8:1 on `--card` (a `tonal` secondary `Button` 5.1:1 and 4.6:1). Under
 near-white text those brights are too light, so every filled surface built on
 them is tinted in the dark theme: a filled `secondary` `Button`, `IconButton`
-or `Badge` at 70 % (5.2:1 on `--background`, 4.9:1 on `--card`), a filled
-`success`, `info` or `warning` one at 60 % (7.3:1, 5.7:1 and 6.0:1 on
-`--background`; 6.7:1, 5.3:1 and 5.6:1 on `--card`; the `warning` `Button` 6.5:1). Their hover, focus and
+or `Badge` at 70 % (4.9 to 5.2:1 on `--background`, 4.7 to 4.9:1 on `--card`), a filled
+`success`, `info` or `warning` one at 60 % (7.1:1, 5.6:1 and 5.8:1 on
+`--background`; 6.8:1, 5.3:1 and 5.5:1 on `--card`; the `warning` `Button` 5.9:1). Their hover, focus and
 pressed states are tinted further down, so they only gain contrast.
 
 In the light theme the filled `primary`, `secondary`, `success`, `info`,
@@ -773,11 +815,11 @@ The `tonal`, `outlined` and `link` variants of `Button` and `IconButton` draw
 their text and icon in one tone per colour, read on `--background`, on
 `--card` and on the variant's own tint (15 % at most, at rest or focused). In
 the light theme `primary`, `secondary`, `info` and `success` use the token
-itself (5.8, 4.8, 4.9 and 4.7:1 at their lowest) and `warning` and `error` the
-token mixed with 15 % black (6.4 and 5.4:1). In the dark theme `primary` is
-mixed with 60 % white, the `--primary-text` token (8.1:1 on `--card`: the token itself is a dark indigo,
-2.2:1), `success` and `warning` with 15 % white (5.0 and 6.3:1), `error` with
-30 % white (5.9:1), and `secondary` and `info` use the token (4.6 and 5.3:1).
+itself (5.4, 4.8, 4.9 and 4.7:1 at their lowest) and `warning` and `error` the
+token mixed with 15 % black (6.0 and 5.0:1). In the dark theme `primary` is
+mixed with 60 % white, the `--primary-text` token (7.7:1 at its lowest: the token itself is a dark indigo,
+2.2:1), `success` and `warning` with 15 % white (4.8 and 5.8:1), `error` with
+30 % white (5.5:1), and `secondary` and `info` use the token (4.6 and 5.0:1).
 The tones are mixed from the tokens (`color-mix(in oklab, var(--color-error)
 85%, black)`), so an override of a token moves its tone with it; a text colour
 of your own on one of those buttons (`className="text-primary-text"`) replaces the tone
@@ -796,32 +838,32 @@ the filled surface's near-white text below 4.5:1 (`0.62` gives 3.85:1).
 the light theme, 70 in the dark one), so a warning `Alert`, `Banner`, `Badge`
 or toast does not read as a failure. Light `oklch(0.52 0.13 62)` is 5.5:1
 under its near-white `-foreground`; dark `oklch(0.7 0.15 70)` reads as text at
-7.3:1 on `--background` and 6.5:1 on `--card` (6.6 and 5.8:1 on its 10 % tint). An app that overrides `--warning` keeps its own
+6.7:1 on `--background` and 6.1:1 on `--card` (5.9 and 5.3:1 on its 10 % tint). An app that overrides `--warning` keeps its own
 value; one that keeps the shipped value sees its `bg-warning` and
 `text-warning` surfaces change hue, and re-checks its custom pairs.
 
 **A selected `DataTable` row** (`TableRow`, `data-state="selected"`) is a 15 %
 primary tint with `foreground` text, a bar on the inline-start edge of its
 first cell (`before:`, primary in the light theme, primary mixed with 60 %
-white in the dark one: 5.9:1 in light and 8.2:1 or more in dark against the
-row), and the checkbox, drawn in the same dark colour (8.2:1 or more). The
-tint is too light to be told from its neighbour alone (1.2:1 in light, 1.06 to
+white in the dark one: 5.4:1 in light and 7.7:1 or more in dark against the
+row), and the checkbox, drawn in the same dark colour (7.7:1 or more). The
+tint is too light to be told from its neighbour alone (1.25:1 in light, 1.10 to
 1.11:1 in dark), which is what keeps the text at 4.5:1 or more on a page and on
-a `Card`: 15.9:1 in light, and in dark 17.5:1 on a page, 17.1:1 in a `DataTable`
-on a `Card` and 15.4:1 for a bare `TableRow` on a `Card`. Links and
-`text-muted-foreground` texts (drawn as `foreground` at 70 %) are 7.0:1 in
-light and 8.15:1 in dark for a bare row on a `Card`. A `text-error-text` text
+a `Card`: 12.6:1 in light, and in dark 14.1:1 on a page, 12.9:1 in a `DataTable`
+on a `Card` and for a bare `TableRow` on a `Card`. Links and
+`text-muted-foreground` texts (drawn as `foreground` at 70 %) are 5.6:1 in
+light and 7.0:1 in dark for a bare row on a `Card`. A `text-error-text` text
 keeps its colour. Do not
 put `text-primary-foreground` in a cell for a selected row: it is near-white
 on that tint.
 
 **Error text has a token of its own**, `--error-text` (`text-error-text`), so
 the fill can stay dark while the text is light enough to read. The light value
-is `color-mix(in oklab, var(--error) 94%, black)` (5.7:1 on `--background`
-and `--card`, 4.8:1 on the `bg-error/10` tint of a focused menu item, where
+is `color-mix(in oklab, var(--error) 92%, black)` (5.6:1 on `--background`,
+6.0:1 on `--card`, 5.0:1 on the `bg-error/10` tint of a focused menu item, where
 `--error` gives 5.0 and 4.2:1); the dark one is
-`color-mix(in oklab, var(--error) 80%, white)`, 5.9:1 on `--background` and
-5.3:1 on `--card`, where `--error` itself gives 4.2 and 3.8:1. Field messages,
+`color-mix(in oklab, var(--error) 80%, white)`, 5.4:1 on `--background` and
+5.0:1 on `--card`, where `--error` itself gives 3.9 and 3.5:1. Field messages,
 `HelperText` in its error state, form, dialog and upload errors, a textarea's
 counter over its limit, the error lines of `Terminal`, a
 `variant="error"` menu item and the falling values of the metric cards use it.
@@ -846,7 +888,8 @@ the override on the root.
 **Primary text has a token of its own**, `--primary-text` (`text-primary-text`),
 for the same reason: the brand colour is a dark fill (it keeps near-white text
 readable on a button) and reads at only about 2:1 as text on the dark surfaces.
-The light value is `var(--primary)`; the dark one is
+The light value is `color-mix(in oklab, var(--primary) 96%, black)` (primary
+4 % toward black, 7.3:1 on the violet page); the dark one is
 `color-mix(in oklab, var(--primary) 40%, white)` (primary mixed 60 % with
 white, the recipe of the tonal `Button` labels). `Typography tone="primary"`,
 the `Alert` primary icon, links, selected labels and the other primary text of
@@ -871,33 +914,33 @@ at rest, hovered, focused and pressed, the tracks and the tabs;
 tokens after an override.
 
 **Tabs.** An `underline` tab's active label is `--primary` in the light
-theme (7.3:1 on `--background` and `--card`, 6.7:1 on `--muted`) and
-`--primary` mixed with 60 % white in the dark one (10.0:1, 9.0:1 and 7.4:1);
+theme (6.8:1 on `--background`, 7.3:1 on `--card`, 6.4:1 on `--muted`) and
+`--primary` mixed with 60 % white in the dark one (9.3:1, 8.5:1 and 7.6:1);
 its bar and every tab's focus outline are `--primary` in the light theme and
-`--track-fill` in the dark one (at least 6.7:1 and 9.0:1 on those surfaces).
+`--track-fill` in the dark one (at least 6.7:1 and 9.4:1 on those surfaces).
 An inactive label is `--muted-foreground`, and turns to `--foreground` when
 hovered. A `segmented` tab's active label is `--foreground` on the raised
-surface (19.9:1 light, 17.0:1 dark); that surface is only 1.1:1 to 1.2:1 on
-the track, so it has a `--muted-foreground` border (5.0:1 light, 4.7:1 dark
+surface (17.1:1 light, 14.2:1 dark); that surface is only 1.1:1 to 1.2:1 on
+the track, so it has a `--muted-foreground` border (5.8:1 light, 6.2:1 dark
 on the track), and the label also changes colour and weight. Storybook's
 `Guides/Theming/Contrast` story `Tabs` measures each label at rest, hovered
 and focused, the outline, the bar and the border, on the three surfaces, in
 both themes.
 
-`--muted-foreground` is 5.5:1 on `--background` and `--card`, 5.1:1 on the
-"paper" tint (`bg-background-paper`, 5 % primary) and 5.0:1 on `--muted` in
-the light theme; in the dark theme it is 6.4:1 on `--background`, 5.7:1 on
-`--card`, 6.3:1 on the paper tint and 4.7:1 on `--muted`. The dark `--muted`
-is a dark surface (`oklch(0.279 0.041 260.031)`, it was the light value, a
-near-white block on a dark page) and `--foreground` on it reaches 14.0:1.
+`--muted-foreground` is 6.2:1 on `--background`, 6.7:1 on `--card`, 5.7:1 on the
+"paper" tint (`bg-background-paper`, 5 % primary) and 5.8:1 on `--muted` in
+the light theme; in the dark theme it is 7.5:1 on `--background`, 6.9:1 on
+`--card`, 7.3:1 on the paper tint and 6.2:1 on `--muted`. The dark `--muted`
+is a dark surface (`oklch(0.27 0.022 290)`, it was the light value, a
+near-white block on a dark page) and `--foreground` on it reaches 12.8:1.
 
 **Tracks.** The empty part of a `Slider`, of the password strength meter and
 the `Drawer` handle use `--track` (`bg-track`), and the `Slider`'s range and
 thumb border `--track-fill` (`bg-track-fill`, `border-track-fill`). In the
-dark theme the track reaches 3.6:1 on `--background` and 3.2:1 on `--card`
+dark theme the track reaches 3.5:1 on `--background` and 3.2:1 on `--card`
 (WCAG 1.4.11; `bg-muted`, a dark surface now, gave 1.4:1 and 1.2:1), and the
-fill 3.4:1 on the track. The light theme keeps a pale track (`--track` is the
-light `--muted`) and `--track-fill` is `--primary`: the thumb, 7.3:1 on the
+fill 3.3:1 on the track. The light theme keeps a pale track (`--track` is the
+light `--muted`) and `--track-fill` is `--primary`: the thumb, 6.8:1 on the
 page, shows the value. A track, bar, handle or divider of your own drawn with
 `bg-muted` is near invisible in the dark theme now that `--muted` is a dark
 surface: draw it with `bg-track`.

package/docs/troubleshooting.md

@@ -27,6 +27,7 @@ words in your error.
 
 - [Components render unstyled, with no error](#components-render-unstyled-with-no-error)
 - [A link is blue and underlined on hover and focus](#a-link-of-mine-or-of-a-component-is-blue-and-underlined-on-hover-and-focus)
+- [The light and dark neutrals turned violet after upgrading to 3.6](#the-light-and-dark-neutrals-turned-violet-after-upgrading-to-36)
 - [Math renders in the system fonts](#math-renders-in-the-system-fonts)
 - [`<Icon>` renders nothing](#icon-renders-nothing)
 - [An accessibility audit reports low contrast on a badge, a button, a toast or a menu entry](#an-accessibility-audit-reports-low-contrast-on-a-badge-a-button-a-toast-or-a-menu-entry)
@@ -58,6 +59,7 @@ words in your error.
 - [My activity content lost its side padding, or the rail's entries moved up](#my-activity-content-lost-its-side-padding-or-the-rails-entries-moved-up)
 - [axe reports `target-size` on a control under a form's sticky actions](#axe-reports-target-size-on-a-control-under-a-forms-sticky-actions)
 - [`color-contrast` fails over the background blobs on phone](#color-contrast-fails-over-the-background-blobs-on-phone)
+- [`ActivityLayout`'s `backdrop` shows nothing, or the blobs are still there](#activitylayouts-backdrop-shows-nothing-or-the-blobs-are-still-there)
 - [Shaped Gallery tiles are plain rounded squares](#shaped-gallery-tiles-are-plain-rounded-squares)
 - [A component with my own tone (Shape, Fab, Avatar, StatCard, a metric card) shows no colour, or `tone` is a type error](#a-component-with-my-own-tone-shape-fab-avatar-statcard-a-metric-card-shows-no-colour-or-tone-is-a-type-error)
 - [A test expects the old `bg-muted` Avatar fallback, or a filled fallback shows a grey ring](#a-test-expects-the-old-bg-muted-avatar-fallback-or-a-filled-fallback-shows-a-grey-ring)
@@ -739,6 +741,34 @@ public/assets/icons/sprites/sharp-solid.svg ← <Icon name="atom" family="sharp"
 
 Serve one sheet per style you use, from your own Font Awesome Pro kit.
 
+### The light and dark neutrals turned violet after upgrading to 3.6
+
+**When:** after `@nxgt/material` 3.6, the page, cards, borders and muted text
+are softly violet-tinted (the dark background was a deep navy), and a
+screenshot test, or a brand that sat on the old slate, no longer matches.
+**Why:** the neutral tokens moved to hue 290 with low chroma in both themes
+(the palette is listed in the [theming guide](guides/theming.md#the-neutral-palette)).
+Primary and the status colours did not change, except that the light
+`--secondary`, `--success` and `--info` and the dark `--secondary` moved
+0.02 in lightness, so their tonal tints keep 4.5:1 on the new page colour.
+**Fix:** update the screenshots, or redefine the old neutrals after the
+stylesheet import, under `:root` and `.dark, [data-theme="dark"]`:
+
+```css
+.dark,
+[data-theme="dark"] {
+  --background: oklch(0.14 0.036 258.53);
+  --card: oklch(0.208 0.042 265.755);
+  --popover: oklch(0.208 0.042 265.755);
+  --muted: oklch(0.279 0.041 260.031);
+  --border: oklch(1 0 0 / 10%);
+}
+```
+
+The [theming guide](guides/theming.md#the-neutral-palette) has the main old
+values for both themes (the `:root` block too); the changelog of 3.6.0 lists
+every one.
+
 ### An accessibility audit reports low contrast on a badge, a button, a toast or a menu entry
 
 **When:** axe (or Lighthouse) reports `color-contrast` on a `Badge` with
@@ -794,7 +824,7 @@ yours still fail, you override them.
 In the dark theme, a filled `secondary` `Button` gave its near-white text
 4.3:1, a `tonal` secondary one 3.9:1 (3.4:1 on `--card`), and a filled
 `success`, `info` or `warning` one 3.5:1, 2.5:1 and 3.4:1. The dark
-`--secondary` is brighter (`oklch(0.66 ...)`, 6.5:1 as text on
+`--secondary` is brighter (`oklch(0.675 ...)`, 6.3:1 as text on
 `--background`), and the filled `secondary`, `success`, `info` and `warning`
 `Button`s and `IconButton`s are filled in the dark theme with an opaque mix
 toward `--background` (about 70 %), so their text keeps 4.5:1 over any backdrop.
@@ -871,12 +901,12 @@ subtitle colour of your own on a selected `ListTile` must reach 4.5:1 on
 ### An accessibility audit reports low contrast on error text in the dark theme
 
 **When:** an error message, a validation hint or a red value of your own, in
-the dark theme, fails 4.5:1 (about 4.2:1 on the page, 3.8:1 on a card); the
+the dark theme, fails 4.5:1 (about 3.9:1 on the page, 3.5:1 on a card); the
 catalogue's own field messages pass.
 **Why:** it is drawn with `text-error`, the fill colour. The dark `--error` is
 kept dark enough for near-white text on a filled error surface, which makes it
 too dark to read as text on the dark surfaces. Error text has its own token,
-`--error-text`, lightened in the dark theme (5.9:1 on `--background`, 5.3:1 on
+`--error-text`, lightened in the dark theme (5.4:1 on `--background`, 5.0:1 on
 `--card`).
 **Fix:** draw text with `text-error-text`; keep `text-error` for fills,
 borders and icons that stand alone. On a `Button` or `IconButton` drop the
@@ -1254,6 +1284,23 @@ reports "needs review", not a failure), and delete the `[data-layer]` rules:
 }
 ```
 
+### `ActivityLayout`'s `backdrop` shows nothing, or the blobs are still there
+
+**When:** `<ActivityLayout backdrop={<Background preset="shapes" />}>` draws
+no shapes, or draws the gradient's blobs behind them.
+**Why:** the presets' CSS is not in `styles.css`, it is its own opt-in file, so
+without it the preset's layers have no look. The blobs are hidden by CSS keyed
+on `data-backdrop` in `styles.css`; they stay when the `Background` you pass
+comes from `@nxgt/material/components` (the gradient alone) and so draws its own
+blobs, or when the page loads a copy of `styles.css` older than 3.5.
+**Fix:** import `Background` from `@nxgt/material/backgrounds`, import
+`@nxgt/material/backgrounds.css` once, and keep `@nxgt/material` current.
+
+```tsx
+import { Background } from '@nxgt/material/backgrounds';
+import '@nxgt/material/backgrounds.css';
+```
+
 ### A ResponsiveButton no longer shows its tooltip next to its visible label
 
 **When:** a `ResponsiveButton` with a `tooltip` on a desktop width (768 px and up, or `expanded`), where the tooltip used to appear beside the label.

package/lib/components/components.css

@@ -56,6 +56,7 @@
 @import "./ui/actions/button-group/button-group.css";
 /* ActivityLayout: the route transition (cross-fade, none under reduced motion). */
 @import "./ui/layout/app-shell/route-transition.css";
+@import "./ui/layout/app-shell/activity-backdrop.css";
 /* DataTable cards and tiles: the item shell (hairline, tint, start bar, columns by the list's width). */
 @import "./ui/collections/data-table/data-table-items.css";
 @import "./ui/collections/data-table/data-table-items-compact.css";