srcdev-nuxt-components 9.6.4 → 9.6.6

package/.claude/rules/consumer/a11y-no-focus-steal.md

@@ -0,0 +1,14 @@
+---
+paths:
+  - "app/**/*.vue"
+---
+
+# Status messages never take focus
+
+Never `.focus()` a toast, banner or other status message when it appears. Announce it with `role`
++ `aria-live`, keep it reachable with `tabindex="0"`, and listen for Escape on the document while
+it's shown (skipping `event.defaultPrevented`).
+
+Why: WCAG 4.1.3 says status messages are announced without receiving focus, and moving focus
+interrupts typing. Chrome also counts script focus before any pointer input as `:focus-visible`,
+so `:focus:not(:focus-visible)` can't hide the ring (`DisplayToast`, 2026-10-16).

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

@@ -130,7 +130,10 @@ The ledger can't see items 6c, 9, 10, 11 and 14, so check those by hand.
       number of items
     - emoji (including at the start of anything that takes initials or first letters), HTML-like
       text (must render as text), right-to-left text
-    - out-of-range or odd numbers (0, negative, above the maximum, fractional, very large)
+    - out-of-range or odd numbers (0, negative, above the maximum, fractional, very large). A
+      count prop used as a `v-for` range (`itemCount`) needs flooring and clamping in a
+      `computed()`: Vue renders nothing for a fractional or negative range and only warns in dev
+      (`StepperList`, 2026-10-15)
     - broken image or link URLs
     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
@@ -175,14 +178,20 @@ The ledger can't see items 6c, 9, 10, 11 and 14, so check those by hand.
    stories/tests up one level, fix relative imports); `pathPrefix: false` keeps the auto-import
    names unchanged. All existing `variants/` folders were flattened 2026-09-25.
 8. **VS Code snippet** — create or update `.vscode/srcdev-component-{family}.code-snippets`,
-   covering the control and its Field wrapper in one file.
+   covering the control and its Field wrapper in one file. For a teleported component, a CSS
+   override scaffold must not nest its selector under a page class: it never matches (the
+   `DisplayToast` snippet did, fixed 2026-10-16).
 9. **Accessibility** — check for gaps beyond what already-passing tests would catch:
    - Interactive controls (buttons, toggles, custom form-like widgets) have an accessible name —
      visible text, `aria-label`, or `aria-labelledby`.
+   - A `<ul>`/`<ol>` styled with `list-style: none` gets `role="list"`, or Safari/VoiceOver stops
+     announcing it as a list (`StepperList`, 2026-10-15).
    - Keyboard behaviour matches what's actually implemented — no keydown case that only calls
      `event.preventDefault()` with a comment like "could add this later", and no screen-reader
      copy (visible or `sr-only`) that describes an interaction the component doesn't actually
      perform. Cross-check every claim in the copy against the handler that's supposed to back it.
+   - 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.
    - Live-updating or auto-advancing content (carousels, marquees, auto-dismissing toasts) has a
      way to pause it, per WCAG 2.2.2 — a visible control, or pause-on-hover/focus at minimum.
@@ -253,6 +262,9 @@ The ledger can't see items 6c, 9, 10, 11 and 14, so check those by hand.
       the edits in private memory. Note that an inline-size container can't size itself from its
       content: say so in `CONSUMER-STYLING.md` (`ProfileSection`).
     - Grid tracks that hold text are `minmax(0, …)` so an unbroken string can't widen the grid.
+    - Layout measured in script (connector lines, indicators) re-measures when any measured item
+      resizes or changes class, not only when the container resizes (`measured-layout-observers.md`,
+      pitfall #28).
     - Action buttons are `InputButton` (`variant="inline"` when the wrapper styles them), not a raw
       `<button>` (`component-inline-button.md`, `component-inline-action-button.md`). The ledger
       doesn't check this, which is how `InputCopy` scored 5/5 with one (fixed 2026-10-15).

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

@@ -111,6 +111,7 @@ const toastVisible = ref(false)
 
 - `onBeforeRouteLeave` dismisses the toast on navigation. This emits a Vue Router warning in Vitest (no active route record) — harmless.
 - `returnFocusTo` accepts an `HTMLElement` or a component instance with `$el`.
+- Neither `DisplayToast` nor `DisplayToastProvider` moves focus when a toast appears (changed 2026-10-16; both used to `.focus()` the toast). Toasts are status messages announced through `role` + `aria-live` (WCAG 4.1.3), and stealing focus interrupted typing and drew a focus ring in Chrome when the toast opened before any pointer input. Keyboard users can still Tab to it (`tabindex="0"`), and Escape is heard on the document while a toast is shown (ignored if another handler called `preventDefault()`).
 - The toast uses `<Teleport to="body">`. In tests, query `document.querySelector(".display-toast")` not `wrapper.find()`.
 - Position, alignment and state are `data-position`, `data-alignment` (`full-width` when `fullWidth`) and `data-state="show|hide"`, not classes (changed 2026-10-08: the old bare `.top`/`.hide`/... classes could collide with a consumer's utility classes, since the toast is teleported into `<body>`).
 - In tests, unmount every toast in `afterEach` before clearing `document.body`: a leftover instance's pending dismiss timer otherwise re-renders into the removed container (`insertBefore` of null) during a later test's timer advance.
@@ -119,8 +120,8 @@ const toastVisible = ref(false)
 
 Auto-dismiss pauses while hovered, or while keyboard focus is on or inside the toast, and resumes with
 the remaining time (`createPausableTimeout` in `app/utils/pausableTimeout.ts`, plus
-`focusPausesAutoDismiss`). The toast's own programmatic focus only pauses it when the root matches
-`:focus-visible` (keyboard modality), so mouse users still get auto-dismiss. `data-paused` freezes the
+`focusPausesAutoDismiss`). Focus on the toast root only pauses it when the root matches
+`:focus-visible` (keyboard modality), so a mouse click on it doesn't stop auto-dismiss. `data-paused` freezes the
 progress bar via `animation-play-state`. In jsdom `:focus-visible` matches any focus, so tests that
 depend on modality spy on `Element.prototype.matches` (see `DisplayToast.spec.ts`).
 
@@ -244,6 +245,8 @@ The SVG border shape matches the standard toast exactly (8px left radius, 4px ri
 
 The inner content layout is handled by the shared `AlertContentInner` molecule — both variants reuse it. `AlertMaskedContent` sets `--alert-content-inner-background: transparent` so the glass effect shows through.
 
+**Contrast caveat:** a toast is fixed to the viewport, so whatever scrolls behind it (body copy, busy photos) shows through the fill. 80% holds up over most backdrops; lowering `--alert-masked-content-background` can make the message hard to read, and the 1px accent border can disappear over a backdrop of similar hue. Set that token on `.display-toast` (or a `styleClassPassthrough` class) or `.display-toast-provider-item`: both teleport to `<body>`, so a page-level ancestor never reaches them. Prefer the opaque variant for error/warning toasts. Storybook's "Masked: Low Contrast Risk" story demos the failure.
+
 ### Provider notes
 
 - `useToastQueue` state persists across route changes — no `onBeforeRouteLeave` cleanup needed.
@@ -252,4 +255,4 @@ The inner content layout is handled by the shared `AlertContentInner` molecule
 - Every mounted provider reacts to the shared `useToastQueue` state, so tests must unmount providers in `afterEach`; otherwise an earlier test's provider runs its own timer for a new toast and dismisses it.
 - Each item pauses independently (hover / keyboard focus, same rule as the standalone toast), tracked per toast id.
 - The progress bar (`.display-toast-provider-progress`) is only rendered when `autoDismiss: true`.
-- Dismissal can be triggered by: close button click, Escape key (when the toast item has focus), `dismiss(id)`, auto-dismiss timer, or `clear()`.
+- Dismissal can be triggered by: close button click, Escape key (dismisses that item when focus is inside it, otherwise the newest visible item), `dismiss(id)`, auto-dismiss timer, or `clear()`.

package/.claude/skills/components/progress-tracker.md

@@ -0,0 +1,140 @@
+# ProgressTracker Component
+
+## Overview
+
+`ProgressTracker` (`app/components/02.molecules/progress-tracker/`) is a presentational progress
+track for a multi-step flow: a header with "Step X of Y" and a progress bar, then the steps as a
+`StepperList`. Steps before the `v-model` index are done (filled indicator with a tick), the model's
+step is current (ringed number, content in a focus card) and later steps are upcoming (outlined
+number, muted text). The current step's `#step-{n}` slot is where a parent puts a form or actions,
+so it also works as an accordion-style n-step wizard. The parent owns all state; the component has
+no events and never changes the model. Styling tokens:
+`app/components/02.molecules/progress-tracker/CONSUMER-STYLING.md`.
+
+---
+
+## Props reference
+
+> **Hyphenation rule**: write camelCase props hyphenated in templates: `:style-class-passthrough`.
+
+| Prop (template form) | Type | Default | Notes |
+|---|---|---|---|
+| `v-model` | `number` | (required) | 0-based index of the current step. `steps.length` means every step is done. Floored, and clamped to `0`–`steps.length`. |
+| `:steps` | `ProgressTrackerStep[]` | (required) | `{ title: string; body?: string }`, exported from `~/types/components`. An empty array renders nothing. |
+| `heading-tag` | `"h2" \| "h3" \| "h4" \| "h5" \| "h6"` | `"h3"` | Tag for each step title. |
+| `step-label` | `string` | `"Step {current} of {total}"` | Header text and the bar's `aria-valuetext`; `{current}` is 1-based. |
+| `complete-label` | `string` | `"All steps complete"` | Header text once every step is done. |
+| `done-label` | `string` | `"Completed"` | Screen-reader text appended to each done title (", Completed"). |
+| `done-icon` | `string` | `"lucide:check"` | Iconify name for the tick. |
+| `:focus-on-change` | `boolean` | `true` | Move focus when the model changes (see Behaviour). |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Classes on the root `div`. |
+
+## Slots
+
+| Slot | Props | Notes |
+|---|---|---|
+| `#step-{n}` | `{ step, index, headingId }` | Rendered **only while step `n` is current**, inside its focus card under the body. `headingId` is the step title's id, for `aria-labelledby` on a form. |
+
+---
+
+## Behaviour
+
+- One row per step, with its title and body; a step without a body has no body paragraph.
+- Steps before the model are done, the model's step is current, later steps are upcoming.
+- The current title has `aria-current="step"`; done titles carry `done-label` as screen-reader
+  text; indicators are `aria-hidden`. The list is an `ol`, so position ("2 of 5") is announced too.
+- The header shows `step-label` filled in, or `complete-label` when every step is done. It's a
+  polite live region, so a change is announced.
+- The bar is `role="progressbar"` with `aria-valuemin="0"`, `aria-valuemax` = step count,
+  `aria-valuenow` = done count and `aria-valuetext` = the header label.
+- Changing the model after mount moves focus to the new current title (`tabindex="-1"`), or to the
+  header label when complete, so keyboard and screen-reader users aren't dropped when a slot's
+  focused button unmounts. Never on first render. `:focus-on-change="false"` turns it off (e.g.
+  when the parent restores saved progress after mount).
+- Done steps are plain text: there is nothing clickable in the component itself.
+- The model is clamped: negative counts as 0, above `steps.length` counts as complete, fractions
+  are floored.
+- Survives worst-case data (unbroken strings, long copy, 20+ steps, empty steps) without breaking
+  the layout; the header wraps the bar below the label when space runs out.
+- Bar and state colour transitions are off under `prefers-reduced-motion: reduce`.
+
+---
+
+## Usage
+
+### Display only
+
+```vue
+<ProgressTracker v-model="currentStep" :steps="onboardingSteps" />
+```
+
+### Wizard (parent-owned forms)
+
+```vue
+<script setup lang="ts">
+import type { ProgressTrackerStep } from "~/types/components";
+
+const currentStep = ref(0);
+const form = reactive({ name: "", email: "" });
+
+const steps = computed<ProgressTrackerStep[]>(() => [
+  { title: "Your details", body: currentStep.value > 0 ? form.name : "Tell us who you are." },
+  { title: "Contact", body: currentStep.value > 1 ? form.email : "Where can we reach you?" },
+  { title: "Review and submit" },
+]);
+</script>
+
+<template>
+  <ProgressTracker v-model="currentStep" :steps="steps">
+    <template #step-0="{ headingId }">
+      <form :aria-labelledby="headingId" @submit.prevent="currentStep++">
+        <!-- fields, then a submit InputButton labelled Continue -->
+      </form>
+    </template>
+    <template #step-1="{ headingId }">
+      <form :aria-labelledby="headingId" @submit.prevent="currentStep++">
+        <!-- fields, a Back InputButton (@click="currentStep--") and Continue -->
+      </form>
+    </template>
+    <template #step-2="{ headingId }">
+      <form :aria-labelledby="headingId" @submit.prevent="currentStep = steps.length">
+        <!-- review, Back and Submit -->
+      </form>
+    </template>
+  </ProgressTracker>
+</template>
+```
+
+Validation, saving and what "complete" means are the parent's job. Pass a summary of each completed
+step back in as its `body` so done steps show what was entered.
+
+---
+
+## Composition
+
+- Built on `StepperList` (`tag="ol"`, `indicator-alignment="top"`), filling its `indicator-{n}` and
+  `item-{n}` slots. ProgressTracker sets StepperList's `--stepper-list-*` tokens on
+  `.progress-tracker-list` from its own, so an ancestor's `--stepper-list-*` values don't reach it.
+- Connector colour per state uses `.stepper-list-item:has(.progress-tracker-indicator.is-done)`,
+  the per-step state recipe from StepperList's `CONSUMER-STYLING.md`.
+- The focus card bleeds left by `--progress-tracker-card-padding-inline` so the current step's text
+  stays aligned with the other steps; the current indicator moves down by the card's block padding
+  to stay level with its title. Clearance between the current ring and the card is
+  `gap - card-padding-inline - ring-width` (4rem - 2rem - 0.6rem = 1.4rem by default). The first
+  defaults (3.2rem gap, 2.4rem padding) left 0.2rem and the ring touched the card, so change these
+  three together.
+
+---
+
+## Stories
+
+Default, All Complete, Interactive (Mark complete), Wizard (parent-owned forms), Translated
+Labels, White Card on a Panel, Stress Test. Title: `Molecules/ProgressTracker`.
+
+---
+
+## Notes
+
+- Out of scope: clickable or back-navigable steps, a built-in complete event or validation,
+  horizontal layout, auto-advance.
+- Auto-imported in Nuxt; import the `ProgressTrackerStep` type from `~/types/components`.

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

@@ -13,6 +13,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`. |
+| `showLabel` | `boolean` | `false` | Show each item's `networkName` as visible text after the icon. Filling the `label` slot shows it too. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the root `<ul>`. |
 
 ---
@@ -26,11 +27,25 @@ interface ISocialIcon {
   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
+  brandColour?: string; // Exposed as --social-icons-list-brand-colour on the item, for recipes
 }
 ```
 
 The rendered `href` is `${baseHref}${profileId}`.
 
+---
+
+## Slots
+
+Both are scoped and receive `{ item }` (the `ISocialIcon`). Types: `SocialIconsListSlots`.
+
+| Slot | Replaces | Notes |
+|------|----------|-------|
+| `icon` | The `<Icon>` inside `.social-icons-list-icon-wrapper` | The wrapper is `aria-hidden` and keeps the size and circle tokens, so slot content (an initial, `DisplayAvatar`, an image) is decorative and sized by `--social-icons-list-icon-size`. |
+| `label` | The visible `networkName` text | Filling it shows the label without `showLabel` (e.g. name plus `@handle`). |
+
+Slot content sits inside the link: keep it non-interactive (no buttons or nested links).
+
 ### Importing the type
 
 **Within the layer** (e.g. in another layer component or composable):
@@ -57,6 +72,8 @@ import type { ISocialIcon } from "srcdev-nuxt-components";
 | YouTube | `logos:youtube-icon` | `https://www.youtube.com/@` |
 | TikTok | `logos:tiktok-icon` | `https://www.tiktok.com/@` |
 
+Mono equivalents for recipes, with brand colours: `bi:facebook` (`#1877f2`), `bi:twitter-x` (`#000000`), `bi:instagram` (`#e1306c`), `bi:youtube` (`#ff0000`), `bi:tiktok` (`#000000`).
+
 `logos:instagram-icon`, `logos:x` and other dark brand icons vanish on a dark background, and their colours can't be changed. On a dark background use a mono icon such as `mdi:instagram` (any set that draws in `currentColor`) and colour it with `--social-icons-list-icon-colour` (default `currentColor`). Installed mono Instagram icons: `mdi:instagram`, `bi:instagram`, `lucide:instagram`, `akar-icons:instagram-fill`, `radix-icons:instagram-logo`.
 
 ---
@@ -88,14 +105,21 @@ import type { ISocialIcon } from "srcdev-nuxt-components";
 
 | Property | Default | Notes |
 |----------|---------|-------|
-| `--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-icon-size` | `2.4rem` | Icon size (a `font-size` on the icon wrapper) |
+| `--social-icons-list-gap` | `1.2rem` | Gap between items |
+| `--social-icons-list-icon-colour` / `-hover` | `currentColor` | Mono icons only; `logos:` colours are fixed |
+| `--social-icons-list-link-padding` / `-border` / `-radius` / `-background` / `-background-hover` / `-shadow` / `-shadow-hover` / `-gap` | none / `0.8rem` gap | Turn links into tiles or pills |
+| `--social-icons-list-icon-wrapper-padding` / `-border` / `-radius` / `-background` | none | Circle or tile behind the icon |
+| `--social-icons-list-label-colour` / `-font-size` / `-font-weight` | `currentColor` / `--step-4` / `600` | Visible label |
 | `--social-icons-list-hover-scale` | `1.15` | Hover/focus scale (none under reduced motion) |
 | `--social-icons-list-hover-opacity` | `0.85` | Hover/focus opacity |
+| `--social-icons-list-focus-ring-colour` | `var(--theme-ring, currentColor)` | Keyboard focus outline |
+
+Full table with defaults in `CONSUMER-STYLING.md`. **Tokens that read `--social-icons-list-brand-colour` must be set on `.social-icons-list-item`**, where the brand colour is defined: a `var()` in a custom property resolves on the declaring element, so set on the list root it finds nothing. Four recipes (mono tiles with brand hover, dark dock with glow, labelled pills, overlapping stack) are in `stories/social-icons-list-recipes.css` and the `Recipe: …` stories; reuse them rather than inventing new structure.
 
-> Renamed 2026-09-28 from `--theme-social-icon-size` / `--theme-social-icon-gap`. Full reference: `CONSUMER-STYLING.md` in the component folder.
+> Renamed 2026-09-28 from `--theme-social-icon-size` / `--theme-social-icon-gap`. Inner classes renamed 2026-10-16 (`.social-icon-item`/`-link`/`.social-icon` are now `.social-icons-list-item`/`-link`/`-icon`). 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.
+The size token is a `font-size` on `.social-icons-list-icon-wrapper`, whose content box is a fixed `1em` square (`box-sizing: content-box`, padding added around it). The default icon fills it, any `icon` slot content is centred in it, and an icon name that doesn't resolve still leaves a visible, focusable target. With uniform `--social-icons-list-icon-wrapper-padding` and a `50%` radius it's always a circle; slot content bigger than `1em` overflows the square, so size it to fit (e.g. `font-size: 0.8em` for a letter).
 
 ---
 
@@ -120,7 +144,7 @@ Offer this scaffold when placing the component in a consuming page or section. T
     /* --social-icons-list-gap: 1.6rem; */
     /* margin-block-start: 1.6rem; */
 
-    .social-icon-link {
+    .social-icons-list-link {
       /* border-radius: 0.4rem; */
       /* padding: 0.4rem; */
       /* outline: 1px solid transparent; */
@@ -138,6 +162,9 @@ 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"`.
+- An item is skipped (with a dev-mode `console.warn`) when its `baseHref + profileId` isn't `http:`/`https:`, `mailto:`, `tel:` or a site-relative `/path`: `items` often comes from a CMS, and a `javascript:` href would otherwise render as a working link. `mailto:` and `tel:` items are fine, so email and phone can sit in the same row.
+- Keys are `index + networkName`, so two accounts on the same network (two Instagram profiles) both render.
+- The `<ul>` has `role="list"`: with `list-style: none`, Safari/VoiceOver stops announcing it as a list otherwise.
 - 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/stepper-list.md

@@ -20,6 +20,7 @@
 | … | … |
 
 **Rules:**
+
 - Slots are always **zero-indexed**: first item = `item-0`, last item = `item-{itemCount - 1}`.
 - `item-{n}` slots are required if you want content in each row.
 - `indicator-{n}` slots are **optional**. When omitted, a CSS counter bubble is rendered automatically. When provided, the custom content replaces the counter entirely — the CSS counter is hidden for that item only.
@@ -32,7 +33,7 @@
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `itemCount` | `number` | — | **Required.** Controls how many `<li>` elements are rendered and which slots exist. |
+| `itemCount` | `number` | — | **Required.** Controls how many `<li>` elements are rendered and which slots exist. Floored to a whole number; negative or `NaN` renders no rows. |
 | `tag` | `"ul" \| "ol"` | `"ul"` | Use `"ol"` for sequentially meaningful content (recipes, instructions). |
 | `indicatorAlignment` | `"top" \| "center"` | `"top"` | Vertical alignment of the indicator relative to each item's content. `"center"` suits single-line items; `"top"` suits multi-line content. |
 | `indicatorVariant` | `"disc" \| "circle" \| "square"` | `"disc"` | Visual style of the auto-generated counter bubble. |
@@ -160,12 +161,14 @@ for full examples (global theming, page-scoped, and per-instance overrides).
 | `--stepper-list-counter-font-size` | `1.4rem` | Counter number font size |
 | `--stepper-list-counter-font-weight` | `600` | Counter number font weight |
 | `--stepper-list-connector-width` | `0.2rem` | Connector line thickness |
+| `--stepper-list-connector-gap` | `0` | Space between each end of the connector line and its indicators |
 
 ### Colours
 
 | Token | Default | Controls |
 |---|---|---|
 | `--stepper-list-connector-color` | `currentColor` | Connector line colour |
+| `--stepper-list-connector-image` | `none` | Image over the connector colour, e.g. a `repeating-linear-gradient()` for a dashed line |
 | `--stepper-list-icon-color` | `currentColor` | Icon colour for custom `indicator-icon` elements |
 
 ### Per-variant tokens
@@ -190,10 +193,10 @@ for full examples (global theming, page-scoped, and per-instance overrides).
 ## Connector behaviour
 
 - Connectors are drawn as `::after` pseudo-elements on each `<li>` except the last.
-- JS (`ResizeObserver`) measures the bottom of each indicator and the top of the next to set `--_connector-top` and `--_connector-height` precisely, keeping the line flush between bubbles regardless of content height.
+- JS (`ResizeObserver`) measures the bottom of each indicator and the top of the next to set `--_connector-top` and `--_connector-height` precisely, keeping the line flush between bubbles regardless of content height. It also sets `--_connector-left` to the indicator's measured centre, so the line stays centred under a custom indicator wider than the counter bubble (before JS runs it falls back to half of `--_counter-size`).
 - Before JS runs (SSR / initial paint), CSS fallback values approximate the correct position for `indicatorAlignment="top"`.
 - If `connected="false"`, no connectors are rendered and JS measurement is skipped.
-- Connectors recalculate automatically when `itemCount`, `connected`, or `indicatorAlignment` props change.
+- Connectors recalculate when `itemCount`, `connected` or `indicatorAlignment` change, when the list or any `<li>` resizes (a `ResizeObserver` on the list and every item), and when a `class` attribute or child nodes change anywhere inside the list (a `MutationObserver`). The last two cover a consumer restyling a step without the list changing size, e.g. ProgressTracker moving its focus card from one step to the next. Inline `style` changes are not watched, since the connector values themselves are written there.
 
 ---
 
@@ -222,6 +225,7 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
     /* --stepper-list-counter-font-size: 1.4rem; */
     /* --stepper-list-counter-font-weight: 600; */
     /* --stepper-list-connector-width: 0.2rem; */
+    /* --stepper-list-connector-gap: 0.6rem; */
 
     /* Counter bubble — disc variant */
     /* --stepper-list-counter-disc-background: var(--brand-primary); */
@@ -246,6 +250,7 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
 
     /* Connector line */
     /* --stepper-list-connector-color: var(--brand-primary); */
+    /* --stepper-list-connector-image: repeating-linear-gradient(to bottom, currentColor 0 0.4rem, transparent 0.4rem 0.8rem); */
   }
 }
 </style>
@@ -258,4 +263,6 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
 - Always keep `itemCount` in sync with the number of `#item-*` slots you provide — mismatches will render empty `<li>` rows.
 - Slot names are **zero-indexed** — `#item-0` not `#item-1`.
 - The `indicator-icon` class is defined inside the component CSS and sizes the SVG to `var(--_counter-size)` (driven by `indicatorSize` or `--stepper-list-counter-size`). Always add it to custom SVGs.
+- Markup: root `<ul>`/`<ol>` with `role="list"` (Safari drops list semantics under `list-style: none`), each row `li.stepper-list-item`, content in `.stepper-list-content`. The content column is `minmax(0, 1fr)` with `overflow-wrap: anywhere`, so long unbroken strings wrap.
+- Used by `ServiceDetail` for its process steps (circle variant, `tag="ol"`, item count from CMS data) and by `ProgressTracker`, which fills the indicator and item slots with done/current/upcoming states (skill `progress-tracker.md`).
 - Auto-imported in Nuxt — no manual import needed.

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

@@ -145,6 +145,10 @@ and the trailing edge catches up: the same stretch effect as before, symmetric b
 settle timer. CSS retargets each edge from its current position, so a quick second move can't
 pull an edge backwards. Hover and active have separate duration/delay variables.
 
+`--tabs-hover-indicator-stretch` (default `1`) multiplies the hover pair's two edge delays in CSS,
+so `0` turns the hover stretch into a plain slide (both edges move together over the same
+duration). The active indicator and underline always stretch.
+
 This replaced a `translate` + `scale` model (a bar-wide box translated to the tab's left and
 scaled to its width, plus a timeout to settle after a stretch, and one shared
 `--_transition-duration`). Rightward moves animated both properties together in the settle step,

package/.claude/skills/css-dynamic-border-radius.md

@@ -0,0 +1,114 @@
+# CSS Dynamic Border Radius
+
+## Overview
+
+`.dynamic-border-radius` (global utility, `app/assets/styles/setup/06.utility-classes/_dynamic-border-radius.css`,
+`utilities` layer) rounds an element's corners while it's narrower than its container, and squares them once it
+spans the full container width. A capped-width image reads as a rounded card on wide screens and as an edge-to-edge
+band on narrow ones, with no media query and no JS.
+
+```css
+.dynamic-border-radius {
+  border-radius: clamp(0px, (100cqi - 100%) * 1e5, var(--dynamic-border-radius, 5rem));
+}
+
+.dynamic-border-radius-transition {
+  max-inline-size: var(--dynamic-border-radius-max-width, 100%);
+  border-radius: clamp(0px, (100cqi - var(--dynamic-border-radius-max-width, 100%)) * 1e5, var(--dynamic-border-radius, 5rem));
+
+  @media (prefers-reduced-motion: no-preference) {
+    transition: border-radius var(--dynamic-border-radius-duration, 300ms) var(--dynamic-border-radius-easing, ease-out);
+  }
+}
+```
+
+It's a utility class, not a component: it works on any element (`<img>`, `NuxtImg`, `<video>`, a card), and the
+container it measures is an ancestor the element doesn't own.
+
+Storybook: **Foundations/Utilities/Dynamic Border Radius**.
+
+## Token
+
+| Token | Default | Controls |
+|---|---|---|
+| `--dynamic-border-radius` | `5rem` | Radius while the element is narrower than its container. Set it on the element or any ancestor. |
+| `--dynamic-border-radius-max-width` | `100%` | `.dynamic-border-radius-transition` only: the element's max width, as a length. Sets its `max-inline-size` and is what the container is compared against. |
+| `--dynamic-border-radius-duration` | `300ms` | Transition duration, with `.dynamic-border-radius-transition`. |
+| `--dynamic-border-radius-easing` | `ease-out` | Transition easing, with `.dynamic-border-radius-transition`. |
+
+## Usage
+
+```html
+<div class="hero-media">
+  <img class="dynamic-border-radius" src="/images/hero.jpg" alt="" width="1600" height="900">
+</div>
+```
+
+```css
+.hero-media {
+  container-type: inline-size;
+
+  img {
+    display: block;
+    inline-size: 100%;
+    max-inline-size: 50rem;
+    margin-inline: auto;
+  }
+}
+```
+
+## How it works
+
+`100cqi` is the container's inline size; inside `border-radius`, `100%` is the element's own width. While the element
+is narrower, the difference is positive, the `* 1e5` blows it up past the max, and `clamp()` caps it at the token.
+When the element fills the container, the difference is 0 and so is the radius.
+
+## Optional transition
+
+Use `.dynamic-border-radius-transition` instead of the base class to ease the switch, and give it the element's max
+width as a token (it sets `max-inline-size` from it, so don't also set `max-inline-size` yourself):
+
+```html
+<img class="dynamic-border-radius-transition" style="--dynamic-border-radius-max-width: 50rem" src="/images/hero.jpg" alt="" width="1600" height="900">
+```
+
+- **Why a different formula.** Don't just add a `transition` to the base class: it flickers while the container
+  shrinks. A transition starts from the old *computed* value, where `100cqi` is already pixels (the previous
+  frame's container width) but `100%` stays unresolved until layout, so it's re-evaluated against this frame's,
+  smaller, element width. Previous container minus current element is positive, `* 1e5` clamps it to the full
+  radius, and every resize frame restarts a transition from there. Comparing against a length token instead makes
+  the computed value a plain length (full radius or 0): nothing changes while you resize either side of the
+  threshold, and crossing it starts exactly one transition.
+- **Without the token** it falls back to `100%`: the base formula, so it works but flickers on resize.
+- **The token must match the element's real max width**, as a single length (`50rem`, not `min(50rem, 90%)`). If
+  something else caps the element narrower (a consumer `max-inline-size`, a small intrinsic image size), the radius
+  stays at 0 even though the element doesn't fill the container.
+- It sets `transition`, which replaces any transition already on the element (the utilities layer beats
+  `@layer components`). If the element needs its own transition too, add `border-radius` to your own combined
+  `transition` instead (`transform 200ms, border-radius 300ms ease-out`).
+- It only animates when the **container** resizes. If only the token changes (at a breakpoint), the value changes
+  too, so that animates as well; an image loading doesn't affect it.
+- The transition is skipped under `prefers-reduced-motion: reduce`; the radius still switches.
+
+## Caveats
+
+1. **It needs a `container-type: inline-size` ancestor.** Without one, `cqi` falls back to the viewport, so the
+   radius only drops when the element is as wide as the screen. It doesn't error; it just looks wrong. Put the
+   container on the element's direct layout wrapper: if the nearest container is wider than the element's real
+   column, the element never "fills" it.
+2. **It works partly by luck. Don't split it into horizontal and vertical radii.** The single value sets both radii, and
+   the vertical one resolves `100%` against the element's *height*, so at full width it's usually still at the max.
+   The corner is square anyway, because CSS draws a square corner when either radius is 0. A `border-radius: X / Y`
+   rewrite, or a percentage max, can break this.
+3. **The element must actually reach full width.** Give an image `display: block; inline-size: 100%` plus a
+   `max-inline-size`. With only a max, an image whose intrinsic width is smaller than the container (a `w=400` CDN
+   URL, for example) never fills it, so the radius never drops.
+4. **Subpixel widths.** A 500.4px container around a 500px element keeps the radius on. That's correct (it isn't
+   full width), but it can look like the switch is late at fractional zoom levels.
+5. **Support:** container query units and `clamp()` with mixed units work in Safari 16, the layer's support
+   baseline.
+
+## Snippet
+
+`.vscode/srcdev-utility-dynamic-border-radius.code-snippets`: `srcdev-dynamic-border-radius` (markup with the
+container wrapper, transition class as an optional placeholder) and `srcdev-dynamic-border-radius-css` (the wrapper and image rules).

package/.claude/skills/index.md

@@ -51,6 +51,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── css-nesting-conventions.md                — native CSS nesting rules: why &__child Sass BEM concatenation silently breaks, correct patterns
 ├── css-grid-max-width-gutters.md             — cap a centre grid column width by growing gutters, with start/center alignment variants
 ├── css-animation-utilities.md                — scroll-driven animation utility classes: scroller-x (carousel), entry-zoom-reveal, entry-slide-in, entry-exit-blur, auto-rotate
+├── css-dynamic-border-radius.md              — .dynamic-border-radius utility: rounded until the element fills its container-type ancestor, then square; --dynamic-border-radius token, opt-in -transition class, container/full-width caveats
 ├── component-aria-landmark.md        — useAriaLabelledById composable: aria-labelledby for section/article/aside tags (not main), consumer-bound vs self-bound pattern, built-in broken-reference console warning
 ├── component-export-types.md         — move inline component types to app/types/components/ barrel for consumer imports
 ├── component-inline-action-button.md — InputButton variant="inline" pattern for buttons embedded in custom input wrappers
@@ -99,7 +100,8 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── skip-links.md                — SkipLinks: focus-revealed accessibility skip-nav, links (SkipLink[]) data-driven, homeLink slot, CSS token API
     ├── tabbed-content.md            — TabbedContent (was TabsCore): tablist + panels from indexed slots (itemCount), arrow-key nav, moving hover/active/underline indicators, CSS token API
     ├── contact-section.md      — ContactSection props (stepperIndicatorSize pass-through), 3-item info+form layout, slot API
-    ├── stepper-list.md         — StepperList dynamic slots (item-{n}/indicator-{n}), props, connector behaviour
+    ├── stepper-list.md         — StepperList dynamic slots (item-{n}/indicator-{n}), props, measured connectors (gap, dashed image tokens), per-step state recipe
+    ├── progress-tracker.md     — ProgressTracker: steps (ProgressTrackerStep[]) + v-model current index over StepperList, header label + progressbar, current-step #step-{n} slot for wizard forms, focus on change, CSS token API
     ├── expanding-panel.md      — ExpandingPanel v-model, forceOpened, contentIsOnTop overlay mode, slots (summary/icon/content), ARIA wiring, CSS token API
     ├── content-docs.md         — ContentDocs docs-page shell: prop-driven docsNav/docsPageNav (not slots), DocsNavItem icons, container-width breakpoint behaviour, shared/per-side CSS token API
     ├── glass-panel.md          — GlassPanel: frosted-glass container, light-only token defaults in-component (light-dark() block removed from _default.css, no built-in dark glass), highlight behind content, section/article labelled via headingId slot prop, CSS token API
@@ -114,7 +116,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── wipe-away-vertical.md   — WipeAwayVertical: scroll-driven vertical wipe-away effect, pure-CSS grid overlay (no JS), indexed dynamic slots, sticky-centering-via-calc gotcha, CSS tokens
     ├── marquee-scroller.md     — MarqueeScroller: infinite logo/badge scroller, per-item dynamic slots (marqueeData id), hover/focus/keyboard pause, reduced-motion, CSS tokens
     ├── rotating-carousel-image.md — RotatingCarouselImage: 3D rotating image carousel, scroll-parallax tilt, focus/keyboard/hover pause, reduced-motion, CSS tokens
-    ├── social-icons-list.md    — SocialIconsList: data-driven social icon links, ISocialIcon type, logos: icon names (dark ones vanish on dark backgrounds; mono alternatives), CSS tokens incl. --social-icons-list-icon-colour
+    ├── social-icons-list.md    — SocialIconsList: data-driven social icon links, ISocialIcon type, logos: icon names (dark ones vanish on dark backgrounds; mono alternatives), showLabel + scoped icon/label slots, per-item brandColour (set brand-colour tokens on .social-icons-list-item), tile/circle/label tokens, four recipes (mono tiles, dark dock, pills, overlapping stack), unsafe hrefs skipped
     ├── display-qr-code.md      — DisplayQrCode: QR code SVG from a string value, colour/size/variant/radius props, currentColor default
     ├── capture-qr-code.md      — CaptureQrCode: live camera scanner, error state, visibility/route/KeepAlive lifecycle, media stream cleanup
     ├── decode-qr-code.md       — DecodeQrCode: file picker + drag-and-drop image decoder, shared results list, CSS override points

package/.claude/skills/storybook-add-story.md

@@ -242,6 +242,12 @@ export default meta;
 type Story = StoryObj<typeof ComponentName>; // ← still strict for individual stories
 ```
 
+When the story assigns a model arg itself (a button doing `args.modelValue = index + 1`, a wizard's
+Back/Continue), a type built from `InstanceType<typeof C>["$props"]` fails `vue-tsc` with "Cannot
+assign to 'modelValue' because it is a read-only property". Re-declare it writable:
+`Omit<InstanceType<typeof C>["$props"], "modelValue"> & { modelValue: number; ... }`
+(`ProgressTracker.stories.ts`).
+
 Strip extra args before `v-bind` using a `useStorySetup` helper in `setup()`:
 
 ```ts
@@ -315,6 +321,12 @@ the earlier nightly `@nuxtjs/storybook` didn't render Docs pages at all, so a lo
   screens, and sets `docs.story: { inline: false }`. `CookieConsentBanner` and `DisplayToast`
   follow this. A teleported component doesn't inherit a wrapper's `dir`, so wrap RTL slot copy
   in `<span dir="rtl">`.
+- The same goes for tokens: a teleported component doesn't inherit custom properties from a story
+  wrapper. To demo a token override, inject a `<style>` rule targeting the component's own root
+  class in setup (remove it in `onUnmounted`); that also keeps `var(--theme-*)` inside the value
+  resolving against the component's own `data-theme`. A backdrop meant to sit behind it (to demo
+  translucency) must be `position: fixed; inset: 0`. `DisplayToast`'s `canvas` / `maskedFill`
+  story controls follow this.
 - Opt a file out with `tags: ["!autodocs"]` only when it isn't a component reference (tooling, or
   a file with its own attached `.mdx` page, like `ColourRamps.stories.ts` with `SetupGuide.mdx`).
 

package/.vscode/srcdev-component-display-toast.code-snippets

@@ -62,16 +62,14 @@
     ]
   },
   "SRCDEV DisplayToast CSS Override": {
-    "description": "CSS override scaffold for DisplayToastProvider items",
+    "description": "CSS override scaffold for DisplayToastProvider items (teleported to body, so not nested in a page class)",
     "scope": "css",
     "body": [
-      ".$1my-page {",
-      "  .display-toast-provider-item {",
-      "    --theme-surface: ;",
-      "    --theme-text: ;",
-      "    --theme-accent: ;",
-      "    --theme-border: ;",
-      "  }",
+      ".display-toast-provider-item {",
+      "  --theme-surface: $1;",
+      "  --theme-text: $2;",
+      "  --theme-accent: $3;",
+      "  --theme-border: $4;",
       "}"
     ]
   }