srcdev-nuxt-components 9.4.11 → 9.5.0

package/.claude/skills/components/scroll-reveal-frame.md

@@ -1,6 +1,6 @@
 ---
 name: ScrollRevealFrame
-description: ScrollRevealFrame generic parallax clipping frame — props, slot API, CSS tokens, browser support, when to use vs ScrollRevealImage
+description: ScrollRevealFrame generic parallax clipping frame — props, slot API, public CSS tokens (prop or CSS), browser support, when to use vs ScrollRevealImage
 type: reference
 ---
 
@@ -14,26 +14,28 @@ Use `ScrollRevealFrame` when the content inside the frame is **anything other th
 
 ## How it works
 
-- The `<figure>` root is a fixed-height clipping window (`overflow: hidden`) that registers a named `view-timeline`.
-- The inner `.reveal-content` wrapper is taller than the frame by `parallaxOffset` and animates `translateY` as the frame scrolls through the viewport.
+- The `<figure class="scroll-reveal-frame">` root is a fixed-height clipping window (`overflow: hidden`) that registers a named `view-timeline`.
+- The inner `.scroll-reveal-frame-content` wrapper is taller than the frame by the parallax offset and animates `translateY` as the frame scrolls through the viewport.
 - Slot content fills that wrapper — anything inside pans as a unit.
 
 Browser support (as of 2026): Chrome 115+, Edge 115+, Firefox 114+, Safari 17.2+. Older browsers fall back to a static cropped view.
 
 ## Props
 
+The three sizing props have **no default**. When passed, each writes its public token inline on the root (so it wins over any CSS). When omitted, the token comes from CSS, falling back to the default shown.
+
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `frameHeight` | `string` | `"540px"` | Height of the visible clipping frame. Any CSS length unit (`px`, `vh`, `rem`). |
-| `parallaxOffset` | `string` | `"36rem"` | Distance the content travels vertically across the full scroll range. Larger = more dramatic reveal. |
-| `radius` | `string` | `"0px"` | `border-radius` applied to the clipping frame. Slot content stays contained within the rounded shape. |
+| `frameHeight` | `string` | unset (CSS `540px`) | Height of the visible clipping frame. Any CSS length unit. Writes `--scroll-reveal-frame-height`. |
+| `parallaxOffset` | `string` | unset (CSS `36rem`) | Distance the content travels vertically across the full scroll range. Writes `--scroll-reveal-frame-parallax-offset`. |
+| `radius` | `string` | unset (CSS `0px`) | `border-radius` of the clipping frame. Writes `--scroll-reveal-frame-radius`. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root `<figure>`. |
 
 ## Slots
 
 | Slot | Description |
 |------|-------------|
-| `default` | Content to pan. It fills a `div.reveal-content` that is taller than the frame by `parallaxOffset`. |
+| `default` | Content to pan. It fills a `div.scroll-reveal-frame-content` that is taller than the frame by the parallax offset. |
 
 ## Basic usage — single image
 
@@ -91,29 +93,27 @@ Wrap each `<img>` / `<NuxtImg>` in a `<div>` cell — `object-fit` on an `<img>`
 
 ## Responsive frame height
 
-The `frameHeight` prop sets `--_frame-height` as an inline style. To vary it responsively, override the CSS custom property in a scoped style block:
+Don't pass the prop; set the public token from CSS on an element you own:
 
 ```css
 .my-page {
-  .reveal-frame {
-    --_frame-height: 320px;
+  --scroll-reveal-frame-height: 320px;
 
-    @media (width >= 768px) {
-      --_frame-height: 540px;
-    }
+  @media (width >= 768px) {
+    --scroll-reveal-frame-height: 540px;
   }
 }
 ```
 
 ## CSS custom properties
 
-These are set from props via inline `:style` but can be overridden in CSS for responsive or contextual control.
+Full detail in `CONSUMER-STYLING.md` next to the component.
 
-| Property | Default | Set by prop |
+| Property | Default | Set by prop (when passed) |
 |----------|---------|-------------|
-| `--_frame-height` | `540px` | `frameHeight` |
-| `--_parallax-offset` | `36rem` | `parallaxOffset` |
-| `--_radius` | `0px` | `radius` |
+| `--scroll-reveal-frame-height` | `540px` | `frameHeight` |
+| `--scroll-reveal-frame-parallax-offset` | `36rem` | `parallaxOffset` |
+| `--scroll-reveal-frame-radius` | `0px` | `radius` |
 
 ## Choosing parallaxOffset
 
@@ -131,6 +131,7 @@ Values below `20rem` tend to look static at normal scroll speeds.
 ## Notes
 
 - `overflow: hidden` is on the root `<figure>` — content that needs to escape (dropdowns, tooltips) must be portalled outside.
-- The named `view-timeline` (`--reveal-frame-timeline`) is scoped to the component. Multiple `ScrollRevealFrame` instances on the same page are independent.
-- Reduced-motion: the animation is disabled and the content falls back to a static centred crop via `@media (prefers-reduced-motion: reduce)`.
+- The named `view-timeline` (`--scroll-reveal-frame-timeline`) is scoped to the component. Multiple `ScrollRevealFrame` instances on the same page are independent.
+- Reduced-motion: the animation is disabled and the content is sized to the frame (a static crop) via `@media (prefers-reduced-motion: reduce)`. Same for browsers without `animation-timeline`.
 - Do not put `ScrollRevealFrame` inside a container with `overflow: hidden` or `overflow: clip` — this breaks the `view-timeline` scroll detection.
+- 2026-09-27 migration: the private `--_frame-height`/`--_parallax-offset`/`--_radius` tokens became public `--scroll-reveal-frame-*` tokens, and the props lost their defaults. Before, the props always wrote the private tokens inline, so the CSS override this doc used to recommend could never apply. Classes renamed `.reveal-frame` → `.scroll-reveal-frame`, `.reveal-content` → `.scroll-reveal-frame-content`; keyframes `reveal-pan` → `scroll-reveal-frame-pan` (generic global names, collision-prone). `ScrollRevealImage`'s image class became `.scroll-reveal-image`.

package/.claude/skills/components/scroll-reveal-image.md

@@ -1,6 +1,6 @@
 ---
 name: ScrollRevealImage
-description: ScrollRevealImage single-image parallax reveal — props, focalX usage, CSS tokens, browser support, when to use vs ScrollRevealFrame
+description: ScrollRevealImage single-image parallax reveal — props, focalX and focal-y crop tokens, CSS tokens (prop or CSS), browser support, when to use vs ScrollRevealFrame
 type: reference
 ---
 
@@ -20,10 +20,10 @@ For arbitrary slot content — a grid of images, video, markup — use `ScrollRe
 | `alt` | `string` | `""` | Alt text for the image. |
 | `imgWidth` | `number` | `1920` | Intrinsic width of the source image — required for NuxtImg optimisation. |
 | `imgHeight` | `number` | `1080` | Intrinsic height of the source image — required for NuxtImg optimisation. |
-| `frameHeight` | `string` | `"540px"` | Height of the visible clipping frame. Any CSS length unit (`px`, `vh`, `rem`). |
-| `parallaxOffset` | `string` | `"36rem"` | Distance the image travels vertically across the full scroll range. Larger = more dramatic reveal. |
-| `focalX` | `string` | `"50%"` | Horizontal focal point — CSS `object-position` x-axis value. Controls which horizontal slice stays in view. |
-| `radius` | `string` | `"0px"` | `border-radius` applied to the clipping frame. |
+| `frameHeight` | `string` | unset (CSS default `540px`) | Height of the visible clipping frame. Any CSS length unit. Leave unset to control it from CSS via `--scroll-reveal-frame-height`. |
+| `parallaxOffset` | `string` | unset (CSS default `36rem`) | Distance the image travels vertically across the full scroll range. Leave unset to control it via `--scroll-reveal-frame-parallax-offset`. |
+| `focalX` | `string` | unset (CSS default `50%`) | Horizontal focal point, CSS `object-position` x value. Controls which horizontal slice stays in view. Leave unset to control it via `--scroll-reveal-image-focal-x`. |
+| `radius` | `string` | unset (CSS default `0px`) | `border-radius` of the clipping frame. Leave unset to control it via `--scroll-reveal-frame-radius`. |
 | `loading` | `"lazy" \| "eager"` | `"lazy"` | Image loading strategy. Use `"eager"` if this is the LCP image (e.g. partially in view on load). |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root `<figure>`. |
 
@@ -102,7 +102,7 @@ The vertical position of the image is driven by the scroll animation (`translate
 | `"75%"` | Right of centre — useful for a subject offset to the right |
 | `"100%"` or `"right"` | Right edge |
 
-Internally, `focalX` sets `object-position: <focalX> 0%` on the `<img>`. The `Y` is always `0%` because the animation handles vertical travel.
+Internally, `focalX` sets `--scroll-reveal-image-focal-x`, used as `object-position: <focal-x> <focal-y>` on the `<img>`. The Y comes from `--scroll-reveal-image-focal-y` (default `0%`, so the animation starts at the image top); raise it if the top of the image is empty or the subject sits low. With no animation (reduced motion or no support), Y is `--scroll-reveal-image-focal-y-static` (default `50%`).
 
 ## imgWidth / imgHeight
 
@@ -122,34 +122,43 @@ Common pairs:
 
 ## Responsive frame height
 
-Override `--_frame-height` in a scoped style block for responsive control:
+Don't pass `frame-height`, and set the frame's public token from CSS on an ancestor you own (a prop,
+when passed, is written inline and always wins):
 
 ```css
 .my-page {
-  .reveal-frame {
-    --_frame-height: 320px;
+  --scroll-reveal-frame-height: 320px;
 
-    @media (width >= 768px) {
-      --_frame-height: 480px;
-    }
+  @media (width >= 768px) {
+    --scroll-reveal-frame-height: 480px;
+  }
 
-    @media (width >= 1024px) {
-      --_frame-height: 540px;
-    }
+  @media (width >= 1024px) {
+    --scroll-reveal-frame-height: 540px;
   }
 }
 ```
 
+> **Changed 2026-09-27**: this section used to recommend overriding `--_frame-height` on
+> `.reveal-frame`. That never worked, because this component always passed a default `frameHeight`
+> down and the frame always wrote it inline. The frame-sizing props now default to unset.
+
 ## CSS custom properties
 
-Set from props via inline `:style` — override in CSS for responsive or contextual control.
+Frame tokens come from `ScrollRevealFrame` (see its `CONSUMER-STYLING.md`); each prop writes its
+token inline only when passed.
 
 | Property | Default | Set by prop |
 | -------- | ------- | ----------- |
-| `--_frame-height` | `540px` | `frameHeight` |
-| `--_parallax-offset` | `36rem` | `parallaxOffset` |
-| `--_radius` | `0px` | `radius` |
-| `--_focal-x` | `50%` | `focalX` |
+| `--scroll-reveal-frame-height` | `540px` | `frameHeight` |
+| `--scroll-reveal-frame-parallax-offset` | `36rem` | `parallaxOffset` |
+| `--scroll-reveal-frame-radius` | `0px` | `radius` |
+| `--scroll-reveal-image-focal-x` | `50%` | `focalX` |
+| `--scroll-reveal-image-focal-y` | `0%` | none (CSS only) |
+| `--scroll-reveal-image-focal-y-static` | `50%` | none (CSS only) |
+
+Classes: root `.scroll-reveal-frame`, wrapper `.scroll-reveal-frame-content`, image
+`.scroll-reveal-image` (renamed 2026-09-27 from `.reveal-frame`/`.reveal-content`/`.reveal-image`).
 
 ## Choosing parallaxOffset
 
@@ -160,5 +169,6 @@ See `scroll-reveal-frame.md` for the full guide. For portrait images the default
 - The root `<figure>` has `margin: 0` set in the component — browser default `<figure>` margins are neutralised at source.
 - `decoding="async"` is always set on the `<img>`. Use `:loading="'eager'"` if this component is the LCP image (e.g. a hero partially in view on load) — the default `"lazy"` is correct for below-fold usage.
 - Do not place inside a container with `overflow: hidden` or `overflow: clip` — breaks the `view-timeline` scroll detection inherited from `ScrollRevealFrame`.
-- Reduced-motion: animation is disabled and the image falls back to a static crop centred at `object-position: <focalX> 50%`.
+- Reduced-motion: animation is disabled and the image falls back to a static crop at `object-position: <focal-x> <focal-y-static>` (default `50% 50%`).
+- 2026-09-27 migration: `focalX` lost its `"50%"` default and now writes the public `--scroll-reveal-image-focal-x` only when passed (it was a private `--_focal-x`, always inline, so CSS could never change it). New `--scroll-reveal-image-focal-y`/`-focal-y-static` tokens replace the hardcoded vertical crop. Added CONSUMER-STYLING.md, snippet and a `CssTokens` story.
 - Storybook: the `"none"` image provider is active (`nuxt.config.ts`), so `src` paths pass through unchanged. Always provide explicit `img-width` and `img-height` props to avoid the `w=1536` fallback in deployed Storybook.

package/.claude/skills/components/service-detail.md

@@ -111,7 +111,7 @@ are delegated to the consumer, matching `ServiceSummary`'s slot-based routing pa
   :related-services="relatedServices"
 >
   <template #book-cta>
-    <InputButtonCore tag="a" href="/contact" button-text="Book now" variant="primary" />
+    <InputButton tag="a" href="/contact" button-text="Book now" variant="primary" />
   </template>
   <template #sidebar-note>
     A patch test is required at least 48 hours before any colour treatment.
@@ -120,7 +120,7 @@ are delegated to the consumer, matching `ServiceSummary`'s slot-based routing pa
     <NuxtLink :to="`/services/${related.slug}`">{{ related.title }} — {{ related.price }}</NuxtLink>
   </template>
   <template #final-cta>
-    <InputButtonCore tag="a" href="/contact" button-text="Book now" variant="secondary" />
+    <InputButton tag="a" href="/contact" button-text="Book now" variant="secondary" />
   </template>
 </ServiceDetail>
 ```

package/.claude/skills/components/services-card-grid.md

@@ -10,13 +10,14 @@
 | ----------------------- | --------------------------------- | -------------------------------- | -------- |
 | `servicesData`          | `Service[]`                       | —                                | **yes**  |
 | `tag`                   | `"div" \| "section" \| "main"`    | `"div"`                          | no       |
-| `eyebrowConfig`         | `EyebrowConfig`                   | `{}`                             | no       |
-| `heroConfig`            | `HeroConfig`                      | `{}`                             | no       |
+| `eyebrowConfig`         | `ServicesCardEyebrowConfig`                   | `{}`                             | no       |
+| `heroConfig`            | `ServicesCardHeroConfig`                      | `{}`                             | no       |
 | `hrefBase`              | `string`                          | `"/services/"`                    | no     |
 | `buttonTextPrefix`      | `string`                          | `"Enquire about"`                | no       |
+| `buttonIcon` | `string` | `"mdi:arrow-right"` | no |
 | `styleClassPassthrough` | `string \| string[]`              | `[]`                             | no       |
 
-Both config props are passed through to every `ServicesCard` in the grid unchanged. See [services-card.md](./services-card.md) for the full `EyebrowConfig` / `HeroConfig` key reference.
+Both config props are passed through to every `ServicesCard` in the grid unchanged. See [services-card.md](./services-card.md) for the full key reference. The types are exported as `ServicesCardEyebrowConfig` / `ServicesCardHeroConfig` from `srcdev-nuxt-components` (were inline and not importable before 2026-09-28).
 
 ### Button link and text
 
@@ -104,6 +105,6 @@ if (servicesData.value.length === 0) {
 
 - Component is auto-imported in Nuxt — no import needed.
 - The `Service` type is imported from `~/types/types.services`.
-- Uses `repeat(auto-fit, minmax(var(--services-card-grid-column-min-width, 250px), 1fr))` — columns grow to fill available space and wrap when below the minimum width.
+- Uses `repeat(auto-fit, minmax(min(var(--services-card-grid-column-min-width, 250px), 100%), 1fr))` (the `min(…, 100%)` stops a single column overflowing containers narrower than the minimum, fixed 2026-09-28) — columns grow to fill available space and wrap when below the minimum width.
 - The `#actions` slot template is passed down into each `ServicesCard`; `serviceData` is the scoped prop for the current iteration item.
 - Data fetching is the page's responsibility — pass an empty array as fallback while loading (`servicesData ?? []`).

package/.claude/skills/components/services-card.md

@@ -12,8 +12,8 @@
 | `tag`                   | `"div" \| "section" \| "article"` | `"div"`     | no       |
 | `href`                  | `string`                           | `undefined` | no       |
 | `external`              | `boolean`                          | `false`     | no       |
-| `eyebrowConfig`         | `EyebrowConfig`                    | `{}`        | no       |
-| `heroConfig`            | `HeroConfig`                       | `{}`        | no       |
+| `eyebrowConfig`         | `ServicesCardEyebrowConfig`                    | `{}`        | no       |
+| `heroConfig`            | `ServicesCardHeroConfig`                       | `{}`        | no       |
 | `durationText`          | `string`                           | `undefined` | no       |
 | `priceText`             | `string`                           | `undefined` | no       |
 | `styleClassPassthrough` | `string \| string[]`               | `[]`        | no       |
@@ -24,7 +24,7 @@ A row below the description shows duration (left) and price (right), separated b
 
 ### Whole-card clickable (`href`)
 
-When `href` is set **and no `actions` slot content is provided**, the root element switches from `tag` to a link (`NuxtLink` for an internal href starting with `/`, a plain `a` otherwise) and the whole card becomes clickable — matching `InputButtonCore`'s link-resolution pattern. `external` forces a plain `a` tag even for an internal-looking href (e.g. a Nitro server route like `/api/auth/github`).
+When `href` is set **and no `actions` slot content is provided**, the root element switches from `tag` to a link (`NuxtLink` for an internal href starting with `/`, a plain `a` otherwise) and the whole card becomes clickable — matching `InputButton`'s link-resolution pattern. `external` forces a plain `a` tag even for an internal-looking href (e.g. a Nitro server route like `/api/auth/github`).
 
 If an `actions` slot is provided, the card stays as a static `tag` element (no href rendered) even when `href` is set — this avoids nesting another interactive element (e.g. a button/link in `actions`) inside the card's own anchor, which would be invalid HTML. Use the `href` mode for a plain "whole card links out" card with no separate CTA, and the `actions`-slot mode (see Basic usage below) when the card needs its own button/link.
 
@@ -32,6 +32,8 @@ If an `actions` slot is provided, the card stays as a static `tag` element (no h
 
 ### EyebrowConfig
 
+Exported as `ServicesCardEyebrowConfig` (and `ServicesCardHeroConfig` below) from `srcdev-nuxt-components` since 2026-09-28.
+
 | Key        | Type                              | Default   |
 | ---------- | ---------------------------------- | --------- |
 | `tag`      | `"p" \| "div" \| "span"`          | `"div"`   |
@@ -71,7 +73,7 @@ scaffold a style block using `styleClassPassthrough` instead — see
 ```vue
 <ServicesCard :service-data="service">
   <template #actions="{ serviceData }">
-    <InputButtonCore
+    <InputButton
       variant="secondary"
       :button-text="`More about ${serviceData.title}`"
       :href="`/services/${serviceData.slug}`"
@@ -79,7 +81,7 @@ scaffold a style block using `styleClassPassthrough` instead — see
       <template #right>
         <Icon name="mdi:arrow-right" class="icon" />
       </template>
-    </InputButtonCore>
+    </InputButton>
   </template>
 </ServicesCard>
 ```
@@ -93,7 +95,7 @@ scaffold a style block using `styleClassPassthrough` instead — see
   :hero-config="{ tag: 'h3', fontSize: 'title' }"
 >
   <template #actions="{ serviceData }">
-    <InputButtonCore variant="secondary" :button-text="`Enquire`" :href="`/services/${serviceData.slug}`" />
+    <InputButton variant="secondary" :button-text="`Enquire`" :href="`/services/${serviceData.slug}`" />
   </template>
 </ServicesCard>
 ```
@@ -111,7 +113,7 @@ scaffold a style block using `styleClassPassthrough` instead — see
     <span>From {{ serviceData.price }}</span>
   </template>
   <template #actions="{ serviceData }">
-    <InputButtonCore variant="secondary" :button-text="`Enquire`" :href="`/services/${serviceData.slug}`" />
+    <InputButton variant="secondary" :button-text="`Enquire`" :href="`/services/${serviceData.slug}`" />
   </template>
 </ServicesCard>
 ```
@@ -126,7 +128,7 @@ scaffold a style block using `styleClassPassthrough` instead — see
     :hero-config="{ tag: 'h2', fontSize: 'heading' }"
   >
     <template #actions="{ serviceData }">
-      <InputButtonCore
+      <InputButton
         variant="secondary"
         :button-text="`Enquire about ${serviceData.title}`"
         :href="`/services/${serviceData.slug}`"
@@ -135,7 +137,7 @@ scaffold a style block using `styleClassPassthrough` instead — see
         <template #right>
           <Icon name="mdi:arrow-right" class="icon" />
         </template>
-      </InputButtonCore>
+      </InputButton>
     </template>
   </ServicesCard>
 </template>
@@ -172,5 +174,5 @@ No `actions` slot — the entire card renders as an anchor (`NuxtLink` for the i
 - Root markup is two rows (`grid-template-rows: auto 1fr`): `.image-wrapper`, then a `.details-wrapper` (`display: flex; flex-direction: column`) holding the eyebrow, title, description, and a `.footer` wrapper. Description length is controlled by `--description-line-clamp` (default effectively unclamped) rather than a fixed-height grid row.
 - `.footer` groups the meta row and the `actions` slot and gets `margin-block-start: auto`, pinning them to the bottom of the card. Combined with the root's `1fr` details row, this means when `ServicesCardGrid`'s default `align-items: stretch` makes a card taller than its own content (to match a taller sibling in the same row), the extra height goes to `.footer`'s top margin rather than leaving whitespace below the actions slot — so the meta row and actions/button line up across a row of cards regardless of each card's description length. This does the visual job of CSS subgrid without needing a subgrid chain across `ServicesCard`/`ServicesCardGrid` (which would also break whenever cards in a row don't all render the same optional rows — `.meta` and `actions` are both conditional).
 - Image has a `3/4` aspect ratio with a subtle scale-on-hover effect.
-- `.services-card`, `.image-wrapper`, `.details-wrapper`, and `.footer` all set `min-inline-size: 0`. Without it, an unbreakable child — most commonly a long `actions` slot button label, since `InputButtonCore`'s `.button-text` is `white-space: nowrap` with no ellipsis — forces its content's min-content width up through the flex/grid chain and widens that one card's grid column in `ServicesCardGrid` wider than its siblings (the image just rides along on the widened column; it isn't the actual cause). If you see one card/column wider than the rest with cut-off content, check for a long unbreakable string in a slot before assuming it's an image sizing issue.
+- `.services-card`, `.image-wrapper`, `.details-wrapper`, and `.footer` all set `min-inline-size: 0`. Without it, an unbreakable child — most commonly a long `actions` slot button label, since `InputButton`'s `.button-text` is `white-space: nowrap` with no ellipsis — forces its content's min-content width up through the flex/grid chain and widens that one card's grid column in `ServicesCardGrid` wider than its siblings (the image just rides along on the widened column; it isn't the actual cause). If you see one card/column wider than the rest with cut-off content, check for a long unbreakable string in a slot before assuming it's an image sizing issue.
 - Usually consumed via `ServicesCardGrid` rather than directly.

package/.claude/skills/components/site-navigation.md

@@ -17,6 +17,8 @@ Both the horizontal list and the panel include animated active/hover indicator d
 | `navItemData` | `NavItemData` | — (required) | Navigation items — see type below |
 | `navAlign` | `"left" \| "center" \| "right"` | `"left"` | Alignment of the horizontal nav list |
 | `ariaLabel` | `string` | `"Site navigation"` | aria-label on the root `<nav>` landmark — override for localisation |
+| `openMenuLabel` | `string` | `"Open navigation menu"` | Burger button text (screen-reader) while closed — override for localisation |
+| `closeMenuLabel` | `string` | `"Close navigation menu"` | Burger button text (screen-reader) while open — override for localisation |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root `<nav>` |
 
 ## NavItemData type
@@ -24,7 +26,7 @@ Both the horizontal list and the panel include animated active/hover indicator d
 **Within the layer:**
 
 ```ts
-import type { NavItemData } from "~/types/components/navigation-horizontal.d";
+import type { NavItemData } from "~/types/components/nav-item.d";
 ```
 
 **In a consuming app:**
@@ -70,6 +72,8 @@ Set these tokens on a parent element (e.g. your `<header>`) to theme the navigat
 .your-header {
   /* ── Decorators ────────────────────────────────────── */
   --site-nav-decorator-indicator-color: var(--rose-05);  /* underline bar */
+  --site-nav-decorator-hovered-bg:      transparent;     /* hover pill behind a link */
+  --site-nav-decorator-active-bg:       transparent;     /* active pill behind a link */
 
   /* ── Horizontal nav links ──────────────────────────── */
   --site-nav-link-color:        var(--warm-01);
@@ -102,30 +106,40 @@ Set these tokens on a parent element (e.g. your `<header>`) to theme the navigat
   --site-nav-burger-gap:        5px;
   --site-nav-burger-transition: 300ms ease;
 
-  /* ── Backdrop (teleported to <body>) ───────────────── */
+}
+```
+
+The backdrop is teleported to `<body>`, so its tokens only land when set on `:root`/`html`/`body`,
+not on your header:
+
+```css
+:where(html) {
   --site-nav-backdrop-bg:       oklch(0% 0 0 / 55%);
   --site-nav-backdrop-blur:     3px;
   --site-nav-backdrop-duration: 350ms;
+  --site-nav-backdrop-z-index:  10;  /* keep your header above this */
 }
 ```
 
+Full reference: `app/components/02.molecules/navigation/site-navigation/CONSUMER-STYLING.md`.
+
 ## Behaviour notes
 
 - **Collapse detection**: `ResizeObserver` fires on every container resize. The list's `scrollWidth` is cached whenever the list is in the DOM; that cached value is compared against the container's `clientWidth` to set `isCollapsed`.
 - **isLoaded state**: The component uses `useState("site-nav-loaded")` — a Nuxt shared state — to gate visibility until the first measurement is complete, preventing a flash of the wrong nav state on load. The nav renders `opacity: 0` until `is-loaded` is applied.
 - **Teleport**: The backdrop overlay is teleported to `<body>` via `<Teleport>` and is only mounted when `isCollapsed && isLoaded`.
-- **Panel inert**: The `#site-nav-panel` div receives `:inert="!isMenuOpen ? true : undefined"` — it is inert (keyboard/pointer-inaccessible) when closed.
+- **Panel inert**: The panel div (id `site-nav-panel-{useId}`, unique per instance) receives `:inert="!isMenuOpen ? true : undefined"` — it is inert (keyboard/pointer-inaccessible) when closed.
 - **Decorator init**: `initNavDecorators()` and `initPanelDecorators()` inject `<li>` elements with CSS-driven indicator `<div>`s. They query `[data-nav-item]` / `[data-panel-nav-item]` to find links, and look for `router-link-active` to set the initial active position.
 
 ## Accessibility
 
-- Root `<nav>` has `aria-label="Site navigation"`.
-- Burger button uses `aria-expanded` (string `"true"/"false"`) and `aria-controls="site-nav-panel"`.
+- Root `<nav>` has `aria-label` from the `ariaLabel` prop (default `"Site navigation"`).
+- Burger button text comes from `openMenuLabel`/`closeMenuLabel`, with `aria-expanded` (string `"true"/"false"`) and `aria-controls` pointing at the panel's per-instance id (was a fixed `site-nav-panel`, which collided when two navs were on one page; fixed 2026-09-27).
 - Backdrop and indicator `<li>` elements are `aria-hidden="true"`.
 - Panel div is `inert` when closed.
 
 ## Related files
 
-- Type: `app/types/components/navigation-horizontal.d.ts`
+- Type: `app/types/components/nav-item.d.ts`
 - Tests: `app/components/02.molecules/navigation/site-navigation/tests/SiteNavigation.spec.ts`
 - Story: `app/components/02.molecules/navigation/site-navigation/stories/SiteNavigation.stories.ts`

package/.claude/skills/components/slider-gallery.md

@@ -0,0 +1,88 @@
+# SliderGallery
+
+## Overview
+
+`SliderGallery` (`03.organisms/image-galleries/slider-gallery`) is a full-screen image carousel:
+a large slide with staggered text, a thumbnail strip that animates into place, prev/next arrows, a
+progress bar, and optional auto-advance. It's `position: absolute; inset: 0` at `100svh × 100vw`,
+so place it inside a positioned container sized for it (usually a full-viewport hero).
+
+> **Changed 2026-09-28:** every inner class is now `slider-gallery-*` (was bare `.list`, `.item`,
+> `.content`, `.title`, `.thumbnail`, `.arrows`, `.time` and so on, which collided with consumer CSS
+> since the component renders inline). State classes are `.is-next`/`.is-prev`/`.is-prepended`/`.is-loaded`.
+> The arrows lost their fixed `id="prev"`/`id="next"`. The dead "See more" `<button>` is now a link,
+> rendered only for slides with an `href`. Auto-advance pauses on hover/focus and is off under
+> reduced motion. Keyframes are prefixed `slider-gallery-*`.
+
+## Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `v-model:gallery-data` | `IGalleryData[]` | required | Slides (see type below) |
+| `autoRun` | `boolean` | `true` | Auto-advance. Paused while hovered or focused; never runs under `prefers-reduced-motion: reduce` |
+| `autoRunInterval` | `number` | `7000` | ms between auto-advances |
+| `animationDuration` | `number` | `3000` | ms a transition locks the controls (also drives the progress bar) |
+| `ariaLabel` | `string` | `"Image gallery"` | Carousel region label |
+| `loadingText` | `string` | `"Loading gallery..."` | Loading-state copy |
+| `seeMoreText` | `string` | `"SEE MORE"` | Link text for slides with an `href` |
+| `prevAriaLabel` / `nextAriaLabel` | `string` | `"Previous image"` / `"Next image"` | Arrow button labels |
+| `prevIcon` / `nextIcon` | `string` | `ic:outline-keyboard-arrow-left/right` | Arrow icons |
+| `textScrim` | `boolean` | `true` | Fades in a gradient behind the active slide's text (slides with no stylist, title, category, description or href get none): dark behind `textBrightness: "light"` slides, light behind `"dark"` ones. Adds `.has-text-scrim` to the root. Styled by `--slider-gallery-text-light-scrim` / `--slider-gallery-text-dark-scrim` |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Classes on the root. Reactive |
+
+All copy props are there for localisation: pass translated strings.
+
+## IGalleryData
+
+```ts
+import type { IGalleryData } from "srcdev-nuxt-components";
+
+interface IGalleryData {
+  src: string;
+  alt: string;
+  stylist?: string;      // small caps line above the title
+  title?: string;
+  category?: string;     // second large line
+  description?: string;
+  thumbnail?: { title: string; description: string };
+  textBrightness: "light" | "dark"; // text colour over this image
+  href?: string;         // renders a see-more link; omitted = no link
+}
+```
+
+## Accessibility
+
+- Root is `role="region"` + `aria-roledescription="carousel"` + `aria-label`.
+- Arrow buttons have labels; ArrowLeft/ArrowRight work while focus is inside the gallery.
+- The thumbnail strip is decorative duplicate content: `aria-hidden`, thumbnail images have empty `alt`.
+- Loading block is `role="status"`; the progress bar is `aria-hidden`.
+- Auto-advance meets WCAG 2.2.2 via pause-on-hover/focus, and is disabled under reduced motion (animations also collapse to near-instant there).
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import type { IGalleryData } from "srcdev-nuxt-components";
+const slides = ref<IGalleryData[]>([
+  { src: "/images/work-1.jpg", alt: "Balayage on long curls", title: "Balayage", textBrightness: "light", href: "/work/balayage" },
+]);
+</script>
+
+<template>
+  <div class="hero" style="position: relative; height: 100svh;">
+    <SliderGallery v-model:gallery-data="slides" aria-label="Recent work" />
+  </div>
+</template>
+```
+
+## Styling
+
+Public tokens (`--slider-gallery-*`) cover height, z-index, accent (spinner and progress), text
+colours, thumbnail size/border/radius/overlay, arrow row position (base, tablet, desktop), arrow size, colours, border, outline (resting, hover and focus) and CTA colours. Full reference:
+`app/components/03.organisms/image-galleries/slider-gallery/CONSUMER-STYLING.md`.
+
+## Notes
+
+- Navigation moves real DOM nodes (append/prepend) rather than re-rendering, so don't key other
+  logic off the rendered order of `.slider-gallery-item`.
+- `z-index` defaults to `9999` (`--slider-gallery-z-index`) because it's a full-screen takeover.

package/.claude/skills/components/social-icons-list.md

@@ -12,6 +12,7 @@
 |------|------|---------|-------|
 | `items` | `ISocialIcon[]` | — | **Required.** Array of social network items. |
 | `label` | `string` | `"Social media profiles"` | `aria-label` applied to the `<ul>` element. |
+| `linkLabelTemplate` | `string` | `"{network} profile (opens in a new tab)"` | `aria-label` for each link; `{network}` is replaced with the item's `networkName`. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the root `<ul>`. |
 
 ---
@@ -20,7 +21,8 @@
 
 ```ts
 interface ISocialIcon {
-  networkName: string; // Used as aria-label: "{networkName} profile"
+  networkName: string; // Fills {network} in the list's linkLabelTemplate
+  label?: string;      // Optional per-item aria-label, overrides the template
   iconName: string;    // Iconify icon name, e.g. "logos:instagram-icon"
   baseHref: string;    // Base URL including trailing slash, e.g. "https://www.instagram.com/"
   profileId: string;   // Profile identifier appended to baseHref
@@ -84,8 +86,12 @@ import type { ISocialIcon } from "srcdev-nuxt-components";
 
 | Property | Default | Notes |
 |----------|---------|-------|
-| `--theme-social-icon-size` | `2.4rem` | Width and height of each icon |
-| `--theme-social-icon-gap` | `1.2rem` | Gap between icons in the flex row |
+| `--social-icons-list-icon-size` | `2.4rem` | Icon size (applied as `font-size`) |
+| `--social-icons-list-gap` | `1.2rem` | Gap between icons in the flex row |
+| `--social-icons-list-hover-scale` | `1.15` | Hover/focus scale (none under reduced motion) |
+| `--social-icons-list-hover-opacity` | `0.85` | Hover/focus opacity |
+
+> Renamed 2026-09-28 from `--theme-social-icon-size` / `--theme-social-icon-gap`. Full reference: `CONSUMER-STYLING.md` in the component folder.
 
 > **Note:** Iconify's `logos:*` styles are injected outside any CSS `@layer`, which means they override layered component styles. Icon sizing is applied via an inline `style` attribute on the `<Icon>` element so it takes precedence.
 
@@ -108,8 +114,8 @@ Offer this scaffold when placing the component in a consuming page or section. T
    ─────────────────────────────────────────────────────────────────── */
 .my-page-or-section {
   .social-icons-list {
-    /* --theme-social-icon-size: 3.2rem; */
-    /* --theme-social-icon-gap: 1.6rem; */
+    /* --social-icons-list-icon-size: 3.2rem; */
+    /* --social-icons-list-gap: 1.6rem; */
     /* margin-block-start: 1.6rem; */
 
     .social-icon-link {
@@ -130,6 +136,6 @@ need to target a specific instance. See `component-local-style-override.md` for
 ## Notes
 
 - All links open in a new tab with `rel="noopener noreferrer"`.
-- Each link carries `aria-label="{networkName} profile"` for screen reader accessibility.
+- Each link's `aria-label` comes from `linkLabelTemplate` (default `"{network} profile (opens in a new tab)"`, `{network}` = `networkName`), or the item's own `label`. Pass a translated template for other languages. The icon is `aria-hidden`.
 - The `logos:*` Iconify collection requires `@iconify-json/logos` to be installed in the consumer app. Without it, icons will fall back to a CDN fetch (causing FOUC). See [icon-sets.md](../icon-sets.md).
 - Auto-imported in Nuxt — no manual import needed.

package/.claude/skills/components/tab-navigation.md

@@ -245,7 +245,7 @@ SSR and the very first client paint always render the **full, uncollapsed** `<ul
 swap is what shrinks the header and shifts everything below it.
 
 Confirmed via `PerformanceObserver({type: "layout-shift"})` plus DOM `MutationObserver` tracing in a
-consuming app (`luxury-locs-by-natasha-nuxt3`): the class mutation on `.tab-navigation` (adding
+consuming app: the class mutation on `.tab-navigation` (adding
 `is-loaded is-animated`) lines up exactly with `.main-content`'s bounding-rect top moving by the
 header's full height delta, at a variable point (roughly 100ms–800ms after first paint depending on
 hydration timing) after first paint.

package/.claude/skills/components/text-block.md

@@ -0,0 +1,68 @@
+---
+name: TextBlock
+description: TextBlock vertical-rhythm text wrapper — tag prop, fluid block padding tokens, heading-id slot prop for section/article aria-labelledby, styleClassPassthrough
+type: reference
+---
+
+# TextBlock
+
+## Overview
+
+`TextBlock` wraps a block of text (typically a page lead: `EyebrowText` + `HeroText`/`HeaderBlock`
++ intro copy) and gives it consistent fluid vertical padding. It has no layout of its own; put it
+inside a `PageRow` for horizontal placement.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `"div" \| "section" \| "article" \| "main"` | `"div"` | Root element. `section`/`article` get `aria-labelledby` (see below); `main` deliberately does not. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes on the root. Reactive: changing the prop swaps the classes. |
+
+## Slots
+
+| Slot | Slot props | Description |
+|------|-----------|-------------|
+| `default` | `{ headingId: string }` | Content. Bind `headingId` to your heading's `id` when `tag` is `section`/`article`. |
+
+## Basic usage
+
+```vue
+<PageRow tag="div" variant="content">
+  <TextBlock :style-class-passthrough="['page-lead']">
+    <EyebrowText text-content="Pricing" font-size="large" />
+    <HeroText … />
+  </TextBlock>
+</PageRow>
+```
+
+## As a labelled landmark
+
+With `tag="section"` or `tag="article"`, the root gets `aria-labelledby` from `useAriaLabelledById`.
+Bind the `heading-id` slot prop to a real heading, or the landmark has no accessible name (a
+dev-mode `console.warn` flags this):
+
+```vue
+<TextBlock tag="section" v-slot="{ headingId }">
+  <HeaderBlock :id="headingId" :tag-level="2" :class-level="2">Our services</HeaderBlock>
+  <p>…</p>
+</TextBlock>
+```
+
+## CSS tokens
+
+| Token | Default |
+|-------|---------|
+| `--text-block-padding-block-start` | `var(--fluid-space-48-96)` |
+| `--text-block-padding-block-end` | `var(--fluid-space-48-96)` |
+
+See [CONSUMER-STYLING.md](../../../app/components/01.atoms/text-block/CONSUMER-STYLING.md).
+
+## History
+
+- **Migrated 2026-09-25** (0/5 → 5/5): padding moved from hardcoded `--fluid-space-48-96` to the two
+  public tokens above (same defaults, no visual change); `section`/`article` now get
+  `aria-labelledby` plus the `heading-id` slot prop (previously an unnamed landmark);
+  `styleClassPassthrough` is now reactive to prop changes. Some consumer apps
+  redeclare `.text-block { padding-block-*: var(--fluid-space-48-96) }` in their
+  own pages; that duplicates the default and can be deleted.