@aceshooting/lyra-ui 27.0.0 → 28.1.0

package/llms/shared/styles-and-tokens.md

@@ -61,17 +61,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
 
@@ -85,7 +86,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
@@ -265,20 +265,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);
@@ -293,10 +308,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                                                                                                                                                                                                                     |
 | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -309,53 +323,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>
 ```
 
-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.
+- **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
+```
+
+**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
 
@@ -396,8 +479,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;
 }
 ```
@@ -572,6 +656,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
@@ -618,25 +709,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;
 }
@@ -659,8 +758,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.
 
@@ -770,28 +870,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
@@ -804,8 +892,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
@@ -876,6 +967,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.
@@ -1155,7 +1267,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.