@aceshooting/lyra-ui 11.1.0 → 12.0.0

package/llms/components/lr-map.md

@@ -16,8 +16,9 @@
 ## `lr-map`
 
 A `maplibre-gl` wrapper with a declarative legend, a single choropleth GeoJSON fill layer, markers,
-and additive plain-GeoJSON `dataLayers`, plus a peer-neutral `map` getter for common imperative
-operations. Its runtime value is the underlying MapLibre map.
+and additive `dataLayers` — plain GeoJSON, natively clustered points, or a heatmap density surface —
+plus a peer-neutral `map` getter for common imperative operations. Its runtime value is the
+underlying MapLibre map.
 
 **Properties:**
 
@@ -100,7 +101,8 @@ string; geojson: GeoJSON.FeatureCollection; field: string; stops: [number, strin
 - `dataLayers: LyraMapGeoJsonDataLayer[] = []` (attribute: false) —
   `LyraMapGeoJsonDataLayer { sourceId: string; geojson: GeoJSON.Feature |
 GeoJSON.FeatureCollection; tone?: 'accent' | 'success' | 'warning' |
-'danger' | 'neutral'; color?: string; strokeColor?: string }`. `sourceId` is trimmed and must be nonempty; the first layer for a
+'danger' | 'neutral'; color?: string; strokeColor?: string; kind?: LyraMapDataLayerKind;
+heatmap?: LyraMapHeatmapOptions; cluster?: LyraMapClusterOptions }`. `sourceId` is trimmed and must be nonempty; the first layer for a
   `sourceId` wins and blank or later duplicate records are ignored. Each retained entry adds one
   GeoJSON source plus three geometry-filtered layers
   (fill, line, and circle, so a mixed `FeatureCollection` renders correctly), colored from the
@@ -123,6 +125,55 @@ GeoJSON.FeatureCollection; tone?: 'accent' | 'success' | 'warning' |
   persists across a `dataLayers` reassignment gets its GeoJSON updated in place (`setData()`), one
   that's dropped has its private source/layers removed, and a genuinely new `sourceId` gets new
   resources — nothing leaks on removal, style change, or disconnect.
+
+  `cluster` and `kind` (both new in 11.3.0) opt one entry out of that three-layer geometry split.
+  **Both are strictly additive: an entry that sets neither renders exactly what it rendered before,
+  down to the layer ids and the point layer's filter.**
+
+  `cluster?: LyraMapClusterOptions { radius?: number; maxZoom?: number; radiusSteps?: [number,
+number][]; colorSteps?: [number, string][]; countFont?: string[] }` turns the entry's source into a
+  natively clustered one — `cluster`/`clusterRadius` (default 50)/`clusterMaxZoom` (default 14) on
+  the source, plus a `${sourceId}-cluster` circle filtered on `has('point_count')`, a
+  `${sourceId}-cluster-count` label, and a `${sourceId}-circle` layer for the points that stayed
+  unclustered. `cluster: {}` opts in at every default. This is what a thousands-of-points map needs
+  and what `markers` cannot be: `markers` mints one real, individually focusable DOM element per
+  entry, which is right for tens of pins and both unreadable and expensive for thousands.
+  `radiusSteps` and `colorSteps` are `['step', …]` breaks keyed on `point_count`, in the same
+  ascending `[value, output]` vocabulary as `choropleth.stops` — including the same base rule, where
+  the first entry's own output covers everything below the first threshold, and the same colour
+  resolution, where a `var(--lr-…)` reference in a `colorSteps` entry is resolved against the host
+  before it reaches MapLibre (which paints to a WebGL canvas and never sees the CSS cascade), so a
+  retheme moves the cluster breaks with everything else. No fill or line layer is created for a
+  clustered entry, because MapLibre's clustering keeps point features only. The count
+  label needs glyphs: a style that declares none gets the graduated circles without the numbers
+  (adding a text layer against a glyph-less style paints nothing and only emits peer errors), and
+  `countFont` names the font stack when your style's glyph source lacks MapLibre's spec default.
+  Cluster options are baked into the source at creation time by MapLibre and have no setter, so
+  changing them (or `kind`) rebuilds that one entry's source and layers; every other update still
+  reconciles in place.
+
+  `kind?: 'auto' | 'heatmap'` (`LyraMapDataLayerKind`, default `'auto'` — today's geometry split)
+  renders the source as MapLibre's own first-class `heatmap` layer instead, which the geometry split
+  cannot express at all: thousands of overlapping circles read as one opaque blob rather than as
+  where the data is concentrated. `heatmap?: LyraMapHeatmapOptions { weightField?: string;
+weightRange?: [number, number]; stops?: [number, string][]; radius?: number; intensity?: number }`
+  configures it. `weightField` weights each point by a feature property, and `weightRange` maps that
+  property's own units onto the 0–1 weight MapLibre expects — without it the raw value is passed
+  through, which saturates the surface for any quantity above ~1; with neither, every point weighs 1.
+  `stops` are `[density, color]` pairs with density in `[0, 1]`, **the same `[value, color]`
+  vocabulary `choropleth.stops` and `legendGradient` already share**, so a `legendGradient` bar can
+  describe the ramp without a second copy of it, and `var(--lr-…)` stops resolve against the host the
+  same way `color`/`strokeColor` do. A ramp that doesn't start at density 0 gets a fully transparent
+  stop prepended, because a coloured zero tints the entire map — so **a single stop is already a
+  complete ramp**, as long as it sits above density 0: `stops: [[1, '#ff0000']]` is exactly
+  transparent → red. The one authored ramp that can't be honoured is a lone stop AT density 0, which
+  describes a flat colour rather than a gradient; that one — like an unset or wholly unusable
+  `stops` — falls back to the built-in ramp, which runs transparent → `--lr-color-brand` →
+  `--lr-color-success` → `--lr-color-warning` → `--lr-color-danger`, so a retheme moves the density
+  surface with everything else. `radius`
+  (default 30) and `intensity` (default 1) are MapLibre's own. `cluster` is ignored on a heatmap
+  entry: a heatmap already aggregates density, and clustering its input would feed it one point per
+  cluster instead of the real distribution.
 - `maxBounds: LyraMapBounds | null = null` (attribute: false) — box the map may not pan outside,
   `[[west, south], [east, north]]`. Prefer it over calling `map.setMaxBounds()` through the `.map`
   escape hatch: constraining the camera can wedge maplibre-gl at a sub-1 fractional zoom in a wide
@@ -160,7 +211,8 @@ payload beside the map.
   empty canvas name. The non-semantic `[part="base"]` wrapper is not named instead.
 
 **Authoring types:** `LyraMapLegendEntry`, `LyraMapLegendPattern`, `LyraMapLegendProjection`, `LyraMapChoroplethLayer`,
-`LyraMapGeoJsonDataLayer`, `LyraMapMarker`, `LyraMapStyleSpecification`, and `LyraMapInstance`.
+`LyraMapGeoJsonDataLayer`, `LyraMapDataLayerKind`, `LyraMapClusterOptions`, `LyraMapHeatmapOptions`,
+`LyraMapMarker`, `LyraMapStyleSpecification`, and `LyraMapInstance`.
 The former `LegendEntry`, `ChoroplethLayer`, `GeoJsonDataLayer`, and `MapMarker` names are removed
 in v9 rather than retained as aliases.
 
@@ -179,10 +231,15 @@ an element.
 (frozen `detail: { readonly lngLat: readonly [lng, lat], readonly feature?, readonly origin?,
 readonly sourceId? }`; the tuple and any hit GeoJSON feature are detached and recursively frozen).
 `feature` resolves against the choropleth fill layer **and** every applied `dataLayers`
-fill/line/circle layer, topmost first — so a shape painted through `dataLayers` is identifiable
-instead of being indistinguishable from empty space. `origin` is `'choropleth'` or `'data-layer'`,
-and `sourceId` carries the authored `dataLayers[].sourceId` for a data-layer hit; both are
-`undefined` whenever `feature` is
+fill/line/circle/cluster layer, topmost first — so a shape painted through `dataLayers` is
+identifiable instead of being indistinguishable from empty space. `origin` is `'choropleth'`,
+`'data-layer'` or `'cluster'`, and `sourceId` carries the authored `dataLayers[].sourceId` for a
+data-layer or cluster hit; both are `undefined` whenever `feature` is. A cluster hit is reported
+separately because it is a synthetic aggregate rather than one of your features: its useful payload
+is MapLibre's `point_count`/`point_count_abbreviated`/`cluster_id` properties, which is what a
+zoom-to-cluster handler reads. The count label is deliberately not hit-tested (it sits exactly on
+the circle already queried and would only make the label the topmost hit), and a `kind: 'heatmap'`
+layer is never queried at all — MapLibre returns no features for a rendered density surface
 
 **Slots:** `legend` — custom legend content, rendered inside the legend panel's own layout so it
 stays positioned with the map instead of floating beside it. Supplying it opens the panel even

package/llms/components/lr-widget.md

@@ -6,7 +6,7 @@
 - **Class** `LyraWidget`, also available unregistered from `@aceshooting/lyra-ui/components/layout/widget/widget.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Deprecations** none
+- **Deprecated property** `activeView` since `11.2.0`; use property `activeViewId`; removal not before `13.0.0` — `activeView` was this property's original public name; the string does not appear anywhere in CHANGELOG.md, so the rename to `activeViewId` was never announced at all. A shipped consumer's `.activeView=` binding became a dead expando and the widget fell back to its first view with no error. The alias seeds `activeViewId` rather than being read alongside it, because the component itself writes that property (a view-toggle click, and the fallback when `views` drops the active id), and a read-alongside alias would undo a later interactive change on the next update.
 - **Optional peers** none
 - **Themeable via** 16 parts, 9 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
@@ -49,6 +49,12 @@ TemplateResult; ariaLabel?: string }`. Each entry gets a header toggle button
 - `activeViewId: string = ''` (attribute: false) — the currently active view's `viewId`; defaults to the
   first entry of `views` (or `''` when `views` is empty). Settable directly to control the active
   view externally; also updated internally when a view toggle is clicked.
+- `activeView: string = ''` (attribute: false) — **deprecated alias for `activeViewId`**, which it
+  seeds. `activeView` was this member's original public name and the rename was never announced, so
+  a shipped `.activeView=${…}` binding silently became inert and the widget fell back to its first
+  view. It seeds rather than being read alongside, because the component itself writes
+  `activeViewId` (a toggle click, and the fallback when `views` drops the active id) — so a stale
+  alias must not undo a later interactive change. Prefer `activeViewId` in new code.
 - `accessibleLabel: string | null = null` (attribute `aria-label`) — overrides the label-derived
   fullscreen dialog name. An explicitly empty value is retained; property, slotted-label, and
   localized fallbacks apply only when it is absent.

package/llms/index.md

@@ -2,7 +2,7 @@
 
 # Component index
 
-284 custom elements, grouped by the source family they live in.
+285 custom elements, grouped by the source family they live in.
 
 **Reading one component.** Its reference file path is derived from the tag — no search needed:
 `llms/components/<tag>.md` (e.g. `llms/components/lr-table.md`). Each is self-contained: import
@@ -50,7 +50,7 @@ Optional peers: `llms/peers.md`. Safe `wa-*`/`sl-*` migration: `llms/migration.m
 - `lr-rubric-form` · lr-rubric-form.js · `stable` since `4.0.0` — a configurable annotation rubric (LangSmith annotation-queue style): score, category, and freeform-comment keys with a submit-and-next fl...
 - `lr-locale-picker` · lr-locale-picker.js · `stable` since `6.0.0` — a closed-list locale switcher over the library's own locale registry.
 
-## Data display, dashboards & flow canvas — `components/data/` (25)
+## Data display, dashboards & flow canvas — `components/data/` (26)
 
 - `lr-sparkline` · lr-sparkline.js · `stable` since `4.0.0` — a zero-dependency inline SVG trend chart.
 - `lr-stat` · lr-stat.js · `stable` since `4.0.0` — a KPI/stat card.
@@ -58,6 +58,7 @@ Optional peers: `llms/peers.md`. Safe `wa-*`/`sl-*` migration: `llms/migration.m
 - `lr-table` · lr-table.js · `stable` since `4.0.0` — a sort/select-aware data table.
 - `lr-pagination` · lr-pagination.js · `stable` since `4.0.0` — controlled, server-friendly page navigation: a numbered page list with elided gaps, optional first/last controls, an optional item-range...
 - `lr-gauge` · lr-gauge.js · `stable` since `4.0.0` — a radial, full-circle ring, or linear meter.
+- `lr-funnel` · lr-funnel.js · `experimental` since `12.0.0` — a dependency-free conversion funnel: an ordered set of stages, each drawn as a bar whose length is that stage's share of the FIRST stage,...
 - `lr-word-cloud` · lr-word-cloud.js · `stable` since `4.0.0` — a zero-dependency SVG word/tag cloud.
 - `lr-heatmap` · lr-heatmap.js · `stable` since `4.0.0` — a Canvas heatmap with a DPR-aware, resize-aware redraw loop.
 - `lr-sequence-strip` · lr-sequence-strip.js · `stable` since `4.0.0` — a compact, one-thin-cell-per-item strip visualizing a sequence of categorical states, with an optional secondary per-cell marker.

package/llms/peers.md

@@ -37,7 +37,7 @@ for the page.
 
 | Peer | Range | Needed by |
 |---|---|---|
-| `@aceshooting/lyra-flags` | `workspace:^2.0.0` | `lr-flag`, `lr-locale-picker`, `lr-phone-input` |
+| `@aceshooting/lyra-flags` | `workspace:^2.2.0` | `lr-flag`, `lr-locale-picker`, `lr-phone-input` |
 | `@aiden0z/pptx-renderer` | `^1.2.4` | `lr-pptx-viewer` |
 | `@sgratzl/chartjs-chart-boxplot` | `^4.4.5` | `lr-box-plot` |
 | `chart.js` | `^4.5.1` | `lr-bar-chart`, `lr-box-plot`, `lr-bubble-chart`, `lr-chart`, `lr-doughnut-chart`, `lr-histogram`, `lr-line-chart`, `lr-pie-chart`, `lr-polar-area-chart`, `lr-radar-chart`, `lr-scatter-chart` |
@@ -48,7 +48,7 @@ for the page.
 | `d3-force` | `^3.0.0` | `lr-graph`, `lr-knowledge-graph-explorer` |
 | `d3-selection` | `^3.0.0` | `lr-graph`, `lr-knowledge-graph-explorer` |
 | `d3-zoom` | `^3.0.0` | `lr-graph`, `lr-knowledge-graph-explorer` |
-| `dompurify` | `^3.4.13` | `lr-agent-workspace`, `lr-command-palette`, `lr-condition-builder`, `lr-dashboard-grid`, `lr-docx-viewer`, `lr-email-viewer`, `lr-eval-run`, `lr-html-viewer`, `lr-icon`, `lr-icon-button`, `lr-include`, `lr-markdown`, `lr-markdown-core`, `lr-message-parts`, `lr-notebook-viewer`, `lr-rag-answer`, `lr-streaming-text`, `lr-svg-viewer`, `lr-video`, `lr-video-playlist`, `lr-widget-renderer` |
+| `dompurify` | `^3.4.14` | `lr-agent-workspace`, `lr-command-palette`, `lr-condition-builder`, `lr-dashboard-grid`, `lr-docx-viewer`, `lr-email-viewer`, `lr-eval-run`, `lr-html-viewer`, `lr-icon`, `lr-icon-button`, `lr-include`, `lr-markdown`, `lr-markdown-core`, `lr-message-parts`, `lr-notebook-viewer`, `lr-rag-answer`, `lr-streaming-text`, `lr-svg-viewer`, `lr-video`, `lr-video-playlist`, `lr-widget-renderer` |
 | `emoji-picker-element-data` | `^1.8.0` | `lr-emoji-picker` |
 | `epubjs` | `^0.3.93` | `lr-ebook-viewer` |
 | `ical.js` | `^2.2.1` | `lr-calendar-viewer` |

package/llms/shared.md

@@ -150,6 +150,8 @@ 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/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 utilities),
   `@aceshooting/lyra-ui/theme.js` (the zero-dependency mode/accent runtime),
@@ -639,6 +641,115 @@ 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`.
+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).
+
+### 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:
+
+```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 */
+```
+
+```css
+/* Now 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);
+  border-radius: var(--lr-radius);
+  background: var(--lr-color-surface-raised);
+  color: var(--lr-color-text);
+  font-family: var(--lr-font);
+}
+.app-panel:focus-visible {
+  outline: var(--lr-focus-ring);
+  outline-offset: var(--lr-focus-ring-offset);
+}
+```
+
+**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:
+
+| Family                | Names                                                                                                                                                                                                                     |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Ambient colour        | `--lr-color-surface`, `--lr-color-surface-raised`, `--lr-color-surface-overlay`, `--lr-color-overlay`, `--lr-color-text`, `--lr-color-text-quiet`, `--lr-color-border`, `--lr-color-border-strong`                         |
+| The semantic grid     | all 45 `--lr-color-{brand,success,warning,danger,neutral}-{fill,border,on}-{quiet,normal,loud}` slots                                                                                                                       |
+| Flat colour aliases   | `--lr-color-{brand,success,warning,danger,neutral}`, `--lr-color-{brand,success,warning,danger}-quiet`, `--lr-color-on-{brand,success,warning,danger,neutral}`                                                              |
+| Spacing               | `--lr-space-2xs`, `--lr-space-xs`, `--lr-space-s`, `--lr-space-m`, `--lr-space-l`, `--lr-space-2xl`                                                                                                                        |
+| Geometry              | `--lr-radius-xs`, `--lr-radius`, `--lr-radius-pill`, `--lr-border-width-thin`, `--lr-border-width-medium`, `--lr-border-width-thick`                                                                                       |
+| Elevation             | `--lr-shadow-color`, `--lr-shadow-xs`, `--lr-shadow-s`, `--lr-shadow-m`, `--lr-shadow-l`, `--lr-shadow-xl`, `--lr-shadow`                                                                                                  |
+| 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` |
+
+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.
+
+**Deliberately not published**, and each for a reason that makes reading it a bug rather than a
+convenience: `--lr-ramp-*` (a step encodes a light-mode choice and has no theme hook),
+`--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`,
+`--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.
+
+**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 work the way the components' do.** Light on `:root` and on `.lr-light` /
+`[data-lr-theme="light"]`, dark under `prefers-color-scheme: dark` (unless an explicit light scope
+opts out) and on `.lr-dark` / `[data-lr-theme="dark"]`, plus the same `forced-colors` and
+`prefers-reduced-motion` overrides the components apply — and those two reach you on **every** one
+of those routes, including a dark OS with no explicit scope, because they repeat the compound
+`:root:not(.lr-light):not([data-lr-theme="light"])` selector the dark route uses rather than a bare
+`:root` that the dark route would out-specify. Every declaration keeps its `--lr-theme-*`
+input in front of a resolved fallback, so `theme.css` and your own overrides still win here exactly
+as they do inside a component.
+
+**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 — `class="lr-light"`, `class="lr-dark"`, or `data-lr-theme` — which is what the file's
+mode rules key on, and the whole subset resolves again there:
+
+```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>
+```
+
+Everything sits 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 colour ramp and the semantic grid
 
 Colour has two layers beneath the `--lr-*` tokens you normally read.
@@ -1185,7 +1296,10 @@ stay in light DOM: they do not pierce a component's shadow root.
 `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-utilities, lr-overrides`; an ordinary unlayered
-application rule therefore beats them regardless of load order.
+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.
 
 ### Utility class inventory
 
@@ -1666,6 +1780,16 @@ control) is a single tab stop using a roving `tabindex`; arrow keys move within
 `Escape` dismisses the topmost dismissible overlay and returns focus to whatever opened it.
 `ArrowLeft`/`ArrowRight` mean previous/next and swap under `dir="rtl"`.
 
+**`accessibleLabel` binds to one of two different attributes depending on the component, and the
+two are not interchangeable.** Most components (e.g. `lr-card`, `lr-stat`) expose it as a direct
+alias of the native `aria-label` attribute — `accessible-label="…"` does nothing on those; write
+`aria-label="…"` instead. A minority (e.g. `lr-callout`, `lr-table`) separately compute an internal
+accessible name and expose `accessibleLabel` through the bespoke `accessible-label` attribute
+instead, specifically so the host's own native `aria-label` can still independently override that
+computed name. Check the component's own reference section (or its class JSDoc) for which
+convention it uses before writing markup — an `accessible-label` attribute on an `aria-label`-only
+component is a silent no-op, not an error.
+
 **What that contract is verified by, precisely.** Every one of the 284 public tags carries at least
 one axe-core assertion in its own directory's tests, in a test that mounts its own tag; contrast
 (4.5:1 text, 3:1 control borders, in both the light and dark palettes), a 40px minimum target size,
@@ -2686,6 +2810,7 @@ These named interfaces and helper signatures are available to typed integrations
   "lr-format-bytes": unknown;
   "lr-format-date": unknown;
   "lr-format-number": unknown;
+  "lr-funnel": unknown;
   "lr-gauge": unknown;
   "lr-generation-metrics": unknown;
   "lr-geojson-view": unknown;
@@ -3071,6 +3196,7 @@ These named interfaces and helper signatures are available to typed integrations
   "lr-format-bytes": unknown;
   "lr-format-date": unknown;
   "lr-format-number": unknown;
+  "lr-funnel": unknown;
   "lr-gauge": unknown;
   "lr-generation-metrics": unknown;
   "lr-geojson-view": unknown;
@@ -3357,6 +3483,7 @@ These named interfaces and helper signatures are available to typed integrations
   "lr-format-bytes": unknown;
   "lr-format-date": unknown;
   "lr-format-number": unknown;
+  "lr-funnel": unknown;
   "lr-gauge": unknown;
   "lr-generation-metrics": unknown;
   "lr-geojson-view": unknown;
@@ -3683,6 +3810,7 @@ These named interfaces and helper signatures are available to typed integrations
   "lr-format-bytes": unknown;
   "lr-format-date": unknown;
   "lr-format-number": unknown;
+  "lr-funnel": unknown;
   "lr-gauge": unknown;
   "lr-generation-metrics": unknown;
   "lr-geojson-view": unknown;