@aceshooting/lyra-ui 23.0.0 → 24.0.0

package/llms/shared/events-and-types.md

@@ -6,7 +6,8 @@ Lyra-specific events are `lr-`-prefixed `CustomEvent`s (`lr-change`, `lr-input`,
 dispatched through `LyraElement`'s `protected emit<T>(name, detail?, options?)`: **bubbling,
 composed, and non-cancelable by default**, with the payload on `event.detail`. A component that
 offers a genuine veto point opts into `{ cancelable: true }` and checks `defaultPrevented` before
-acting (as `lr-export` does) — that is called out per component. Native wrappers may additionally
+acting (as `lr-export-request` on `<lr-export-button>` does) — that is called out per component.
+Native wrappers may additionally
 relay unprefixed `Event`, `InputEvent`, or `FocusEvent` instances; each component section documents
 the exact native names, constructors, bubbling, and cancelability it supports.
 
@@ -23,6 +24,10 @@ Every one of those names is also typed — per component through its own event m
 through `@aceshooting/lyra-ui/events` for listeners on an ancestor, `document` or `window`. See
 "TypeScript" below.
 
+For the manually reviewed, retained event-detail compatibility fields in the v23-to-v24 upgrade,
+use step 7 of the [migration checklist](v23-to-v24-migration.md#migrate-a-project-in-reviewable-steps).
+Those nested detail fields are separate from deprecated event names and are not automatic renames.
+
 ## TypeScript
 
 - **Per-component event maps.** Every component with events exports a `Lyra<Name>EventMap` type, and
@@ -1586,34 +1591,30 @@ These named interfaces and helper signatures are available to typed integrations
   copy, so a glyph rendered anywhere else on the page can match it exactly by consuming the same
   export and attribute.
 
-- **`theme-presets-contracts`** — Shared utility contracts.
-  `applyLyraThemePreset(/* public names: presetOrName */): unknown`
-  `defineLyraThemePreset(/* public names: preset */): unknown`
-  `LyraThemePresetChangeDetail {
-  id: unknown;
-  theme: unknown;
-}`
-  `LyraThemePreset {
-  id: unknown;
-  theme: unknown;
-}`
-
 - **`theme-theme-contracts`** — Shared utility contracts.
-  `createLyraThemeBootstrap(/* public names: options */): unknown`
-  `getLyraTheme(): unknown`
+  `createLyraThemeBootstrap(options?: LyraThemeBootstrapOptions): string`
   `LyraThemeBootstrapOptions {
-  storageKey: unknown;
-}`
-  `LyraTheme {
-  mode: unknown;
-  accent: unknown;
-  surface: unknown;
-  tokens: unknown;
-}`
-  `setLyraTheme(/* public names: theme */): unknown`
+  storageKey?: string;
+}`
+  `LyraThemeSemanticRole = 'brand' | 'success' | 'warning' | 'danger' | 'neutral'`
+  `LyraThemeAccentValue = string | null | { light?: string | null; dark?: string | null }`
+  `LyraThemeAccent = string | null | Partial<Record<LyraThemeSemanticRole, LyraThemeAccentValue>>`
+  ``LyraThemeTokenName = `--lr-theme-${string}```
+  `LyraThemeTokenValue = string | { light?: string | null; dark?: string | null }`
+  `LyraThemeTokens = Readonly<Record<LyraThemeTokenName, LyraThemeTokenValue>>`
+  `LyraStyleAxis = 'look' | 'surface' | 'density' | 'mode' | 'accent'`
+  `LyraStyleField = LyraStyleAxis | 'accentBackground' | 'overrides'`
+  `LyraLookId = 'lyra' | 'shadcn' | 'material' | (string & {})`
+  `LyraSurface = 'solid' | 'glass'`
+  `LyraDensity = 'compact' | 'comfortable' | 'touch'`
+  `LyraMode = 'light' | 'dark' | 'system' | 'unset'`
+  `LyraAccentName = 'emerald' | 'peridot' | 'topaz' | 'ruby' | 'tourmaline' | 'amethyst' | 'aquamarine' | 'sapphire' | 'hematite'`
+  `LyraAccent = LyraAccentName | LyraThemeAccent`
+  `LyraAccentBackground = string | { light?: string | null; dark?: string | null } | null`
   `applyLyraStyleScope(element: Element, choices: LyraStyleScopeChoices | null): void`
   `defineLyraLook<const Look extends LyraLook>(look: Look): Readonly<Look>`
   `getLyraStyle(): Readonly<LyraStyle>`
+  `lyraThemeBootstrap: string`
   `LyraLook {
   readonly id: LyraLookId;
   readonly tokens: LyraThemeTokens;

package/llms/shared/frameworks-and-ssr.md

@@ -32,12 +32,16 @@ and adapters emit empty JavaScript and do not register elements.
 
 ## SSR and declarative shadow DOM
 
+When replacing the removed combined `ssr-loader.js` route, split browser hydration from component
+registration and server rendering as shown below. The [v23-to-v24 migration guide](v23-to-v24-migration.md)
+has the ordered upgrade steps and environment-specific import mapping.
+
 Root, `all.js`, and granular component imports are server-safe under the supported Node 22+ runtime.
 `@aceshooting/lyra-ui/ssr/all.js` is the **server-only** convenience entry: unlike the browser
 `all.js`, it registers the complete inventory including the optional-peer families — defining those
 tags never imports their peers (each component loads its own lazily, client-side), and the
 browser-bundle argument for excluding them does not apply to a server render. Use the public
-`@aceshooting/lyra-ui/ssr-loader.js` entry for the tested Lit SSR contract. Its exported
+`@aceshooting/lyra-ui/ssr.js` entry for the tested Lit SSR contract. Its exported
 `LYRA_SSR_SUPPORT_MATRIX`, `LYRA_SSR_RENDER_AND_HYDRATE_TAGS`, and
 `LYRA_SSR_CLIENT_RENDER_TAGS` classify every inventory tag exactly once:
 
@@ -50,7 +54,7 @@ browser-bundle argument for excluding them does not apply to a server render. Us
 Server setup (the fallback must precede Lit's renderer):
 
 ```ts
-import { lyraSsrElementRenderers } from "@aceshooting/lyra-ui/ssr-loader.js";
+import { lyraSsrElementRenderers } from "@aceshooting/lyra-ui/ssr.js";
 import { render, LitElementRenderer } from "@lit-labs/ssr";
 import { html } from "lit";
 
@@ -59,7 +63,7 @@ const result = render(html`<lr-page><main>Dashboard</main></lr-page>`, {
 });
 ```
 
-In the browser, import `@aceshooting/lyra-ui/ssr-loader.js` before any other module that can import
+In the browser, import `@aceshooting/lyra-ui/hydration.js` before any other module that can import
 Lit. This installs `@lit-labs/ssr-client/lit-element-hydrate-support.js` before component
 registration. `getLyraSsrMode(tagName)` reads one tag's tier, and
 `diagnoseLyraHydration(document)` inspects current Lyra hosts in the supplied tree and every

package/llms/shared/imports-and-registration.md

@@ -60,8 +60,8 @@ way, and moving to the replacement removes the warning. A test suite that fails
 while deliberately exercising a deprecated form can pre-seed Lit's development-mode
 `globalThis.litIssuedWarnings` set, before the element renders, with the key
 `lyra-deprecated:<owner>:<kind>:<name>` — `<kind>` and `<name>` as in the deprecation record.
-`<owner>` is the element name or package-relative module specifier; for example,
-`lyra-deprecated:./theme.js:function:setLyraTheme`.
+`<owner>` is the element name or package-relative module specifier. Theme migration guidance is in
+[styles and tokens](styles-and-tokens.md).
 
 ### Release history and upgrade notes
 
@@ -82,6 +82,13 @@ The major-version landmarks after 9.0.0 are:
   that themselves overrode the hook are affected. Collection snapshot enforcement moved to a
   decorator-agnostic accessor seam instead.
 
+- **24.0.0:** removed eligible v22 compatibility routes, including package-root component
+  constructors, duplicate nested registration entries, the combined `ssr-loader.js` entry, and the
+  retired theme/preset facade. Use stable tag-shaped registration entries, a component's
+  registration-free `.class.js` subpath, the split SSR/hydration entries, and the current style API.
+  The [v23-to-v24 migration guide](v23-to-v24-migration.md) gives the removed routes, ordered
+  consumer cleanup and retained-profile instructions.
+
 ### The support window
 
 Compatibility promises are bounded by a published support window, not by "evergreen browsers":
@@ -106,9 +113,9 @@ import "@aceshooting/lyra-ui/components/lr-combobox.js"; // registers <lr-combob
 import "@aceshooting/lyra-ui/components/lr-table.js"; // registers <lr-table>
 ```
 
-The older family-shaped registration paths remain supported for compatibility. Class-only
-`.class.js` entries still use their owning family path because they intentionally expose source
-organization and do not register a tag.
+Family barrel entries remain supported and register their family. Class-only `.class.js` entries
+use their owning family/component path because they intentionally expose source organization and
+do not register a tag.
 
 New application code can import any component through its stable tag-shaped path:
 
@@ -119,8 +126,7 @@ import "@aceshooting/lyra-ui/components/lr-tool-call-block.js";
 ```
 
 `llms/index.md` lists every tag and its owning implementation module. The stable tag-shaped alias
-and the family-shaped compatibility path both resolve through the package's `./components/*`
-export.
+and the supported family barrel each resolve through the package's component exports.
 
 The package root is a pure, side-effect-free export surface. Import a component entry to register
 only that tag, or use the explicit `all.js` entry when whole-library registration is needed:
@@ -129,17 +135,11 @@ only that tag, or use the explicit `all.js` entry when whole-library registratio
 import "@aceshooting/lyra-ui/all.js"; // explicitly registers the root-included tags
 ```
 
-Import component classes from their family-shaped `.class.js` subpaths. Deprecated root
-component-class exports refer to the component constructor bindings themselves, including a
-constructor re-exported from a module that also exports helpers or types. That deprecation does not
-extend to sibling helpers, constants, or types; those remain supported unless they have their own
-deprecation record. Use the owning component's granular `.class.js` subpath for class imports.
-Family-shaped registration imports are also deprecated. Both deprecated root component-class exports
-and family-shaped registration imports keep working throughout the compatibility window, with
-removal no earlier than 24.0.0. Stable tag-shaped registration imports and class-only subpaths are
-the canonical routes. The package root's helpers and types remain available. `all.js` is
-side-effectful and registers the root-included inventory; prefer tag-shaped imports in application
-code for smaller bundles.
+The package root does not re-export component constructors. Import a class from its owning
+component's `.class.js` subpath; import the stable tag-shaped entry to register it. The root remains
+a side-effect-free home for shared utilities and types. Family registration barrels and `all.js`
+remain side-effectful convenience entries; prefer tag-shaped imports for smaller application
+bundles.
 
 The entry points, then:
 
@@ -178,7 +178,7 @@ The entry points, then:
     LyraAnchor,
     LyraHighlight,
     AnchorTargetCapabilities,
-  } from "@aceshooting/lyra-ui/components/viewers/document-viewer/document-viewer.js";
+  } from "@aceshooting/lyra-ui/components/lr-document-viewer.js";
   ```
   Prefer the granular entry for component-local imports; use the root export when an application
   deliberately shares the contracts across several viewer integrations.
@@ -186,13 +186,13 @@ The entry points, then:
   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),
-  `@aceshooting/lyra-ui/themes/shadcn.css` (opt-in shadcn/ui look, imported after `theme.css` — see
-  [The shadcn look](./styles-and-tokens.md#the-shadcn-look--themesshadcncss)),
+  `@aceshooting/lyra-ui/looks/shadcn.css` (opt-in shadcn/ui look, imported after `theme.css` — see
+  [The shadcn look](./styles-and-tokens.md#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/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 mode/accent runtime),
+  `@aceshooting/lyra-ui/theme.js` (the zero-dependency style runtime),
   `@aceshooting/lyra-ui/localization.js` (side-effect-free locale runtime),
   `@aceshooting/lyra-ui/autoloader.js` (side-effect-free on-demand tag loading),
   `@aceshooting/lyra-ui/autoloader-cdn.js` (browser-guarded auto-start side effect),

package/llms/shared/localization-and-rtl.md

@@ -61,8 +61,8 @@ The side-effect-free `@aceshooting/lyra-ui/localization.js` entry exports
 `LyraPluralMessage`, `LyraPluralCategory`, `LyraLocaleBridgeOptions` and `LyraLocaleBridgeCleanup`.
 The package root continues to re-export the runtime for compatibility and remains registration-free;
 use the dedicated entry when the application only needs locale setup and the narrower import graph.
-The former `@aceshooting/lyra-ui/utilities/localization.js` entry point was removed in 23.0.0.
-Change that import specifier to `@aceshooting/lyra-ui/localization.js`; the helper contracts are unchanged.
+The former utility-scoped entry point was removed in 23.0.0. Change that import specifier to
+`@aceshooting/lyra-ui/localization.js`; the helper contracts are unchanged.
 **`LYRA_DEFAULT_STRINGS` is the authoritative key list** (matching the `LyraMessageKey` union) —
 read it to find the key to override rather than guessing one. Date, number, byte, relative-time and
 calendar output goes through `Intl`.

package/llms/shared/native-styles-and-utilities.md

@@ -0,0 +1,263 @@
+# Native styles and CSS utilities
+
+## Optional native styles and CSS utilities
+
+Lyra ships two independent light-DOM stylesheets. Neither is imported by the root barrel, a family
+barrel, a component entry, or `theme.css`, so applications that do not opt in keep their existing
+native-element and utility conventions unchanged.
+
+```css
+@import "@aceshooting/lyra-ui/native.css";
+@import "@aceshooting/lyra-ui/utilities.css";
+```
+
+`native.css` places its rules in `lr-base` and styles native elements only when they are
+**descendants** of an explicit `.lr-native` scope. It has no `:root`, `html`, `body`, or unscoped
+reset, and the element carrying `.lr-native` is not styled by the native bundle itself. The rules
+stay in light DOM: they do not pierce a component's shadow root.
+
+```html
+<section class="lr-native">
+  <h2>Profile</h2>
+  <label for="profile-name">Display name</label>
+  <input id="profile-name" />
+  <button type="button">Save</button>
+</section>
+```
+
+`utilities.css` places exact, zero-specificity `:where(.lr-*)` classes in `lr-utilities`. It never
+uses a substring class selector, so a class such as `app-lr-flex-preview` does not opt in. Both
+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`](./styles-and-tokens.md#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.
+
+### Utility class inventory
+
+| Group                       | Exact classes                                                                                                                                                     |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Display and composition     | `lr-block`, `lr-inline-block`, `lr-flex`, `lr-inline-flex`, `lr-grid`, `lr-flow-root`, `lr-stack`, `lr-cluster`, `lr-grid-auto`                                   |
+| Flex direction and wrapping | `lr-row`, `lr-column`, `lr-wrap`, `lr-nowrap`, `lr-grow`, `lr-grow-0`, `lr-shrink`, `lr-shrink-0`                                                                 |
+| Item alignment              | `lr-items-start`, `lr-items-center`, `lr-items-end`, `lr-items-stretch`, `lr-items-baseline`, `lr-self-start`, `lr-self-center`, `lr-self-end`, `lr-self-stretch` |
+| Distribution                | `lr-justify-start`, `lr-justify-center`, `lr-justify-end`, `lr-justify-between`, `lr-justify-around`                                                              |
+| Gaps                        | `lr-gap-0`, `lr-gap-xs`, `lr-gap-s`, `lr-gap-m`, `lr-gap-l`, `lr-gap-2xl`                                                                                         |
+| Logical sizing              | `lr-inline-full`, `lr-block-full`, `lr-size-full`, `lr-min-inline-0`, `lr-min-block-0`, `lr-max-inline-full`, `lr-max-inline-prose`, `lr-center`                  |
+| Overflow                    | `lr-overflow-auto`, `lr-overflow-hidden`                                                                                                                          |
+| Text alignment and size     | `lr-text-start`, `lr-text-center`, `lr-text-end`, `lr-text-xs`, `lr-text-sm`, `lr-text-base`, `lr-text-lg`, `lr-text-xl`, `lr-text-quiet`                         |
+| Font                        | `lr-font-normal`, `lr-font-medium`, `lr-font-semibold`, `lr-font-bold`, `lr-font-mono`                                                                            |
+| Text flow                   | `lr-text-break`, `lr-text-nowrap`, `lr-truncate`, `lr-text-balance`, `lr-text-pretty`, `lr-prose`                                                                 |
+| Typography                  | `lr-typography`, `lr-not-typography`, `lr-heading-1`, `lr-heading-2`, `lr-heading-3`, `lr-heading-4`, `lr-inline-code`                                           |
+| Visibility and focus        | `lr-visually-hidden`, `lr-visually-hidden-focusable`, `lr-fouce-hidden`, `lr-hidden`                                                                              |
+| Page allocation             | `lr-page-mobile-only`, `lr-page-desktop-only`                                                                                                                     |
+
+`lr-fouce-hidden` hides only an opted-in custom element while it matches `:not(:defined)`, then
+reveals it automatically after registration. `lr-visually-hidden-focusable` becomes visible on
+focus or when a descendant receives focus, making it suitable for skip links.
+
+The Page helpers key off the reflected `view` state of their containing `<lr-page>`:
+`lr-page-mobile-only` is hidden for `view="desktop"`, and `lr-page-desktop-only` is hidden for
+`view="mobile"`. Page derives that state from its own allocated inline size, not the viewport.
+
+### Typography
+
+`utilities.css` also carries an opt-in typography look for light-DOM content. Nothing changes for
+markup that does not use these classes.
+
+- **Scope** — `lr-typography` styles bare `h1`–`h6`, `p`, `a[href]`, `blockquote`, `ul`/`ol`/`li`,
+  inline `code` (not `pre code`) and `table`/`th`/`td`/`tr` **descendants**, and spaces its direct
+  children. Use it for CMS or Markdown-rendered HTML you cannot annotate element by element.
+- **Roles** — `lr-heading-1` … `lr-heading-4` give any element a heading level's look without
+  changing its semantic level; `lr-inline-code` gives one element the inline-code chip. Role classes
+  apply anywhere, including inside a boundary, and an explicit role beats the element's own level
+  inside the scope (`<h3 class="lr-heading-1">` renders heading-1).
+- **Boundary** — `lr-not-typography` removes an element and its whole subtree from every element
+  look. Use it around layout lists (`<ul class="lr-cluster">` tag rows, nav), embedded widgets and
+  component clusters. A nested `lr-typography` inside a boundary is not re-enabled.
+- **Named-slot children are skipped.** A child with a `slot` attribute (`<lr-card><h2
+  slot="header">`) is component chrome and keeps the component's own styling; default-slot content
+  is styled.
+- **The scope element itself is never styled.** It sets no font, size, colour or margin, so it can
+  sit on an app region. `<blockquote class="lr-typography">` does nothing: wrap single elements.
+  Root font and colour come from the page, from `lr-prose` or from `lr-native`
+  (`class="lr-prose lr-typography"` is the usual pairing).
+
+Choose the element for the document outline and the class for the look: `<h2 class="lr-heading-1">`
+for a visually dominant section heading, never `<div class="lr-heading-1">`.
+
+| Element in `lr-typography` | Role class       | Look                                                                                   |
+| -------------------------- | ---------------- | -------------------------------------------------------------------------------------- |
+| `h1`                       | `lr-heading-1`   | `--lr-font-size-3xl`, bold, compact leading                                            |
+| `h2`                       | `lr-heading-2`   | `--lr-font-size-2xl`, semibold, subtle bottom rule with `--lr-space-s` padding         |
+| `h3`                       | `lr-heading-3`   | `--lr-font-size-xl`, semibold                                                          |
+| `h4`                       | `lr-heading-4`   | `--lr-font-size-lg`, semibold                                                          |
+| `h5` / `h6`                | —                | `--lr-font-size-m` / `--lr-font-size-sm`, semibold                                     |
+| `p`                        | —                | `--lr-line-height-loose`                                                               |
+| `a[href]`                  | —                | `--lr-color-brand`, always underlined; the underline thickens on hover                 |
+| `blockquote`               | —                | italic, subtle `--lr-border-width-medium` inline-start edge, inherited colour          |
+| `ul` / `ol`                | —                | `--lr-space-2xl` indent, markers restated (disc/circle/square, decimal), item rhythm   |
+| inline `code`              | `lr-inline-code` | mono chip on `--lr-color-neutral-fill-quiet`, `0.875em`, semibold; inherits link colour |
+| `table`                    | —                | full width, collapsed subtle cell borders, bold `th`, `--lr-color-surface-raised` zebra |
+
+Headings, role classes and quotes inherit their colour, so a role class inside a banner or alert
+keeps that surface's text colour. Heading tracking reads `--lr-heading-letter-spacing`, then the
+`--lr-theme-heading-letter-spacing` theme input, then `normal`.
+
+**Lead, large, small and muted** are compositions of existing utilities:
+
+| Look  | Classes                         |
+| ----- | ------------------------------- |
+| Lead  | `lr-text-xl lr-text-quiet`      |
+| Large | `lr-text-lg lr-font-semibold`   |
+| Small | `lr-text-sm lr-font-medium`     |
+| 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):
+
+```css
+.app-muted {
+  font-size: var(--lr-font-size-md-sm, var(--lr-theme-font-size-md-sm, 0.875rem));
+}
+.app-small {
+  font-size: var(--lr-font-size-md-sm, var(--lr-theme-font-size-md-sm, 0.875rem));
+  line-height: var(--lr-line-height-none, var(--lr-theme-line-height-none, 1));
+}
+```
+
+Combine `.app-muted` with `lr-text-quiet`, and `.app-small` with `lr-font-medium`.
+
+**Precedence.** Every selector has zero specificity, so source order and layers decide:
+
+1. The typography element looks and role classes open the `lr-utilities` layer, so any other `lr-*`
+   utility on the same element wins: `class="lr-heading-2 lr-text-quiet"` is a quiet heading, and a
+   scope `<blockquote class="lr-center">` is centred.
+2. An explicit heading role class beats the element's own scope look (`<h2 class="lr-heading-4">`
+   has no bottom rule).
+3. In `class="lr-prose lr-typography"`, `lr-prose` keeps the measure, root type and colour, and the
+   typography element looks and heading-aware spacing win. Inside a boundary, or on a named-slot
+   child, `lr-prose` applies exactly as before. Plain `lr-prose` output is unchanged.
+4. `lr-utilities` beats `lr-base`, so the scope beats `lr-native` normalization, including its link,
+   quote and heading colours.
+5. A layered reset (such as Tailwind's `base` preflight) loses only when you declare the documented
+   layer order first — see [Using the light-DOM stylesheets with a CSS
+   reset](#using-the-light-dom-stylesheets-with-a-css-reset-tailwind-v4-preflight-and-similar).
+   Authored `type` (lists) and `align` (cells) attributes are presentational hints that any author
+   rule, including a reset, overrides.
+
+Any unlayered application rule beats all of the above.
+
+**Flow.** Every direct, non-slotted child of the scope has its block margins replaced by
+`--lr-prose-flow-space` (default `--lr-space-l`), and a heading gets twice that space before it.
+That includes wrappers, `hr`, `img`, `details`, `section` and `lr-*` elements, so a component's own
+host margin is overridden at that position (wrap it in a `<div>` to keep it). Flow counts the
+immediately preceding element sibling, including non-rendered ones (`<style>`, `<template>`,
+`[hidden]`), so keep those out of the scope's direct children. Blocks nested inside `li` or
+`blockquote` keep the page's own margins. Do not put `lr-stack`/`lr-cluster` on the scope element
+itself — gap and flow margins would add up (set `--lr-prose-flow-space: 0` if you must).
+
+**Wide tables** go in a focusable, labelled scroll region, labelled by the table's own caption:
+
+```html
+<div class="lr-overflow-auto" role="region" aria-labelledby="pricing-caption" tabindex="0">
+  <table>
+    <caption id="pricing-caption">Plans and prices</caption>
+    …
+  </table>
+</div>
+```
+
+**Differences from the shadcn/ui look.** Values come from Lyra's scale:
+
+| Element               | Lyra                                                          | shadcn/ui                               |
+| --------------------- | ------------------------------------------------------------- | --------------------------------------- |
+| Heading sizes         | 2 / 1.75 / 1.25 / 1.125rem                                    | 2.25 / 1.875 / 1.5 / 1.25rem            |
+| h1 weight             | 700                                                           | 800                                     |
+| Tracking              | `normal` unless the hook or theme input sets it; `looks/shadcn.css` sets -0.025em | tight              |
+| Flow spacing          | 1rem (`--lr-prose-flow-space`)                                | 1.5rem                                  |
+| Space before headings | 2 × flow = 2rem for every level                               | 2.5rem before h2, 2rem before h3        |
+| Paragraph leading     | 1.6                                                           | 1.75rem                                 |
+| Quote and list indent | 1rem and 2rem                                                 | 1.5rem each                             |
+| Inline code size      | 0.875em (scales inside headings)                              | 0.875rem                                |
+| Inline code padding   | 0.25rem inline / 0.125rem block                               | 0.3rem / 0.2rem                         |
+| Table stripe          | `--lr-color-surface-raised` (matches `lr-data-grid`)          | muted fill                              |
+| Links                 | brand colour, inherited weight, underline                     | primary colour, medium weight, underline |
+| Muted and small size  | 0.8125rem via `lr-text-sm` (exact recipe above)               | 0.875rem                                |
+| Small line-height     | inherited (exact recipe above)                                | 1                                       |
+
+**Languages.** Only logical properties are used, so edges and indents mirror under `dir="rtl"`.
+Blockquotes under `:lang()` `ar`, `fa`, `ur`, `ps`, `ckb`, `sd`, `ug`, `syr`, `he`, `yi`, `ja`, `ko`
+and `zh` are not italic (those scripts have no true italic), and headings under `ar`, `fa`, `ur`,
+`ps`, `ckb`, `sd`, `ug` and `syr` reset `letter-spacing` to `normal` (negative tracking breaks
+cursive joins). To add a language to either list, or to opt back in, write an unlayered rule; it
+wins.
+
+**`lr-markdown`** renders into its own shadow root, which `utilities.css` cannot reach. For a
+similar look, use its existing parts and hooks:
+
+```css
+lr-markdown::part(inline-code) {
+  background: var(--lr-color-neutral-fill-quiet, var(--lr-theme-color-neutral-fill-quiet));
+  font-weight: var(--lr-font-weight-semibold, var(--lr-theme-font-weight-semibold, 600));
+}
+lr-markdown {
+  --lr-markdown-table-header-bg: transparent;
+}
+lr-markdown::part(blockquote) {
+  font-style: italic;
+}
+```
+
+The `blockquote` rule carries the same `:lang()` caveat as above.
+
+### Using the light-DOM stylesheets with a CSS reset (Tailwind v4 preflight and similar)
+
+A layered reset such as Tailwind v4's preflight lives in its own `base` layer. Layer order is fixed
+by first appearance, so if the reset's layers are declared first they sort **after** Lyra's and
+outrank `native.css` and `utilities.css`: headings shrink to body size, list markers and link
+underlines disappear. Declare the full order as the **first** CSS the page loads — for example a
+tiny `layers.css` imported before `tailwindcss` and before any Lyra CSS:
+
+```css
+/* layers.css — load first */
+@layer theme, base, lr-base, lr-theme, lr-theme-preset, components, lr-utilities, utilities, lr-overrides;
+```
+
+The reset then sorts before Lyra's layers, and Tailwind's own utilities after `lr-utilities`. List
+markers and link underlines inside `lr-typography` survive the reset because the scope restates
+them. An authored `type` on a list or `align` on a cell does not: presentational hints lose to every
+author rule, so under a reset set `list-style-type` (or `text-align`) with a class instead.
+
+### Bundle-specific override hooks
+
+The bundles consume the ordinary shared color, typography, spacing, border, radius, focus, size,
+and opacity tokens first. These additional hooks customize only the light-DOM bundle behavior:
+
+| Hook                                      | Default/fallback and use                                                     |
+| ----------------------------------------- | ---------------------------------------------------------------------------- |
+| `--lr-layout-gap`                         | `--lr-space-m`; default gap for `lr-stack`, `lr-cluster`, and `lr-grid-auto` |
+| `--lr-grid-min-inline-size`               | `--lr-size-14rem`; minimum auto-grid item inline size                        |
+| `--lr-content-max-inline-size`            | `--lr-size-48rem`; `lr-center` content measure                               |
+| `--lr-prose-max-inline-size`              | `65ch`; `lr-prose` and `lr-max-inline-prose` measure                         |
+| `--lr-prose-flow-space`                   | `--lr-space-l`; flow spacing between direct blocks of `lr-prose` and `lr-typography`; the space before an `lr-typography` heading is twice this value |
+| `--lr-prose-quote-padding`                | `--lr-space-l`; logical quote inset in `lr-prose` and `lr-typography`        |
+| `--lr-prose-quote-border-width`           | `--lr-border-width-thick` in `lr-prose`, `--lr-border-width-medium` in `lr-typography`; logical quote edge |
+| `--lr-heading-letter-spacing`             | `--lr-theme-heading-letter-spacing`, then `normal`; heading tracking for `lr-heading-1`–`4` and `lr-typography` headings |
+| `--lr-theme-heading-letter-spacing`       | unset; theme input for heading tracking (no resolved `--lr-*` token); `looks/shadcn.css` sets it |
+| `--lr-visually-hidden-size`               | `--lr-size-1px` (1px); retained hidden box size                              |
+| `--lr-native-link-decoration-width`       | `--lr-border-width-thin`; resting underline thickness                        |
+| `--lr-native-link-underline-offset`       | `--lr-space-2xs`; underline offset                                           |
+| `--lr-native-link-hover-decoration-width` | `--lr-border-width-medium`; hovered underline thickness                      |
+| `--lr-native-pre-padding`                 | `--lr-space-m`; preformatted block padding                                   |
+| `--lr-native-tab-size`                    | `2`; preformatted tab width                                                  |
+| `--lr-native-quote-padding`               | `--lr-space-l`; native blockquote logical inset                              |
+| `--lr-native-quote-border-width`          | `--lr-border-width-thick`; native blockquote logical edge                    |
+| `--lr-native-control-min-block-size`      | `--lr-icon-button-size`; native control hit-area floor                       |
+| `--lr-native-control-padding-block`       | `--lr-space-s`; native control block padding                                 |
+| `--lr-native-control-padding-inline`      | `--lr-space-m`; native control inline padding                                |
+| `--lr-native-placeholder-opacity`         | `1`; native input/textarea placeholder opacity                               |
+| `--lr-native-summary-min-block-size`      | `--lr-icon-button-size`; native summary hit-area floor                       |
+| `--lr-native-fieldset-padding`            | `--lr-space-l`; fieldset padding                                             |
+| `--lr-native-legend-padding`              | `--lr-space-xs`; legend inline padding                                       |
+| `--lr-native-table-cell-padding`          | `--lr-space-s`; caption and table-cell padding                               |
+| `--lr-native-rule-space`                  | `--lr-space-l`; horizontal-rule block margin                                 |