@nxgt/material 3.7.5 → 3.8.1

package/docs/roadmap.md

@@ -287,6 +287,31 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **Themes** (in the next prerelease) — 14 ready-made themes (Lavande, the
+  default, then Océan, Forêt, Ambre, Ardoise, Corail, Menthe, Prune, Sable,
+  Slate, Pink, Bleu mono, Blue moon and Teal) as stylesheets,
+  `@import "@nxgt/material/themes/<name>.css"` after `styles.css`, each with
+  light and dark and each also usable on a single element: `[data-nxgt-theme]`
+  makes a zone that paints its own text. `NxgtThemeProvider`, `NxgtTheme` and
+  `useThemeContext` in `@nxgt/material/themes` hold the registry and the
+  persisted choice; `useTheme()` gains `themeName` and `setThemeName`, shared
+  across components and tabs and hydration-safe. `Background` and
+  `ActivityLayout` take the theme's background, and `ThemePicker`
+  (`@nxgt/material/theme-picker`, with its opt-in `theme-picker.css`) is a
+  radiogroup of theme tiles beside the light / dark / system control. Define
+  your own with `defineTheme()` from one to three seed colours: the Vite
+  plugin's `themes` option (or the `nxgt-theme` command) writes the CSS and
+  typings and adds the boot script. The page is white in light and a shared
+  night in dark for every theme (`neutrals: 'tinted'` brings back a tinted
+  page). `Background` also draws a `moon` preset.
+  Four behaviour changes: a wrapper that overrides `--color-*` no longer
+  recolours utilities (set `--primary`, or use a theme), `ActivityLayout`
+  `backdrop={false}` now draws a plain page, `class="dark"`, `data-theme="dark"`
+  or a token such as `--primary:` on a sub-element now recolours the utilities
+  below it, and the default page is white in light and a shared night in dark
+  (see above). React only; the Vue port is on the Vue roadmap.
+  ([Theming](guides/theming.md#themes), [Themes for your app](guides/themes.md))
+
 - **44 `Background` presets, and 22 motif shapes** — `Background` from
   `@nxgt/material/backgrounds` draws six light presets (`rays`, `halo`,
   `plasma`, `glass`, `ripples`, `blobs`), six geometry presets (`hexagons`,

package/docs/troubleshooting.md

@@ -28,6 +28,7 @@ words in your error.
 - [Components render unstyled, with no error](#components-render-unstyled-with-no-error)
 - [A link is blue and underlined on hover and focus](#a-link-of-mine-or-of-a-component-is-blue-and-underlined-on-hover-and-focus)
 - [The light and dark neutrals turned violet after upgrading to 3.6](#the-light-and-dark-neutrals-turned-violet-after-upgrading-to-36)
+- [A theme's colours do not show](#a-themes-colours-do-not-show)
 - [Math renders in the system fonts](#math-renders-in-the-system-fonts)
 - [`<Icon>` renders nothing](#icon-renders-nothing)
 - [An accessibility audit reports low contrast on a badge, a button, a toast or a menu entry](#an-accessibility-audit-reports-low-contrast-on-a-badge-a-button-a-toast-or-a-menu-entry)
@@ -722,6 +723,28 @@ first three, on an older version, add the ones you use after it:
 `CodeBlock`'s theme and the other components' CSS have no file you can
 import before 2.2.0: upgrade.
 
+### A theme's colours do not show
+
+**When:** `data-nxgt-theme="ocean"` is set, `themes/ocean.css` is imported, and the page still looks like the default (Lavande).
+**Why:** the theme's block has the same specificity as `:root`, so it wins by source order only. Imported before `styles.css`, it loses. A theme file that is not imported at all does nothing either.
+**Fix:**
+
+```css
+@import "@nxgt/material/styles.css";
+@import "@nxgt/material/themes/ocean.css"; /* after styles.css */
+```
+
+### ThemePicker tiles look unstyled
+
+**When:** `ThemePicker` renders, but its tiles are plain buttons with no swatches or mini background.
+**Why:** the picker's stylesheet is opt-in and not part of `styles.css`, so an app that does not import it ships nothing for it.
+**Fix:**
+
+```css
+@import "@nxgt/material/styles.css";
+@import "@nxgt/material/theme-picker.css"; /* after styles.css */
+```
+
 ### Math renders in the system fonts
 
 **When:** a formula in `Markdown` (or `ChatMarkdown`) shows in a serif or
@@ -933,10 +956,10 @@ class instead: the tone already colours the text:
 <p className="text-sm text-error-text">Enter a valid email</p>
 ```
 
-Setting `--error` or `--error-text` on an element below the root (a `style`
-on a section) changes nothing: `@theme` resolves `--color-error-text` on the
-root. Below the root, set `--color-error-text` (and `--color-error` for fills)
-on that element, or put the override on the root.
+Setting only `--error` on an element below the root (a `style` on a section)
+does not move `text-error-text`: the derived token is computed on the root.
+Set `--error-text` on that element too, put the override on the root, or use a
+theme zone, which re-declares the derived tokens.
 
 ### An accessibility audit reports low contrast on primary text in the dark theme
 
@@ -959,7 +982,7 @@ fills, borders and rings:
 
 An app that overrides `--primary` under `:root` and `.dark, [data-theme="dark"]`
 gets `--primary-text` for free; set `--primary-text` after it to choose another
-colour. On an element below the root, set `--color-primary-text`.
+colour. On an element below the root, set `--primary-text` too.
 
 The same goes for a primary mark that is not text: a bar, a dot, a selected or
 focused border, a ring or a spinner arc. In dark, `--primary` is only 2.1 to
@@ -1319,6 +1342,11 @@ blobs, or when the page loads a copy of `styles.css` older than 3.5.
 **Fix:** import `Background` from `@nxgt/material/backgrounds`, import
 `@nxgt/material/backgrounds.css` once, and keep `@nxgt/material` current.
 
+The same holds for a theme's background (no `backdrop` given, under a theme
+other than Lavande): without `backgrounds.css` it has no look. And
+`backdrop={false}` no longer keeps the gradient: it draws a plain page, so leave
+`backdrop` out to get the gradient back.
+
 ```tsx
 import { Background } from '@nxgt/material/backgrounds';
 import '@nxgt/material/backgrounds.css';
@@ -6782,13 +6810,13 @@ How the presets work is in the [Backgrounds guide](guides/backgrounds.md).
 ### `Background: preset "<id>" is not available in this library yet; drawing "gradient".`
 
 **When:** in development (not when `NODE_ENV` is `production`), the first time a `Background` from `@nxgt/material/backgrounds` gets a `preset` that this library does not draw yet, or a typo from JavaScript. It is printed once per id.
-**Why:** `BACKGROUND_PRESETS` lists the 44 presets; this library draws the ones in `AVAILABLE_BACKGROUND_PRESETS`. Any other id draws the gradient.
+**Why:** `BACKGROUND_PRESETS` lists the 45 presets; this library draws the ones in `AVAILABLE_BACKGROUND_PRESETS`. Any other id draws the gradient.
 **Fix:** use an available preset:
 
 ```ts
 import { AVAILABLE_BACKGROUND_PRESETS } from '@nxgt/material/backgrounds';
 
-console.log(AVAILABLE_BACKGROUND_PRESETS); // all 44 ids: 'gradient', 'grain', 'mesh', 'aurora', …, 'sport'
+console.log(AVAILABLE_BACKGROUND_PRESETS); // all 45 ids: 'gradient', 'grain', 'mesh', 'aurora', …, 'sport', 'moon'
 ```
 
 ### A preset `Background` looks bare, with no error

package/lib/backgrounds/backgrounds.css

@@ -49,6 +49,8 @@
 @import "./css-react/music.css";
 @import "./css-react/travel.css";
 @import "./css-react/sport.css";
+/* the moon (React only) */
+@import "./css-react/moon.css";
 /* motifs */
 @import "./css/motifs.css";
 @import "./css/shapes.css";

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

@@ -0,0 +1,97 @@
+/* The `moon` preset: a thin crescent in a wide halo among a few stars. The
+ * scene drawn by core's `buildBackgroundScene` carries the geometry (the
+ * halo's gradient stops are `s3`, the crescent `k2`, the stars `k1` and
+ * `k2`); this file gives it a faint wash, the strength each intensity sets,
+ * and a silver moon in dark. Motion (opt-in, `animated`): the stars twinkle,
+ * 8 s a leg; the delay of each (`l1..l4`) is a class, so the markup holds no
+ * inline style. React only: nothing in the shared `css/` folder. */
+@import "../css/scene.css";
+
+@layer components {
+	[data-background="moon"] > [data-layer="wash"] {
+		position: absolute;
+		inset: 0;
+		background:
+			radial-gradient(
+				ellipse 70% 60% at 82% 14%,
+				color-mix(in oklab, var(--nxgt-bg-c3) var(--nxgt-bg-a1), transparent),
+				transparent 72%
+			),
+			radial-gradient(
+				ellipse 60% 55% at 12% 92%,
+				color-mix(in oklab, var(--nxgt-bg-c1) var(--nxgt-bg-a1), transparent),
+				transparent 70%
+			);
+	}
+
+	[data-background="moon"] > [data-scene] {
+		overflow: hidden;
+		container: nxgt-moon / inline-size;
+	}
+
+	/* The scene is written for 0.8 at the default strength: subtle 0.47,
+	 * vivid the full 1. The root class makes it (0,4,0), above the motif rule (0,3,0). */
+	[data-background="moon"] > [data-scene] > .mn :is(.mo, .mh) {
+		opacity: calc(var(--nxgt-bg-op) / 0.9);
+	}
+
+	/* The scene has no viewBox (lengths are pixels, positions shares of the
+	 * container): the moon and the stars draw past their own origin. */
+	[data-background="moon"] > [data-scene] .pt {
+		overflow: visible;
+	}
+
+	/* A narrow container: half the size, so the moon stays whole in the top right corner. */
+	@container nxgt-moon (max-width: 640px) {
+		[data-background="moon"] > [data-scene] .mg .md {
+			transform: scale(0.5);
+		}
+	}
+
+	/* In light the scene is multiplied into the page and the crescent is
+	 * lighter still: a faint watermark. */
+	[data-background="moon"] > [data-scene] {
+		mix-blend-mode: multiply;
+	}
+	[data-background="moon"] > [data-scene] .md {
+		opacity: 0.55;
+	}
+
+	/* In dark it adds nothing but light, and the moon is silver, lighter than the lifted tone. */
+	:is(.dark, [data-theme="dark"]) [data-background="moon"] > [data-scene],
+	[data-background="moon"]:is(.dark, [data-theme="dark"]) > [data-scene] {
+		mix-blend-mode: normal;
+	}
+	:is(.dark, [data-theme="dark"]) [data-background="moon"] > [data-scene] .md,
+	[data-background="moon"]:is(.dark, [data-theme="dark"]) > [data-scene] .md {
+		color: color-mix(in oklab, var(--nxgt-bg-c2) 30%, white);
+		opacity: 0.78;
+	}
+}
+
+@media (prefers-reduced-motion: no-preference) {
+	@keyframes nxgt-bg-moon-twinkle {
+		to {
+			opacity: 0.3;
+		}
+	}
+
+	@layer components {
+		[data-background="moon"][data-animated] > [data-scene] .tw {
+			animation: nxgt-bg-moon-twinkle 8s ease-in-out infinite alternate
+				var(--nxgt-bg-play, running);
+		}
+		[data-background="moon"][data-animated] > [data-scene] .l1 {
+			animation-delay: 0s;
+		}
+		[data-background="moon"][data-animated] > [data-scene] .l2 {
+			animation-delay: -2s;
+		}
+		[data-background="moon"][data-animated] > [data-scene] .l3 {
+			animation-delay: -4s;
+		}
+		[data-background="moon"][data-animated] > [data-scene] .l4 {
+			animation-delay: -6s;
+		}
+	}
+}

package/lib/components/theme-tokens.css

@@ -3,7 +3,7 @@
  * after importing the stylesheet, under the same selectors. */
 :root {
 	--radius: 0.625rem;
-	--background: oklch(0.973 0.008 293.9);
+	--background: oklch(1 0 0);
 	--foreground: oklch(0.227 0.017 290);
 	--card: oklch(1 0 0);
 	--card-foreground: oklch(0.227 0.017 290);
@@ -13,9 +13,8 @@
 	--primary: oklch(46% 0.1135 276.35);
 	--primary-foreground: oklch(0.984 0.003 247.858);
 	/* Primary drawn as text or an icon on a normal surface (`text-primary-text`):
-	   the colour mixed 4 % toward black in light, which keeps it 7.3:1 or more on
-	   the violet page (7.9:1 on a Card; the colour itself gives 6.8:1 on the
-	   page); the dark theme lifts it. */
+	   the colour mixed 4 % toward black in light, which keeps it 7.9:1 on
+	   the white page and on a Card (the colour itself gives 7.3:1); the dark theme lifts it. */
 	--primary-text: color-mix(in oklab, var(--primary) 96%, black);
 	/* Primary drawn as a non-text mark (WCAG 1.4.11, 3:1): an indicator bar or dot,
 	   a selected or focused border, a ring, a spinner arc, a progress fill
@@ -23,7 +22,7 @@
 	   the dark theme lifts it. */
 	--primary-indicator: var(--primary);
 	/* --secondary, --success and --info are 0.02 darker than before: on the
-	   violet page tint (--background, 97.3 %) their own 15 % tonal tint gave the
+	   former violet page tint (--background, 97.3 %) their own 15 % tonal tint gave the
 	   text 4.3 to 4.5:1; now 4.7:1 or more on the page and on a Card. */
 	--secondary: oklch(48% 0.1135 245.65);
 	--secondary-foreground: oklch(0.984 0.003 247.858);
@@ -58,8 +57,8 @@
 	--destructive: var(--error);
 	--border: oklch(0.912 0.016 293.7);
 	--input: oklch(0.912 0.016 293.7);
-	/* The focus indicator (WCAG 1.4.11, 3:1): 3.40:1 on --background, 3.69:1 on
-	   --card, 3.23:1 on --muted. */
+	/* The focus indicator (WCAG 1.4.11, 3:1): 3.68:1 on --background, 3.68:1 on
+	   --card, 3.22:1 on --muted. */
 	--ring: oklch(0.62 0.04 291);
 	--chart-1: oklch(0.646 0.222 41.116);
 	--chart-2: oklch(0.6 0.118 184.704);
@@ -98,41 +97,41 @@
 
 .dark,
 [data-theme="dark"] {
-	--background: oklch(0.192 0.016 290.5);
+	--background: oklch(0.15 0.026 273);
 	--foreground: oklch(0.943 0.012 291.3);
-	--card: oklch(0.232 0.019 289.4);
+	--card: oklch(0.19 0.019 289.4);
 	--card-foreground: oklch(0.943 0.012 291.3);
-	--popover: oklch(0.232 0.019 289.4);
+	--popover: oklch(0.19 0.019 289.4);
 	--popover-foreground: oklch(0.943 0.012 291.3);
 	--primary: oklch(46% 0.1135 276.35);
 	--primary-foreground: oklch(0.995 0.002 291.3);
 	/* Mixed 60 % toward white (the tonal Button labels' recipe): readable as text
 	   on --background and --card. */
 	--primary-text: color-mix(in oklab, var(--primary) 40%, white);
-	/* --primary itself is 2.5:1 on --background, 2.3:1 on --card and 2.1:1 on
-	   --muted. Mixed 25 % toward white: 4.5:1, 4.1:1 and 3.7:1. */
+	/* --primary itself is 2.7:1 on --background, 2.5:1 on --card and 2.3:1 on
+	   --muted. Mixed 25 % toward white: 4.8:1, 4.5:1 and 4.2:1. */
 	--primary-indicator: color-mix(in oklab, var(--primary) 75%, white);
-	/* Brighter than the light one: it is read as text on the dark surfaces (6.3:1
-	   on --background, 5.8:1 on --card; 4.6:1 on its own 15 % tonal tint over a
+	/* Brighter than the light one: it is read as text on the dark surfaces (6.8:1
+	   on --background, 6.4:1 on --card; 5.1:1 on its own 15 % tonal tint over a
 	   Card). A filled secondary surface mixes it toward --background (the opaque
-	   70 % mix) to keep 5.2:1 under its near-white text (4.9:1 over a Card). */
+	   70 % mix) to keep 5.4:1 under its near-white text (4.9:1 over a Card). */
 	--secondary: oklch(0.675 0.1135 245.65);
 	--secondary-foreground: oklch(0.995 0.002 291.3);
-	--muted: oklch(0.27 0.022 290);
+	--muted: oklch(0.228 0.022 290);
 	--muted-foreground: oklch(0.725 0.03 292.2);
-	/* 3.5:1 on --background, 3.2:1 on --card; the fill 3.3:1 on the track. */
+	/* 3.7:1 on --background, 3.5:1 on --card; the fill 3.3:1 on the track. */
 	--track: oklch(0.53 0.03 290);
 	--track-fill: oklch(0.85 0.09 276.35);
 	--tooltip: oklch(0.925 0.012 291.3);
 	--tooltip-foreground: oklch(0.446 0.043 291);
-	--accent: oklch(0.27 0.022 290);
+	--accent: oklch(0.25 0.022 290);
 	--accent-foreground: oklch(0.943 0.012 291.3);
 	--error: oklch(0.577 0.245 27.325);
 	--error-foreground: oklch(0.995 0.002 291.3);
 	/* --error stays the fill under near-white text; as text it would give only
-	   3.9:1 on --background and 3.5:1 on --card. Lightened (76 % --error), 5.85
-	   and 5.35:1, and 4.78:1 on a focused error menu item (bg-error/20 over the
-	   popover; 4.45:1 at the former 80 %, which missed 4.5:1 once rendered). */
+	   4.0:1 on --background and 3.8:1 on --card. Lightened (76 % --error), 6.25
+	   and 5.9:1, and 5.2:1 on a focused error menu item (bg-error/20 over the
+	   popover; the former 80 % missed 4.5:1 once rendered). */
 	--error-text: color-mix(in oklab, var(--error) 76%, white);
 	/* The light brights: on the dark surfaces they read as text and as the
 	   badge's 60% tint, which keeps its contrast under near-white text (success
@@ -141,15 +140,15 @@
 	--success-foreground: oklch(0.995 0.002 291.3);
 	--info: oklch(0.707 0.165 254.624);
 	--info-foreground: oklch(0.995 0.002 291.3);
-	/* Amber too, as text: 6.7:1 on --background and 6.1:1 on --card, 5.9:1 and
-	   5.3:1 on its 10% tint; the badge's 60% fill under near-white text is
-	   5.8:1 on a page and 5.5:1 on a Card. */
+	/* Amber too, as text: 7.2:1 on --background and 6.7:1 on --card, 6.4:1 and
+	   5.9:1 on its 10% tint; the badge's 60% fill under near-white text is
+	   6.1:1 on a page and 5.8:1 on a Card. */
 	--warning: oklch(0.7 0.15 70);
 	--warning-foreground: oklch(0.995 0.002 291.3);
 	--destructive: oklch(0.704 0.191 22.216);
-	--border: oklch(0.301 0.025 291.4);
-	--input: oklch(0.34 0.027 291.4);
-	/* 3.78:1 on --background, 3.45:1 on --card, 3.09:1 on --muted. */
+	--border: oklch(0.259 0.025 291.4);
+	--input: oklch(0.298 0.027 291.4);
+	/* 4.05:1 on --background, 3.80:1 on --card, 3.50:1 on --muted. */
 	--ring: oklch(0.551 0.03 290);
 	--chart-1: oklch(0.488 0.243 264.376);
 	--chart-2: oklch(0.696 0.17 162.48);
@@ -158,8 +157,8 @@
 	--chart-5: oklch(0.645 0.246 16.439);
 	/* The soft palette on the dark card: mid-tone fills (L 0.49, the sand a
 	   warmer 0.5 0.1 75), light inks of the same hues. Ink on the card:
-	   1 8.44:1, 2 9.46, 3 10.17, 4 8.03, 5 8.06; at the 0.85 dim 6.17:1 or
-	   more. Ink on its own fill (the outline): 1 3.13:1, 2 3.40, 3 3.69,
+	   1 9.27:1, 2 10.38, 3 11.20, 4 8.82, 5 8.85; at the 0.85 dim 6.66:1 or
+	   more. Ink on its own fill (the outline): 1 3.13:1, 2 3.38, 3 3.69,
 	   4 3.11, 5 3.13. Every pair at least 54 degrees and ΔEOK 0.109 apart. */
 	--chart-soft-1: oklch(0.49 0.08 255);
 	--chart-soft-1-ink: oklch(0.78 0.1 255);
@@ -171,13 +170,13 @@
 	--chart-soft-4-ink: oklch(0.78 0.13 310);
 	--chart-soft-5: oklch(0.49 0.09 25);
 	--chart-soft-5-ink: oklch(0.78 0.11 25);
-	--sidebar: oklch(0.232 0.019 289.4);
+	--sidebar: oklch(0.19 0.019 289.4);
 	--sidebar-foreground: oklch(0.943 0.012 291.3);
 	--sidebar-primary: oklch(0.488 0.243 264.376);
 	--sidebar-primary-foreground: oklch(0.995 0.002 291.3);
-	--sidebar-accent: oklch(0.27 0.022 290);
+	--sidebar-accent: oklch(0.228 0.022 290);
 	--sidebar-accent-foreground: oklch(0.943 0.012 291.3);
-	--sidebar-border: oklch(0.301 0.025 291.4);
+	--sidebar-border: oklch(0.259 0.025 291.4);
 	--sidebar-ring: oklch(0.551 0.03 290);
 }
 
@@ -188,10 +187,10 @@
 	--tertiary-foreground: oklch(0.984 0.003 247.858);
 }
 
-/* Dark: lifted like --secondary, as it is read as text (6.5:1 on --background,
-   5.9:1 on --card); its foreground is the dark surface, 6.5:1 on the fill. */
+/* Dark: lifted like --secondary, as it is read as text (6.9:1 on --background,
+   6.5:1 on --card); its foreground is the dark surface, 6.9:1 on the fill. */
 .dark,
 [data-theme="dark"] {
 	--tertiary: oklch(0.7 0.15 310.75);
-	--tertiary-foreground: oklch(0.192 0.016 290.5);
+	--tertiary-foreground: oklch(0.15 0.026 273);
 }

package/lib/components/tones/app-tones.css

@@ -58,7 +58,8 @@
 	/* White on a tone of relative luminance up to 0.179, black above: from
 	 * there each is 4.5:1 or more (white needs 0.183 or less, black 0.175 or
 	 * more). r, g and b are the tone's linear sRGB channels. */
-	:root {
+	:root,
+	[data-nxgt-theme] {
 		--nxgt-tone-on-channel: clamp(
 			0,
 			(0.179 - (0.2126 * r + 0.7152 * g + 0.0722 * b)) *

package/lib/components/tones/containers.css

@@ -15,6 +15,7 @@
  * (the tone held at a container's lightness, set below where relative colour
  * syntax works, the tone's text colour where it does not). */
 :root,
+[data-nxgt-theme],
 .dark,
 [data-theme="dark"] {
 	--primary-container: var(
@@ -131,7 +132,9 @@
  * text colour above. */
 @supports (color: oklch(from red clamp(0, l, 0.5) c h)) {
 	.dark,
-	[data-theme="dark"] {
+	[data-theme="dark"],
+	:is(.dark, [data-theme="dark"]) [data-nxgt-theme],
+	[data-nxgt-theme]:is(.dark, [data-theme="dark"]) {
 		--nxgt-primary-container-base: oklch(
 			from var(--primary)
 				clamp(var(--nxgt-tone-container-min), l, var(--nxgt-tone-container-max))

package/lib/components/tones/index.css

@@ -8,6 +8,7 @@
  *   surface.css     the surface a channel container is mixed over
  *   channel.css     --nxgt-tone* of a named tone, and its container and ring
  *   app-tones.css   the derivation for an app's own tone
+ *   zone-paint.css  a theme zone paints its own text (and a forced mode its background)
  *
  * The sidebar's active tokens are in ui/layout/sidebar/sidebar-tokens.css.
  *
@@ -34,3 +35,4 @@
 @import "./surface.css";
 @import "./channel.css";
 @import "./app-tones.css";
+@import "./zone-paint.css";

package/lib/components/tones/surface.css

@@ -5,6 +5,7 @@
  * unlayered, like theme-tokens.css. */
 @layer base {
 	:root,
+	[data-nxgt-theme],
 	.dark,
 	[data-theme="dark"] {
 		--nxgt-tone-surface: var(--background);

package/lib/components/tones/tokens.css

@@ -1,4 +1,5 @@
-:root {
+:root,
+[data-nxgt-theme] {
 	/* Tints over the page. Hover, selected and strong are the alpha of the
 	 * selection and hover surfaces; the container tint is the share of the tone
 	 * in `--<tone>-container`. For apps: no rule of the library reads hover,
@@ -64,7 +65,9 @@
 }
 
 .dark,
-[data-theme="dark"] {
+[data-theme="dark"],
+:is(.dark, [data-theme="dark"]) [data-nxgt-theme],
+[data-nxgt-theme]:is(.dark, [data-theme="dark"]) {
 	/* 24 % of the tone's text colour where the browser cannot derive the
 	 * container's base (no relative colour syntax): the shares below hold its
 	 * text at 4.5:1. */
@@ -111,7 +114,9 @@
  * or more (the named tones' and an app tone's, on the page and on a card). */
 @supports (color: oklch(from red clamp(0, l, 0.5) c h)) {
 	.dark,
-	[data-theme="dark"] {
+	[data-theme="dark"],
+	:is(.dark, [data-theme="dark"]) [data-nxgt-theme],
+	[data-nxgt-theme]:is(.dark, [data-theme="dark"]) {
 		--nxgt-tint-container: 45%;
 		--nxgt-tint-status: 45%;
 	}

package/lib/components/tones/zone-paint.css

@@ -0,0 +1,15 @@
+/* A theme zone paints its own text: it sets the colour tokens below :root, so
+ * the colour it inherits would be the page's. A zone with a forced mode
+ * (`NxgtTheme mode`, `data-theme`) also paints its own background, since the
+ * page's would be the other mode's. `@layer base`, so a utility on the zone
+ * still wins. Lavande on <html> with no zone is untouched. React only (the
+ * zones are, until the Vue port). */
+@layer base {
+	[data-nxgt-theme] {
+		color: var(--foreground);
+	}
+	[data-nxgt-theme][data-theme="dark"],
+	[data-nxgt-theme][data-theme="light"] {
+		background: var(--background);
+	}
+}

package/lib/components/ui/feedback/toast/toast-tokens.css

@@ -8,6 +8,7 @@
  * outside a Toaster it changes nothing. */
 @layer components {
 	:root,
+	[data-nxgt-theme],
 	.dark,
 	[data-theme="dark"] {
 		--nxgt-toast-success-text: var(--success-text);

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

@@ -25,6 +25,15 @@
  * fallback is their usual surface, through `--nxgt-backdrop-fill-*`: a utility
  * class outranks any rule in a layer, so a rule here could not set them. */
 @layer components {
+	/* `backdrop={false}`, or a theme with no background: a plain page, no
+	 * gradient and no blobs. The chrome keeps its usual fills. */
+	[data-slot="activity-layout"][data-plain] {
+		background-image: none;
+	}
+	[data-slot="activity-layout"][data-plain] > [data-layer] {
+		display: none;
+	}
+
 	/* The gutter mask without a backdrop (activity-layout.tsx) has the app bar's
 	 * translucent fill, which the page's top gutter never had: it fades in over
 	 * the first 8px of scroll, so at scroll top nothing changed. A browser
@@ -68,6 +77,23 @@
 		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/lib/components/ui/layout/sidebar/sidebar-tokens.css

@@ -18,7 +18,9 @@
 }
 
 .dark,
-[data-theme="dark"] {
+[data-theme="dark"],
+:is(.dark, [data-theme="dark"]) [data-nxgt-theme],
+[data-nxgt-theme]:is(.dark, [data-theme="dark"]) {
 	/* 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
@@ -32,7 +34,8 @@
  * it is primary, as set on :root (2.5:1 in dark rather than the inherited
  * muted text). */
 @supports not (color: oklch(from red l c h)) {
-	:root {
+	:root,
+	[data-nxgt-theme] {
 		--sidebar-active-foreground: var(--primary);
 	}
 }

package/lib/components/ui/media/media-player/nxgt-media-player.css

@@ -69,42 +69,17 @@
 }
 
 /* The glass drawer reads the dark theme whatever the page's. `.dark` on it
- * redefines `--background` and friends, but Tailwind's `--color-*` were
- * resolved at the root, so they are pointed at the local values again. */
-[data-slot="media-panel-drawer"],
-[data-slot="media-lightbox"] {
-	--color-background: var(--background);
-	--color-foreground: var(--foreground);
-	--color-card: var(--card);
-	--color-card-foreground: var(--card-foreground);
-	--color-popover: var(--popover);
-	--color-popover-foreground: var(--popover-foreground);
-	--color-secondary: var(--secondary);
-	--color-secondary-foreground: var(--secondary-foreground);
-	--color-destructive: var(--destructive);
-	--color-error: var(--error);
-	--color-error-foreground: var(--error-foreground);
-	--color-error-text: var(--error-text);
-	--color-success: var(--success);
-	--color-success-foreground: var(--success-foreground);
-	--color-primary: var(--primary);
-	--color-primary-foreground: var(--primary-foreground);
-	--color-primary-text: var(--primary-text);
-	--color-muted: var(--muted);
-	--color-muted-foreground: color-mix(
+ * redefines `--background` and friends; the utilities read `var(--token)`
+ * where they sit (`@theme inline`), so only the one token the dark theme does
+ * not give the glass, the muted text, is derived here. `.dark` in the selector
+ * outranks the dark tokens' own `.dark` rule, which sets `--muted-foreground`. */
+.dark[data-slot="media-panel-drawer"],
+.dark[data-slot="media-lightbox"] {
+	--muted-foreground: color-mix(
 		in oklab,
 		var(--foreground) 82%,
 		var(--background)
 	);
-	--color-accent: var(--accent);
-	--color-accent-foreground: var(--accent-foreground);
-	--color-border: var(--border);
-	--color-input: var(--input);
-	--color-ring: var(--ring);
-	--color-track: var(--track);
-	--color-track-fill: var(--track-fill);
-	--color-tooltip: var(--tooltip);
-	--color-tooltip-foreground: var(--tooltip-foreground);
 }
 
 /* The fullscreen drawer takes the end 24rem of a wide player (a bottom sheet

package/lib/components/ui/primitives/field-box/field-box-tokens.css

@@ -8,7 +8,8 @@
  * so a filled field still reads apart from an empty one on the near-black
  * page (≥ 1.10:1 between the two, ≥ 1.15:1 against the page;
  * Guides/Accessibility/Field contrast measures both). */
-:root {
+:root,
+[data-nxgt-theme] {
 	--nxgt-field-bg: color-mix(in oklab, var(--foreground) 2%, var(--background));
 	--nxgt-field-bg-hover: color-mix(
 		in oklab,
@@ -60,7 +61,9 @@
 }
 
 .dark,
-[data-theme="dark"] {
+[data-theme="dark"],
+:is(.dark, [data-theme="dark"]) [data-nxgt-theme],
+[data-nxgt-theme]:is(.dark, [data-theme="dark"]) {
 	--nxgt-option-ring: color-mix(in oklab, var(--primary-text) 50%, transparent);
 	--nxgt-option-muted: color-mix(
 		in oklab,

package/lib/styles.css

@@ -36,7 +36,12 @@
 	--radius-field-inner: var(--nxgt-field-inner-radius);
 }
 
-@theme {
+/* Colours and radius are inline: a utility reads `var(--primary)` where it is
+ * used, not a `--color-primary` computed once on :root, so a zone
+ * (`[data-nxgt-theme]`, a `.dark` wrapper) that sets `--primary` below :root
+ * reaches `bg-primary`. Tailwind still emits the `--color-*` a page uses, as
+ * before, for app CSS that reads `var(--color-primary)`. */
+@theme inline {
 	--radius-sm: calc(var(--radius) - 4px);
 	--radius-md: calc(var(--radius) - 2px);
 	--radius-lg: var(--radius);
@@ -102,7 +107,9 @@
 	--color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
 	--color-sidebar-border: var(--sidebar-border);
 	--color-sidebar-ring: var(--sidebar-ring);
+}
 
+@theme {
 	--ease-spatial-fast: var(--nxgt-motion-spatial-fast);
 	--ease-spatial-default: var(--nxgt-motion-spatial-default);
 	--ease-spatial-slow: var(--nxgt-motion-spatial-slow);