srcdev-nuxt-components 9.6.5 → 9.6.7

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

@@ -178,7 +178,9 @@ 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`.
@@ -188,6 +190,8 @@ The ledger can't see items 6c, 9, 10, 11 and 14, so check those by hand.
      `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.

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/page-hero-highlights.md

@@ -1,5 +1,7 @@
 # PageHeroHighlights Component
 
+> **Changed 2026-10-16:** `widthConstrained` was inverted in the CSS since it was first added (`true` gave full width, `false` capped the column); it now does what this doc always said. The tablet/desktop gutters never applied (their `@container` queries had no container): the root is now a named `page-hero-highlights` inline-size container and the rows sit in a `.page-hero-highlights-grid` wrapper. Colour defaults are light theme tokens (were `darkblue`/`white`/`black`/`--slate-*`). Equal-width highlights wrap below `--page-hero-highlights-item-min-width` (12rem). Grid tracks are `minmax(0, …)` and items get `overflow-wrap: anywhere`.
+
 > **Changed 2026-09-28:** styles are now in `@layer components` (they were unlayered). Every token is `--page-hero-highlights-*` with its default as a `var()` fallback, so it can be set on the component or any ancestor (previously declared on the root with generic names like `--max-width`, `--highlight-border`, so ancestor values never landed). Inner classes are prefixed (`.page-hero-highlights-header-row`, `-header-slot`, `-strip`, `-content-row`, `-content-slot`); the content-align root classes are `.content-align-start`/`.content-align-center` (were bare `.start`/`.center`); the highlight contract classes are `.page-hero-highlights-item`, `-item-title`, `-item-body` (were `.highlight`, `.title`, `.body`); PageHeroHighlightsHeader uses `.page-hero-highlights-header-start`/`-end` and `--page-hero-highlights-header-*` tokens (were `.phh-*` / `--phh-*`). Full token reference: `CONSUMER-STYLING.md` in the component folder.
 
 ## Overview
@@ -19,7 +21,7 @@ The layout uses a 4-row CSS Grid with `subgrid` — no `translate`, negative mar
 | `tag`                   | `"div" \| "section" \| "main"`                                      | `"div"`     | Root element tag                                                                                                                |
 | `highlightsEqualWidths` | `boolean`                                                           | `false`     | Equal-width grid columns for highlight items                                                                                    |
 | `highlightsJustify`     | `"start" \| "center" \| "end" \| "space-between" \| "space-around"` | `"start"`   | Alignment of highlight items along the main axis                                                                                |
-| `widthConstrained`              | `boolean`                                                           | `false`     | When `true`, caps the central column at `--width-constrained` (default `1064px`). Gutters grow responsively to enforce the constraint. |
+| `widthConstrained`              | `boolean`                                                           | `false`     | When `true`, caps the central column at `--page-hero-highlights-max-width` (default `1064px`). Gutters grow responsively to enforce the constraint. |
 | `contentAlign`          | `"start" \| "center"`                                               | `"center"`  | When `widthConstrained` is `true`: `"center"` grows gutters equally; `"start"` pins content to the left with a fixed left gutter.      |
 | `contentPanel`          | `boolean`                                                           | `true`      | When `true`, renders a decorative panel behind the content slot and offsets the highlights strip. Set to `false` for a flat layout with no backdrop. |
 | `highlightTitleBaseline`| `boolean`                                                           | `false`     | When `true`, fixes the highlight title row to a set height so titles align at a common baseline. Override `--page-hero-highlights-title-height` to tune. |
@@ -166,7 +168,7 @@ See [component-aria-landmark.md](../component-aria-landmark.md) for the full pat
 
 ## Equal-width highlights
 
-By default, highlight items size to their content (`flex-wrap`). Pass `:highlights-equal-widths="true"` to switch to a grid where all items share equal column widths:
+By default, highlight items size to their content (`flex-wrap`). Pass `:highlights-equal-widths="true"` to switch to a grid where all items share equal column widths (`repeat(auto-fit, minmax(min(100%, --page-hero-highlights-item-min-width), 1fr))`), wrapping onto new rows when they'd get narrower than the min width (default `12rem`):
 
 ```vue
 <PageHeroHighlights :highlights-equal-widths="true">
@@ -176,10 +178,10 @@ By default, highlight items size to their content (`flex-wrap`). Pass `:highligh
 
 ## Constraining the central column width
 
-Pass `:width-constrained="true"` to cap the content column at `--width-constrained` (default `1064px`). The gutters grow responsively to enforce it — full-bleed backgrounds are unaffected and `subgrid` continues to work. Use `content-align` to pin to the left or centre:
+Pass `:width-constrained="true"` to cap the content column at `--page-hero-highlights-max-width` (default `1064px`). The gutters grow responsively to enforce it — full-bleed backgrounds are unaffected and `subgrid` continues to work. Use `content-align` to pin to the left or centre:
 
 ```vue
-<!-- Centred, capped at --width-constrained (1064px) -->
+<!-- Centred, capped at --page-hero-highlights-max-width (1064px) -->
 <PageHeroHighlights :width-constrained="true" content-align="center">...</PageHeroHighlights>
 
 <!-- Left-pinned (right side takes remaining space) -->
@@ -190,12 +192,12 @@ The maximum width value and gutter sizes are all CSS tokens — override them vi
 
 ```css
 .my-page-hero {
-  --width-constrained: 1200px;
+  --page-hero-highlights-max-width: 1200px;
   --page-hero-highlights-gutter-desktop: 48px;
 }
 ```
 
-See [css-grid-width-constrained-gutters.md](../css-grid-width-constrained-gutters.md) for the underlying pattern explanation.
+See [css-grid-max-width-gutters.md](../css-grid-max-width-gutters.md) for the underlying pattern explanation.
 
 ## Local style override scaffold
 
@@ -215,40 +217,41 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
 .page-hero-highlights {
   &.my-page-hero {
     /* Grid layout */
-    /* --width-constrained: 1064px; */
+    /* --page-hero-highlights-max-width: 1064px; */
     /* --page-hero-highlights-gutter-mobile: 16px; */
     /* --page-hero-highlights-gutter-tablet: 40px; */
     /* --page-hero-highlights-gutter-desktop: 32px; */
 
     /* Header zone */
-    /* --page-hero-highlights-header-background: darkblue; */
+    /* --page-hero-highlights-header-background: var(--theme-surface-subtle); */
 
     /* Highlights strip */
     /* --page-hero-highlights-strip-gap: 1rem; */
     /* --page-hero-highlights-strip-inset: 1.2rem; */
+    /* --page-hero-highlights-item-min-width: 12rem; */ /* equal-widths wrap point */
 
     /* Highlight cards */
     /* --page-hero-highlights-item-rows-gap: 1.2rem; */
     /* --page-hero-highlights-title-height: 1fr; */ /* see: highlight-title-baseline prop */
     /* --page-hero-highlights-item-padding-block-start: 1.2rem; */
     /* --page-hero-highlights-item-padding: 1.2rem; */
-    /* --page-hero-highlights-item-background: white; */
-    /* --page-hero-highlights-item-border: 1px solid black; */
+    /* --page-hero-highlights-item-background: var(--page-bg, Canvas); */
+    /* --page-hero-highlights-item-border: 1px solid var(--theme-border); */
     /* --page-hero-highlights-item-border-radius: 8px; */
-    /* --page-hero-highlights-item-colour: black; */
+    /* --page-hero-highlights-item-colour: var(--theme-text); */
 
     /* Content zone */
-    /* --page-hero-highlights-content-background: var(--slate-01); */ /* transparent */
+    /* --page-hero-highlights-content-background: transparent; */
     /* --page-hero-highlights-content-start-gap: 1.2rem; */
     /* --page-hero-highlights-content-end-gap: 1.2rem; */
 
     /* Content slot decorative border */
     /* --page-hero-highlights-content-margin-block-start: 2.4rem; */
     /* --page-hero-highlights-content-margin: var(--page-hero-highlights-strip-inset); */
-    /* --page-hero-highlights-panel-background: var(--slate-00); */
-    /* --page-hero-highlights-panel-border: 1px solid var(--slate-06); */
+    /* --page-hero-highlights-panel-background: var(--theme-surface-subtle); */
+    /* --page-hero-highlights-panel-border: 1px solid var(--theme-border); */
     /* --page-hero-highlights-panel-border-radius: 0.8rem; */
-    /* --page-hero-highlights-panel-outline: 1px solid var(--slate-02); */
+    /* --page-hero-highlights-panel-outline: none; */
 
     /* When using :highlight-title-baseline="true" */
     /* --page-hero-highlights-title-height-baseline: 4rem; */ /* proportional value preferred */
@@ -268,10 +271,10 @@ row3: highlights bottom half
 row4: page content (never underflows highlights)
 ```
 
-`.page-hero-highlights-header-row` spans cols 1–3, rows 1–2 (edge-to-edge bg). `.page-hero-highlights-header-slot` is placed in row 1 only.
+All of these sit in `.page-hero-highlights-grid`, the grid inside the root (the root is the size container). `.page-hero-highlights-header-row` spans cols 1–3, rows 1–2 (edge-to-edge bg). `.page-hero-highlights-header-slot` is placed in row 1 only.
 `.page-hero-highlights-content-row` spans cols 1–3, rows 3–4 (bg fills behind highlights; `.page-hero-highlights-content-slot` is placed in row 4 only). The decorative border behind `.page-hero-highlights-content-slot` is rendered via `.page-hero-highlights-content-row::before` — there is no separate DOM element for it.
 
-Grid columns are determined entirely by CSS — no `v-bind`. The `widthConstrained` and `contentAlign` props add CSS classes (`width-constrained`, `start`, `center`) which select the appropriate `grid-template-columns` rule.
+Grid columns are determined entirely by CSS — no `v-bind`. The `widthConstrained` and `contentAlign` props add CSS classes (`width-constrained`, `content-align-start`, `content-align-center`) on the root, which select the `grid-template-columns` rule on `.page-hero-highlights-grid`.
 
 ## Layout pitfall: do not use `grid-template-rows: subgrid` inside `.page-hero-highlights-strip`
 
@@ -300,4 +303,5 @@ The `.page-hero-highlights-strip` element spans rows 2–3 of the parent grid (t
 - Lives in `app/components/04.templates/page-hero-highlights/`.
 - Storybook title: `"Templates/PageHeroHighlights"`.
 - **`contentAlign` has no effect when `widthConstrained` is `false`** — both gutters hold their responsive default.
-- **Gutter sizes are CSS tokens** — `--page-hero-highlights-gutter-mobile/tablet/desktop` are all overridable. The responsive switching between them (via `@container`) is handled internally and cannot be overridden.
+- **Gutter sizes are CSS tokens** — `--page-hero-highlights-gutter-mobile/tablet/desktop` are all overridable. They switch at 768px and 1024px of the component's own width (`@container page-hero-highlights`); the breakpoints themselves aren't tokens.
+- **The root is an inline-size container**, so it can't size from its content: as a flex or grid item give it `inline-size: 100%` or a track. A grid on the root itself was moved to `.page-hero-highlights-grid` for this (an element can't query its own size).

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/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
@@ -87,7 +88,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── link-text.md            — LinkText props, slots, usage patterns, styling
     ├── header-block.md         — HeaderBlock: tagLevel/classLevel semantic-vs-visual heading decoupling, page-heading-N utility classes
     ├── text-block.md           — TextBlock: vertical-rhythm text wrapper, --text-block-padding-block-start/-end tokens, heading-id slot prop for section/article aria-labelledby
-    ├── page-hero-highlights.md — PageHeroHighlights template: hero + highlights strip grid, CSS custom property theming
+    ├── page-hero-highlights.md — PageHeroHighlights template: hero + straddling highlights strip grid (root is the `page-hero-highlights` container, grid in `.page-hero-highlights-grid`), widthConstrained caps the column, equal-width highlights wrap at --page-hero-highlights-item-min-width, light theme-token defaults, PageHeroHighlightsHeader companion
     ├── slider-gallery.md       — SliderGallery: full-screen image carousel, IGalleryData, pause-on-hover/reduced-motion auto-advance, prefixed classes, CSS tokens
     ├── services-card.md        — ServicesCard props (incl. eyebrowConfig/heroConfig), actions slot, CSS tokens, page boilerplate
     ├── google-reviews.md        — GoogleReviews + GoogleReviewCard: Google Places reviews in a scrolling row; env vars, server route, useGoogleReviews, props, slots, tokens, Google terms
@@ -115,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

@@ -321,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;",
       "}"
     ]
   }

package/.vscode/srcdev-component-page-hero-highlights.code-snippets

@@ -3,7 +3,7 @@
     "description": "PageHeroHighlights: header zone, straddling highlights strip, content panel",
     "scope": "vue,html",
     "body": [
-      "<PageHeroHighlights tag=\"section\" content-align=\"${1|center,start|}\">",
+      "<PageHeroHighlights tag=\"section\" :width-constrained=\"true\" content-align=\"${1|center,start|}\">",
       "  <template #header=\"{ headingId }\">",
       "    <PageHeroHighlightsHeader>",
       "      <template #start><h1 :id=\"headingId\">$2</h1></template>",
@@ -31,6 +31,7 @@
       "  --page-hero-highlights-content-background: $3;",
       "  --page-hero-highlights-item-background: $4;",
       "  --page-hero-highlights-max-width: $5;",
+      "  --page-hero-highlights-item-min-width: $6;",
       "}"
     ]
   }

package/.vscode/srcdev-component-social-icons-list.code-snippets

@@ -11,6 +11,19 @@
       "/>"
     ]
   },
+  "SRCDEV SocialIconsList Labelled": {
+    "description": "SocialIconsList with visible labels and brand colours (mono icons, for the pill or tile recipes)",
+    "scope": "vue,html",
+    "body": [
+      "<SocialIconsList",
+      "  :items=\"[",
+      "    { networkName: '${1:Instagram}', iconName: '${2:bi:instagram}', baseHref: '${3:https://www.instagram.com/}', profileId: '$4', brandColour: '${5:#e1306c}' },",
+      "  ]\"",
+      "  show-label",
+      "  :style-class-passthrough=\"['${6:my-social-pills}']\"",
+      "/>"
+    ]
+  },
   "SRCDEV SocialIconsList CSS Override": {
     "description": "CSS override scaffold for SocialIconsList tokens",
     "scope": "css",
@@ -18,6 +31,7 @@
       ".$1my-page {",
       "  --social-icons-list-icon-size: $2;",
       "  --social-icons-list-gap: $3;",
+      "  --social-icons-list-icon-colour: $4;",
       "}"
     ]
   }

package/.vscode/srcdev-utility-dynamic-border-radius.code-snippets

@@ -0,0 +1,31 @@
+{
+  "SRCDEV Dynamic Border Radius Markup": {
+    "prefix": "srcdev-dynamic-border-radius",
+    "description": ".dynamic-border-radius: rounded until the image fills its container, then square (wrapper needs container-type: inline-size)",
+    "scope": "vue,html",
+    "body": [
+      "<div class=\"$1media-wrapper\">",
+      "  <img class=\"dynamic-border-radius${6:-transition}\" src=\"$2\" alt=\"$3\" width=\"$4\" height=\"$5\">",
+      "</div>"
+    ]
+  },
+  "SRCDEV Dynamic Border Radius CSS": {
+    "prefix": "srcdev-dynamic-border-radius-css",
+    "description": "Container wrapper and image rules for .dynamic-border-radius (max width via the token, so the -transition class can read it)",
+    "scope": "css",
+    "body": [
+      ".$1media-wrapper {",
+      "  container-type: inline-size;",
+      "",
+      "  img {",
+      "    display: block;",
+      "    inline-size: 100%;",
+      "    --dynamic-border-radius-max-width: ${2:50rem};",
+      "    max-inline-size: var(--dynamic-border-radius-max-width);",
+      "    margin-inline: auto;",
+      "    --dynamic-border-radius: ${3:5rem};",
+      "  }",
+      "}"
+    ]
+  }
+}

package/app/assets/styles/setup/06.utility-classes/_dynamic-border-radius.css

@@ -0,0 +1,27 @@
+/* ===========================================
+   DYNAMIC BORDER RADIUS
+   Rounded corners while the element is narrower than its
+   container; square once it spans the full container width.
+   Needs an ancestor with container-type: inline-size.
+   =========================================== */
+
+.dynamic-border-radius {
+  border-radius: clamp(0px, (100cqi - 100%) * 1e5, var(--dynamic-border-radius, 5rem));
+}
+
+/*
+ * Transition variant: compares against a max-width token instead of 100%, so the computed value is a plain length.
+ * A % stays unresolved until layout, which makes a transition start from a stale value and flicker on every resize frame.
+ */
+.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);
+  }
+}

package/app/assets/styles/setup/06.utility-classes/index.css

@@ -2,3 +2,4 @@
 @import "./spacing/index.css";
 /* @import "./layout/"; */
 @import "./_a11y.css";
+@import "./_dynamic-border-radius.css";