srcdev-nuxt-components 9.4.12 → 9.5.0

package/app/components/02.molecules/samaritan-prompt/tests/SamaritanPromptMixed.spec.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, afterEach } from "vitest";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
 import { nextTick } from "vue";
 import SamaritanPromptMixed from "../SamaritanPromptMixed.vue";
-import type { MessageConfig } from "../SamaritanPromptMixed.vue";
+import type { SamaritanPromptMessageConfig as MessageConfig } from "~/types/components/samaritan-prompt";
 
 // ─── Typewriter ───────────────────────────────────────────────────────────────
 //
@@ -38,14 +38,14 @@ describe("SamaritanPromptMixed — typewriter", () => {
     expect(wrapper.find(".samaritan-prompt__stage").exists()).toBe(true);
   });
 
-  it.skip("types the first character immediately on mount", async () => {
-    wrapper = await mountSuspended(SamaritanPromptMixed, { props: { messageConfigs: [config] } });
+  it("types the first character immediately on mount", async () => {
+    wrapper = await mountSuspended(SamaritanPromptMixed, { props: { messageConfigs: [config], introDelay: 0 } });
     await nextTick();
     expect(wrapper.find(".samaritan-prompt__text").text()).toBe("H");
   });
 
-  it.skip("types one character per typeSpeed tick", async () => {
-    wrapper = await mountSuspended(SamaritanPromptMixed, { props: { messageConfigs: [config] } });
+  it("types one character per typeSpeed tick", async () => {
+    wrapper = await mountSuspended(SamaritanPromptMixed, { props: { messageConfigs: [config], introDelay: 0 } });
     await nextTick();
     expect(wrapper.find(".samaritan-prompt__text").text()).toBe("H");
 
@@ -55,8 +55,8 @@ describe("SamaritanPromptMixed — typewriter", () => {
     expect(wrapper.find(".samaritan-prompt__text").text()).toBe("HE");
   });
 
-  it.skip("hides cursor when typing starts", async () => {
-    wrapper = await mountSuspended(SamaritanPromptMixed, { props: { messageConfigs: [config] } });
+  it("hides cursor when typing starts", async () => {
+    wrapper = await mountSuspended(SamaritanPromptMixed, { props: { messageConfigs: [config], introDelay: 0 } });
     await nextTick();
     expect(wrapper.find(".samaritan-prompt__cursor").attributes("style")).toContain("opacity: 0");
   });
@@ -166,16 +166,16 @@ describe("SamaritanPromptMixed — word-pulse", () => {
     expect(wrapper.find(".samaritan-prompt__text").text()).toBe("");
   });
 
-  it.skip("fades content out when cycle starts", async () => {
-    wrapper = await mountSuspended(SamaritanPromptMixed, { props: { messageConfigs: [config] } });
+  it("fades content out when cycle starts", async () => {
+    wrapper = await mountSuspended(SamaritanPromptMixed, { props: { messageConfigs: [config], introDelay: 0 } });
     await nextTick(); // component's await nextTick() resolves → sets opacity=0
     await nextTick(); // DOM update
 
     expect(wrapper.find(".samaritan-prompt__content").attributes("style")).toContain("opacity: 0");
   });
 
-  it.skip("hides cursor when cycle starts", async () => {
-    wrapper = await mountSuspended(SamaritanPromptMixed, { props: { messageConfigs: [config] } });
+  it("hides cursor when cycle starts", async () => {
+    wrapper = await mountSuspended(SamaritanPromptMixed, { props: { messageConfigs: [config], introDelay: 0 } });
     await nextTick();
     await nextTick();
 
@@ -192,8 +192,8 @@ describe("SamaritanPromptMixed — word-pulse", () => {
     expect(wrapper.find(".samaritan-prompt__cursor").attributes("style")).toContain("opacity: 1");
   });
 
-  it.skip("shows text and restores opacity after fade duration and settle delay", async () => {
-    wrapper = await mountSuspended(SamaritanPromptMixed, { props: { messageConfigs: [config] } });
+  it("shows text and restores opacity after fade duration and settle delay", async () => {
+    wrapper = await mountSuspended(SamaritanPromptMixed, { props: { messageConfigs: [config], introDelay: 0 } });
     await nextTick(); // component's nextTick resolves → opacity=0, await wait(fadeDuration)
     await nextTick(); // DOM update
 
@@ -211,8 +211,8 @@ describe("SamaritanPromptMixed — word-pulse", () => {
     expect(wrapper.find(".samaritan-prompt__content").attributes("style")).toContain("opacity: 1");
   });
 
-  it.skip("fades text back out after word duration", async () => {
-    wrapper = await mountSuspended(SamaritanPromptMixed, { props: { messageConfigs: [config] } });
+  it("fades text back out after word duration", async () => {
+    wrapper = await mountSuspended(SamaritanPromptMixed, { props: { messageConfigs: [config], introDelay: 0 } });
     await nextTick();
     await nextTick();
 
@@ -241,10 +241,11 @@ describe("SamaritanPromptMixed — config resolution", () => {
     // wrappers are unmounted inline in each test
   });
 
-  it.skip("falls back to global effect prop when not specified per message", async () => {
+  it("falls back to global effect prop when not specified per message", async () => {
     const wrapper = await mountSuspended(SamaritanPromptMixed, {
       props: {
         messageConfigs: [{ text: "TEST" }], // no effect
+        introDelay: 0,
         effect: "typewriter",
         typeSpeed: 100,
       },
@@ -255,10 +256,11 @@ describe("SamaritanPromptMixed — config resolution", () => {
     wrapper.unmount();
   });
 
-  it.skip("falls back to global typeSpeed when not specified per message", async () => {
+  it("falls back to global typeSpeed when not specified per message", async () => {
     const wrapper = await mountSuspended(SamaritanPromptMixed, {
       props: {
         messageConfigs: [{ text: "HI", effect: "typewriter" }],
+        introDelay: 0,
         typeSpeed: 150,
       },
     });
@@ -304,3 +306,79 @@ describe("SamaritanPromptMixed — config resolution", () => {
     wrapper.unmount();
   });
 });
+
+// ─── Accessibility, pause and slots ───────────────────────────────────────────
+
+describe("SamaritanPromptMixed — accessibility and pause", () => {
+  const config: MessageConfig = {
+    text: "HI",
+    effect: "typewriter",
+    typeSpeed: 100,
+    deleteSpeed: 50,
+    holdDuration: 300,
+    pauseDuration: 100,
+  };
+
+  let wrapper: Awaited<ReturnType<typeof mountSuspended>>;
+
+  afterEach(() => {
+    wrapper?.unmount();
+  });
+
+  it("hides the animated content from assistive tech and exposes a polite live region", async () => {
+    wrapper = await mountSuspended(SamaritanPromptMixed, { props: { messageConfigs: [config], introDelay: 0 } });
+    expect(wrapper.find(".samaritan-prompt__content").attributes("aria-hidden")).toBe("true");
+    const live = wrapper.find(".samaritan-prompt__sr-text");
+    expect(live.attributes("aria-live")).toBe("polite");
+    expect(live.attributes("aria-atomic")).toBe("true");
+  });
+
+  it("announces the full message once it is typed", async () => {
+    wrapper = await mountSuspended(SamaritanPromptMixed, { props: { messageConfigs: [config], introDelay: 0 } });
+    await vi.advanceTimersByTimeAsync(200);
+    await nextTick();
+    expect(wrapper.find(".samaritan-prompt__sr-text").text()).toBe("HI");
+  });
+
+  it("sets data-paused on hover and removes it on leave", async () => {
+    wrapper = await mountSuspended(SamaritanPromptMixed, { props: { messageConfigs: [config] } });
+    const root = wrapper.find(".samaritan-prompt");
+    await root.trigger("pointerenter");
+    expect(root.attributes("data-paused")).toBeDefined();
+    await root.trigger("pointerleave");
+    expect(root.attributes("data-paused")).toBeUndefined();
+  });
+
+  it("stops typing while hovered and resumes on leave", async () => {
+    wrapper = await mountSuspended(SamaritanPromptMixed, {
+      props: { messageConfigs: [{ ...config, text: "HELLO" }], introDelay: 0 },
+    });
+    await vi.advanceTimersByTimeAsync(100);
+    await nextTick();
+    const typedBeforePause = wrapper.find(".samaritan-prompt__text").text();
+
+    await wrapper.find(".samaritan-prompt").trigger("pointerenter");
+    await vi.advanceTimersByTimeAsync(1000);
+    await nextTick();
+    expect(wrapper.find(".samaritan-prompt__text").text()).toBe(typedBeforePause);
+
+    await wrapper.find(".samaritan-prompt").trigger("pointerleave");
+    await vi.advanceTimersByTimeAsync(300);
+    await nextTick();
+    expect(wrapper.find(".samaritan-prompt__text").text().length).toBeGreaterThan(typedBeforePause.length);
+  });
+
+  it("renders a custom cursor from the cursor slot", async () => {
+    wrapper = await mountSuspended(SamaritanPromptMixed, {
+      props: { messageConfigs: [config] },
+      slots: { cursor: () => "_" },
+    });
+    expect(wrapper.find(".samaritan-prompt__cursor").text()).toBe("_");
+  });
+
+  it("exposes the fade duration as an inline private token", async () => {
+    wrapper = await mountSuspended(SamaritanPromptMixed, { props: { messageConfigs: [config], fadeDuration: 900 } });
+    const style = (wrapper.find(".samaritan-prompt").element as HTMLElement).style;
+    expect(style.getPropertyValue("--_fade-duration")).toBe("900ms");
+  });
+});

package/app/components/02.molecules/select-menu/CONSUMER-STYLING.md

@@ -54,7 +54,7 @@ global token so it matches the rest of the design system out of the box.
 
 ---
 
-## Global theming — recommended approach
+## Global theming
 
 Create `assets/styles/setup/07.components/select-menu.css` in the consuming app and set tokens
 on `:root`. This applies to every `SelectMenu` across the site.
@@ -77,7 +77,15 @@ on `:root`. This applies to every `SelectMenu` across the site.
 
 ---
 
-## Per-instance overrides via styleClassPassthrough
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): 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: `.claude/skills/component-local-style-override.md`.
+
+### One instance
 
 ```vue
 <SelectMenu
@@ -166,3 +174,4 @@ story.
   the bottom of the viewport (`position-try-fallbacks: flip-block`).
 - **Chevron rotation** is pure CSS via `:has(.select-menu-popover:popover-open)` — no JS state
   needed for the visual, though `isOpen` is still tracked internally to drive `aria-expanded`.
+

package/app/components/02.molecules/social-icons-list/CONSUMER-STYLING.md

@@ -0,0 +1,43 @@
+# SocialIconsList — Consumer Styling Guide
+
+## Public token API
+
+| Token | Default | Controls |
+|---|---|---|
+| `--social-icons-list-icon-size` | `2.4rem` | Icon size (applied as `font-size`) |
+| `--social-icons-list-gap` | `1.2rem` | Gap between icons |
+| `--social-icons-list-hover-scale` | `1.15` | Scale on hover/focus (no scaling under `prefers-reduced-motion: reduce`) |
+| `--social-icons-list-hover-opacity` | `0.85` | Opacity on hover/focus |
+
+The focus outline uses `--theme-ring`, falling back to `currentColor`. Icon colour is whatever the
+Iconify icon renders (`logos:` icons carry their own brand colours; mono sets follow `color`).
+
+> Changed 2026-09-28: `--theme-social-icon-size` and `--theme-social-icon-gap` were renamed to
+> `--social-icons-list-icon-size` and `--social-icons-list-gap`; the old names no longer work. The
+> icon is now sized with `font-size` (it used an inline `width`/`height` style). The hover tokens
+> are new, and the hover scale now respects reduced motion.
+
+No private `--_` tokens.
+
+---
+
+## State hooks
+
+Inner classes: `.social-icon-item` (each `<li>`), `.social-icon-link` (the `<a>`, opens in a new
+tab), `.social-icon` (the icon, `aria-hidden`).
+
+---
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): 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: `.claude/skills/component-local-style-override.md`.
+
+---
+
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root `<ul>`. Reactive after mount.

package/app/components/02.molecules/social-icons-list/SocialIconsList.vue

@@ -4,15 +4,11 @@
       <a
         :href="`${item.baseHref}${item.profileId}`"
         class="social-icon-link"
-        :aria-label="`${item.networkName} profile`"
+        :aria-label="linkLabel(item)"
         rel="noopener noreferrer"
         target="_blank"
       >
-        <Icon
-          :name="item.iconName"
-          class="social-icon"
-          :style="{ width: 'var(--_icon-size)', height: 'var(--_icon-size)' }"
-        />
+        <Icon :name="item.iconName" class="social-icon" aria-hidden="true" />
       </a>
     </li>
   </ul>
@@ -24,14 +20,18 @@ import type { ISocialIcon } from "~/types/components/social-icons-list.d";
 interface Props {
   items: ISocialIcon[];
   label?: string;
+  linkLabelTemplate?: string;
   styleClassPassthrough?: string | string[];
 }
 
 const props = withDefaults(defineProps<Props>(), {
   label: "Social media profiles",
+  linkLabelTemplate: "{network} profile (opens in a new tab)",
   styleClassPassthrough: () => [],
 });
 
+const linkLabel = (item: ISocialIcon) => item.label ?? props.linkLabelTemplate.replace("{network}", item.networkName);
+
 const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 
 watch(
@@ -45,12 +45,9 @@ watch(
 <style lang="css">
 @layer components {
   .social-icons-list {
-    --_icon-size: var(--theme-social-icon-size, 2.4rem);
-    --_gap: var(--theme-social-icon-gap, 1.2rem);
-
     display: flex;
     flex-wrap: wrap;
-    gap: var(--_gap);
+    gap: var(--social-icons-list-gap, 1.2rem);
     list-style: none;
     padding: 0;
     margin: 0;
@@ -69,19 +66,22 @@ watch(
 
         &:hover,
         &:focus-visible {
-          transform: scale(1.15);
-          opacity: 0.85;
+          transform: scale(var(--social-icons-list-hover-scale, 1.15));
+          opacity: var(--social-icons-list-hover-opacity, 0.85);
+
+          @media (prefers-reduced-motion: reduce) {
+            transform: none;
+          }
         }
 
         &:focus-visible {
-          outline: 2px solid currentColor;
+          outline: 2px solid var(--theme-ring, currentColor);
           outline-offset: 3px;
           border-radius: 2px;
         }
 
         .social-icon {
-          /* width: var(--_icon-size); */
-          /* height: var(--_icon-size); */
+          font-size: var(--social-icons-list-icon-size, 2.4rem);
         }
       }
     }

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

@@ -48,6 +48,10 @@ const meta: Meta<typeof SocialIconsList> = {
       control: "text",
       description: "aria-label for the list element",
     },
+    linkLabelTemplate: {
+      control: "text",
+      description: "aria-label for each link; {network} is replaced with the item's networkName",
+    },
     styleClassPassthrough: {
       control: "object",
       description: "Additional CSS classes applied to the root element",
@@ -56,6 +60,7 @@ const meta: Meta<typeof SocialIconsList> = {
   args: {
     items: sampleItems,
     label: "Social media profiles",
+    linkLabelTemplate: "{network} profile (opens in a new tab)",
     styleClassPassthrough: ["m-40"],
   },
 };
@@ -84,7 +89,7 @@ export const LargeIcons: Story = {
     setup() {
       return { args };
     },
-    template: `<SocialIconsList v-bind="args" style="--theme-social-icon-size: 4rem;" />`,
+    template: `<SocialIconsList v-bind="args" style="--social-icons-list-icon-size: 4rem;" />`,
   }),
 };
 

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

@@ -62,7 +62,7 @@ describe("SocialIconsList", () => {
     });
     const links = wrapper.findAll(".social-icon-link");
     defaultItems.forEach((item, i) => {
-      expect(links[i]!.attributes("aria-label")).toBe(`${item.networkName} profile`);
+      expect(links[i]!.attributes("aria-label")).toBe(`${item.networkName} profile (opens in a new tab)`);
     });
   });
 
@@ -122,3 +122,24 @@ describe("SocialIconsList", () => {
     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");
+  });
+
+  it("lets an item's own label override the template", async () => {
+    const wrapper = await mountSuspended(SocialIconsList, {
+      props: { items: [{ ...defaultItems[0]!, label: "Our Facebook page" }] },
+    });
+    expect(wrapper.find(".social-icon-link").attributes("aria-label")).toBe("Our Facebook page");
+  });
+
+  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");
+  });
+});

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

@@ -2,8 +2,8 @@
 
 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" rel="noopener noreferrer" target="_blank"><span class="iconify i-logos:facebook social-icon" aria-hidden="true" style="width: var(--_icon-size); height: var(--_icon-size);"></span></a></li>
-  <li class="social-icon-item"><a href="https://www.instagram.com/testhandle" class="social-icon-link" aria-label="Instagram profile" rel="noopener noreferrer" target="_blank"><span class="iconify i-logos:instagram-icon social-icon" aria-hidden="true" style="width: var(--_icon-size); height: var(--_icon-size);"></span></a></li>
-  <li class="social-icon-item"><a href="https://www.youtube.com/@testchannel" class="social-icon-link" aria-label="YouTube profile" rel="noopener noreferrer" target="_blank"><span class="iconify i-logos:youtube-icon social-icon" aria-hidden="true" style="width: var(--_icon-size); height: var(--_icon-size);"></span></a></li>
+  <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>"
 `;

package/app/components/02.molecules/stepper-list/CONSUMER-STYLING.md

@@ -50,9 +50,34 @@ file, scoped to a page wrapper, or per-instance via `styleClassPassthrough`.
 | `--stepper-list-counter-square-border` | `transparent` | Bubble border colour |
 | `--stepper-list-counter-square-border-radius` | `0.25rem` | Bubble corner rounding |
 
+The defaults above are the component's own fallbacks. The library's default theme
+(`app/assets/styles/setup/03.theming/_default.css`) sets blue values for the colour tokens on
+`:root`, so that's what you see unless your app replaces that theme file or overrides them.
+
+> Changed 2026-09-27: the default theme set `--stepper-list-icon`, a name the component never
+> reads, so custom indicator icons fell back to `currentColor`. It now sets
+> `--stepper-list-icon-color`.
+
+Private (not public API): `--_gap`, `--_counter-size` and `--_padding-block`, plus `--_connector-top` and
+`--_connector-height`, which script measures and sets inline on each `<li>`.
+
+---
+
+## State hooks
+
+| Hook | Element | When |
+|---|---|---|
+| `.has-connectors` | root | `connected` is on (default) |
+| `.has-indicator` | `<li>` | That item has an `indicator-{n}` slot |
+| `.indicator-top`, `.indicator-center` | `<li>` | `indicator-alignment` |
+| `.indicator-disc`, `.indicator-square`, `.indicator-circle` | `<li>` | `indicator-variant` |
+
+Inner classes: `.stepper-list__indicator-counter` (auto-numbered bubble) or
+`.stepper-list__indicator-custom` (wraps a custom `indicator-{n}` slot).
+
 ---
 
-## Global theming — recommended approach
+## Global theming
 
 Create `assets/styles/setup/07.components/stepper-list.css` in the consuming app and set
 tokens on `:root`. This applies to every `StepperList` across the site.
@@ -78,7 +103,15 @@ tokens on `:root`. This applies to every `StepperList` across the site.
 
 ---
 
-## Page-scoped overrides
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): 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: `.claude/skills/component-local-style-override.md`.
+
+### Page or section
 
 Override tokens for a specific section by scoping them under the page or layout wrapper.
 No `:deep()` is required (component styles are unscoped).
@@ -96,9 +129,7 @@ No `:deep()` is required (component styles are unscoped).
 }
 ```
 
----
-
-## Per-instance overrides via styleClassPassthrough
+### One instance
 
 Use sparingly — prefer global or page-scoped CSS. When a single instance needs a distinct
 visual style, pass a modifier class:
@@ -125,6 +156,13 @@ visual style, pass a modifier class:
 
 ---
 
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root `<ul>`/`<ol>`. Tokens set on a passthrough class
+land for the whole list. Reactive after mount.
+
+---
+
 ## Notes
 
 - `--stepper-list-counter-size` takes precedence over the `indicatorSize` prop. Use the prop
@@ -136,3 +174,4 @@ visual style, pass a modifier class:
 - All border tokens (`--stepper-list-counter-*-border`) control the **colour** only — the
   border is always `2px solid`. Override the border shorthand directly on `.stepper-list li
   .stepper-list__indicator-counter::before` if you need a different width.
+

package/app/components/02.molecules/stepper-list/StepperList.vue

@@ -46,7 +46,12 @@ const props = withDefaults(defineProps<Props>(), {
   styleClassPassthrough: () => [],
 });
 
-const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => resetElementClasses(props.styleClassPassthrough)
+);
 
 const listEl = ref<HTMLElement | null>(null);
 let resizeObserver: ResizeObserver | null = null;
@@ -104,31 +109,6 @@ watch(
     --_padding-block: var(--stepper-list-padding-block, 1.2rem);
     --_gap: var(--stepper-list-gap, 2.2rem);
     --_counter-size: var(--stepper-list-counter-size, v-bind(indicatorSize));
-    --_counter-font-size: var(--stepper-list-counter-font-size, 1.4rem);
-    --_counter-font-weight: var(--stepper-list-counter-font-weight, 600);
-    --_connector-width: var(--stepper-list-connector-width, 0.2rem);
-
-    /* Colours */
-    --_connector-color: var(--stepper-list-connector-color, currentColor);
-    --_icon-color: var(--stepper-list-icon-color, currentColor);
-
-    /* Circle indicator */
-    --_counter-circle-background: var(--stepper-list-counter-circle-background, transparent);
-    --_counter-circle-text: var(--stepper-list-counter-circle-text, currentColor);
-    --_counter-circle-border-color: var(--stepper-list-counter-circle-border, currentColor);
-    --_counter-circle-border-radius: var(--stepper-list-counter-circle-border-radius, 100vw);
-
-    /* Disc indicator */
-    --_counter-disc-background: var(--stepper-list-counter-disc-background, transparent);
-    --_counter-disc-text: var(--stepper-list-counter-disc-text, currentColor);
-    --_counter-disc-border-color: var(--stepper-list-counter-disc-border, transparent);
-    --_counter-disc-border-radius: var(--stepper-list-counter-disc-border-radius, 100vw);
-
-    /* Square indicator */
-    --_counter-square-background: var(--stepper-list-counter-square-background, transparent);
-    --_counter-square-text: var(--stepper-list-counter-square-text, currentColor);
-    --_counter-square-border-color: var(--stepper-list-counter-square-border, transparent);
-    --_counter-square-border-radius: var(--stepper-list-counter-square-border-radius, 0.25rem);
 
     list-style: none;
     counter-reset: stepper-list;
@@ -158,29 +138,29 @@ watch(
         place-content: center;
         width: var(--_counter-size);
         height: var(--_counter-size);
-        font-size: var(--_counter-font-size);
-        font-weight: var(--_counter-font-weight);
+        font-size: var(--stepper-list-counter-font-size, 1.4rem);
+        font-weight: var(--stepper-list-counter-font-weight, 600);
       }
 
       &.indicator-circle .stepper-list__indicator-counter::before {
-        background-color: var(--_counter-circle-background);
-        color: var(--_counter-circle-text);
-        border: 2px solid var(--_counter-circle-border-color);
-        border-radius: var(--_counter-circle-border-radius);
+        background-color: var(--stepper-list-counter-circle-background, transparent);
+        color: var(--stepper-list-counter-circle-text, currentColor);
+        border: 2px solid var(--stepper-list-counter-circle-border, currentColor);
+        border-radius: var(--stepper-list-counter-circle-border-radius, 100vw);
       }
 
       &.indicator-disc .stepper-list__indicator-counter::before {
-        background-color: var(--_counter-disc-background);
-        color: var(--_counter-disc-text);
-        border: 2px solid var(--_counter-disc-border-color);
-        border-radius: var(--_counter-disc-border-radius);
+        background-color: var(--stepper-list-counter-disc-background, transparent);
+        color: var(--stepper-list-counter-disc-text, currentColor);
+        border: 2px solid var(--stepper-list-counter-disc-border, transparent);
+        border-radius: var(--stepper-list-counter-disc-border-radius, 100vw);
       }
 
       &.indicator-square .stepper-list__indicator-counter::before {
-        background-color: var(--_counter-square-background);
-        color: var(--_counter-square-text);
-        border: 2px solid var(--_counter-square-border-color);
-        border-radius: var(--_counter-square-border-radius);
+        background-color: var(--stepper-list-counter-square-background, transparent);
+        color: var(--stepper-list-counter-square-text, currentColor);
+        border: 2px solid var(--stepper-list-counter-square-border, transparent);
+        border-radius: var(--stepper-list-counter-square-border-radius, 0.25rem);
       }
 
       &.has-indicator::before {
@@ -198,7 +178,7 @@ watch(
         justify-content: center;
 
         .indicator-icon {
-          color: var(--_icon-color);
+          color: var(--stepper-list-icon-color, currentColor);
           width: var(--_counter-size) !important;
           height: var(--_counter-size) !important;
         }
@@ -216,8 +196,8 @@ watch(
     top: var(--_connector-top, calc(var(--_padding-block) + var(--_counter-size)));
     height: var(--_connector-height, auto);
     bottom: calc(-1 * var(--_padding-block));
-    width: var(--_connector-width);
-    background-color: var(--_connector-color);
+    width: var(--stepper-list-connector-width, 0.2rem);
+    background-color: var(--stepper-list-connector-color, currentColor);
   }
 }
 </style>

package/app/components/02.molecules/stepper-list/tests/StepperList.spec.ts

@@ -118,6 +118,15 @@ describe("StepperList", () => {
     expect(wrapper.classes()).toContain("class-b");
   });
 
+  it("updates classes when styleClassPassthrough changes after mount", async () => {
+    const wrapper = await mountSuspended(StepperList, {
+      props: { itemCount: 1, styleClassPassthrough: ["original"] },
+    });
+    await wrapper.setProps({ styleClassPassthrough: ["updated"] });
+    expect(wrapper.classes()).not.toContain("original");
+    expect(wrapper.classes()).toContain("updated");
+  });
+
   it("renders cleanly with no styleClassPassthrough prop", async () => {
     const wrapper = await mountSuspended(StepperList, {
       props: { itemCount: 1 },

package/app/components/{01.atoms → 02.molecules}/toast/CONSUMER-STYLING.md

@@ -25,3 +25,17 @@ with a strict priority order between them.
   --display-toast-provider-z-index: 1000000;
 }
 ```
+
+---
+
+## Local overrides
+
+The `--display-toast-z-index` and `--display-toast-provider-z-index` tokens above are only read,
+never declared on the toast, so they work from any ancestor, though a global `:root` value is usually
+what you want for a `position: fixed` overlay. Anything else is a direct property, scoped to an
+element you own (a page or section class, or a class added with `:style-class-passthrough`). 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:
+`.claude/skills/component-local-style-override.md`.
+

package/app/components/{01.atoms → 02.molecules}/toast/DisplayToast.vue

@@ -229,7 +229,6 @@ onBeforeRouteLeave(() => {
     }
 
     /* See the matching comment in DisplayToastProvider.vue — same fix, same rationale. */
-    --_z-index: var(--display-toast-z-index, 999999);
 
     display: block;
     overflow: hidden;
@@ -237,7 +236,7 @@ onBeforeRouteLeave(() => {
     margin: 0;
     opacity: 0;
 
-    z-index: var(--_z-index);
+    z-index: var(--display-toast-z-index, 999999);
 
     /* Focus styles for accessibility */
     &:focus {