srcdev-nuxt-components 9.4.4 → 9.4.6

package/.claude/skills/components/breadcrumb.md

@@ -13,6 +13,7 @@ current page).
 |------|------|---------|----------|
 | `items` | `BreadcrumbItem[]` | — | **yes** |
 | `separator` | `string` | `"/"` | no |
+| `ariaLabel` | `string` | `"Breadcrumb"` | no — override for localisation |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | no |
 
 `BreadcrumbItem` is exported from `~/types/components/breadcrumb` (and re-exported from

package/.claude/skills/components/canvas-switcher.md

@@ -0,0 +1,61 @@
+# CanvasSwitcher Component
+
+## Overview
+
+`CanvasSwitcher` renders a row of icon buttons (mobile / tablet / laptop / desktop / full width)
+for switching a bound `MediaCanvas` value — typically used to drive a preview/demo wrapper's width
+while working on a responsive component in Storybook. Each button is an `InputButtonCore`
+(`variant="tertiary"`, icon-only), giving it the library's standard button focus ring and hover
+state for free instead of a raw `<button>`.
+
+## Model
+
+| Model | Type | Required |
+|---|---|---|
+| `canvasName` (`v-model:canvas-name`) | `MediaCanvas` | no |
+
+`MediaCanvas` is exported from `~/types/components/canvas-switcher` (and re-exported from
+`~/types/components`):
+
+```typescript
+type MediaCanvas = "mobileCanvas" | "tabletCanvas" | "laptopCanvas" | "desktopCanvas" | "fullWidthCanvas";
+```
+
+## Props
+
+| Prop | Type | Default | Required |
+|------|------|---------|----------|
+| `styleClassPassthrough` | `string \| string[]` | `[]` | no |
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import type { MediaCanvas } from "~/types/components";
+
+const canvasName = ref<MediaCanvas>("desktopCanvas");
+</script>
+
+<template>
+  <CanvasSwitcher v-model:canvas-name="canvasName" />
+  <div :class="canvasName">
+    <!-- preview content constrained to the selected canvas width -->
+  </div>
+</template>
+```
+
+The selected value doubles as a utility class name: `CanvasSwitcher`'s stylesheet also declares
+`.mobileCanvas`/`.tabletCanvas`/`.laptopCanvas`/`.desktopCanvas`/`.fullWidthCanvas` (max-width
+utilities, not scoped to `.canvas-switcher`), so binding `:class="canvasName"` directly onto a
+preview wrapper constrains it to match — see `LayoutGridA`/`LayoutGridB` stories for the pattern.
+These classes only ship in the bundle once `CanvasSwitcher` (or another importer of them) is
+actually imported somewhere, since Nuxt only bundles a component's SFC styles when it's used.
+
+## Notes
+
+- Component is auto-imported in Nuxt — no import needed.
+- No accessible-name prop is needed on the buttons — each one's `button-text` ("Mobile", "Tablet",
+  etc.) is rendered screen-reader-only by `InputButtonCore`'s icon-only handling, and the selected
+  button is marked via `aria-pressed="true"` rather than a private CSS-only "current" class.
+- See `CONSUMER-STYLING.md` in the component's own folder for the full `--canvas-switcher-*` token
+  API. Button-level tokens (surface/hover/focus) belong to `InputButtonCore`, not this component.

package/.claude/skills/components/clip-element.md

@@ -0,0 +1,67 @@
+---
+name: ClipElement
+description: ClipElement scroll-driven clip-path reveal — props, slot API, tokens, when to use vs ScrollRevealFrame
+type: reference
+---
+
+# ClipElement
+
+## Overview
+
+`ClipElement` clips its slot content in from the top edge as it scrolls into the viewport, using a
+`window` scroll listener to drive a `clip-path: inset(...)` value on the content. As the element's
+top position moves through the range `[0, maxClip]`, the clip inset shrinks from `maxClip` to `0`;
+once the element scrolls above the viewport (`top < 0`), the inset grows again past `maxClip`,
+re-clipping the content as it exits.
+
+This is a JS/scroll-listener implementation, unlike `ScrollRevealFrame`/`ScrollRevealImage` which
+use CSS Scroll-driven Animations with no listeners. Prefer `ScrollRevealFrame` for a general
+parallax pan effect with no JS overhead — reach for `ClipElement` specifically when you want this
+top-edge clip-in/clip-out behaviour rather than a pan.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `maxClip` | `number` | `100` | Scroll distance (px) over which the element clips in as it enters the viewport, and clips further out as it scrolls above it. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root `.clip-element-wrapper`. |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Content to clip. Rendered inside `.clipped-element`, which receives the computed `clip-path`. |
+
+## Basic usage
+
+```vue
+<ClipElement :max-clip="150">
+  <img src="/images/hero.jpg" alt="Hero" style="width: 100%; display: block;" />
+</ClipElement>
+```
+
+## How it works
+
+- A `scroll` listener (added on `onMounted`, client-only, `{ passive: true }`) reads
+  `.clipped-element`'s `getBoundingClientRect().top` on every scroll event.
+- `topPosition` between `0` and `maxClip`: clip inset = `maxClip - topPosition` (shrinks toward 0
+  as the element scrolls up into place).
+- `topPosition < 0` (element scrolled above the viewport): clip inset = `maxClip + abs(topPosition)`
+  (grows past `maxClip`, re-clipping as it exits upward).
+- `topPosition > maxClip` (element still below the visible clip range): clip inset stays `0`.
+- The computed inset is written to a private `--_clip-path` custom property via inline `:style`,
+  consumed by `.clipped-element { clip-path: var(--_clip-path); }`.
+
+## CSS custom properties
+
+`--_clip-path` is private and JS-driven — there is no public token API for this component. See
+`CONSUMER-STYLING.md` for the class-passthrough override surface.
+
+## Notes
+
+- `.clip-element-wrapper` has `overflow: hidden` — content that needs to escape (dropdowns,
+  tooltips) must be portalled outside.
+- No `IntersectionObserver`; the scroll listener runs on every scroll event for the page's
+  lifetime while the component is mounted. Avoid mounting many instances on one long page.
+- Client-only: the initial clip check and the listener are both gated behind `import.meta.client`,
+  so SSR renders the content unclipped until hydration.

package/.claude/skills/components/clipped-panel.md

@@ -0,0 +1,64 @@
+---
+name: ClippedPanel
+description: ClippedPanel fixed-size notched/cutout shape panel — props, variants, CSS tokens
+type: reference
+---
+
+# ClippedPanel
+
+## Overview
+
+`ClippedPanel` renders its slot content inside a panel clipped to one of three fixed-size
+notched shapes via `clip-path: path(...)`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `"div" \| "p" \| "span" \| "section" \| "article" \| "aside" \| "header" \| "footer" \| "main" \| "nav" \| "ul" \| "ol"` | `"div"` | Root element tag. |
+| `variant` | `"square" \| "rectangle" \| "circle-cutout"` | `"square"` | Which fixed-size shape to clip to. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
+
+## Variants
+
+| Variant | Fixed size | Shape |
+|---|---|---|
+| `square` | 200×200px | Rounded square with a small pull-tab notch cut into the top edge. |
+| `rectangle` | 300×200px | Same pull-tab notch shape, wider. |
+| `circle-cutout` | 200×200px | Rounded square with a 50px-radius circular notch bitten out of the top-right corner. |
+
+Each shape's `clip-path: path(...)` uses literal pixel coordinates matched to its fixed width —
+see CONSUMER-STYLING.md for why these can't be resized via CSS.
+
+## Basic usage
+
+```vue
+<ClippedPanel variant="square">
+  <p>Panel content</p>
+</ClippedPanel>
+
+<ClippedPanel variant="circle-cutout" tag="section">
+  <p>Panel content</p>
+</ClippedPanel>
+```
+
+## CSS custom properties
+
+| Property | Default | Controls |
+|----------|---------|----------|
+| `--clipped-panel-background-colour` | `light-dark(hsl(0, 0%, 96%), hsl(0, 0%, 12%))` | Panel background |
+| `--clipped-panel-outline-colour` | `light-dark(hsl(0, 29%, 3%), hsl(0, 0%, 92%))` | Outline colour and text/icon colour |
+| `--clipped-panel-outline-width` | `1px` | Outline width |
+
+## Notes
+
+- `aspect-ratio: 1` is set on the shared `.clipped-panel` base class, so height tracks whatever
+  `width` the active variant sets.
+- Shape geometry (corner radii, notch size, overall dimensions) is fixed per variant — CSS custom
+  properties can't be interpolated into a `path()` string. A new size/shape needs a new variant
+  with its own `path()`, not a token override.
+- 2026-09-07 migration: the previous `circle-cutout` variant shipped with an invalid, empty
+  `clip-path: path("M Z")` that rendered no clip at all. It now has a real shape (described
+  above). The unused `--_max-x-position`/`--_curve-radius` custom properties on `rectangle` were
+  also removed — they were declared but never actually referenced by the hardcoded path string,
+  so they did nothing.

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

@@ -18,6 +18,8 @@
 | `docsNavLabel` | `string` | `"Navigation"` | Heading text for the `docsNav` panel's `#summary`. |
 | `docsPageNavLabel` | `string` | `"On this page"` | Heading text for the `docsPageNav` panel's `#summary`. |
 | `panelVariant` | `"modern" \| "classic"` | `"classic"` | Which panel component renders `docsNav`/`docsPageNav`: `ExpandingPanel` (`"modern"`) or `ExpandingPanelClassic` (`"classic"`, default). `"modern"` is known not to work correctly on WebKit — the mobile nav (which relies on `contentIsOnTop`) becomes unreachable there. See CLAUDE.md pitfall #19. |
+| `docsNavAriaLabel` | `string` | `"Docs navigation"` | aria-label on the `docsNav` `<nav>` landmark — override for localisation. |
+| `docsPageNavAriaLabel` | `string` | `"On this page"` | aria-label on the `docsPageNav` `<nav>` landmark — override for localisation. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the root `.content-docs` element. |
 
 `DocsNavItem` (from `~/types/components`):

package/.claude/skills/components/deep-expanding-menu-classic.md

@@ -0,0 +1,94 @@
+---
+name: DeepExpandingMenuClassic
+description: DeepExpandingMenuClassic <details>-based top-level nav with click-outside close, CSS token API
+type: reference
+---
+
+# DeepExpandingMenuClassic
+
+## Overview
+
+`<details>`/`<summary>`-based fallback for [`DeepExpandingMenu`](deep-expanding-menu.md) — same
+props, same `ResponsiveHeaderNavItem` data shape, same visual result, but built without CSS
+anchor-positioning or the Popover API. Each nav item with `childLinks` renders as a native
+`<details>` element; opening one and clicking outside it closes it again via `@vueuse/core`'s
+`onClickOutside`.
+
+Prefer `DeepExpandingMenu` unless the modern implementation's browser support isn't acceptable for
+your target audience — see its own docs for the caveat.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `"div" \| "section" \| "nav" \| "ul" \| "ol"` | `"nav"` | Root element tag. |
+| `navLinks` | `ResponsiveHeaderNavItem[]` | `[]` | Top-level nav items. An item with `path` renders as a direct link; an item with `childLinks` renders as a `<details>` group. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
+
+`ResponsiveHeaderNavItem` is exported from `~/types/components` (shared with `ResponsiveHeader`).
+
+## Basic usage
+
+```vue
+<script setup lang="ts">
+import type { ResponsiveHeaderNavItem } from "~/types/components";
+
+const navLinks: ResponsiveHeaderNavItem[] = [
+  { name: "Home", path: "/" },
+  {
+    name: "Services",
+    childLinksTitle: "Our services",
+    childLinks: [
+      { name: "Haircuts", path: "/services/haircuts" },
+      { name: "Colouring", path: "/services/colouring" },
+    ],
+  },
+];
+</script>
+
+<template>
+  <DeepExpandingMenuClassic :nav-links="navLinks" />
+</template>
+```
+
+## CSS custom properties
+
+| Property | Default | Controls |
+|----------|---------|----------|
+| `--deep-expanding-menu-classic-gap` | `1.2rem` | Gap on the root grid |
+| `--deep-expanding-menu-classic-item-gap` | `2.4rem` | Gap between top-level items |
+| `--deep-expanding-menu-classic-link-border-width` | `0.2rem` | Bottom border width on links/toggles |
+| `--deep-expanding-menu-classic-link-padding-block` | `0.8rem` | Vertical padding on links/toggles |
+| `--deep-expanding-menu-classic-link-border-colour-hover` | `light-dark(var(--blue-10), var(--slate-00))` | Bottom border colour on hover/focus |
+| `--deep-expanding-menu-classic-icon-size` | `1.2rem` | Caret icon size |
+| `--deep-expanding-menu-classic-panel-offset-top` | `4rem` | Panel offset from the toggle |
+| `--deep-expanding-menu-classic-panel-width` | `20rem` | Panel width below `768px` |
+| `--deep-expanding-menu-classic-panel-width-tablet` | `40rem` | Panel width from `768px` |
+| `--deep-expanding-menu-classic-panel-width-desktop` | `60rem` | Panel width from `1024px` |
+| `--deep-expanding-menu-classic-panel-background-colour` | `white` | Panel background |
+| `--deep-expanding-menu-classic-panel-border-width` | `0.1rem` | Panel border width |
+| `--deep-expanding-menu-classic-panel-border-colour` | `black` | Panel border colour |
+| `--deep-expanding-menu-classic-panel-border-radius` | `1.2rem` | Panel corner radius |
+| `--deep-expanding-menu-classic-panel-shadow` | `0 0 1rem rgba(0, 0, 0, 0.1)` | Panel box-shadow |
+| `--deep-expanding-menu-classic-panel-padding` | `1.2rem` | Panel padding |
+| `--deep-expanding-menu-classic-panel-heading-colour` | `var(--slate-10)` | `childLinksTitle` heading colour |
+| `--deep-expanding-menu-classic-panel-list-gap` | `1.2rem` | Gap between child link grid items |
+| `--deep-expanding-menu-classic-group-link-colour` | `var(--slate-10)` | Child link text colour |
+| `--deep-expanding-menu-classic-group-link-border-colour-hover` | `var(--slate-10)` | Child link bottom border colour on hover/focus |
+
+See `CONSUMER-STYLING.md` for the full token API.
+
+## Notes
+
+- Auto-imported in Nuxt — no manual import needed.
+- Multiple `<details>` groups sharing `name="navigation-group"` means opening one does **not**
+  auto-close siblings (unlike a native accordion) — each group closes independently via
+  click-outside.
+- 2026-09-07 migration: moved from an unplaced top-level folder (was `DeepExpandingMenuOld.vue`)
+  into `02.molecules/navigation/deep-expanding-menu-classic/`; converted options-style
+  `defineProps` to `interface Props` + `withDefaults`; switched its locally-declared
+  `ResponsiveHeaderNavItem` interface to the shared exported type from `~/types/components`
+  (was a duplicate, drift-prone copy); removed a dead, unused `:id="popovertarget-nav-1-..."`
+  attribute left over from copying the modern implementation (this component doesn't use the
+  Popover API); promoted 19 previously-hardcoded values to public CSS tokens.
+- File: `app/components/02.molecules/navigation/deep-expanding-menu-classic/DeepExpandingMenuClassic.vue`

package/.claude/skills/components/deep-expanding-menu.md

@@ -0,0 +1,92 @@
+---
+name: DeepExpandingMenu
+description: DeepExpandingMenu top-level nav with anchor-positioned popover child-link panels, browser support caveat, CSS token API
+type: reference
+---
+
+# DeepExpandingMenu
+
+## Overview
+
+`DeepExpandingMenu` renders a top-level navigation row where each item is either a direct link
+(`link.path` set) or a toggle button that opens a popover panel of child links. It's built on CSS
+anchor-positioning (`anchor-name`/`position-anchor`/`anchor()`) and the native Popover API
+(`popover`/`popovertarget`).
+
+**Browser support caveat:** CSS anchor-positioning and the Popover API are both comparatively
+recent — check current browser support before shipping this on a page that must work everywhere,
+same caution as `ExpandingPanel`'s `::details-content` gap (CLAUDE.md pitfall #19). If broad
+support is a hard requirement, use [`DeepExpandingMenuClassic`](deep-expanding-menu-classic.md)
+instead — same API and visual result, built on `<details>`/`<summary>` +
+`onClickOutside` instead.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `"div" \| "section" \| "nav" \| "ul" \| "ol"` | `"nav"` | Root element tag. |
+| `navLinks` | `ResponsiveHeaderNavItem[]` | `[]` | Top-level nav items. An item with `path` renders as a direct link; an item with `childLinks` renders as a toggle + popover panel. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
+
+`ResponsiveHeaderNavItem` is exported from `~/types/components` (shared with `ResponsiveHeader`).
+
+## Basic usage
+
+```vue
+<script setup lang="ts">
+import type { ResponsiveHeaderNavItem } from "~/types/components";
+
+const navLinks: ResponsiveHeaderNavItem[] = [
+  { name: "Home", path: "/" },
+  {
+    name: "Services",
+    childLinksTitle: "Our services",
+    childLinks: [
+      { name: "Haircuts", path: "/services/haircuts" },
+      { name: "Colouring", path: "/services/colouring" },
+    ],
+  },
+];
+</script>
+
+<template>
+  <DeepExpandingMenu :nav-links="navLinks" />
+</template>
+```
+
+## CSS custom properties
+
+| Property | Default | Controls |
+|----------|---------|----------|
+| `--deep-expanding-menu-gap` | `2.4rem` | Gap between top-level items |
+| `--deep-expanding-menu-link-border-width` | `0.2rem` | Bottom border width on links/toggles |
+| `--deep-expanding-menu-link-padding-block` | `0.8rem` | Vertical padding on links/toggles |
+| `--deep-expanding-menu-link-border-colour-hover` | `light-dark(var(--blue-10), var(--slate-00))` | Bottom border colour on hover/focus |
+| `--deep-expanding-menu-icon-size` | `1.2rem` | Caret icon size |
+| `--deep-expanding-menu-panel-width` | `min(100%, 50vw)` | Popover panel width |
+| `--deep-expanding-menu-panel-background-colour` | `white` | Popover panel background |
+| `--deep-expanding-menu-panel-border-width` | `0.1rem` | Popover panel border width |
+| `--deep-expanding-menu-panel-border-colour` | `black` | Popover panel border colour |
+| `--deep-expanding-menu-panel-border-radius` | `1.2rem` | Popover panel corner radius |
+| `--deep-expanding-menu-panel-shadow` | `0 0 1rem rgba(0, 0, 0, 0.1)` | Popover panel box-shadow |
+| `--deep-expanding-menu-panel-padding` | `1.2rem` | Popover panel padding |
+| `--deep-expanding-menu-panel-heading-colour` | `var(--slate-10)` | `childLinksTitle` heading colour |
+| `--deep-expanding-menu-panel-list-gap` | `1.2rem` | Gap between child link grid items |
+| `--deep-expanding-menu-group-link-colour` | `var(--slate-10)` | Child link text colour |
+| `--deep-expanding-menu-group-link-border-colour-hover` | `var(--slate-10)` | Child link bottom border colour on hover/focus |
+
+See `CONSUMER-STYLING.md` for the full token API and what's not tokenised.
+
+## Notes
+
+- Auto-imported in Nuxt — no manual import needed.
+- Anchor names and popover target ids are generated per-instance via `useId()`, so multiple
+  instances on one page don't collide.
+- 2026-09-07 migration: moved from an unplaced top-level folder into
+  `02.molecules/navigation/deep-expanding-menu/`; converted options-style `defineProps` to
+  `interface Props` + `withDefaults`; the previous hardcoded `nav-1` anchor/popover id prefix
+  (a multi-instance collision bug) was replaced with a `useId()`-scoped prefix; removed a dead,
+  never-consumed `ref="detailsRef"` template ref; promoted 16 previously-hardcoded values (gap,
+  border widths/colours, panel background/border/radius/shadow/padding, heading and link colours)
+  to public CSS tokens.
+- File: `app/components/02.molecules/navigation/deep-expanding-menu/DeepExpandingMenu.vue`

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

@@ -0,0 +1,60 @@
+---
+name: DisplayBanner
+description: DisplayBanner canvas/content stacked overlay banner — props, slots, CSS tokens
+type: reference
+---
+
+# DisplayBanner
+
+## Overview
+
+`DisplayBanner` stacks a `canvas` slot (background media) and a `content` slot (overlaid
+text/CTAs) into a single grid area, so content renders on top of the canvas. Either slot may be
+omitted; an unused slot contributes no empty wrapper `<div>` to the DOM.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `"div" \| "p" \| "span" \| "section" \| "article" \| "aside" \| "header" \| "footer" \| "main" \| "nav" \| "ul" \| "ol"` | `"div"` | Root element tag. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `canvas` | Background media (image, video, or any visual). Rendered first, so it sits behind `content`. |
+| `content` | Overlaid content (text, CTAs). Rendered after `canvas`, so it sits on top. |
+
+## Basic usage
+
+```vue
+<DisplayBanner>
+  <template #canvas>
+    <NuxtImg src="/hero.jpg" alt="" style="width: 100%; height: 100%; object-fit: cover;" />
+  </template>
+  <template #content>
+    <h2>Banner heading</h2>
+  </template>
+</DisplayBanner>
+```
+
+## CSS custom properties
+
+| Property | Default | Controls |
+|----------|---------|----------|
+| `--display-banner-min-height` | `auto` | Minimum height of the banner |
+
+See `CONSUMER-STYLING.md` for the full token API.
+
+## Notes
+
+- `container-type: inline-size` is set on the root, so slot content can use container queries.
+- No sizing/aspect-ratio is imposed on the `canvas` slot's content itself (e.g. an image needs its
+  own `width`/`height`/`object-fit`) — `DisplayBanner` only positions the two slots, it doesn't
+  style what's inside them.
+- 2026-09-07 migration: removed a dead `.canvas .image { object-fit: cover; ... }` CSS rule that
+  assumed consumer-slotted content would use a generic `.image` class — nothing in the template
+  ever rendered that class, and styling a generic class name inside a slot risks colliding with a
+  consumer's own `.image` class (see CLAUDE.md pitfall #16). Style slotted media directly on the
+  element you put in the slot instead.

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

@@ -0,0 +1,139 @@
+---
+name: DisplayTooltipDefined
+description: DisplayTooltipDefined structured title/body/action tooltip content with close button, composes DisplayTooltip
+type: reference
+---
+
+# DisplayTooltipDefined
+
+## Overview
+
+`DisplayTooltipDefined` 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`. 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.
+
+## 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. |
+| `triggerAriaLabel` | `string` | `"Toggle the popover"` | Forwarded to the underlying `DisplayTooltip`'s `triggerAriaLabel` — override for localisation. |
+| `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. |
+
+`TooltipContentText` is exported from `~/types/components`:
+
+```ts
+interface TooltipContentTextItem {
+  tag: string;   // e.g. "h4", "p", "span"
+  text: string;
+}
+
+interface TooltipContentText {
+  tooltipTitle?: TooltipContentTextItem;
+  tooltipContent?: TooltipContentTextItem;
+  tooltipAction?: TooltipContentTextItem;
+}
+```
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `triggerContent` | Passed through to the underlying `DisplayTooltip`'s `triggerContent` slot. |
+
+## Basic usage
+
+```vue
+<script setup lang="ts">
+import type { TooltipContentText } from "~/types/components";
+
+const contentText: TooltipContentText = {
+  tooltipTitle: { tag: "h4", text: "Free delivery" },
+  tooltipContent: { tag: "p", text: "Orders over £50 qualify for free standard delivery." },
+  tooltipAction: { tag: "span", text: "See delivery policy" },
+};
+</script>
+
+<template>
+  <DisplayTooltipDefined :content-text="contentText" />
+</template>
+```
+
+## 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.
+
+## 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
+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).
+
+## 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`
+  atom); converted options-style `defineProps` to `interface Props` + `withDefaults`; moved the
+  inline `TooltipContentText` interface out to `~/types/components/display-tooltip-defined.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
+  never matched anything; replaced two custom properties referencing tokens never declared
+  anywhere in this repo (`--nuxt-text-white-header`, `--nuxt-text-white-body`) with real public
+  tokens defaulting to `inherit` (same class of bug as `AnimatedSvgText`, CLAUDE.md pitfall #21) —
+  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
+  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
+  parent) is the flex container — the shared `.display-tooltip-popover-content` wrapper one level
+  up is a different, outer flex context and can't align this button directly.
+- 2026-09-07 (user follow-up): fixed a real spacing bug, not a preference tweak — `contentText.*.tag`
+  lets the consumer pick any tag (`h3`, `h4`, `p`, ...), and a heading tag carries its own
+  non-zero UA default `margin-block` (e.g. `1em`/`1em`), which was stacking on top of
+  `.popover-content-defined`'s flex `gap` and visually doubling the space between title/body/action.
+  `margin-block: 0 0` now resets that UA default on all three regardless of which tag is chosen, so
+  `gap` is the only spacing mechanism — see the comment in the component. Also gave each of
+  `tooltipTitle`/`tooltipContent`/`tooltipAction` a full typographic token set — `font-size`,
+  `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`