srcdev-nuxt-components 9.6.1 → 9.6.3

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/input-copy/stories/InputCopy.stories.ts

@@ -4,7 +4,6 @@ import InputCopy from "../InputCopy.vue";
 const meta: Meta<typeof InputCopy> = {
   title: "Molecules/Input Copy",
   component: InputCopy,
-  tags: ["autodocs"],
   argTypes: {
     value: { control: "text" },
     id: {