srcdev-nuxt-components 9.6.5 → 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

@@ -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/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
@@ -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-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";

package/app/components/02.molecules/social-icons-list/CONSUMER-STYLING.md

@@ -2,18 +2,68 @@
 
 ## Public token API
 
+### List
+
+| Token | Default | Controls |
+|---|---|---|
+| `--social-icons-list-gap` | `1.2rem` | Gap between items |
+
+### Link (the tile)
+
 | Token | Default | Controls |
 |---|---|---|
-| `--social-icons-list-icon-size` | `2.4rem` | Icon size (applied as `font-size`) |
-| `--social-icons-list-gap` | `1.2rem` | Gap between icons |
-| `--social-icons-list-icon-colour` | `currentColor` | Colour of mono icons (sets that draw in `currentColor`, e.g. `mdi:instagram`). No effect on `logos:` icons, whose colours are fixed in the SVG |
+| `--social-icons-list-link-padding` | `0` | Padding inside each link: set it to turn links into tiles or pills |
+| `--social-icons-list-link-gap` | `0.8rem` | Gap between the icon and the visible label |
+| `--social-icons-list-link-border` | `none` | Border shorthand |
+| `--social-icons-list-link-radius` | `0` | Corner radius (the focus outline follows it) |
+| `--social-icons-list-link-background` | `transparent` | Background |
+| `--social-icons-list-link-background-hover` | the resting background | Background on hover/focus |
+| `--social-icons-list-link-shadow` | `none` | Box shadow |
+| `--social-icons-list-link-shadow-hover` | the resting shadow | Box shadow on hover/focus (a glow) |
 | `--social-icons-list-hover-scale` | `1.15` | Scale on hover/focus (no scaling under `prefers-reduced-motion: reduce`) |
 | `--social-icons-list-hover-opacity` | `0.85` | Opacity on hover/focus |
+| `--social-icons-list-focus-ring-colour` | `var(--theme-ring, currentColor)` | Keyboard focus outline colour |
+
+### Icon
 
-The focus outline uses `--theme-ring`, falling back to `currentColor`. `logos:` icons carry their own brand colours. Some are dark (`logos:instagram-icon`, `logos:x`,
-`logos:github-icon`) and vanish on a dark background: use a mono icon there (`mdi:instagram`,
-`bi:instagram`, ...) and colour it with `--social-icons-list-icon-colour`.
+| Token | Default | Controls |
+|---|---|---|
+| `--social-icons-list-icon-size` | `2.4rem` | Icon size (a `font-size` on the icon wrapper) |
+| `--social-icons-list-icon-colour` | `currentColor` | Colour of mono icons (sets that draw in `currentColor`, e.g. `bi:instagram`). No effect on `logos:` icons, whose colours are fixed in the SVG |
+| `--social-icons-list-icon-colour-hover` | the resting icon colour | Mono icon colour on hover/focus |
+| `--social-icons-list-icon-wrapper-padding` | `0` | Padding around the icon's fixed `1em` square: uniform padding with a background and `50%` radius gives a circle, whatever the `icon` slot holds |
+| `--social-icons-list-icon-wrapper-border` | `none` | Border shorthand around the icon |
+| `--social-icons-list-icon-wrapper-radius` | `0` | Corner radius of the icon wrapper |
+| `--social-icons-list-icon-wrapper-background` | `transparent` | Background behind the icon |
+
+### Label (`show-label` or the `label` slot)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--social-icons-list-label-colour` | `currentColor` | Label text colour (set on the link) |
+| `--social-icons-list-label-font-size` | `var(--step-4, 1.6rem)` | Label font size |
+| `--social-icons-list-label-font-weight` | `600` | Label font weight |
 
+### Brand colour (data, not a default)
+
+`--social-icons-list-brand-colour` is set inline on each `.social-icons-list-item` from that item's
+`brandColour`. The component doesn't use it; it's there so your tokens can (hover colour, glow,
+circle fill). See the caveat under Local overrides.
+
+`logos:` icons carry their own brand colours. Some are dark (`logos:instagram-icon`, `logos:x`,
+`logos:github-icon`) and vanish on a dark background: use a mono icon there (`bi:instagram`,
+`mdi:instagram`, ...) and colour it with `--social-icons-list-icon-colour`.
+
+> Changed 2026-10-16: the inner classes were renamed so they can't collide with a site's own
+> `.social-icon` styles: `.social-icon-item` is now `.social-icons-list-item`, `.social-icon-link` is
+> `.social-icons-list-link` and `.social-icon` is `.social-icons-list-icon`. Update any selector that
+> used the old names. The icon now sits in a `.social-icons-list-icon-wrapper` span, which carries
+> the icon size (so a missing icon still leaves a focus target). New: the link, icon wrapper and
+> label tokens above, `--social-icons-list-focus-ring-colour` (the outline read `--theme-ring`
+> directly), and per-item `--social-icons-list-brand-colour`. Items whose href isn't http(s),
+> mailto, tel or site-relative are skipped. The focus outline's fixed `2px` radius is now
+> `--social-icons-list-link-radius` (default `0`).
+>
 > Changed 2026-10-14: new `--social-icons-list-icon-colour` token for mono icons.
 >
 > Changed 2026-09-28: `--theme-social-icon-size` and `--theme-social-icon-gap` were renamed to
@@ -27,8 +77,10 @@ No private `--_` tokens.
 
 ## State hooks
 
-Inner classes: `.social-icon-item` (each `<li>`), `.social-icon-link` (the `<a>`, opens in a new
-tab), `.social-icon` (the icon, `aria-hidden`).
+Inner classes: `.social-icons-list-item` (each `<li>`, carries `--social-icons-list-brand-colour`),
+`.social-icons-list-link` (the `<a>`, opens in a new tab), `.social-icons-list-icon-wrapper` (the
+`aria-hidden` span around the icon or the `icon` slot), `.social-icons-list-icon` (the default
+icon), `.social-icons-list-label` (visible text, only with `show-label` or the `label` slot).
 
 ---
 
@@ -40,6 +92,43 @@ Set the tokens above on an element you own (a page or section class, or a class
 `<style scoped>`, tokens set on your element still work, but selectors that reach inside the component need
 `:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
 
+**Caveat:** a token whose value reads `--social-icons-list-brand-colour` must be set on
+`.social-icons-list-item` (or deeper), not on the list or an ancestor. A `var()` inside a custom
+property resolves on the element that declares it, and the brand colour only exists on each item,
+so set on the root it finds nothing and falls back to the default.
+
+```css
+.my-section .social-icons-list-item {
+  --social-icons-list-icon-colour-hover: var(--social-icons-list-brand-colour);
+}
+```
+
+---
+
+## Recipes
+
+Four looks built only from the tokens above and consumer CSS, each on a class passed through
+`style-class-passthrough`. The full CSS is in `stories/social-icons-list-recipes.css` next to the
+component, and each has a Storybook story (`Recipe: …`). All use mono `bi:` icons plus a
+`brandColour` per item.
+
+- **Mono tiles, brand colour on hover**: tile tokens (`link-padding`, `-radius`, `-background`,
+  `-background-hover`), then `--social-icons-list-icon-colour-hover: var(--social-icons-list-brand-colour)`
+  on `.social-icons-list-item`.
+- **Dark dock with glow**: the dock is the list root (padding, border, radius and
+  `inline-size: fit-content` on your class), dark tiles inside, and
+  `--social-icons-list-link-shadow-hover` mixed from the brand colour on `.social-icons-list-item`.
+  Black brand colours (X, TikTok) don't show on a dark dock: give those items a light or accent
+  `brandColour` there.
+- **Labelled pills**: `show-label`, a pill link (`link-padding`, `-border`, `99rem` radius), and the
+  icon wrapper as a brand-coloured circle (`icon-wrapper-padding`, `50%` radius,
+  `icon-wrapper-background` from the brand colour on the item).
+- **Overlapping stack**: circles from the icon wrapper tokens, a negative `margin-inline-start` on
+  every `.social-icons-list-item + .social-icons-list-item`, reset on the list's `:hover` and
+  `:focus-within` so keyboard users get the fan-out too. Put the transition inside
+  `@media (prefers-reduced-motion: no-preference)`. A "Follow us" caption is your own text beside
+  the component.
+
 ---
 
 ## Class passthrough