srcdev-nuxt-components 9.6.1 → 9.6.2

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

@@ -101,6 +101,10 @@ The ledger can't see items 9, 10, 11 and 14, so check those by hand.
    If other components render this one inside them (it's a child or building block of theirs),
    each story gets a short note that explains the relationship and links to the parent's story
    (`storybook-add-story.md`, "Link to the stories of components that use this one").
+   Sample copy in stories, and examples in the skill doc, use placeholders (a name like "Alex
+   Morgan", a town like "Northtown"), never a real client's name, town, business or site: the
+   stories and docs ship in the public package. **Existing component:** check for, and replace, any
+   copy lifted from a consumer app (`ProfileSection` had both).
 6a. **Storybook Controls-panel reactivity** — check every story `Template`/`render` function in
     the component's `stories/*.stories.ts` files for this bug: `@storybook/vue3` mounts the story
     component **once** and, on every Controls-panel change, mutates the same reactive `args`
@@ -134,7 +138,9 @@ The ledger can't see items 9, 10, 11 and 14, so check those by hand.
     descriptions, body text) a line-clamp token, `--<component>-<element>-line-clamp`, which
     covers ellipsis too (`1` is single-line ellipsis). Default it to `none` unless the layout
     clearly needs a cap, and never clamp text that must stay readable (legal or attribution text,
-    link text that names its destination). Shape and rules: `theming-component-token-pattern.md`,
+    link text that names its destination). Only text the component renders itself (props and data) needs a token: text that arrives
+    through a slot is the consumer's own markup, so they clamp it directly and the component adds
+    no token for it (`ProfileSection` is all slots and has none). Shape and rules: `theming-component-token-pattern.md`,
     "Line-clamp tokens". Give each line-clamp token a Controls-panel select in the stories (set on
     a wrapper `:style`, stripped from the component's args), labelled as a story-only CSS token so
     nobody mistakes it for a prop: `storybook-add-story.md`, "Label token controls as story-only".
@@ -222,3 +228,10 @@ The ledger can't see items 9, 10, 11 and 14, so check those by hand.
     - `NuxtImg` gets explicit `width` and `height`; a `<video>` uses a `<source :src>` child with
       `:key` and `.load()` (pitfall #12).
     - No `#components` import (breaks Storybook); use `resolveComponent()`.
+    - Layout breakpoints respond to the component's own width (`container: <name> / inline-size` on the
+      root, `@container <name> (min-width: …)`), not the viewport, so it still works in a narrow
+      column. **Existing component:** when converting a viewport `@media` breakpoint, grep consumer
+      repos for `@media` overrides of the same element (they now switch at a different point) and list
+      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.

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

@@ -1,5 +1,7 @@
 # DisplayAvatar Component
 
+> **Changed 2026-10-14:** size is a `data-size` attribute, not a bare class (`.display-avatar.lg` → `.display-avatar[data-size="lg"]`). New `image-size` prop (default `112`): `NuxtImg` used to get `width="100%"`, which @nuxt/image ignores, so the Vercel provider requested its largest screen width for every avatar. A broken image now falls back to the initials, initials are emoji-safe, and long fallback text is clipped inside the circle. With `chip`, the status dot was drawn at the avatar's diameter instead of its configured size: avatar and chip both declared a private `--_size` on the same root element and the avatar's size rules won. The avatar's private tokens are now `--_avatar-size`/`--_avatar-font-size`. Content (both slots too) now sits in a full-size `.display-avatar-surface` that carries the background, so the chip's cutout covers the whole avatar instead of landing on the initials span and cutting into the letters.
+
 > **Changed 2026-10-08:** new `status`/`status-label` props, forwarded to the chip. Chip status used to be an `online`/`idle`/`dnd` class through `style-class-passthrough`, which no longer colours the dot.
 
 ## Overview
@@ -18,10 +20,11 @@
 | `src`                       | `string`                                  | —        | Image URL. Renders `NuxtImg` when set; fallback text otherwise.   |
 | `alt`                       | `string`                                  | —        | Alt text for the image; also used to derive initials.             |
 | `text`                      | `string`                                  | —        | Override the auto-derived initials with an explicit string.       |
-| `size`                      | `"xs" \| "s" \| "md" \| "lg" \| "xl"`   | `"md"`   | Controls width, height, and font-size.                            |
+| `size`                      | `"xs" \| "s" \| "md" \| "lg" \| "xl"`   | `"md"`   | Sets `data-size`, which picks width, height and font-size.        |
 | `chip`                      | `boolean \| DisplayChipConfig`           | —        | Add a status chip. `true` uses defaults; pass a config object to customise. |
 | `status`                    | `DisplayChipStatus`                       | —        | Chip status colour (`offline`/`online`/`idle`/`dnd`), forwarded to `DisplayChip`. Ignored without `chip`; the chip defaults to `offline`. |
 | `status-label`              | `string`                                  | —        | Screen-reader text for the chip status (e.g. "Online"), forwarded to `DisplayChip`. Ignored without `chip`. |
+| `:image-size`              | `number`                                  | `112`    | Pixel width and height requested from `@nuxt/image` (1x; 2x is double). Raise it if you resize the avatar past `xl` with `--display-avatar-size`. |
 | `:style-class-passthrough`  | `string \| string[]`                      | `[]`     | Extra CSS classes on the root element.                            |
 
 ### Size dimensions
@@ -45,24 +48,32 @@ Each step is a token (`--display-avatar-size-md`, `--display-avatar-font-size-md
 | `default` | Replaces the auto image/fallback content entirely.                  |
 | `icon`    | Appended inside the avatar (e.g. an icon overlay over the image). |
 
+Both slots render inside `.display-avatar-surface`, a full-size element that carries the background. With `chip`, that surface is what gets the cutout mask.
+
 ---
 
 ## Fallback text logic
 
 When `src` is not set, a `<span>` renders the fallback value:
 
-1. `text` prop — used as-is if provided.
-2. `alt` initials — first character of each word, capped at two characters.
+1. `text` prop — used as-is if it has any non-whitespace content.
+2. `alt` initials — the first character (a whole grapheme, so emoji and flags stay intact) of the first two words. Extra whitespace is ignored.
 3. Empty string — if neither is set.
 
 When `alt` is set, the initials are `aria-hidden` and the full `alt` is rendered as `sr-only` text, so a screen reader announces "Jane Smith" rather than "J S". With only `text`, the text is read as-is.
 
+If the image fails to load, the initials fallback shows instead (an empty circle when there is no `alt`). A new `src` tries the image again.
+
+The fallback is one line, clipped to the circle: keep `text` short (1–3 characters).
+
 With `src`, the image uses `alt`, or an empty (decorative) `alt` when none is given. Pass `alt` unless the name is already visible next to the avatar.
 
 ```
 alt="John Doe"     → "JD"
 alt="Alice"        → "A"
 alt="Alice Bob C"  → "AB"
+alt="🦄 Unicorn"    → "🦄U"
+alt="  Jane  Smith " → "JS"
 text="?"           → "?"
 ```
 

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

@@ -226,6 +226,7 @@ See [display-avatar.md](./display-avatar.md) for the full API.
 - `shape` must match the actual shape of the slot content — the position maths differs between `circle` (radius-based) and `square` (clamped corner-aware).
 - `config` values are geometric inputs to CSS `calc(cos())` / `calc(sin())` expressions. Pass them as strings with units (`"12px"`, `"45deg"`), not plain numbers.
 - The chip dot is rendered via `::after` pseudo-element; icon and label sit above it at `z-index: 2`.
-- The mask cutout is applied to all direct children of `.display-chip` except `.display-chip-icon`, `.display-chip-label` and the `.sr-only` status text — ensure the host element is a direct child.
+- The mask cutout is applied to all direct children of `.display-chip` except `.display-chip-icon`, `.display-chip-label` and the `.sr-only` status text. The mask is positioned in percentages of each child's own box, so slot exactly one host element that fills the chip and carries its own background (an `<img>`, or a full-size wrapper around text). A small text span as a direct child gets the notch cut into its letters, and a background set on `.display-chip` itself is never cut. `DisplayAvatar` wraps its content in a full-size `.display-avatar-surface` for this reason.
+- A component that renders `DisplayChip` as its own root (as `DisplayAvatar` does) shares that element, so it must not declare the chip's private tokens (`--_size`, `--_offset`, ...) for its own values: they collide on the same element. `DisplayAvatar` uses `--_avatar-size`.
 - The `StressTest` story shows the worst-case labels and config values.
 - `DisplayChipConfig` and `DisplayChipProps` are both exported from the layer types. Use `DisplayChipConfig` when passing geometry values (the `config` prop). Use `DisplayChipProps` only if you need to pass the full component prop set (e.g. when building a wrapper component).

package/.claude/skills/components/google-reviews.md

@@ -132,8 +132,8 @@ replaced.
 - Survives hostile data (see the `StressTest` story): long and unbroken text wraps inside its card,
   reviewer names are cut to 2 lines (`--google-reviews-author-line-clamp`),
   initials take whole characters (emoji-safe), star fill is clamped to 0–5, review text renders as
-  plain text. A broken photo URL still shows the browser's broken-image icon, since
-  `DisplayAvatar` has no image-error fallback.
+  plain text. A broken photo URL falls back to the reviewer's initials (`DisplayAvatar`'s image-error
+  fallback).
 
 ## Variants
 

package/.claude/skills/components/profile-section.md

@@ -1,24 +1,26 @@
 ---
 name: ProfileSection
-description: ProfileSection molecule — props, dynamic profile-info slots, eyebrowText/heroText/profileLinks slots, layout, accessibility
+description: ProfileSection molecule — props, dynamic profile-info slots, eyebrowText/heroText/profileLinks slots, container-query layout, accessibility
 type: reference
 ---
 
 # ProfileSection
 
+> **Changed 2026-10-14 (breaking):** New `headerPlacement` prop (`above`, `picture-bottom`, `picture-top`) can put the header over the bottom or top of the picture. `profileInfoCount` removed — only the `profile-info-N` slots you give are rendered (it used to pad with empty blocks when none were given). The two-column switch is a container query on the component's own width, not a viewport `@media` query, and both columns are `minmax(0, …)`. The `<header>` is only rendered when a header slot is given. Highlight colours go through new `--profile-section-*` tokens. An invalid `profilePicture.width`/`height` (0, negative, `NaN`) falls back to 828×1104.
+>
 > **Classes renamed 2026-09-27:** `.picture` → `.profile-section-picture`, `.profile-picture` → `.profile-section-image`, `.profile-info` → `.profile-section-info`, `.profile-info-content` → `.profile-section-info-content`, `.profile-info-block` → `.profile-section-info-block`, `.profile-links` → `.profile-section-links`.
 
 ## Overview
 
-`ProfileSection` is a molecule that renders a practitioner/author profile: a header area (eyebrow + heading), a profile picture, and a flexible set of bio/info blocks alongside optional profile links. It is landmark-aware — when `tag` is `section`, `article`, or `aside`, the root element automatically gets `aria-labelledby` wired to the heading inside the `#heroText` slot (**you must bind `headingId` yourself, and a console warning fires if you forget** — see [component-aria-landmark.md](../component-aria-landmark.md)). `tag="main"` is never auto-labelled.
+`ProfileSection` is a molecule that renders a practitioner/author profile: a header area (eyebrow + heading), a profile picture, and a flexible set of bio/info blocks alongside optional profile links. It is landmark-aware — when `tag` is `section` or `article`, the root element automatically gets `aria-labelledby` wired to the heading inside the `#heroText` slot (**you must bind `headingId` yourself, and a console warning fires if you forget** — see [component-aria-landmark.md](../component-aria-landmark.md)). `tag="main"` is never auto-labelled.
 
 ## Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `profilePicture` | `ProfilePicture` (`{ src; alt; width?; height? }`, exported from the layer types) | — | **Required.** Rendered via `NuxtImg` with `width`/`height` defaulting to `828`/`1104` (3:4, a Vercel-allowed width). |
+| `profilePicture` | `ProfilePicture` (`{ src; alt; width?; height? }`, exported from the layer types) | — | **Required.** Rendered via `NuxtImg`. `width`/`height` default to `828`/`1104` (3:4, a Vercel-allowed width), and a missing or invalid value (0, negative, `NaN`, `Infinity`) uses the default. |
 | `tag` | `"div" \| "section" \| "article" \| "main"` | `"div"` | HTML element rendered as the root. |
-| `profileInfoCount` | `number` | `3` | Number of `profile-info-N` slots to generate when none are explicitly provided. |
+| `headerPlacement` | `"above" \| "picture-bottom" \| "picture-top"` | `"above"` | Where the `#eyebrowText`/`#heroText` header goes: above the grid, or over the bottom or top of the picture on a scrim. Template form: `header-placement`. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
 
 ## Slots
@@ -28,17 +30,19 @@ type: reference
 | `#eyebrowText` | Optional eyebrow label above the heading. Use `EyebrowText`. |
 | `#heroText` | Heading slot. Receives `headingId` as a slot prop — bind it to the heading's `id` for accessible `aria-labelledby`. |
 | `#profile-info-1` … `#profile-info-N` | Bio / info blocks. Provide as many numbered slots as needed. They are rendered in ascending numeric order. |
-| `#profileLinks` | Links / actions shown at the bottom-right of the info column (e.g. social icons, booking CTA). |
+| `#profileLinks` | Links / actions shown at the bottom-right of the info column (e.g. social icons, booking CTA). Wraps onto more lines when there are many. |
+
+The `<header class="profile-section-header">` is only rendered when `#eyebrowText` or `#heroText` is given. It renders above the grid, or inside the picture when `header-placement` is `picture-bottom` or `picture-top`.
 
 ## Basic usage
 
 ```vue
 <ProfileSection
   tag="section"
-  :profile-picture="{ src: '/images/profile/mel.jpg', alt: 'Mel Stafford, reflexologist' }"
+  :profile-picture="{ src: '/images/profile/alex.jpg', alt: 'Alex Morgan, hair stylist' }"
 >
   <template #eyebrowText>
-    <EyebrowText font-size="large" text="About Mel" />
+    <EyebrowText font-size="large" text-content="About Alex" />
   </template>
 
   <template #heroText="{ headingId }">
@@ -47,8 +51,8 @@ type: reference
       :id="headingId"
       font-size="title"
       :text-content="[
-        { text: 'Mel Stafford', styleClass: 'normal' },
-        { text: 'Reflexologist', styleClass: 'accent' },
+        { text: 'Alex Morgan', styleClass: 'normal' },
+        { text: 'Hair stylist', styleClass: 'accent' },
       ]"
     />
   </template>
@@ -58,7 +62,7 @@ type: reference
   </template>
 
   <template #profile-info-2>
-    <p>Mel is based in Lichfield…</p>
+    <p class="location">Based in <span class="highlight">Northtown</span>…</p>
   </template>
 
   <template #profileLinks>
@@ -69,11 +73,12 @@ type: reference
 
 ## Dynamic profile-info slots
 
-The `profile-info-N` slots are discovered at runtime by filtering `useSlots()` for keys matching `/^profile-info-\d+$/`. The slots are rendered in ascending numeric order.
+The `profile-info-N` slots are discovered at runtime by filtering `useSlots()` for keys matching `/^profile-info-\d+$/`, and rendered in ascending numeric order.
 
 - If you provide `#profile-info-1`, `#profile-info-2`, `#profile-info-3` — all three render in order.
-- If you provide no `profile-info-*` slots, the component renders `profileInfoCount` empty blocks (they used to contain visible placeholder text, removed 2026-09-27). Slot discovery runs every render, so slots added after mount appear.
-- Gaps are supported — you can provide `#profile-info-1` and `#profile-info-3` without `#profile-info-2`; they sort correctly.
+- If you provide none, no info blocks render.
+- Gaps are supported — you can provide `#profile-info-1` and `#profile-info-3` without `#profile-info-2`; `#profile-info-12` sorts after `#profile-info-2`.
+- Discovery runs every render, so slots added or removed after mount (a `v-if` on the slot template) appear and disappear.
 
 ## heroText slot prop
 
@@ -89,10 +94,41 @@ If you use a different heading component, bind `headingId` to whatever prop rend
 
 ## Layout
 
-- **Mobile**: single column — picture stacked above info.
-- **768px+**: two columns — `--profile-section-picture-width` (`384px`) picture column, `1fr` info column, `--profile-section-gap-wide` (`4rem`) gap (`--profile-section-gap`, `2rem`, below 768px).
-- Picture frame (`.profile-section-picture`): `--profile-section-picture-aspect-ratio` (`3 / 4`), `--profile-section-picture-border-radius` (`8px`), `overflow: hidden`. Full token list: `CONSUMER-STYLING.md` in the component folder. The `NuxtImg` fills the frame with `object-fit: cover`.
-- Profile links: `align-items: end; justify-content: flex-end` — right-aligned to the bottom of the info column.
+- The root is a size container named `profile-section`. Layout follows **the component's own width**, not the viewport.
+- **Under 768px wide**: single column — picture stacked above info, `--profile-section-gap` (`2rem`).
+- **768px wide or more**: two columns — `minmax(0, var(--profile-section-picture-width))` (`38.4rem`) picture column, `minmax(0, 1fr)` info column, `--profile-section-gap-wide` (`4rem`) gap.
+- Being an inline-size container, the root can't size itself from its content: give it a width in a flex row or other shrink-to-fit context.
+- The root sets `overflow-wrap: anywhere`, so unbroken text and URLs in any slot wrap rather than widening the grid.
+- Picture frame (`.profile-section-picture`): `--profile-section-picture-aspect-ratio` (`3 / 4`), `--profile-section-picture-border-radius` (`0.8rem`), `overflow: hidden`. The `NuxtImg` fills the frame with `object-fit: cover`. Full token list: `CONSUMER-STYLING.md` in the component folder.
+- Profile links: `flex-wrap: wrap; align-items: end; justify-content: flex-end` — right-aligned to the bottom of the info column.
+- To change the picture column width, set `--profile-section-picture-width`; don't override `grid-template-columns` in a viewport `@media` query, which no longer lines up with the component's own switch.
+
+## Header in picture
+
+With `header-placement="picture-bottom"` or `"picture-top"`, the `<header>` renders inside `.profile-section-picture`, before the image in the DOM (so it is read first), and sits at the bottom or top of the frame on a scrim that fades away from that edge. It follows ServicesCard's `titles-within-image-wrapper`:
+
+- Scrim and text come from `--profile-section-picture-header-*` tokens: scrim colour (`#000`) and opacity (`75%`), a solid stop (`0%`, how far the scrim stays full strength before fading) and a target colour (`transparent`, what it fades into, set it to roughly the photo's colour where the fade ends so it blends instead of leaving a grey band), text colour (`contrast-color()` of the scrim colour where supported, else `#fff`), eyebrow colour, padding (`2.4rem`), gap (`0.4rem`). Full list in `CONSUMER-STYLING.md`.
+- The frame drops `overflow: hidden` in this mode, so its aspect ratio is a minimum: a long header grows the frame rather than being clipped. The image is absolutely positioned and still fills the frame.
+- `aria-labelledby` still points at the heading.
+- Drop spacing utilities like `mb-20` from the heading in this mode; the header's padding handles spacing.
+
+```vue
+<ProfileSection tag="section" header-placement="picture-bottom" :profile-picture="picture">
+  <template #eyebrowText>
+    <EyebrowText tag="p" font-size="medium" text-content="About Alex" />
+  </template>
+  <template #heroText="{ headingId }">
+    <HeroText :id="headingId" tag="h2" font-size="heading" :text-content="[{ text: 'Alex Morgan', styleClass: 'normal' }]" />
+  </template>
+  ...
+</ProfileSection>
+```
+
+Two stories show themes built only from tokens: `Header In Picture (Dark, Bottom)`, ServicesCard-style, and `Header In Picture (Light, Top)`. A light scrim needs a dark `--profile-section-picture-header-text-colour`; `contrast-color()` picks one where supported, but set it for older browsers. `--profile-section-info-text-colour` sets the info column's text colour for a themed background.
+
+## Content hooks
+
+A `.highlight` inside an element with class `location` gets `--profile-section-highlight-colour` (default `var(--colour-text-accent)`); inside `services` it gets `--profile-section-link-colour` / `--profile-section-link-colour-hover` (defaults `var(--colour-link-default)` / `var(--colour-link-hover)`). Both use `--profile-section-highlight-font-weight` (`600`). The `location`/`services` class can sit on the `<p>` itself or a wrapper.
 
 ## CSS notes
 
@@ -106,8 +142,6 @@ If you use a different heading component, bind `headingId` to whatever prop rend
 }
 ```
 
-- Accent-coloured text within `.location` or `.services` info blocks can use the `.highlight` class for `var(--colour-text-accent)` or `var(--colour-link-default)` colouring respectively.
-
 ## Consumer styling scaffold
 
 ```vue
@@ -121,6 +155,8 @@ If you use a different heading component, bind `headingId` to whatever prop rend
 <style>
 .profile-section {
   &.my-profile {
+    --profile-section-picture-width: 32rem;
+
     .profile-section-header {
       margin-block-end: 3.2rem;
     }
@@ -131,6 +167,8 @@ If you use a different heading component, bind `headingId` to whatever prop rend
 
 ## Notes
 
-- `NuxtImg` is used for the profile picture — provide a real `src` path. A placeholder (grey box) is shown if the image 404s.
-- The component does not expose `imgWidth` / `imgHeight` props for the picture. If IPX optimisation is critical, use a fixed-dimension image and rely on the `384px` column cap as the natural size constraint.
+- `NuxtImg` is used for the profile picture — provide a real `src` path. A broken image shows its alt text inside the 3:4 frame.
+- Pass `width`/`height` in `profilePicture` when your image isn't 3:4 at 828px wide, so IPX/Vercel request the right size.
+- The `With Social Icons` story shows a `SocialIconsList` in `#profileLinks`; size it with `--social-icons-list-icon-size` and `--social-icons-list-gap` on your own wrapper.
+- The `StressTest` story covers hostile content (broken image, unbroken text, RTL, out-of-order slots, many links) at every canvas width.
 - Component is auto-imported in Nuxt — no import needed.

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

@@ -57,6 +57,8 @@ import type { ISocialIcon } from "srcdev-nuxt-components";
 | YouTube | `logos:youtube-icon` | `https://www.youtube.com/@` |
 | TikTok | `logos:tiktok-icon` | `https://www.tiktok.com/@` |
 
+`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`.
+
 ---
 
 ## Usage example

package/.claude/skills/index.md

@@ -32,7 +32,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── theming-override-default.md      — replace the entire default theme with a custom palette (set --theme-hue/--theme-chroma)
 ├── theming-partial-override.md      — override a specific colour token category (palette, buttons, inputs) without a full theme replacement
 ├── theming-form-geometry-tokens.md  — non-colour form/button/input tokens (padding, border-radius, gaps): full inventory, why partial override doesn't need duplicating the source files
-├── theming-component-token-pattern.md — standard shape for overridable component colours: public token + inline fallback, no bare var()/no private-only indirection; the three tiers (theme slots / cross-component families / component-scoped); line-clamp tokens for overflowing text; rollout status
+├── theming-component-token-pattern.md — standard shape for overridable component colours: public token + inline fallback, no bare var()/no private-only indirection; the three tiers (theme slots / cross-component families / component-scoped); line-clamp tokens for overflowing text; image-overlay scrim tokens; rollout status
 ├── theming-status-tokens.md        — global --status-* colours (success/warning/danger/info/neutral: solid + surface + text), which components read them, how to override once for the whole library
 ├── theming-dark-mode.md            — add a dark scheme in a consumer app (layer is light-only): enable plumbing, full dark token set without light-dark(), light-dark() alternative, light-only pinning
 ├── colour-scheme-disable.md         — disable light/dark scheme support in a consumer app
@@ -108,12 +108,13 @@ 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, 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
     ├── 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
     ├── auto-grid.md            — AutoGrid: auto-fit responsive grid, $slots iteration, --auto-grid-gap/min-col-size-{small,default,large} tokens, is-responsive, semantic tag + aria
-    ├── display-avatar.md       — DisplayAvatar (02.molecules): circular avatar with image/initials fallback (alt announced), size scale tokens, --display-avatar-* colours, chip badge, icon slot
+    ├── display-avatar.md       — DisplayAvatar (02.molecules): circular avatar with image/initials fallback (alt announced), broken-image fallback, data-size scale tokens, image-size, --display-avatar-* colours, chip badge, icon slot
+    ├── profile-section.md      — ProfileSection (02.molecules): picture + numbered profile-info-N slots, eyebrow/hero header (above, or over the picture top/bottom on a scrim via header-placement), profileLinks, container-query two-column layout, .location/.services highlight tokens
     ├── display-theme-switch.md — DisplayThemeSwitch: system/light/dark picker wrapping TripleToggleSwitch, wired to useSettingsStore, labels/icons props, small sizing variant
     ├── card-core.md            — CardCore: generic card container, dynamic named slots as rows, 4 variants, blurred backdrop layer, full CSS token API
     ├── action-menu.md          — ActionMenu + ActionMenuItem: ellipsis trigger + anchored popover menu, indexed item-{n} slots, link/button items, full CSS token API

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

@@ -268,6 +268,8 @@ export const Default: Story = {
 Key points:
 
 - `computed` is **not** auto-imported in `.ts` story files — import it explicitly from `"vue"`.
+- Components aren't auto-registered in a story's `template` string either. Every component used there, including ones you put in the component's slots (`EyebrowText`, `HeroText`, `SocialIconsList`, ...), must be imported and listed in `components: {}`. Otherwise Vue renders it as an empty unknown element (`<eyebrowtext>`) with no error. ProfileSection's header and social-icons stories rendered blank this way until 2026-10-14.
+- Props in a story's `template` string aren't type-checked either. An invalid value renders silently with no warning: ProfileSection's stories passed `font-size="large"` to `HeroText`, which only has `display`/`title`/`heading`/`subheading`/`label`, so the heading fell back to unstyled text. Check every literal prop value against the component's `interface Props`.
 - Extra args must be stripped before `v-bind` — spreading unknown keys onto a component makes them unknown HTML attributes.
 - CSS custom properties set via `:style` on the component root are picked up by `var()` in the component's scoped CSS.
 

package/.claude/skills/theming-component-token-pattern.md

@@ -83,6 +83,54 @@ Prefer this over a prop: line count is presentation, and CSS handles it without
   layout around it.
 - Document it in `CONSUMER-STYLING.md` with its default and the `1`/`none` options.
 
+## Text over an image: scrim tokens
+
+Any component that puts text over a photo (a header in a picture, a card title on its image) gets
+the same scrim token set, so a consumer can match the scrim to their photos. `ProfileSection`'s
+`header-placement="picture-top|picture-bottom"` is the reference; `ServicesCard`'s
+`titles-within-image-wrapper` has the older subset (colour and whole-background override only) and
+should gain the rest when it's next touched.
+
+| Token | Default | Purpose |
+|---|---|---|
+| `--{c}-scrim-colour` | `#000` | Colour the scrim starts from at the image's edge |
+| `--{c}-scrim-opacity` | `75%` | Its opacity at the start |
+| `--{c}-scrim-solid-stop` | `0%` | How far it stays full strength before fading, so the text sits on a clean background |
+| `--{c}-scrim-target-colour` | `transparent` | What it fades into: set to roughly the photo's colour where the fade ends, so there's no grey band |
+| `--{c}-scrim` | the gradient | Whole `background` override; `none` removes it |
+| `--{c}-text-colour` | `contrast-color(<scrim colour>)`, `#fff` without support | Text on the scrim |
+
+```css
+.component-header {
+  --_scrim-colour: var(--component-scrim-colour, #000);
+  --_scrim-start-colour: color-mix(in oklab, var(--_scrim-colour) var(--component-scrim-opacity, 75%), transparent);
+  --_scrim-solid-stop: var(--component-scrim-solid-stop, 0%);
+  --_scrim-target-colour: var(--component-scrim-target-colour, transparent);
+
+  color: var(--component-text-colour, #fff);
+  background: var(--component-scrim, linear-gradient(to top, rgb(0 0 0 / 0.75), rgb(0 0 0 / 0.75) var(--_scrim-solid-stop), var(--_scrim-target-colour)));
+
+  @supports (color: color-mix(in oklab, red, transparent)) {
+    background: var(--component-scrim, linear-gradient(to top, var(--_scrim-start-colour), var(--_scrim-start-colour) var(--_scrim-solid-stop), var(--_scrim-target-colour)));
+  }
+
+  @supports (color: contrast-color(red)) {
+    color: var(--component-text-colour, contrast-color(var(--_scrim-colour)));
+  }
+}
+```
+
+- The `@supports` fallback is for Safari before 16.2 (no `color-mix()`): it starts from 75% black
+  whatever the scrim colour, but keeps the solid stop and target colour.
+- `contrast-color()` reads the scrim colour, not the photo. Document that a consumer who removes the
+  scrim must set the text colour.
+- Round only the corners on the image's edge (`border-end-*-radius: inherit` for a bottom scrim),
+  or an opaque target colour shows rounded inner corners.
+- If the text can be long, don't clip it: let the frame grow (absolutely position the image and
+  keep `overflow` visible so `aspect-ratio` acts as a minimum).
+- Give the story a light and a dark theme built only from these tokens, each with a photo whose
+  edge suits the scrim.
+
 ## Multi-level fallback chains are fine
 
 A component that wants to *look like* another component's default (rather than duplicating a

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

@@ -6,6 +6,13 @@
       "<DisplayAvatar src=\"${1:/images/profile.jpg}\" alt=\"${2:Jane Smith}\" size=\"${3|md,xs,s,lg,xl|}\" />"
     ]
   },
+  "SRCDEV DisplayAvatar Large Image": {
+    "description": "DisplayAvatar: image avatar resized beyond the scale, with a matching image-size so it stays sharp",
+    "scope": "vue,html",
+    "body": [
+      "<DisplayAvatar src=\"${1:/images/profile.jpg}\" alt=\"${2:Jane Smith}\" :image-size=\"${3:240}\" style=\"--display-avatar-size: ${4:12rem}\" />"
+    ]
+  },
   "SRCDEV DisplayAvatar Initials": {
     "description": "DisplayAvatar: initials derived from alt (alt is announced, initials hidden from screen readers)",
     "scope": "vue,html",

package/.vscode/srcdev-component-profile-section.code-snippets

@@ -5,16 +5,16 @@
     "body": [
       "<ProfileSection",
       "  tag=\"section\"",
-      "  :profile-picture=\"{ src: '$1', alt: '$2' }\"",
+      "  :profile-picture=\"{ src: '$2', alt: '$3' }\"",
       ">",
       "  <template #eyebrowText>",
-      "    <EyebrowText text-content=\"$3\" />",
+      "    <EyebrowText text-content=\"$4\" />",
       "  </template>",
       "  <template #heroText=\"{ headingId }\">",
-      "    <HeroText :id=\"headingId\" tag=\"h2\" :text-content=\"[{ text: '$4' }]\" />",
+      "    <HeroText :id=\"headingId\" tag=\"h2\" :text-content=\"[{ text: '$5' }]\" />",
       "  </template>",
       "  <template #profile-info-1>",
-      "    <p>$5</p>",
+      "    <p>$6</p>",
       "  </template>",
       "  <template #profile-info-2>",
       "    <p>$6</p>",
@@ -22,6 +22,27 @@
       "</ProfileSection>"
     ]
   },
+  "SRCDEV ProfileSection Header In Picture": {
+    "description": "ProfileSection with the eyebrow and heading over the bottom or top of the picture, on a scrim",
+    "scope": "vue,html",
+    "body": [
+      "<ProfileSection",
+      "  tag=\"section\"",
+      "  header-placement=\"${1|picture-bottom,picture-top|}\"",
+      "  :profile-picture=\"{ src: '$2', alt: '$3' }\"",
+      ">",
+      "  <template #eyebrowText>",
+      "    <EyebrowText text-content=\"$4\" />",
+      "  </template>",
+      "  <template #heroText=\"{ headingId }\">",
+      "    <HeroText :id=\"headingId\" tag=\"h2\" :text-content=\"[{ text: '$5' }]\" />",
+      "  </template>",
+      "  <template #profile-info-1>",
+      "    <p>$6</p>",
+      "  </template>",
+      "</ProfileSection>"
+    ]
+  },
   "SRCDEV ProfileSection CSS Override": {
     "description": "CSS override scaffold for ProfileSection tokens",
     "scope": "css",
@@ -30,6 +51,8 @@
       "  --profile-section-picture-width: $2;",
       "  --profile-section-gap-wide: $3;",
       "  --profile-section-picture-border-radius: $4;",
+      "  --profile-section-highlight-colour: $5;",
+      "  --profile-section-link-colour: $6;",
       "}"
     ]
   }

package/app/components/02.molecules/display-avatar/CONSUMER-STYLING.md

@@ -6,13 +6,17 @@
 
 | Token | Default | Controls |
 |---|---|---|
-| `--display-avatar-size` | the size class's value | Diameter, overriding the `size` prop's scale (one instance or a whole area) |
-| `--display-avatar-font-size` | the size class's value | Initials/text size, overriding the scale |
+| `--display-avatar-size` | the `size` step's value | Diameter, overriding the `size` prop's scale (one instance or a whole area) |
+| `--display-avatar-font-size` | the `size` step's value | Initials/text size, overriding the scale |
 | `--display-avatar-size-xs` / `-s` / `-md` / `-lg` / `-xl` | `2.4rem` / `3.2rem` / `4rem` / `4.8rem` / `5.6rem` | The diameter each `size` value maps to |
 | `--display-avatar-font-size-xs` / `-s` / `-md` / `-lg` / `-xl` | `1.2rem` / `1.4rem` / `1.6rem` / `1.8rem` / `2rem` | The text size each `size` value maps to |
 
-A custom `size` string (anything other than `xs`–`xl`) is added as a class but maps to no scale
-step, so it renders at `md` unless you set `--display-avatar-size` for it.
+A custom `size` string (anything other than `xs`–`xl`) is set as `data-size` but maps to no
+scale step, so it renders at `md` unless you set `--display-avatar-size` for it (target it with
+`.display-avatar[data-size="<your-size>"]`).
+
+If you size an image avatar beyond the scale, raise the `image-size` prop (default `112`, the
+pixel width and height requested from `@nuxt/image`) to match, or the image is upscaled and blurry.
 
 ### Appearance
 
@@ -30,21 +34,33 @@ step, so it renders at `md` unless you set `--display-avatar-size` for it.
 > faint in light mode; it now uses the `--theme-*` surface and text tokens, so it follows light
 > and dark mode.
 
-Private tokens (not public API): `--_size` and `--_font-size`, which each size class sets from its
+Private tokens (not public API): `--_avatar-size` and `--_avatar-font-size`, which each size step sets from its
 scale token.
 
 ## State hooks
 
-- Size class on the root: `.xs`, `.s`, `.md`, `.lg`, `.xl` (or your custom `size` string).
-- Classes: `.display-avatar` (root), `.display-avatar-image` (the image), `.display-avatar-icon`
-  (opt-in, for your `#icon` slot content).
+- `data-size` on the root: `xs`, `s`, `md`, `lg`, `xl` (or your custom `size` string).
+- Classes: `.display-avatar` (root: size, font size, radius), `.display-avatar-surface` (fills the root,
+  carries the background and text colour, and holds all content), `.display-avatar-image` (the image), `.display-avatar-fallback`
+  (the initials or `text`; one line, clipped to the circle), `.display-avatar-icon` (opt-in, for
+  your `#icon` slot content).
 - With `chip`, the root is `DisplayChip`, so it also carries `.display-chip` and its
   `data-shape`/`data-status` attributes (status comes from the `status` prop). See `display-chip`
   for its tokens.
 
+> **Changed 2026-10-14**: the size was a bare class on the root (`.display-avatar.lg`), which a
+> consumer's own `.lg`/`.xl` utility classes could match. Replace `.display-avatar.<size>` with
+> `.display-avatar[data-size="<size>"]`. Overlong fallback text is now clipped inside the circle, the
+> avatar no longer shrinks in a flex row, and a broken image falls back to the initials.
+> With `chip`, the status dot is its configured size again (it had picked up the avatar's diameter
+> through a shared private `--_size` name). Content now sits in a full-size
+> `.display-avatar-surface`, which carries the background: the chip's cutout used to land on the
+> small initials span (cutting into the letters) and never reached the background. If you set
+> `background` directly on `.display-avatar`, use `--display-avatar-background` instead.
+>
 > **Changed 2026-10-08**: chip status is the `status` prop (forwarded to `DisplayChip` as
 > `data-status`), not an `online`/`idle`/`dnd` class through `style-class-passthrough`.
-
+>
 > **Changed 2026-09-27**: `.avatar-image` → `.display-avatar-image` and `.avatar-icon` →
 > `.display-avatar-icon`.
 
@@ -56,7 +72,7 @@ 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:** the size classes set `--_size`/`--_font-size` on the avatar itself, so changing the
+**Caveat:** the size steps set `--_avatar-size`/`--_avatar-font-size` on the avatar itself, so changing the
 scale (`--display-avatar-size-md` etc.) from an ancestor works, but a one-off diameter should use
 `--display-avatar-size`, which beats the scale wherever it's set.