@nxgt/material 3.7.4 → 3.8.0

package/docs/guides/theming.md

@@ -37,8 +37,10 @@ at the top are needed is in [getting started](../getting-started.md#styles).
   `lib/components/`);
 - the **tokens**: CSS variables on `:root`, and their dark values on `.dark`
   and `[data-theme="dark"]`;
-- a `@theme` block that maps each token to a Tailwind colour, so `bg-primary`,
-  `text-error-foreground`, `border-border` are real utilities;
+- an `@theme inline` block that maps each token to a Tailwind colour, so
+  `bg-primary`, `text-error-foreground`, `border-border` are real utilities
+  that read `var(--primary)`… where they are used (a wrapper or a theme zone
+  that sets the token is followed);
 - the **background presets' base, gradient and motion CSS** (`lib/backgrounds/css/`),
   which `Background` from `/components` draws with: plain CSS keyed on
   `data-background`, in `@layer components`, so a utility on the element wins.
@@ -65,7 +67,7 @@ at the top are needed is in [getting started](../getting-started.md#styles).
 | `--nxgt-accent` | `[--nxgt-accent:…]` | the mark colour of the selection controls: the fill, handle, state layer and stop dots of `Slider`, the on state of `Switch`, the box and dot of `Checkbox` and `Radio`. It defaults to `--primary` (`--primary-text` in dark) and is set per control, so override it on the control itself, not on `:root` |
 | `--error`, `--success`, `--info`, `--warning` (+ `-foreground`) | `bg-error`, `text-success`, … | the status colours of `Button`, `Alert`, `Badge`, toasts |
 | `--primary-text` | `text-primary-text` | primary drawn as text or an icon on a page, card or popover surface: `Typography tone="primary"`, links, the `Alert` primary icon, selected labels. Equal to `--primary` in light; in dark, `--primary` mixed 60 % with white (`color-mix(in oklab, var(--primary) 40%, white)`), well over 4.5:1 on `--background` and `--card` |
-| `--primary-indicator` | `bg-primary-indicator`, `border-primary-indicator`, `ring-primary-indicator`, `stroke-primary-indicator` | primary drawn as a non-text mark that carries a state (WCAG 1.4.11, 3:1): an active bar or dot, a selected or focused border, a ring, a spinner arc. Equal to `--primary` in light; in dark, `--primary` mixed 25 % with white (`color-mix(in oklab, var(--primary) 75%, white)`), 4.5:1 on `--background`, 4.1:1 on `--card`, 3.7:1 on `--muted` (`--primary` itself gives 2.5, 2.3 and 2.1:1) |
+| `--primary-indicator` | `bg-primary-indicator`, `border-primary-indicator`, `ring-primary-indicator`, `stroke-primary-indicator` | primary drawn as a non-text mark that carries a state (WCAG 1.4.11, 3:1): an active bar or dot, a selected or focused border, a ring, a spinner arc. Equal to `--primary` in light; in dark, `--primary` mixed 25 % with white (`color-mix(in oklab, var(--primary) 75%, white)`), 4.8:1 on `--background`, 4.5:1 on `--card`, 4.2:1 on `--muted` (`--primary` itself gives 2.7, 2.5 and 2.3:1) |
 | `--error-text` | `text-error-text` | error drawn as text: field messages, `HelperText` in its error state, form and dialog errors, `variant="error"` menu items |
 | `--destructive` | `bg-destructive`, `text-destructive` | deprecated alias of `--error`: the light theme sets it to `var(--error)`, the dark theme keeps its own value; use `--error` |
 | `--card`, `--popover`, `--tooltip` (+ `-foreground`) | `bg-card`, `bg-popover`, `bg-tooltip` | surfaces |
@@ -93,17 +95,22 @@ Put `text-foreground` on a container; it stays well above 4.5:1 in both themes.
 
 ## The neutral palette
 
-The neutrals of both themes are softly tinted toward violet (hue 290, low
-chroma), to sit with the primary indigo instead of fighting it. The values:
+The default theme's page is plain: pure white in light and the one dark night
+every theme shares (`oklch(0.15 0.026 273)`), whatever the colours. Its other
+neutrals (cards in dark, muted, borders, text) are softly tinted toward violet
+(hue 290, low chroma), to sit with the primary indigo instead of fighting it.
+A theme can tint its page too with `neutrals: 'tinted'` in `defineTheme`
+(`@nxgt/material-core` theme guide), which is how the page looked before 3.8
+(`oklch(0.973 0.008 293.9)` and `oklch(0.192 0.016 290.5)` for Lavande). The values:
 
 | Token | Light | Dark |
 | --- | --- | --- |
-| `--background` | `oklch(0.973 0.008 293.9)` | `oklch(0.192 0.016 290.5)` |
-| `--card`, `--popover` / `--sidebar` | white / `oklch(0.985 0.006 293.9)` | `oklch(0.232 0.019 289.4)` |
+| `--background` | `oklch(1 0 0)` | `oklch(0.15 0.026 273)` |
+| `--card`, `--popover` / `--sidebar` | white / `oklch(0.985 0.006 293.9)` | `oklch(0.19 0.019 289.4)` |
 | `--foreground` | `oklch(0.227 0.017 290)` | `oklch(0.943 0.012 291.3)` |
-| `--muted`, `--accent` | `oklch(0.955 0.012 292)`, `oklch(0.91 0.016 293)` | `oklch(0.27 0.022 290)` |
+| `--muted`, `--accent` | `oklch(0.955 0.012 292)`, `oklch(0.91 0.016 293)` | `oklch(0.228 0.022 290)`, `oklch(0.25 0.022 290)` |
 | `--muted-foreground` | `oklch(0.478 0.032 292)` | `oklch(0.725 0.03 292.2)` |
-| `--border`, `--input` | `oklch(0.912 0.016 293.7)` | `oklch(0.301 0.025 291.4)`, `oklch(0.34 0.027 291.4)` |
+| `--border`, `--input` | `oklch(0.912 0.016 293.7)` | `oklch(0.259 0.025 291.4)`, `oklch(0.298 0.027 291.4)` |
 
 Earlier versions used a blue-slate neutral (hue 247 to 266; the dark
 background `oklch(0.14 0.036 258.53)` was a deep navy). To bring it back,
@@ -246,7 +253,7 @@ the element overrides them.
 | `--nxgt-tint-hover`, `-selected`, `-strong` | `color-mix(in oklab, var(--primary) var(--nxgt-tint-hover), transparent)` | the 8 %, 12 % and 18 % tints of hover, selected and strong states. For your own components: no component of the library reads them |
 | `--nxgt-tint-container` | | the share of the tone in a container: 20 % in light, 45 % in dark (of the dark base below; 24 % of the tone's text colour in a browser without relative colour syntax) |
 | `--nxgt-tone-container-from` | | where a tone container is mixed from, the dark rule stated once: 100 % mixes from the tone itself, 0 % from the tone held at a container's lightness (the dark base, next row). It is 100 % in light and 0 % in dark, where the raw tone is too deep (the indigo primary) or too pale (an M3 dark primary, `#cfbcff`) to show over the surfaces. It applies to the channel's container, the opaque `--<tone>-container` tokens and the status `Chip` alike. Set it under `.dark, [data-theme="dark"]` (the dark selector of `tones/tokens.css`) to bring the dark containers back to the raw tone: `.dark, [data-theme="dark"] { --nxgt-tone-container-from: 100%; }` |
-| `--nxgt-tone-container-min`, `-max` | | the dark base: the tone with its lightness held between these two (`0.35` and `0.4`, on `:root`), its hue and chroma kept, `oklch(from <tone> clamp(min, l, max) c h)`. 45 % of it over the surface gives a container of lightness 0.25 to 0.32 that shows the tone's colour. In the default theme the text of every named tone is 5.2:1 or more on it, an app tone's 5.7:1 or more, on the page and on a card; with an M3 dark palette (`#141218` page, `#211f26` card), 4.9:1 or more. Without relative colour syntax (before Chrome 119, Safari 18, Firefox 128) the base is the tone's text colour at 24 %, the earlier rule |
+| `--nxgt-tone-container-min`, `-max` | | the dark base: the tone with its lightness held between these two (`0.35` and `0.4`, on `:root`), its hue and chroma kept, `oklch(from <tone> clamp(min, l, max) c h)`. 45 % of it over the surface gives a container of lightness 0.25 to 0.32 that shows the tone's colour. In the default theme the text of every named tone is 4.5:1 or more on it, and so is an app tone's, on the page and on a card; with an M3 dark palette (`#141218` page, `#211f26` card), 4.9:1 or more. Without relative colour syntax (before Chrome 119, Safari 18, Firefox 128) the base is the tone's text colour at 24 %, the earlier rule |
 | `--nxgt-tone-container-base` | `color-mix(in oklab, var(--nxgt-tone-container-base) 45%, <surface>)` | what the channel's container mixes from, set on every element whose `data-tone` is a named tone or yours (not the library's other `data-tone` values, which inherit it): the tone in light, the dark base in dark. Read it for a tint of your own that should match the containers |
 | `--nxgt-tint-status` | the tonal `Chip` with a `color` (`color-mix(in oklab, <tone> var(--nxgt-tint-status), <surface>)`) | the share of the tone in a status: 20 % in light, 45 % in dark (of the dark base there, as above; 24 % of the text colour without relative colour syntax). Separate from `--nxgt-tint-container`, so changing that one does not change chips. Override it under `:root` and `.dark, [data-theme="dark"]` like the other tokens |
 | `--nxgt-calm-hides`, `--nxgt-expressive-hides` | `var(--nxgt-calm-hides, <tone>) var(--nxgt-expressive-hides, <surface>)` | the flags of the [calm zone](#calm-zone): set by the zone (`data-density`), empty or invalid, never by hand, because setting one inverts the behaviour. Your own component reads them to be the tone outside a zone and the surface inside one |
@@ -679,19 +686,23 @@ Redefine the variables **after** the import, for light and dark separately:
 }
 ```
 
-Override the variable, not the `@theme` entry: `--color-primary` is defined as
-`var(--primary)`, so one change reaches both modes and every derived colour.
+Override the variable, not the `@theme` entry (for a brand palette, prefer a
+[theme](#from-token-overrides-to-a-theme)): the utilities read `var(--primary)`
+where they are used, so one change reaches both modes and every derived colour.
 
-For a single area of the page, set the `--color-*` variables on a wrapper
-(the `@theme` entries are resolved on the root, so setting `--primary` on an
-element below it changes nothing):
+For a single area of the page, set the token on a wrapper. Utilities inside it
+follow, since they read the token where they sit (before 3.8 they read a
+`--color-*` computed on the root, and the wrapper had to set that one; setting
+`--color-primary` on a wrapper no longer changes `bg-primary`). Derived tokens
+such as `--primary-text` are computed where they are declared, so for a full
+recolour use a [theme zone](#themes), which re-declares them:
 
 ```tsx
 import { Button } from '@nxgt/material/components';
 
 export function DangerZone() {
   return (
-    <section style={{ ['--color-primary' as string]: 'var(--error)' }}>
+    <section style={{ ['--primary' as string]: 'var(--error)' }}>
       <Button>Delete workspace</Button>
     </section>
   );
@@ -787,20 +798,20 @@ the rest yourself. Without the class the anchor keeps the prose style.
 **Contrast.** The shipped light palette keeps the text of every filled status
 colour at 4.5:1 or more (WCAG 1.4.3): `--secondary` 6.2:1, `--success` 6.1:1,
 `--info` 6.3:1 and `--warning` 5.5:1 against their `-foreground`, and
-`--secondary` as text (a `tonal`, `outlined` or `link` `Button`) 6.0:1 on
-`--background`, 4.8:1 on its own 15 % `tonal` tint.
+`--secondary` as text (a `tonal`, `outlined` or `link` `Button`) 6.5:1 on
+`--background`, 5.2:1 on its own 15 % `tonal` tint.
 
 The dark theme keeps brighter values, read as text on the dark surfaces: the
-dark `--tertiary` (`oklch(0.7 0.15 310.75)`) is 6.5:1 on `--background` and
-5.9:1 on `--card`, with a dark `--tertiary-foreground` that keeps 6.5:1 on
+dark `--tertiary` (`oklch(0.7 0.15 310.75)`) is 6.9:1 on `--background` and
+6.5:1 on `--card`, with a dark `--tertiary-foreground` that keeps 6.9:1 on
 a filled tertiary surface (light: 7.6:1 under near-white). The dark
-`--secondary` (`oklch(0.675 0.1135 245.65)`) is 6.3:1 on `--background`
-and 5.8:1 on `--card` (a `tonal` secondary `Button` 5.1:1 and 4.6:1). Under
+`--secondary` (`oklch(0.675 0.1135 245.65)`) is 6.8:1 on `--background`
+and 6.4:1 on `--card` (a `tonal` secondary `Button` 5.6:1 and 5.1:1). Under
 near-white text those brights are too light, so every filled surface built on
 them is tinted in the dark theme: a filled `secondary` `Button`, `IconButton`
-or `Badge` at 70 % (4.9 to 5.2:1 on `--background`, 4.7 to 4.9:1 on `--card`), a filled
-`success`, `info` or `warning` one at 60 % (7.1:1, 5.6:1 and 5.8:1 on
-`--background`; 6.8:1, 5.3:1 and 5.5:1 on `--card`; the `warning` `Button` 5.9:1). Their hover, focus and
+or `Badge` at 70 % (5.1 to 5.4:1 on `--background`, 4.9:1 or more on `--card`), a filled
+`success`, `info` or `warning` one at 60 % (7.6:1, 5.8:1 and 6.1:1 on
+`--background`; 7.3:1, 5.5:1 and 5.8:1 on `--card`; the `warning` `Button` 4.5:1 or more). Their hover, focus and
 pressed states are tinted further down, so they only gain contrast.
 
 In the light theme the filled `primary`, `secondary`, `success`, `info`,
@@ -816,11 +827,11 @@ The `tonal`, `outlined` and `link` variants of `Button` and `IconButton` draw
 their text and icon in one tone per colour, read on `--background`, on
 `--card` and on the variant's own tint (15 % at most, at rest or focused). In
 the light theme `primary`, `secondary`, `info` and `success` use the token
-itself (5.4, 4.8, 4.9 and 4.7:1 at their lowest) and `warning` and `error` the
-token mixed with 15 % black (6.0 and 5.0:1). In the dark theme `primary` is
-mixed with 60 % white, the `--primary-text` token (7.7:1 at its lowest: the token itself is a dark indigo,
-2.2:1), `success` and `warning` with 15 % white (4.8 and 5.8:1), `error` with
-30 % white (5.5:1), and `secondary` and `info` use the token (4.6 and 5.0:1).
+itself (5.8, 5.2, 5.2 and 5.0:1 at their lowest) and `warning` and `error` the
+token mixed with 15 % black (6.4 and 5.4:1). In the dark theme `primary` is
+mixed with 60 % white, the `--primary-text` token (8.5:1 at its lowest: the token itself is a dark indigo,
+2.3:1), `success` and `warning` with 15 % white (5.3 and 6.5:1), `error` with
+30 % white (6.0:1), and `secondary` and `info` use the token (5.1 and 5.6:1).
 The tones are mixed from the tokens (`color-mix(in oklab, var(--color-error)
 85%, black)`), so an override of a token moves its tone with it; a text colour
 of your own on one of those buttons (`className="text-primary-text"`) replaces the tone
@@ -829,7 +840,7 @@ and is yours to check.
 A `Badge` used as a link (`asChild` around an `<a>`) darkens on hover like a filled
 button (mixed with 10 % black; in the dark theme its tint drops by ten
 points) rather than fading toward the page. A selected `ListTile` draws its
-subtitle in `text-foreground/70` (7.0:1 on the selected tint, where the muted
+subtitle in `text-foreground/70` (7.5:1 on the selected tint, where the muted
 colour gave 4.4:1). The light `--error` is `oklch(0.56 0.245 27.325)`, a shade
 darker than the dark theme's: a filled `error` button's near-white text reaches
 4.8:1 (it was 4.6:1). The dark `--error` keeps `0.577`: a lighter value drops
@@ -839,32 +850,32 @@ the filled surface's near-white text below 4.5:1 (`0.62` gives 3.85:1).
 the light theme, 70 in the dark one), so a warning `Alert`, `Banner`, `Badge`
 or toast does not read as a failure. Light `oklch(0.52 0.13 62)` is 5.5:1
 under its near-white `-foreground`; dark `oklch(0.7 0.15 70)` reads as text at
-6.7:1 on `--background` and 6.1:1 on `--card` (5.9 and 5.3:1 on its 10 % tint). An app that overrides `--warning` keeps its own
+7.2:1 on `--background` and 6.7:1 on `--card` (6.4 and 5.9:1 on its 10 % tint). An app that overrides `--warning` keeps its own
 value; one that keeps the shipped value sees its `bg-warning` and
 `text-warning` surfaces change hue, and re-checks its custom pairs.
 
 **A selected `DataTable` row** (`TableRow`, `data-state="selected"`) is a 15 %
 primary tint with `foreground` text, a bar on the inline-start edge of its
 first cell (`before:`, primary in the light theme, primary mixed with 60 %
-white in the dark one: 5.4:1 in light and 7.7:1 or more in dark against the
-row), and the checkbox, drawn in the same dark colour (7.7:1 or more). The
-tint is too light to be told from its neighbour alone (1.25:1 in light, 1.10 to
-1.11:1 in dark), which is what keeps the text at 4.5:1 or more on a page and on
-a `Card`: 12.6:1 in light, and in dark 14.1:1 on a page, 12.9:1 in a `DataTable`
+white in the dark one: 5.8:1 in light and 8.5:1 or more in dark against the
+row), and the checkbox, drawn in the same dark colour (8.5:1 or more). The
+tint is too light to be told from its neighbour alone (1.26:1 in light, 1.09 to
+1.10:1 in dark), which is what keeps the text at 4.5:1 or more on a page and on
+a `Card`: 13.6:1 in light, and in dark 15.3:1 on a page, 14.2:1 in a `DataTable`
 on a `Card` and for a bare `TableRow` on a `Card`. Links and
 `text-muted-foreground` texts (drawn as `foreground` at 70 %) are 5.6:1 in
-light and 7.0:1 in dark for a bare row on a `Card`. A `text-error-text` text
+light and 7.5:1 in dark for a bare row on a `Card`. A `text-error-text` text
 keeps its colour. Do not
 put `text-primary-foreground` in a cell for a selected row: it is near-white
 on that tint.
 
 **Error text has a token of its own**, `--error-text` (`text-error-text`), so
 the fill can stay dark while the text is light enough to read. The light value
-is `color-mix(in oklab, var(--error) 92%, black)` (5.6:1 on `--background`,
+is `color-mix(in oklab, var(--error) 92%, black)` (6.0:1 on `--background`,
 6.0:1 on `--card`, 5.0:1 on the `bg-error/10` tint of a focused menu item, where
 `--error` gives 5.0 and 4.2:1); the dark one is
-`color-mix(in oklab, var(--error) 76%, white)`, 5.85:1 on `--background` and
-5.35:1 on `--card` (4.78:1 on a focused error menu item), where `--error` itself gives 3.9 and 3.5:1. Field messages,
+`color-mix(in oklab, var(--error) 76%, white)`, 6.25:1 on `--background` and
+5.9:1 on `--card` (5.2:1 on a focused error menu item), where `--error` itself gives 4.0 and 3.8:1. Field messages,
 `HelperText` in its error state, form, dialog and upload errors, a textarea's
 counter over its limit, the error lines of `Terminal`, a
 `variant="error"` menu item and the falling values of the metric cards use it.
@@ -879,18 +890,18 @@ Which one to use:
   need 3:1 (WCAG 1.4.11), which `--error` reaches in both themes. Text on a
   filled error surface is `text-error-foreground`.
 
-`--error-text` is computed where it is declared, on the root, and `@theme`
-resolves `--color-error-text` there too: an override of `--error` under `:root`
-and `.dark, [data-theme="dark"]` moves it, but setting `--error-text` or
-`--error` on an element below the root changes nothing. Below the root, set
-`--color-error-text` (and `--color-error` for fills) on that element, or put
-the override on the root.
+`--error-text` is computed where it is declared, on the root: an override of
+`--error` under `:root` and `.dark, [data-theme="dark"]` moves it. Utilities
+read the token where they are used, so setting `--error-text` itself on an
+element below the root works, but setting only `--error` there does not move
+the text colour (it stays the root's). Set both on that element, put the
+override on the root, or use a [theme zone](#themes), which re-declares them.
 
 **Primary text has a token of its own**, `--primary-text` (`text-primary-text`),
 for the same reason: the brand colour is a dark fill (it keeps near-white text
 readable on a button) and reads at only about 2:1 as text on the dark surfaces.
 The light value is `color-mix(in oklab, var(--primary) 96%, black)` (primary
-4 % toward black, 7.3:1 on the violet page); the dark one is
+4 % toward black, 7.9:1 on the white page); the dark one is
 `color-mix(in oklab, var(--primary) 40%, white)` (primary mixed 60 % with
 white, the recipe of the tonal `Button` labels). `Typography tone="primary"`,
 the `Alert` primary icon, links, selected labels and the other primary text of
@@ -904,7 +915,8 @@ the catalogue use it.
 Like `--error-text`, it is computed where it is declared, on the root: an
 override of `--primary` under `:root` and `.dark, [data-theme="dark"]` moves it
 (override `--primary-text` itself after it to pick another dark colour); below
-the root, set `--color-primary-text` on the element.
+the root, set `--primary-text` on the element (setting only `--primary` there
+does not move it; a [theme zone](#themes) does).
 
 Storybook's `Guides/Theming/Contrast` measures all of this in both themes:
 the surfaces' text, the error text (`HelperText` and a field's message on
@@ -915,33 +927,33 @@ at rest, hovered, focused and pressed, the tracks and the tabs;
 tokens after an override.
 
 **Tabs.** An `underline` tab's active label is `--primary` in the light
-theme (6.8:1 on `--background`, 7.3:1 on `--card`, 6.4:1 on `--muted`) and
-`--primary` mixed with 60 % white in the dark one (9.3:1, 8.5:1 and 7.6:1);
+theme (7.3:1 on `--background`, 7.3:1 on `--card`, 6.4:1 on `--muted`) and
+`--primary` mixed with 60 % white in the dark one (9.9:1, 9.3:1 and 8.6:1);
 its bar and every tab's focus outline are `--primary` in the light theme and
-`--track-fill` in the dark one (at least 6.7:1 and 9.4:1 on those surfaces).
+`--track-fill` in the dark one (at least 6.4:1 and 10.5:1 on those surfaces).
 An inactive label is `--muted-foreground`, and turns to `--foreground` when
 hovered. A `segmented` tab's active label is `--foreground` on the raised
-surface (17.1:1 light, 14.2:1 dark); that surface is only 1.1:1 to 1.2:1 on
-the track, so it has a `--muted-foreground` border (5.8:1 light, 6.2:1 dark
+surface (17.1:1 light, 15.6:1 dark); that surface is only 1.1:1 to 1.2:1 on
+the track, so it has a `--muted-foreground` border (5.8:1 light, 7.0:1 dark
 on the track), and the label also changes colour and weight. Storybook's
 `Guides/Theming/Contrast` story `Tabs` measures each label at rest, hovered
 and focused, the outline, the bar and the border, on the three surfaces, in
 both themes.
 
-`--muted-foreground` is 6.2:1 on `--background`, 6.7:1 on `--card`, 5.7:1 on the
+`--muted-foreground` is 6.7:1 on `--background`, 6.7:1 on `--card`, 6.2:1 on the
 "paper" tint (`bg-background-paper`, 5 % primary) and 5.8:1 on `--muted` in
-the light theme; in the dark theme it is 7.5:1 on `--background`, 6.9:1 on
-`--card`, 7.3:1 on the paper tint and 6.2:1 on `--muted`. The dark `--muted`
-is a dark surface (`oklch(0.27 0.022 290)`, it was the light value, a
-near-white block on a dark page) and `--foreground` on it reaches 12.8:1.
+the light theme; in the dark theme it is 8.0:1 on `--background`, 7.6:1 on
+`--card`, 7.8:1 on the paper tint and 7.0:1 on `--muted`. The dark `--muted`
+is a dark surface (`oklch(0.228 0.022 290)`, it was the light value, a
+near-white block on a dark page) and `--foreground` on it reaches 14.4:1.
 
 **Tracks.** The empty part of a `Slider`, of the password strength meter and
 the `Drawer` handle use `--track` (`bg-track`), and the `Slider`'s range and
 thumb border `--track-fill` (`bg-track-fill`, `border-track-fill`). In the
-dark theme the track reaches 3.5:1 on `--background` and 3.2:1 on `--card`
-(WCAG 1.4.11; `bg-muted`, a dark surface now, gave 1.4:1 and 1.2:1), and the
+dark theme the track reaches 3.7:1 on `--background` and 3.5:1 on `--card`
+(WCAG 1.4.11; `bg-muted`, a dark surface now, gives only 1.2:1 and 1.1:1), and the
 fill 3.3:1 on the track. The light theme keeps a pale track (`--track` is the
-light `--muted`) and `--track-fill` is `--primary`: the thumb, 6.8:1 on the
+light `--muted`) and `--track-fill` is `--primary`: the thumb, 7.3:1 on the
 page, shows the value. A track, bar, handle or divider of your own drawn with
 `bg-muted` is near invisible in the dark theme now that `--muted` is a dark
 surface: draw it with `bg-track`.
@@ -1052,6 +1064,158 @@ are, without growing what is painted (nothing changes for a mouse):
 A toast covering a control is out of scope: it physically hides what is under
 it.
 
+## Themes
+
+Fourteen ready-made themes ship as stylesheets, each generated from a preset of
+`@nxgt/material-core/theme/presets` with every colour token in light and dark,
+the radius and the font: `lavande` (the default), `ocean`, `foret`, `ambre`,
+`ardoise`, `corail`, `menthe`, `prune`, `sable`, `slate`, `pink`, `bleumono`,
+`bluemoon` and `teal`.
+
+```css
+@import "tailwindcss";
+@import "@nxgt/material/styles.css";
+@import "@nxgt/material/themes/ocean.css"; /* after styles.css */
+```
+
+```html
+<html data-nxgt-theme="ocean">
+```
+
+```tsx
+<section data-nxgt-theme="ocean" data-theme="dark">
+  {/* a dark Ocean zone, in a page of any theme */}
+</section>
+```
+
+A theme applies to the element that carries `data-nxgt-theme`: `<html>` for the
+whole page, or any element for a **zone** (a card in another theme, a preview).
+Nothing to change for an app that does not use one: `styles.css` keeps the
+Lavande tokens on `:root`.
+
+- **Dark mode.** The theme is dark when the element has `.dark` or
+  `data-theme="dark"`, or sits inside an element that has. A zone with
+  `data-theme="dark"` is dark in a light page. A light zone inside a dark page
+  is not supported.
+- **A zone paints its own text.** The shipped CSS gives `[data-nxgt-theme]`
+  `color: var(--foreground)`, and a zone with a forced mode
+  (`data-theme="dark"`, which is what `NxgtTheme mode="dark"` sets) also
+  `background: var(--background)`, so a dark zone in a light page is dark with
+  no class of yours. Both sit in `@layer base`: a utility on the zone
+  (`text-primary`, `bg-card`) still wins.
+- **Zones are self-contained.** The theme file declares every token on the zone,
+  and the derived ones (`--primary-text`, the tone texts and containers, the
+  field box) are computed there, so a zone never shows its parent's colours.
+  Utilities such as `bg-primary` read the token where they are used.
+- **Cascade.** The theme block beats `:root` by source order, so import it after
+  `styles.css`. Once an app opts into a theme, its `:root { --primary: … }`
+  override placed before the theme file no longer wins. Override on the same
+  selector after the theme (`[data-nxgt-theme="ocean"] { --primary: … }`).
+- **Fonts.** The theme sets `font-family` on its own element; a font stack that
+  is not installed falls back to the system face.
+
+### The provider and zones
+
+`@nxgt/material/themes` holds the React side: the provider that keeps the chosen
+theme, and the zone.
+
+```tsx
+import { NxgtTheme, NxgtThemeProvider } from '@nxgt/material/themes';
+
+<NxgtThemeProvider defaultTheme="ocean">
+  <App />
+  <NxgtTheme theme="prune" mode="dark" className="rounded p-4">
+    {/* a dark Prune zone */}
+  </NxgtTheme>
+</NxgtThemeProvider>
+```
+
+- **`NxgtThemeProvider`** (props `themes`, default `THEME_PRESETS`; `defaultTheme`, default `'lavande'`; `defaultMode`, default the active theme's `colorScheme`) goes at the root and renders no element. It holds the
+  registry (`themes`, default the 14 presets; add your own `defineTheme`
+  results), reads and writes the name stored under `nxgt-theme`
+  (`useTheme().setThemeName`) and is **the one writer of `<html
+  data-nxgt-theme>`** while it is mounted (without a provider the store
+  writes it). A stored name the registry does not know resolves to
+  `defaultTheme` (default `lavande`), and so does a key another tab clears;
+  `setThemeName` of a name it does not know is ignored, with a warning in
+  development. On the server and while hydrating the name is `defaultTheme`;
+  the boot script has already put a stored name on `<html>`, and the provider
+  leaves it alone until the stored name has been read. `useTheme().themeName`
+  is the nearest provider's (or zone's) name, so it agrees with
+  `useThemeContext()`; without either it is the stored name or `lavande`.
+- **`NxgtTheme`** is a zone: a `div` with `data-nxgt-theme` (and
+  `data-theme="dark"` for `mode="dark"`; a `data-theme` you pass yourself is
+  kept when `mode` is left out), whose children read that theme.
+  `theme` is a `Theme` or the name of one the provider knows; a bare name with
+  no provider has no registry, so its `Background` falls back to the defaults.
+  `asChild` puts the attributes on your element. Import the theme's stylesheet
+  yourself. Zones nest; a light zone inside a dark page is not supported.
+  The nearest zone's tokens win, with one limit: in A > B > A, a `.dark` element
+  *below* the inner A (not on it) takes Lavande's dark tokens, not A's. Put
+  `mode="dark"` on the inner `NxgtTheme` instead.
+- **`useThemeContext()`** returns `{ name, theme, background, defaultMode }` for the nearest
+  zone or provider, and `null` outside both.
+- **The background follows the theme.** A `Background` with no props, and
+  `ActivityLayout`, draw the nearest theme's `background`; see
+  [Defaults from the theme](./backgrounds.md#defaults-from-the-theme) and
+  [The theme's background](./app-shell.md#the-themes-background).
+- **Nothing is added without it.** An app with no provider and no zone, or on
+  Lavande, renders the same markup, apart from one attribute and the page
+  background (white in light, the shared night in dark; `neutrals: 'tinted'`
+  keeps a tinted page).
+
+### Let users choose
+
+`ThemePicker` (`@nxgt/material/theme-picker`, its own entry so `/themes` stays small) is the chooser: a radiogroup of tiles, each previewing its own theme
+(swatches and a mini background), with the light / dark / system control. Mount it
+under the provider; it reads and writes the provider's name.
+
+```css
+@import "@nxgt/material/theme-picker.css"; /* after styles.css */
+```
+
+```tsx
+import { ThemePicker } from '@nxgt/material/theme-picker';
+
+<ThemePicker layout="list" showBackground={false} />;
+```
+
+The tiles' stylesheet is opt-in (about 3.3 KB gzipped), so an app that does not
+use the picker does not ship it; `styles.css` does not carry it.
+
+Pass `themes` to choose among fewer or to add an app theme, `value` and
+`onValueChange` to hold the choice yourself, `showMode={false}` (default `true`) when the mode has
+its own control. Labels come from each theme's `label` and the
+`material.theme-picker.*` keys.
+
+### From token overrides to a theme
+
+Before 3.8 an app recoloured itself by overriding `--color-*` or `--primary` on
+`:root`. Both still work on `:root`, but a **theme** is the way to customise:
+it solves a whole palette (light and dark, every derived colour) from one to
+three seed colours, checks it against AA, and applies to a page or a zone.
+
+| You wrote | Write |
+| --- | --- |
+| `:root { --primary: …; --secondary: … }` and the matching `.dark` block | `defineTheme({ name: 'brand', colors: { primary: '#0b6bcb' } })`, generated by `nxgtMaterial({ themes })` ([Themes for your app](./themes.md)) |
+| a wrapper that sets `--color-primary` | `<NxgtTheme theme="brand">`, or `--primary` on the wrapper for a one-off |
+| `backdrop={false}` on `ActivityLayout` for the gradient | leave `backdrop` out (the theme's background); `false` is now a plain page |
+
+A wrapper that overrides `--color-*` **no longer recolours utilities**:
+`bg-primary` reads `var(--primary)` where it is used. Set `--primary` on the
+wrapper (its derived tokens, such as `--primary-text`, are computed where they
+are declared, so they do not follow), or use a theme zone, which re-declares
+them. A `:root` override placed before an imported theme file stops winning
+(see Cascade above).
+
+A third change comes with the same `@theme inline`: **`class="dark"`,
+`data-theme="dark"` or a token such as `--primary:` set on a sub-element (not
+`<html>`) now recolours the utilities below it.** Utilities used to read a
+colour computed once on `:root`, so such a wrapper changed nothing for
+`bg-primary` or `text-foreground`; now it does. Search your app for those three
+on a selector or element other than `<html>`/`:root`: a nested dark card or a
+scoped brand colour will now show.
+
 ## Dark mode
 
 Dark values apply under a `.dark` class **or** a `data-theme="dark"`
@@ -1095,45 +1259,83 @@ function useTheme(): {
   theme: ResolvedTheme;          // what is shown: 'system' resolved through prefers-color-scheme
   preference: ThemePreference;   // what the user chose
   updateTheme(next: ThemePreference): void; // stores it and applies it to <html>
+  themeName: ThemeName;          // the nearest provider's or zone's; else the stored name, 'lavande' when none (and on the server)
+  setThemeName(next: ThemeName): void;      // stores it; sets <html data-nxgt-theme> unless a provider does
 };
+
+// useTheme({ defaultMode }): the mode when none is stored. Default: the provider's
+// defaultMode, else the active theme's colorScheme, else 'system'.
 ```
 
 - The preference is stored in `localStorage` under `theme`, **JSON-encoded**
   (`"dark"`, with the quotes, as `react-use`'s `useLocalStorage` writes it).
-  Choosing `system` removes the key.
-- `updateTheme` sets the `dark` class and `color-scheme` on `<html>`. Reading
-  `useTheme()` alone does not apply anything.
+  Choosing `system` removes the key, unless a first visit would not be `system`
+  (a theme suggests `dark`): then `"system"` is stored, or clearing it would
+  bring the suggestion back.
+- **The first-visit mode.** A theme may suggest one (`colorScheme` in
+  `defineTheme`: `bluemoon` suggests `dark`). With no stored mode, the boot
+  script, `useTheme()` (so `theme`, `preference`, `CodeBlock` and `ThemeToggle`)
+  all use it: under `NxgtThemeProvider` it is the active theme's, or the
+  provider's `defaultMode`. With no provider, the stored name of a library
+  preset still gives its `colorScheme` (`bluemoon`: dark); an app's own theme
+  needs the provider, or `useTheme({ defaultMode })`. A zone never changes the
+  page's mode. The class on `<html>` comes from the boot script before the
+  first paint, and then from `NxgtThemeProvider`, which applies the resolved
+  mode whenever the theme name or the mode changes (so `setThemeName('bluemoon')`
+  turns the page dark with no `ThemeToggle` mounted); with no provider, a
+  mounted `ThemeToggle` or `updateTheme` does.
+- The theme name is stored apart, under `nxgt-theme`, also JSON-encoded, so
+  the mode and the name change independently. `setThemeName` sets
+  `data-nxgt-theme` on `<html>` (through the provider, when there is one); Lavande, the default, takes the attribute off
+  (the boot script never sets it for Lavande either), so an app that never
+  calls it gets no attribute. A name that is not a well-formed theme name
+  (`[a-z][a-z0-9-]*`) reads as `lavande`.
+- `ThemeName` is augmentable, like `AppTones`: an app adds its own themes with
+  `declare module '@nxgt/material' { interface NxgtThemes { brand: true } }`.
+  Out of the box it types the 14 presets; an app theme needs the same
+  augmentation to pass `setThemeName`. `DEFAULT_THEME` (`'lavande'`) is exported too.
+- `resolveThemeName(stored, known, fallback)` and `applyThemeName(name)` are
+  exported beside `resolveTheme` and `applyResolvedTheme`, for a bundled entry.
 - Every `useTheme()` call reads one shared store, so a component that reads
   `theme` (the code blocks and the code editor pick their highlighting theme
   this way) re-renders when any other component calls `updateTheme`. A change
-  made in another tab arrives through the `storage` event.
+  made in another tab arrives through the `storage` event (for the name, it
+  also sets `data-nxgt-theme` there).
 - On the server and during hydration the preference reads as `system` and
   `prefers-color-scheme` as light, so `theme` is `light`; the stored value and
   the real color scheme take over right after, without a hydration mismatch.
+  The name reads as `lavande` the same way, and the attribute is only ever
+  written on the client (by the boot script, or `setThemeName`), never rendered
+  by the server: put `suppressHydrationWarning` on `<html>`.
 
 ### No flash on load: a boot script
 
 `useTheme` and `ThemeToggle` run after React mounts, so a stored `dark`
-preference would first paint light. Apply it before the first paint with an
-inline script in `<head>`. It is the same logic as `resolveTheme` +
-`applyResolvedTheme`, written without imports because an inline script cannot
-have any:
+preference or a stored theme name would first paint the default. Apply both
+before the first paint with an inline script in `<head>`. It sets the `dark`
+class and `color-scheme` from the mode (key `theme`) and `data-nxgt-theme`
+from the name (key `nxgt-theme`; Lavande sets no attribute), without imports,
+because an inline script cannot have any. `themeBootScript` from
+`@nxgt/material/themes` generates it, and takes the app's own theme names and
+defaults:
 
-```html
-<script>
-  (function () {
-    var stored = null;
-    try { stored = JSON.parse(localStorage.getItem('theme') || 'null'); } catch (e) {}
-    var preference = stored === 'light' || stored === 'dark' ? stored : 'system';
-    var dark = preference === 'dark' ||
-      (preference === 'system' && matchMedia('(prefers-color-scheme: dark)').matches);
-    document.documentElement.classList.toggle('dark', dark);
-    document.documentElement.style.colorScheme = dark ? 'dark' : 'light';
-  })();
-</script>
+```tsx
+import { themeBootScript } from '@nxgt/material/themes';
+
+// <head>: add the nonce when the CSP uses one, or hash the script.
+<script dangerouslySetInnerHTML={{ __html: themeBootScript({ themes: ['lavande', 'ocean', 'brand'] }) }} />
 ```
 
-Read the value with `JSON.parse`: `localStorage.getItem('theme')` returns
+The constant `THEME_BOOT_SCRIPT` is the same script for the 14 presets, with a
+stable CSP hash. A stored name the script does not know falls back to
+Lavande. When no mode is stored, the first visit takes `defaultMode` if you
+pass one, else the **active theme's `colorScheme`** (`schemes` maps a theme
+name to it; the presets' are built in, so a first visit on `bluemoon` opens
+dark; `nxgtMaterial({ themes })` fills it from your themes), else `system`. A
+stored mode always wins. Put `suppressHydrationWarning` on `<html>`: the script changes its
+`class`, `style` and `data-nxgt-theme` before React hydrates.
+
+Read a stored value with `JSON.parse`: `localStorage.getItem('theme')` returns
 `"dark"` with its quotes, which a plain comparison never matches.
 
 In a bundled client entry that runs first (an SPA's `main.tsx`), the exported
@@ -1152,11 +1354,13 @@ applyResolvedTheme(resolveTheme(stored, matchMedia('(prefers-color-scheme: dark)
 ```
 
 ```ts
-function resolveTheme(stored: string | null | undefined, prefersDark: boolean): {
+function resolveTheme(stored: string | null | undefined, prefersDark: boolean, defaultMode?: ThemePreference): {
   theme: ResolvedTheme;
   preference: ThemePreference;
 };
 function applyResolvedTheme(theme: ResolvedTheme): void; // no-op without `document`
+function resolveThemeName(stored: string | null | undefined, known: readonly string[] | undefined, fallback: string): string;
+function applyThemeName(name: string): void; // sets <html data-nxgt-theme>, removes it for 'lavande'; no-op without `document`
 ```
 
 In a server-rendered app, keep the inline script: the server does not know the

package/docs/guides/vite-plugin.md

@@ -32,6 +32,7 @@ Every part is on by default and has an opt-out. It needs `vite` 5.2 or later (6,
 | `fonts.katex` | `true` | Never inline a font as a `data:` URI (`cspAssetsInlineLimit`), composed with your own `build.assetsInlineLimit` |
 | `fonts.sans` | `'inter'` | Loads self-hosted Inter when `@fontsource-variable/inter` is installed (otherwise warns and keeps the system stack), in your root stylesheet, and sets `--font-sans`; `false` to keep the system stack and silence the warning. `fonts: false` turns both off |
 | `styles.check` | `true` | Fails `vite build` when the library's stylesheet is never imported (`@nxgt/material/styles.css`, or the compiled one through `@import "@nxgt/material";`), or `styles.css` is imported without the `@source` line Tailwind needs |
+| `themes` | off | Generates your themes' stylesheets and types and injects the boot script: see [Themes](#themes) |
 | `pdf` | on | pdfkit's standard fonts (`pdfkitStandardFonts()`): a no-op unless pdfkit goes through the bundle; and a dev-server route for the pdf.js worker (the `pdf.worker` row). `pdf: false` turns both off |
 | `pdf.bundle` | `false` | Also adds the renderer to `ssr.noExternal`, for a server whose runtime image has no `node_modules` (see [Rendering PDFs on a bundled server](#rendering-pdfs-on-a-bundled-server)) |
 | `pdf.worker` | `true` | Dev server only: answers `pdf.worker.min.mjs` in Vite's pre-bundle folder (`…/deps/`, any `cacheDir`, so Storybook and Vitest browser mode too) with the installed `@nxgt/material/dist/pdf.worker.min.mjs` (else `pdfjs-dist/build/…`). Vite 5 to 7 pre-bundle the library without the worker, so the readers' worker URL is a 404 there; Vite 8 needs no route, and `@nxgt/material-vue` none (it imports the worker with `?url`). `pdf: { worker: false }` drops it; then set `configurePdfReader({ workerSrc })` instead (see [the PDF reader guide](pdf-reader.md#bundlers)) |
@@ -91,6 +92,31 @@ Pick nonce mode when a server renders or serves your HTML and can run
 strict option for styles: `style-src-elem 'self' 'nonce-…'`, no
 `'unsafe-inline'`.
 
+## Themes
+
+`themes` (off unless given) generates the stylesheets and types of your own
+`defineTheme()` modules (see [Themes for your app](themes.md)) and puts the boot
+script that restores the stored mode and theme name first in `<head>`.
+
+```ts
+nxgtMaterial({ themes: { entries: 'src/themes/*.ts' } });
+```
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `themes.entries` | required | Paths or globs of the theme modules; each module's default or named exports are themes |
+| `themes.outDir` | `'src/themes/generated'` | Where `<name>.css` and `nxgt-themes.d.ts` are written, relative to the project root. Commit them |
+| `themes.types` | `true` | Write `nxgt-themes.d.ts`, which merges your tones into `AppTones` and your theme names into `NxgtThemes` |
+| `themes.boot` | `true` | The boot script, with the presets' and your theme names. `{ defaultTheme, defaultMode }` sets a first visit's theme and mode; without `defaultMode`, a first visit takes the active theme's `colorScheme` (yours included), then `system` |
+| `themes.onWarning` | `'warn'` | Contrast and tone warnings go to Vite's logger; `'error'` fails the build |
+
+The modules are loaded with Vite's module runner (Vite 6.1 or later), so a `.ts`
+theme file needs no loader. A file is rewritten only when its bytes change, so HMR
+does not loop; in dev the plugin watches the modules and what they import. The boot
+script is an inline script: in hash mode its hash goes to `nxgt-csp.json` with the
+others, in nonce mode it carries the placeholder. The dev report-only header lists
+it as a violation, like Vite's own dev scripts.
+
 ## The dev server
 
 `csp.dev` sends `Content-Security-Policy-Report-Only` (hash mode: no nonce,