srcdev-nuxt-components 9.6.0 → 9.6.2

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

@@ -1,24 +1,35 @@
 <template>
   <component
     :is="chip ? DisplayChip : as"
-    v-bind="chip ? { tag: chipTag, config: chipConfig } : {}"
+    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>
 
 <script setup lang="ts">
 import DisplayChip from "../display-chip/DisplayChip.vue";
-import type { DisplayChipConfig } from "~/types/components";
+import type { DisplayChipConfig, DisplayChipStatus } from "~/types/components";
 
 interface Props {
   as?: string | object;
@@ -27,6 +38,9 @@ interface Props {
   text?: string;
   size?: "xs" | "s" | "md" | "lg" | "xl" | string;
   chip?: boolean | DisplayChipConfig;
+  status?: DisplayChipStatus;
+  statusLabel?: string;
+  imageSize?: number;
   styleClassPassthrough?: string | string[];
 }
 
@@ -37,6 +51,9 @@ const props = withDefaults(defineProps<Props>(), {
   text: undefined,
   size: "md",
   chip: undefined,
+  status: undefined,
+  statusLabel: undefined,
+  imageSize: 112,
   styleClassPassthrough: () => [],
 });
 
@@ -47,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 = {
@@ -72,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

@@ -56,6 +56,21 @@ export default {
         category: "Chip Configuration",
       },
     },
+    status: {
+      control: { type: "inline-radio" },
+      options: ["offline", "online", "idle", "dnd"],
+      description: "Chip status colour (forwarded to DisplayChip)",
+      table: {
+        category: "Chip Configuration",
+      },
+    },
+    statusLabel: {
+      control: { type: "text" },
+      description: "Screen-reader text for the chip status, e.g. 'Online' (forwarded to DisplayChip)",
+      table: {
+        category: "Chip Configuration",
+      },
+    },
     // Hide the chip prop from controls since we're using individual controls
     chip: {
       table: {
@@ -77,10 +92,22 @@ export default {
     chipMaskWidth: 4,
     chipOffset: 2,
     chipAngle: 45,
-    styleClassPassthrough: ["test-storybook--display-avatar", "online"],
+    status: "online",
+    statusLabel: "Online",
+    styleClassPassthrough: ["test-storybook--display-avatar"],
   },
 } 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(() => ({
@@ -96,12 +123,15 @@ 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"
         :alt="args.alt"
         :chip="chip"
+        :status="args.status"
+        :status-label="args.statusLabel"
         :style-class-passthrough="args.styleClassPassthrough"
       />
     </div>
@@ -116,9 +146,10 @@ 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;">
-      <StorybookComponent :size="args.size" :alt="args.alt" :chip="chip" :style-class-passthrough="args.styleClassPassthrough" />
-      <StorybookComponent :size="args.size" text="?" :chip="chip" :style-class-passthrough="args.styleClassPassthrough" />
+    ${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>
   `,
 });
@@ -131,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"
@@ -139,6 +171,8 @@ export const Sizes: StoryFn<typeof StorybookComponent> = (args) => ({
         :src="args.src"
         :alt="args.alt"
         :chip="chip"
+        :status="args.status"
+        :status-label="args.statusLabel"
         :style-class-passthrough="args.styleClassPassthrough"
       />
     </div>
@@ -146,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,31 @@ 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 () => {
+    const wrapper = await mountSuspended(DisplayAvatar, {
+      props: { chip: true, alt: "Jane Smith", status: "dnd", statusLabel: "Do not disturb" },
+    });
+    expect(wrapper.attributes("data-status")).toBe("dnd");
+    expect(wrapper.findAll(".sr-only").map((el) => el.text())).toContain("Do not disturb");
+  });
+
+  it("leaves the chip offline when no status is given", async () => {
+    const wrapper = await mountSuspended(DisplayAvatar, { props: { chip: true } });
+    expect(wrapper.attributes("data-status")).toBe("offline");
+  });
+
+  it("does not put status attributes on a plain avatar", async () => {
+    const wrapper = await mountSuspended(DisplayAvatar, { props: { status: "online" } });
+    expect(wrapper.attributes("data-status")).toBeUndefined();
+    expect(wrapper.attributes("status")).toBeUndefined();
   });
 
   it("updates the chip config when the chip prop changes", async () => {
@@ -237,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,11 +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 circle display-avatar md" 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

@@ -2,19 +2,35 @@
 
 ## Public token API
 
+### Geometry
+
 | Token | Default | Controls |
 |---|---|---|
-| `--display-chip-colour-offline` | `slategrey` | Dot colour with no status class |
-| `--display-chip-colour-online` | `rgb(0, 255, 135)` | Dot colour with `.online` |
-| `--display-chip-colour-idle` | `rgb(255, 185, 51)` | Dot colour with `.idle` |
-| `--display-chip-colour-dnd` | `rgb(255, 40, 80)` | Dot colour with `.dnd` |
+| `--display-chip-size` | `1.2rem` | Dot diameter. Negative values clamp to `0` (no dot) |
+| `--display-chip-mask-width` | `0.4rem` | Width of the cutout ring around the dot. Negative values clamp to `0` |
+| `--display-chip-offset` | `0rem` | Extra distance from the host's edge (negative pulls the dot inwards) |
+| `--display-chip-angle` | `90deg` | Position around the host, clockwise from the top |
+
+A field set in the `config` prop wins over its token for that chip. Fields left out of `config` fall
+back to the token, so `:config="{ label: '5' }"` gets the default geometry.
+
+> Changed 2026-10-08: geometry tokens are new. Before, geometry came only from `config`, and a
+> `config` missing any of `size`/`maskWidth`/`offset`/`angle` broke the dot and cutout entirely.
+
+### Colour
+
+| Token | Default | Controls |
+|---|---|---|
+| `--display-chip-colour-offline` | `var(--status-neutral)` | Dot colour for `status="offline"` (the default) |
+| `--display-chip-colour-online` | `var(--status-success)` | Dot colour for `status="online"` |
+| `--display-chip-colour-idle` | `var(--status-warning)` | Dot colour for `status="idle"` |
+| `--display-chip-colour-dnd` | `var(--status-danger)` | Dot colour for `status="dnd"` |
 | `--display-chip-text-colour` | `black` | Icon and label colour on the dot |
 
-Geometry (size, mask width, offset, angle) is set through the `config` prop, not tokens. Those
-values are written inline as private `--_chip-size`, `--_chip-mask-width`, `--_chip-offset` and
-`--_chip-angle`, which feed the private position maths (`--_mask-diameter`, `--_position-x`,
-`--_position-y`, `--_offset`, `--_circle-x`, `--_circle-y`) and the resolved `--_dot-colour`. None
-of these are public API.
+Private tokens (not public API): `--_chip-size`, `--_chip-mask-width`, `--_chip-offset` and
+`--_chip-angle` (written inline from `config` or the geometry tokens), `--_size`, and the position
+maths (`--_mask-diameter`, `--_position-x`, `--_position-y`, `--_offset`, `--_circle-x`,
+`--_circle-y`), plus the resolved `--_dot-colour` and the label's `--_font-size-adjust`.
 
 > Changed 2026-09-27: the status colours were unprefixed `--color-offline`, `--color-online`,
 > `--color-idle` and `--color-dnd`, and the geometry and maths vars were unprefixed too
@@ -22,20 +38,37 @@ of these are public API.
 > consumer variable of the same name. The icon is now sized with `font-size` (its old
 > `width`/`height` were overridden by `@nuxt/icon`), and the icon/label colour is a token instead
 > of a hardcoded `black`.
+>
+> Changed 2026-10-07: the status colours default to the global `--status-*` tokens
+> (`03.theming/_status.css`) instead of hardcoded neon `rgb()` values and `slategrey`, so they
+> match `DisplayPill`, `SelectMenu` and anything else reading the shared set. To keep the old
+> look, set the four `--display-chip-colour-*` tokens to the previous values. To restyle every
+> status across the library, override `--status-*` instead. See
+> `.claude/skills/theming-status-tokens.md`.
 
 ---
 
 ## State hooks
 
-| Class | When |
-|---|---|
-| `.display-chip.circle`, `.square` | The `shape` prop (must match the slotted content's shape) |
-| `.online`, `.idle`, `.dnd` | Added by you through `style-class-passthrough`; no class means offline |
+| Hook | Element | When |
+|---|---|---|
+| `[data-shape="circle\|square"]` | `.display-chip` (root) | The `shape` prop (must match the slotted content's shape) |
+| `[data-status="offline\|online\|idle\|dnd"]` | `.display-chip` (root) | The `status` prop (default `offline`) |
+| `[data-length="1\|2\|3"]` | `.display-chip-label` | Label length in characters (emoji count as one), for font-size stepping |
 
-Inner elements: the dot is `.display-chip::after`; `.chip-icon` and `.chip-label` (with
-`.length-1`/`.length-2`/`.length-3` for font-size stepping) sit on top of it. Every other direct
-child gets the cutout `mask-image`.
+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`. 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
+> consumer's own classes of the same name. Status is now the `status` prop rather than a class
+> passed through `style-class-passthrough`. `.chip-icon` → `.display-chip-icon`, `.chip-label` →
+> `.display-chip-label`, and its `.length-N` classes → `data-length="N"`.
+>
 > Changed 2026-09-27: root class renamed from `.display-chip-core`.
 
 ---
@@ -48,10 +81,15 @@ Set the tokens above on an element you own (a page or section class, or a class
 `<style scoped>`, tokens set on your element still work, but selectors that reach inside the component need
 `:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
 
+**Caveat:** a geometry field set in `config` is written inline on the chip, so it beats the
+matching `--display-chip-*` geometry token from any ancestor. Leave the field out of `config` to
+let the token apply.
+
 ---
 
 ## Class passthrough
 
-`style-class-passthrough` adds classes to the root `.display-chip`. It's also how you set the
-status (`online`, `idle`, `dnd`). Reactive after mount. `DisplayAvatar` with `chip` renders this
-component as its root, so the same applies there.
+`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. Because the
+root element is shared, a wrapping component must not reuse this component's private token names
+(`--_size` especially) for its own values.