srcdev-nuxt-components 9.4.12 → 9.5.1

package/app/components/01.atoms/animations/scroll-reveal-frame/stories/ScrollRevealFrame.stories.ts

@@ -164,3 +164,51 @@ export const ShortFrame: Story = {
     },
   },
 };
+
+export const ResponsiveTokens: Story = {
+  args: {},
+  render: (args) => ({
+    components: { ScrollRevealFrame },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div style="padding-block: 60vh; max-width: 860px; margin-inline: auto;">
+        <component is="style">
+          .srf-story-responsive {
+            --scroll-reveal-frame-height: 280px;
+            --scroll-reveal-frame-parallax-offset: 18rem;
+            --scroll-reveal-frame-radius: 0.8rem;
+          }
+          @media (width >= 768px) {
+            .srf-story-responsive {
+              --scroll-reveal-frame-height: 540px;
+              --scroll-reveal-frame-parallax-offset: 36rem;
+              --scroll-reveal-frame-radius: 2.4rem;
+            }
+          }
+        </component>
+        <p style="text-align: center; font-size: 1.4rem; opacity: 0.5; margin-block-end: 4rem;">
+          Resize below/above 768px and scroll: height, travel and radius come from CSS tokens, no props passed
+        </p>
+        <div class="srf-story-responsive">
+          <ScrollRevealFrame v-bind="args">
+            <img
+              src="/images/page/hero/hero-blonde.jpg"
+              alt="Blonde hair portrait"
+              style="display: block; width: 100%; height: 100%; object-fit: cover;"
+            />
+          </ScrollRevealFrame>
+        </div>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "No sizing props are passed, so the frame reads --scroll-reveal-frame-height/-parallax-offset/-radius from an ancestor class with a media query. A prop, when passed, is written inline and wins over these.",
+      },
+    },
+  },
+};

package/app/components/01.atoms/animations/scroll-reveal-frame/tests/ScrollRevealFrame.spec.ts

@@ -2,6 +2,8 @@ import { describe, it, expect } from "vitest";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
 import ScrollRevealFrame from "../ScrollRevealFrame.vue";
 
+const styleOf = (el: Element) => (el as HTMLElement).style;
+
 describe("ScrollRevealFrame", () => {
   // ─── Mount ───────────────────────────────────────────────────────────────
 
@@ -36,80 +38,85 @@ describe("ScrollRevealFrame", () => {
     expect(wrapper.element.tagName).toBe("FIGURE");
   });
 
-  it("always has the reveal-frame class", async () => {
+  it("always has the scroll-reveal-frame class", async () => {
     const wrapper = await mountSuspended(ScrollRevealFrame);
-    expect(wrapper.classes()).toContain("reveal-frame");
+    expect(wrapper.classes()).toContain("scroll-reveal-frame");
   });
 
   // ─── Inner content wrapper ───────────────────────────────────────────────
 
-  it("renders a .reveal-content child element", async () => {
+  it("renders a .scroll-reveal-frame-content child element", async () => {
     const wrapper = await mountSuspended(ScrollRevealFrame);
-    expect(wrapper.find(".reveal-content").exists()).toBe(true);
+    expect(wrapper.find(".scroll-reveal-frame-content").exists()).toBe(true);
   });
 
   // ─── Slot ────────────────────────────────────────────────────────────────
 
-  it("renders slot content inside .reveal-content", async () => {
+  it("renders slot content inside .scroll-reveal-frame-content", async () => {
     const wrapper = await mountSuspended(ScrollRevealFrame, {
       slots: { default: "<p class='slot-child'>Hello</p>" },
     });
-    const content = wrapper.find(".reveal-content");
+    const content = wrapper.find(".scroll-reveal-frame-content");
     expect(content.find(".slot-child").exists()).toBe(true);
     expect(content.find(".slot-child").text()).toBe("Hello");
   });
 
-  it("renders multiple slot children inside .reveal-content", async () => {
+  it("renders multiple slot children inside .scroll-reveal-frame-content", async () => {
     const wrapper = await mountSuspended(ScrollRevealFrame, {
       slots: { default: "<div class='child-a'></div><div class='child-b'></div>" },
     });
-    const content = wrapper.find(".reveal-content");
+    const content = wrapper.find(".scroll-reveal-frame-content");
     expect(content.find(".child-a").exists()).toBe(true);
     expect(content.find(".child-b").exists()).toBe(true);
   });
 
   // ─── CSS custom properties ───────────────────────────────────────────────
 
-  it("sets --_frame-height to 540px by default", async () => {
+  it("sets no inline tokens by default, so CSS overrides and defaults apply", async () => {
     const wrapper = await mountSuspended(ScrollRevealFrame);
-    const style = (wrapper.element as HTMLElement).style;
-    expect(style.getPropertyValue("--_frame-height")).toBe("540px");
+    const style = styleOf(wrapper.element);
+    expect(style.getPropertyValue("--scroll-reveal-frame-height")).toBe("");
+    expect(style.getPropertyValue("--scroll-reveal-frame-parallax-offset")).toBe("");
+    expect(style.getPropertyValue("--scroll-reveal-frame-radius")).toBe("");
+    expect(wrapper.attributes("style")).toBeUndefined();
   });
 
-  it("sets --_parallax-offset to 36rem by default", async () => {
-    const wrapper = await mountSuspended(ScrollRevealFrame);
-    const style = (wrapper.element as HTMLElement).style;
-    expect(style.getPropertyValue("--_parallax-offset")).toBe("36rem");
+  it("reflects frameHeight prop in --scroll-reveal-frame-height", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame, {
+      props: { frameHeight: "80vh" },
+    });
+    expect(styleOf(wrapper.element).getPropertyValue("--scroll-reveal-frame-height")).toBe("80vh");
   });
 
-  it("sets --_radius to 0px by default", async () => {
-    const wrapper = await mountSuspended(ScrollRevealFrame);
-    const style = (wrapper.element as HTMLElement).style;
-    expect(style.getPropertyValue("--_radius")).toBe("0px");
+  it("reflects parallaxOffset prop in --scroll-reveal-frame-parallax-offset", async () => {
+    const wrapper = await mountSuspended(ScrollRevealFrame, {
+      props: { parallaxOffset: "48rem" },
+    });
+    expect(styleOf(wrapper.element).getPropertyValue("--scroll-reveal-frame-parallax-offset")).toBe("48rem");
   });
 
-  it("reflects frameHeight prop in --_frame-height", async () => {
+  it("reflects radius prop in --scroll-reveal-frame-radius", async () => {
     const wrapper = await mountSuspended(ScrollRevealFrame, {
-      props: { frameHeight: "80vh" },
+      props: { radius: "2.4rem" },
     });
-    const style = (wrapper.element as HTMLElement).style;
-    expect(style.getPropertyValue("--_frame-height")).toBe("80vh");
+    expect(styleOf(wrapper.element).getPropertyValue("--scroll-reveal-frame-radius")).toBe("2.4rem");
   });
 
-  it("reflects parallaxOffset prop in --_parallax-offset", async () => {
+  it("only sets the tokens whose props were passed", async () => {
     const wrapper = await mountSuspended(ScrollRevealFrame, {
-      props: { parallaxOffset: "48rem" },
+      props: { radius: "1rem" },
     });
-    const style = (wrapper.element as HTMLElement).style;
-    expect(style.getPropertyValue("--_parallax-offset")).toBe("48rem");
+    const style = styleOf(wrapper.element);
+    expect(style.getPropertyValue("--scroll-reveal-frame-radius")).toBe("1rem");
+    expect(style.getPropertyValue("--scroll-reveal-frame-height")).toBe("");
   });
 
-  it("reflects radius prop in --_radius", async () => {
+  it("removes the inline token when the prop is cleared", async () => {
     const wrapper = await mountSuspended(ScrollRevealFrame, {
-      props: { radius: "2.4rem" },
+      props: { frameHeight: "400px" },
     });
-    const style = (wrapper.element as HTMLElement).style;
-    expect(style.getPropertyValue("--_radius")).toBe("2.4rem");
+    await wrapper.setProps({ frameHeight: undefined });
+    expect(styleOf(wrapper.element).getPropertyValue("--scroll-reveal-frame-height")).toBe("");
   });
 
   // ─── styleClassPassthrough ───────────────────────────────────────────────
@@ -129,11 +136,11 @@ describe("ScrollRevealFrame", () => {
     expect(wrapper.classes()).toContain("mbe-32");
   });
 
-  it("does not apply styleClassPassthrough to .reveal-content", async () => {
+  it("does not apply styleClassPassthrough to .scroll-reveal-frame-content", async () => {
     const wrapper = await mountSuspended(ScrollRevealFrame, {
       props: { styleClassPassthrough: "hero-frame" },
     });
-    expect(wrapper.find(".reveal-content").classes()).not.toContain("hero-frame");
+    expect(wrapper.find(".scroll-reveal-frame-content").classes()).not.toContain("hero-frame");
   });
 
   it("updates classes when styleClassPassthrough prop changes", async () => {

package/app/components/01.atoms/animations/scroll-reveal-frame/tests/__snapshots__/ScrollRevealFrame.spec.ts.snap

@@ -1,13 +1,13 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`ScrollRevealFrame > renders correct HTML structure (all props set) 1`] = `
-"<figure class="reveal-frame custom-class" style="--_frame-height: 400px; --_parallax-offset: 20rem; --_radius: 1.6rem;">
-  <div class="reveal-content"></div>
+"<figure class="scroll-reveal-frame custom-class" style="--scroll-reveal-frame-height: 400px; --scroll-reveal-frame-parallax-offset: 20rem; --scroll-reveal-frame-radius: 1.6rem;">
+  <div class="scroll-reveal-frame-content"></div>
 </figure>"
 `;
 
 exports[`ScrollRevealFrame > renders correct HTML structure (default props) 1`] = `
-"<figure class="reveal-frame" style="--_frame-height: 540px; --_parallax-offset: 36rem; --_radius: 0px;">
-  <div class="reveal-content"></div>
+"<figure class="scroll-reveal-frame">
+  <div class="scroll-reveal-frame-content"></div>
 </figure>"
 `;

package/app/components/01.atoms/animations/scroll-reveal-image/CONSUMER-STYLING.md

@@ -0,0 +1,74 @@
+# ScrollRevealImage — Consumer Styling Guide
+
+`ScrollRevealImage` renders a `ScrollRevealFrame` with a single `NuxtImg` inside. Frame sizing uses
+the frame's own tokens; this component adds the image crop tokens.
+
+## Public token API
+
+### Frame (from ScrollRevealFrame)
+
+| Token | Default | Set by prop |
+|---|---|---|
+| `--scroll-reveal-frame-height` | `540px` | `frameHeight` |
+| `--scroll-reveal-frame-parallax-offset` | `36rem` | `parallaxOffset` |
+| `--scroll-reveal-frame-radius` | `0px` | `radius` |
+
+See `ScrollRevealFrame`'s `CONSUMER-STYLING.md` for details.
+
+### Image crop
+
+| Token | Default | Set by prop | Controls |
+|---|---|---|---|
+| `--scroll-reveal-image-focal-x` | `50%` | `focalX` | Horizontal `object-position` (which slice stays in view when the frame is narrower than the image) |
+| `--scroll-reveal-image-focal-y` | `0%` | none | Vertical `object-position` while the scroll animation runs |
+| `--scroll-reveal-image-focal-y-static` | `50%` | none | Vertical `object-position` when there's no animation (reduced motion, or no `animation-timeline` support) |
+
+A prop, when passed, writes its token inline on the root `<figure>` and beats any CSS. None of the
+props has a default of its own, so leave one off to control that value from CSS.
+
+> **Changed 2026-09-27**: the horizontal crop was a private `--_focal-x`, always written inline from
+> a `focalX` prop that defaulted to `50%`, so CSS could never change it. The vertical crop was
+> hardcoded (`0%` animated, `50%` static) with no token at all, which pushed consumers into
+> overriding `object-position` on the image directly. Both are now public tokens.
+
+Private tokens (not public API): `--_focal-x` on the image, which resolves the public focal-x once
+for the three `object-position` declarations.
+
+## State hooks
+
+No `data-*` attributes. Classes:
+
+- `.scroll-reveal-frame`: the root `<figure>` (from `ScrollRevealFrame`).
+- `.scroll-reveal-frame-content`: the panning wrapper (from `ScrollRevealFrame`).
+- `.scroll-reveal-image`: the `<img>`.
+
+> **Changed 2026-09-27**: `.reveal-image` → `.scroll-reveal-image` (with the frame's
+> `.reveal-frame`/`.reveal-content` renames in the same release).
+
+## 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`.
+
+**Caveat:** `frameHeight`, `parallaxOffset`, `radius` and `focalX`, when passed, are written inline
+on the root and override their tokens. To drive one from CSS, don't pass its prop.
+
+## Recipe: different crop on small screens
+
+```css
+.welcome {
+  --scroll-reveal-image-focal-y: 40%;
+
+  @media (width >= 768px) {
+    --scroll-reveal-image-focal-y: 0%;
+  }
+}
+```
+
+## Class passthrough
+
+`style-class-passthrough` is forwarded to `ScrollRevealFrame` and lands on the root `<figure>`,
+not the image. Reachable in normal use.

package/app/components/01.atoms/animations/scroll-reveal-image/ScrollRevealImage.vue

@@ -4,10 +4,10 @@
     :parallax-offset="parallaxOffset"
     :radius="radius"
     :style-class-passthrough="styleClassPassthrough"
-    :style="{ '--_focal-x': focalX }"
+    :style="{ '--scroll-reveal-image-focal-x': focalX }"
   >
     <NuxtImg
-      class="reveal-image"
+      class="scroll-reveal-image"
       :src="src"
       :alt="alt"
       :width="imgWidth"
@@ -19,37 +19,14 @@
 </template>
 
 <script setup lang="ts">
-/**
- * ScrollRevealImage
- *
- * A single-image convenience wrapper around ScrollRevealFrame.
- * Adds NuxtImg optimisation (src, alt, intrinsic dimensions) and horizontal
- * focal-point control (focalX → CSS object-position x-axis).
- *
- * For a grid of images or arbitrary slot content use ScrollRevealFrame directly.
- */
-
 interface Props {
   src: string;
   alt?: string;
-  /** Intrinsic width of the source image — required for NuxtImg optimisation. */
   imgWidth?: number;
-  /** Intrinsic height of the source image — required for NuxtImg optimisation. */
   imgHeight?: number;
-  /** Height of the visible clipping frame. */
   frameHeight?: string;
-  /**
-   * How far the image travels vertically as the frame scrolls through the
-   * viewport. Larger = more image revealed = stronger parallax feel.
-   */
   parallaxOffset?: string;
-  /**
-   * Horizontal focal point — CSS `object-position` x-axis value.
-   * Controls which horizontal slice of the image is kept in view.
-   * Examples: "50%", "left", "30%".
-   */
   focalX?: string;
-  /** Optional rounded corners on the frame. */
   radius?: string;
   loading?: "lazy" | "eager";
   styleClassPassthrough?: string | string[];
@@ -59,10 +36,10 @@ withDefaults(defineProps<Props>(), {
   alt: "",
   imgWidth: 1920,
   imgHeight: 1080,
-  frameHeight: "540px",
-  parallaxOffset: "36rem",
-  focalX: "50%",
-  radius: "0px",
+  frameHeight: undefined,
+  parallaxOffset: undefined,
+  focalX: undefined,
+  radius: undefined,
   loading: "lazy",
   styleClassPassthrough: () => [],
 });
@@ -70,28 +47,21 @@ withDefaults(defineProps<Props>(), {
 
 <style lang="css">
 @layer components {
-  .reveal-image {
+  .scroll-reveal-image {
+    --_focal-x: var(--scroll-reveal-image-focal-x, 50%);
+
     display: block;
     width: 100%;
     height: 100%;
     object-fit: cover;
-    /*
-     * Y is always 0% — ScrollRevealFrame's translateY handles vertical travel.
-     * focalX (--_focal-x) lets the consumer pin the horizontal crop point.
-     */
-    object-position: var(--_focal-x, 50%) 0%;
-  }
+    object-position: var(--_focal-x) var(--scroll-reveal-image-focal-y, 0%);
 
-  /* ── Fallback: centre the crop vertically when there is no animation ── */
-  @supports not (animation-timeline: scroll()) {
-    .reveal-image {
-      object-position: var(--_focal-x, 50%) 50%;
+    @supports not (animation-timeline: scroll()) {
+      object-position: var(--_focal-x) var(--scroll-reveal-image-focal-y-static, 50%);
     }
-  }
 
-  @media (prefers-reduced-motion: reduce) {
-    .reveal-image {
-      object-position: var(--_focal-x, 50%) 50%;
+    @media (prefers-reduced-motion: reduce) {
+      object-position: var(--_focal-x) var(--scroll-reveal-image-focal-y-static, 50%);
     }
   }
 }

package/app/components/01.atoms/animations/scroll-reveal-image/stories/ScrollRevealImage.stories.ts

@@ -90,7 +90,7 @@ export const Default: Story = {
   parameters: {
     docs: {
       description: {
-        story: "All props at their default values. A portrait image panning from top to bottom as the frame crosses the viewport.",
+        story: "A portrait image panning from top to bottom as the frame crosses the viewport. The sizing values shown match the CSS defaults.",
       },
     },
   },
@@ -179,3 +179,52 @@ export const TallFrame: Story = {
     },
   },
 };
+
+export const CssTokens: Story = {
+  args: {
+    src: "/images/page/hero/hero-red.jpg",
+    alt: "Red hair portrait",
+    imgWidth: 1280,
+    imgHeight: 1920,
+  },
+  render: (args) => ({
+    components: { ScrollRevealImage },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div style="padding-block: 60vh; max-width: 860px; margin-inline: auto;">
+        <component is="style">
+          .sri-story-tokens {
+            --scroll-reveal-frame-height: 320px;
+            --scroll-reveal-frame-parallax-offset: 20rem;
+            --scroll-reveal-image-focal-x: 70%;
+            --scroll-reveal-image-focal-y: 40%;
+          }
+          @media (width >= 768px) {
+            .sri-story-tokens {
+              --scroll-reveal-frame-height: 540px;
+              --scroll-reveal-frame-parallax-offset: 36rem;
+              --scroll-reveal-image-focal-x: 50%;
+              --scroll-reveal-image-focal-y: 0%;
+            }
+          }
+        </component>
+        <p style="text-align: center; font-size: 1.4rem; opacity: 0.5; margin-block-end: 4rem;">
+          Resize below/above 768px and scroll: frame size and crop point come from CSS tokens, no props passed
+        </p>
+        <div class="sri-story-tokens">
+          <ScrollRevealImage v-bind="args" />
+        </div>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Only the image props are passed, so frame size and crop point come from --scroll-reveal-frame-* and --scroll-reveal-image-focal-x/-y on an ancestor, changing at 768px. A prop, when passed, is written inline and wins.",
+      },
+    },
+  },
+};

package/app/components/01.atoms/animations/scroll-reveal-image/tests/ScrollRevealImage.spec.ts

@@ -48,82 +48,89 @@ describe("ScrollRevealImage", () => {
     expect(wrapper.element.tagName).toBe("FIGURE");
   });
 
-  it("always has the reveal-frame class", async () => {
+  it("always has the scroll-reveal-frame class", async () => {
     const wrapper = await mountSuspended(ScrollRevealImage, {
       props: { src: "/images/test.jpg" },
     });
-    expect(wrapper.classes()).toContain("reveal-frame");
+    expect(wrapper.classes()).toContain("scroll-reveal-frame");
   });
 
   // ─── CSS custom properties ───────────────────────────────────────────────
 
-  it("sets --_frame-height to 540px by default", async () => {
+  it("leaves --scroll-reveal-frame-height unset by default (CSS default applies)", async () => {
     const wrapper = await mountSuspended(ScrollRevealImage, {
       props: { src: "/images/test.jpg" },
     });
     const style = (wrapper.element as HTMLElement).style;
-    expect(style.getPropertyValue("--_frame-height")).toBe("540px");
+    expect(style.getPropertyValue("--scroll-reveal-frame-height")).toBe("");
   });
 
-  it("sets --_parallax-offset to 36rem by default", async () => {
+  it("leaves --scroll-reveal-frame-parallax-offset unset by default (CSS default applies)", async () => {
     const wrapper = await mountSuspended(ScrollRevealImage, {
       props: { src: "/images/test.jpg" },
     });
     const style = (wrapper.element as HTMLElement).style;
-    expect(style.getPropertyValue("--_parallax-offset")).toBe("36rem");
+    expect(style.getPropertyValue("--scroll-reveal-frame-parallax-offset")).toBe("");
   });
 
-  it("sets --_radius to 0px by default", async () => {
+  it("leaves --scroll-reveal-frame-radius unset by default (CSS default applies)", async () => {
     const wrapper = await mountSuspended(ScrollRevealImage, {
       props: { src: "/images/test.jpg" },
     });
     const style = (wrapper.element as HTMLElement).style;
-    expect(style.getPropertyValue("--_radius")).toBe("0px");
+    expect(style.getPropertyValue("--scroll-reveal-frame-radius")).toBe("");
   });
 
-  it("sets --_focal-x to 50% by default", async () => {
+  it("leaves --scroll-reveal-image-focal-x unset by default (CSS default applies)", async () => {
     const wrapper = await mountSuspended(ScrollRevealImage, {
       props: { src: "/images/test.jpg" },
     });
     const style = (wrapper.element as HTMLElement).style;
-    expect(style.getPropertyValue("--_focal-x")).toBe("50%");
+    expect(style.getPropertyValue("--scroll-reveal-image-focal-x")).toBe("");
   });
 
-  it("reflects frameHeight prop in --_frame-height", async () => {
+  it("reflects frameHeight prop in --scroll-reveal-frame-height", async () => {
     const wrapper = await mountSuspended(ScrollRevealImage, {
       props: { src: "/images/test.jpg", frameHeight: "80vh" },
     });
     const style = (wrapper.element as HTMLElement).style;
-    expect(style.getPropertyValue("--_frame-height")).toBe("80vh");
+    expect(style.getPropertyValue("--scroll-reveal-frame-height")).toBe("80vh");
   });
 
-  it("reflects parallaxOffset prop in --_parallax-offset", async () => {
+  it("reflects parallaxOffset prop in --scroll-reveal-frame-parallax-offset", async () => {
     const wrapper = await mountSuspended(ScrollRevealImage, {
       props: { src: "/images/test.jpg", parallaxOffset: "48rem" },
     });
     const style = (wrapper.element as HTMLElement).style;
-    expect(style.getPropertyValue("--_parallax-offset")).toBe("48rem");
+    expect(style.getPropertyValue("--scroll-reveal-frame-parallax-offset")).toBe("48rem");
   });
 
-  it("reflects radius prop in --_radius", async () => {
+  it("reflects radius prop in --scroll-reveal-frame-radius", async () => {
     const wrapper = await mountSuspended(ScrollRevealImage, {
       props: { src: "/images/test.jpg", radius: "2.4rem" },
     });
     const style = (wrapper.element as HTMLElement).style;
-    expect(style.getPropertyValue("--_radius")).toBe("2.4rem");
+    expect(style.getPropertyValue("--scroll-reveal-frame-radius")).toBe("2.4rem");
   });
 
-  it("reflects focalX prop in --_focal-x", async () => {
+  it("writes no inline style at all when no sizing or focal props are passed", async () => {
+    const wrapper = await mountSuspended(ScrollRevealImage, {
+      props: { src: "/images/test.jpg" },
+    });
+    expect(wrapper.attributes("style")).toBeUndefined();
+  });
+
+  it("reflects focalX prop in --scroll-reveal-image-focal-x", async () => {
     const wrapper = await mountSuspended(ScrollRevealImage, {
       props: { src: "/images/test.jpg", focalX: "75%" },
     });
     const style = (wrapper.element as HTMLElement).style;
-    expect(style.getPropertyValue("--_focal-x")).toBe("75%");
+    expect(style.getPropertyValue("--scroll-reveal-image-focal-x")).toBe("75%");
   });
 
   // ─── Image element ───────────────────────────────────────────────────────
 
-  it("renders an img child element with the reveal-image class", async () => {
+  it("renders an img child element with the scroll-reveal-image class", async () => {
     const wrapper = await mountSuspended(ScrollRevealImage, {
       props: { src: "/images/test.jpg" },
     });
@@ -131,7 +138,7 @@ describe("ScrollRevealImage", () => {
     // identified by the data-nuxt-img attribute it injects.
     const img = wrapper.find("img[data-nuxt-img]");
     expect(img.exists()).toBe(true);
-    expect(img.classes()).toContain("reveal-image");
+    expect(img.classes()).toContain("scroll-reveal-image");
   });
 
   it("passes src through to the image element", async () => {

package/app/components/01.atoms/animations/scroll-reveal-image/tests/__snapshots__/ScrollRevealImage.spec.ts.snap

@@ -1,13 +1,13 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`ScrollRevealImage > renders correct HTML structure (all props set) 1`] = `
-"<figure class="reveal-frame custom-class" style="--_frame-height: 400px; --_parallax-offset: 20rem; --_radius: 1.6rem; --_focal-x: 30%;">
-  <div class="reveal-content"><img width="800" height="600" data-nuxt-img="" srcset="/_ipx/s_800x600/images/test.jpg 1x, /_ipx/s_1600x1200/images/test.jpg 2x" class="reveal-image" alt="All props" loading="eager" decoding="async" src="/_ipx/s_800x600/images/test.jpg"></div>
+"<figure class="scroll-reveal-frame custom-class" style="--scroll-reveal-frame-height: 400px; --scroll-reveal-frame-parallax-offset: 20rem; --scroll-reveal-frame-radius: 1.6rem; --scroll-reveal-image-focal-x: 30%;">
+  <div class="scroll-reveal-frame-content"><img width="800" height="600" data-nuxt-img="" srcset="/_ipx/s_800x600/images/test.jpg 1x, /_ipx/s_1600x1200/images/test.jpg 2x" class="scroll-reveal-image" alt="All props" loading="eager" decoding="async" src="/_ipx/s_800x600/images/test.jpg"></div>
 </figure>"
 `;
 
 exports[`ScrollRevealImage > renders correct HTML structure (default props) 1`] = `
-"<figure class="reveal-frame" style="--_frame-height: 540px; --_parallax-offset: 36rem; --_radius: 0px; --_focal-x: 50%;">
-  <div class="reveal-content"><img width="1920" height="1080" data-nuxt-img="" srcset="/_ipx/s_1920x1080/images/test.jpg 1x, /_ipx/s_3840x2160/images/test.jpg 2x" class="reveal-image" alt="Test image" loading="lazy" decoding="async" src="/_ipx/s_1920x1080/images/test.jpg"></div>
+"<figure class="scroll-reveal-frame">
+  <div class="scroll-reveal-frame-content"><img width="1920" height="1080" data-nuxt-img="" srcset="/_ipx/s_1920x1080/images/test.jpg 1x, /_ipx/s_3840x2160/images/test.jpg 2x" class="scroll-reveal-image" alt="Test image" loading="lazy" decoding="async" src="/_ipx/s_1920x1080/images/test.jpg"></div>
 </figure>"
 `;

package/app/components/01.atoms/animations/section-parallax/CONSUMER-STYLING.md

@@ -19,12 +19,33 @@
 </SectionParallax>
 ```
 
+---
+
 ## Motion
 
 The parallax effect (`background-attachment: fixed`) only activates on `(hover: hover) and
 (pointer: fine)` inputs that support it, and is disabled under `prefers-reduced-motion: reduce`
 (falls back to `background-attachment: scroll` and the base `--section-parallax-min-height`).
 
+---
+
+## No overlay/gradient built in
+
+The component has no built-in overlay or gradient scrim — add one via the default slot or a
+`::before` pseudo-element in your consuming-page styles.
+
+---
+
+## 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
 
 Use `styleClassPassthrough` to add classes to the root element — e.g. to override `min-height`
@@ -38,7 +59,3 @@ from a consuming page's own stylesheet instead of inline tokens:
 }
 ```
 
-## No overlay/gradient built in
-
-The component has no built-in overlay or gradient scrim — add one via the default slot or a
-`::before` pseudo-element in your consuming-page styles.