srcdev-nuxt-components 9.6.12 → 9.6.14

package/.claude/rules/consumer/ids-from-useid.md

@@ -7,7 +7,8 @@ paths:
 
 Build `id`/`for` pairs from `useId()` (plus a loop index for repeated items), never from props or
 data values like `` `${name}-${item.value}` ``. A radio group's default `name` comes from
-`useId()` too, never a fixed string.
+`useId()` too, never a fixed string. Call `useId()` once at setup and store the result; never call
+it inside a `computed`, which can re-run it.
 
 Why: two instances sharing a `name` and values produce duplicate ids, and a value with spaces makes
 an invalid one, so labels toggle the wrong control (`MultipleCheckboxes`, 2026-10-16). A fixed default radio `name` makes every instance on a page

package/.claude/rules/consumer/story-register-components.md

@@ -6,7 +6,7 @@ paths:
 # Register every component a story template uses
 
 Every component in a story's `template` string, including ones placed in the component's slots, must
-be listed in that story's `components: {}`.
+be listed in that story's `components: {}`. Globally registered ones (`Icon`, `NuxtLink`) are the exception.
 
 Why: components aren't auto-registered in story templates; unregistered ones render as unknown tags.
 Detail: skill `storybook-add-story.md` (srcdev-nuxt-components).

package/.claude/rules/consumer/vfor-keys-from-data.md

@@ -0,0 +1,14 @@
+---
+paths:
+  - "app/**/*.vue"
+---
+
+# Key data-driven `v-for` lists on something unique
+
+Key a `v-for` over prop, CMS or API data on a field guaranteed unique. When the only candidates
+can repeat (`href`, `to`, a label), combine one with the index: `` :key="`${index}-${link.href}`" ``.
+
+Why: duplicate keys break Vue's keyed diff. Reordering a list where two items shared an `href` left
+a stale extra element in the DOM (`SkipLinks`, 2026-10-18); `ContentDocs` had the same bug with
+nav items sharing a `to`. Vue only warns while patching an update, so first render looks fine.
+Detail: skill `testing-add-unit-test.md` (srcdev-nuxt-components), "Testing duplicate `v-for` keys".

package/.claude/skills/component-compliance-checklist.md

@@ -138,6 +138,11 @@ The ledger can't see items 6c, 9, 10, 11 and 14, so check those by hand.
       `computed()`: Vue renders nothing for a fractional or negative range and only warns in dev
       (`StepperList`, 2026-10-15)
     - broken image or link URLs
+    - data a third-party child can't handle: a library that throws while rendering (an encoder, a
+      parser) breaks the whole page render. Catch it with `onErrorCaptured` and render a fallback
+      (`DisplayQrCode` threw "Data too long" on an over-capacity value until 2026-10-19). Check story
+      control ranges against the library's real range too: its `radius` control ran to 20 while the
+      library clamps to 0-1
     Describe what to check in the story's docs description, and look at it at every
     `CanvasSwitcher` width. Fixes usually mean `overflow-wrap: anywhere`, `min-inline-size: 0` on
     flex/grid children, `Array.from(str)` instead of `str[0]`, and `clamp()` on values
@@ -197,6 +202,9 @@ The ledger can't see items 6c, 9, 10, 11 and 14, so check those by hand.
    - A toast, banner or status message doesn't `.focus()` itself when it appears (rule
      `consumer/a11y-no-focus-steal.md`).
    - Focus is visible (`:focus-visible`, not a suppressed outline) on anything focusable.
+   - An element hidden visually but kept in the DOM (zero width, `opacity: 0`, kept as an anchor)
+     also leaves the tab order and the accessibility tree (`tabindex="-1"`, `aria-hidden`), or it's
+     an invisible tab stop (`DisplayTooltip`'s `hideTrigger`, fixed 2026-10-18).
    - `aria-invalid` is bound as `fieldHasError ? 'true' : undefined`, never the boolean itself:
      `:aria-invalid="fieldHasError"` renders `aria-invalid="false"` on every valid field
      (`InputTextarea`, `ToggleSwitch`, fixed 2026-10-16). Same for an empty `aria-describedby`.
@@ -264,7 +272,20 @@ The ledger can't see items 6c, 9, 10, 11 and 14, so check those by hand.
     - A `position: fixed`/`sticky` overlay exposes a public z-index token defaulting to `999999`
       (pitfall #17).
     - No utility class from `06.utility-classes` in the component's own markup unless it's used
-      for what that class actually means (pitfall #18, `mi-12`).
+      for what that class actually means (pitfall #18, `mi-12`). And no class the layer doesn't
+      define at all: `DisplayTooltipRich` carried `subtitle-sm`, `body-sm` and `input-value`, which
+      did nothing here but would pick up a consumer's own CSS (removed 2026-10-18). Grep
+      `app/assets/styles` for each non-prefixed class.
+    - A class this component styles that another component also styles (a class passed to a child,
+      or a child's class the parent restyles): compare the two selectors' specificity. An `all: unset`
+      in the higher one silently resets every layout property the other sets: `DisplayTooltip`'s
+      close-button reset stretched `DisplayTooltipRich`'s right-aligned button full width for six
+      weeks (fixed 2026-10-18).
+    - A `v-for` over consumer or CMS data is keyed on something guaranteed unique; a data field
+      that can repeat (`href`, `to`, a label) is combined with the index (rule
+      `consumer/vfor-keys-from-data.md`).
+    - Every raw `<button>` has an explicit `type` (ESLint `vue/html-button-has-type`, on since
+      2026-10-18), or it submits any form a consumer renders it inside.
     - Nothing load-bearing relies on a CSS feature WebKit lacks (pitfall #19).
     - No `computed()` over `useSlots()`; use a function called from the template (pitfall #25).
     - Values derived from props are `computed()`, not plain consts frozen at mount.
@@ -286,6 +307,8 @@ The ledger can't see items 6c, 9, 10, 11 and 14, so check those by hand.
       defaults to its min-content width and overflows a narrow column (`MultipleCheckboxes`,
       2026-10-16).
     - Element ids come from `useId()`, never from data values (rule `consumer/ids-from-useid.md`).
+      Call `useId()` once at setup, never inside a `computed` (`DisplayTooltip`, `DisplayTooltipRich`,
+      2026-10-18).
     - A wrapper passes its child only props the child declares. Anything else falls through as an
       HTML attribute on the child's root: `InputTextField` put `label="…"` and
       `error-message="…"` on `.input-text-wrapper` (fixed 2026-10-16). Check the child root's

package/.claude/skills/component-naming.md

@@ -105,6 +105,7 @@ external consumer, free to rename. Run `/check-component-usage` for the current
 | ~~InputCheckboxRadioWithLabel~~ | ✅ `InputCheckboxRadioField` (2026-09-27) | - |
 | ~~ActionMenuItemCore~~ | ✅ `ActionMenuItem` (2026-09-27) | - |
 | ~~AlertMaskCore~~ | ✅ `AlertMask` (2026-10-17) | - |
+| ~~DisplayTooltipDefined~~ | ✅ `DisplayTooltipRich` (2026-10-18): Material 3 "rich tooltip", the implementation word "Defined" said nothing about what it is | - |
 | CardCore | **decide**: `Card` is single-word and collision-prone; prefer a prefixed name (`Display*`, `Content*`) | yes |
 | AccordianCore | **decide**: also fixes the "Accordian" misspelling; bare `Accordion` is single-word and collision-prone, and it is built on `<details>`/`<summary>` | yes |
 | ~~TabsCore~~ | ✅ `TabbedContent` (2026-10-07) | - |

package/.claude/skills/components/banner-video.md

@@ -1,6 +1,6 @@
 ---
 name: BannerVideo
-description: BannerVideo full-width hero video banner — props, depth tier system, verticalPosition/horizontalPosition, playIcon/pauseIcon/toggle-icon slot, reduced-motion fallback, CSS tokens, consumer styling
+description: BannerVideo full-width hero video banner — props, depth tier system, verticalPosition/horizontalPosition, playIcon/pauseIcon/toggle-icon slot, playLabel/pauseLabel, reduced-motion fallback, CSS tokens, consumer styling
 type: reference
 ---
 
@@ -25,21 +25,23 @@ The video uses `autoplay muted loop playsinline preload="auto"` attributes on th
 | `alt` | `string` | `""` | Alt text for the fallback `NuxtImg`. |
 | `imgWidth` | `number` | `1920` | Intrinsic width of the poster image — required for NuxtImg/IPX optimisation. |
 | `imgHeight` | `number` | `1080` | Intrinsic height of the poster image — required for NuxtImg/IPX optimisation. |
-| `tag` | `"section" \| "div" \| "header" \| "main" \| "article"` | `"section"` | HTML element rendered as the root. |
+| `tag` | `"section" \| "div" \| "header" \| "main" \| "article"` | `"div"` | HTML element rendered as the root. Pass `aria-label` as a plain attribute (it falls through to the root) when the tag is a landmark that needs a name. |
 | `depth` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Responsive max-height tier. Each maps to a `clamp()` scale; override via `--banner-video-max-height-{depth}`. |
-| `aspectRatio` | `string` | `"21/9"` | CSS `aspect-ratio` of the container (e.g. `"16/9"`, `"21/9"`, `"4/3"`). |
+| `aspectRatio` | `string` | `"21/9"` | CSS `aspect-ratio` of the container (e.g. `"16/9"`, `"21/9"`, `"4/3"`, `"1.5"`). Anything that isn't a positive number or `w/h` ratio falls back to `"21/9"`. |
 | `objectFit` | `"cover" \| "contain" \| "fill" \| "none" \| "scale-down"` | `"cover"` | How the video and fallback image fill the banner frame. |
 | `verticalPosition` | `"start" \| "center" \| "end"` | `"center"` | Vertical crop position. Maps to `align-self` on the video element and `object-position` Y on the fallback image. |
 | `horizontalPosition` | `"start" \| "center" \| "end"` | `"center"` | Horizontal crop position. Maps to `object-position` X on the fallback image. |
 | `playIcon` | `string` | `"mdi:play"` | Iconify icon name shown on the toggle button before playback starts. |
 | `pauseIcon` | `string` | `"mdi:pause"` | Iconify icon name shown on the toggle button once playback starts. |
+| `playLabel` | `string` | `"Play background video"` | Toggle button label while paused (visually hidden; the button's accessible name). Override for localisation. |
+| `pauseLabel` | `string` | `"Pause background video"` | Toggle button label while playing. Override for localisation. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
 
 ## Slots
 
 | Slot | Slot props | Purpose |
 |---|---|---|
-| `toggle-icon` | `{ isPlaying: boolean }` | Replaces the toggle button's icon entirely. Default renders `<Icon :name="isPlaying ? pauseIcon : playIcon" />` — use this slot instead of `playIcon`/`pauseIcon` when an Iconify name isn't enough (custom SVG, different icon set). |
+| `toggle-icon` | `{ isPlaying: boolean }` | Replaces the toggle button's icon entirely. Default renders `<Icon :name="isPlaying ? pauseIcon : playIcon" />` — use this slot instead of `playIcon`/`pauseIcon` when an Iconify name isn't enough (custom SVG, different icon set). Content is clipped to the round button, so size it to `--banner-video-toggle-size`. The accessible name still comes from `playLabel`/`pauseLabel`. |
 
 ## Basic usage
 
@@ -180,18 +182,22 @@ Inline style tokens (set from props):
 | `--banner-video-toggle-background` | `oklch(0% 0 0 / 0.4)` | Button background |
 | `--banner-video-toggle-background-hover` | `oklch(0% 0 0 / 0.6)` | Button background on hover/focus |
 | `--banner-video-toggle-icon-color` | `white` | Icon colour |
+| `--banner-video-toggle-focus-outline-width` | `2px` | Focus ring width |
+| `--banner-video-toggle-focus-outline-color` | `currentColor` | Focus ring colour (the icon colour by default) |
+| `--banner-video-toggle-focus-outline-offset` | `2px` | Focus ring offset |
 
 Full details, plus global/page-scoped/per-instance override patterns, live in the
 component's own `CONSUMER-STYLING.md`.
 
 ## Pause/play toggle
 
-A `<button class="banner-video__toggle">` is always rendered in the bottom-right corner of the
-banner, overlaying the video. It calls `videoEl.pause()` / `.play()` directly and its
-`aria-label` reflects actual playback state ("Pause background video" / "Play background video"),
-tracked via the video's native `play`/`pause` events rather than assumed — autoplay can be
-blocked by the browser, so the label starts as "Play background video" until a `play` event
-actually fires.
+An icon-only `InputButton variant="inline"` (class `.banner-video-toggle`) is always rendered in the
+bottom-right corner of the banner, overlaying the video. It calls `videoEl.pause()` / `.play()`
+directly. Its accessible name is visually hidden text (`.input-button-text.sr-only`, not an
+`aria-label`) that reflects actual playback state: `pauseLabel` while playing, `playLabel`
+otherwise (defaults "Pause background video" / "Play background video"). State is tracked via the
+video's native `play`/`pause` events rather than assumed: autoplay can be blocked by the browser,
+so the label starts as `playLabel` until a `play` event actually fires.
 
 This exists to satisfy **WCAG 2.2.2 (Pause, Stop, Hide)**: content that autoplays and lasts more
 than 5 seconds needs an on-page mechanism to pause it. The `prefers-reduced-motion` fallback only
@@ -211,9 +217,11 @@ component, since `BannerVideo` has no slot for it.
 | Class | Applied when |
 |---|---|
 | `.banner-video` | Always — the root element |
-| `.video` | The `<video>` element |
-| `.fallback` | The `<NuxtImg>` fallback — hidden by default, shown via `prefers-reduced-motion` CSS |
-| `.banner-video__toggle` | The pause/play button — always rendered except under `prefers-reduced-motion: reduce` |
+| `.banner-video-media` | The `<video>` element |
+| `.banner-video-fallback` | The `<NuxtImg>` fallback — hidden by default, shown via `prefers-reduced-motion` CSS |
+| `.banner-video-toggle` | The pause/play `InputButton` (also `.input-button`) — always rendered, hidden under `prefers-reduced-motion: reduce` |
+
+Renamed 2026-10-18 from `.video`, `.fallback` and `.banner-video__toggle` (generic names collided with consumer CSS).
 
 ## Consumer styling
 
@@ -239,37 +247,23 @@ per-instance override patterns.
 
 `max-height` from the depth tier silently wins over `aspect-ratio` once the viewport is wide enough. For example, at `depth="md"` the max-height clamp caps at `56rem` — so changing `aspectRatio` from `"21/9"` to `"1/1"` produces no visible change on a wide desktop because `max-height` is the binding constraint.
 
-**If you need `aspect-ratio` to dominate**, override all depth tokens to a large fixed value on the parent:
+**If you need `aspect-ratio` to dominate**, raise the active tier's token on the parent. Only that one is read: `depth` is always set, so the root always matches one `[data-depth]` rule.
 
 ```css
 .my-page {
-  --banner-video-max-height-xs: 80rem;
-  --banner-video-max-height-sm: 80rem;
-  --banner-video-max-height-md: 80rem;
   --banner-video-max-height-lg: 80rem;
-  --banner-video-max-height-xl: 80rem;
 }
 ```
 
-Or via inline `:style` on the parent element (useful for dev QA exploration):
-
 ```vue
-<div :style="{
-  '--banner-video-max-height-xs': '80rem',
-  '--banner-video-max-height-sm': '80rem',
-  '--banner-video-max-height-md': '80rem',
-  '--banner-video-max-height-lg': '80rem',
-  '--banner-video-max-height-xl': '80rem',
-}">
+<div class="my-page">
   <BannerVideo aspect-ratio="1/1" depth="lg" ... />
 </div>
 ```
 
-You must override **all five tier tokens** — overriding only the active depth token is not sufficient because the component resolves the token by name.
-
 ## Notes
 
 - `loading="eager"` and `decoding="async"` are hardcoded on the fallback `NuxtImg` — it is above the fold by definition.
 - The video has `autoplay muted loop playsinline preload="auto"` — intentional and not configurable. This component is for ambient background video only, not a media player — the pause/play toggle exists purely for WCAG 2.2.2 compliance, not as a general playback UI (no seek bar, volume, etc.).
-- `prefers-reduced-motion` is handled in CSS (`.video { display: none }` + `.fallback { display: block }`), not via JS.
+- `prefers-reduced-motion` is handled in CSS (`.banner-video-media` and the toggle hidden, `.banner-video-fallback` shown), not via JS. The script still loads and plays the hidden video.
 - Storybook: the `"none"` image provider is active, so `poster` paths pass through unchanged. Always provide explicit `img-width` and `img-height` to avoid the `w=1536` fallback in deployed Storybook.

package/.claude/skills/components/content-docs.md

@@ -4,7 +4,7 @@
 
 `ContentDocs` is a docs-page layout shell: a primary nav column, a main content column, and an "on this page" nav column, arranged via CSS `@container` queries (not viewport breakpoints) so the layout adapts to the space actually available — correct even when a consumer page has its own decoration (e.g. a site-wide left nav) eating into the viewport.
 
-`docsNav` and `docsPageNav` are **not** slots — they're rendered internally as `ExpandingPanel` accordions driven by `docsNavItems`/`docsPageNavItems` props. Only `docsContent` remains a slot, since it's arbitrary page content. The two side panels auto force-open/collapse based on the component's own measured width via `useContainerBreakpoints`, and share a native `<details name>` accordion group only on mobile (see "Breakpoint behaviour" below).
+`docsNav` and `docsPageNav` are **not** slots — they're rendered internally as collapsible panels (`ExpandingPanelClassic` by default, `ExpandingPanel` with `panel-variant="modern"`) driven by `docsNavItems`/`docsPageNavItems` props. Only `docsContent` remains a slot, since it's arbitrary page content. The two side panels auto force-open/collapse based on the component's own measured width via `useContainerBreakpoints`, and share a native `<details name>` accordion group only on mobile (see "Breakpoint behaviour" below).
 
 ---
 
@@ -13,7 +13,7 @@
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `tag` | `"div" \| "section" \| "article" \| "main"` | `"div"` | Root element tag. |
-| `docsNavItems` | `DocsNavItem[]` | `[]` | Items rendered in the `docsNav` panel. Panel (and its `.docs-nav` wrapper) is omitted entirely when empty. |
+| `docsNavItems` | `DocsNavItem[]` | `[]` | Items rendered in the `docsNav` panel. Panel (and its `.content-docs-nav` wrapper) is omitted entirely when empty. Items may share a `to` (keys include the index); every item matching the active `to` is marked active. |
 | `docsPageNavItems` | `DocsNavItem[]` | `[]` | Items rendered in the `docsPageNav` panel. Panel omitted entirely when empty. |
 | `docsNavLabel` | `string` | `"Navigation"` | Heading text for the `docsNav` panel's `#summary`. |
 | `docsPageNavLabel` | `string` | `"On this page"` | Heading text for the `docsPageNav` panel's `#summary`. |
@@ -113,7 +113,7 @@ In the template, `docsContent` is placed **before** `docsNav`/`docsPageNav` —
 
 ### Why the two panels share a `name` only on mobile
 
-Both panels are `ExpandingPanel`s using the native `<details name="...">` grouping feature, which makes same-named panels mutually exclusive (browser force-closes one when the other opens). That's the wanted behaviour on mobile (accordion — only one open at a time), but at tablet/desktop both panels must be open **simultaneously** — a shared name there would make the browser silently force-close one of them the moment both try to be open. So the component computes distinct names (`"docsNav"` / `"docsPageNav"`) once past mobile, and a shared name (`"docsPanelGroup"`) only while mobile.
+Both panels are `ExpandingPanel`s using the native `<details name="...">` grouping feature, which makes same-named panels mutually exclusive (browser force-closes one when the other opens). That's the wanted behaviour on mobile (accordion — only one open at a time), but at tablet/desktop both panels must be open **simultaneously** — a shared name there would make the browser silently force-close one of them the moment both try to be open. So the component computes distinct names (`useId()` plus `-docsNav` / `-docsPageNav`) once past mobile, and the shared bare `useId()` value only while mobile. Ids come from `useId()`, so two `ContentDocs` on one page never share a group.
 
 ### Related fix in ExpandingPanel.vue
 
@@ -125,7 +125,19 @@ Building this component's forced-open/forced-closed cycling surfaced a real bug
 
 `DocsNavItem.icon` is optional (any icon name resolvable by `<Icon>`, e.g. Lucide set: `"lucide:rocket"`). Items without an icon still align correctly with icon-bearing items — the link is `display: grid` with a fixed-width icon column (`--content-docs-link-icon-size`), not `flex`, so an absent icon doesn't collapse the label leftward.
 
-To move the icon to the end of the link instead of the start, set `--content-docs-nav-link-icon-order` (or `--content-docs-page-nav-link-icon-order`) to `rtl` (default `ltr`). This uses a `direction` flip to mirror which physical side the fixed-width column renders on, rather than swapping `grid-column` values directly — swapping columns would put the label into the icon-sized track and squeeze it. The icon and label content reset `direction: ltr` internally so text/glyphs don't visually mirror.
+To move the icon to the end of the link instead of the start, set `--content-docs-nav-link-icon-order` (or `--content-docs-page-nav-link-icon-order`) to `rtl` (default `ltr`). This uses a `direction` flip to mirror which physical side the fixed-width column renders on, rather than swapping `grid-column` values directly — swapping columns would put the label into the icon-sized track and squeeze it. The icon resets `direction: ltr` so its glyph doesn't mirror. The label uses `unicode-bidi: plaintext` with `text-align: start` instead, so it takes its direction from its own text: a right-to-left label still reads and aligns right-to-left. (Until 2026-10-18 the label forced `direction: ltr`, which broke right-to-left labels.)
+
+---
+
+## Classes and state hooks
+
+Root `.content-docs`; grid `.content-docs-inner`; grid areas `.content-docs-nav`, `.content-docs-content`, `.content-docs-page-nav` (each `min-inline-size: 0`, tracks `minmax(0, 1fr)`, content area `overflow-wrap: break-word`); headings `.content-docs-nav-heading` / `.content-docs-page-nav-heading`; `<nav>`s `.content-docs-nav-list` / `.content-docs-page-nav-list` (their `<ul role="list">`); links `.content-docs-nav-link` / `.content-docs-page-nav-link` with `-icon` and `-label` children. The active link is selected by `[aria-current="page"]`; there is no `.is-active` class.
+
+Renamed 2026-10-18 from the unprefixed `.docs-*` names (`.docs-nav`, `.docs-content`, `.docs-page-nav`, `.docs-nav-link`, ...), which collided with consumer CSS. Full map in `CONSUMER-STYLING.md`.
+
+## Worst-case data
+
+Labels and headings wrap anywhere, so an unbroken label stays in its column. An empty `label` renders a thin link with no accessible name: filter those out of the data. Link labels have no line-clamp token: they name their destinations. See the `StressTest` story.
 
 ---
 
@@ -140,7 +152,8 @@ All `--content-docs-*` tokens can be overridden at global, page, or instance sco
 - `-bg` (default: `var(--page-bg)`), `-padding-block`, `-padding-inline`, `-border-radius`
 
 **Link tokens** (shared: `--content-docs-link-*`, per-side: `--content-docs-{nav,page-nav}-link-*`):
-- `-font-size`, `-padding-block`, `-padding-inline`, `-margin-block`, `-border-radius`, `-color`, `-bg`, `-hover-bg`, `-hover-color`, `-active-bg`, `-active-color`
+- `-font-size`, `-padding-block`, `-padding-inline`, `-margin-block`, `-border-radius`, `-color`, `-bg`, `-hover-bg`, `-hover-color`, `-active-bg`, `-active-color` (active defaults to `var(--theme-surface)` / `var(--theme-on-surface)`; it was a fixed green pair before 2026-10-18)
+- Shared only: `--content-docs-link-focus-outline-width` (`0.2rem`), `--content-docs-link-focus-outline-color` (`var(--theme-border-focus)`)
 
 **Column-width tokens** (fixed-width grid tracks at tablet/desktop):
 - `--content-docs-nav-column-width` (default `23rem`, desktop `docsNav` track)

package/.claude/skills/components/display-dialog.md

@@ -14,14 +14,14 @@ open/close state management.
 |---|---|---|---|
 | `dataDialogId` | `string` | — | **Required.** Unique identifier rendered as `data-dialog-id` attribute. |
 | `variant` | `'dialog' \| 'modal' \| 'confirm' \| 'alert' \| 'fullscreen'` | `'dialog'` | Controls panel sizing and ARIA role. |
-| `theme` | `SemanticTheme` | `undefined` | Optional header accent — `data-theme` on `.display-dialog-header` only; adds a coloured bottom border and tints the close icon. |
+| `theme` | `SemanticTheme` | `undefined` | Optional header accent: `data-theme` on `.display-dialog-header` only; adds a coloured bottom border and tints the close icon (`--display-dialog-header-accent-color`). |
 | `v-model` | `boolean` | — | Controls open/closed state. |
 | `allowContentScroll` | `boolean` | `false` | Enables independent scroll on `.display-dialog-content`. |
-| `lockViewport` | `boolean` | `true` | Adds/removes `lock` class on `<body>` on mount/close. |
+| `lockViewport` | `boolean` | `true` | Locks body scroll (`useBodyLock`) on mount and releases it on unmount, not on close: render the dialog with `v-if`. |
 | `justifyDialog` | `'start' \| 'center' \| 'end'` | `'center'` | Horizontal position of panel within overlay. |
 | `alignDialog` | `'start' \| 'center' \| 'end'` | `'center'` | Vertical position of panel within overlay. |
 | `closeIcon` | `string` | app.config | Icon name for the header close button. Override per-instance or set globally via `app.config`. |
-| `closeLabel` | `string` | app.config (`"Close"`) | Screen-reader text on the icon-only close button. Pass a translated string, or set it site-wide via `app.config`. |
+| `closeLabel` | `string` | app.config (`"Close"`) | Visually hidden text on the icon-only close button (an `InputButton`). Pass a translated string, or set it site-wide via `app.config`. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root `<dialog>` element. |
 
 ## Slots
@@ -35,16 +35,26 @@ open/close state management.
 
 `.display-dialog-footer` is omitted entirely when neither action button slot is provided.
 
+## Accessible name
+
+The `#dialogTitle` slot names the dialog (`aria-labelledby` points at it). A dialog without a
+title has no name, so pass `aria-label="..."`: it isn't a prop, it falls through to the root
+`<dialog>`.
+
 ## Variants
 
 | Variant | Panel size | ARIA role | Dismiss on Escape/outside-click |
 |---|---|---|---|
 | `dialog` | `70dvh × min(75%, 72rem)` | `dialog` | Yes |
-| `modal` | Content-sized | `dialog` | Yes |
-| `confirm` | Content-sized | `dialog` | Yes |
+| `modal` | Content-sized, capped at the viewport | `dialog` | Yes |
+| `confirm` | `min(90%, 48rem)` wide, content height | `dialog` | Yes |
 | `alert` | `min(90%, 48rem)` | `alertdialog` | **No** — requires explicit action |
 | `fullscreen` | `100% × 100%` | `dialog` | Yes |
 
+Every variant is capped at the overlay's size. Long titles and content wrap, footer buttons wrap onto
+further rows, and content taller than the panel is clipped (or scrolls with `allowContentScroll`)
+while the header and footer stay visible.
+
 ## Basic usage
 
 ```vue
@@ -137,7 +147,7 @@ CSS over per-instance overrides — dialogs are site-wide UI:
 
 ```css
 /* assets/styles/setup/07.components/display-dialog.css */
-:root {
+:where(html) {
   --display-dialog-inner-border-radius: 1.2rem;
   --display-dialog-inner-background: var(--brand-surface);
   --display-dialog-inner-border: 0.1rem solid var(--brand-border);

package/.claude/skills/components/display-qr-code.md

@@ -10,10 +10,10 @@ Renders a styled QR code SVG from a string value. Supports colour, size, corner
 |------|------|---------|-------------|
 | `qr-value` | `string` | required | The string to encode into the QR code |
 | `variant` | `QrCodeVariant` | `{ inner: "default", marker: "default", pixel: "default" }` | Shape variants for inner markers, outer markers, and pixels |
-| `radius` | `number` | `0` | Corner rounding applied to pixels/markers (0–1 scale) |
+| `radius` | `number` | `0` | Corner rounding for the rounded, circle and dots shapes, 0 to 1 (the library clamps values outside) |
 | `black-color` | `string` | `"currentColor"` | Colour for the dark modules |
 | `white-color` | `string` | `"transparent"` | Colour for the light modules |
-| `size` | `string` | `"256px"` | Width of the QR code (height matches via `aspect-ratio: 1 / 1`) |
+| `size` | `string` | `"256px"` | Width of the QR code (height matches via `aspect-ratio: 1 / 1`), never wider than its container |
 | `aria-label` | `string` | `"QR code"` | Accessible name for the QR image (root has `role="img"`). Pass something specific and translated, e.g. "Scan to book an appointment". |
 | `style-class-passthrough` | `string \| string[]` | `[]` | Extra classes on the root element |
 
@@ -22,7 +22,7 @@ Renders a styled QR code SVG from a string value. Supports colour, size, corner
 ```typescript
 import type { QrCodeVariant } from "srcdev-nuxt-components/types/components";
 
-// Each field accepts: "default" | "circle" | "rounded" | "dots" | "classy" | "classy-rounded"
+// Each field accepts: "default" | "circle" | "rounded" | "dots" | "pixelated"
 const variant: QrCodeVariant = {
   inner: "circle",
   marker: "rounded",
@@ -30,6 +30,21 @@ const variant: QrCodeVariant = {
 };
 ```
 
+## Slots and events
+
+| Name | Kind | Description |
+|------|------|-------------|
+| `fallback` | slot | Rendered in place of the code when `qr-value` is too long to encode (about 2.9KB at the lowest error correction, less at higher). Empty by default, leaving a blank box of the same size. |
+| `error` | event | `(error: Error)`, emitted once when encoding fails. Resets when `qr-value` changes. |
+
+```vue
+<DisplayQrCode :qr-value="bookingUrl" @error="reportQrError">
+  <template #fallback>
+    <a :href="bookingUrl">Open the booking page</a>
+  </template>
+</DisplayQrCode>
+```
+
 ## CSS token
 
 `--display-qr-code-size` overrides the `size` prop when set (e.g. on a page wrapper). Full reference: `app/components/01.atoms/qr-code/CONSUMER-STYLING.md`.
@@ -39,6 +54,7 @@ const variant: QrCodeVariant = {
 | Class | Where | Description |
 |-------|-------|-------------|
 | `.display-qr-code` | root | always present |
+| `.display-qr-code-fallback` | root | only when the value can't be encoded (with `data-error`) |
 
 ## Usage
 
@@ -63,7 +79,9 @@ Custom size, colour, and rounded pixels:
 
 ## Notes
 
-- The component renders directly as the `Qrcode` element from `nuxt-qrcode` — there is no wrapper `<div>`. The `.display-qr-code` class is applied to the `Qrcode` root, which renders as an `<svg>`.
+- The component renders directly as the `Qrcode` element from `nuxt-qrcode` — there is no wrapper `<div>`. The `.display-qr-code` class is applied to the `Qrcode` root, which renders as an `<svg>`. When encoding fails it renders a `<span class="display-qr-code display-qr-code-fallback">` instead.
+- Encoding errors are caught with `onErrorCaptured`, so an over-capacity value from a CMS can't break the page render. `nuxt-qrcode` must be installed in the consuming app.
 - `size` is applied via CSS `v-bind()` — pass any valid CSS length value (`px`, `rem`, `%`, etc.).
 - `black-color` defaults to `currentColor`, so the QR code inherits the surrounding text colour automatically unless overridden.
 - `white-color` defaults to `transparent`, making the background of the QR code see-through by default.
+- 2026-10-19 migration: added the `fallback` slot and `error` event, capped the width at the container, corrected the variant list (`pixelated`, no `classy`) and added a `StressTest` story; the story's radius control now uses the real 0 to 1 range.

package/.claude/skills/components/{display-tooltip-defined.md → display-tooltip-rich.md}

@@ -1,30 +1,37 @@
 ---
-name: DisplayTooltipDefined
-description: DisplayTooltipDefined structured title/body/action tooltip content with close button, composes DisplayTooltip
+name: DisplayTooltipRich
+description: DisplayTooltipRich (Material 3 "rich tooltip", renamed from DisplayTooltipDefined) structured title/body/action tooltip content with close button, composes DisplayTooltip
 type: reference
 ---
 
-# DisplayTooltipDefined
+# DisplayTooltipRich
 
 ## Overview
 
-`DisplayTooltipDefined` composes [`DisplayTooltip`](display-tooltip.md), supplying a structured
+`DisplayTooltipRich` composes [`DisplayTooltip`](display-tooltip.md), supplying a structured
 title/body/action content shape (each rendered with a consumer-chosen tag) plus a built-in close
 button wired to the popover's `popovertarget` and to `DisplayTooltip`'s scoped `close()`, so it also
 closes the tooltip on Safari 16 (no Popover API). Use this when you want the standard tooltip content
 layout without hand-building the `tooltipContent` slot markup each time; use plain `DisplayTooltip`
 directly when you need full control over the popover's content.
 
+The name follows Material 3's **rich tooltip** (subhead, supporting text, optional action, as
+opposed to a plain one-line tooltip). Renamed from `DisplayTooltipDefined` on 2026-10-18: every
+`display-tooltip-defined` class and `--display-tooltip-defined-*` token became `display-tooltip-rich`,
+with the same suffixes and defaults. Older notes below use the new component name but keep the
+class names of their date (`.popover-content-defined` is today's `.display-tooltip-rich-content`).
+
 ## Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `tooltipId` | `string` | `""` | Base id for the popover. Prefixed with `nuxt-tooltip-` when provided; auto-generated via `useId()` (also prefixed) when omitted. |
-| `contentText` | `TooltipContentText` | `{}` | Title/body/action content. Each field is optional — omitted fields render nothing. |
+| `tooltipId` | `string` | `""` | Base id for the popover. Prefixed with `nuxt-tooltip-` when provided; when empty, an id generated once at setup via `useId()` (also prefixed) is used. Reactive. |
+| `contentText` | `TooltipContentText` | `{}` | Title/body/action content. Each field is optional: omitted fields render nothing. An empty `tag` falls back to `p` (title, body) or `span` (action). Text renders as text, never HTML. |
 | `triggerAriaLabel` | `string` | `"Toggle the popover"` | Forwarded to the underlying `DisplayTooltip`'s `triggerAriaLabel` — override for localisation. |
+| `triggerIcon` | `string` | `undefined` | Forwarded to `DisplayTooltip`'s `triggerIcon` (its default question-mark icon when unset). |
 | `closeButtonText` | `string` | `"Close"` | Visible text on the close button — override for localisation. |
-| `closeButtonAriaLabel` | `string` | `"Close tool tip"` | aria-label on the close button — override for localisation. |
-| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the underlying `DisplayTooltip` root element. |
+| `closeButtonAriaLabel` | `string` | `"Close tool tip"` | aria-label on the close button: override for localisation, and keep the visible `closeButtonText` inside it (WCAG 2.5.3, label in name). |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes on the underlying `DisplayTooltip` root, which always also carries `display-tooltip-rich`. |
 
 `TooltipContentText` is exported from `~/types/components`:
 
@@ -61,57 +68,40 @@ const contentText: TooltipContentText = {
 </script>
 
 <template>
-  <DisplayTooltipDefined :content-text="contentText" />
+  <DisplayTooltipRich :content-text="contentText" />
 </template>
 ```
 
+## Close button
+
+An `InputButton` (`variant="inline"`, `type="button"`) with the `.display-tooltip-close-button`
+class. It carries `popovertarget` and `popovertargetaction="hide"` (which `useTooltipsGuide` looks
+for) and calls `DisplayTooltip`'s scoped `close()`, so it also works without the Popover API.
+
 ## CSS custom properties
 
-| Property | Default | Controls |
-|----------|---------|----------|
-| `--display-tooltip-defined-content-gap` | `1.2rem` | Gap between title/body/action/close-button |
-| `--display-tooltip-defined-title-colour` | `inherit` | `tooltipTitle` text colour |
-| `--display-tooltip-defined-title-margin-block` | `0 0` | `tooltipTitle` block margin |
-| `--display-tooltip-defined-title-font-size` | `1.6rem` | `tooltipTitle` font size |
-| `--display-tooltip-defined-title-font-weight` | `700` | `tooltipTitle` font weight |
-| `--display-tooltip-defined-title-line-height` | `120%` | `tooltipTitle` line height |
-| `--display-tooltip-defined-title-letter-spacing` | `normal` | `tooltipTitle` letter spacing |
-| `--display-tooltip-defined-body-colour` | `inherit` | `tooltipContent` text colour |
-| `--display-tooltip-defined-body-margin-block` | `0 0` | `tooltipContent` block margin |
-| `--display-tooltip-defined-body-font-size` | `1.3rem` | `tooltipContent` font size |
-| `--display-tooltip-defined-body-font-weight` | `inherit` | `tooltipContent` font weight |
-| `--display-tooltip-defined-body-line-height` | `140%` | `tooltipContent` line height |
-| `--display-tooltip-defined-body-letter-spacing` | `normal` | `tooltipContent` letter spacing |
-| `--display-tooltip-defined-action-colour` | `inherit` | `tooltipAction` text colour |
-| `--display-tooltip-defined-action-margin-block` | `0 0` | `tooltipAction` block margin |
-| `--display-tooltip-defined-action-font-size` | `1.4rem` | `tooltipAction` font size |
-| `--display-tooltip-defined-action-font-weight` | `700` | `tooltipAction` font weight |
-| `--display-tooltip-defined-action-line-height` | `130%` | `tooltipAction` line height |
-| `--display-tooltip-defined-action-letter-spacing` | `normal` | `tooltipAction` letter spacing |
-| `--display-tooltip-defined-close-button-margin-block` | `1.2rem 0` | Space above the close button |
-
-Also renders every `--display-tooltip-*` token from the underlying `DisplayTooltip` — see its
-CONSUMER-STYLING.md for the full list.
+See `CONSUMER-STYLING.md` for the full `--display-tooltip-rich-*` list: per-field colour,
+margin, font size and weight, line height, letter spacing and a `*-line-clamp` token (default
+`none`) for the title, body and action, plus the content gap and the close button's top margin.
+Every `--display-tooltip-*` token from the underlying `DisplayTooltip` applies too.
 
 ## Pairing with useTooltipsGuide
 
 For a sequential, auto-advancing "guide" walkthrough (the pattern used in some guide intros — show
 step 1, wait for dismissal, show step 2, ...), pair this component with
 [`useTooltipsGuide`](../composable-tooltips-guide.md): put a ref on the container wrapping your
-`DisplayTooltipDefined`/`DisplayTooltip` instances and pass it to the composable. The composable
+`DisplayTooltipRich`/`DisplayTooltip` instances and pass it to the composable. The composable
 only needs native `[popover]`/`popovertarget` markup, which both components already emit, so no
 extra wiring is required beyond the container ref. See the `GuidedTour` story in
-`DisplayTooltipDefined.stories.ts` for a full working example (it recreates the old
-`app/pages/ui/tooltips.vue` demo page, removed 2026-08-23 when Storybook became the only demo
-surface).
+`DisplayTooltipRich.stories.ts` for a full working example.
 
 ## Notes
 
 - Auto-imported in Nuxt — no manual import needed.
 - 2026-09-07 migration: moved from an unplaced top-level folder into
-  `02.molecules/display-tooltip-defined/` (molecule tier, since it composes the `DisplayTooltip`
+  `02.molecules/display-tooltip-rich/` (molecule tier, since it composes the `DisplayTooltip`
   atom); converted options-style `defineProps` to `interface Props` + `withDefaults`; moved the
-  inline `TooltipContentText` interface out to `~/types/components/display-tooltip-defined.d.ts`
+  inline `TooltipContentText` interface out to `~/types/components/display-tooltip-rich.d.ts`
   so consumers can import it (inline `.vue` types aren't importable); fixed a dead CSS selector —
   the stylesheet targeted `.popover .popover-content .popover-content-defined`, but the actual
   rendered classes are `.display-tooltip-popover`/`.display-tooltip-popover-content`, so the rule
@@ -121,7 +111,7 @@ surface).
   the title/body/action text had been rendering only by accident, via CSS falling back to the
   inherited colour when a `var()` reference is unresolvable, not by design.
 - 2026-09-07 (same day, follow-up): `.popover-content-defined` gained `display: flex;
-  flex-direction: column;` and a `gap` (new `--display-tooltip-defined-content-gap` token), and
+  flex-direction: column;` and a `gap` (new `--display-tooltip-rich-content-gap` token), and
   its close button is now right-aligned (`align-self: flex-end`) rather than sitting inline after
   the action text — part of the same visual-polish pass as `DisplayTooltip` itself (see its skill
   doc). Note `align-self` only works because `.popover-content-defined` (the button's actual DOM
@@ -137,4 +127,12 @@ surface).
   `font-weight`, `line-height`, `letter-spacing`, and `margin-block` (all overridable, in case a
   consumer genuinely wants extra margin on top of `gap`) — rather than only `colour`. The close
   button gained its own `margin-block` token to separate it from the action text above it.
-- File: `app/components/02.molecules/display-tooltip-defined/DisplayTooltipDefined.vue`
+- 2026-10-18 migration: generic classes `.popover-content-defined`, `.tooltip-title`,
+  `.tooltip-body`, `.tooltip-action` renamed to `.display-tooltip-rich-content`, `-title`,
+  `-body`, `-action`, and the root gained `.display-tooltip-rich`; undefined utility classes
+  (`subtitle-sm`, `body-sm`, `input-value`) removed; the close button is now an `InputButton` (it
+  had no `type`, so it submitted surrounding forms), and its right alignment and margin finally
+  apply (`DisplayTooltip`'s `all: unset` close-button rule out-specified them, stretching it full
+  width); the generated id is created once at setup instead of inside a `computed`; new
+  `triggerIcon` prop, empty-tag fallback, `*-line-clamp` tokens and wrapping for worst-case content.
+- File: `app/components/02.molecules/display-tooltip-rich/DisplayTooltipRich.vue`

package/.claude/skills/components/display-tooltip.md

@@ -11,7 +11,7 @@ type: reference
 `DisplayTooltip` renders a trigger button that opens an anchor-positioned popover panel, built on
 the native Popover API (`popover`/`popovertarget`) and CSS anchor-positioning
 (`anchor-name`/`position-anchor`/`anchor()`). For a structured title/body/action content shape
-with a built-in close button, see [`DisplayTooltipDefined`](display-tooltip-defined.md), which
+with a built-in close button, see [`DisplayTooltipRich`](display-tooltip-rich.md), which
 composes this component.
 
 **Browser support:** since 2026-10-05 open/close and positioning go through the shared
@@ -25,8 +25,9 @@ closes in JS, with outside-click and Escape dismissal. The trigger has `aria-exp
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `tooltipId` | `string` | `""` | Id linking the trigger button (`popovertarget`) to the popover panel (`id`). Auto-generated via `useId()` when omitted. |
-| `hideTrigger` | `boolean` | `false` | Visually hides the trigger button (kept in the DOM, not removed) — e.g. when an equivalent trigger is supplied via the `triggerContent` slot. |
+| `hideTrigger` | `boolean` | `false` | Collapses the trigger button to zero width and removes it from the tab order and accessibility tree (`tabindex="-1"`, `aria-hidden`). It stays in the DOM as the panel's anchor: open the panel from your own button with `popovertarget="<tooltipId>"` (Popover API browsers only; Safari 16 has no way to open it then). |
 | `triggerAriaLabel` | `string` | `"Toggle the popover"` | aria-label on the trigger button — override for localisation. |
+| `triggerIcon` | `string` | `"fa7-solid:circle-question"` | Iconify name for the trigger button icon. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
 
 ## Slots
@@ -52,7 +53,7 @@ closes in JS, with outside-click and Escape dismissal. The trigger has `aria-exp
 ## CSS custom properties
 
 See `CONSUMER-STYLING.md` for the full `--display-tooltip-*` token API (padding, gaps, icon size,
-popover width/colours/radius, and the close-button tokens `DisplayTooltipDefined` uses).
+popover width/colours/radius, and the close-button tokens `DisplayTooltipRich` uses).
 
 ## Notes
 
@@ -61,9 +62,19 @@ popover width/colours/radius, and the close-button tokens `DisplayTooltipDefined
   `-line-height` (`1.4`), so a bare `<p>` reads as tooltip text without extra styling.
 
 - Auto-imported in Nuxt — no manual import needed.
-- `tooltipId` is only reactive at mount — changing it after mount does not regenerate the linked
-  `popovertarget`/`id` pair reactively beyond Vue's normal re-render, since both derive from the
-  same computed.
+- `tooltipId` is reactive: changing it updates both `popovertarget` and the panel `id`. Clearing it
+  falls back to the id generated once at setup (`nuxt-tooltip-<useId>`), which stays stable.
+- The trigger is `type="button"`, so it never submits a surrounding form. It stays a raw `<button>`
+  rather than `InputButton`, like `PopOver`'s: `useAnchoredPopover` needs the native element (it
+  carries `popovertarget` and `anchor-name`) in its ref.
+- Long unbroken text wraps in the trigger row and the panel; the panel width is capped at the
+  viewport (`100vw - 3.2rem`).
+- 2026-10-18 migration: root class `.display-tooltip-core` renamed to `.display-tooltip`; the
+  hidden trigger's generic `.hide` class replaced by `[data-hidden]`, plus `tabindex="-1"` and
+  `aria-hidden` so it's no longer an invisible tab stop; `type="button"` added (it submitted
+  surrounding forms); new `triggerIcon` prop; the generated id is created once at setup instead
+  of inside a `computed`; the close button's documented resting-outline token now works and its
+  hover styles apply on `:focus-visible`; wrapping and width cap for worst-case content.
 - 2026-09-07 migration: moved from an unplaced top-level folder into `01.atoms/display-tooltip/`;
   converted options-style `defineProps` to `interface Props` + `withDefaults`; fixed a real
   accessibility bug where the trigger button's hover/focus-visible state set `outline-offset` but