@nxgt/material 3.2.0 → 3.4.0

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

@@ -741,7 +741,7 @@ import { Background, Card } from '@nxgt/material/components';
 It fills the viewport; pass a `className` such as `h-96 w-full` to use it as a band.
 It is plain CSS from `styles.css`, with no inline `style`, and its colours lift
 in dark. `ActivityLayout` and `ThreadLayout` sit on it. The superset with `grain`,
-`seed`, `fill`, `motif` and the other presets (light, geometry and motif families) is `Background` from `/backgrounds`; see the [backgrounds guide](../guides/backgrounds.md). Light presets there: `mesh`, `aurora`, `spotlight`, `bokeh`, `grain`; geometry: `isometric`, `blueprint`, `dots`, `stripes`, `low-poly`, `topography`, `waves`; motifs: `shapes`, `confetti-grid`, `constellation`, `halftone`, `truchet`, `floating`, `scatter-icons`.
+`seed`, `fill`, `motif` and the other presets (light, geometry and motif families) is `Background` from `/backgrounds`; see the [backgrounds guide](../guides/backgrounds.md). Light presets there: `mesh`, `aurora`, `spotlight`, `bokeh`, `rays`, `halo`, `plasma`, `glass`, `ripples`, `blobs`, `paper`, `linen`, `concrete`, `marble`, `grain`; geometry: `isometric`, `blueprint`, `dots`, `stripes`, `low-poly`, `topography`, `waves`, `hexagons`, `circuit`, `graph-paper`, `checker`, `diagonal-checker`, `chevrons`; motifs: `shapes`, `confetti-grid`, `constellation`, `halftone`, `truchet`, `floating`, `scatter-icons`, `school`, `night-sky`, `bubbles`, `leaves`, `science`, `music`, `travel`, `sport`.
 
 **Storybook:** `Navigation & layout/Background` · **Vue:** `Background`
 

package/docs/getting-started.md

@@ -139,7 +139,7 @@ and need nothing.
 | `@nxgt/material/editor/viewer` | `RichTextViewer`: shows a saved document (HTML, JSON or Markdown) read-only. **Server-safe**: no editor instance, no `'use client'` ([RichTextViewer](components/rich-widgets.md#richtextviewer)) |
 | `@nxgt/material/editor/collab` | `collaboration()`: several people editing one `DocumentEditor` through a Yjs document and provider your app supplies. Needs `yjs` and `y-protocols` ([Collaboration](components/rich-widgets.md#collaboration)) |
 | `@nxgt/material/editor/pm` | The editor's own tiptap and ProseMirror classes (`Extension`, `Node`, `Plugin`, `PluginKey`, `TextSelection`, `ProseMirrorNode`, `Fragment`, `DecorationSet`, …) for a custom feature's extensions, so `instanceof` agrees with the editor. Shares the editor's code; **server-safe** ([A custom feature](components/rich-widgets.md#a-custom-feature)) |
-| `@nxgt/material/backgrounds` | Background presets: `Background` (a superset of the `/components` one: `preset` (twenty ids, `AVAILABLE_BACKGROUND_PRESETS`), `tone`, `intensity`, `animated`, `grain`, `seed`, `fill` and `motif` (`shapes`, `density`, `size`, `rotate`, `shapeFill`, `opacitySpread`)), and the types and tables re-exported from `@nxgt/material-core/backgrounds`. **Its own entry**, with an opt-in stylesheet ([backgrounds](guides/backgrounds.md)) |
+| `@nxgt/material/backgrounds` | Background presets: `Background` (a superset of the `/components` one: `preset` (44 ids, `AVAILABLE_BACKGROUND_PRESETS`), `tone`, `intensity`, `animated`, `grain`, `seed`, `fill` and `motif` (`shapes`, `density`, `size`, `rotate`, `shapeFill`, `opacitySpread`)), and the types and tables re-exported from `@nxgt/material-core/backgrounds`. **Its own entry**, with an opt-in stylesheet ([backgrounds](guides/backgrounds.md)) |
 | `@nxgt/material/media-hls` | `hlsStreaming()`: the HLS adapter for `MediaPlayer`, `hls.js` loaded lazily ([streaming](guides/media-streaming.md)) |
 | `@nxgt/material/vite` | Build-time helper for consumers: `pdfkitStandardFonts()` ([printing](guides/printing.md#bundling-print-into-an-ssr-server)) |
 | `@nxgt/material/hooks` | `useTheme`, `useIsClient`, `useIsMobile`, `useLocalizedDate`, … ([helpers](guides/helpers.md#nxgtmaterialhooks)) |

package/docs/guides/backgrounds.md

@@ -7,7 +7,7 @@ preset family and shares its tones, its intensities and its CSS with
 that gradient. There, `Background` is a superset of the `/components` one under
 the same name (same props, plus the preset ones); it draws every preset: the
 gradient and the grain, the light family (`mesh`, `aurora`, `spotlight`,
-`bokeh`), the [geometry family](#geometry-presets) and the
+`bokeh`, `rays`, `halo`, `plasma`, `glass`, `ripples`, `blobs`, then the textures `paper`, `linen`, `concrete`, `marble`), the [geometry family](#geometry-presets) and the
 [motif presets](#motif-presets).
 
 ## Tone and intensity
@@ -45,7 +45,7 @@ import '@nxgt/material/backgrounds.css';
 
 | Prop | Values | Default |
 | --- | --- | --- |
-| `preset` | `gradient`, `grain`, `mesh`, `aurora`, `spotlight`, `bokeh`, `isometric`, `blueprint`, `dots`, `stripes`, `low-poly`, `topography`, `waves`, `shapes`, `confetti-grid`, `constellation`, `halftone`, `truchet`, `floating`, `scatter-icons` (`AVAILABLE_BACKGROUND_PRESETS`, the ids this library draws); any other id draws the gradient and warns outside production | `gradient` |
+| `preset` | `gradient`, `grain`, `mesh`, `aurora`, `spotlight`, `bokeh`, `rays`, `halo`, `plasma`, `glass`, `ripples`, `blobs`, `paper`, `linen`, `concrete`, `marble`, `isometric`, `blueprint`, `dots`, `stripes`, `low-poly`, `topography`, `waves`, `hexagons`, `circuit`, `graph-paper`, `checker`, `diagonal-checker`, `chevrons`, `shapes`, `confetti-grid`, `constellation`, `halftone`, `truchet`, `floating`, `scatter-icons`, `school`, `night-sky`, `bubbles`, `leaves`, `science`, `music`, `travel`, `sport` (`AVAILABLE_BACKGROUND_PRESETS`, the ids this library draws); any other id draws the gradient and warns outside production | `gradient` |
 | `tone`, `intensity` | as above | `primary`, `default` |
 | `animated` | `boolean`: drifts the layers, see Motion | `false` |
 | `grain` | `boolean`: film noise over the preset; needs `grain.css` | `false` |
@@ -53,11 +53,11 @@ import '@nxgt/material/backgrounds.css';
 | `motif` | a `MotifOptions` object (`shapes`, `density`, `size`, `rotate`, `shapeFill`, `opacitySpread`), see [Motif presets](#motif-presets) | all fields optional |
 | `fill` | `viewport` (the viewport's size) or `container` (its parent's size: the parent needs a definite height) | `viewport` |
 
-`BACKGROUND_PRESETS` is the table of all twenty presets with their family and
+`BACKGROUND_PRESETS` is the table of all 44 presets with their family and
 kind; `AVAILABLE_BACKGROUND_PRESETS` lists the ids this library draws (all
-twenty; `SHIPPED_BACKGROUND_PRESETS` is the common floor every library draws).
+44; `SHIPPED_BACKGROUND_PRESETS` is the common floor every library draws).
 
-<img src="../previews/backgrounds-matrix.webp" width="640" alt="The twenty presets, each in a card with its name">
+<img src="../previews/backgrounds-matrix.webp" width="640" alt="The 44 presets, each in a card with its name">
 
 The root states `preset`, `tone`, `intensity`, `animated`, `grain` and `fill` as
 `data-*` attributes (`data-animated` and `data-grain` are empty attributes), and
@@ -78,10 +78,12 @@ markup, and nothing is random or measured.
 
 <img src="../previews/backgrounds-light.webp" width="480" alt="The mesh preset behind a card">
 
-Soft colour, no geometry. All four read the tone's three colours, so they follow
+Soft colour, no geometry. All of them read the tone's three colours, so they follow
 `tone`, `intensity` and the theme; `animated` is opt-in and never runs under
 reduced motion. Their CSS is `mesh.css`, `aurora.css`, `spotlight.css` and
-`bokeh.css`.
+`bokeh.css`; the six after `bokeh` (`rays`, `halo`, `plasma`, `glass`, `ripples`,
+`blobs`) are drawn by `@nxgt/material` only, from `@nxgt/material/backgrounds.css` or
+one file such as `@nxgt/material/backgrounds/plasma.css`.
 
 | `preset` | What it draws | Notes |
 | --- | --- | --- |
@@ -89,18 +91,51 @@ reduced motion. Their CSS is `mesh.css`, `aurora.css`, `spotlight.css` and
 | `aurora` | four blurred, wavy veils with thin vertical rays | SVG scene; fixed geometry; adds light (`screen`) in dark; `animated` sways the veils |
 | `spotlight` | a cone of light from the top with six beams and a glow | SVG scene; fixed geometry; `animated` swings the beams |
 | `bokeh` | 26 blurred discs with a brighter rim | SVG scene; `seed` moves the discs; `animated` makes them bob |
+| `rays` | a sunburst: alternating rays from the top centre, faded with distance | CSS only (a conic gradient); adds light in dark; `animated` turns the burst slowly |
+| `halo` | a ring of light through the tone's three colours | CSS only (a conic gradient cut to a ring); adds light in dark; `animated` turns the colours round the ring |
+| `plasma` | a soft colour field: blurred discs whose tone and strength follow two value-noise fields | SVG scene; `seed` redraws the field; `animated` drifts it |
+| `glass` | frosted panes over blurred colour blobs | SVG scene; a background has no backdrop to blur, so the frost is faked (blurred blobs under pale panes with a bright edge); `seed` moves the blobs and the panes' edges; `animated` drifts the blobs behind the panes |
+| `ripples` | rings spreading from three seeded centres, one tone colour each, fading outward | SVG scene; `seed` moves the centres; `animated` makes each set of rings breathe |
+| `blobs` | seven soft organic blobs in the tone's colours | SVG scene (smooth seeded paths, slightly blurred); `--nxgt-bg-blob-1..3` recolour the blobs (unset, the tone's colours); `seed` redraws them; `animated` drifts each at its own pace |
 
 ```tsx
-<Background preset="aurora" tone="mixed" intensity="subtle" className="h-96 w-full">
+import '@nxgt/material/backgrounds/plasma.css'; // or backgrounds.css for every preset
+
+<Background preset="plasma" tone="mixed" intensity="subtle" seed={3} className="h-96 w-full">
   ...
 </Background>
 ```
 
+
+### The textures
+
+<img src="../previews/backgrounds-material-more.webp" width="480" alt="The paper, linen, concrete and marble textures behind a card">
+
+`paper`, `linen`, `concrete` and `marble` are discreet page textures: a wash of the
+tone (a warm cream for `paper`, a cool grey for `concrete`) under a fine pattern of
+specks that is black in light and white in dark (like the grain). They are made to sit
+under body text: the specks stay faint. `subtle` softens them, and `vivid` is capped:
+it draws as the default (`intensity` never goes above normal for these four), so body
+text keeps at least 6:1 over the darkest pixel and 8:1 over the darkest 1% in light and dark. They are still:
+`animated` adds nothing. Seeded: `seed` moves the fibres,
+the mottle, the slubs and the veins. React only, like the six before them
+(`@nxgt/material/backgrounds/paper.css`, `linen.css`, `concrete.css`, `marble.css`).
+
+| `preset` | What it draws | Notes |
+| --- | --- | --- |
+| `paper` | fibre grain on a warm tint that the tone cools or warms | SVG scene in screen pixels, a 400 px seamless tile of `feTurbulence`; the cream goes in dark |
+| `linen` | a plain weave: 1 px threads every 4 px, with faint slubs | the weave sits on whole pixels, so it is crisp at 1x and has no moire; the slubs are a 960 px `feTurbulence` tile (large, so no grid of blocks shows) |
+| `concrete` | a soft mottle and small pores on a cool grey | a 640 px `feTurbulence` tile of three layers (mottle, pores, tooth); a little fainter in dark |
+| `marble` | a cloudy body and soft veins, very low in contrast | a faint 960 px cloud tile, and smooth seeded vein curves with a halo (geometry, not cut noise, so it never bands) |
+
+The noise runs once per tile and the browser repeats it, so the cost does not grow with
+the page (a full-page filter would).
+
 ## Geometry presets
 
 <img src="../previews/backgrounds-geometry.webp" width="480" alt="The isometric preset behind a card">
 
-Seven presets draw regular patterns and structures. All of them take `tone`,
+Thirteen presets draw regular patterns and structures. The six after `waves` (`hexagons`, `circuit`, `graph-paper`, `checker`, `diagonal-checker`, `chevrons`) are drawn by `@nxgt/material` only: their CSS sits in `css-react/`, which `@nxgt/material-vue` does not have (it draws `gradient` and `grain`). All of them take `tone`,
 `intensity` and `animated`; the CSS is the one file per preset (or
 `backgrounds.css`).
 
@@ -122,13 +157,19 @@ import '@nxgt/material/backgrounds/isometric.css';
 | `low-poly` | SVG mosaic of 208 triangular facets lit by a raking light | yes | the facets breathe | `low-poly.css` |
 | `topography` | SVG contour lines (marching squares) of a seeded height field, every fifth curve heavier | yes | the map floats | `topography.css` |
 | `waves` | SVG: five stacked wavy bands along the bottom, each with a bright crest | no | the bands slide, each at its own speed | `waves.css` |
+| `hexagons` | SVG: a honeycomb (one `<pattern>` of cell edges, each edge drawn once) with a seeded tenth of its cells tinted in the tone's three colours | yes (which cells light up) | the tinted cells pulse, out of step | `hexagons.css` |
+| `circuit` | SVG: a printed circuit board, with chips, pins, traces that bend by 45 degrees and end in a pad, all on a 20 unit grid and never crossing | yes (chips and traces) | a bright dash runs along a dozen of the traces | `circuit.css` |
+| `graph-paper` | CSS soft squared grid in the tone's colour: thin pale lines every 20 px, every fifth (100 px) barely stronger, fading out toward the edges, with fine line doodles (set square, compass, ruler, plotted curve, arrow, star) drawn in an SVG near the edges | yes (the doodles) | the grid pans by one major cell | `graph-paper.css` |
+| `checker` | SVG: a fine checkerboard in two close tints of the tone, with no tint layer over it, fading out toward the edges; about one cell in eight near the edges carries a small motif shape | yes (which cells carry a motif) | the board and its motifs drift slowly | `checker.css` |
+| `diagonal-checker` | SVG: the fine checkerboard turned 45 degrees (its size follows the viewport), one `<pattern>` of a diamond and its corner triangles, fading out toward the edges, with the same motifs on some cells | yes (which cells carry a motif) | the field and its motifs drift slowly | `diagonal-checker.css` |
+| `chevrons` | SVG: four large, very pale chevron bands leaning across the frame, sized by the viewport, with small motif shapes along them | yes (where the motifs sit) | the bands drift slowly down and back (the motifs with them) | `chevrons.css` |
 
 The SVG ones are drawn by `@nxgt/material-core/backgrounds`
 (`buildBackgroundScene`; the CSS-only ones have no scene). Their colours are classes of the stylesheet, never a
 `style` attribute: `low-poly` colours each facet with two classes (`lp-t0..8`,
 the base colour, and `lp-s0..6`, its shade) that the stylesheet resolves in the
 tone's colours. At the defaults the heaviest geometry scene is `topography`, about 80 KB
-of path data; `low-poly` is about 20 KB (210 nodes).
+of path data; `low-poly` is about 20 KB (210 nodes); `circuit` about 9 KB (90 nodes), `hexagons` about 6 KB, `graph-paper` about 7 KB, `chevrons` about 16 KB, `checker` about 20 KB (91 nodes) and `diagonal-checker` about 23 KB (125 nodes); `dots` and `stripes` are under 1 KB.
 
 ## Motif presets
 
@@ -154,13 +195,21 @@ browser, and a new `seed` redraws it.
 
 | Field | Values | Default | Read by |
 | --- | --- | --- | --- |
-| `shapes` | any of `MOTIF_SHAPES`: `circle`, `ring`, `square`, `triangle`, `plus`, `line`, `arc`; none chosen draws circles | all of them | `shapes`, `confetti-grid`, `halftone`, `truchet`, `floating` (`halftone` takes `circle`, else the first of `square`, `ring`, `plus`; `truchet` draws diagonals for `line` without `arc`; `floating` turns `circle`/`triangle` into blobs, `ring`/`arc` into rings, `square` into squircles and ignores `plus`/`line`) |
-| `density` | `low`, `default`, `high`: how many items | `default` | all seven |
-| `size` | `small`, `mixed`, `large` | `mixed` | all seven |
-| `rotate` | `boolean`: turns the items | `false` | `shapes`, `confetti-grid`, `scatter-icons` (tilts up to 35 degrees) |
+| `shapes` | any of `MOTIF_SHAPES_ALL`: `circle`, `ring`, `square`, `triangle`, `plus`, `line`, `arc`, then `star`, `heart`, `hexagon`, `diamond`, `wave`, `zigzag`, `spiral`, then the Material 3 Expressive ones `m3-cookie-6`, `m3-cookie-9`, `m3-flower`, `m3-clover-4`, `m3-soft-burst`, `m3-sunny`, `m3-gem`, `m3-puffy`; none chosen draws circles | `MOTIF_SHAPES`: the first seven | `shapes`, `confetti-grid`, `halftone`, `truchet`, `floating` (`halftone` takes `circle`, else the first of `square`, `ring`, `plus`; `truchet` draws diagonals for `line` without `arc`; `floating` turns `circle`/`triangle` into blobs, `ring`/`arc` into rings, `square` into squircles and ignores `plus`/`line`; `shapes` and `confetti-grid` are the only presets that draw the added shapes, the others ignore them) |
+| `density` | `low`, `default`, `high`: how many items | `default` | all fifteen |
+| `size` | `small`, `mixed`, `large` | `mixed` | all fifteen |
+| `rotate` | `boolean`: turns the items | `false` | `shapes`, `confetti-grid`, `scatter-icons` (tilts up to 35 degrees), the illustrated scenes (up to 35 degrees instead of 8) |
 | `shapeFill` | `filled`, `outline`, `mixed` | `mixed` | `shapes`, `confetti-grid`, `halftone`, `floating` |
 | `opacitySpread` | `uniform`, `varied` | `varied` | all but `halftone` |
 
+`MOTIF_SHAPES` (the default) stays the first seven; pass `shapes: MOTIF_SHAPES_ALL`, or a hand-picked list such as `['star', 'm3-flower', 'wave']`, for the rest. In `shapes` and `confetti-grid` the 15 added shapes are drawn once per scene as a repeated pattern, so their tone, fill and (in `confetti-grid`) turn and size are fixed per shape; the first seven behave as before, item by item. The Storybook story `Backgrounds/Motif shapes/ShapeCatalogue` draws every shape filled and outlined.
+
+<img src="../previews/backgrounds-motif-shapes.webp" width="480" alt="The 22 motif shapes, each filled and outlined">
+
+```tsx
+<Background preset="shapes" motif={{ shapes: ['star', 'm3-flower', 'wave'] }} />
+```
+
 A field a preset does not read is ignored. `rotate` defaults to `false`: motifs stay upright
 unless you turn them on. A new `motif` object with the same values redraws nothing.
 
@@ -181,6 +230,35 @@ stops under `prefers-reduced-motion` or while the page is hidden. The drift is c
 CSS: `backgrounds/motifs.css` (shared by the seven) plus `shapes.css`, `confetti-grid.css`,
 `halftone.css`, `truchet.css`, `constellation.css`, `floating.css` and `scatter-icons.css` (the last two share `drift.css`); each preset's file imports `motifs.css`, so one alone works. `constellation` is about 34 KB of markup at the defaults and 59 KB at `motif.density: 'high'`, `scatter-icons` 18 and 31 KB (438 elements), `floating` under 8 KB.
 
+### Illustrated scenes
+
+<img src="../previews/backgrounds-illustrated-scenes.webp" width="480" alt="An illustrated scene behind a card">
+
+`school`, `night-sky`, `bubbles`, `leaves`, `science`, `music`, `travel` and `sport` are the motif family's
+themed line art: fine strokes (round caps, about 1.5 px at 1440 px wide) of one theme each, drawn in the tone's
+three colours, seeded so the placement never tiles. They are thicker with drawings toward the edges and calm
+around the content: the drawings thin out and fade toward the middle of the frame, which a mask keeps nearly empty
+for your content. They follow `tone`, `intensity` (the stroke opacity, with `vivid` capped at the default so body text stays readable) and the theme, and read `density`, `size`,
+`opacitySpread` and `rotate` from `motif`: a drawing is tilted up to 8 degrees, up to 35 with `rotate`. They are still
+by default.
+
+| Preset | Draws | With `animated` |
+| --- | --- | --- |
+| `school` | pencils, open books, rulers, a graduation cap, notebooks, set squares, a magnifier, an apple | still |
+| `night-sky` | a crescent moon, stars, clouds, a ringed planet, shooting stars, constellations | the stars twinkle (14 to 24 s) |
+| `bubbles` | soap bubbles with a glint, drops, ripples | the bubbles rise and sink back (14 to 24 s a leg) |
+| `leaves` | leaves, a fern, an acorn | the leaves sway (14 to 24 s a leg) |
+| `science` | flasks, an atom, a bulb, a test tube, a molecule, a graph | still |
+| `music` | notes, a treble clef, a staff, a drum, a metronome, headphones, a record | still |
+| `travel` | a paper plane, a pin, a suitcase, a globe, mountains, a sun, a balloon, a camera, a compass | still |
+| `sport` | balls, a racket, a trophy, a dumbbell, a medal, a stopwatch, a flag, a target | still |
+
+Each is about 14 to 16 KB of markup at the defaults and 24 to 28 KB at `density: 'high'`. The motion is
+classes (a pace `p1..p3`, a delay `l1..l4`), so it needs no inline style under a strict CSP, and it stops under
+`prefers-reduced-motion` or while the page is hidden. CSS: `backgrounds/illustrated.css` (shared, imported by each
+preset's file) plus `school.css`, `night-sky.css`, `bubbles.css`, `leaves.css`, `science.css`, `music.css`,
+`travel.css` and `sport.css`; one alone works. React only: `@nxgt/material-vue` does not draw them.
+
 ## Dark mode
 
 In dark the drawn colours are lifted to a lightness floor: the dark `--primary` is as dim as the light one, which made the
@@ -218,6 +296,27 @@ you can select on:
 The gradient ends on `--nxgt-bg-cp`, not `--nxgt-bg-c2`: to recolour it, set
 `--nxgt-bg-cp` too.
 
+## 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"]`:
+
+```css
+[data-slot="activity-layout"] {
+  --nxgt-bg-blob-1: var(--tint-1);
+  --nxgt-bg-blob-2: var(--tint-2);
+  --nxgt-bg-blob-3: var(--tint-3);
+}
+```
+
+Do not override the internals: `[data-layer="blob-1"] { background: var(--tint-1) }`
+paints a solid `background-color`, and axe, which ignores the blur filter,
+reads each blob as an opaque square (see
+[color-contrast fails over the background blobs on phone](../troubleshooting.md#color-contrast-fails-over-the-background-blobs-on-phone)).
+The variables paint through `background-image`, which axe reports as "needs review" at worst.
+
 ## Stylesheets
 
 `styles.css` carries the base, the gradient and the motion rules. Everything
@@ -228,7 +327,7 @@ else is opt-in, because CSS cannot be tree-shaken. `animated` on the
 ```css
 @import "@nxgt/material/backgrounds.css";            /* every opt-in file */
 /* or just the one you use: */
-@import "@nxgt/material/backgrounds/aurora.css";     /* a preset file, named after the preset (aurora.css, low-poly.css, scatter-icons.css…) */
+@import "@nxgt/material/backgrounds/aurora.css";     /* a preset file, named after the preset (aurora.css, low-poly.css, hexagons.css, scatter-icons.css…) */
 @import "@nxgt/material/backgrounds/grain.css";      /* the grain overlay, over any preset */
 @import "@nxgt/material/backgrounds/halftone.css";   /* a motif preset (brings motifs.css) */
 @import "@nxgt/material/backgrounds/floating.css";   /* brings motifs.css and drift.css */

package/docs/roadmap.md

@@ -185,10 +185,6 @@ version they shipped in, and planned entries may name the major they target.
   it. Needs a spike first: sonner pauses its own timer on hover and focus and
   does not expose the time left, so the bar would run beside it.
 
-- **`Background` blobs in a tone's colour** — the background presets drawing
-  their blobs from the tone channel, so an app tone colours them. Not
-  decided yet.
-
 - **`CountryField` single mode takes only the field's own props** —
   `CountryFieldProps` narrows to what single mode reads (`label`,
   `helperText`, `error`, `required`, `disabled`, `name`, `id`, `className`,
@@ -274,6 +270,22 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **44 `Background` presets, and 22 motif shapes** — `Background` from
+  `@nxgt/material/backgrounds` draws six light presets (`rays`, `halo`,
+  `plasma`, `glass`, `ripples`, `blobs`), six geometry presets (`hexagons`,
+  `circuit`, `graph-paper`, `checker`, `diagonal-checker`, `chevrons`), four
+  textures discreet enough under body text (`paper`, `linen`, `concrete`,
+  `marble`) and eight illustrated line-art scenes (`school`, `night-sky`,
+  `bubbles`, `leaves`, `science`, `music`, `travel`, `sport`), beside the
+  existing ones. The motif shapes grow from seven to 22 (`MOTIF_SHAPES_ALL`:
+  `star`, `heart`, `hexagon`, `diamond`, `wave`, `zigzag`, `spiral` and eight
+  Material 3 Expressive shapes such as `m3-flower`); the default stays the
+  first seven, so existing backgrounds draw as before. The textures and the
+  scenes cap `vivid` at the default intensity so body text stays readable.
+  Every preset follows `tone`, `intensity` and the theme, is seeded where
+  random, and moves only with `animated`. React only. 3.4.0.
+  ([Backgrounds guide](guides/backgrounds.md))
+
 - **Tailwind 4 animation API** — `animate-*` classes in `styles.css`, pure CSS
   and completed by Tailwind IntelliSense, with the Material 3 Expressive
   springs and durations by default: entrances and exits (fade, slide, scale,

package/docs/troubleshooting.md

@@ -57,6 +57,7 @@ words in your error.
 - [A form's fields no longer scroll in their own box after upgrading](#a-forms-fields-no-longer-scroll-in-their-own-box-after-upgrading)
 - [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)
 - [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)
@@ -1232,6 +1233,27 @@ await page.addStyleTag({
 await expectAccessible(page);
 ```
 
+### `color-contrast` fails over the background blobs on phone
+
+**When:** axe reports `color-contrast` ("Element has insufficient color
+contrast", for example 4.08:1 against 4.5:1) on a button or a link at phone
+width, while the same control reads fine to the eye (about 4.95:1) and passes on
+desktop. Your stylesheet restyles the blobs: `[data-slot="activity-layout"] > [data-layer="blob-1"] { background: var(--tint-1) }`.
+**Why:** the blobs are 128 px boxes blurred with `filter: blur(64px)`. axe
+ignores `filter`, so a blob painted with a solid `background` is an opaque,
+full-strength square to it; on a phone the left-aligned content falls inside
+blob-1 and axe computes the contrast against that square, not the soft glow.
+**Fix:** use the variables, which paint through `background-image` (axe then
+reports "needs review", not a failure), and delete the `[data-layer]` rules:
+
+```css
+[data-slot="activity-layout"] {
+  --nxgt-bg-blob-1: var(--tint-1);
+  --nxgt-bg-blob-2: var(--tint-2);
+  --nxgt-bg-blob-3: var(--tint-3);
+}
+```
+
 ### 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.
@@ -6680,13 +6702,13 @@ How the presets work is in the [Backgrounds guide](guides/backgrounds.md).
 ### `Background: preset "<id>" is not available in this library yet; drawing "gradient".`
 
 **When:** in development (not when `NODE_ENV` is `production`), the first time a `Background` from `@nxgt/material/backgrounds` gets a `preset` that this library does not draw yet, or a typo from JavaScript. It is printed once per id.
-**Why:** `BACKGROUND_PRESETS` lists the twenty presets; this library draws the ones in `AVAILABLE_BACKGROUND_PRESETS`. Any other id draws the gradient.
+**Why:** `BACKGROUND_PRESETS` lists the 44 presets; this library draws the ones in `AVAILABLE_BACKGROUND_PRESETS`. Any other id draws the gradient.
 **Fix:** use an available preset:
 
 ```ts
 import { AVAILABLE_BACKGROUND_PRESETS } from '@nxgt/material/backgrounds';
 
-console.log(AVAILABLE_BACKGROUND_PRESETS); // all twenty ids: 'gradient', 'grain', 'mesh', 'aurora', …, 'scatter-icons'
+console.log(AVAILABLE_BACKGROUND_PRESETS); // all 44 ids: 'gradient', 'grain', 'mesh', 'aurora', …, 'sport'
 ```
 
 ### A preset `Background` looks bare, with no error

package/lib/backgrounds/backgrounds.css

@@ -1,5 +1,6 @@
 /* Every background preset's CSS, opt-in: `import "@nxgt/material/backgrounds.css"`
- * (the same file in @nxgt/material-vue). Not part of styles.css, which carries
+ * (Vue's copy imports only the shared `css/` presets; `css-react/` is React
+ * only). Not part of styles.css, which carries
  * only the base, the gradient and the motion `Background` (from /components)
  * needs. One preset alone: `@nxgt/material/backgrounds/<preset>.css`. */
 @import "./css/base.css";
@@ -20,6 +21,34 @@
 @import "./css/low-poly.css";
 @import "./css/topography.css";
 @import "./css/waves.css";
+/* geometry, React only (css-react/: not in scripts/shared-paths.ts, so no Vue copy) */
+@import "./css-react/hexagons.css";
+@import "./css-react/circuit.css";
+@import "./css-react/graph-paper.css";
+@import "./css-react/checker.css";
+@import "./css-react/diagonal-checker.css";
+@import "./css-react/chevrons.css";
+/* light, more (React only) */
+@import "./css-react/rays.css";
+@import "./css-react/halo.css";
+@import "./css-react/plasma.css";
+@import "./css-react/glass.css";
+@import "./css-react/ripples.css";
+@import "./css-react/blobs.css";
+/* textures (React only) */
+@import "./css-react/paper.css";
+@import "./css-react/linen.css";
+@import "./css-react/concrete.css";
+@import "./css-react/marble.css";
+/* illustrated scenes (React only) */
+@import "./css-react/school.css";
+@import "./css-react/night-sky.css";
+@import "./css-react/bubbles.css";
+@import "./css-react/leaves.css";
+@import "./css-react/science.css";
+@import "./css-react/music.css";
+@import "./css-react/travel.css";
+@import "./css-react/sport.css";
 /* motifs */
 @import "./css/motifs.css";
 @import "./css/shapes.css";

package/lib/backgrounds/css/gradient.css

@@ -1,7 +1,11 @@
 /* The `gradient` preset: the frame's tint and three blurred blobs, what
  * `Background` always looked like (a primary tint from 5% to 20%, blobs
  * going primary to secondary), now drawn from the tone's colours so it lifts
- * in dark. The layers are `aria-hidden` divs, see base.css. */
+ * in dark. The layers are `aria-hidden` divs, see base.css.
+ *
+ * Public API: `--nxgt-bg-blob-1..3` recolour a blob (any colour; unset keeps the
+ * tone's gradient). The blob is always painted with `background-image`, never a
+ * solid `background-color`, so axe cannot resolve it as an opaque square. */
 @layer components {
 	[data-background="gradient"] {
 		background-image: linear-gradient(
@@ -27,27 +31,36 @@
 		opacity: var(--nxgt-bg-blob);
 		background-image: linear-gradient(
 			to right in oklab,
-			var(--nxgt-bg-c1),
-			var(--nxgt-bg-cp)
+			var(--nxgt-bg-blob-colour, var(--nxgt-bg-c1)),
+			var(--nxgt-bg-blob-colour, var(--nxgt-bg-cp))
 		);
 	}
 	[data-background="gradient"] > [data-layer="blob-1"] {
+		--nxgt-bg-blob-colour: var(--nxgt-bg-blob-1);
 		bottom: 33.333333%;
 		width: 8rem;
 	}
 	[data-background="gradient"] > [data-layer="blob-2"] {
+		--nxgt-bg-blob-colour: var(--nxgt-bg-blob-2);
 		right: 0;
 		bottom: 0;
 		width: 8rem;
 		max-width: 28rem;
 	}
 	[data-background="gradient"] > [data-layer="blob-3"] {
+		--nxgt-bg-blob-colour: var(--nxgt-bg-blob-3);
 		right: 50%;
 		width: 10rem;
 		background-image: linear-gradient(
 			to right in oklab,
-			color-mix(in oklab, var(--nxgt-bg-c1) 60%, transparent),
-			color-mix(in oklab, var(--nxgt-bg-cp) 60%, transparent)
+			var(
+				--nxgt-bg-blob-colour,
+				color-mix(in oklab, var(--nxgt-bg-c1) 60%, transparent)
+			),
+			var(
+				--nxgt-bg-blob-colour,
+				color-mix(in oklab, var(--nxgt-bg-cp) 60%, transparent)
+			)
 		);
 	}
 }

package/lib/backgrounds/css-react/blobs.css

@@ -0,0 +1,65 @@
+/* The `blobs` preset: soft organic blobs in the tone's colours. A seeded SVG
+ * of smooth shapes in c1, c2 and c3 (`bl1..3`), slightly blurred, over a tint
+ * (`wash`). Blended with the page: it adds light in dark. Motion (opt-in,
+ * `animated`): each blob drifts at its own pace (`bd1..3`). React only:
+ * nothing in the shared `css/` folder. `--nxgt-bg-blob-1..3` recolour the blobs
+ * as they do the gradient's; unset, a blob keeps `--nxgt-bg-c1..c3`. */
+@import "../css/scene.css";
+
+@layer components {
+	[data-background="blobs"] {
+		isolation: isolate;
+	}
+	[data-background="blobs"] > [data-layer="wash"] {
+		position: absolute;
+		inset: 0;
+		background-image: linear-gradient(
+			200deg,
+			color-mix(in oklab, var(--nxgt-bg-c2) var(--nxgt-bg-a1), transparent),
+			transparent 70%
+		);
+	}
+	[data-background="blobs"] > [data-scene] > svg {
+		mix-blend-mode: var(--nxgt-bg-glow-blend);
+	}
+	[data-background="blobs"] > [data-scene] .bl {
+		fill-opacity: calc(var(--nxgt-bg-op) * 0.42);
+	}
+	[data-background="blobs"] > [data-scene] .bl1 {
+		fill: var(--nxgt-bg-blob-1, var(--nxgt-bg-c1));
+	}
+	[data-background="blobs"] > [data-scene] .bl2 {
+		fill: var(--nxgt-bg-blob-2, var(--nxgt-bg-c2));
+	}
+	[data-background="blobs"] > [data-scene] .bl3 {
+		fill: var(--nxgt-bg-blob-3, var(--nxgt-bg-c3));
+	}
+}
+
+@media (prefers-reduced-motion: no-preference) {
+	@keyframes nxgt-bg-blobs-drift {
+		from {
+			transform: translate(-30px, 18px);
+		}
+		to {
+			transform: translate(34px, -26px);
+		}
+	}
+
+	@layer components {
+		[data-background="blobs"][data-animated] > [data-scene] .bl-g {
+			animation: nxgt-bg-blobs-drift 19s ease-in-out infinite alternate
+				var(--nxgt-bg-play, running);
+		}
+		[data-background="blobs"][data-animated] > [data-scene] .bd1 {
+			animation-direction: alternate;
+		}
+		[data-background="blobs"][data-animated] > [data-scene] .bd2 {
+			animation-duration: 26s;
+			animation-direction: alternate-reverse;
+		}
+		[data-background="blobs"][data-animated] > [data-scene] .bd3 {
+			animation-duration: 33s;
+		}
+	}
+}

package/lib/backgrounds/css-react/bubbles.css

@@ -0,0 +1,41 @@
+/* The `bubbles` preset: line drawings of one theme (see illustrated.css).
+ * Motion (opt-in, `animated`): a bubble rises and sinks back, 14 to 24 s a leg. The builder sets
+ * the pace (`p1..p3`) and the delay (`l1..l4`) as classes, so the markup holds
+ * no inline style. */
+@import "./illustrated.css";
+
+@media (prefers-reduced-motion: no-preference) {
+	@keyframes nxgt-bg-bubbles-up {
+		to {
+			translate: 0 -46px;
+		}
+	}
+
+	@layer components {
+		[data-background="bubbles"][data-animated] > [data-scene] .up {
+			animation: nxgt-bg-bubbles-up 14s ease-in-out infinite alternate
+				var(--nxgt-bg-play, running);
+		}
+		[data-background="bubbles"][data-animated] > [data-scene] .p1 {
+			animation-duration: 14s;
+		}
+		[data-background="bubbles"][data-animated] > [data-scene] .p2 {
+			animation-duration: 19s;
+		}
+		[data-background="bubbles"][data-animated] > [data-scene] .p3 {
+			animation-duration: 24s;
+		}
+		[data-background="bubbles"][data-animated] > [data-scene] .l1 {
+			animation-delay: 0s;
+		}
+		[data-background="bubbles"][data-animated] > [data-scene] .l2 {
+			animation-delay: -3s;
+		}
+		[data-background="bubbles"][data-animated] > [data-scene] .l3 {
+			animation-delay: -7s;
+		}
+		[data-background="bubbles"][data-animated] > [data-scene] .l4 {
+			animation-delay: -11s;
+		}
+	}
+}

package/lib/backgrounds/css-react/checker.css

@@ -0,0 +1,47 @@
+/* The `checker` preset: a fine checkerboard of 24 unit cells in two tints of
+ * the tone that sit close together, fading out toward the edges (stronger in
+ * dark, as the isometric: `--nxgt-bg-iso-k`), with a seeded eighth of the cells
+ * near the edges carrying a small tonal motif. One layer, the SVG scene
+ * (`ck-a`, `ck-b` the cells, `ck-m` the motifs), with nothing over it; the
+ * scene covers the background, so the cells follow the viewport. For the
+ * diagonal one, see `diagonal-checker.css`. React only: nothing in the shared
+ * `css/` folder. */
+@import "../css/scene.css";
+
+@layer components {
+	[data-background="checker"] > [data-scene] .fade-1 {
+		stop-color: white;
+	}
+	[data-background="checker"] > [data-scene] .fade-0 {
+		stop-color: black;
+	}
+	[data-background="checker"] > [data-scene] .ck-a {
+		fill: var(--nxgt-bg-c1);
+		fill-opacity: calc(var(--nxgt-bg-op) * 0.14 * var(--nxgt-bg-iso-k));
+	}
+	[data-background="checker"] > [data-scene] .ck-b {
+		fill: var(--nxgt-bg-c2);
+		fill-opacity: calc(var(--nxgt-bg-op) * 0.07 * var(--nxgt-bg-iso-k));
+	}
+	[data-background="checker"] > [data-scene] .ck-m,
+	[data-background="checker"] > [data-scene] .ck-p {
+		color: var(--nxgt-bg-c1);
+		stroke-opacity: 0.85;
+		fill-opacity: calc(0.4 * var(--nxgt-bg-iso-k));
+	}
+}
+
+@media (prefers-reduced-motion: no-preference) {
+	@keyframes nxgt-bg-checker-drift {
+		to {
+			transform: translate(24px, 24px);
+		}
+	}
+
+	@layer components {
+		[data-background="checker"][data-animated] > [data-scene] .ck-drift {
+			animation: nxgt-bg-checker-drift 22s ease-in-out infinite alternate
+				var(--nxgt-bg-play, running);
+		}
+	}
+}