srcdev-nuxt-components 9.6.10 → 9.6.12

package/app/components/01.atoms/alert-mask/stories/AlertMask.stories.ts

@@ -0,0 +1,198 @@
+import { ref } from "vue";
+import AlertMask from "../AlertMask.vue";
+import CanvasSwitcher from "../../canvas-switcher/CanvasSwitcher.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+import type { MediaCanvas } from "~/types/components";
+
+const meta: Meta<typeof AlertMask> = {
+  title: "Atoms/AlertMask",
+  component: AlertMask,
+  argTypes: {
+    config: {
+      control: "object",
+      description:
+        "Border/background colour and geometry: backgroundColour, borderColour, radiusLeft, radiusRight, borderLeft, borderTop, borderRight, borderBottom",
+      table: { category: "Basic" },
+    },
+    styleClassPassthrough: {
+      table: { disable: true },
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Draws a border and translucent fill around slotted content as an SVG path, sized to the measured content. Geometry (radii and per-side border widths) comes from the `config` prop; colours default from `--alert-mask-border-colour` and `--alert-mask-background-colour`, and `config` colours override them. [AlertMaskedContent](?path=/story/molecules-alertmaskedcontent--default) is the alert built on it.",
+      },
+    },
+  },
+  decorators: [
+    (story, context) => ({
+      components: { story, CanvasSwitcher },
+      setup() {
+        const canvasName = ref<MediaCanvas>(context.parameters.initialCanvas ?? "fullWidthCanvas");
+        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;">
+          <p style="margin: 0 0 1.6rem; font-size: 1.4rem;">
+            The alert built on this mask is
+            <a href="/?path=/story/molecules-alertmaskedcontent--default" target="_top">AlertMaskedContent</a>.
+          </p>
+          <story />
+        </div>
+      `,
+    }),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof AlertMask>;
+
+// The mask is a translucent fill plus a cut-out border, so it needs something busy behind it to read at all.
+const backdrop =
+  "background: url('/images/banners/video/lake-banner.jpg') center / cover; padding: 4rem 2.4rem; border-radius: 1.2rem; max-width: 60rem;";
+const gradientBackdrop =
+  "background: 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(65% 0.2 200) 60%, oklch(55% 0.22 300)); padding: 4rem 2.4rem; border-radius: 1.2rem; max-width: 60rem;";
+
+export const Default: Story = {
+  args: { config: {} },
+  render: (args) => ({
+    components: { AlertMask },
+    setup() {
+      return { args, gradientBackdrop };
+    },
+    template: `
+      <div data-theme="info" :style="gradientBackdrop">
+        <AlertMask v-bind="args">
+          <p style="margin: 0; padding: 1.6rem;">Default geometry and token colours: an 8px theme-accent border and a translucent subtle-surface fill.</p>
+        </AlertMask>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: { description: { story: "No config: default radii and borders, colours from the CSS tokens and the surrounding `data-theme`." } },
+  },
+};
+
+export const CustomConfig: Story = {
+  args: {
+    config: {
+      backgroundColour: "rgba(0, 0, 0, 0.3)",
+      borderColour: "var(--theme-accent)",
+      radiusLeft: 8,
+      radiusRight: 4,
+      borderLeft: 6,
+      borderTop: 1,
+      borderRight: 1,
+      borderBottom: 1,
+    },
+  },
+  render: (args) => ({
+    components: { AlertMask },
+    setup() {
+      return { args, backdrop };
+    },
+    template: `
+      <div data-theme="info" :style="backdrop">
+        <AlertMask v-bind="args">
+          <p style="margin: 0; padding: 1.6rem; color: white;">Custom accent-bar config, matching AlertMaskedContent's default shape</p>
+        </AlertMask>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "The accent-bar shape used by AlertMaskedContent: thick left radius/border, thin elsewhere.",
+      },
+    },
+  },
+};
+
+export const OverGradient: Story = {
+  args: {
+    config: {
+      backgroundColour: "rgba(0, 0, 0, 0.3)",
+      borderColour: "white",
+      radiusLeft: 16,
+      radiusRight: 16,
+      borderLeft: 4,
+      borderTop: 4,
+      borderRight: 4,
+      borderBottom: 4,
+    },
+  },
+  render: (args) => ({
+    components: { AlertMask },
+    setup() {
+      return { args, gradientBackdrop };
+    },
+    template: `
+      <div :style="gradientBackdrop">
+        <AlertMask v-bind="args">
+          <p style="margin: 0; padding: 1.6rem; color: white;">Even border all round: the stripes show through the fill and stop at the border's inner edge.</p>
+        </AlertMask>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "A striped gradient behind an even 4px white border, so the translucent fill and the border's cut-out are both visible.",
+      },
+    },
+  },
+};
+
+const stressConfigs = [
+  { caption: "Radii far larger than the box (500)", config: { radiusLeft: 500, radiusRight: 500 } },
+  { caption: "Negative borders and radius (clamped to 0)", config: { borderLeft: -10, borderTop: -4, radiusLeft: -8 } },
+  { caption: "Huge borders (40px) round a single word", config: { borderLeft: 40, borderTop: 40, borderRight: 40, borderBottom: 40 } },
+  { caption: "Fractional values", config: { borderLeft: 2.5, borderTop: 0.5, borderRight: 0.5, borderBottom: 0.5, radiusLeft: 6.25, radiusRight: 3.75 } },
+  { caption: "Zero borders", config: { borderLeft: 0, borderTop: 0, borderRight: 0, borderBottom: 0 } },
+];
+
+export const StressTest: Story = {
+  name: "Stress Test (Worst-Case Data)",
+  render: () => ({
+    components: { AlertMask },
+    setup() {
+      return { stressConfigs, gradientBackdrop };
+    },
+    template: `
+      <div data-theme="info" :style="gradientBackdrop" style="display: grid; gap: 2.4rem;">
+        <AlertMask :config="{ borderLeft: 6, borderTop: 1, borderRight: 1, borderBottom: 1, radiusLeft: 8, radiusRight: 4 }">
+          <p style="margin: 0; padding: 1.6rem; overflow-wrap: anywhere;">
+            📧 Datenschutzgrundverordnungskonformitätsbestätigung https://example.com/a/very/long/unbroken/url/that/should/wrap <b>not bold</b> &lt;b&gt;escaped&lt;/b&gt; يرجى إدخال بريدك الإلكتروني. Wir verwenden Ihre Adresse ausschließlich für Rückfragen zu Ihrer Bestellung bei Alex Morgan in Northtown.
+          </p>
+        </AlertMask>
+        <div dir="rtl">
+          <AlertMask :config="{ borderLeft: 6, borderTop: 1, borderRight: 1, borderBottom: 1, radiusLeft: 8, radiusRight: 4 }">
+            <p style="margin: 0; padding: 1.6rem;">نص من اليمين إلى اليسار داخل القناع، مع شريط التمييز على اليسار</p>
+          </AlertMask>
+        </div>
+        <AlertMask></AlertMask>
+        <div v-for="item in stressConfigs" :key="item.caption">
+          <p style="margin: 0 0 0.8rem; font-size: 1.4rem;">{{ item.caption }}</p>
+          <AlertMask :config="item.config">
+            <p style="margin: 0; padding: 0.8rem;">x</p>
+          </AlertMask>
+        </div>
+      </div>
+    `,
+  }),
+  parameters: {
+    initialCanvas: "mobileCanvas",
+    docs: {
+      story: { inline: false, height: "1100px" },
+      description: {
+        story:
+          "Long German copy with an unbroken compound word and URL, HTML-like and right-to-left text, an empty mask, then hostile config: oversized radii, negative and fractional values, huge and zero borders. Check at every canvas width: the frame always hugs its content inside the dashed outline, no path draws outside the box or inverts, the thick bar stays on the left in the right-to-left mask with the text clear of it, and the empty mask collapses to a border-only frame.",
+      },
+    },
+  },
+};

package/app/components/01.atoms/alert-mask/tests/AlertMask.spec.ts

@@ -0,0 +1,233 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import { defineComponent, nextTick } from "vue";
+import AlertMask from "../AlertMask.vue";
+import type { AlertMaskConfig } from "~/types/components";
+
+interface AlertMaskInstance {
+  cfg: {
+    backgroundColour: string | undefined;
+    borderColour: string | undefined;
+    radiusLeft: number;
+    radiusRight: number;
+    borderLeft: number;
+    borderTop: number;
+    borderRight: number;
+    borderBottom: number;
+  };
+  contentWidth: number;
+  contentHeight: number;
+  measured: boolean;
+  svgWidth: number;
+  svgHeight: number;
+  outerPath: string;
+  innerPath: string;
+}
+
+// Vitest 4: a mock's implementation must be a regular function (not an arrow function) to stay
+// constructible via `new`.
+const mockResizeObserver = vi.fn(function () {
+  return { observe: vi.fn(), unobserve: vi.fn(), disconnect: vi.fn() };
+});
+vi.stubGlobal("ResizeObserver", mockResizeObserver);
+
+const mounted: { unmount: () => void }[] = [];
+
+const mountMask = async (options: Parameters<typeof mountSuspended<typeof AlertMask>>[1] = {}) => {
+  const wrapper = await mountSuspended(AlertMask, options);
+  mounted.push(wrapper);
+  return wrapper;
+};
+
+const vmOf = (wrapper: Awaited<ReturnType<typeof mountMask>>) => wrapper.vm as unknown as AlertMaskInstance;
+
+const setContentSize = async (vm: AlertMaskInstance, width: number, height: number) => {
+  vm.contentWidth = width;
+  vm.contentHeight = height;
+  vm.measured = true;
+  await nextTick();
+};
+
+const numbersIn = (path: string) => (path.match(/-?\d+(\.\d+)?/g) ?? []).map(Number);
+
+describe("AlertMask", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    mounted.splice(0).forEach((wrapper) => wrapper.unmount());
+    vi.restoreAllMocks();
+  });
+
+  it("renders the root, decorator and content structure", async () => {
+    const wrapper = await mountMask();
+    expect(wrapper.find(".alert-mask").exists()).toBe(true);
+    expect(wrapper.find(".alert-mask-decorator").exists()).toBe(true);
+    expect(wrapper.find(".alert-mask-border").exists()).toBe(true);
+    expect(wrapper.find(".alert-mask-background").exists()).toBe(true);
+    expect(wrapper.find(".alert-mask-content-slot").exists()).toBe(true);
+  });
+
+  it("renders default slot content", async () => {
+    const wrapper = await mountMask({ slots: { default: "<p class='test-content'>Alert</p>" } });
+    expect(wrapper.find(".test-content").text()).toBe("Alert");
+  });
+
+  it("applies passthrough classes and reacts to changes", async () => {
+    const wrapper = await mountMask({ props: { styleClassPassthrough: ["one", "two"] } });
+    const root = () => wrapper.find(".alert-mask");
+    expect(root().classes()).toEqual(expect.arrayContaining(["one", "two"]));
+
+    await wrapper.setProps({ styleClassPassthrough: "three" });
+    expect(root().classes()).toContain("three");
+    expect(root().classes()).not.toContain("one");
+  });
+
+  it("uses default geometry and leaves colours to CSS tokens when no config is given", async () => {
+    const vm = vmOf(await mountMask());
+    expect(vm.cfg).toEqual({
+      backgroundColour: undefined,
+      borderColour: undefined,
+      radiusLeft: 12,
+      radiusRight: 12,
+      borderLeft: 8,
+      borderTop: 8,
+      borderRight: 8,
+      borderBottom: 8,
+    });
+  });
+
+  it("applies a full custom config", async () => {
+    const config: AlertMaskConfig = {
+      backgroundColour: "rgba(255,0,0,0.5)",
+      borderColour: "#ff0000",
+      radiusLeft: 20,
+      radiusRight: 15,
+      borderLeft: 12,
+      borderTop: 10,
+      borderRight: 8,
+      borderBottom: 6,
+    };
+    const vm = vmOf(await mountMask({ props: { config } }));
+    expect(vm.cfg).toEqual(config);
+  });
+
+  it("sanitises negative and non-finite sizes", async () => {
+    const vm = vmOf(
+      await mountMask({
+        props: { config: { borderLeft: -10, borderTop: Number.NaN, radiusLeft: -4, radiusRight: Infinity } },
+      })
+    );
+    expect(vm.cfg.borderLeft).toBe(0);
+    expect(vm.cfg.borderTop).toBe(8);
+    expect(vm.cfg.radiusLeft).toBe(0);
+    expect(vm.cfg.radiusRight).toBe(12);
+  });
+
+  it("only sets fill styles for colours given in config", async () => {
+    const plain = await mountMask();
+    expect(plain.find(".alert-mask-border").attributes("style")).toBeUndefined();
+    expect(plain.find(".alert-mask-background").attributes("style")).toBeUndefined();
+
+    const custom = await mountMask({
+      props: { config: { borderColour: "var(--my-border)", backgroundColour: "var(--my-bg)" } },
+    });
+    expect((custom.find(".alert-mask-border").element as unknown as SVGElement).style.fill).toBe("var(--my-border)");
+    expect((custom.find(".alert-mask-background").element as unknown as SVGElement).style.fill).toBe("var(--my-bg)");
+  });
+
+  it("gives each instance its own mask id", async () => {
+    const Host = defineComponent({
+      components: { AlertMask },
+      template: "<div><AlertMask>One</AlertMask><AlertMask>Two</AlertMask></div>",
+    });
+    const wrapper = await mountSuspended(Host);
+    mounted.push(wrapper);
+    const ids = wrapper.findAll("mask").map((mask) => mask.attributes("id"));
+    expect(new Set(ids).size).toBe(2);
+    expect(wrapper.findAll(".alert-mask-border")[0]!.attributes("mask")).toBe(`url(#${ids[0]})`);
+  });
+
+  it("hides the decorative SVG from assistive technology", async () => {
+    const wrapper = await mountMask();
+    expect(wrapper.find(".alert-mask-decorator").attributes("aria-hidden")).toBe("true");
+  });
+
+  it("insets the content by the configured borders", async () => {
+    const wrapper = await mountMask({
+      props: { config: { borderLeft: 15, borderTop: 20, borderRight: 25, borderBottom: 30 } },
+    });
+    const style = (wrapper.find(".alert-mask-content").element as HTMLElement).style;
+    expect(style.getPropertyValue("--_inset-left")).toBe("15px");
+    expect(style.getPropertyValue("--_inset-top")).toBe("20px");
+    expect(style.getPropertyValue("--_inset-right")).toBe("25px");
+    expect(style.getPropertyValue("--_inset-bottom")).toBe("30px");
+  });
+
+  it("insets the content by the default borders when config omits them", async () => {
+    const style = ((await mountMask()).find(".alert-mask-content").element as HTMLElement).style;
+    expect(style.getPropertyValue("--_inset-left")).toBe("8px");
+    expect(style.getPropertyValue("--_inset-bottom")).toBe("8px");
+  });
+
+  it("observes the content and disconnects on unmount", async () => {
+    const wrapper = await mountMask({ slots: { default: "<div>Content</div>" } });
+    expect(mockResizeObserver).toHaveBeenCalled();
+    const observer = mockResizeObserver.mock.results.at(-1)?.value as { disconnect: ReturnType<typeof vi.fn> };
+    wrapper.unmount();
+    mounted.splice(mounted.indexOf(wrapper), 1);
+    expect(observer.disconnect).toHaveBeenCalled();
+  });
+
+  it("draws nothing until the content is measured", async () => {
+    const vm = vmOf(await mountMask());
+    vm.measured = false;
+    await nextTick();
+    expect(vm.svgWidth).toBe(0);
+    expect(vm.outerPath).toBe("");
+    expect(vm.innerPath).toBe("");
+  });
+
+  it("sizes the SVG from the content plus the borders", async () => {
+    const wrapper = await mountMask();
+    const vm = vmOf(wrapper);
+    await setContentSize(vm, 200, 100);
+    expect(vm.svgWidth).toBe(216);
+    expect(vm.svgHeight).toBe(116);
+    expect((wrapper.find(".alert-mask-decorator").element as HTMLElement).style.getPropertyValue("--_height")).toBe(
+      "116px"
+    );
+    expect(vm.outerPath).not.toBe("");
+    expect(vm.innerPath).not.toBe("");
+  });
+
+  it("recomputes the size when the border config changes without a content resize", async () => {
+    const wrapper = await mountMask();
+    const vm = vmOf(wrapper);
+    await setContentSize(vm, 200, 100);
+
+    await wrapper.setProps({ config: { borderTop: 30, borderBottom: 30 } });
+    expect(vm.svgHeight).toBe(160);
+  });
+
+  it("clamps radii larger than the box so the path stays inside it", async () => {
+    const wrapper = await mountMask({ props: { config: { radiusLeft: 500, radiusRight: 500 } } });
+    const vm = vmOf(wrapper);
+    await setContentSize(vm, 200, 40);
+
+    const outer = numbersIn(vm.outerPath);
+    expect(Math.min(...outer)).toBeGreaterThanOrEqual(0);
+    expect(Math.max(...outer)).toBeLessThanOrEqual(216);
+    const inner = numbersIn(vm.innerPath);
+    expect(Math.min(...inner)).toBeGreaterThanOrEqual(0);
+  });
+
+  it("drops the inner cut-out when the borders fill the whole box", async () => {
+    const wrapper = await mountMask({ props: { config: { borderLeft: 100, borderRight: 100 } } });
+    const vm = vmOf(wrapper);
+    await setContentSize(vm, 0, 40);
+    expect(vm.outerPath).not.toBe("");
+    expect(vm.innerPath).toBe("");
+  });
+});

package/app/components/01.atoms/animations/marquee-scroller/CONSUMER-STYLING.md

@@ -2,17 +2,30 @@
 
 ## Public token API
 
+### Region
+
 | Token | Default | Controls |
 |---|---|---|
 | `--marquee-scroller-fade-width` | `10%` | Width of the transparent fade at each edge of the track (`mask-image`) |
-| `--marquee-scroller-focus-outline-width` | `2px` | Outline width on the root region and the control button when keyboard-focused (colour is `--theme-ring`) |
+| `--marquee-scroller-focus-outline-width` | `2px` | Outline width on the root region and the control button when keyboard-focused |
+| `--marquee-scroller-focus-outline-colour` | `var(--theme-ring)` | Outline colour on the same two focus states |
 | `--marquee-scroller-focus-outline-offset` | `2px` | Outline offset on the same two focus states |
+
+### Items
+
+| Token | Default | Controls |
+|---|---|---|
 | `--marquee-scroller-group-hover-filter` | `grayscale(1)` | Filter applied to every item when the pointer hovers anywhere over the scroller |
 | `--marquee-scroller-item-hover-filter` | `grayscale(0)` | Filter applied to a single item when it is individually hovered (overrides the group filter for that item) |
 | `--marquee-scroller-item-transition-duration` | `0.5s` | Transition duration for the item hover filter change |
 | `--marquee-scroller-item-border-width` | `1px` | Item border width |
 | `--marquee-scroller-item-border-colour` | `var(--slate-10)` | Item border colour |
 | `--marquee-scroller-item-border-radius` | `4px` | Item border radius |
+
+### Control button
+
+| Token | Default | Controls |
+|---|---|---|
 | `--marquee-scroller-control-offset` | `8px` | Distance of the pause/play button from the top and end edges |
 | `--marquee-scroller-control-background-colour` | `rgba(0, 0, 0, 0.7)` | Pause/play button background |
 | `--marquee-scroller-control-background-colour-hover` | `rgba(0, 0, 0, 0.9)` | Pause/play button background on hover |
@@ -21,15 +34,35 @@
 | `--marquee-scroller-control-padding` | `8px` | Pause/play button padding |
 | `--marquee-scroller-control-font-size` | `14px` | Pause/play button icon font size |
 | `--marquee-scroller-control-transition-duration` | `0.2s` | Pause/play button background-colour transition duration |
-| `--marquee-scroller-control-border-width` | `1px` | Pause/play button border width in forced-colors/high-contrast mode (`prefers-contrast: high`). The border colour itself stays the system `ButtonText` keyword — see note below. |
+| `--marquee-scroller-control-border-width` | `1px` | Pause/play button border width under `prefers-contrast: high`. The border colour itself stays the system `ButtonText` keyword, see below. |
 
-```css
-.my-page {
-  --marquee-scroller-item-border-colour: #b5651d;
-  --marquee-scroller-control-background-colour: #1a1a1a;
-  --marquee-scroller-fade-width: 20%;
-}
-```
+Private tokens (not public API): `--_fade-width`, `--_focus-outline` (width + colour, shared by
+both focus states) and `--_track-shift` (the loop distance, computed from `itemConfig`).
+
+---
+
+## State hooks
+
+The root `.marquee-scroller` carries:
+
+| Attribute | When |
+|---|---|
+| `data-paused` | The track is paused (control button, spacebar, focus inside, or reduced motion) |
+| `data-reverse` | `reverse` is `true` |
+| `data-reduced-motion` | The user prefers reduced motion and `respect-reduced-motion` is on |
+
+Inner elements: `.marquee-scroller-track` (the animated row), `.marquee-scroller-group` (one copy
+of the items; the second is `aria-hidden` and `inert`), `.marquee-scroller-item` (one fixed-size
+item box), `.marquee-scroller-control` (the pause/play `InputButton`) and
+`.marquee-scroller-description` (the visually hidden instructions).
+
+> **Changed 2026-10-17**: the generic class names were renamed so they can't collide with consumer
+> CSS. `.item` → `.marquee-scroller-item`, `.control-btn` → `.marquee-scroller-control` (now an
+> `InputButton`, so it also has `.input-button`), `.marquee-track` → `.marquee-scroller-track`,
+> `.marquee-group` → `.marquee-scroller-group`, `.sr-only` → `.marquee-scroller-description`. The
+> bare state classes became attributes: `.reverse` → `[data-reverse]`, `.paused` →
+> `[data-paused]`, `.reduced-motion` → `[data-reduced-motion]`. The keyframes are now
+> `marquee-scroller-move` (was `marqueeMove`).
 
 ---
 
@@ -37,10 +70,9 @@
 
 Under `prefers-contrast: high`, the control button switches to the system colour keywords
 `ButtonFace`/`ButtonText` rather than the component's own background/text tokens. These aren't
-exposed as overridable tokens on purpose — they're meant to track the user's OS-level high-contrast
-theme, which a component-level override would defeat. Only the border *width* in that mode is a
-token (`--marquee-scroller-control-border-width`), since it's a plain dimension with no such
-constraint.
+exposed as overridable tokens on purpose: they track the user's OS-level high-contrast theme, which
+a component-level override would defeat. Only the border *width* in that mode is a token
+(`--marquee-scroller-control-border-width`), since it's a plain dimension with no such constraint.
 
 ---
 
@@ -48,7 +80,7 @@ constraint.
 
 Item `width`/`height`/`gap` and the animation duration are set via the `itemConfig` and
 `animationRuntime` props (not CSS custom properties), since they also drive the component's own
-layout math (`aspect-ratio`, track width). Override those through props:
+loop math (`--_track-shift`) and the repeat measurement. Override those through props:
 
 ```vue
 <MarqueeScroller
@@ -57,58 +89,49 @@ layout math (`aspect-ratio`, track width). Override those through props:
 />
 ```
 
----
+Item boxes are a fixed size. Text in an item wraps (`overflow-wrap: anywhere`), but content taller
+than `itemConfig.height` overflows, so size slot content to the box.
 
-## Item content via slots
+---
 
-Each entry in `marqueeData` (`{ id, content }`) renders a slot named after its `id`. Provide the
-markup for each item via that dynamically-named slot:
+## Global theming
 
-```vue
-<MarqueeScroller :marquee-data="[{ id: 1, content: 'logo-a' }, { id: 2, content: 'logo-b' }]">
-  <template #1>
-    <img src="/logos/a.svg" alt="Logo A" />
-  </template>
-  <template #2>
-    <img src="/logos/b.svg" alt="Logo B" />
-  </template>
-</MarqueeScroller>
+```css
+:where(html) {
+  --marquee-scroller-fade-width: 15%;
+  --marquee-scroller-item-border-colour: var(--slate-04);
+}
 ```
 
 ---
 
-## Control button icon and copy
-
-The pause/play button's icon and its `aria-label` copy are all overridable — see `playIcon`/
-`pauseIcon`/`playLabel`/`pauseLabel` props, or the `toggle-icon` slot for a fully custom icon
-(scoped with `isPaused`):
+## Local overrides
 
-```vue
-<MarqueeScroller
-  show-controls
-  play-icon="mdi:play-circle"
-  pause-icon="mdi:pause-circle"
-  play-label="Reproduire"
-  pause-label="Suspendre"
-/>
-```
+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`.
 
-```vue
-<MarqueeScroller show-controls>
-  <template #toggle-icon="{ isPaused }">
-    <Icon :name="isPaused ? 'lucide:play' : 'lucide:pause'" />
-  </template>
-</MarqueeScroller>
+```css
+.partners-section {
+  --marquee-scroller-item-border-colour: #b5651d;
+  --marquee-scroller-control-background-colour: #1a1a1a;
+  --marquee-scroller-fade-width: 20%;
+}
 ```
 
 ---
 
-## Local overrides
+## Class passthrough
+
+`:style-class-passthrough` (string or string array) adds classes to the root `.marquee-scroller`
+region.
+
+---
 
-Set the tokens above on an element you own (a page or section class, or a plain `class` on the
-component (it falls through to the root element)): 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`.
+## Notes
 
+- Item content and the control button's icon and copy are covered in the skill doc
+  (`marquee-scroller.md`): one slot per `marqueeData` id, `toggle-icon` slot, and the
+  `playIcon`/`pauseIcon`/`playLabel`/`pauseLabel` props.