@nxgt/material 3.8.0 → 3.9.0

package/dist/{use-theme-Cd-aiDJo.js → use-theme-DMcyJ52N.js}

@@ -1,6 +1,6 @@
 import { t as e } from "./use-ssr-media-query-C6M5m8sf.js";
 import { i as t, n, o as r, r as i, s as a, t as o } from "./theme-store-CSl51uNH.js";
-import { a as s } from "./theme-context-BagPvRcz.js";
+import { a as s } from "./theme-context-Cofk6vgs.js";
 import { useCallback as c, useEffect as l, useState as u, useSyncExternalStore as d } from "react";
 import { PRESET_SCHEMES as f } from "@nxgt/material-core/theme/boot";
 //#region lib/hooks/use-is-client.ts

package/docs/README.md

@@ -23,6 +23,8 @@ detail: every option, the second example, and the traps.
 | [Streaming (HLS)](guides/media-streaming.md) | You play `.m3u8` streams in `MediaPlayer` with `@nxgt/material/media-hls` |
 | [Maps](guides/maps.md) | You render Leaflet maps or a location field with `@nxgt/material/map` |
 | [Drawing](guides/drawing.md) | You draw diagrams, badges or illustrations from code with `@nxgt/material/draw`: scenes and JSX primitives, roles and tones, a strict CSP, accessibility and events, sketch, animation, PNG, PDF and e-mail |
+| [Illustrations](guides/illustrations.md) | You draw state illustrations from your Font Awesome sprites with `@nxgt/material/illustrations`: the twelve scenes and the health and education sets, `EmptyState` / `ErrorState` / `DataTable` with `illustration`, `IllustrationDefaults` for an app, sizes, motion and CSP |
+| [Icon motifs](guides/icon-motifs.md) | You use icon backgrounds, celestial skies, illustrations or a theme that names a motif: serving your own Font Awesome sprites (the package ships none), `IconSpritesProvider`, `icons` / `iconStyle` / `iconMotif`, `sky`, the health and education sets, Free fallbacks for Pro-only names |
 | [Backgrounds](guides/backgrounds.md) | You want a gradient or patterned backdrop: tones, intensity, the opt-in `backgrounds.css`, custom colours, motion and CSP |
 | [SSR](guides/ssr.md) | Your app renders on a server and bundles this package |
 | [Content Security Policy](guides/csp.md) | Your app sends a strict CSP: the directives to use, the components that still inject a `<style>`, the zod and KaTeX settings, self-hosting a font, the per-request nonce |

package/docs/components/README.md

@@ -6,6 +6,8 @@ example that compiles and the options that change behaviour. The same twelve
 categories (after Foundations, which is React only) are the README's catalogue, the Storybook sidebar and
 `@nxgt/material-vue`'s pages.
 
+Icons in the previews: Font Awesome Free 7.3.1 by Fonticons, Inc., CC BY 4.0 — https://fontawesome.com/license/free
+
 ## [Foundations](foundations.md)
 
 What the stylesheet gives any element, not a component: the animation classes (`animate-fade-in-up`, `animate-duration-300`…), pure CSS for Tailwind 4. React only. 1 entry.

package/docs/components/data-table-filter-and-lists.md

@@ -109,6 +109,7 @@ table enables, for typing your own column defs.
 | `density` | `'comfortable' \| 'compact'` | `'comfortable'` | `compact` tightens the cell padding, the row and header heights and the gap between rows, the selection column included; it is the table's `data-density` attribute, styled with classes (no inline style). The toolbar band and the empty state keep their size; the print variant is unchanged |
 | `empty` | `ReactNode \| ({ filtered }) => ReactNode` | a compact `EmptyState`: "No data available", or "No results" when filtered | content of the empty row, spanning every visible column |
 | `emptyFiltered` | `ReactNode \| ({ filtered }) => ReactNode` | none (falls back to `empty`, then the default) | content of the empty row when the table is filtered (rows exist but the filters hide every one, or `filtered`); wins over `empty` then |
+| `emptyIllustration` | `IllustrationScene \| true` | none | draws the default empty state with an icon illustration from your Font Awesome sprites: a scene id (`'empty'`, `'no-results'`…) for both states, `true` for `empty` (`no-results` when filtered); never replaces your own `empty` or `emptyFiltered` ([Illustrations](../guides/illustrations.md#use-them-in-the-states)) |
 | `filtered` | `boolean` | what the table sees | whether the rows are filtered, overriding the table's own reading; for `manual` data, which cannot tell: `true` when the page's query has a search or a filter. It picks `emptyFiltered` and the "No results" announcement on an empty page ([an empty server page](#an-empty-server-page)) |
 | `manual` | `boolean` | `false` | `data` is one server page: no client filtering, sorting or paging; the footer is the server footer ([server-side data](#server-side-data)) |
 | `sorting` / `onSortingChange` | `SortingState` / `(sorting) => void` | held inside | controlled sorting; the callback gets the new state, not an updater, and is not called for an update that resolves to the current value |

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

@@ -320,7 +320,7 @@ import { Button, EmptyState } from '@nxgt/material/components';
 | --- | --- | --- | --- |
 | `kind` | `'empty' \| 'search' \| 'not-found' \| 'unauthorized'` | `'empty'` | illustration, icon, title and description |
 | `size` | `'default' \| 'compact' \| 'inline'` | `'default'` | `compact` swaps the illustration for a small icon and tightens the spacing; `inline` lays out one row (the icon in a 32px round well, the text beside it, the action at the end), for a list of options |
-| `illustration` | `ReactNode \| false` | the kind's | replaces the illustration; `false` shows no media |
+| `illustration` | `ReactNode \| false \| 'empty' \| 'no-results' \| 'not-found' \| 'error' \| 'offline' \| 'success' \| 'welcome' \| true` | the kind's | replaces the illustration; `false` shows no media; a scene id, or `true` for the kind's scene, draws an icon illustration from your Font Awesome sprites ([Illustrations](../guides/illustrations.md)) |
 | `icon` | `ReactNode` | the kind's | replaces the icon |
 | `title` / `description` | `ReactNode` | the kind's (translated) | replace the kind's text; see below |
 | `headingLevel` | `2`–`6` | — | the title becomes a heading of that level (`h2`…`h6`); without it, it is a plain `div`, as before |
@@ -355,7 +355,7 @@ import { ErrorState } from '@nxgt/material/components';
 | `kind` | `'generic' \| 'offline' \| 'maintenance'` | `'generic'` | illustration, title and description (`material.error-state.<kind>.*`) |
 | `size` | `'default' \| 'compact'` | `'default'` | compact swaps the illustration for an icon |
 | `title` / `description` | `ReactNode` | the kind's (translated) | replace the text; a custom `title` drops the default description |
-| `illustration` / `icon` | media | the built-in illustration | replace the media; `illustration={false}` hides it |
+| `illustration` / `icon` | media | the built-in illustration | replace the media; `illustration={false}` hides it; a scene id or `true` draws an icon illustration ([Illustrations](../guides/illustrations.md)) |
 | `error` | `unknown` | none | the thrown value; its name, message and `cause` chain go in the details |
 | `showDetails` | `boolean` | `true` when `error` is set | `false` hides the details |
 | `details` | `ReactNode \| (details: ErrorDetail[]) => ReactNode` | the collapsed details | replaces them (Vue's `#details` slot); `details={null}` removes them; a function gets the described error (name, message, then each cause), or `[]` without an `error` or with `showDetails={false}` |

package/docs/components/foundations.md

@@ -165,7 +165,7 @@ The Storybook page *Foundations / Animations* shows every class with controls.
 
 A radiogroup of tiles, one per theme. Each tile is a zone of its own theme, so its
 three swatches (primary, secondary, tertiary) and its mini background (the theme's
-tone and preset's texture, drawn by CSS) are that theme's colours in the page's
+tone and preset's texture, drawn by CSS; a theme with an `icons` background adds its first four icons as sprite `<use>`s from your sprite base, and keeps the plain wash when they are not served) are that theme's colours in the page's
 mode. The light / dark / system control sits beneath. The arrow keys move the
 choice; the selected tile is tinted, with a start bar and its name in primary text.
 
@@ -191,7 +191,7 @@ locale; the capitalised name when there is none). The group is named by
 `material.theme-picker.label` and the mode control by `material.theme-picker.mode`; the mode control is `ThemeToggle`, whose Light, Dark and System names keep their own keys.
 It writes no inline style, so a strict CSP needs nothing. Its tiles are styled by
 an opt-in stylesheet, `@import "@nxgt/material/theme-picker.css";` after
-`styles.css` (about 3.3 KB gzipped, not part of `styles.css`, so an app without
+`styles.css` (about 3.8 KB gzipped, not part of `styles.css`, so an app without
 the picker pays nothing); the app also imports each theme's stylesheet
 (`@nxgt/material/themes/<name>.css`), as for any theme.
 

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

@@ -742,7 +742,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`, `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`, `moon`.
+`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`, `moon`; sky: `eclipse`, `meteor-shower`, `ringed-planet`, `northern-lights`, or the `sky` prop to lay the moon or one of them over any preset.
 
 **Storybook:** `Navigation & layout/Background` · **Vue:** `Background`
 

package/docs/components/primitives.md

@@ -428,13 +428,26 @@ import { Icon } from '@nxgt/material/components';
 | --- | --- | --- | --- |
 | `name` | `IconName` | — (required) | the Font Awesome icon |
 | `type` | `IconStyle \| 'semibold'` | `'duotone'` | the sprite sheet: `solid`, `regular`, `light`, `thin`, … |
-| `family` | `IconFamily` | `'classic'` | a non-classic family reads `<family>-<type>.svg` |
+| `family` | `IconFamily` | `'classic'` | a non-classic family reads `<family>-<type>.svg` (the duotone family in `solid` reads `duotone.svg`) |
 | `aria-label` | `string` | `"Icon <name>"` | the accessible name; pass `aria-hidden` for a decorative icon. Inside a named `IconButton`, `InputGroupButton` or `IconLinkButton` the default is dropped and the icon is `aria-hidden`, unless it has its own `aria-label` or `aria-labelledby` |
 
 The sprites are **not** shipped: serve them from
 `/assets/icons/sprites/<style>.svg` on your own origin. A missing sheet renders
 nothing, with no error — see [Icons in Getting started](../getting-started.md#icons).
 
+Serve them from another root-relative path with `IconSpritesProvider`; every
+`Icon` below it uses that base (a URL, `//host`, `..` or `:` throws an
+`IconRefError`), and `useSpriteBase()` reads it:
+
+```tsx
+import { Icon, IconSpritesProvider } from '@nxgt/material/components';
+
+<IconSpritesProvider base="/static/icons/">
+	<Icon name="bell" type="solid" />
+</IconSpritesProvider>;
+// → /static/icons/solid.svg#bell
+```
+
 **Storybook:** `Primitives/Icon` · **Vue:** `Icon`
 
 ---

package/docs/getting-started.md

@@ -101,7 +101,7 @@ import { Icon } from '@nxgt/material/components';
 
 export function Atom() {
   return <Icon name="atom" type="duotone" />;
-  // → <svg role="img" aria-label="Icon atom"><use xlink:href="/assets/icons/sprites/duotone.svg#atom"/></svg>
+  // → <svg role="img" aria-label="Icon atom"><use href="/assets/icons/sprites/duotone.svg#atom"/></svg>
 }
 ```
 
@@ -122,6 +122,11 @@ build cannot leak them into the tarball.
 A missing sheet renders an empty box: no error, no fallback. Open the sprite
 URL in the browser when an icon is blank.
 
+Serve them from another root-relative path with `IconSpritesProvider`:
+`<IconSpritesProvider base="/static/icons/">` around the app (or a part of it)
+makes every `Icon` below it read `/static/icons/<style>.svg`. A URL, `//host`,
+`..` or `:` throws an `IconRefError`. The same base serves the icon backgrounds, illustrations and theme tiles ([icon motifs](guides/icon-motifs.md)).
+
 Many components also use `lucide-react` icons internally; those are bundled
 and need nothing.
 
@@ -139,7 +144,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` (45 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` (50 ids, `AVAILABLE_BACKGROUND_PRESETS`), `tone`, `intensity`, `animated`, `grain`, `seed`, `fill`, `sky`, `motif` (`shapes`, `density`, `size`, `rotate`, `shapeFill`, `opacitySpread`) and, for `preset="icons"`, `icons`, `iconStyle` and `iconMotif`), 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/app-shell.md

@@ -521,7 +521,7 @@ to know the theme on the server (a cookie, passed to `defaultTheme`).
 ## Use a background preset behind the shell
 
 The shell draws the gradient with three blurred blobs behind its frame. To use
-one of the 45 presets of `@nxgt/material/backgrounds` instead, pass it as
+one of the 50 presets of `@nxgt/material/backgrounds` instead, pass it as
 `backdrop`:
 
 ```tsx

package/docs/guides/backgrounds.md

@@ -45,18 +45,23 @@ import '@nxgt/material/backgrounds.css';
 
 | Prop | Values | Default |
 | --- | --- | --- |
-| `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`, `moon` (`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`, `moon`, `eclipse`, `meteor-shower`, `ringed-planet`, `northern-lights`, `icons` (`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` |
 | `seed` | `number`: moves a seeded preset's geometry and the grain | `0` |
 | `motif` | a `MotifOptions` object (`shapes`, `density`, `size`, `rotate`, `shapeFill`, `opacitySpread`), see [Motif presets](#motif-presets) | all fields optional |
-| `moon` | a `MoonOptions` object for `preset="moon"`: `position` (`{ x, y }`, fractions of the container), `phase`, `halo`; see [Moon](#moon) | `{ position: { x: 0.8, y: 0.2 }, phase: 0.78, halo: 2.6 }` |
+| `moon` | a `MoonOptions` object for `preset="moon"`, the celestial presets and a `sky`: `position` (`{ x, y }`, fractions of the container), `phase`, `halo`; see [Moon](#moon) | `{ position: { x: 0.8, y: 0.2 }, phase: 0.78, halo: 2.6 }` |
+| `sky` | `'moon'`, `'eclipse'`, `'meteor-shower'`, `'ringed-planet'` or `'northern-lights'`: a second scene drawn over any preset, before the grain; see [Celestial presets and the sky overlay](#celestial-presets-and-the-sky-overlay) | none |
+| `icons` | for `preset="icons"`: a pack name (`school`, `health`, `finance`, `travel`, `nature`, `tech`) or up to 48 icon names and `{ name, family?, type? }` references; see [Icons](#icons) | the `school` pack |
+| `iconStyle` | for `preset="icons"`: one style (`{ family?, type? }` or a sprite name such as `'sharp-light'`) or a list of at most 8, one drawn per icon | duotone thin |
+| `iconMotif` | for `preset="icons"`: `layout` (`scatter`, `grid`, `constellation`, `drift`), `sizeRange`, `rotation`, `duotone` (`opacity` or `tones`), `secondaryOpacity` (0.4 or, with `tones`, 0.85 unless set), `calm` | `{ layout: 'scatter', duotone: 'opacity', calm: true }` (`secondaryOpacity` unset: 0.4, or 0.85 with `tones`) |
 | `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 45 presets with their family and
-kind; `AVAILABLE_BACKGROUND_PRESETS` lists the ids this library draws (all
-45; `SHIPPED_BACKGROUND_PRESETS` is the common floor every library draws).
+
+`BACKGROUND_PRESETS` is the table of all 50 presets with their family and
+kind; `AVAILABLE_BACKGROUND_PRESETS` lists the ids this library draws (all 50;
+`SHIPPED_BACKGROUND_PRESETS` is the common floor every library draws).
 
 <img src="../previews/backgrounds-matrix.webp" width="640" alt="The presets, each in a card with its name">
 
@@ -271,6 +276,87 @@ follows `intensity` (`subtle` is a faint watermark, `vivid` the strongest; the s
 `scene.css`); one alone works. React only: `@nxgt/material-vue` does not draw it. The moon's `position`, `phase` and
 `halo` come from the `moon` prop (`<Background preset="moon" moon={{ position: { x: 0.2, y: 0.25 }, phase: 0.6 }} />`).
 
+## Celestial presets and the sky overlay
+
+Four presets draw a sky of their own, each discreet like `moon`: thin outlines and soft halos in the tone's three
+colours, a few stars and a clear middle for the content.
+
+| Preset | Draws | `moon.phase` is | Default `moon.position` |
+| --- | --- | --- | --- |
+| `eclipse` | a dark moon covering a disc, a corona of fine rays and a ring | how much of the disc the moon covers | `0.8, 0.2` |
+| `meteor-shower` | streaks falling down and to the left, among a few stars | the direction of the fall (0.2 steep, 0.9 shallow) | `0.7, 0.18` (the radiant) |
+| `ringed-planet` | a planet with a ring that passes behind it, and a small moon | the ring's tilt | `0.78, 0.22` |
+| `northern-lights` | three soft ribbons across the top | the ribbons' height | `0.5, 0.2` (only `y` applies) |
+
+```tsx
+import '@nxgt/material/backgrounds/celestial.css'; // or backgrounds.css
+import { Background } from '@nxgt/material/backgrounds';
+
+<Background preset="ringed-planet" tone="mixed" moon={{ position: { x: 0.2, y: 0.25 }, phase: 0.6 }} />
+```
+
+They read `motif.size` (the body at 0.7, 1 or 1.4 times) and `motif.density` (5, 9 or 15 stars; 4, 6 or 8 meteors),
+and `seed` places the stars. The body is halved (the planet scaled to two thirds) in a container under 640 px
+wide so it stays whole in its corner. In light the scene is multiplied into the page, a faint watermark; in dark
+it adds light and the body is silver. `intensity` fades it (`subtle` is the calmest, and the right pick for
+`northern-lights`, whose ribbons are the strongest of the four).
+
+The builders live in `@nxgt/material-core/backgrounds/celestial`, a separate subpath, and `Background` loads it
+on demand: the first paint (and the server's HTML) holds the layers, with the SVG filling in once the chunk has
+loaded, so the scene never causes a hydration mismatch and an app that draws none never downloads it.
+
+### The `sky` prop
+
+`sky` draws the moon or a celestial preset over *any* preset, after its layers and before the grain, with its
+own ids (`<id>-sky-…`), so the two never clash. It reads the base's `motif` but not its `moon` options (those stay with the
+preset): the sky's body sits at its own default place, mirrored to the other side when the preset's moon or
+celestial body would land within a fifth of the width, and its stars follow `seed + 1`.
+
+```tsx
+<Background preset="school" tone="mixed" sky="northern-lights" grain />
+```
+
+A theme can name it too (`background: { preset: 'school', sky: 'meteor-shower' }`): a `sky` you pass wins over the
+theme's. With `animated` the stars twinkle (8 s a leg), a meteor glides and fades (10 s) and a ribbon drifts
+(14 s); nothing moves under `prefers-reduced-motion` or while the page is hidden. CSS: `backgrounds/celestial.css`
+(it imports `scene.css`) styles all four presets and the overlay; React only, `@nxgt/material-vue` does not draw
+them. The theme picker draws a small tile for a theme with a celestial preset.
+
+## Icons
+
+`preset="icons"` scatters Font Awesome icons over a faint wash. The library ships **no icon artwork**: each icon is a
+`<use>` of a sprite file your app serves (`/assets/icons/sprites/` by default; `IconSpritesProvider base="/static/icons/"`
+moves it, as for `Icon`). Font Awesome Pro is licensed to you, not to this package. The [icon motifs guide](icon-motifs.md) puts icons, skies, illustrations and themes together.
+
+```tsx
+import '@nxgt/material/backgrounds/icons.css'; // or backgrounds.css
+import { Background } from '@nxgt/material/backgrounds';
+
+<Background
+	preset="icons"
+	tone="mixed"
+	icons="health" // a pack, or ['rocket', 'star', { name: 'bolt', family: 'sharp', type: 'solid' }]
+	iconStyle={['duotone-thin', 'duotone-light']} // one style or up to 8; an icon's own family/type wins
+	iconMotif={{ layout: 'constellation', duotone: 'tones' }}
+	animated
+/>;
+```
+
+- The icons come from a builder in its own chunk, loaded on demand (`@nxgt/material-core/backgrounds/icons`), so the
+  preset registry does not grow. A streaming server render has the icons in the first HTML; with `renderToString` the
+  scene layer is empty until the chunk has loaded, on the server and on the client alike (no hydration mismatch).
+- Icons that cannot be drawn (an unknown pack, a name that is not an icon, more than 48, an unknown style) draw
+  `scatter-icons`, with a warning outside production.
+- Colours: the primary layer takes the tone's colours; the second layer of a duotone icon is the same colour at
+  `secondaryOpacity` (no default of its own: 0.4 with `duotone: 'opacity'`, 0.85 with `'tones'`, where the second layer takes the next tone; a value you set, 0.4 included, is used in both). Flat styles (`solid`,
+  `regular`) take the tone through `currentColor`. A name missing from the sprite of the style drawn shows
+  nothing, so keep a list of styles to ones that share your names. The default style needs `duotone-thin.svg` at the
+  sprite base (see the sprite 404 entry in [troubleshooting](../troubleshooting.md)).
+- `animated` drifts each icon a few pixels on `translate` (never under `prefers-reduced-motion`, paused while hidden).
+- In an `ActivityLayout` the keep-inside pass hides an icon that would cross the layer's edge or the header band.
+- A theme can name the preset with `background: { preset: 'icons', icons, iconStyle, iconMotif, sky }`; the props win. The theme picker draws the first four icons in the theme's tile ([themes](themes.md#icon-motifs-in-a-theme)).
+- CSS: `backgrounds/icons.css` (or `backgrounds.css`). React only: `@nxgt/material-vue` does not draw it.
+
 ## 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
@@ -311,7 +397,7 @@ The gradient ends on `--nxgt-bg-cp`, not `--nxgt-bg-c2`: to recolour it, set
 ## Defaults from the theme
 
 The `Background` of `@nxgt/material/backgrounds` takes what you leave out
-(`preset`, `tone`, `intensity`, `seed`, `motif`, `grain`, `animated`) from the
+(`preset`, `tone`, `intensity`, `seed`, `motif`, `moon`, `sky`, `grain`, `animated`) from the
 nearest theme (`NxgtThemeProvider` or an `NxgtTheme` zone, see
 [the provider and zones](./theming.md#the-provider-and-zones)), then from the
 defaults above. A prop you pass always wins; the others still come from the theme.
@@ -371,6 +457,7 @@ else is opt-in, because CSS cannot be tree-shaken. `animated` on the
 /* or just the one you use: */
 @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/celestial.css";  /* eclipse, meteor-shower, ringed-planet, northern-lights, and the `sky` overlay */
 @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/guides/icon-motifs.md

@@ -0,0 +1,198 @@
+# Icon motifs, celestial skies and illustrations
+
+Since 3.9 the backgrounds, the state illustrations and the themes can draw
+**Font Awesome icons** and a **sky**. This page ties the pieces together; each
+has its own reference ([backgrounds](backgrounds.md), [illustrations](illustrations.md),
+[themes](themes.md)). All of it is React only: `@nxgt/material-vue` does not
+draw it yet.
+
+## Serve your own sprites first
+
+**This package ships no icon artwork.** Every icon is a `<use>` of a sprite
+sheet your app serves from its own origin. Font Awesome Pro is licensed to you,
+not to this library, so it cannot be redistributed inside it: the tarball
+excludes the sheets and a repository check fails if one slips in. Font Awesome
+Free works the same way.
+
+| You have | Serve | Use |
+| --- | --- | --- |
+| the Pro 7.3 pack | one sheet per style you draw, in `public/assets/icons/sprites/`: `duotone-thin.svg` (the default look), `duotone.svg`, `solid.svg`, `sharp-solid.svg`… A non-classic family is `<family>-<style>.svg` | the defaults |
+| Font Awesome Free | `solid.svg`, `regular.svg` and `brands.svg` from `@fortawesome/fontawesome-free/sprites/`, copied to the same folder | `iconStyle="solid"` (and `iconStyle="solid"` on an `Illustration`) |
+
+The Free icons are CC BY 4.0: credit Font Awesome where you show them (the
+previews below are drawn with the Free `solid` sheet, Font Awesome Free 7.3.1,
+[CC BY 4.0](https://fontawesome.com/license/free)).
+
+Serve the sheets from another root-relative path with `IconSpritesProvider`, once,
+at the root. `Icon`, `Background`, `Illustration` and the theme picker all read it:
+
+```tsx
+import { IconSpritesProvider } from '@nxgt/material/components';
+
+<IconSpritesProvider base="/static/icons/">
+  <App />
+</IconSpritesProvider>
+```
+
+A URL, `//host`, `..` or `:` in `base` throws an `IconRefError` (code `base`):
+sprites load from your own origin only, so a strict CSP needs nothing more than
+`img-src 'self'`. A sheet that is not served draws nothing, with no error: open
+the sprite URL in the browser when icons are blank (see
+[troubleshooting](../troubleshooting.md#a-background-an-illustration-or-a-theme-tile-draws-no-icons)).
+
+Names are not the same in every style or family. A name a sheet does not hold
+is blank, and some of the suggested names exist in Pro only (see
+[Free fallbacks](#free-fallbacks-for-pro-only-names)).
+
+## Icons over a background
+
+```tsx
+import '@nxgt/material/backgrounds/icons.css'; // or backgrounds.css
+import { Background } from '@nxgt/material/backgrounds';
+
+<Background
+  preset="icons"
+  tone="mixed"
+  icons="health" // a pack, or up to 48 names and { name, family?, type? }
+  iconStyle={['duotone-thin', 'duotone-light']} // one style, or a list of up to 8
+  iconMotif={{ layout: 'constellation', duotone: 'opacity' }}
+/>;
+```
+
+<img src="../previews/backgrounds-icons.webp" width="480" alt="The school pack of icons scattered over a faint wash, around a card">
+
+- **`icons`**: a pack name (`school`, `health`, `finance`, `travel`, `nature`,
+  `tech`: lists of names, drawn in any style) or your own names and
+  `{ name, family?, type? }` references. No `icons` draws the `school` pack.
+- **`iconStyle`**: one style (`'duotone-thin'`, `{ family: 'sharp', type: 'solid' }`)
+  or a list of up to 8. Each icon takes one style from the list by the seeded
+  pick, so a seed always draws the same picture. An icon's own `family` / `type`
+  always wins. Keep a list to styles that share your names.
+- **`iconMotif`**: `layout` (`scatter`, `grid`, `constellation`, `drift`),
+  `sizeRange`, `rotation`, `duotone` (`'opacity'`: the second layer is the same
+  tone at 0.4; `'tones'`: the next tone) and `secondaryOpacity`.
+- `animated` drifts each icon a little; nothing moves under
+  `prefers-reduced-motion`. Icons that cannot be drawn (an unknown pack or style,
+  a bad name, more than 48) draw `scatter-icons`, with a console warning outside
+  production.
+
+The builder is a separate chunk, loaded when the preset is used, so an app with
+no icon background never downloads it.
+
+## A sky
+
+Four presets draw a discreet sky (`eclipse`, `meteor-shower`, `ringed-planet`,
+`northern-lights`), and `sky` lays the moon or one of them over **any** preset:
+
+```tsx
+import '@nxgt/material/backgrounds/celestial.css'; // or backgrounds.css
+
+<Background preset="ringed-planet" tone="mixed" />
+<Background preset="icons" icons="travel" sky="northern-lights" grain />
+```
+
+<img src="../previews/backgrounds-celestial.webp" width="480" alt="The four celestial presets: an eclipse, a meteor shower, a ringed planet and northern lights">
+
+The `sky` keeps clear of the base's own moon or planet (it moves to the other
+side), and sits before the grain. The sky over the school icons:
+
+<img src="../previews/backgrounds-sky-overlay.webp" width="480" alt="The four skies laid over the school icons">
+
+The presets and `sky` are pure SVG: they need no sprite. Details in
+[backgrounds](backgrounds.md#celestial-presets-and-the-sky-overlay).
+
+## Illustrations for states
+
+```tsx
+import { Illustration, IllustrationDefaults } from '@nxgt/material/illustrations';
+import { HEALTH_SCENES } from '@nxgt/material/illustrations/health';
+import { EDUCATION_SCENES } from '@nxgt/material/illustrations/education';
+import { EmptyState } from '@nxgt/material/components';
+
+<IconSpritesProvider base="/static/icons/">
+  <IllustrationDefaults icons="suggested" sets={[HEALTH_SCENES, EDUCATION_SCENES]}>
+    <Illustration scene="empty" size="lg" title="An empty inbox" />
+    <EmptyState illustration="no-patients" title="No patients yet" />
+    <EmptyState illustration="no-students" title="No students yet" />
+  </IllustrationDefaults>
+</IconSpritesProvider>
+```
+
+An `Illustration` draws a hero icon on a Material 3 Expressive plate, with two
+to four satellites. There are twelve base scenes (`empty`, `no-results`,
+`not-found`, `error`, `offline`, `success`, `welcome`, `forbidden`,
+`maintenance`, `invitation`, `sign-in`, `empty-inbox`) and two domain sets of
+ten, **health** and **education**, each its own subpath so an app that does not
+import one does not carry it:
+
+<img src="../previews/feedback-status-illustration.webp" width="480" alt="The twelve base illustration scenes">
+
+<img src="../previews/feedback-status-illustration-health.webp" width="480" alt="The ten health scenes">
+
+<img src="../previews/feedback-status-illustration-education.webp" width="480" alt="The ten education scenes">
+
+- `IllustrationDefaults` is opt-in: without it (and without a `hero`) an
+  `EmptyState` or `ErrorState` draws the same built-in art as before. An
+  `illustration` prop wins over it, `illustration={false}` hides the media, and
+  an `icon` keeps its well.
+- Change the icons of a scene with `hero` and `satellites`, the look with
+  `iconStyle`, `tone` and `duotone`. Give the picture a `title` to make it an image
+  for assistive technology; without one it is decorative.
+- A scene id that no registered set holds draws the built-in art and warns once
+  outside production (register the set, or pass `scenes={HEALTH_SCENES}` to the
+  one `Illustration`).
+
+Full props in [illustrations](illustrations.md).
+
+## A theme that names its motif
+
+A theme carries the whole look, so the app needs no prop on its backgrounds:
+
+```ts
+// src/themes/sante.ts
+import { defineTheme, menthe } from '@nxgt/material/themes';
+
+export default defineTheme({
+  name: 'sante',
+  label: 'Santé',
+  extends: menthe,
+  background: {
+    preset: 'icons',
+    tone: 'mixed',
+    icons: 'health',
+    iconStyle: ['duotone-thin', 'duotone-light'],
+    iconMotif: { layout: 'constellation' },
+    sky: 'meteor-shower', // optional
+  },
+});
+```
+
+`defineTheme` checks the pack, the names, the styles and the motif when the
+theme is defined. `ThemePicker` draws the theme's first four icons in its tile;
+a sheet that is not served draws nothing and the tile keeps its wash.
+
+<img src="../previews/foundations-themes-icon-motifs.webp" width="480" alt="Three themes in the theme picker, each tile showing its own icons, and a background below each">
+
+See [themes](themes.md#icon-motifs-in-a-theme).
+
+## Free fallbacks for Pro-only names
+
+Most suggested names exist in Font Awesome Free. These do not, and stand in
+with a Free neighbour when you serve the Free sheets (pass `hero`, `satellites`
+or `icons` with the Free name):
+
+| Where | Pro-only name | A Free neighbour |
+| --- | --- | --- |
+| `school` pack | `backpack` | `bag-shopping` |
+| `nature` pack | `flower` | `seedling` |
+| base scenes | `sparkles`, `wifi-slash`, `cloud-slash`, `party-horn`, `hand-wave`, `lock-keyhole`, `traffic-cone` | `star`, `wifi`, `cloud`, `gift`, `hand`, `lock`, `triangle-exclamation` |
+| health scenes | `folder-user`, `clipboard-medical`, `calendar-clock`, `siren-on` | `folder`, `clipboard`, `calendar-check`, `triangle-exclamation` |
+| education scenes | `backpack`, `clipboard-list-check`, `books`, `file-chart-column` | `bag-shopping`, `clipboard-check`, `book`, `file-lines` |
+
+## Where to go next
+
+- [Backgrounds](backgrounds.md): every preset and prop, with the sizes.
+- [Illustrations](illustrations.md): the scenes, the sets and the states.
+- [Themes](themes.md#icon-motifs-in-a-theme): naming a motif in a theme.
+- [Troubleshooting](../troubleshooting.md): blank icons, the `scatter-icons`
+  warning, an unknown scene.