srcdev-nuxt-components 9.6.5 → 9.6.6

package/app/components/02.molecules/social-icons-list/tests/SocialIconsList.spec.ts

@@ -1,8 +1,22 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { h } from "vue";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
 import SocialIconsList from "../SocialIconsList.vue";
 import type { ISocialIcon } from "~/types/components/social-icons-list.d";
 
+const mounted: { unmount: () => void }[] = [];
+
+async function mountList(props: Record<string, unknown>) {
+  const wrapper = await mountSuspended(SocialIconsList, { props: props as { items: ISocialIcon[] } });
+  mounted.push(wrapper);
+  return wrapper;
+}
+
+afterEach(() => {
+  mounted.splice(0).forEach((wrapper) => wrapper.unmount());
+  vi.restoreAllMocks();
+});
+
 const defaultItems: ISocialIcon[] = [
   {
     networkName: "Facebook",
@@ -26,120 +40,177 @@ const defaultItems: ISocialIcon[] = [
 
 describe("SocialIconsList", () => {
   it("mounts without error", async () => {
-    const wrapper = await mountSuspended(SocialIconsList, {
-      props: { items: defaultItems },
-    });
+    const wrapper = await mountList({ items: defaultItems });
     expect(wrapper.vm).toBeTruthy();
   });
 
   it("renders as a ul element", async () => {
-    const wrapper = await mountSuspended(SocialIconsList, {
-      props: { items: defaultItems },
-    });
+    const wrapper = await mountList({ items: defaultItems });
     expect(wrapper.element.tagName.toLowerCase()).toBe("ul");
   });
 
   it("renders the correct number of list items", async () => {
-    const wrapper = await mountSuspended(SocialIconsList, {
-      props: { items: defaultItems },
-    });
-    expect(wrapper.findAll(".social-icon-item").length).toBe(defaultItems.length);
+    const wrapper = await mountList({ items: defaultItems });
+    expect(wrapper.findAll(".social-icons-list-item").length).toBe(defaultItems.length);
   });
 
   it("renders the correct href for each item", async () => {
-    const wrapper = await mountSuspended(SocialIconsList, {
-      props: { items: defaultItems },
-    });
-    const links = wrapper.findAll(".social-icon-link");
+    const wrapper = await mountList({ items: defaultItems });
+    const links = wrapper.findAll(".social-icons-list-link");
     defaultItems.forEach((item, i) => {
       expect(links[i]!.attributes("href")).toBe(`${item.baseHref}${item.profileId}`);
     });
   });
 
   it("renders aria-label on each link using networkName", async () => {
-    const wrapper = await mountSuspended(SocialIconsList, {
-      props: { items: defaultItems },
-    });
-    const links = wrapper.findAll(".social-icon-link");
+    const wrapper = await mountList({ items: defaultItems });
+    const links = wrapper.findAll(".social-icons-list-link");
     defaultItems.forEach((item, i) => {
       expect(links[i]!.attributes("aria-label")).toBe(`${item.networkName} profile (opens in a new tab)`);
     });
   });
 
   it("adds rel='noopener noreferrer' to each link", async () => {
-    const wrapper = await mountSuspended(SocialIconsList, {
-      props: { items: defaultItems },
-    });
-    const links = wrapper.findAll(".social-icon-link");
+    const wrapper = await mountList({ items: defaultItems });
+    const links = wrapper.findAll(".social-icons-list-link");
     links.forEach((link) => {
       expect(link.attributes("rel")).toBe("noopener noreferrer");
     });
   });
 
   it("opens each link in a new tab", async () => {
-    const wrapper = await mountSuspended(SocialIconsList, {
-      props: { items: defaultItems },
-    });
-    const links = wrapper.findAll(".social-icon-link");
+    const wrapper = await mountList({ items: defaultItems });
+    const links = wrapper.findAll(".social-icons-list-link");
     links.forEach((link) => {
       expect(link.attributes("target")).toBe("_blank");
     });
   });
 
   it("uses the default aria-label on the list", async () => {
-    const wrapper = await mountSuspended(SocialIconsList, {
-      props: { items: defaultItems },
-    });
+    const wrapper = await mountList({ items: defaultItems });
     expect(wrapper.attributes("aria-label")).toBe("Social media profiles");
   });
 
   it("uses a custom label prop as aria-label on the list", async () => {
-    const wrapper = await mountSuspended(SocialIconsList, {
-      props: { items: defaultItems, label: "Follow us" },
-    });
+    const wrapper = await mountList({ items: defaultItems, label: "Follow us" });
     expect(wrapper.attributes("aria-label")).toBe("Follow us");
   });
 
   it("renders an empty list when items is empty", async () => {
-    const wrapper = await mountSuspended(SocialIconsList, {
-      props: { items: [] },
-    });
-    expect(wrapper.findAll(".social-icon-item").length).toBe(0);
+    const wrapper = await mountList({ items: [] });
+    expect(wrapper.findAll(".social-icons-list-item").length).toBe(0);
   });
 
   it("applies styleClassPassthrough classes to the root element", async () => {
-    const wrapper = await mountSuspended(SocialIconsList, {
-      props: { items: defaultItems, styleClassPassthrough: ["custom-class", "another-class"] },
-    });
+    const wrapper = await mountList({ items: defaultItems, styleClassPassthrough: ["custom-class", "another-class"] });
     expect(wrapper.classes()).toContain("custom-class");
     expect(wrapper.classes()).toContain("another-class");
   });
 
   it("renders the correct HTML structure", async () => {
-    const wrapper = await mountSuspended(SocialIconsList, {
-      props: { items: defaultItems },
-    });
+    const wrapper = await mountList({ items: defaultItems });
     expect(wrapper.html()).toMatchSnapshot();
   });
 });
 
 describe("SocialIconsList link labels", () => {
   it("uses linkLabelTemplate for each link", async () => {
-    const wrapper = await mountSuspended(SocialIconsList, {
-      props: { items: defaultItems, linkLabelTemplate: "Profil {network}" },
-    });
-    expect(wrapper.findAll(".social-icon-link")[0]!.attributes("aria-label")).toBe("Profil Facebook");
+    const wrapper = await mountList({ items: defaultItems, linkLabelTemplate: "Profil {network}" });
+    expect(wrapper.findAll(".social-icons-list-link")[0]!.attributes("aria-label")).toBe("Profil Facebook");
   });
 
   it("lets an item's own label override the template", async () => {
+    const wrapper = await mountList({ items: [{ ...defaultItems[0]!, label: "Our Facebook page" }] });
+    expect(wrapper.find(".social-icons-list-link").attributes("aria-label")).toBe("Our Facebook page");
+  });
+
+  it("hides the icon from assistive tech (the link carries the name)", async () => {
+    const wrapper = await mountList({ items: defaultItems });
+    expect(wrapper.find(".social-icons-list-icon-wrapper").attributes("aria-hidden")).toBe("true");
+  });
+});
+
+describe("SocialIconsList hostile data", () => {
+  it("announces as a list even with list-style: none (Safari/VoiceOver)", async () => {
+    const wrapper = await mountList({ items: defaultItems });
+    expect(wrapper.attributes("role")).toBe("list");
+  });
+
+  it("renders every item when two share a networkName", async () => {
+    const twoInstagrams: ISocialIcon[] = [
+      { ...defaultItems[1]!, profileId: "salon" },
+      { ...defaultItems[1]!, profileId: "academy" },
+    ];
+    const wrapper = await mountList({ items: twoInstagrams });
+    const hrefs = wrapper.findAll(".social-icons-list-link").map((link) => link.attributes("href"));
+    expect(hrefs).toEqual(["https://www.instagram.com/salon", "https://www.instagram.com/academy"]);
+  });
+
+  it("skips an item whose href isn't http(s), mailto, tel or site-relative", async () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    const wrapper = await mountList({
+      items: [
+        { ...defaultItems[0]!, baseHref: "javascript:", profileId: "alert(1)" },
+        { ...defaultItems[0]!, baseHref: " JavaScript:", profileId: "alert(1)" },
+        { ...defaultItems[0]!, baseHref: "//evil.example/", profileId: "x" },
+        defaultItems[1]!,
+      ],
+    });
+    const links = wrapper.findAll(".social-icons-list-link");
+    expect(links.length).toBe(1);
+    expect(links[0]!.attributes("href")).toBe("https://www.instagram.com/testhandle");
+  });
+
+  it("keeps mailto, tel and site-relative hrefs", async () => {
+    const wrapper = await mountList({
+      items: [
+        { networkName: "Email", iconName: "mdi:email", baseHref: "mailto:", profileId: "hello@example.com" },
+        { networkName: "Phone", iconName: "mdi:phone", baseHref: "tel:", profileId: "+441234567890" },
+        { networkName: "Contact", iconName: "mdi:account", baseHref: "/", profileId: "contact" },
+      ],
+    });
+    const hrefs = wrapper.findAll(".social-icons-list-link").map((link) => link.attributes("href"));
+    expect(hrefs).toEqual(["mailto:hello@example.com", "tel:+441234567890", "/contact"]);
+  });
+});
+
+describe("SocialIconsList labels, slots and brand colour", () => {
+  it("renders no visible label by default", async () => {
+    const wrapper = await mountList({ items: defaultItems });
+    expect(wrapper.find(".social-icons-list-label").exists()).toBe(false);
+  });
+
+  it("shows each networkName as visible text with showLabel, keeping the aria-label", async () => {
+    const wrapper = await mountList({ items: defaultItems, showLabel: true });
+    const labels = wrapper.findAll(".social-icons-list-label").map((label) => label.text());
+    expect(labels).toEqual(["Facebook", "Instagram", "YouTube"]);
+    expect(wrapper.find(".social-icons-list-link").attributes("aria-label")).toBe("Facebook profile (opens in a new tab)");
+  });
+
+  it("sets --social-icons-list-brand-colour on an item only when it has a brandColour", async () => {
+    const wrapper = await mountList({ items: [{ ...defaultItems[0]!, brandColour: "#1877f2" }, defaultItems[1]!] });
+    const items = wrapper.findAll(".social-icons-list-item");
+    expect((items[0]!.element as HTMLElement).style.getPropertyValue("--social-icons-list-brand-colour")).toBe("#1877f2");
+    expect((items[1]!.element as HTMLElement).style.getPropertyValue("--social-icons-list-brand-colour")).toBe("");
+  });
+
+  it("replaces the icon with the scoped icon slot, inside the wrapper", async () => {
     const wrapper = await mountSuspended(SocialIconsList, {
-      props: { items: [{ ...defaultItems[0]!, label: "Our Facebook page" }] },
+      props: { items: defaultItems },
+      slots: { icon: ({ item }: { item: ISocialIcon }) => h("b", { class: "custom-icon" }, item.networkName[0]) },
     });
-    expect(wrapper.find(".social-icon-link").attributes("aria-label")).toBe("Our Facebook page");
+    mounted.push(wrapper);
+    const custom = wrapper.findAll(".social-icons-list-icon-wrapper .custom-icon");
+    expect(custom.map((el) => el.text())).toEqual(["F", "I", "Y"]);
+    expect(wrapper.find(".social-icons-list-icon").exists()).toBe(false);
   });
 
-  it("hides the icon from assistive tech (the link carries the name)", async () => {
-    const wrapper = await mountSuspended(SocialIconsList, { props: { items: defaultItems } });
-    expect(wrapper.find(".social-icon").attributes("aria-hidden")).toBe("true");
+  it("renders the scoped label slot without showLabel", async () => {
+    const wrapper = await mountSuspended(SocialIconsList, {
+      props: { items: defaultItems },
+      slots: { label: ({ item }: { item: ISocialIcon }) => `@${item.profileId}` },
+    });
+    mounted.push(wrapper);
+    expect(wrapper.find(".social-icons-list-label").text()).toBe("@testprofile");
   });
 });

package/app/components/02.molecules/social-icons-list/tests/__snapshots__/SocialIconsList.spec.ts.snap

@@ -1,9 +1,15 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`SocialIconsList > renders the correct HTML structure 1`] = `
-"<ul class="social-icons-list" aria-label="Social media profiles">
-  <li class="social-icon-item"><a href="https://www.facebook.com/testprofile" class="social-icon-link" aria-label="Facebook profile (opens in a new tab)" rel="noopener noreferrer" target="_blank"><span class="iconify i-logos:facebook social-icon" aria-hidden="true"></span></a></li>
-  <li class="social-icon-item"><a href="https://www.instagram.com/testhandle" class="social-icon-link" aria-label="Instagram profile (opens in a new tab)" rel="noopener noreferrer" target="_blank"><span class="iconify i-logos:instagram-icon social-icon" aria-hidden="true"></span></a></li>
-  <li class="social-icon-item"><a href="https://www.youtube.com/@testchannel" class="social-icon-link" aria-label="YouTube profile (opens in a new tab)" rel="noopener noreferrer" target="_blank"><span class="iconify i-logos:youtube-icon social-icon" aria-hidden="true"></span></a></li>
+"<ul class="social-icons-list" role="list" aria-label="Social media profiles">
+  <li class="social-icons-list-item"><a href="https://www.facebook.com/testprofile" class="social-icons-list-link" aria-label="Facebook profile (opens in a new tab)" rel="noopener noreferrer" target="_blank"><span class="social-icons-list-icon-wrapper" aria-hidden="true"><span class="iconify i-logos:facebook social-icons-list-icon" aria-hidden="true"></span></span>
+      <!--v-if-->
+    </a></li>
+  <li class="social-icons-list-item"><a href="https://www.instagram.com/testhandle" class="social-icons-list-link" aria-label="Instagram profile (opens in a new tab)" rel="noopener noreferrer" target="_blank"><span class="social-icons-list-icon-wrapper" aria-hidden="true"><span class="iconify i-logos:instagram-icon social-icons-list-icon" aria-hidden="true"></span></span>
+      <!--v-if-->
+    </a></li>
+  <li class="social-icons-list-item"><a href="https://www.youtube.com/@testchannel" class="social-icons-list-link" aria-label="YouTube profile (opens in a new tab)" rel="noopener noreferrer" target="_blank"><span class="social-icons-list-icon-wrapper" aria-hidden="true"><span class="iconify i-logos:youtube-icon social-icons-list-icon" aria-hidden="true"></span></span>
+      <!--v-if-->
+    </a></li>
 </ul>"
 `;

package/app/components/02.molecules/toast/CONSUMER-STYLING.md

@@ -71,9 +71,15 @@ Toasts slide in and out over `behavior.revealDuration` (default `550ms`). Under
 because it shows how long is left.
 
 Auto-dismiss pauses while the pointer is over a toast, or while keyboard focus is on it or inside
-it, and resumes with the time that was left (WCAG 2.2.2). The toast moves focus to itself when
-shown; that only pauses it when the user was using a keyboard (`:focus-visible`), so mouse users
-still get auto-dismiss.
+it, and resumes with the time that was left (WCAG 2.2.2). Toasts don't take focus when they
+appear, so the focus ring only shows when a keyboard user tabs to one, and focus on the toast
+itself only pauses it for keyboard users (`:focus-visible`).
+
+> Changed 2026-10-16: toasts used to move focus to themselves when shown, which interrupted
+> typing and showed the focus ring when a toast opened before any pointer input. Escape now
+> dismisses a toast from anywhere on the page (the provider dismisses the newest one), unless
+> another handler called `preventDefault()`. No consumer change needed, unless your own code relied
+> on the toast holding focus.
 
 ## Global theming
 

package/app/components/02.molecules/toast/DisplayToast.vue

@@ -14,7 +14,6 @@
       :aria-live="ariaLive"
       :tabindex="slots.default ? undefined : '0'"
       :aria-describedby="slots.default ? undefined : 'toast-message-' + toastId"
-      @keydown.escape="setDismissToast"
       @pointerenter="isHovered = true"
       @pointerleave="isHovered = false"
       @focusin="handleFocusIn"
@@ -48,6 +47,7 @@
 </template>
 
 <script setup lang="ts">
+import { useEventListener } from "@vueuse/core";
 import AlertContent from "~/components/02.molecules/alert-content/AlertContent.vue";
 import AlertMaskedContent from "~/components/02.molecules/alert-masked-content/AlertMaskedContent.vue";
 import type { DisplayToastConfig, ToastSlots } from "~/types/components";
@@ -182,15 +182,6 @@ watch(
       privateDisplayToast.value = true;
       transitionalState.value = true;
 
-      // Focus management for accessibility when not using custom slots
-      if (!slots.default) {
-        await nextTick();
-        // Wait for animation to start before focusing
-        setTimeout(() => {
-          toastElementRef.value?.focus();
-        }, 100);
-      }
-
       if (autoDismiss.value) {
         clearDismissTimer();
         dismissTimer = createPausableTimeout(setDismissToast, duration.value);
@@ -203,6 +194,15 @@ watch(
   }
 );
 
+// The toast never takes focus (WCAG 4.1.3), so Escape is heard document-wide while it's shown.
+useEventListener(
+  () => (import.meta.client ? document : null),
+  "keydown",
+  (event: KeyboardEvent) => {
+    if (event.key === "Escape" && !event.defaultPrevented && transitionalState.value) setDismissToast();
+  }
+);
+
 onBeforeRouteLeave(() => {
   setDismissToast();
 });

package/app/components/02.molecules/toast/DisplayToastProvider.vue

@@ -7,7 +7,6 @@
       :data-alignment="fullWidth ? 'full-width' : alignment"
       @before-leave="onBeforeLeave"
       @after-leave="onAfterLeave"
-      @after-enter="onAfterEnter"
     >
       <div
         v-for="entry in visibleEntries"
@@ -54,6 +53,7 @@
 </template>
 
 <script setup lang="ts">
+import { useEventListener } from "@vueuse/core";
 import AlertContent from "~/components/02.molecules/alert-content/AlertContent.vue";
 import AlertMaskedContent from "~/components/02.molecules/alert-masked-content/AlertMaskedContent.vue";
 import type {
@@ -187,9 +187,17 @@ const onAfterLeave = () => {
   }
 };
 
-const onAfterEnter = (el: Element) => {
-  (el as HTMLElement).focus();
-};
+// Toasts never take focus (WCAG 4.1.3); Escape outside one dismisses the newest.
+useEventListener(
+  () => (import.meta.client ? document : null),
+  "keydown",
+  (event: KeyboardEvent) => {
+    if (event.key !== "Escape" || event.defaultPrevented) return;
+    if ((event.target as Element | null)?.closest?.(".display-toast-provider-item")) return;
+    const newest = visibleEntries.value.at(-1);
+    if (newest) handleDismiss(newest.id);
+  }
+);
 
 onUnmounted(() => {
   timers.forEach((timer) => timer.clear());

package/app/components/02.molecules/toast/stories/DisplayToast.stories.ts

@@ -1,12 +1,56 @@
 import type { Meta, StoryFn } from "@nuxtjs/storybook";
-import { ref, onMounted } from "vue";
+import { ref, computed, watchEffect, onMounted, onUnmounted } from "vue";
 import StorybookComponent from "../DisplayToast.vue";
 
+type CanvasKey = "none" | "gradient" | "lake" | "portrait" | "dark-photo" | "stripes" | "page-text";
+
+const busyBackdrop = [
+  "repeating-linear-gradient(45deg, oklch(100% 0 0 / 0.18) 0 1.2rem, transparent 1.2rem 2.4rem)",
+  "linear-gradient(120deg, oklch(70% 0.2 30), oklch(75% 0.18 90) 35%, oklch(65% 0.2 200) 70%, oklch(55% 0.22 300))",
+].join(", ");
+
+const canvases: Record<CanvasKey, string> = {
+  none: "",
+  gradient: "background: linear-gradient(135deg, oklch(40% 0.15 250), oklch(25% 0.1 300));",
+  lake: "background: url('/images/banners/video/lake-banner.jpg') center / cover;",
+  portrait: "background: url('/images/page/hero/hero-blonde.jpg') center 30% / cover;",
+  "dark-photo": "background: url('/images/page/hero/hero-dark.jpg') center / cover;",
+  stripes: `background: ${busyBackdrop};`,
+  "page-text": "background: white;",
+};
+
+const pageText = Array.from(
+  { length: 6 },
+  () =>
+    "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. " +
+    "Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. " +
+    "Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur."
+);
+
+/*
+ * The toast teleports to <body>, so a fill override on a story wrapper never reaches it. Inject a
+ * rule on .display-toast instead: --theme-surface-subtle then resolves against the toast's data-theme.
+ */
+function useMaskedFillStyle(fill: () => number) {
+  const styleEl = document.createElement("style");
+  document.head.appendChild(styleEl);
+  watchEffect(() => {
+    styleEl.textContent =
+      fill() === 80
+        ? ""
+        : `.display-toast { --alert-masked-content-background: color-mix(in oklab, var(--theme-surface-subtle) ${fill()}%, transparent); }`;
+  });
+  onUnmounted(() => styleEl.remove());
+}
+
 interface ToastStoryArgs {
   theme: "info" | "success" | "warning" | "error";
   position: "top" | "bottom";
   alignment: "left" | "center" | "right";
   fullWidth: boolean;
+  masked: boolean;
+  maskedFill: number;
+  canvas: CanvasKey;
   autoDismiss: boolean;
   duration: number;
   revealDuration: number;
@@ -42,6 +86,24 @@ export default {
       description: "Whether toast spans full width",
       table: { category: "Appearance" },
     },
+    masked: {
+      control: { type: "boolean" },
+      description: "Render with AlertMaskedContent (SVG border, translucent fill) instead of AlertContent",
+      table: { category: "Appearance" },
+    },
+    maskedFill: {
+      control: { type: "range", min: 0, max: 100, step: 5 },
+      description:
+        "Story-only: opacity (%) of the masked fill, set via --alert-masked-content-background. 80 is the library default; lower values cost contrast",
+      if: { arg: "masked" },
+      table: { category: "Story canvas" },
+    },
+    canvas: {
+      control: { type: "select" },
+      options: ["none", "gradient", "lake", "portrait", "dark-photo", "stripes", "page-text"],
+      description: "Story-only: full-viewport backdrop behind the toast, to show what the masked variant lets through",
+      table: { category: "Story canvas" },
+    },
     autoDismiss: {
       control: { type: "boolean" },
       description: "Auto dismiss toast after duration",
@@ -80,6 +142,9 @@ export default {
     position: "top",
     alignment: "right",
     fullWidth: false,
+    masked: false,
+    maskedFill: 80,
+    canvas: "none",
     autoDismiss: false,
     duration: 3000,
     revealDuration: 300,
@@ -104,9 +169,21 @@ const Template: StoryFn<ToastStoryArgs> = (args) => ({
       }, 500);
     });
 
-    return { args, isActive };
+    useMaskedFillStyle(() => args.maskedFill);
+    const canvasStyle = computed(() => canvases[args.canvas]);
+
+    return { args, isActive, canvasStyle, pageText };
   },
   template: `
+    <div
+      v-if="args.canvas !== 'none'"
+      :style="canvasStyle + ' position: fixed; inset: 0; overflow: hidden; padding: 6rem 2rem 2rem; font-family: sans-serif; font-size: 1.6rem; line-height: 1.5; color: #222;'"
+    >
+      <template v-if="args.canvas === 'page-text'">
+        <h2 style="margin: 0 0 1rem;">Article heading behind the toast</h2>
+        <p v-for="(para, i) in pageText" :key="i" style="margin: 0 0 1rem;">{{ para }}</p>
+      </template>
+    </div>
     <div style="position: relative; height: 200px; padding: 20px;">
       <button
         @click="isActive = true"
@@ -123,6 +200,7 @@ const Template: StoryFn<ToastStoryArgs> = (args) => ({
             position: args.position,
             alignment: args.alignment,
             fullWidth: args.fullWidth,
+            masked: args.masked,
           },
           behavior: {
             autoDismiss: args.autoDismiss,
@@ -220,3 +298,123 @@ StressTest.parameters = {
     },
   },
 };
+
+export const MaskedOverGradient = Template.bind({});
+MaskedOverGradient.storyName = "Masked: Over Gradient";
+MaskedOverGradient.args = {
+  masked: true,
+  canvas: "gradient",
+  title: "Masked toast",
+  description: "AlertMaskedContent: the accent border is an SVG cut-out and the fill is 80% translucent.",
+};
+MaskedOverGradient.parameters = {
+  docs: {
+    description: {
+      story:
+        "`appearance.masked: true` swaps AlertContent for AlertMaskedContent. Over a flat gradient the effect is subtle: " +
+        "switch `canvas` to a photo or the stripes to see the backdrop through the fill.",
+    },
+  },
+};
+
+export const MaskedOverPhoto = Template.bind({});
+MaskedOverPhoto.storyName = "Masked: Over Photo";
+MaskedOverPhoto.args = {
+  theme: "success",
+  masked: true,
+  canvas: "portrait",
+  title: "Booking confirmed",
+  description: "We've sent the details to your inbox.",
+  customIcon: "akar-icons:check-box",
+};
+MaskedOverPhoto.parameters = {
+  docs: {
+    description: {
+      story:
+        "A photo backdrop is where the masked variant earns its place: the image stays visible through the body and around the border. " +
+        "Try `lake` and `dark-photo` too, and every theme.",
+    },
+  },
+};
+
+export const MaskedVsOpaque: StoryFn<ToastStoryArgs> = (args) => ({
+  components: { StorybookComponent },
+  setup() {
+    const isActive = ref(false);
+    onMounted(() => {
+      setTimeout(() => {
+        isActive.value = true;
+      }, 500);
+    });
+    useMaskedFillStyle(() => args.maskedFill);
+    const canvasStyle = computed(() => canvases[args.canvas]);
+    const config = (masked: boolean, alignment: "left" | "right") => ({
+      appearance: { theme: args.theme, position: args.position, alignment, masked },
+      behavior: { autoDismiss: false, revealDuration: args.revealDuration },
+      content: { title: masked ? "AlertMaskedContent" : "AlertContent", description: args.description },
+    });
+    return { args, isActive, canvasStyle, config };
+  },
+  template: `
+    <div :style="canvasStyle + ' position: fixed; inset: 0;'"></div>
+    <div style="position: relative; padding: 20px;">
+      <button
+        @click="isActive = true"
+        style="padding: 8px 16px; background: #0066cc; color: white; border: none; border-radius: 4px; cursor: pointer;"
+      >
+        Trigger Toasts
+      </button>
+    </div>
+    <StorybookComponent v-model="isActive" :config="config(false, 'left')" />
+    <StorybookComponent v-model="isActive" :config="config(true, 'right')" />
+  `,
+});
+MaskedVsOpaque.storyName = "Masked: Side by Side with Opaque";
+MaskedVsOpaque.args = {
+  masked: true,
+  canvas: "lake",
+  description: "Same theme, same backdrop: opaque on the left, masked on the right.",
+};
+MaskedVsOpaque.argTypes = {
+  masked: { table: { disable: true } },
+  alignment: { table: { disable: true } },
+  fullWidth: { table: { disable: true } },
+  title: { table: { disable: true } },
+  customIcon: { table: { disable: true } },
+  autoDismiss: { table: { disable: true } },
+  duration: { table: { disable: true } },
+};
+MaskedVsOpaque.parameters = {
+  docs: {
+    description: {
+      story:
+        "Two toasts over one backdrop: AlertContent (left) and AlertMaskedContent (right). Change `canvas` and `theme` to compare, " +
+        "and drag `maskedFill` to see how much backdrop the masked one lets through.",
+    },
+  },
+};
+
+export const MaskedLowContrast = Template.bind({});
+MaskedLowContrast.storyName = "Masked: Low Contrast Risk";
+MaskedLowContrast.args = {
+  theme: "info",
+  masked: true,
+  maskedFill: 35,
+  canvas: "page-text",
+  alignment: "center",
+  title: "Hard to read",
+  description: "Page text shows through a 35% fill and fights with the toast's own text.",
+};
+MaskedLowContrast.parameters = {
+  docs: {
+    description: {
+      story:
+        "What can go wrong. The default 80% fill keeps `--theme-text` readable over most backdrops, but contrast depends on what's behind the toast, " +
+        "which you don't control once it's fixed to the viewport. Here the fill is lowered to 35% over body copy, so letterforms from the page " +
+        "show through and compete with the message. Other traps to try: `stripes` or `portrait` with a low fill (busy detail behind small text), " +
+        "and the `info` theme over `gradient` (the 1px accent border nearly vanishes against a backdrop of a similar hue). " +
+        "Drag `maskedFill` back up to 80 to see the default recover. If you lower `--alert-masked-content-background`, test it over your real imagery and content, " +
+        "and prefer the opaque variant for error and warning toasts that must be read.",
+    },
+  },
+};