@nxgt/material 3.11.0 → 3.12.1

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @nxgt/material
 
+## 3.12.1
+
+### Patch Changes
+
+- [#1498](https://github.com/softistx/nxgt-material/pull/1498) [`2e31381`](https://github.com/softistx/nxgt-material/commit/2e3138104b6db82a01ccd339c074dab7a5fcad5f) Thanks [@SteveGT96](https://github.com/SteveGT96)! - README: the nxgt-material plugin is 2.0.0. `use-nxgt-material` is now an index with references for forms, i18n, tests, SSR and the other subpaths; the self-critique grid moves to `design-screens/references/grid.md`; the four screen recipes get a11y and copy fixes (one h1, Free icons, `EmptyState` and `Typography` props, ordered headings). Storybook: the Home dashboard recipe renders in the app shell. Nothing changes in the published components.
+
+- [#1494](https://github.com/softistx/nxgt-material/pull/1494) [`1ca476f`](https://github.com/softistx/nxgt-material/commit/1ca476f5978cd7932b015e725ab82828676cb611) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Storybook: two screen recipes under Guides/Recipes, a form with dialogs and a table with a settings page, tested with plays in light, dark and on a phone. Nothing changes in the published components.
+
+- [#1464](https://github.com/softistx/nxgt-material/pull/1464) [`f3ef6d0`](https://github.com/softistx/nxgt-material/commit/f3ef6d0fc874b21615f20e54878a7b4902a86bea) Thanks [@SteveGT96](https://github.com/SteveGT96)! - README: the nxgt-material plugin row now lists the design-screens skill and the design-reviewer agent.
+
+- [#1466](https://github.com/softistx/nxgt-material/pull/1466) [`8cf392d`](https://github.com/softistx/nxgt-material/commit/8cf392dc0ed9e32d03150b47671543c075605239) Thanks [@SteveGT96](https://github.com/SteveGT96)! - README: the nxgt-material plugin now lists four domain pairs of a skill and an agent (theme, scenes, print documents, vector drawings).
+
+- [#1487](https://github.com/softistx/nxgt-material/pull/1487) [`57f4570`](https://github.com/softistx/nxgt-material/commit/57f4570e9b98fd1723c1bb9be84683d2080b834c) Thanks [@SteveGT96](https://github.com/SteveGT96)! - README: the nxgt-material plugin now lists the screen-recipes skill. Storybook gains `Guides/Recipes/Home dashboard` and `Guides/Recipes/List and detail`, two whole screens to start from.
+
+## 3.12.0
+
+### Minor Changes
+
+- [#1472](https://github.com/softistx/nxgt-material/pull/1472) [`d01b87a`](https://github.com/softistx/nxgt-material/commit/d01b87a5be1e5b82cc46749fb67fe9193aac338f) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `StatCard` gets a compact `size="sm"`, `EntityHeader` a `stats` prop, and `Banner` takes `Alert`'s look.
+  
+  - `StatCard size="sm"` is a tile 40 to 56 px tall for a header band: the optional icon, then the value (tabular figures) over its label. It keeps `tone` and `variant`; `hint`, `delta` and `valueSize` are ignored. Tiles in a `flex flex-wrap` row wrap on a phone. New type `StatCardSize`.
+  - `EntityHeader` takes `stats` (`{ label, value, tone? }[]`), rendered as these tiles under `metadata`, so figures show as tiles while facts stay in `metadata`. New type `EntityStat`.
+  - `Banner` keeps its role and API (page level, `action`, `onDismiss`, default icon per tone) but now looks exactly like `Alert`: the light tone surface, the start accent bar, the tone-coloured icon, the title and description typography and the padding. It shares `Alert`'s variants, so the two cannot drift. Visual change: the solid tinted fill, the full tone border and the rounded corners are gone. `Alert` itself is unchanged, apart from its icon wrapper carrying `data-slot="alert-icon"` and its icon colour, size and margin rules now applying to the SVG inside that wrapper only, not to any SVG in its text.
+
+- [#1467](https://github.com/softistx/nxgt-material/pull/1467) [`338a8fe`](https://github.com/softistx/nxgt-material/commit/338a8fe79cb47dccaa52632da1eaa5d49bc1ef38) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `Badge` becomes a status badge: a 20 px pill with the `label-sm` text, compact padding and no hover or pointer affordance (a `Badge` link no longer fades on hover). New `soft` variant, a tonal fill from the tone tokens and the recommended variant for a state, and a `tone` prop for `soft` and `outlined` (neutral by default; `BadgeTone` is the library's `Tone`, so a tone declared in `AppTones` works too); `outlined` is now a thin 1 px line at 40 % of the tone. Visual change: every Badge is 20 px high and a little smaller in text, `CountBadge` keeps its own h-4 / 10 px size and loses the hover. `ListTile` with an `href` now ends with a discreet, decorative chevron after `trailing` (flipped in right-to-left); `chevron={false}` opts out, `chevron` opts a button tile in. A tile that already passes its own `ChevronRight` as `trailing` shows two: drop yours or pass `chevron={false}`.
+
+- [#1477](https://github.com/softistx/nxgt-material/pull/1477) [`90290fd`](https://github.com/softistx/nxgt-material/commit/90290fdedb66bd7a88932e910ad810e90e83826c) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `ActivityLayout` takes `breadcrumb` (default `true`): `breadcrumb={false}` hides the trail, for an error page whose matched routes would show a misleading one ([#1475](https://github.com/softistx/nxgt-material/issues/1475)). The trail is also hidden when every matched `handle.breadcrumb` renders `null`, and a crumb that renders `null` is left out with its separator. The Autocomplete and Combobox options no longer shrink below their content on a coarse pointer when the list scrolls: `ComboboxList` uses `auto-rows-max` ([#1474](https://github.com/softistx/nxgt-material/issues/1474)).
+
+- [#1465](https://github.com/softistx/nxgt-material/pull/1465) [`af31879`](https://github.com/softistx/nxgt-material/commit/af31879654725cdf62ea753b994b6e2d2aee3386) Thanks [@SteveGT96](https://github.com/SteveGT96)! - ActivityLayout and `AppSidebar`: a `MenuItem` takes `display?: 'icon'`. On a `footer` entry (a "Settings") it is drawn as a round, icon-only `IconButton` in the collapsed rail, the expanded sidebar and the phone's menu sheet: the label is its tooltip and its accessible name, it is `aria-current="page"` and tonal when active, and its target is 44 px on a coarse pointer. Entries without it keep their icon and label.
+  
+  **Visual change** (every `SidebarMenuItem`, `AppSidebar` and `ActivityLayout`): the active entry's label and icon are drawn in primary at 85 % of its lightness in light (`--sidebar-active-foreground`), so the label reads 4.5:1 or more on its pill for every theme preset (it was `--primary` itself, 3.7:1 on the corail preset's pill). The dark foreground and the pills are unchanged. A theme that sets `--sidebar-active-foreground` is unaffected.
+
+### Patch Changes
+
+- [#1479](https://github.com/softistx/nxgt-material/pull/1479) [`f8779d6`](https://github.com/softistx/nxgt-material/commit/f8779d6d56a06eff970b1676e472884a769cd4b9) Thanks [@SteveGT96](https://github.com/SteveGT96)! - `ActivityLayout`'s backdrop no longer draws a shape over the page's text or fields ([#1478](https://github.com/softistx/nxgt-material/issues/1478)). Shapes of a theme's background or of a `backdrop` `Background` (the motif and illustrated presets) are now hidden while they lie over, or within 8px of, a line of text or a control of the content: they fade out in 150ms (none under reduced motion) and fade back once clear, on scroll, resize and when the content changes. A moon, a planet or an eclipse is hidden whole, with its halo. They are hidden, never moved, so the shapes keep their places in the empty space, and nothing shows before the first check. The check keeps the content's boxes and only shifts them on scroll (rAF-throttled). The backdrop stays below the content (`-z-10`), under dialogs, sheets and sticky headers. Visible change: on a phone, and on a page that fills the column, fewer shapes show. Docs: the app-shell guide's "Where the shapes go".
+
+- [#1481](https://github.com/softistx/nxgt-material/pull/1481) [`eff59eb`](https://github.com/softistx/nxgt-material/commit/eff59eb10fc9d272e3e84d1fc85bde0d46d18214) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Stacked toasts pass axe's `target-size` on a coarse pointer again. Fixes [#1480](https://github.com/softistx/nxgt-material/issues/1480).
+  
+  A toast behind the front one in a collapsed stack is scaled and offset under it, so its covered close button (41.8 px once scaled, overlapping the front one's hit area) failed `target-size` since 3.11. The buttons (action and close) of such a toast are now hidden (`visibility: hidden`) until the stack opens on hover, or while focus is inside the toaster, so a Tab from the front toast still reaches them. Nothing changes for a single toast or an expanded stack.
+
 ## 3.11.0
 
 ### Minor Changes

package/README.md

@@ -420,7 +420,7 @@ Each area a consumer starts from has its own page under `docs/guides/`.
 | --- | --- |
 | [Forms](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/forms.md) | wiring fields to React Hook Form and Zod, composite values (contacts, opening hours), config-driven `Field`, server errors, what each field emits |
 | [i18n](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/i18n.md) | adding your strings next to the package's, switching language, translated Zod messages, SSR without a text mismatch |
-| [App shell](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/app-shell.md) | laying out an app with `ActivityLayout` (route changes cross-fade by default, `routeTransition={false}` opts out; it draws the theme's background, `backdrop` is the exception and `backdrop={false}` a plain page), its `items` (rendered as links; `linkComponent` to pass your own), the brand (`logo`, `name`, and `context` for the phone sheet's tenant line), the header's title, a route's `handle.title` as the page's `h1` in the app bar (`AppShellHandle`, `PageTitle`; it labels `<main>`, and `usePageTitleFocus()` focuses it after a navigation), and `AccountMenu`, the active entry and breadcrumbs (needs a data router; `breadcrumbRoot` replaces the home icon with a text link), the `<main>` landmark, the `h1` title, document scrolling, and a background preset behind the shell (`backdrop`) |
+| [App shell](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/app-shell.md) | laying out an app with `ActivityLayout` (route changes cross-fade by default, `routeTransition={false}` opts out; it draws the theme's background, `backdrop` is the exception and `backdrop={false}` a plain page), its `items` (rendered as links; `linkComponent` to pass your own), the brand (`logo`, `name`, and `context` for the phone sheet's tenant line), the header's title, a route's `handle.title` as the page's `h1` in the app bar (`AppShellHandle`, `PageTitle`; it labels `<main>`, and `usePageTitleFocus()` focuses it after a navigation), and `AccountMenu`, the active entry and breadcrumbs (needs a data router; `breadcrumbRoot` replaces the home icon with a text link, `breadcrumb={false}` hides the trail), the `<main>` landmark, the `h1` title, document scrolling, and a background preset behind the shell (`backdrop`) |
 | [Themes for your app](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/themes.md) | defining app themes, generating their stylesheets and types with the Vite plugin's `themes` option or the `nxgt-theme` command, the CI check |
 | [Theming](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/theming.md) | changing colours, radius or fonts, motion and corner tokens, dark mode, tones (the `data-tone` channel, app tones and the calm zone `data-density="calm"`), touch targets, using the compiled CSS without Tailwind |
 | [Printing](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/printing.md) | producing PDFs with `@nxgt/material/print` and getting the file in one call (download, new tab, preview, server `Response`) — its own entry since 2.0.0, with optional peers, a bundling trap on SSR servers, and the `next.config.ts` a Next.js route handler (and `output: 'standalone'`) needs |
@@ -593,20 +593,19 @@ Not components: what the stylesheet gives any element.
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-avatar.webp" width="120" alt="Avatar"> | [`Avatar`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#avatar), `AvatarImage`, `AvatarFallback`, `AvatarBase` | Image with a fallback and an optional online / offline dot; `shape` clips it to an expressive shape; `tone` colours the fallback. | `Avatar`, `AvatarImage`, `AvatarFallback` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-avatargroup.webp" width="120" alt="AvatarGroup"> | [`AvatarGroup`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#avatargroup) | Overlapping avatars with a `+N` overflow. | `AvatarGroup` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-shape.webp" width="120" alt="Shape"> | [`Shape`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#shape) | Material 3 Expressive's 35 shapes and a squircle as a backdrop, an icon container or a mask for a photo, with a morph; eight tones or an app tone. | — |
-| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-badge.webp" width="120" alt="Badge"> | [`Badge`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#badge) | Pill label: default, secondary, error, success, info, warning, outlined. | `Badge` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-badge.webp" width="120" alt="Badge"> | [`Badge`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#badge) | Status pill, 20 px: default, secondary, error, success, info, warning, `soft` (tonal, for states), outlined. | `Badge` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-countbadge.webp" width="120" alt="CountBadge"> | [`CountBadge`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#countbadge) | Count in the corner of its children, capped at `99+` and hidden at 0; `animated` pops it in when it changes. | `CountBadge` |
-| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-countbadge.webp" width="120" alt="CountBadge"> | [`CountBadge`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#countbadge) | Count in the corner of its children, capped at `99+` and hidden at 0. | `CountBadge` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-dayseparator.webp" width="120" alt="DaySeparator"> | [`DaySeparator`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#dayseparator), `isNewDay`, `formatDayLabel` | "Today", "Yesterday", the weekday or the date between two hairlines, in the provider's language; sticky if asked. | — |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-periodcards.webp" width="120" alt="PeriodCards"> | [`PeriodCards`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#periodcards) | Consecutive date ranges (terms, sprints) as cards: a "Current" marker with `aria-current`, a link over each card, as many 14rem columns as fit (one on a phone). | — |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-chip.webp" width="120" alt="Chip"> | [`Chip`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#chip) | Compact pill in three looks (hairline, soft, tag) and a dashed add pill, with leading, avatar and trailing slots, a selected state and a dismiss button; a coloured soft chip reads as a status (the tone's container, its text colour on it). | `Chip` |
-| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-statcard.webp" width="120" alt="StatCard"> | [`StatCard`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#statcard) | KPI tile with value, hint, icon, toned delta and a loading skeleton; `tone` and `variant` (`outlined`, `tonal`, `filled`) colour it, `valueSize` enlarges the value. | `StatCard` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-statcard.webp" width="120" alt="StatCard"> | [`StatCard`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#statcard) | KPI tile with value, hint, icon, toned delta and a loading skeleton; `tone` and `variant` (`outlined`, `tonal`, `filled`) colour it, `valueSize` enlarges the value, `size="sm"` makes a compact tile (it ignores `hint`, `delta` and `valueSize`). | `StatCard` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-metric-cards.webp" width="120" alt="TrendCard"> | [`TrendCard`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#metric-cards), `GoalCard`, `BreakdownCard`, `RankCard`, `CompareCard`, `HeatweekCard`, `FunnelCard`, `GaugeCard`, `SparkbarCard`, `DeltaListCard`, `BandCard`, `LatencyCard`, `RatioCard`, `ThresholdCard`, `PaceCard`, `HistogramCard`, `Sparkline` | Dashboard tiles including compare, heat, funnel, gauge, spark bars, delta list, range band, latency, ratio, threshold, pace and labelled histogram. Container queries. A `tone` (named, or your app's) draws the accent in it; deltas and breaches stay semantic. | `TrendCard`, `GoalCard`, `BreakdownCard`, `RankCard`, `CompareCard`, `HeatweekCard`, `FunnelCard`, `GaugeCard`, `SparkbarCard`, `DeltaListCard`, `BandCard`, `LatencyCard`, `RatioCard`, `ThresholdCard`, `PaceCard`, `HistogramCard` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-card-presets.webp" width="120" alt="FeatureCard"> | [`FeatureCard`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#card-presets), `MediaCard`, `PricingCard`, `ProfileCard`, `QuoteCard`, `OverlayCard`, `SpotlightCard`, `CrewCard`, `SplitCard`, `TicketCard`, `NoticeCard`, `TimelineCard`, `MessageCard`, `EventCard`, `StackCard`, `LinkCard`, `AlbumCard`, `TagCard`, `ReceiptCard`, `ReviewCard`, `OfferCard`, `PlaceCard`, `FileCard`, `StatusCard`, `ScoreCard`, `ShortcutCard`, `ChecklistCard` | Card presets including overlay, ticket, inbox, event, stack, link, album, tags, receipt, review, offer, place, file, status, score, shortcuts and checklist. Container queries. | `FeatureCard`, `MediaCard`, `PricingCard`, `ProfileCard`, `QuoteCard`, `OverlayCard`, `SpotlightCard`, `CrewCard`, `SplitCard`, `TicketCard`, `NoticeCard`, `TimelineCard`, `MessageCard`, `EventCard`, `StackCard`, `LinkCard`, `AlbumCard`, `TagCard`, `ReceiptCard`, `ReviewCard`, `OfferCard`, `PlaceCard`, `FileCard`, `StatusCard`, `ScoreCard`, `ShortcutCard`, `ChecklistCard` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-statusindicator.webp" width="120" alt="StatusIndicator"> | [`StatusIndicator`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#statusindicator) | Coloured status dot with an optional pulse and label. | `StatusIndicator` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-summarydata.webp" width="120" alt="SummaryData"> | [`SummaryData`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#summarydata) | Label / value pairs as a grid or inline; hides empty values. | `SummaryData` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-description.webp" width="120" alt="Description"> | [`Description`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#description) | Read-only label / value pair that renders nothing when empty. | `Description` |
-| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-entityheader.webp" width="120" alt="EntityHeader"> | [`EntityHeader`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#entityheader) | Page header with icon, title, status, metadata and actions. | `EntityHeader` |
-| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-listtile.webp" width="120" alt="ListTile"> | [`ListTile`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#listtile) | Row with leading / trailing slots, title and subtitle; becomes a link or button when interactive. `size="sm"` is the dense row. | `ListTile` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-entityheader.webp" width="120" alt="EntityHeader"> | [`EntityHeader`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#entityheader) | Page header with icon, title, status, metadata, `stats` (figures as compact `size="sm"` StatCard tiles) and actions. | `EntityHeader` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-listtile.webp" width="120" alt="ListTile"> | [`ListTile`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#listtile) | Row with leading / trailing slots, title and subtitle; becomes a link (with a decorative chevron) or button when interactive. `size="sm"` is the dense row. | `ListTile` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-accordioncard.webp" width="120" alt="AccordionCard"> | [`AccordionCard`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#accordioncard) | Renders `items` (title, content) as a styled accordion. | `AccordionCard` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-timeline.webp" width="120" alt="Timeline"> | [`Timeline`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#timeline), `TimelineItem`, `RelativeTime` | Vertical event timeline with toned icons and relative times. | `Timeline`, `TimelineItem`, `RelativeTime` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/data-display-eventchip.webp" width="120" alt="EventChip"> | [`EventChip`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/data-display.md#eventchip) | Calendar event pill — soft, solid or outlined — with its times, all-day and continuation edges. | `EventChip` |
@@ -682,7 +681,7 @@ Not components: what the stylesheet gives any element.
 | Preview | Component | What it does | @nxgt/material-vue |
 | --- | --- | --- | --- |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/feedback-status-alert.webp" width="120" alt="Alert"> | [`Alert`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/feedback-and-status.md#alert) | Callout with icon, title and description in seven tones. | `Alert` |
-| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/feedback-status-banner.webp" width="120" alt="Banner"> | [`Banner`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/feedback-and-status.md#banner) | Dismissible info / success / warning / error banner with an action. | `Banner` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/feedback-status-banner.webp" width="120" alt="Banner"> | [`Banner`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/feedback-and-status.md#banner) | Dismissible info / success / warning / error banner with an action, in the look of `Alert` (light surface, start bar). | `Banner` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/feedback-status-alertdialog.webp" width="120" alt="AlertDialog"> | [`AlertDialog`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/feedback-and-status.md#alertdialog), `AlertDialogContent`, `AlertDialogAction`, `AlertDialogCancel`… | Parts for a blocking confirmation dialog. | `AlertDialog` (same parts) |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/feedback-status-confirmdialog.webp" width="120" alt="ConfirmDialog"> | [`ConfirmDialog`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/feedback-and-status.md#confirmdialog), `ConfirmationDialog`, `CustomAlertDialog` | Confirm / cancel dialog with async loading. `ConfirmationDialog` adds a trigger and an optional Zod form. | `ConfirmDialog`, `ConfirmationDialog`, `CustomAlertDialog` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/feedback-status-customdialog.webp" width="120" alt="CustomDialog"> | [`CustomDialog`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/feedback-and-status.md#customdialog) | Ready-made dialog with trigger, icon, title, body and footer. | `CustomDialog` |
@@ -786,8 +785,15 @@ which is private: adding it needs a GitHub account with access to it.
 
 | Part | What it does |
 | --- | --- |
-| skill `use-nxgt-material` | picks the component by need, and wires imports, `styles.css` and the tokens, forms, i18n, tests by role and SSR from these docs, read in `node_modules/@nxgt/material/docs/` |
-| agent `screen-builder` | builds a page or a form from the catalogue, with tests by role and name and an accessibility check |
+| skill `use-nxgt-material` | an index that picks the component by need and wires imports and `styles.css`; its references cover the tokens and themes, forms, i18n, tests by role, SSR and the other subpaths, read from these docs in `node_modules/@nxgt/material/docs/` |
+| skill `design-screens` | the library's visual language for a screen (hierarchy, rhythm, tones, surfaces, states, phone, dark, motion) and an 11-criteria grid to score a screen out of 5 |
+| skill `screen-recipes` | whole screens to start from (a home dashboard, a list with a detail sheet, forms and dialogs, tables and settings), each the code of a tested `Guides/Recipes/<Name>` story |
+| agent `screen-builder` | builds a page or a form from the catalogue, with tests by role and name and an accessibility check, then looks at 360 and 1440 px screenshots in light and dark and fixes until the grid reads 4 everywhere |
+| agent `design-reviewer` | read-only: scores a screen's screenshots on the same 11 criteria and returns the fixes ranked, each with the component and prop |
+| skill `build-a-theme` + agent `theme-builder` | the app's own theme with `defineTheme`: seeds, tones, background and icon motif, generation, provider and picker; checks the AA contrast of the generated tokens in light and dark and looks at key screens |
+| skill `compose-scenes` + agent `scene-composer` | illustrations (domain scene sets), backgrounds and icon sprites for empty, error, auth, hero and celebration moments; checks text contrast over backgrounds, reduced motion, dark, Free against Pro sprites and the Font Awesome Pro licence rule |
+| skill `design-print-documents` + agent `print-designer` | PDF and print documents with `@nxgt/material/print`: a school report card, a prescription and a receipt as recipes; checks A4 margins, page breaks, figures, black-and-white legibility, fonts and accessibility |
+| skill `draw-with-vectors` + agent `vector-artist` | diagrams, floor plans, pictograms and annotated images drawn from code with `@nxgt/material/draw`; checks colour roles in dark mode, accessible names, PNG and PDF export and legibility at phone width |
 | agent `upgrade-assistant` | upgrades between two versions: reads the release notes in between, applies the migrations that match, runs the app's typecheck and tests |
 | hook (after Write / Edit) | names the component and its docs page when a file hand-rolls one (a native date input, a home-made dialog or tabs, a paged `<table>`, a file input with a preview). Advisory only; `NXGT_MATERIAL_ADVISOR_DISABLE=1` turns it off |
 

package/dist/components/components.css

@@ -55,6 +55,7 @@
 /* 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";
+@import "./ui/layout/app-shell/activity-backdrop-shapes.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";

package/dist/components/ui/feedback/toast/toast-expressive.css

@@ -107,6 +107,23 @@
 		gap: 8px;
 		margin-inline-start: auto;
 	}
+	/* A stacked toast behind the front one (`data-expanded="false"`,
+	 * `data-front="false"`) sits under it, scaled and offset by a few pixels:
+	 * its buttons are covered, so a tap lands on the front toast, and a covered,
+	 * scaled close button fails axe's `target-size` (#1480). Its buttons are
+	 * hidden until the stack opens (sonner opens it on hover, not on focus) or
+	 * focus is inside the toaster, so a Tab from the front toast still reaches
+	 * them. Sonner's own `opacity: 0` for these does not apply to our unstyled
+	 * (`data-styled="false"`) toasts. */
+	[data-sonner-toast][data-expanded="false"][data-front="false"]
+	.nxgt-toast-buttons {
+		visibility: hidden;
+	}
+	[data-sonner-toaster]:focus-within
+		[data-sonner-toast][data-expanded="false"][data-front="false"]
+		.nxgt-toast-buttons {
+		visibility: visible;
+	}
 	.nxgt-toast-title {
 		color: var(--toast-fg);
 	}

package/dist/components/ui/layout/app-shell/activity-backdrop-shapes.css

@@ -0,0 +1,49 @@
+/* Which shapes of the backdrop show (observe-layout.ts, watch-content.ts).
+ * Plain CSS in `@layer components`, beside activity-backdrop.css. */
+@layer components {
+	/* The theme's backdrop keeps its shapes whole (keep-shapes-inside.ts):
+	 * the scene waits for the first pass, then a shape that would cross the
+	 * layer's edge or reach the header band is hidden, never cut. */
+	[data-keep-inside]:not([data-checked]) .mo,
+	[data-slot="activity-layout-backdrop"]
+		[data-background]:not([data-checked])
+		.mo {
+		visibility: hidden;
+	}
+	[data-keep-inside] .mo > [data-outside],
+	[data-slot="activity-layout-backdrop"]
+		[data-background]
+		.mo
+		> [data-outside] {
+		visibility: hidden;
+	}
+
+	/* A shape over the page's text or controls fades out and comes back once
+	 * clear (watch-content.ts): it is hidden, never moved. A compound body (the
+	 * moon, the planet, the eclipse: `.pt.mg`) is hidden whole, with its halo
+	 * (`.pt.mh`). The scene stays invisible until the first check, so nothing
+	 * flashes over the content. */
+	[data-keep-inside] .mo > *,
+	[data-keep-inside] .pt,
+	[data-slot="activity-layout-backdrop"] [data-background] .mo > *,
+	[data-slot="activity-layout-backdrop"] [data-background] .pt {
+		transition: opacity 150ms ease;
+	}
+	/* Important: a preset sets its own opacity on a body (`.md`, the dark
+	 * moon's, a celestial body's); in a layer, `!important` beats every normal
+	 * declaration of those. The 150 ms transition still runs. */
+	[data-keep-inside] .mo > [data-hidden],
+	[data-keep-inside] .pt[data-hidden],
+	[data-slot="activity-layout-backdrop"] [data-background] .mo > [data-hidden],
+	[data-slot="activity-layout-backdrop"] [data-background] .pt[data-hidden] {
+		opacity: 0 !important;
+	}
+	@media (prefers-reduced-motion: reduce) {
+		[data-keep-inside] .mo > *,
+		[data-keep-inside] .pt,
+		[data-slot="activity-layout-backdrop"] [data-background] .mo > *,
+		[data-slot="activity-layout-backdrop"] [data-background] .pt {
+			transition: none;
+		}
+	}
+}

package/dist/components/ui/layout/app-shell/activity-backdrop.css

@@ -77,23 +77,6 @@
 		display: none;
 	}
 
-	/* The theme's backdrop keeps its shapes whole (use-keep-shapes-inside.ts):
-	 * the scene waits for the first pass, then a shape that would cross the
-	 * layer's edge or reach the header band is hidden, never cut. */
-	[data-keep-inside]:not([data-checked]) .mo,
-	[data-slot="activity-layout-backdrop"]
-		[data-background]:not([data-checked])
-		.mo {
-		visibility: hidden;
-	}
-	[data-keep-inside] .mo > [data-outside],
-	[data-slot="activity-layout-backdrop"]
-		[data-background]
-		.mo
-		> [data-outside] {
-		visibility: hidden;
-	}
-
 	/* A preset fills the layer: the layer's size, not `100lvw x 100lvh`, which
 	 * counts the scrollbar and a phone's toolbar. */
 	[data-slot="activity-layout-backdrop"] > [data-background] {

package/dist/components/ui/layout/sidebar/sidebar-tokens.css

@@ -3,13 +3,18 @@
 :root {
 	/* The active entry of the sidebar and the navigation rail: its tint, the
 	 * tint hovered, the start bar (the label's colour), and the icon and label drawn on it. Translucent primary
-	 * (these shares, 15 % and 20 % hovered); the label is primary itself. The
+	 * (these shares, 15 % and 20 % hovered); the label is primary at 85 % of its lightness in light (a lavender of its hue in dark). The
 	 * utilities (`bg-sidebar-active`...) derive them on the element, so they
 	 * follow a `--primary` set below :root. To theme the rail set
 	 * `--sidebar-active`, `--sidebar-active-hover` and
 	 * `--sidebar-active-foreground` (all three, or the first two and the
 	 * foreground); the derived colours are not declared here, on purpose. */
 	--nxgt-sidebar-active-share: 15%;
+	/* Light: primary itself reads 4.5:1 on the page but not on its own 15 % pill
+	 * for every preset (corail 3.7:1), so the label is primary darkened to 85 %
+	 * of its lightness (4.99:1 on the worst preset, hovered). The preset spec
+	 * (sidebar-active-contrast.test.ts) reads this number back. */
+	--nxgt-sidebar-active-l: calc(l * 0.85);
 	/* The height of the app bar and of the rail's header from `md` up, so the
 	 * rail's logo and the bar's title share one centre line. Phones keep the
 	 * bar alone at this height; the menu sheet's header is unconstrained. */
@@ -24,7 +29,7 @@
 	/* The dark theme's primary is too dark to read on its surfaces (2.5:1), so
 	 * the rail's label is a saturated lavender of its hue (5.3:1: lightness
 	 * 0.72, chroma 0.15) on a denser pill (30 %, 35 % hovered). Light keeps the
-	 * lightness and chroma of primary (the `l` and `c` fallbacks). */
+	 * chroma of primary and 85 % of its lightness. */
 	--nxgt-sidebar-active-share: 30%;
 	--nxgt-sidebar-active-hover-share: 35%;
 	--nxgt-sidebar-active-l: 0.72;