srcdev-nuxt-components 9.6.1 → 9.6.2

package/app/components/02.molecules/display-avatar/DisplayAvatar.vue

@@ -3,16 +3,27 @@
     :is="chip ? DisplayChip : as"
     v-bind="chip ? { tag: chipTag, config: chipConfig, status, statusLabel } : {}"
     class="display-avatar"
-    :class="[size, elementClasses]"
+    :class="elementClasses"
+    :data-size="size"
   >
-    <slot name="default">
-      <NuxtImg v-if="src" :src :alt="alt ?? ''" width="100%" height="100%" class="display-avatar-image" />
-      <template v-else>
-        <span :aria-hidden="alt ? 'true' : undefined">{{ fallback }}</span>
-        <span v-if="alt" class="sr-only">{{ alt }}</span>
-      </template>
-    </slot>
-    <slot name="icon"></slot>
+    <span class="display-avatar-surface">
+      <slot name="default">
+        <NuxtImg
+          v-if="src && !imageFailed"
+          :src
+          :alt="alt ?? ''"
+          :width="imageSize"
+          :height="imageSize"
+          class="display-avatar-image"
+          @error="imageFailed = true"
+        />
+        <template v-else>
+          <span class="display-avatar-fallback" :aria-hidden="alt ? 'true' : undefined">{{ fallback }}</span>
+          <span v-if="alt" class="sr-only">{{ alt }}</span>
+        </template>
+      </slot>
+      <slot name="icon"></slot>
+    </span>
   </component>
 </template>
 
@@ -29,6 +40,7 @@ interface Props {
   chip?: boolean | DisplayChipConfig;
   status?: DisplayChipStatus;
   statusLabel?: string;
+  imageSize?: number;
   styleClassPassthrough?: string | string[];
 }
 
@@ -41,6 +53,7 @@ const props = withDefaults(defineProps<Props>(), {
   chip: undefined,
   status: undefined,
   statusLabel: undefined,
+  imageSize: 112,
   styleClassPassthrough: () => [],
 });
 
@@ -51,14 +64,26 @@ watch(
   () => resetElementClasses(props.styleClassPassthrough)
 );
 
+const imageFailed = ref(false);
+
+watch(
+  () => props.src,
+  () => (imageFailed.value = false)
+);
+
+const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+const firstGrapheme = (word: string) => graphemes.segment(word)[Symbol.iterator]().next().value?.segment ?? "";
+
 const fallback = computed(
   () =>
-    props.text ||
+    props.text?.trim() ||
     (props.alt || "")
-      .split(" ")
-      .map((word) => word.charAt(0))
+      .trim()
+      .split(/\s+/)
+      .filter(Boolean)
+      .slice(0, 2)
+      .map(firstGrapheme)
       .join("")
-      .substring(0, 2)
 );
 
 const chipDefaultConfig: DisplayChipConfig = {
@@ -76,36 +101,52 @@ const chipTag = computed((): "div" | "span" => (props.as === "div" || props.as =
 <style lang="css">
 @layer components {
   .display-avatar {
-    --_size: var(--display-avatar-size-md, 4rem);
-    --_font-size: var(--display-avatar-font-size-md, 1.6rem);
+    --_avatar-size: var(--display-avatar-size-md, 4rem);
+    --_avatar-font-size: var(--display-avatar-font-size-md, 1.6rem);
 
     display: flex;
-    align-items: center;
-    justify-content: center;
-    width: var(--display-avatar-size, var(--_size));
-    height: var(--display-avatar-size, var(--_size));
-    font-size: var(--display-avatar-font-size, var(--_font-size));
+    flex-shrink: 0;
+    width: var(--display-avatar-size, var(--_avatar-size));
+    height: var(--display-avatar-size, var(--_avatar-size));
+    font-size: var(--display-avatar-font-size, var(--_avatar-font-size));
     border-radius: var(--display-avatar-border-radius, 50%);
-    background-color: var(--display-avatar-background, var(--theme-surface-subtle));
-    color: var(--display-avatar-text-colour, var(--theme-text));
 
     isolation: isolate;
 
-    &.xs {
-      --_size: var(--display-avatar-size-xs, 2.4rem);
-      --_font-size: var(--display-avatar-font-size-xs, 1.2rem);
+    /* Fills the root so DisplayChip's per-child cutout mask is sized to the whole avatar. */
+    .display-avatar-surface {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      width: 100%;
+      height: 100%;
+      border-radius: inherit;
+      background-color: var(--display-avatar-background, var(--theme-surface-subtle));
+      color: var(--display-avatar-text-colour, var(--theme-text));
+    }
+
+    &[data-size="xs"] {
+      --_avatar-size: var(--display-avatar-size-xs, 2.4rem);
+      --_avatar-font-size: var(--display-avatar-font-size-xs, 1.2rem);
+    }
+    &[data-size="s"] {
+      --_avatar-size: var(--display-avatar-size-s, 3.2rem);
+      --_avatar-font-size: var(--display-avatar-font-size-s, 1.4rem);
     }
-    &.s {
-      --_size: var(--display-avatar-size-s, 3.2rem);
-      --_font-size: var(--display-avatar-font-size-s, 1.4rem);
+    &[data-size="lg"] {
+      --_avatar-size: var(--display-avatar-size-lg, 4.8rem);
+      --_avatar-font-size: var(--display-avatar-font-size-lg, 1.8rem);
     }
-    &.lg {
-      --_size: var(--display-avatar-size-lg, 4.8rem);
-      --_font-size: var(--display-avatar-font-size-lg, 1.8rem);
+    &[data-size="xl"] {
+      --_avatar-size: var(--display-avatar-size-xl, 5.6rem);
+      --_avatar-font-size: var(--display-avatar-font-size-xl, 2rem);
     }
-    &.xl {
-      --_size: var(--display-avatar-size-xl, 5.6rem);
-      --_font-size: var(--display-avatar-font-size-xl, 2rem);
+
+    .display-avatar-fallback {
+      min-inline-size: 0;
+      max-inline-size: 100%;
+      overflow: hidden;
+      white-space: nowrap;
     }
 
     .display-avatar-image {

package/app/components/02.molecules/display-avatar/stories/DisplayAvatar.stories.ts

@@ -98,6 +98,16 @@ export default {
   },
 } as Meta<typeof StorybookComponent>;
 
+// Links in the canvas open in the Storybook manager (target="_top"), not inside the preview iframe.
+const storyNoteStyle = "margin: 0 0 1.6rem; font-size: 1.4rem;";
+const googleReviewsNote = `
+  <p style="${storyNoteStyle}">
+    GoogleReviewCard puts an avatar beside each reviewer's name, with their photo or initials and its own avatar colour tokens. See the
+    <a href="/?path=/story/organisms-google-reviews--default" target="_top">Google Reviews</a> story, and
+    <a href="/?path=/story/organisms-google-reviews--no-avatars" target="_top">No Avatars</a> for the initials fallback.
+  </p>
+`;
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const useChip = (args: any) =>
   computed(() => ({
@@ -113,7 +123,8 @@ const Template: StoryFn<typeof StorybookComponent> = (args) => ({
     return { args, chip: useChip(args) };
   },
   template: `
-    <div style="display: flex; align-items: center; justify-content: center; height: 100vh;">
+    ${googleReviewsNote}
+    <div style="display: flex; align-items: center; justify-content: center; min-height: 80vh;">
       <StorybookComponent
         :size="args.size"
         :src="args.src"
@@ -135,7 +146,8 @@ export const Initials: StoryFn<typeof StorybookComponent> = (args) => ({
     return { args, chip: useChip(args) };
   },
   template: `
-    <div style="display: flex; align-items: center; justify-content: center; gap: 1.6rem; height: 100vh;">
+    ${googleReviewsNote}
+    <div style="display: flex; align-items: center; justify-content: center; gap: 1.6rem; min-height: 80vh;">
       <StorybookComponent :size="args.size" :alt="args.alt" :chip="chip" :status="args.status" :status-label="args.statusLabel" :style-class-passthrough="args.styleClassPassthrough" />
       <StorybookComponent :size="args.size" text="?" :chip="chip" :status="args.status" :status-label="args.statusLabel" :style-class-passthrough="args.styleClassPassthrough" />
     </div>
@@ -150,7 +162,8 @@ export const Sizes: StoryFn<typeof StorybookComponent> = (args) => ({
     return { args, chip: useChip(args), sizes: ["xs", "s", "md", "lg", "xl"] };
   },
   template: `
-    <div style="display: flex; align-items: center; justify-content: center; gap: 1.6rem; height: 100vh;">
+    ${googleReviewsNote}
+    <div style="display: flex; align-items: center; justify-content: center; gap: 1.6rem; min-height: 80vh;">
       <StorybookComponent
         v-for="size in sizes"
         :key="size"
@@ -167,3 +180,71 @@ export const Sizes: StoryFn<typeof StorybookComponent> = (args) => ({
 });
 Sizes.args = { src: undefined, alt: "Jane Smith" };
 Sizes.argTypes = { size: { table: { disable: true } } };
+
+const stressAvatars = [
+  { key: "long-text", caption: "Long text prop", props: { text: "Administrator account" } },
+  { key: "unbroken", caption: "Unbroken alt", props: { alt: "Pneumonoultramicroscopicsilicovolcanoconiosis" } },
+  { key: "german", caption: "Long German name", props: { alt: "Maximilian-Alexander von Hohenzollern-Sigmaringen" } },
+  { key: "emoji", caption: "Emoji first", props: { alt: "🦄 Unicorn Team" } },
+  { key: "zwj", caption: "ZWJ family emoji", props: { alt: "👩‍👩‍👧 Family" } },
+  { key: "flags", caption: "Flag emoji", props: { alt: "🇬🇧 🇫🇷" } },
+  { key: "whitespace", caption: "Extra whitespace", props: { alt: "   Jane      Smith   " } },
+  { key: "text-blank", caption: "Whitespace text prop", props: { alt: "Jane Smith", text: "   " } },
+  { key: "single", caption: "Single character", props: { alt: "J" } },
+  { key: "empty", caption: "No alt, text or src", props: {} },
+  { key: "html", caption: "HTML-like alt", props: { alt: "<b>Bold</b> <script>" } },
+  { key: "rtl", caption: "Right-to-left", props: { alt: "محمد علي" }, dir: "rtl" },
+  { key: "wide", caption: "Widest glyphs", props: { text: "WW" } },
+  { key: "broken", caption: "Broken src", props: { src: "/does-not-exist.jpg", alt: "Jane Smith" } },
+  { key: "broken-no-alt", caption: "Broken src, no alt", props: { src: "/does-not-exist.jpg" } },
+  { key: "custom-size", caption: "Unknown size string", props: { alt: "Jane Smith", size: "huge" } },
+];
+
+export const StressTest: StoryFn<typeof StorybookComponent> = () => ({
+  components: { StorybookComponent },
+  setup() {
+    return { stressAvatars, sizes: ["xs", "s", "md", "lg", "xl"] };
+  },
+  template: `
+    ${googleReviewsNote}
+    <div style="display: grid; gap: 4.8rem; padding: 4rem 2rem; font: 1.2rem sans-serif;">
+      <div style="display: grid; grid-template-columns: repeat(auto-fill, minmax(14rem, 1fr)); gap: 3.2rem 2.4rem;">
+        <figure
+          v-for="avatar in stressAvatars"
+          :key="avatar.key"
+          :dir="avatar.dir"
+          style="margin: 0; display: grid; justify-items: center; align-content: start; gap: 1.2rem; min-inline-size: 0;"
+        >
+          <StorybookComponent v-bind="avatar.props" :chip="true" status="online" status-label="Online" />
+          <figcaption style="text-align: center; overflow-wrap: anywhere;">{{ avatar.caption }}</figcaption>
+        </figure>
+      </div>
+
+      <div style="display: flex; align-items: center; gap: 1.6rem;">
+        <StorybookComponent v-for="size in sizes" :key="size" :size="size" text="WW" />
+      </div>
+
+      <div style="display: grid; gap: 1.2rem; inline-size: 20rem; border: 1px dashed currentColor; padding: 0.8rem;">
+        <div v-for="size in sizes" :key="size" style="display: flex; align-items: center; gap: 0.8rem;">
+          <StorybookComponent :size="size" alt="Jane Smith" />
+          <span style="min-inline-size: 0; overflow-wrap: anywhere;">Averyveryverylongunbrokenusername@example.com</span>
+        </div>
+      </div>
+    </div>
+  `,
+});
+StressTest.storyName = "Stress Test (Worst-Case Data)";
+StressTest.parameters = {
+  // Fixed showcase: hardcoded values, so Controls would do nothing here.
+  controls: { disable: true },
+  docs: {
+    description: {
+      story:
+        "Hostile names and sources: long and unbroken text, emoji (including ZWJ and flags) at the start of a name, extra whitespace, a whitespace-only " +
+        "text prop, a single character, nothing at all, HTML-like and right-to-left text, the widest Latin glyphs at every size, broken image URLs with and " +
+        "without alt, and an unknown size string. The last block puts each size in a narrow flex row next to a long unbroken name. " +
+        "Check that initials are whole characters (never a broken half emoji), overlong text is clipped inside the circle rather than spilling out, " +
+        "a broken image falls back to initials (or an empty circle with no alt), an unknown size renders at md, and no avatar squashes into an oval in the narrow rows.",
+    },
+  },
+};

package/app/components/02.molecules/display-avatar/tests/DisplayAvatar.spec.ts

@@ -64,14 +64,15 @@ describe("DisplayAvatar", () => {
 
   // ─── Size ─────────────────────────────────────────────────────────────────
 
-  it("applies md size class by default", async () => {
+  it("sets data-size=\"md\" by default", async () => {
     const wrapper = await mountSuspended(DisplayAvatar);
-    expect(wrapper.classes()).toContain("md");
+    expect(wrapper.attributes("data-size")).toBe("md");
   });
 
-  it.each(["xs", "s", "md", "lg", "xl"] as const)("applies %s size class when size='%s'", async (size) => {
+  it.each(["xs", "s", "md", "lg", "xl"] as const)("sets data-size=\"%s\" when size='%s'", async (size) => {
     const wrapper = await mountSuspended(DisplayAvatar, { props: { size } });
-    expect(wrapper.classes()).toContain(size);
+    expect(wrapper.attributes("data-size")).toBe(size);
+    expect(wrapper.classes()).not.toContain(size);
   });
 
   // ─── Fallback text ────────────────────────────────────────────────────────
@@ -80,33 +81,33 @@ describe("DisplayAvatar", () => {
     const wrapper = await mountSuspended(DisplayAvatar, {
       props: { alt: "John Doe" },
     });
-    expect(wrapper.find(".display-avatar > span:first-child").text()).toBe("JD");
+    expect(wrapper.find(".display-avatar-fallback").text()).toBe("JD");
   });
 
   it("caps initials at two characters", async () => {
     const wrapper = await mountSuspended(DisplayAvatar, {
       props: { alt: "Alice Bob Charlie" },
     });
-    expect(wrapper.find(".display-avatar > span:first-child").text()).toBe("AB");
+    expect(wrapper.find(".display-avatar-fallback").text()).toBe("AB");
   });
 
   it("shows single initial for a single-word alt", async () => {
     const wrapper = await mountSuspended(DisplayAvatar, {
       props: { alt: "Alice" },
     });
-    expect(wrapper.find(".display-avatar > span:first-child").text()).toBe("A");
+    expect(wrapper.find(".display-avatar-fallback").text()).toBe("A");
   });
 
   it("shows text prop instead of alt-derived initials when text is set", async () => {
     const wrapper = await mountSuspended(DisplayAvatar, {
       props: { alt: "John Doe", text: "?" },
     });
-    expect(wrapper.find(".display-avatar > span:first-child").text()).toBe("?");
+    expect(wrapper.find(".display-avatar-fallback").text()).toBe("?");
   });
 
   it("shows empty fallback when neither src, text, nor alt are set", async () => {
     const wrapper = await mountSuspended(DisplayAvatar);
-    expect(wrapper.find(".display-avatar > span:first-child").text()).toBe("");
+    expect(wrapper.find(".display-avatar-fallback").text()).toBe("");
   });
 
   // ─── Image ────────────────────────────────────────────────────────────────
@@ -210,13 +211,13 @@ describe("DisplayAvatar", () => {
 
   it("hides the initials from screen readers and announces the alt instead", async () => {
     const wrapper = await mountSuspended(DisplayAvatar, { props: { alt: "John Doe" } });
-    expect(wrapper.find(".display-avatar > span:first-child").attributes("aria-hidden")).toBe("true");
+    expect(wrapper.find(".display-avatar-fallback").attributes("aria-hidden")).toBe("true");
     expect(wrapper.find(".sr-only").text()).toBe("John Doe");
   });
 
   it("leaves text-only fallback readable when there is no alt", async () => {
     const wrapper = await mountSuspended(DisplayAvatar, { props: { text: "?" } });
-    expect(wrapper.find(".display-avatar > span:first-child").attributes("aria-hidden")).toBeUndefined();
+    expect(wrapper.find(".display-avatar-fallback").attributes("aria-hidden")).toBeUndefined();
     expect(wrapper.find(".sr-only").exists()).toBe(false);
   });
 
@@ -225,11 +226,12 @@ describe("DisplayAvatar", () => {
     expect(wrapper.attributes("style-class-passthrough")).toBeUndefined();
   });
 
-  it("puts display-avatar, size and passthrough classes on the DisplayChip root", async () => {
+  it("puts display-avatar, data-size and passthrough classes on the DisplayChip root", async () => {
     const wrapper = await mountSuspended(DisplayAvatar, {
       props: { chip: true, size: "lg", styleClassPassthrough: ["online"] },
     });
-    expect(wrapper.classes()).toEqual(expect.arrayContaining(["display-chip", "display-avatar", "lg", "online"]));
+    expect(wrapper.classes()).toEqual(expect.arrayContaining(["display-chip", "display-avatar", "online"]));
+    expect(wrapper.attributes("data-size")).toBe("lg");
   });
 
   it("forwards status and statusLabel to the chip", async () => {
@@ -256,4 +258,74 @@ describe("DisplayAvatar", () => {
     await wrapper.setProps({ chip: { size: "20px", maskWidth: "2px", offset: "0px", angle: "0deg" } });
     expect(wrapper.findComponent(DisplayChip).props("config")).toMatchObject({ size: "20px" });
   });
+
+  // ─── Stress test 2026-10-14 ────────────────────────────────────────────────
+
+  const initialsFor = async (alt: string) => {
+    const wrapper = await mountSuspended(DisplayAvatar, { props: { alt } });
+    return wrapper.find(".display-avatar-fallback").text();
+  };
+
+  it("takes whole emoji as initials, not half a surrogate pair", async () => {
+    expect(await initialsFor("🦄 Unicorn")).toBe("🦄U");
+    expect(await initialsFor("👩‍👩‍👧 Family")).toBe("👩‍👩‍👧F");
+    expect(await initialsFor("🇬🇧 Team")).toBe("🇬🇧T");
+  });
+
+  it("ignores leading, trailing and repeated whitespace in alt", async () => {
+    expect(await initialsFor("  Jane    Smith  ")).toBe("JS");
+    expect(await initialsFor("Jane\tSmith")).toBe("JS");
+  });
+
+  it("falls back to alt initials when text is whitespace only", async () => {
+    const wrapper = await mountSuspended(DisplayAvatar, { props: { alt: "Jane Smith", text: "   " } });
+    expect(wrapper.find(".display-avatar-fallback").text()).toBe("JS");
+  });
+
+  it("renders HTML-like alt as text", async () => {
+    const wrapper = await mountSuspended(DisplayAvatar, { props: { alt: "<b>Bold</b> <script>" } });
+    expect(wrapper.find("b").exists()).toBe(false);
+    expect(wrapper.find(".sr-only").text()).toBe("<b>Bold</b> <script>");
+  });
+
+  it("passes a numeric width and height to the image", async () => {
+    const wrapper = await mountSuspended(DisplayAvatar, { props: { src: "/avatar.jpg" } });
+    const img = wrapper.find(".display-avatar-image");
+    expect(img.attributes("width")).toBe("112");
+    expect(img.attributes("height")).toBe("112");
+  });
+
+  it("uses imageSize for the image's width and height", async () => {
+    const wrapper = await mountSuspended(DisplayAvatar, { props: { src: "/avatar.jpg", imageSize: 240 } });
+    expect(wrapper.find(".display-avatar-image").attributes("width")).toBe("240");
+  });
+
+  it("shows the initials fallback when the image fails to load", async () => {
+    const wrapper = await mountSuspended(DisplayAvatar, { props: { src: "/broken.jpg", alt: "Jane Smith" } });
+    await wrapper.find(".display-avatar-image").trigger("error");
+    expect(wrapper.find(".display-avatar-image").exists()).toBe(false);
+    expect(wrapper.find(".display-avatar-fallback").text()).toBe("JS");
+    expect(wrapper.find(".sr-only").text()).toBe("Jane Smith");
+  });
+
+  it("tries the image again when src changes after a failure", async () => {
+    const wrapper = await mountSuspended(DisplayAvatar, { props: { src: "/broken.jpg", alt: "Jane Smith" } });
+    await wrapper.find(".display-avatar-image").trigger("error");
+    await wrapper.setProps({ src: "/working.jpg" });
+    expect(wrapper.find(".display-avatar-image").exists()).toBe(true);
+  });
+
+  it("wraps all content in one surface so the chip's per-child mask covers the whole avatar", async () => {
+    const wrapper = await mountSuspended(DisplayAvatar, {
+      props: { alt: "Jane Smith", chip: true },
+      slots: { icon: "<span class='status-icon'>●</span>" },
+    });
+    const masked = Array.from((wrapper.element as HTMLElement).children).filter(
+      (el) => !el.matches(".display-chip-icon, .display-chip-label, .sr-only")
+    );
+    expect(masked).toHaveLength(1);
+    expect(masked[0]!.classList.contains("display-avatar-surface")).toBe(true);
+    expect(masked[0]!.querySelector(".display-avatar-fallback")?.textContent).toBe("JS");
+    expect(masked[0]!.querySelector(".status-icon")).not.toBeNull();
+  });
 });

package/app/components/02.molecules/display-avatar/tests/__snapshots__/DisplayAvatar.spec.ts.snap

@@ -1,12 +1,12 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`DisplayAvatar > renders correct HTML structure (default) 1`] = `"<span class="display-avatar md"><span aria-hidden="true">JD</span><span class="sr-only">John Doe</span></span>"`;
+exports[`DisplayAvatar > renders correct HTML structure (default) 1`] = `"<span class="display-avatar" data-size="md"><span class="display-avatar-surface"><span class="display-avatar-fallback" aria-hidden="true">JD</span><span class="sr-only">John Doe</span></span></span>"`;
 
 exports[`DisplayAvatar > renders correct HTML structure (with chip) 1`] = `
-"<span class="display-chip display-avatar md" data-shape="circle" data-status="offline" style="--_chip-size: 12px; --_chip-mask-width: 4px; --_chip-offset: 0px; --_chip-angle: 90deg;"><span aria-hidden="true">JD</span><span class="sr-only">John Doe</span>
+"<span class="display-chip display-avatar" data-shape="circle" data-status="offline" style="--_chip-size: 12px; --_chip-mask-width: 4px; --_chip-offset: 0px; --_chip-angle: 90deg;" data-size="md"><span class="display-avatar-surface"><span class="display-avatar-fallback" aria-hidden="true">JD</span><span class="sr-only">John Doe</span></span>
 <!--v-if-->
 <!--v-if-->
 <!--v-if--></span>"
 `;
 
-exports[`DisplayAvatar > renders correct HTML structure (with src) 1`] = `"<span class="display-avatar lg"><img data-nuxt-img="" srcset="/_ipx/_/avatar.jpg 1x, /_ipx/_/avatar.jpg 2x" alt="John Doe" class="display-avatar-image" src="/_ipx/_/avatar.jpg"></span>"`;
+exports[`DisplayAvatar > renders correct HTML structure (with src) 1`] = `"<span class="display-avatar" data-size="lg"><span class="display-avatar-surface"><img width="112" height="112" data-nuxt-img="" srcset="/_ipx/s_112x112/avatar.jpg 1x, /_ipx/s_224x224/avatar.jpg 2x" alt="John Doe" class="display-avatar-image" src="/_ipx/s_112x112/avatar.jpg"></span></span>"`;

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

@@ -58,7 +58,10 @@ maths (`--_mask-diameter`, `--_position-x`, `--_position-y`, `--_offset`, `--_ci
 
 Inner elements: the dot is `.display-chip::after`; `.display-chip-icon` and `.display-chip-label`
 sit on top of it. The `statusLabel` text is a `.sr-only` span. Every other direct child gets the
-cutout `mask-image`.
+cutout `mask-image`. The mask is positioned in percentages of each child's own box, so the slot
+should be one element that fills the chip and carries any background: a small child (a bare text
+span) gets the notch cut into its own content, and a background on the root is never masked.
+`DisplayAvatar` uses a full-size `.display-avatar-surface` for this.
 
 > Changed 2026-10-08: shape and status are `data-shape`/`data-status` attributes instead of the
 > `.circle`/`.square` and `.online`/`.idle`/`.dnd` classes, so they can't collide with a
@@ -87,4 +90,6 @@ let the token apply.
 ## Class passthrough
 
 `style-class-passthrough` adds classes to the root `.display-chip`. Reactive after mount.
-`DisplayAvatar` with `chip` renders this component as its root, so the same applies there.
+`DisplayAvatar` with `chip` renders this component as its root, so the same applies there. Because the
+root element is shared, a wrapping component must not reuse this component's private token names
+(`--_size` especially) for its own values.

package/app/components/02.molecules/profile-section/CONSUMER-STYLING.md

@@ -2,35 +2,89 @@
 
 ## Public token API
 
+### Grid and picture
+
 | Token | Default | Controls |
 |---|---|---|
-| `--profile-section-gap` | `2rem` | Gap between picture and info, single column (below 768px) |
-| `--profile-section-gap-wide` | `4rem` | Gap between picture and info columns (768px+) |
-| `--profile-section-picture-width` | `384px` | Picture column width (768px+) |
+| `--profile-section-gap` | `2rem` | Gap between picture and info, single column (component under 768px wide) |
+| `--profile-section-gap-wide` | `4rem` | Gap between picture and info columns (component 768px wide or more) |
+| `--profile-section-picture-width` | `38.4rem` | Maximum picture column width in the two-column layout. The column can shrink below it |
 | `--profile-section-picture-aspect-ratio` | `3 / 4` | Picture frame aspect ratio |
-| `--profile-section-picture-border-radius` | `8px` | Picture frame corner rounding |
+| `--profile-section-picture-border-radius` | `0.8rem` | Picture frame corner rounding |
 | `--profile-section-info-block-gap` | `1.5rem` | Space after each `profile-info-N` block |
 | `--profile-section-links-gap` | `1rem` | Gap between items in the `profileLinks` slot |
+| `--profile-section-info-text-colour` | `inherit` | Text colour of the info column (blocks and links) |
+
+### Info block highlights
+
+| Token | Default | Controls |
+|---|---|---|
+| `--profile-section-highlight-colour` | `var(--colour-text-accent)` | `.highlight` inside a `.location` element |
+| `--profile-section-link-colour` | `var(--colour-link-default)` | `.highlight` inside a `.services` element |
+| `--profile-section-link-colour-hover` | `var(--colour-link-hover)` | The same, on hover |
+| `--profile-section-highlight-font-weight` | `600` | Weight of both highlight kinds (also sets the `wght` variation axis) |
+
+The defaults read the global `--colour-*` tokens, so setting those on an ancestor still works.
 
-Highlight colours inside info blocks read the global `--colour-text-accent`,
-`--colour-link-default` and `--colour-link-hover` (see **State hooks**).
+### Header in picture
 
+These only apply when `header-placement` is `picture-bottom` or `picture-top`. The scrim fades
+upward from the bottom edge for `picture-bottom` and downward from the top edge for `picture-top`.
+
+| Token | Default | Controls |
+|---|---|---|
+| `--profile-section-picture-header-scrim-colour` | `#000` | Colour the scrim starts from at the frame's edge |
+| `--profile-section-picture-header-scrim-opacity` | `75%` | Opacity of the scrim colour at its start |
+| `--profile-section-picture-header-scrim-solid-stop` | `0%` | How far into the header the scrim stays at full strength before it starts to fade (e.g. `55%` keeps it solid behind the text) |
+| `--profile-section-picture-header-scrim-target-colour` | `transparent` | Colour the scrim fades into at the header's inner edge. Set it to roughly the photo's colour there (often translucent) so the fade blends into the image instead of leaving a grey band or a visible edge |
+| `--profile-section-picture-header-scrim` | gradient from the scrim colour | The whole scrim `background`; set `none` to remove it |
+| `--profile-section-picture-header-text-colour` | `contrast-color(<scrim colour>)`, `#fff` without support | Eyebrow and heading text colour |
+| `--profile-section-picture-header-eyebrow-colour` | `inherit` | Eyebrow colour only |
+| `--profile-section-picture-header-padding` | `2.4rem` | Padding around the header inside the picture |
+| `--profile-section-picture-header-gap` | `0.4rem` | Gap between eyebrow and heading |
+
+Matching the photo is a judgement call per image: pick the target colour from the part of the photo
+the fade ends on, and add end padding (`--profile-section-picture-header-padding`, e.g.
+`3.2rem 3.2rem 6.4rem` for `picture-top`) so the fade sits past the text. The header only rounds the
+corners on the frame's edge, so an opaque target colour doesn't show rounded inner corners.
+Browsers without `color-mix()` (before Safari 16.2) start the scrim from 75% black whatever the scrim
+colour and opacity; the solid stop and target colour still apply.
+
+`contrast-color()` only reads the scrim colour, not the photo. If you remove the scrim, set
+`--profile-section-picture-header-text-colour` yourself to suit the image. The eyebrow's own
+`--eyebrow-text-bg-img` is set to `none` inside the picture.
+
+> Changed 2026-10-14: new `header-placement` prop and its tokens, and `--profile-section-info-text-colour`. The scrim
+> gained opacity, solid-stop and target-colour tokens. The image is now absolutely positioned
+> inside the frame (no visual change), so a header in the frame can grow it past its aspect ratio.
+>
+> Changed 2026-10-14: the highlight colours read the global `--colour-*` tokens directly; they now
+> go through the `--profile-section-*` tokens above, with the same defaults. `384px` and `8px`
+> became the same values in rem.
+>
 > Changed 2026-09-27: all of these were hardcoded values; they're now tokens with the same
 > defaults.
 
-No private `--_` tokens.
+Private tokens (not public API): `--_scrim-colour`, the resolved scrim colour used by the gradient
+and `contrast-color()`, `--_scrim-direction` (`to top` or `to bottom`, set by the placement), and
+`--_scrim-start-colour`, `--_scrim-solid-stop` and `--_scrim-target-colour`, which compose the
+gradient from the tokens above.
 
 ---
 
 ## State hooks
 
-Inner classes: `.profile-section-header`, `.profile-section-inner` (the grid),
-`.profile-section-picture` (frame), `.profile-section-image` (the `NuxtImg`),
-`.profile-section-info`, `.profile-section-info-content`, `.profile-section-info-block` (one per
-`profile-info-N` slot), `.profile-section-links`.
+Inner classes: `.profile-section-header` (only rendered when the `eyebrowText` or `heroText` slot
+is given; it moves inside `.profile-section-picture`, before the image, when `header-placement` is
+`picture-bottom` or `picture-top`), `.profile-section-inner` (the grid), `.profile-section-picture` (frame),
+`.profile-section-image` (the `NuxtImg`), `.profile-section-info`,
+`.profile-section-info-content`, `.profile-section-info-block` (one per `profile-info-N` slot
+given), `.profile-section-links`.
 
-Content hooks inside info blocks: an element with class `location` or `services` containing a
-`.highlight` gets a bold accent (`location`) or link (`services`) colour.
+`data-header-placement` on the root: `above`, `picture-bottom` or `picture-top`.
+
+Content hooks inside info blocks: a `.highlight` inside an element with class `location` or
+`services` gets the highlight or link colour above.
 
 > Changed 2026-09-27: renamed from `.picture`, `.profile-picture`, `.profile-info`,
 > `.profile-info-content`, `.profile-info-block` and `.profile-links`. `.picture` in particular
@@ -38,6 +92,35 @@ Content hooks inside info blocks: an element with class `location` or `services`
 
 ---
 
+## Layout
+
+The root is a size container named `profile-section` (`container: profile-section / inline-size`).
+The grid switches to two columns when **the component itself** is 768px wide or more, not the
+viewport, so it stays stacked in a narrow column or sidebar. Because it's an inline-size container,
+its width can't come from its content: in a flex row or other shrink-to-fit context, give it a
+width (`flex: 1`, `width: 100%`) or it collapses.
+
+Both grid columns are `minmax(0, …)`, so long unbroken text wraps (the root sets
+`overflow-wrap: anywhere`) instead of widening the grid. Profile links wrap onto more lines.
+
+To target the two-column layout in your own CSS, query the same container:
+
+```css
+.my-page .profile-section-inner {
+  @container profile-section (min-width: 768px) {
+    align-items: center;
+  }
+}
+```
+
+> Changed 2026-10-14: the breakpoint was a viewport `@media (min-width: 768px)` query. A
+> `@media (min-width: 768px)` override of `.profile-section-inner`'s `grid-template-columns` now
+> applies at a different point from the component's own switch. Remove it and set
+> `--profile-section-picture-width` instead (`minmax(0, 320px) 1fr` is
+> `--profile-section-picture-width: 32rem`, since the column is now `minmax(0, …)` by default).
+
+---
+
 ## Local overrides
 
 Set the tokens above on an element you own (a page or section class, or a class added with
@@ -51,3 +134,10 @@ Set the tokens above on an element you own (a page or section class, or a class
 ## Class passthrough
 
 `style-class-passthrough` adds classes to the root element. Reactive after mount.
+
+---
+
+## Notes
+
+There are no line-clamp tokens. All text comes through slots, so it is your own markup: clamp it
+there, for example with `-webkit-line-clamp` on your own paragraph class.