srcdev-nuxt-components 9.6.0 → 9.6.2

package/app/components/02.molecules/alert-content/AlertContent.vue

@@ -1,5 +1,5 @@
 <template>
-  <div class="alert-content" :data-theme="theme">
+  <div class="alert-content" :class="[elementClasses]" :data-theme="theme">
     <AlertContentInner
       :theme="theme"
       :custom-icon="customIcon"
@@ -41,19 +41,28 @@ interface Props {
   dismissible?: boolean;
   contentId?: string;
   ariaLive?: "polite" | "assertive" | "off";
+  styleClassPassthrough?: string | string[];
 }
 
-withDefaults(defineProps<Props>(), {
+const props = withDefaults(defineProps<Props>(), {
   customIcon: undefined,
   showIcon: true,
   dismissible: false,
   contentId: undefined,
   ariaLive: undefined,
+  styleClassPassthrough: () => [],
 });
 
 const emit = defineEmits<{ dismiss: [] }>();
 
 const slots = useSlots();
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => resetElementClasses(props.styleClassPassthrough)
+);
 </script>
 
 <style lang="css">

package/app/components/02.molecules/alert-content/AlertContentInner.vue

@@ -89,6 +89,7 @@ const dismissIcon = computed(() => appConfig.srcdev?.alertContent?.dismissIcon ?
     border-start-start-radius: var(--alert-content-border-radius-start, 0.8rem);
     border-end-start-radius: var(--alert-content-border-radius-start, 0.8rem);
     padding: var(--alert-content-padding, 1.2rem 1.5rem);
+    min-inline-size: 0;
     overflow: hidden;
 
     .alert-content-icon {
@@ -124,6 +125,12 @@ const dismissIcon = computed(() => appConfig.srcdev?.alertContent?.dismissIcon ?
         font-weight: 600;
         line-height: 1.2;
         margin: 0;
+        display: -webkit-box;
+        -webkit-box-orient: vertical;
+        overflow: hidden;
+        overflow-wrap: anywhere;
+        -webkit-line-clamp: var(--alert-content-title-line-clamp, none);
+        line-clamp: var(--alert-content-title-line-clamp, none);
       }
 
       .alert-content-text {
@@ -132,6 +139,12 @@ const dismissIcon = computed(() => appConfig.srcdev?.alertContent?.dismissIcon ?
         line-height: 1.4;
         margin: 0;
         opacity: 0.9;
+        display: -webkit-box;
+        -webkit-box-orient: vertical;
+        overflow: hidden;
+        overflow-wrap: anywhere;
+        -webkit-line-clamp: var(--alert-content-text-line-clamp, none);
+        line-clamp: var(--alert-content-text-line-clamp, none);
       }
     }
 
@@ -141,6 +154,12 @@ const dismissIcon = computed(() => appConfig.srcdev?.alertContent?.dismissIcon ?
       align-items: center;
       justify-content: var(--alert-content-actions-justify, flex-end);
       gap: var(--alert-content-actions-gap, 0.8rem);
+      --input-button-text-white-space: normal;
+
+      & > * {
+        min-inline-size: 0;
+        max-inline-size: 100%;
+      }
     }
 
     .alert-content-dismiss {

package/app/components/02.molecules/alert-content/CONSUMER-STYLING.md

@@ -28,6 +28,8 @@ Covers `AlertContent` and its inner `AlertContentInner`. The inner tokens also a
 | `--alert-content-body-gap` | `0.4rem` | Gap between title and message |
 | `--alert-content-title-font-size` | `var(--step-4)` | Title size |
 | `--alert-content-text-font-size` | `var(--step-3)` | Message size |
+| `--alert-content-title-line-clamp` | `none` | Max title lines before an ellipsis (`1` = single-line ellipsis, `none` = show everything) |
+| `--alert-content-text-line-clamp` | `none` | Max message lines before an ellipsis. Leave it at `none` for messages people must read in full (errors, consent text): clamped text is still read by screen readers but hidden from sighted users |
 | `--alert-content-actions-spacing` | `1.2rem` | Space between the message and the actions row |
 | `--alert-content-actions-gap` | `0.8rem` | Gap between action controls |
 | `--alert-content-actions-justify` | `flex-end` | Horizontal alignment of the actions row (`justify-content`) |
@@ -42,6 +44,9 @@ Covers `AlertContent` and its inner `AlertContentInner`. The inner tokens also a
 | `--alert-content-dismiss-colour-hover` | `var(--theme-on-surface)` | Icon colour on hover/focus |
 | `--alert-content-dismiss-ring` | `var(--theme-ring)` | Focus/hover outline colour |
 
+> **Changed 2026-10-08**: added the two line-clamp tokens. The title and message now wrap long
+> unbroken strings (`overflow-wrap: anywhere`) instead of being clipped at the alert's edge.
+
 > **Changed 2026-09-27**: every value above except `--alert-content-inner-background` was hardcoded
 > (or read a `--theme-*` token directly, CLAUDE.md pitfall #14). Defaults are unchanged apart from
 > the px radii and stripe width, which are now the same sizes in rem. The icon and dismiss colours now
@@ -66,8 +71,8 @@ radius tokens once for the four corners.
 
 ## Local overrides
 
-Set the tokens above on an element you own (a page or section class, or a plain `class` on the
-component, which falls through to the root `.alert-content`): they inherit down into the component.
+Set the tokens above on an element you own (a page or section class, or a `:style-class-passthrough`
+class on the component, which lands on the root `.alert-content`): they inherit down into the component.
 Keep the block **unlayered** (no `@layer` wrapper) so it beats the library's `@layer components`. If
 your own file uses `<style scoped>`, tokens set on your element still work, but selectors that reach
 inside the component need `:deep()`. Patterns and examples:
@@ -78,7 +83,15 @@ don't reach it: the alert always uses its own `theme` prop's palette. Override t
 tokens instead. When it's rendered by `DisplayToast`/`DisplayToastProvider` it's teleported to
 `<body>`, so set tokens globally or through the toast's own hooks rather than on a page wrapper.
 
+**Caveat:** `.alert-content-actions` sets `--input-button-text-white-space: normal`, so an
+`InputButton` in the `#actions` slot wraps a long label instead of spilling out of the alert. A value
+for that token set on an ancestor doesn't reach buttons inside the actions row; set it on the button
+itself (its own `style-class-passthrough` class) if you need `nowrap` there.
+
 ## Class passthrough
 
-No `style-class-passthrough` prop. A plain `class` attribute falls through to the root `.alert-content`
-(`AlertContent` has a single root), which is enough for setting tokens on one instance.
+`style-class-passthrough` adds classes to the root `.alert-content`, so it's the hook for setting tokens
+on one instance. A plain `class` attribute lands there too (single root). Components that render
+`AlertContent` for you (`DisplayToast`, `DisplayPrompt`, `CookieConsentBanner`) don't forward it.
+
+> **Changed 2026-10-08**: added the prop. Before this, a plain `class` was the only option.

package/app/components/02.molecules/alert-content/stories/AlertContent.stories.ts

@@ -1,11 +1,34 @@
+import { computed, ref } from "vue";
 import type { Meta, StoryObj } from "@nuxtjs/storybook";
 import AlertContent from "../AlertContent.vue";
 import InputButton from "../../../05.forms/input-button/InputButton.vue";
+import CanvasSwitcher from "../../../01.atoms/canvas-switcher/CanvasSwitcher.vue";
+import type { MediaCanvas } from "~/types/components";
 
-const meta: Meta<typeof AlertContent> = {
+type LineClamp = "none" | "1" | "2" | "3" | "4";
+
+// Story-only args: drive CSS tokens, not AlertContent props. See their argTypes entries.
+type StoryArgs = InstanceType<typeof AlertContent>["$props"] & {
+  titleLineClamp: LineClamp;
+  textLineClamp: LineClamp;
+};
+
+const lineClampArgType = (token: string, example: string) => ({
+  control: "select" as const,
+  options: ["none", "1", "2", "3", "4"] satisfies LineClamp[],
+  description:
+    `**Story control, not a prop.** Sets the \`${token}\` CSS token on a wrapper so you can try it here. ` +
+    `To use it in an app, set the token in your own CSS, e.g. \`.site-notice { ${token}: ${example}; }\`. ` +
+    "`1` is single-line ellipsis, `none` (the default) shows everything. Don't clamp messages people need to read in full.",
+  table: { category: "CSS tokens (story only, set in your CSS)", defaultValue: { summary: "none" } },
+});
+
+const meta: Meta<StoryArgs> = {
   title: "Molecules/AlertContent",
   component: AlertContent,
   argTypes: {
+    titleLineClamp: lineClampArgType("--alert-content-title-line-clamp", "1"),
+    textLineClamp: lineClampArgType("--alert-content-text-line-clamp", "3"),
     theme: {
       control: { type: "inline-radio" },
       options: ["info", "success", "warning", "error"],
@@ -27,6 +50,11 @@ const meta: Meta<typeof AlertContent> = {
       description: "Show a close button (emits 'dismiss' on click)",
       table: { category: "Behaviour" },
     },
+    styleClassPassthrough: {
+      control: "object",
+      description: "Additional CSS classes applied to the root element",
+      table: { category: "Styling" },
+    },
     contentId: { table: { disable: true } },
     ariaLive: { table: { disable: true } },
   },
@@ -34,22 +62,53 @@ const meta: Meta<typeof AlertContent> = {
     theme: "info",
     showIcon: true,
     dismissible: false,
+    titleLineClamp: "none",
+    textLineClamp: "none",
   },
 };
 
 export default meta;
-type Story = StoryObj<typeof AlertContent>;
+type Story = StoryObj<StoryArgs>;
+
+// Links open in the Storybook manager (target="_top"), not inside the preview iframe.
+const storyNoteStyle = "margin: 0 0 1.6rem; font-size: 1.4rem;";
+const toastNote = `
+  <p style="${storyNoteStyle}">
+    To see the dismiss action and auto-dismiss in context, open the
+    <a href="/?path=/story/molecules-displaytoast--default" target="_top">DisplayToast</a> and
+    <a href="/?path=/story/molecules-displaytoastprovider--default" target="_top">DisplayToastProvider</a> stories.
+  </p>
+`;
+const cookieNote = `
+  <p style="${storyNoteStyle}">
+    For the #actions slot wired up to real accept and reject handlers, open the
+    <a href="/?path=/story/molecules-cookieconsentbanner--default" target="_top">CookieConsentBanner</a> story.
+  </p>
+`;
+
+function useStorySetup(args: StoryArgs) {
+  const componentArgs = computed(() => {
+    const { titleLineClamp: _titleLineClamp, textLineClamp: _textLineClamp, ...rest } = args;
+    return rest;
+  });
+  const tokenStyles = computed(() => ({
+    "--alert-content-title-line-clamp": args.titleLineClamp,
+    "--alert-content-text-line-clamp": args.textLineClamp,
+  }));
+  return { args, componentArgs, tokenStyles };
+}
 
 /** Default — info theme with title and body content. */
 export const Default: Story = {
   render: (args) => ({
     components: { AlertContent },
     setup() {
-      return { args };
+      return useStorySetup(args);
     },
     template: `
-      <div :data-theme="args.theme" style="max-width: 600px; padding: 2rem;">
-        <AlertContent v-bind="args">
+      <div :data-theme="args.theme" :style="tokenStyles" style="max-width: 600px; padding: 2rem;">
+        ${toastNote}
+        <AlertContent v-bind="componentArgs">
           <template #title>Alert title</template>
           <template #content>This is the alert body. It describes what happened and what the user should do next.</template>
         </AlertContent>
@@ -64,11 +123,12 @@ export const Dismissible: Story = {
   render: (args) => ({
     components: { AlertContent },
     setup() {
-      return { args };
+      return useStorySetup(args);
     },
     template: `
-      <div :data-theme="args.theme" style="max-width: 600px; padding: 2rem;">
-        <AlertContent v-bind="args">
+      <div :data-theme="args.theme" :style="tokenStyles" style="max-width: 600px; padding: 2rem;">
+        ${toastNote}
+        <AlertContent v-bind="componentArgs">
           <template #title>Dismissible alert</template>
           <template #content>Click the close button to emit the dismiss event.</template>
         </AlertContent>
@@ -84,11 +144,12 @@ export const TitleOnly: Story = {
   render: (args) => ({
     components: { AlertContent },
     setup() {
-      return { args };
+      return useStorySetup(args);
     },
     template: `
-      <div :data-theme="args.theme" style="max-width: 600px; padding: 2rem;">
-        <AlertContent v-bind="args">
+      <div :data-theme="args.theme" :style="tokenStyles" style="max-width: 600px; padding: 2rem;">
+        ${toastNote}
+        <AlertContent v-bind="componentArgs">
           <template #title>Your changes have been saved.</template>
         </AlertContent>
       </div>
@@ -103,11 +164,12 @@ export const CustomIcon: Story = {
   render: (args) => ({
     components: { AlertContent },
     setup() {
-      return { args };
+      return useStorySetup(args);
     },
     template: `
-      <div :data-theme="args.theme" style="max-width: 600px; padding: 2rem;">
-        <AlertContent v-bind="args">
+      <div :data-theme="args.theme" :style="tokenStyles" style="max-width: 600px; padding: 2rem;">
+        ${toastNote}
+        <AlertContent v-bind="componentArgs">
           <template #title>Custom icon via prop</template>
           <template #content>The icon is overridden using the customIcon prop.</template>
         </AlertContent>
@@ -126,6 +188,7 @@ export const AllThemes: Story = {
     },
     template: `
       <div style="display: flex; flex-direction: column; gap: 1.6rem; max-width: 600px; padding: 2rem;">
+        ${toastNote}
         <div v-for="theme in themes" :key="theme" :data-theme="theme">
           <AlertContent :theme="theme" :dismissible="true">
             <template #title>{{ theme.charAt(0).toUpperCase() + theme.slice(1) }}</template>
@@ -144,11 +207,12 @@ export const WithActions: Story = {
   render: (args) => ({
     components: { AlertContent, InputButton },
     setup() {
-      return { args };
+      return useStorySetup(args);
     },
     template: `
-      <div :data-theme="args.theme" style="max-width: 600px; padding: 2rem;">
-        <AlertContent v-bind="args">
+      <div :data-theme="args.theme" :style="tokenStyles" style="max-width: 600px; padding: 2rem;">
+        ${cookieNote}
+        <AlertContent v-bind="componentArgs">
           <template #title>Cookies</template>
           <template #content>This site uses cookies to understand how it's used. You can accept or reject them.</template>
           <template #actions>
@@ -163,8 +227,127 @@ export const WithActions: Story = {
     docs: {
       description: {
         story:
+          "For the slot wired to real handlers, see the [CookieConsentBanner](?path=/story/molecules-cookieconsentbanner--default) story. " +
           "The #actions slot renders a wrapping row under the message, outside the aria-live/contentId body so the buttons aren't announced or pulled into aria-describedby. Actions are right-aligned by default (--alert-content-actions-justify). The cookie icon comes from customIcon; set showIcon to false to drop the icon column.",
       },
     },
   },
 };
+
+const stressAlerts = [
+  {
+    key: "german",
+    theme: "error",
+    dismissible: true,
+    title: "Donaudampfschifffahrtselektrizitätenhauptbetriebswerkbauunterbeamtengesellschaft",
+    content:
+      "Ihre Zahlung konnte leider nicht verarbeitet werden. Bitte überprüfen Sie Ihre Kartendaten und versuchen Sie es erneut, oder wenden Sie sich an Ihre Bank. https://example.com/zahlungen/fehler/a-very-long-path-segment-without-any-spaces-at-all-in-it",
+    actions: ["Zahlungsinformationenaktualisierung", "Kundendienstmitarbeiterkontaktaufnahme"],
+  },
+  {
+    key: "emoji-html",
+    theme: "warning",
+    dismissible: true,
+    title: "🚨🔥 Heads up <script>alert('xss')</script>",
+    content: "<b>Not bold</b> &amp; <img src=x onerror=alert(1)> should all render as plain text. 👍🏽👨‍👩‍👧‍👦",
+  },
+  {
+    key: "rtl",
+    theme: "info",
+    dir: "rtl",
+    dismissible: true,
+    title: "تنبيه مهم بخصوص حسابك",
+    content: "تم تحديث شروط الخدمة. يرجى مراجعة التغييرات قبل المتابعة لاستخدام الموقع.",
+  },
+  {
+    key: "single-char",
+    theme: "success",
+    title: "Ok",
+  },
+  {
+    key: "broken-icon-empty-title",
+    theme: "info",
+    customIcon: "not-a-real-set:missing-icon",
+    title: "",
+    content: "Broken customIcon name and an empty title slot.",
+  },
+  {
+    key: "content-only-no-icon",
+    theme: "success",
+    showIcon: false,
+    content: "x",
+  },
+];
+
+/**
+ * Stress test — hostile content across several alerts, inside the CanvasSwitcher so it can be
+ * checked at every width.
+ */
+export const StressTest: Story = {
+  name: "Stress Test (Worst-Case Data)",
+  args: { titleLineClamp: "none", textLineClamp: "none" },
+  decorators: [
+    (story, context) => ({
+      components: { story, CanvasSwitcher },
+      setup() {
+        const canvasName = ref<MediaCanvas>(context.parameters.initialCanvas ?? "mobileCanvas");
+        return { canvasName };
+      },
+      template: `
+        <div style="padding: 1.2rem 1.6rem; border-block-end: 1px solid currentColor;">
+          <CanvasSwitcher v-model:canvas-name="canvasName" />
+        </div>
+        <div :class="canvasName" style="margin-inline: auto; padding: 2rem; outline: 1px dashed currentColor;">
+          <story />
+        </div>
+      `,
+    }),
+  ],
+  render: (args) => ({
+    components: { AlertContent, InputButton },
+    setup() {
+      return { ...useStorySetup(args), stressAlerts };
+    },
+    template: `
+      <div :style="tokenStyles" style="display: grid; gap: 1.6rem;">
+        ${toastNote}
+        <div v-for="alert in stressAlerts" :key="alert.key" :data-theme="alert.theme" :dir="alert.dir">
+          <AlertContent
+            :theme="alert.theme"
+            :custom-icon="alert.customIcon"
+            :show-icon="alert.showIcon ?? true"
+            :dismissible="alert.dismissible ?? false"
+          >
+            <template v-if="alert.title !== undefined" #title>{{ alert.title }}</template>
+            <template v-if="alert.content" #content>{{ alert.content }}</template>
+            <template v-if="alert.actions" #actions>
+              <InputButton
+                v-for="label in alert.actions"
+                :key="label"
+                type="button"
+                variant="primary"
+                :button-text="label"
+              />
+            </template>
+            <template v-if="alert.dir === 'rtl'" #dismissLabel>إغلاق</template>
+          </AlertContent>
+        </div>
+      </div>
+    `,
+  }),
+  parameters: {
+    layout: "fullscreen",
+    initialCanvas: "mobileCanvas",
+    docs: {
+      description: {
+        story:
+          "Hostile content: an unbroken German compound as the title, long German copy ending in a long URL, long German button labels, " +
+          "emoji at the start, HTML-like text (must render as text), right-to-left Arabic, a two-character title, an empty title slot, " +
+          "a broken customIcon name, and a one-character message with no icon. Check at every CanvasSwitcher width that nothing overflows " +
+          "or gets clipped by the alert's rounded edge, unbroken text wraps, the action buttons wrap their labels instead of spilling out, " +
+          "the icon and dismiss button keep their size, and the RTL alert puts the accent stripe on the right. " +
+          "The two line-clamp controls are CSS tokens (story only), not props: try `1` to see single-line ellipsis.",
+      },
+    },
+  },
+};

package/app/components/02.molecules/alert-content/tests/AlertContent.spec.ts

@@ -156,6 +156,39 @@ describe("AlertContent", () => {
     expect(wrapper.find("[data-test-id='alert-actions']").exists()).toBe(false);
   });
 
+  // ─── styleClassPassthrough / hostile text (added 2026-10-08) ────────────────
+
+  it("applies styleClassPassthrough classes to the root", async () => {
+    const wrapper = await mountSuspended(AlertContent, {
+      props: { theme: "info", styleClassPassthrough: ["site-notice", "is-wide"] },
+    });
+    expect(wrapper.find(".alert-content").classes()).toEqual(expect.arrayContaining(["site-notice", "is-wide"]));
+  });
+
+  it("updates root classes when styleClassPassthrough changes", async () => {
+    const wrapper = await mountSuspended(AlertContent, {
+      props: { theme: "info", styleClassPassthrough: "first-class" },
+    });
+    await wrapper.setProps({ styleClassPassthrough: "second-class" });
+    const classes = wrapper.find(".alert-content").classes();
+    expect(classes).toContain("second-class");
+    expect(classes).not.toContain("first-class");
+  });
+
+  it("renders HTML-like slot text as text, not markup", async () => {
+    const wrapper = await mountSuspended(
+      {
+        components: { AlertContent },
+        setup: () => ({ text: "<img src=x onerror=alert(1)>" }),
+        template: `<AlertContent theme="info"><template #content>{{ text }}</template></AlertContent>`,
+      },
+      {}
+    );
+    const content = wrapper.find("[data-test-id='alert-content']");
+    expect(content.find("img").exists()).toBe(false);
+    expect(content.text()).toBe("<img src=x onerror=alert(1)>");
+  });
+
   it("uses component-prefixed classes for the title and text", async () => {
     const wrapper = await mountSuspended(AlertContent, {
       props: { theme: "info" },

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,18 +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).
-- With `chip`, the root is `DisplayChip`, so it also carries `.display-chip` and its shape
-  class; status classes such as `.online` (through `style-class-passthrough`) are `DisplayChip`'s.
-  See `display-chip` for its tokens.
-
+- `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`.
 
@@ -53,11 +72,10 @@ 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.
 
 ## Class passthrough
 
-`style-class-passthrough` adds classes to the root, including when the root is `DisplayChip`. That's
-how chip status classes like `online` are applied.
+`style-class-passthrough` adds classes to the root, including when the root is `DisplayChip`.