@aceshooting/lyra-ui 27.0.0 → 28.0.0

package/llms/shared.md

@@ -184,11 +184,12 @@ The entry points, then:
 - **`lr-flag`** registers from the barrel, but resolving a flag by `country`/`language` (rather than
   a pre-resolved `src`) additionally needs
   `import '@aceshooting/lyra-ui/components/media/flag/flag-peer.js';` once.
-- **Other subpaths.** `@aceshooting/lyra-ui/theme.css` (ready-made light/dark theme),
+- **Other subpaths.** `@aceshooting/lyra-ui/theme.css` (ready-made light/dark theme, including the
+  document token layer),
   `@aceshooting/lyra-ui/looks/shadcn.css` (opt-in shadcn/ui look, imported after `theme.css` — see
   [The shadcn look](#the-shadcn-look--looksshadcncss)),
-  `@aceshooting/lyra-ui/tokens-root.css` (opt-in: the curated resolved `--lr-*` tokens at `:root`,
-  so your own components can read them),
+  `@aceshooting/lyra-ui/tokens-root.css` (the document token layer alone, for pages that do not
+  use `theme.css`; link one of the two, not both),
   `@aceshooting/lyra-ui/native.css` (opt-in native-element styles inside `.lr-native`),
   `@aceshooting/lyra-ui/utilities.css` (opt-in light-DOM layout/text/typography utilities),
   `@aceshooting/lyra-ui/theme.js` (the zero-dependency style runtime),
@@ -880,17 +881,18 @@ Three layers, and **which one you set decides how far the override reaches**:
 3. **`--lr-<component>-*`** — per-component properties, for one element at a time. Listed in each
    component's own section.
 
-**Layer 2 (`--lr-*`) is declared only on each `lr-*` element's own shadow `:host`.** It never
-reaches plain application CSS, and it never reaches your own custom elements, since neither is a
-descendant of an `lr-*` shadow root — `body { color: var(--lr-color-text) }` in application CSS
-resolves to nothing, silently, not an error. Retheme through layer 1 (`--lr-theme-*`), which
-`theme.css` supplies at document scope and which inherits normally into every nested shadow root.
-To _read_ (not retheme) the resolved values from your own components, import the opt-in
-[`tokens-root.css`](#reading-the-resolved-tokens-from-your-own-components--tokens-rootcss), which
-declares a curated subset of layer 2 at `:root`.
+**Layer 2 (`--lr-*`) is declared once per document, not on each component** (since 28.0.0). The
+_document token layer_ declares every shared output on `:root` and re-derives it only at
+[theme scopes](#theme-scopes). `theme.css` carries it, so a page that imports `theme.css` has it from
+first paint; on a page without `theme.css`, registering the first `lr-*` element adopts the same text
+as a constructed stylesheet. Components inherit the result, and so do your own elements —
+`body { color: var(--lr-color-text) }` resolves everywhere the layer applies.
+[`tokens-root.css`](#reading-the-resolved-tokens-from-your-own-components--tokens-rootcss) is the
+layer alone, for pages that do not use `theme.css`. Retheme through layer 1 (`--lr-theme-*`) **on a theme scope**: `:root`, a
+mode scope, a style-axis boundary, or any element marked `data-lr-theme-scope`.
 See [Where an override actually reaches](#where-an-override-actually-reaches) below for the full
-inheritance rules, including the one documented exception (per-component `--lr-<component>-*`
-hooks, layer 3, which do inherit through wrappers).
+inheritance rules, including per-component `--lr-<component>-*` hooks (layer 3), which inherit
+through wrappers.
 
 ### Lyra signature starter
 
@@ -904,7 +906,6 @@ mode; `accent: null` explicitly clears the accent, while `resetLyraStyle()` rest
 @layer lr-base, lr-theme, lr-theme-preset, lr-utilities, lr-overrides;
 @layer lr-theme-preset.look, lr-theme-preset.density, lr-theme-preset.surface, lr-theme-preset.accent, lr-theme-preset.mode;
 @import "@aceshooting/lyra-ui/theme.css";
-@import "@aceshooting/lyra-ui/tokens-root.css";
 ```
 
 Keep both layer-order statements before these imports. Bundlers can hoist statements from imported
@@ -1084,20 +1085,35 @@ design launcher. Keep these layout rules shared across application headers and a
 
 ### Reading the resolved tokens from your own components — `tokens-root.css`
 
-The paragraph above is a real problem for any application that has custom elements of its own: they
-are not descendants of an `lr-*` shadow root either, so `var(--lr-color-border)` inside **your**
-component resolves to nothing, and `var(--lr-space-m, 0.5rem)` quietly runs on its literal fallback
-forever. Both failures are invisible without reading computed styles in a browser.
-
-Import one optional stylesheet and the curated part of layer 2 exists at document scope:
+Since 28.0.0 the resolved layer lives in the document, so your own elements read it like any
+component does: `var(--lr-color-border)` inside **your** component resolves wherever the layer
+applies. `theme.css` carries the layer, so importing `theme.css` is enough, including for
+server-rendered pages and for application elements that paint before any Lyra element exists.
+`tokens-root.css` is the same layer alone, as a static stylesheet, for pages that do not use
+`theme.css`:
+
+- **Server-rendered pages.** Declarative shadow roots no longer carry the layer, so link
+  `theme.css` (or `tokens-root.css`) for a correct first paint before hydration (see
+  [Theme scopes](#theme-scopes) for application shadow roots).
+- **Application elements that paint before the first Lyra element is registered**, for example
+  ahead of a lazily loaded route; otherwise they change value when the layer is adopted.
+- **Large pages that load Lyra late.** Without a static copy, the layer is adopted when the first
+  Lyra element is registered, which usually happens while the document is still small. A route that
+  imports Lyra only after the page already holds a large DOM pays a one-off, whole-document style
+  invalidation then. A document whose root already resolves the layer (it links `theme.css` or
+  `tokens-root.css`) keeps the static copy and adopts no constructed one.
+
+Link one of the two, not both: the second copy changes no value, but every scope matches the layer
+twice.
 
 ```css
-@import "@aceshooting/lyra-ui/theme.css"; /* the --lr-theme-* input layer */
-@import "@aceshooting/lyra-ui/tokens-root.css"; /* the resolved --lr-* layer, at :root */
+@import "@aceshooting/lyra-ui/theme.css"; /* the --lr-theme-* inputs, Lyra's layer order, and the resolved --lr-* layer */
+/* or, without theme.css: */
+@import "@aceshooting/lyra-ui/tokens-root.css"; /* the resolved --lr-* layer alone */
 ```
 
 ```css
-/* Now valid in your own component's stylesheet, in plain application CSS, anywhere. */
+/* Valid in your own component's stylesheet, in plain application CSS, anywhere. */
 .app-panel {
   padding: var(--lr-space-m);
   border: var(--lr-border-width-thin) solid var(--lr-color-border);
@@ -1112,10 +1128,9 @@ Import one optional stylesheet and the curated part of layer 2 exists at documen
 }
 ```
 
-**It is opt-in, and it is a curated subset — not all of layer 2.** `--lr-*` is internal precisely so
-it can change without a major version; publishing all of it at `:root` would freeze several hundred
-internal decisions as permanent API. What ships is what an application's own component needs to sit
-inside a Lyra UI without looking foreign:
+**Every output is visible on `:root`; only a subset is public API.** `--lr-*` is internal precisely
+so it can change without a major version. The stable subset is what an application's own component
+needs to sit inside a Lyra UI without looking foreign, and the file's header lists it:
 
 | Family                | Names                                                                                                                                                                                                                     |
 | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -1128,53 +1143,122 @@ inside a Lyra UI without looking foreign:
 | Typography            | `--lr-font`, `--lr-font-mono`, the ten `--lr-font-size-*` steps, the four `--lr-font-weight-*` steps                                                                                                                        |
 | State and motion      | `--lr-focus-ring`, `--lr-focus-ring-color`, `--lr-focus-ring-width`, `--lr-focus-ring-offset`, `--lr-opacity-disabled`, `--lr-opacity-muted`, `--lr-duration-fast`, `--lr-duration-base`, `--lr-easing-standard`, `--lr-easing-emphasized`, `--lr-transition-fast`, `--lr-transition-base`, `--lr-transition-interactive` |
 
-The grid ships whole because its contrast guarantee is **per tier** — a `fill-quiet` background is
-only guaranteed legible under the matching `on-quiet` foreground — so shipping the flat aliases
-alone would hand you a pairing with nothing behind it.
+The grid is stable as a whole because its contrast guarantee is **per tier** — a `fill-quiet`
+background is only guaranteed legible under the matching `on-quiet` foreground.
 
-**Deliberately not published**, and each for a reason that makes reading it a bug rather than a
-convenience: `--lr-ramp-*` (tooling-only numeric inputs, absent from component host styles),
-`--lr-size-*` (value-named geometry constants, frozen internals), the chart, graph and terminal
-palettes (generated ramps that move with the palette tooling), `--lr-layer-*` (stacking order is
-your decision), `--lr-color-mix-*` and `--lr-hover-brightness` (inputs to the library's own
-interaction recipe), `--lr-line-height-*`, the per-control internals (`--lr-icon-button-size`,
+**Visible but internal** (read them at your own risk; they may change in any release): `--lr-size-*`,
+`--lr-layer-*`, `--lr-color-mix-*`, `--lr-hover-brightness`, `--lr-line-height-*`,
 `--lr-otp-input-segment-size`, `--lr-scroll-fade-size`, `--lr-popover-viewport-clamp`,
-`--lr-safe-area-*`, `--lr-mask-opaque`, `--lr-color-no-data`), and the nine variant-following slots
-(`--lr-color-fill-loud` and friends), which mean "the variant _this_ element is set to" and are
-meaningless on `:root`. If you need one of these, ask for it to be added rather than reading it out
-of a component's shadow root.
+`--lr-mask-opaque`, `--lr-color-no-data`, and the private `--_lr-*` names. **Not in the layer at all:**
+`--lr-ramp-*` (tooling-only), the chart, graph and terminal palettes (per host, on the components that
+draw with them), the form-control ladder, and the per-element names `--lr-icon-button-size`,
+`--lr-radius-button` and `--lr-safe-area-*`. If you need one of these, ask for it to be added to the
+stable subset rather than reading it from the document.
 
 **Stability promise.** Every name in the table is public API from the release that introduced it: it
 will not be renamed or removed outside a major version, and its meaning will not change. Its _value_
 may change in a minor exactly as it may inside a component — a palette retune moves your elements
-and the kit's together, which is the point. Names absent from the file stay internal and may change
-in any release.
-
-**Modes follow the inherited style context.** Standalone `tokens-root.css` follows the OS at the
-root and accepts `.lr-light` / `.lr-dark`, `data-lr-theme` and `data-lr-mode` scopes. When `theme.css`
-is also installed, its requested mode owns the switches instead. Shared outputs re-resolve on style
-and contrast/motion preference boundaries; forced-colors and reduced-motion overrides use those
-same boundaries, including under a dark OS. Each output reads the local `--lr-theme-*` input before
-its built-in fallback. A preference-only boundary never overwrites inherited theme inputs.
-
-**One caveat, and it is the same shape as layer 2's rule everywhere else.** A `--lr-theme-*` input
-set on a mid-tree element retunes every `lr-*` component below it, because each component re-derives
-the resolved layer on its own `:host`. The document-scope copy cannot: it is substituted where it is
-declared, and what inherits past that point is the finished value. So if an application element
-carries a subtree override and expects its **own** descendants to follow, give that element a mode
-scope too — `data-lr-mode`, `data-lr-theme-scope`, or the compatibility `lr-light`/`lr-dark`
-classes — so the whole subset resolves again there:
+and the kit's together, which is the point.
+
+**Modes follow the nearest mode scope.** The layer follows the OS preference at the root and accepts
+`.lr-light` / `.lr-dark`, `data-lr-theme` and `data-lr-mode` scopes, in every engine, with or without
+`theme.css`. When `theme.css` is installed its requested mode owns the switches. A mode-neutral
+scope keeps its ancestor's mode. Forced colours, increased contrast and reduced motion apply at every
+scope and again on every component host.
+
+Public outputs sit in the `lr-theme` cascade layer (the fallback mode switches in `lr-base`), so any
+unlayered application rule beats them regardless of load order, and the file declares custom
+properties only — notably not `color-scheme` — so importing it paints nothing by itself.
+
+### Theme scopes
+
+A **theme scope** is an element that re-derives the whole token layer from the `--lr-theme-*` inputs
+and the mode it sees. The list is closed: `:root`; the mode scopes `.lr-light`, `.lr-dark` and
+`[data-lr-theme]` (any value); the style-axis boundaries `[data-lr-mode]`, `[data-lr-look]`,
+`[data-lr-accent]`, `[data-lr-density]`, `[data-lr-contrast]`, `[data-lr-motion]`; a look's scoped
+`.light` / `.dark` aliases; the design-token fixture scopes `.lr-token-light`, `.lr-token-dark`,
+`[data-lr-design-token-mode]`; and the mode-neutral marker **`data-lr-theme-scope`**.
 
 ```html
-<!-- Both the lr-* components and the app's own elements below follow the override. -->
-<section class="lr-light" style="--lr-theme-color-brand-fill-loud: #7c3aed">…</section>
+<!-- Re-theme one region: mark it, then set inputs on it. -->
+<section data-lr-theme-scope style="--lr-theme-color-brand-fill-loud: #7c3aed">
+  <lr-button variant="brand">Save</lr-button>
+</section>
+
+<!-- Mode scopes are already scopes; a marked region inside one keeps its mode. -->
+<aside class="lr-dark"><div data-lr-theme-scope style="--lr-theme-space-m: 1rem">…</div></aside>
+
+<!-- A single re-themed component. -->
+<lr-button data-lr-theme-scope style="--lr-theme-color-brand-fill-loud: #7c3aed">Save</lr-button>
+```
+
+- **The marker follows HTML presence semantics:** `data-lr-theme-scope="false"` still marks. React
+  renders `data-*={false}` as `"false"`, so write `data-lr-theme-scope=""` (or omit the attribute);
+  the development build warns on the literal `"false"`.
+- **Nesting** works like inheritance: a scope re-derives from what it inherits plus what it sets, and
+  its descendants inherit the result until the next scope. The marker only re-derives the `--lr-*`
+  outputs, so an input set on `:root` (inline, in your stylesheet, or by `setLyraStyle()`) or on an
+  outer scope reaches a marked region exactly as it reaches an unmarked one, and adding a marker
+  where nothing needs it changes nothing. With `theme.css`, mode scopes and the style-axis
+  boundaries also re-resolve the inputs from the selected look, accent and mode, so an input set
+  above one of them stops there (set it on that boundary, or below it). A scope costs a little less
+  than one component did before 28.0.0, so put inputs on a common ancestor rather than marking every
+  row of a list.
+- **`applyLyraStyleScope()`** writes the marker whenever it writes inline inputs.
+- **Brand regions in the default look.** The marker re-derives outputs but is not a style boundary,
+  so the roles that follow brand in the default Shadcn look (the neutral loud tier) keep the brand
+  of the nearest boundary inside the first example above. For a brand region call
+  `applyLyraStyleScope(el, { accent: '#7c3aed' })`, which writes the `data-lr-accent="custom"`
+  boundary, or set the `--lr-theme-color-neutral-*-loud` inputs on the region too.
+- **Which inputs need a scope.** Only the `--lr-theme-*` inputs the layer consumes (listed in
+  `llms/tokens.md`). Inputs read on the host itself keep working on any element: the chart,
+  graph and terminal palettes, the form-control heights and radius, the icon-button size, the
+  button radius, scrollbar and progress-ring inputs.
+
+**Application shadow roots.** Custom properties inherit across shadow boundaries; selectors do not.
+A scope _inside_ your own component's shadow root therefore needs the layer adopted in that root.
+Lyra does that on demand: when a Lyra element connects inside an application shadow root and it is,
+or sits below, a scope in that root, an unlayered copy of the layer with zero-specificity
+(`:where()`) selectors is appended to the root's `adoptedStyleSheets`, so your component's own rules
+there still win (unless you put them in a cascade layer).
+"Below" follows the flat tree, so a Lyra element slotted into your component (directly, or through
+forwarded slots) counts as below the scopes around its slot, also when your component renders its
+slots right after connecting, as Lit does. A Lyra element inside a slotted non-Lyra wrapper does not
+trigger it. Library components' own shadow roots never receive it. Call
+`adoptLyraTokens(root)` (from `@aceshooting/lyra-ui/utilities/tokens.js`, or the package root) for a
+root whose scopes appear after its Lyra elements connected, a root that has scopes but no Lyra
+element yet, or an iframe that holds application elements only. Server-rendered application roots
+that contain scopes include `<link rel="stylesheet" href="…/tokens-root.css">`.
+
+```js
+// An application component whose shadow root holds scopes before any Lyra element connects in it.
+import { adoptLyraTokens } from "@aceshooting/lyra-ui/utilities/tokens.js";
+adoptLyraTokens(this.shadowRoot); // adoptLyraTokens(root: Document | ShadowRoot): void, idempotent
 ```
 
-Public outputs sit in the `lr-theme` cascade layer, like `theme.css`, so any unlayered application rule
-beats it regardless of load order, and the file declares custom properties only — notably not
-`color-scheme` — so importing it paints nothing by itself. `--lr-focus-ring` and its three parts are
-also declared at document scope by `theme.css`; both spell the same chain, so importing both is a
-no-op either way round.
+**Append, never replace.** Lyra appends its sheet to `document.adoptedStyleSheets` and to an
+application root's. An application that later assigns a new array wholesale removes it until the next
+Lyra element connects there; append to the existing array instead.
+In Chromium, Lyra also appends a one-rule sheet to `document.adoptedStyleSheets`: a private root
+property (`--_lr-root-inputs`) that follows every theme input. It lets Chromium skip a full
+custom-property comparison per element when the root is re-themed (an accent or spacing input
+written on `<html>` with dark islands or other scopes on the page costs about half as much). Firefox
+and Safari do not get it; they already stop at unchanged scopes, which the property would defeat.
+When `theme.css` or `tokens-root.css` provides the layer, that sheet goes in only at the first
+attribute change on `<html>` (an inline input, a mode or look attribute, a class), so a route that registers Lyra late on a large page does not restyle every element for it.
+
+**Layer order.** On a page with no Lyra stylesheet, the adopted sheet's layer statement is the last
+the browser sees, so Lyra's layers sort after yours. Declare Lyra's order first (import `theme.css`,
+or repeat `@layer lr-base, lr-theme, lr-theme-preset, lr-utilities, lr-overrides;` before your own
+layers), or leave application overrides of `--lr-*` outputs unlayered.
+
+**Finding unscoped inputs.** `findUnscopedThemeInputs(root?)` (from
+`@aceshooting/lyra-ui/utilities/theme-scopes.js`; `findUnscopedThemeInputs(root?: Document |
+DocumentFragment | Element): Element[]`) returns, without logging, every element under `root`
+(through open shadow roots) whose inline style sets a layer-consumed input and that is not a scope. `lyra-ui-migrate --rule=theme-scopes`
+adds the marker in HTML, Lit and JSX templates and reports dynamic inputs and stylesheet rules;
+`lyra-ui-migrate --origin=lyra-v26` runs the same rule together with the other Lyra 27 moves (relocated
+locale and editor-data specifiers, `ToolStatus`) and reports removed localization keys.
 
 ### The colour ramp and the semantic grid
 
@@ -1215,8 +1299,9 @@ These guarantees apply in both modes.
 rethemed without forking anything beneath it:
 
 ```css
-/* Both the grid slot and the flat alias below now resolve to this. */
-.invoice-panel {
+/* Both the grid slot and the flat alias below now resolve to this, for every component inside
+   the panel (mark the panel <div class="invoice-panel" data-lr-theme-scope>, or use :root). */
+.invoice-panel[data-lr-theme-scope] {
   --lr-theme-color-brand-fill-loud: #7c3aed;
 }
 ```
@@ -1391,6 +1476,13 @@ first statement the browser sees is appended at the end, so an older four-name s
 `lr-theme-preset`) would rank an imported look preset above `lr-overrides` and your own layer. Every Lyra stylesheet that declares an order repeats the same five names for exactly this
 reason.
 
+The same rule decides application **fallback fills**. A page that keeps plain `background` rules
+for dialogs or panels (so it also renders without the component bundle) and uses an unlayered rule
+on an `.lr-surface-chrome` element overrides the Glass fill; declare a low-priority layer before
+Lyra's names (`@layer app-base, lr-base, lr-theme, lr-theme-preset, lr-utilities, lr-overrides;`)
+for those fallbacks, or set `--lr-surface-background`. See
+[Application fallback fills and cascade layers](native-styles-and-utilities.md#application-fallback-fills-and-cascade-layers).
+
 <a id="the-shadcn-look--themesshadcncss"></a>
 
 ### The shadcn look — looks/shadcn.css
@@ -1437,25 +1529,33 @@ compatibility aliases above.
 
 ### Where an override actually reaches
 
-**Shared computed `--lr-*` design-token outputs are declared on every `lr-*` element's `:host`.**
-That includes palette, spacing, radius, typography, and motion outputs such as
-`--lr-color-brand`, `--lr-space-m`, and `--lr-radius`. A value for one of those shared outputs set
-on an ancestor is re-declared — and lost — at the first `lr-*` element between that ancestor and
-the component you meant to style. It never reaches anything nested inside another component.
-
-**`--lr-theme-*` inputs are never redeclared inside a component's shadow styles.** `theme.css`
-supplies them on its root and light/dark mode selectors, so an application override inherits normally
-through every nested shadow root. **Setting a `--lr-theme-*` input on a wrapper element is the
-supported way to retheme one subtree.** Setting a `--lr-*` token there only works for that wrapper's
-direct children.
+**Shared computed `--lr-*` outputs are resolved at theme scopes and inherited everywhere else.** That
+includes palette, spacing, radius, typography and motion outputs such as `--lr-color-brand`,
+`--lr-space-m` and `--lr-radius`. No component re-declares them on its host (since 28.0.0), so:
+
+- **A `--lr-theme-*` input** retunes everything below it **when it is set on a theme scope**. Set on a
+  plain wrapper, a component's inline style, or an application component's own `:host` rule, it no
+  longer re-derives the components below; add `data-lr-theme-scope` to that element.
+- **A `--lr-*` output** set on an ancestor now reaches every component below it, until the next theme
+  scope (which re-derives every output). The outputs _derived_ from it (`--lr-focus-ring` from
+  `--lr-focus-ring-color`, `--lr-color-brand` from `--lr-color-brand-fill-loud`,
+  `--lr-transition-interactive` from `--lr-transition-fast`) keep the scope's values unless the
+  element is itself a scope.
+- **Border outputs stop at an opaque content interior.** The bodies of `lr-card`, `lr-details` and
+  `lr-accordion-item` restore the nearest scope's unqualified `--lr-color-border` and
+  `--lr-color-border-strong` for their content (inside a glass surface the surface would otherwise
+  hand its translucency-qualified borders to opaque content). A `--lr-color-border` set on such a
+  component, or above it, still applies to the chrome that reads it, but not to the content; set
+  `--lr-theme-color-surface-border` on a theme scope, or a component hook such as
+  `--lr-input-border-color`, to reach the content.
 
 ```css
-/* Reaches everything in the subtree, however deeply nested. */
-.invoice-panel {
+/* Reaches everything in the subtree, however deeply nested: the element is a theme scope. */
+.invoice-panel[data-lr-theme-scope] {
   --lr-theme-color-brand-fill-loud: #7c3aed;
 }
 
-/* A shared computed output reaches direct lr-* children only — shadowed at the first nested host. */
+/* An output reaches the subtree down to the next scope; its dependants do not follow it. */
 .invoice-panel {
   --lr-color-brand: #7c3aed;
 }
@@ -1478,8 +1578,9 @@ reliable way to theme a group of matching components:
 State and size selectors change only the private fallback. An inherited or direct public value
 continues to win in every state and size tier.
 
-**Diagnostic:** if a shared design-token output has no effect on a nested component, check which
-layer you set before assuming the component is at fault. If a documented component-specific hook
+**Diagnostic:** if a `--lr-theme-*` input has no effect on a nested component, check that the element
+carrying it is a theme scope (the development build warns once per page about an inline input on an
+element that is not, and `findUnscopedThemeInputs()` lists them). If a documented component-specific hook
 fails when inherited from a wrapper, that is a component bug; setting the same hook directly on
 every host should not be necessary.
 
@@ -1589,28 +1690,16 @@ consult it rather than guessing a token name.
 }
 ```
 
-With `theme.css` imported, switch modes by putting `class="lr-light"`/`class="lr-dark"` (or
-`data-lr-theme="light"`/`"dark"`) on any ancestor; it also sets `color-scheme`. Without it, the token
-layer still ships a `prefers-color-scheme: dark` fallback that re-points the hardcoded defaults at a
-dark palette. Two things switch that fallback off:
-
-- **A real `--lr-theme-*` value**, which the fallback only substitutes for.
-- **`data-lr-theme="light"` on the component itself**, which pins light mode regardless of the OS.
-  Both layers honour it now: the palette layer always did, and the token layer — the hardcoded
-  surface/text/border defaults — does too, so `<lr-card data-lr-theme="light">` on a dark machine is
-  light throughout rather than light chrome over a dark colour grid. The mirror-image
-  `data-lr-theme="dark"` pins dark on a light machine the same way, and a `.lr-dark` /
-  `data-lr-theme="dark"` _ancestor_ is followed as well (through `:host-context()` where the engine
-  has it, and through `theme.css`'s inheriting custom properties everywhere else).
-
-Note the asymmetry: the _light_ pin is read on the component itself (`:host([data-lr-theme='light'])`),
-while a _dark_ ancestor is followed through `:host-context()`. Putting `data-lr-theme="light"` on
-`<html>` — what `setLyraStyle({ mode: 'light' })` does — pins the page through
-`theme.css`'s real `--lr-theme-*` values, which inherit into every shadow root. Without `theme.css`
-there are no such values to inherit, so put the attribute on the components you actually need
-pinned.
-
-The token layer also sets `:host([hidden]) { display: none !important; }` and an inherited
+Switch modes by putting `class="lr-light"`/`class="lr-dark"` (or `data-lr-theme="light"`/`"dark"`,
+or `data-lr-mode`) on any element, including a component itself; with `theme.css` imported it also
+sets `color-scheme`. **Every engine follows the nearest mode scope, with or without `theme.css`:** the
+document layer carries mode to every scope through two inherited private switches, so a `.lr-light`
+island inside a `.lr-dark` region is light, a mode-neutral scope keeps its ancestor's mode, and the
+OS preference decides the root unless the root carries an explicit mode. A real `--lr-theme-*` value
+still wins over the built-in light or dark default. (Before 28.0.0 an ancestor mode reached
+components without `theme.css` only in Chromium, through `:host-context()`.)
+
+Each component host also keeps `:host([hidden]) { display: none !important; }` and an inherited
 `box-sizing: border-box` reset.
 
 ### Style runtime — @aceshooting/lyra-ui/theme.js
@@ -1623,8 +1712,11 @@ import {
   getLyraStyle,
   resetLyraStyle,
   setLyraStyle,
+  startLyraStyle,
 } from "@aceshooting/lyra-ui/theme.js";
 
+startLyraStyle(); // adopt the saved style and follow the OS without writing storage
+
 setLyraStyle({ mode: "dark" }); // unspecified axes keep their current value
 setLyraStyle({ accent: "sapphire" }); // named palette accent
 setLyraStyle({ accent: "#7c3aed" }); // absolute CSS color
@@ -1695,6 +1787,27 @@ initial snapshot; it does not install a live system-mode listener. This option c
 the bootstrap. Later runtime calls such as `setLyraStyle()` follow their own style and persistence
 policy, so choose that policy explicitly if the application initializes the runtime afterward.
 
+**Starting the runtime after the bootstrap — `startLyraStyle()`.** A page that inlines only the
+bootstrap and loads `theme.js` later in a deferred bundle calls `startLyraStyle()` once. It adopts
+the saved style (the defaults when nothing is saved) on the document root and, while the mode is
+System, attaches the live `prefers-color-scheme` listener. It never writes storage: no record is
+created, a v1 record is not migrated, and an operating-system flip afterwards repaints without
+saving. Repeated calls do not stack listeners. The call emits no `lr-style-change`; a later
+operating-system flip emits `changed: ["resolvedMode"]`. The first `setLyraStyle()` takes over the
+same listener. Do not call `setLyraStyle({})` for this: it persists the current record.
+
+~~~ts
+// deferred bundle, after <script>lyraThemeBootstrap</script> in <head>
+import { startLyraStyle } from "@aceshooting/lyra-ui/theme.js";
+
+startLyraStyle(); // adopts the saved style, follows the OS while mode is System, never writes
+~~~
+
+`startLyraStyle()` always reads the runtime's own `localStorage['lyra-theme']` record and applies
+the whole profile in it. A page whose bootstrap uses `data-lr-theme-restore="mode"` or an
+application-owned storage key does not pair with it: the start would apply axes or a record the
+bootstrap deliberately ignored. Such pages call `setLyraStyle()` with the policy they want.
+
 **Migrating the retired theme facade.** New code uses setLyraStyle() and getLyraStyle(). Map old auto mode to system, an old surface reference color to accentBackground, and an old token map to overrides; review custom CSS colors that share a gemstone name before choosing a named accent. Replace preset definitions with a LyraLook plus explicit style choices. Replace selectors for data-lr-theme-preset with the actual axis they need, such as data-lr-look="shadcn". Import theme.css in place of the removed fixed themes/shadcn.css facade and select the look with setLyraStyle({ look: "shadcn" }) or a scoped data-lr-look attribute. Listen for lr-style-change and read event.detail.style and event.detail.changed; the old theme and preset events are no longer emitted. For the complete project-by-project sequence, see [Upgrading from v23 to v24](v23-to-v24-migration.md).
 
 Historical v1 stored records remain readable by the runtime and bootstrap. The removed JavaScript functions, preset subpaths, preset event, root marker, and fixed stylesheet are not available in the current API.
@@ -1825,8 +1938,8 @@ uses a substring class selector, so a class such as `app-lr-flex-preview` does n
 assets repeat `@layer lr-base, lr-theme, lr-theme-preset, lr-utilities, lr-overrides`; an ordinary unlayered
 application rule therefore beats them regardless of load order. A third opt-in asset,
 [`tokens-root.css`](#reading-the-resolved-tokens-from-your-own-components--tokens-rootcss), is not a
-style sheet in the same sense — it declares custom properties only, and exists so your own
-components can read the resolved `--lr-*` tokens these two are written against.
+style sheet in the same sense — it declares custom properties only: the document token layer that
+the first connected Lyra element would otherwise adopt, available before any component connects.
 
 ### Utility class inventory
 
@@ -1908,7 +2021,8 @@ keeps that surface's text colour. Heading tracking reads `--lr-heading-letter-sp
 | Muted | `lr-text-sm lr-text-quiet`      |
 
 For an exact 0.875rem muted/small size, use a class of your own with the token chain (resolved
-`--lr-*` tokens are undefined at document scope unless `tokens-root.css` is loaded):
+`--lr-*` tokens exist at document scope once a Lyra element has connected or `tokens-root.css` is
+loaded; the chain covers the moment before):
 
 ```css
 .app-muted {
@@ -2098,6 +2212,40 @@ contrast/motion choices. Nested chrome suppresses repeated blur; independently p
 surfaces begin their own material root. Keep cards, data tables, charts, map layers and editing
 fields outside the automatic chrome class.
 
+#### Application fallback fills and cascade layers
+
+Lyra paints the `.lr-surface-chrome` fill from a rule inside its cascade layers
+(`lr-theme-preset.surface`). An **unlayered** application rule that sets `background` on the same
+element — a generic `dialog { background: … }`, a `.panel` class — beats every layered rule
+whatever its specificity, so the element keeps the application's opaque fill and the Glass
+treatment disappears without a warning. No `revert-layer` workaround is needed; put the
+application's fallback where it ranks below Lyra:
+
+```css
+/* 1. A low-priority application layer named before Lyra's. This order statement must be the first
+      the browser sees: put it at the top of the entry stylesheet, before the theme.css import. */
+@layer app-base, lr-base, lr-theme, lr-theme-preset, lr-utilities, lr-overrides;
+@import "@aceshooting/lyra-ui/theme.css";
+
+@layer app-base {
+  dialog,
+  .panel {
+    background: #fff; /* still paints when the Lyra stylesheets are absent */
+  }
+}
+
+/* 2. Or choose the chrome's base fill through its token; Glass mixes it at the surface opacity. */
+.panel.lr-surface-chrome {
+  --lr-surface-background: #fff;
+}
+```
+
+An application layer declared after Lyra's (or unnamed until after `theme.css` loads) ranks above
+the surface layer and disables Glass in the same way as an unlayered rule. Keep unlayered
+`background` rules off `.lr-surface-chrome` elements, or exclude them with
+`:not(.lr-surface-chrome)`. See [Cascade layers](styles-and-tokens.md#cascade-layers) for the full
+order.
+
 ## Localization: `locale`, `strings`, and the locale runtime
 
 Every built-in string — button labels, accessible names, descriptions, validation messages, status
@@ -2622,6 +2770,22 @@ browser-bundle argument for excluding them does not apply to a server render. Us
   template; the component renders when its definition upgrades in the browser. Use this for initial
   renders that require light-DOM traversal, layout, canvas, observers, media, or other browser APIs.
 
+**Link the token layer in `<head>`.** Since 28.0.0 declarative shadow roots no longer carry the
+shared `--lr-*` layer (one server-rendered `lr-button` is about 34 KB smaller). `theme.css` carries
+it, so for a correct first paint before hydration link `theme.css` after the no-flash bootstrap (a
+page that does not use `theme.css` links `styles/tokens-root.css`, the layer alone, instead):
+
+```html
+<link rel="stylesheet" href="/node_modules/@aceshooting/lyra-ui/dist/theme.css" />
+```
+
+Hydration then skips the constructed copy. An application's **own** declarative shadow roots that
+contain theme scopes (for example a `.lr-dark` region or a `data-lr-theme-scope` wrapper) include the
+same `<link rel="stylesheet" href="…/tokens-root.css">` inside their template: document styles do not
+reach into a shadow root until hydration adopts the layer there. Without any link and without
+JavaScript, server-rendered components paint without resolved tokens, as a page without Lyra's styles
+always did.
+
 Server setup (the fallback must precede Lit's renderer):
 
 ```ts
@@ -2698,6 +2862,60 @@ only targets in the element's own or an ancestor shadow scope (sibling and desce
 targets are dropped); `null` clears it and removes the attribute; a changed `aria-controls`
 attribute resolves ids in the element's own root instead.
 
+`installHappyDomShims()` also calls `installHappyDomCascadeLayerShim()`. Happy DOM 20 drops every
+rule inside an `@layer` block from its CSSOM, while `CSS.supports('at-rule(@layer)')` still reports
+support. Lyra's stylesheets declare their probe properties (`--_lr-style-resolver`, the
+`--_lr-*-installed` markers, the token-layer sentinel) inside cascade layers, so under Happy DOM
+`theme.css` looked absent: `setLyraStyle()` warned that a stylesheet was missing and took its
+no-stylesheet fallback. The shim passes the text that `CSSStyleSheet.replaceSync()`/`replace()`
+parse (the path used by `<style>`, `<link rel="stylesheet">` and constructed sheets) through the
+exported `flattenCascadeLayers(css)`. That function drops `@layer a, b;` statements and unwraps
+each layer block in place, leaving comments, strings, `url(...)` and `@import … layer(x)` as they
+are. The probes then resolve as they do in a browser. Layer precedence is not modelled: the
+unwrapped rules cascade in source order, so assert behaviour, not values that depend on which layer
+wins. `insertRule()` is unchanged. The shim detects the defect by parsing a layered rule, so it is
+a no-op in every browser and without a `CSSStyleSheet` global; it installs once and returns a
+function that restores the original methods. Install it before any stylesheet is parsed (in the
+same `setupFiles` entry): a sheet parsed earlier keeps the rules it dropped.
+
+### jsdom: `installJsdomShims()`
+
+jsdom implements no `adoptedStyleSheets`, so Lit renders one `<style>` element per component
+shadow root. jsdom registers each of those sheets on the document, not the shadow root, and every
+`getComputedStyle()` call then matches the element against every rule of every sheet. With a few
+hundred Lyra elements on the page a single computed-style read can take over 100 ms, and Lyra
+reads computed style to decide which slotted text is visible, so whole tests slow to a crawl.
+
+`installJsdomShims()` installs the two jsdom shims. `installJsdomAdoptedStyleSheetsShim()` adds an inert
+`adoptedStyleSheets` to `Document` and `ShadowRoot`, so Lit adopts each component's constructed
+stylesheet instead of appending `<style>` elements. Adopted sheets are stored and read back (the
+same array until reassigned, so `push()` persists) but never applied; jsdom could not cascade them
+per shadow root anyway. `getComputedStyle()` then sees only the document's own sheets and inline
+styles, so assert behaviour and DOM rather than component styling. A jsdom release without
+`CSSStyleSheet.prototype.replace()`/`replaceSync()`, which Lit also requires, gets inert versions
+that record the text. The shim installs only when `navigator.userAgent` carries jsdom's
+`jsdom/<version>` signature and `adoptedStyleSheets` is missing, so it is a no-op in browsers,
+under Happy DOM and in plain Node projects. It installs once and returns a function that removes
+what it added.
+
+jsdom's `ElementInternals` has no form association, so every Lyra form control (`lr-button`,
+`lr-input`, `lr-checkbox`, …) throws in its constructor there. `installJsdomFormAssociatedShim()`
+adds, only where missing, an inert `setFormValue()`, a `setValidity()` that `validity`,
+`validationMessage`, `checkValidity()` and `reportValidity()` reflect, `willValidate`, `form` (the
+host's closest `<form>`) and a `Set` for `states`. Nothing is submitted and no `invalid` event
+fires. It has the same jsdom detection, install-once and restore behaviour.
+
+Lit decides whether it can adopt stylesheets when its module is first evaluated, so call the shim
+in a `setupFiles` entry before anything imports Lit or a Lyra component. Importing
+`@aceshooting/lyra-ui/testing` does not load Lit:
+
+```ts
+// vitest.setup.ts (environment: 'jsdom')
+import { installJsdomShims } from '@aceshooting/lyra-ui/testing';
+
+installJsdomShims();
+```
+
 ## Constructing a validated test event: `createLyraEvent()`
 
 `@aceshooting/lyra-ui/testing` also exports
@@ -2730,8 +2948,9 @@ semantics of their own that this factory does not model.
 
 ## Driving a component's real activation path: interaction drivers
 
-For the exact gap `createLyraEvent()` leaves open — choosing an option, submitting a confirm
-decision, toggling a switch, activating a step — `@aceshooting/lyra-ui/testing` exports a small
+For the exact gap `createLyraEvent()` leaves open — choosing an option, a swatch or a currency,
+submitting a confirm decision, toggling a switch, activating a step, opening and closing a
+popover — `@aceshooting/lyra-ui/testing` exports a small
 set of typed interaction drivers, one per interaction, that go through the real component's own
 activation path (its own shadow-part lookup and `.click()`, the same as its own tests) instead of
 a downstream suite reverse-engineering internal detail shapes or shadow-part selectors itself:
@@ -2739,17 +2958,43 @@ a downstream suite reverse-engineering internal detail shapes or shadow-part sel
 ```ts
 import {
   chooseOption,
+  chooseSwatch,
+  chooseCurrency,
+  openPopover,
+  closePopover,
   submitConfirmDecision,
   toggleSwitch,
   activateStep,
 } from '@aceshooting/lyra-ui/testing';
 
 await chooseOption(combobox, 'banana'); // opens the listbox, clicks the matching [part="option"] row
+await chooseSwatch(swatchPicker, 'ruby'); // clicks the matching swatch radio
+await chooseCurrency(currencyPicker, 'EUR'); // opens the composed listbox, clicks the EUR option
+await openPopover(popover); // clicks the slotted (or `for`) trigger, waits for lr-after-show
+await closePopover(popover); // presses Escape, waits for lr-after-hide; { via: 'trigger' } clicks instead
 await submitConfirmDecision(confirmBar, 'approved'); // clicks [part="approve-button"]
 await toggleSwitch(switchEl); // calls switchEl.click(), lr-switch's own activation path
 await activateStep(stepper, 'review'); // clicks the [part="step"] button for that stepId (or pass an index)
 ```
 
+`chooseSwatch(picker, value)` clicks the `<lr-swatch-picker>` radio whose value matches (the first
+enabled one when values repeat). When it resolves, `lr-change` (only if the selection moved) and
+`lr-activate` have fired. `chooseCurrency(picker, code)` drives the select, or the lazily loaded
+combobox of a `searchable` picker, that `<lr-currency-picker>` composes. The code must match the
+catalog exactly (`"EUR"`). When it resolves, the picker has emitted `input`, `lr-input`, `change`
+and `lr-change` once if the value changed.
+
+`openPopover(popover, { timeoutMs? })` clicks the `<lr-popover>` interaction trigger (the slotted
+`trigger` element, else its `for` target) and resolves after `lr-show` and `lr-after-show`. A
+`hover`/`focus` popover opens and pins, as for a user's click. `closePopover(popover, { via?,
+timeoutMs? })` presses Escape on the focused element by default, which closes the topmost overlay,
+or clicks the trigger again with `via: 'trigger'`. It resolves after `lr-hide` and `lr-after-hide`,
+with focus back on the trigger. Both resolve at once when the popover is already in the requested
+state. They throw when the interaction is refused: an `lr-show`/`lr-hide` veto, a disabled popover
+or trigger, `trigger="manual"`, no trigger, or Escape going to a newer overlay. Use `show()`/`hide()`
+for manual and `showAt()` popovers. A missing `lr-after-*` event rejects after `timeoutMs`
+(default 2000).
+
 `chooseOption()` accepts any of `<lr-combobox>`, `<lr-select>`, `<lr-model-select>`,
 `<lr-locale-picker>` and `<lr-voice-picker>` — every component that independently implements the
 same `[part="option"]` row plus `data-value` delegated-click pattern for its own listbox/popup.
@@ -2765,13 +3010,14 @@ immediately after it see the render reached by that interaction. Host-driven asy
 still need their own completion check. Each driver also throws a plain `Error` — never a
 silent no-op — when the requested interaction cannot actually happen: the target is disabled, the
 option owner/stepper is read-only or has no matching row/step currently rendered, or the confirm
-bar is already decided. That is the exact failure mode a hand-rolled event misses (for example
+bar is already decided, or a popover's lifecycle event was vetoed. That is the exact failure mode a hand-rolled event misses (for example
 dispatching a confirm event without `cancelable`, which makes a `preventDefault()`-based
 pending-state handler a silent no-op that still looks tested) — these drivers exercise the
 component for real, so a precondition that blocks the interaction is surfaced as a thrown error
 instead of quietly doing nothing.
 
-Pure DOM operations only (`Element.click()`, shadow-part queries, public properties) — no
+Pure DOM operations only (`Element.click()`, an Escape `KeyboardEvent`, shadow-part queries,
+public properties) — no
 `@web/test-runner`/CDP-only helper, so they also run under a downstream suite's own
 happy-dom/jsdom environment, not only a real browser.
 
@@ -3120,7 +3366,8 @@ arrowPadding?: number; hoverBridge?: HTMLElement; onPlaced?: (result: PlacementR
   (`next`); the `value` getter/setter (`next`); `defaultValue`; `customError`; `disabled`; `required`; readonly
   `effectiveDisabled`; the `form` getter/setter (`owner`); readonly `labels`, `validity`,
   `validationMessage`, and `willValidate`; `setFormValue(next)`; `getForm()`; `checkValidity()`;
-  `reportValidity()`; `setCustomValidity(message)`; `resetValidity()`; `formResetCallback()`; and
+  `reportValidity()`; `setCustomValidity(message)`; `resetValidity()`; `formResetCallback()`;
+  `formDisabledCallback(disabled)`; and
   `formStateRestoreCallback(state, reason)`.
   Writing `null` to `defaultValue` removes its markup value and resets the default to the adapter's
   empty value; reading it still returns `TValue`. This does not overwrite a dirty live value.
@@ -3143,7 +3390,8 @@ HTMLFormElement | null; set form(owner: FormOwnerValue); readonly labels: NodeLi
 validity: ValidityState; readonly validationMessage: string; readonly willValidate: boolean;
 setFormValue(next: TValue): void; getForm(): HTMLFormElement | null; checkValidity(): boolean;
 reportValidity(): boolean; setCustomValidity(message: string): void; resetValidity(): void;
-formResetCallback(): void; formStateRestoreCallback(state: FormSubmissionValue, reason:
+formResetCallback(): void; formDisabledCallback(disabled: boolean): void;
+formStateRestoreCallback(state: FormSubmissionValue, reason:
 'autocomplete' | 'restore'): void }`. The exported subclass seam is
   `FormAssociatedSubclassInterface<TValue> { protected captureLiveValueCheckpoint(): { readonly
 value: TValue; readonly dirty: boolean }; protected restoreLiveValueCheckpoint(checkpoint: {
@@ -4245,6 +4493,16 @@ These named interfaces and helper signatures are available to typed integrations
   `resolveCanvasColor(/* public names: scope, color, fallback */): unknown`
   `resolveCanvasColors(/* public names: scope, colors, fallback */): unknown`
 
+- **`internal-document-tokens-contracts`** — Shared utility contracts.
+  `adoptLyraTokens(root: Document | ShadowRoot): void`
+  Adopts the document token layer into a document or shadow root. Idempotent; see "Application
+  shadow roots" in the styles and tokens guide for when a root needs it.
+
+- **`internal-theme-scopes-contracts`** — Shared utility contracts.
+  `findUnscopedThemeInputs(root?: Document | DocumentFragment | Element): Element[]`
+  Lists elements that set an inline `--lr-theme-*` input the layer consumes without being a theme
+  scope. Reads inline styles only and logs nothing.
+
 - **`internal-localization-runtime-contracts`** — Shared utility contracts.
   `getLyraLocaleDirection(/* public names: locale */): unknown`
   `getLyraLocale(): unknown`
@@ -4980,15 +5238,45 @@ These named interfaces and helper signatures are available to typed integrations
 - **`testing-happy-dom-shims-contracts`** — Shared utility contracts.
   `installHappyDomFormAssociatedShims(): unknown`
   `installHappyDomShadowFocusShim(): unknown`
+  `flattenCascadeLayers(/* public names: css */): unknown`
   `installHappyDomAriaControlsShim(/* public names: proto */): unknown`
+  `installHappyDomCascadeLayerShim(/* public names: proto, misbehaves */): unknown`
   `installHappyDomShims(): unknown`
   `installStubInternalsForTest(/* public names: host */): unknown`
 
+- **`testing-jsdom-shims-contracts`** — Shared utility contracts.
+  `JsdomAdoptedStyleSheetsTargets {
+  documentPrototype?: object;
+  shadowRootPrototype?: object;
+  styleSheetPrototype?: object;
+  isJsdom?: () => boolean;
+}`
+  `installJsdomAdoptedStyleSheetsShim(targets?: JsdomAdoptedStyleSheetsTargets): () => void`
+  `JsdomFormAssociatedTargets {
+  internalsPrototype?: object;
+  elementPrototype?: object;
+  isJsdom?: () => boolean;
+}`
+  `installJsdomFormAssociatedShim(targets?: JsdomFormAssociatedTargets): () => void`
+  `installJsdomShims(): () => void`
+  See "jsdom: `installJsdomShims()`" above for the full contract.
+
 - **`testing-interaction-drivers-contracts`** — Shared utility contracts.
   `chooseOption(/* public names: owner, value */): unknown`
   `submitConfirmDecision(/* public names: owner, decision */): unknown`
   `toggleSwitch(/* public names: switchEl */): unknown`
   `activateStep(/* public names: stepper, target */): unknown`
+  `chooseSwatch(/* public names: picker, value */): unknown`
+  `chooseCurrency(/* public names: picker, code */): unknown`
+  `PopoverDriverOptions {
+  timeoutMs: unknown;
+}`
+  `ClosePopoverOptions {
+  via: unknown;
+  timeoutMs: unknown;
+}`
+  `openPopover(/* public names: popover, options */): unknown`
+  `closePopover(/* public names: popover, options */): unknown`
   See "Driving a component's real activation path: interaction drivers" above for the full contract.
 
 - **`testing-wait-for-mount-contracts`** — Shared utility contracts.
@@ -5085,6 +5373,7 @@ These named interfaces and helper signatures are available to typed integrations
   `parseLyraStyleRecord(value: unknown): Readonly<LyraStyle>`
   `resetLyraStyle(fields?: readonly LyraStyleField[]): Readonly<LyraStyle>`
   `setLyraStyle(choices: LyraStyleChoices): Readonly<LyraStyle>`
+  `startLyraStyle(): Readonly<LyraStyle>`
 
 - **`vue-contracts`** — Framework integration type contracts, including the multi-split
   `for` launcher id and `trigger` element reference.
@@ -5873,7 +6162,35 @@ of the backdrop; the default foreground qualification covers 60%, while a custom
 cannot guarantee contrast against every backdrop. Solid and accessibility preferences retain
 opaque fills regardless of this input.
 Dark Glass deepens the selected fill at opacity below 70% so light foregrounds remain readable
-against bright backdrops; at 70% and above, the selected fill keeps its original color.
+against bright backdrops; at 70% and above, the selected fill keeps its original color. The
+deepening blends toward a darkened `--lr-color-surface` (10% of the surface, the rest black), not
+pure black, so a lifted dark palette (for example a neutral grey `--lr-theme-color-surface-default`
+and overlay tokens) lifts its Glass chrome with it. That share is small on purpose: the stock
+palettes are qualified for 4.5:1 text over a pure white backdrop at 60% opacity, which caps how
+light the pane can get. To paint a lifted palette's own overlay colour, set `--lr-theme-surface-opacity`
+to 0.7 or higher.
+
+`--lr-theme-surface-glass-dark-share` is the public input for that share. It is a percentage,
+default `10%`, read in dark mode only, below 70% opacity. It sets how much of `--lr-color-surface`
+the deepening anchor keeps (the rest is black), so raising it lifts dark Glass chrome toward the
+surface. It inherits, so set it on `:root` for the whole app or on any container for that subtree;
+values outside 0% to 100% clamp. It is deliberately not registered with `@property` (a registered
+inherited property slows every re-theme in Chromium), so a value that is not a percentage voids the
+dark fill; the development build warns about one set on `:root`. The default paints exactly as before. For a softer grey dark mode:
+
+```css
+:root {
+  --lr-theme-color-surface-default: #1f2023;
+  --lr-theme-color-surface-raised: #1f2023;
+  --lr-theme-color-surface-overlay: #1f2023;
+  --lr-theme-surface-glass-dark-share: 60%;
+}
+```
+
+The trade-off is contrast: the 4.5:1 qualification over a white backdrop at 60% opacity holds for
+the stock palettes only at the 10% default, and a lighter pane lowers light-text contrast over bright
+backdrops. After raising the share, re-measure your own text colours, or raise
+`--lr-theme-surface-opacity` to 0.7 or higher, where the fill keeps the palette's own colour.
 Necessary control borders use the effective painted opacity: their glass adjustment grows as
 transparency increases and disappears at 100% opacity. Ordinary and strong borders share this
 adjustment; decorative borders and explicit component border overrides keep their own tokens.