srcdev-nuxt-components 9.4.11 → 9.5.0

package/app/components/03.organisms/image-galleries/slider-gallery/stories/SliderGallery.stories.ts

@@ -18,6 +18,22 @@ const meta: Meta<typeof SliderGallery> = {
       control: { type: "number", min: 100, step: 100 },
       description: "Slide transition duration in milliseconds",
     },
+    ariaLabel: {
+      control: { type: "text" },
+      description: "aria-label on the carousel region",
+    },
+    seeMoreText: {
+      control: { type: "text" },
+      description: "Link text for slides that have an href",
+    },
+    prevAriaLabel: { control: { type: "text" }, description: "Previous button aria-label" },
+    nextAriaLabel: { control: { type: "text" }, description: "Next button aria-label" },
+    prevIcon: { control: { type: "text" }, description: "Previous button icon" },
+    nextIcon: { control: { type: "text" }, description: "Next button icon" },
+    textScrim: {
+      control: { type: "boolean" },
+      description: "Gradient behind the slide text, matched to each slide's textBrightness",
+    },
     styleClassPassthrough: {
       control: "object",
       description: "Additional CSS classes applied to the root element",
@@ -27,6 +43,13 @@ const meta: Meta<typeof SliderGallery> = {
     autoRun: true,
     autoRunInterval: 7000,
     animationDuration: 3000,
+    textScrim: true,
+    ariaLabel: "Image gallery",
+    seeMoreText: "SEE MORE",
+    prevAriaLabel: "Previous image",
+    nextAriaLabel: "Next image",
+    prevIcon: "ic:outline-keyboard-arrow-left",
+    nextIcon: "ic:outline-keyboard-arrow-right",
     styleClassPassthrough: [],
   },
   parameters: {
@@ -34,7 +57,7 @@ const meta: Meta<typeof SliderGallery> = {
     docs: {
       description: {
         component:
-          "A full-screen image slider gallery with animated slide transitions, thumbnail navigation, arrow controls, and keyboard support. Gallery data is passed via v-model:galleryData.",
+          "A full-screen image slider gallery with animated slide transitions, thumbnail navigation, arrow controls, and keyboard support. Gallery data is passed via v-model:galleryData. Auto-advance pauses on hover/focus and is off under reduced motion; slides with an href get a see-more link.",
       },
     },
   },
@@ -55,6 +78,7 @@ const sampleSlides: IGalleryData[] = [
     description: "Vast mountain ranges stretching to the horizon at the golden hour of sunrise.",
     thumbnail: { title: "Into the Wild", description: "Landscape" },
     textBrightness: "light",
+    href: "#into-the-wild",
   },
   {
     src: "https://picsum.photos/seed/gallery2/1920/1080",
@@ -65,6 +89,7 @@ const sampleSlides: IGalleryData[] = [
     description: "Modern skyscrapers reflecting the warm hues of the setting sun.",
     thumbnail: { title: "City Lights", description: "Architecture" },
     textBrightness: "light",
+    href: "#city-lights",
   },
   {
     src: "https://picsum.photos/seed/gallery3/1920/1080",

package/app/components/03.organisms/image-galleries/slider-gallery/tests/SliderGallery.spec.ts

@@ -94,25 +94,55 @@ describe("SliderGallery", () => {
     expect(wrapper.classes()).toContain("slider-gallery");
   });
 
+  // ─── Text scrim ───────────────────────────────────────────────────────────
+
+  it("adds has-text-scrim to the root by default", async () => {
+    const wrapper = await mountSuspended(SliderGallery);
+    expect(wrapper.classes()).toContain("has-text-scrim");
+  });
+
+  it("omits has-text-scrim when textScrim is false", async () => {
+    const wrapper = await mountSuspended(SliderGallery, { props: { galleryData: mockGalleryData, textScrim: false } });
+    expect(wrapper.classes()).not.toContain("has-text-scrim");
+  });
+
+  it("toggles has-text-scrim when textScrim changes after mount", async () => {
+    const wrapper = await mountSuspended(SliderGallery);
+    await wrapper.setProps({ textScrim: false });
+    expect(wrapper.classes()).not.toContain("has-text-scrim");
+  });
+
+  it("marks each main slide with its textBrightness", async () => {
+    const wrapper = await mountAndLoad(mockGalleryData, mockImage);
+    const slides = wrapper.findAll(".slider-gallery-list .slider-gallery-item");
+    expect(slides.map((slide) => slide.attributes("data-text-brightness"))).toEqual(["light", "dark", "light"]);
+  });
+
+  it("marks only slides with overlay text as data-has-text", async () => {
+    const wrapper = await mountAndLoad(mockGalleryData, mockImage);
+    const slides = wrapper.findAll(".slider-gallery-list .slider-gallery-item");
+    expect(slides.map((slide) => slide.attributes("data-has-text") !== undefined)).toEqual([true, true, false]);
+  });
+
   // ─── Loading state ────────────────────────────────────────────────────────
 
   it("shows loading state before images load", async () => {
     const wrapper = await mountSuspended(SliderGallery, {
       props: { galleryData: mockGalleryData },
     });
-    expect(wrapper.find(".loading-state").exists()).toBe(true);
+    expect(wrapper.find(".slider-gallery-loading").exists()).toBe(true);
   });
 
   it("hides gallery content before images load", async () => {
     const wrapper = await mountSuspended(SliderGallery, {
       props: { galleryData: mockGalleryData },
     });
-    expect(wrapper.find(".gallery-content").exists()).toBe(false);
+    expect(wrapper.find(".slider-gallery-content").exists()).toBe(false);
   });
 
   it("shows gallery content after image loads", async () => {
     const wrapper = await mountAndLoad(mockGalleryData, mockImage);
-    expect(wrapper.find(".gallery-content").exists()).toBe(true);
+    expect(wrapper.find(".slider-gallery-content").exists()).toBe(true);
   });
 
   it("dismisses loading state when galleryData is empty", async () => {
@@ -120,8 +150,8 @@ describe("SliderGallery", () => {
       props: { galleryData: [] },
     });
     await nextTick();
-    // galleryLoaded becomes false → loading-state gains the galleryLoaded class
-    expect(wrapper.find(".loading-state.galleryLoaded").exists()).toBe(true);
+    // loading finishes → the loading block gains is-loaded
+    expect(wrapper.find(".slider-gallery-loading.is-loaded").exists()).toBe(true);
   });
 
   it("resolves loading when first image errors", async () => {
@@ -133,31 +163,31 @@ describe("SliderGallery", () => {
     await nextTick(); // extra tick — onerror → resolve → Promise.race → onMounted resume
     vi.advanceTimersByTime(500);
     await nextTick();
-    expect(wrapper.find(".gallery-content").exists()).toBe(true);
+    expect(wrapper.find(".slider-gallery-content").exists()).toBe(true);
   });
 
   // ─── Gallery items ────────────────────────────────────────────────────────
 
   it("renders correct number of slide items", async () => {
     const wrapper = await mountAndLoad(mockGalleryData, mockImage);
-    expect(wrapper.findAll(".list .item")).toHaveLength(mockGalleryData.length);
+    expect(wrapper.findAll(".slider-gallery-list .slider-gallery-item")).toHaveLength(mockGalleryData.length);
   });
 
   it("renders correct number of thumbnail items", async () => {
     const wrapper = await mountAndLoad(mockGalleryData, mockImage);
-    expect(wrapper.findAll(".thumbnail .item")).toHaveLength(mockGalleryData.length);
+    expect(wrapper.findAll(".slider-gallery-thumbnails .slider-gallery-item")).toHaveLength(mockGalleryData.length);
   });
 
   it("renders slide image alt text correctly", async () => {
     const wrapper = await mountAndLoad(mockGalleryData, mockImage);
-    const images = wrapper.findAll(".list .item img");
+    const images = wrapper.findAll(".slider-gallery-list .slider-gallery-item img");
     expect(images[0]?.attributes("alt")).toBe(mockGalleryData[0]?.alt);
     expect(images[1]?.attributes("alt")).toBe(mockGalleryData[1]?.alt);
   });
 
   it("renders thumbnail images with lazy loading", async () => {
     const wrapper = await mountAndLoad(mockGalleryData, mockImage);
-    const thumbImages = wrapper.findAll(".thumbnail .item img");
+    const thumbImages = wrapper.findAll(".slider-gallery-thumbnails .slider-gallery-item img");
     thumbImages.forEach((img) => {
       expect(img.attributes("loading")).toBe("lazy");
     });
@@ -165,48 +195,48 @@ describe("SliderGallery", () => {
 
   it("renders slide content fields when provided", async () => {
     const wrapper = await mountAndLoad([mockGalleryData[0]!], mockImage);
-    expect(wrapper.find(".list .item .author").text()).toBe(mockGalleryData[0]!.stylist);
-    expect(wrapper.find(".list .item .title").text()).toBe(mockGalleryData[0]!.title);
-    expect(wrapper.find(".list .item .topic").text()).toBe(mockGalleryData[0]!.category);
-    expect(wrapper.find(".list .item .description").text()).toBe(mockGalleryData[0]!.description);
+    expect(wrapper.find(".slider-gallery-list .slider-gallery-item .slider-gallery-author").text()).toBe(mockGalleryData[0]!.stylist);
+    expect(wrapper.find(".slider-gallery-list .slider-gallery-item .slider-gallery-title").text()).toBe(mockGalleryData[0]!.title);
+    expect(wrapper.find(".slider-gallery-list .slider-gallery-item .slider-gallery-topic").text()).toBe(mockGalleryData[0]!.category);
+    expect(wrapper.find(".slider-gallery-list .slider-gallery-item .slider-gallery-description").text()).toBe(mockGalleryData[0]!.description);
   });
 
   it("renders thumbnail content when provided", async () => {
     const wrapper = await mountAndLoad([mockGalleryData[0]!], mockImage);
-    expect(wrapper.find(".thumbnail .item .title").text()).toBe(mockGalleryData[0]!.thumbnail?.title);
-    expect(wrapper.find(".thumbnail .item .description").text()).toBe(mockGalleryData[0]!.thumbnail?.description);
+    expect(wrapper.find(".slider-gallery-thumbnails .slider-gallery-item .slider-gallery-title").text()).toBe(mockGalleryData[0]!.thumbnail?.title);
+    expect(wrapper.find(".slider-gallery-thumbnails .slider-gallery-item .slider-gallery-description").text()).toBe(mockGalleryData[0]!.thumbnail?.description);
   });
 
   // ─── Navigation buttons ───────────────────────────────────────────────────
 
   it("renders prev and next arrow buttons", async () => {
     const wrapper = await mountAndLoad(mockGalleryData, mockImage);
-    expect(wrapper.find("#prev").exists()).toBe(true);
-    expect(wrapper.find("#next").exists()).toBe(true);
+    expect(wrapper.find(".slider-gallery-prev").exists()).toBe(true);
+    expect(wrapper.find(".slider-gallery-next").exists()).toBe(true);
   });
 
   it("prev button has accessible aria-label", async () => {
     const wrapper = await mountAndLoad(mockGalleryData, mockImage);
-    expect(wrapper.find("#prev").attributes("aria-label")).toBe("Previous image");
+    expect(wrapper.find(".slider-gallery-prev").attributes("aria-label")).toBe("Previous image");
   });
 
   it("next button has accessible aria-label", async () => {
     const wrapper = await mountAndLoad(mockGalleryData, mockImage);
-    expect(wrapper.find("#next").attributes("aria-label")).toBe("Next image");
+    expect(wrapper.find(".slider-gallery-next").attributes("aria-label")).toBe("Next image");
   });
 
   // ─── styleClassPassthrough ────────────────────────────────────────────────
 
   it("applies a single styleClassPassthrough string", async () => {
     const wrapper = await mountSuspended(SliderGallery, {
-      props: { styleClassPassthrough: "custom-gallery" },
+      props: { galleryData: [], styleClassPassthrough: "custom-gallery" },
     });
     expect(wrapper.classes()).toContain("custom-gallery");
   });
 
   it("applies multiple styleClassPassthrough classes from an array", async () => {
     const wrapper = await mountSuspended(SliderGallery, {
-      props: { styleClassPassthrough: ["class-a", "class-b"] },
+      props: { galleryData: [], styleClassPassthrough: ["class-a", "class-b"] },
     });
     expect(wrapper.classes()).toContain("class-a");
     expect(wrapper.classes()).toContain("class-b");
@@ -214,7 +244,7 @@ describe("SliderGallery", () => {
 
   it("updates classes when styleClassPassthrough prop changes", async () => {
     const wrapper = await mountSuspended(SliderGallery, {
-      props: { styleClassPassthrough: ["original"] },
+      props: { galleryData: [], styleClassPassthrough: ["original"] },
     });
     expect(wrapper.classes()).toContain("original");
     await wrapper.setProps({ styleClassPassthrough: ["updated"] });
@@ -231,4 +261,53 @@ describe("SliderGallery", () => {
     wrapper.unmount();
     expect(spy).toHaveBeenCalledWith("keydown", expect.any(Function));
   });
+
+  // ─── Carousel semantics and a11y ──────────────────────────────────────────
+
+  it("is a labelled carousel region", async () => {
+    const wrapper = await mountSuspended(SliderGallery, { props: { galleryData: [], ariaLabel: "Our work" } });
+    expect(wrapper.attributes("role")).toBe("region");
+    expect(wrapper.attributes("aria-roledescription")).toBe("carousel");
+    expect(wrapper.attributes("aria-label")).toBe("Our work");
+  });
+
+  it("does not use fixed ids on the arrow buttons", async () => {
+    const wrapper = await mountAndLoad(mockGalleryData, mockImage);
+    expect(wrapper.find(".slider-gallery-prev").attributes("id")).toBeUndefined();
+    expect(wrapper.find(".slider-gallery-next").attributes("id")).toBeUndefined();
+  });
+
+  it("hides the decorative thumbnail strip from assistive tech", async () => {
+    const wrapper = await mountAndLoad(mockGalleryData, mockImage);
+    expect(wrapper.find(".slider-gallery-thumbnails").attributes("aria-hidden")).toBe("true");
+  });
+
+  it("renders the see-more link only for slides with an href", async () => {
+    const data: IGalleryData[] = [{ ...mockGalleryData[0]!, href: "/work/1" }, mockGalleryData[1]!];
+    const wrapper = await mountAndLoad(data, mockImage);
+    const ctas = wrapper.findAll(".slider-gallery-cta");
+    expect(ctas).toHaveLength(1);
+    expect(ctas[0]!.attributes("href")).toBe("/work/1");
+    expect(ctas[0]!.text()).toBe("SEE MORE");
+  });
+
+  it("pauses auto-advance while hovered and resumes on leave", async () => {
+    const wrapper = await mountAndLoad(mockGalleryData, mockImage);
+    await wrapper.trigger("mouseenter");
+    vi.advanceTimersByTime(7000);
+    await nextTick();
+    expect(wrapper.classes()).not.toContain("is-next");
+    await wrapper.trigger("mouseleave");
+    vi.advanceTimersByTime(7000);
+    await nextTick();
+    expect(wrapper.classes()).toContain("is-next");
+  });
+
+  it("does not auto-advance under prefers-reduced-motion", async () => {
+    vi.stubGlobal("matchMedia", vi.fn(() => ({ matches: true })));
+    const wrapper = await mountAndLoad(mockGalleryData, mockImage);
+    vi.advanceTimersByTime(7000);
+    await nextTick();
+    expect(wrapper.classes()).not.toContain("is-next");
+  });
 });

package/app/components/03.organisms/image-galleries/slider-gallery/tests/__snapshots__/SliderGallery.spec.ts.snap

@@ -1,69 +1,69 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`SliderGallery > renders correct HTML structure after load 1`] = `
-"<div class="slider-gallery">
-  <div class="loading-state">
-    <div class="loading-spinner"></div>
+"<div class="slider-gallery has-text-scrim" role="region" aria-roledescription="carousel" aria-label="Image gallery">
+  <div class="slider-gallery-loading" role="status">
+    <div class="slider-gallery-spinner" aria-hidden="true"></div>
     <p>Loading gallery...</p>
   </div>
-  <div class="gallery-content">
-    <div class="list">
-      <div class="item"><img data-nuxt-img="" srcset="/_ipx/_/images/slide-1.jpg 1x, /_ipx/_/images/slide-1.jpg 2x" alt="Slide 1" src="/_ipx/_/images/slide-1.jpg">
-        <div class="content light">
-          <div class="author light">Stylist One</div>
-          <div class="title light">First Slide</div>
-          <div class="topic light">Fashion</div>
-          <div class="description light">Description for first slide</div>
-          <div class="buttons light"><button>SEE MORE</button></div>
+  <div class="slider-gallery-content">
+    <div class="slider-gallery-list">
+      <div class="slider-gallery-item" data-text-brightness="light" data-has-text=""><img data-nuxt-img="" srcset="/_ipx/_/images/slide-1.jpg 1x, /_ipx/_/images/slide-1.jpg 2x" alt="Slide 1" src="/_ipx/_/images/slide-1.jpg">
+        <div class="slider-gallery-item-content light">
+          <div class="slider-gallery-author">Stylist One</div>
+          <div class="slider-gallery-title">First Slide</div>
+          <div class="slider-gallery-topic">Fashion</div>
+          <div class="slider-gallery-description">Description for first slide</div>
+          <!--v-if-->
         </div>
       </div>
-      <div class="item"><img data-nuxt-img="" srcset="/_ipx/_/images/slide-2.jpg 1x, /_ipx/_/images/slide-2.jpg 2x" alt="Slide 2" src="/_ipx/_/images/slide-2.jpg">
-        <div class="content dark">
-          <div class="author dark"></div>
-          <div class="title dark">Second Slide</div>
-          <div class="topic dark">Style</div>
-          <div class="description dark"></div>
-          <div class="buttons dark"><button>SEE MORE</button></div>
+      <div class="slider-gallery-item" data-text-brightness="dark" data-has-text=""><img data-nuxt-img="" srcset="/_ipx/_/images/slide-2.jpg 1x, /_ipx/_/images/slide-2.jpg 2x" alt="Slide 2" src="/_ipx/_/images/slide-2.jpg">
+        <div class="slider-gallery-item-content dark">
+          <!--v-if-->
+          <div class="slider-gallery-title">Second Slide</div>
+          <div class="slider-gallery-topic">Style</div>
+          <!--v-if-->
+          <!--v-if-->
         </div>
       </div>
-      <div class="item"><img data-nuxt-img="" srcset="/_ipx/_/images/slide-3.jpg 1x, /_ipx/_/images/slide-3.jpg 2x" alt="Slide 3" src="/_ipx/_/images/slide-3.jpg">
-        <div class="content light">
-          <div class="author light"></div>
-          <div class="title light"></div>
-          <div class="topic light"></div>
-          <div class="description light"></div>
-          <div class="buttons light"><button>SEE MORE</button></div>
+      <div class="slider-gallery-item" data-text-brightness="light"><img data-nuxt-img="" srcset="/_ipx/_/images/slide-3.jpg 1x, /_ipx/_/images/slide-3.jpg 2x" alt="Slide 3" src="/_ipx/_/images/slide-3.jpg">
+        <div class="slider-gallery-item-content light">
+          <!--v-if-->
+          <!--v-if-->
+          <!--v-if-->
+          <!--v-if-->
+          <!--v-if-->
         </div>
       </div>
     </div>
-    <div class="thumbnail">
-      <div class="item">
-        <div class="inner"><img data-nuxt-img="" srcset="/_ipx/_/images/slide-1.jpg 1x, /_ipx/_/images/slide-1.jpg 2x" alt="Slide 1" loading="lazy" src="/_ipx/_/images/slide-1.jpg">
-          <div class="content light">
-            <div class="title light">Thumb 1</div>
-            <div class="description light">Thumb desc 1</div>
+    <div class="slider-gallery-thumbnails" aria-hidden="true">
+      <div class="slider-gallery-item">
+        <div class="slider-gallery-thumbnail-overlay"><img data-nuxt-img="" srcset="/_ipx/_/images/slide-1.jpg 1x, /_ipx/_/images/slide-1.jpg 2x" alt="" loading="lazy" src="/_ipx/_/images/slide-1.jpg">
+          <div class="slider-gallery-item-content light">
+            <div class="slider-gallery-title">Thumb 1</div>
+            <div class="slider-gallery-description">Thumb desc 1</div>
           </div>
         </div>
       </div>
-      <div class="item">
-        <div class="inner"><img data-nuxt-img="" srcset="/_ipx/_/images/slide-2.jpg 1x, /_ipx/_/images/slide-2.jpg 2x" alt="Slide 2" loading="lazy" src="/_ipx/_/images/slide-2.jpg">
-          <div class="content dark">
-            <div class="title dark">Thumb 2</div>
-            <div class="description dark">Thumb desc 2</div>
+      <div class="slider-gallery-item">
+        <div class="slider-gallery-thumbnail-overlay"><img data-nuxt-img="" srcset="/_ipx/_/images/slide-2.jpg 1x, /_ipx/_/images/slide-2.jpg 2x" alt="" loading="lazy" src="/_ipx/_/images/slide-2.jpg">
+          <div class="slider-gallery-item-content dark">
+            <div class="slider-gallery-title">Thumb 2</div>
+            <div class="slider-gallery-description">Thumb desc 2</div>
           </div>
         </div>
       </div>
-      <div class="item">
-        <div class="inner"><img data-nuxt-img="" srcset="/_ipx/_/images/slide-3.jpg 1x, /_ipx/_/images/slide-3.jpg 2x" alt="Slide 3" loading="lazy" src="/_ipx/_/images/slide-3.jpg">
-          <div class="content light">
-            <div class="title light"></div>
-            <div class="description light"></div>
+      <div class="slider-gallery-item">
+        <div class="slider-gallery-thumbnail-overlay"><img data-nuxt-img="" srcset="/_ipx/_/images/slide-3.jpg 1x, /_ipx/_/images/slide-3.jpg 2x" alt="" loading="lazy" src="/_ipx/_/images/slide-3.jpg">
+          <div class="slider-gallery-item-content light">
+            <!--v-if-->
+            <!--v-if-->
           </div>
         </div>
       </div>
     </div>
-    <div class="arrows"><button id="prev" aria-label="Previous image"><span class="iconify i-ic:outline-keyboard-arrow-left arrows-icon" aria-hidden="true"></span></button><button id="next" aria-label="Next image"><span class="iconify i-ic:outline-keyboard-arrow-right arrows-icon" aria-hidden="true"></span></button></div>
-    <div class="time"></div>
+    <div class="slider-gallery-arrows"><button type="button" class="slider-gallery-prev" aria-label="Previous image"><span class="iconify i-ic:outline-keyboard-arrow-left slider-gallery-arrow-icon" aria-hidden="true"></span></button><button type="button" class="slider-gallery-next" aria-label="Next image"><span class="iconify i-ic:outline-keyboard-arrow-right slider-gallery-arrow-icon" aria-hidden="true"></span></button></div>
+    <div class="slider-gallery-progress" aria-hidden="true"></div>
   </div>
 </div>"
 `;

package/app/components/03.organisms/responsive-header/CONSUMER-STYLING.md

@@ -28,7 +28,7 @@ are documented alongside it since that's where they're consumed.
 
 ---
 
-## Global theming — recommended approach
+## Global theming
 
 Create `assets/styles/setup/07.components/responsive-header.css` in the consuming app and set
 tokens on a scope class matching the one passed via `styleClassPassthrough`:
@@ -54,6 +54,16 @@ tokens on a scope class matching the one passed 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`.
+
+---
+
 ## Notes
 
 - Anything with async-loaded content (an `iconName` icon on a nav item, a new decorator inside
@@ -64,3 +74,4 @@ tokens on a scope class matching the one passed via `styleClassPassthrough`:
 - `NavigationItems`' own tokens (`--overflow-nav-*`) are documented in its own skill doc since
   they style the overflow-panel's *content*, distinct from `ResponsiveHeader`'s own tokens
   above which style the top bar and the overflow *button*/*container*.
+

package/app/components/03.organisms/responsive-header/ResponsiveHeader.vue

@@ -717,7 +717,6 @@ watch(
        Set this token to a fixed value (or a small set of breakpoint-based values)
        to avoid it. */
 
-    --_link-visibility-transition: none;
     position: relative;
     color: var(--responsive-header-color, inherit);
 
@@ -731,7 +730,6 @@ watch(
     inline-size: var(--responsive-header-inline-size, 100%);
 
     &.loaded {
-      --_link-visibility-transition: all 0.2s ease-in-out;
     }
 
     /* flex-grow: 1; */
@@ -746,7 +744,6 @@ watch(
       --_link-margin-inline: 0.1rem;
       --_link-focus-visible-outline-width: 0.2rem;
       --_link-border-default: 2px solid transparent;
-      --_link-border-bottom-hover: var(--green-08);
 
       grid-area: navStack;
       display: flex;
@@ -816,7 +813,6 @@ watch(
             --_icon-transform: scaleY(1);
 
             margin-inline-start: 0;
-            /* transition: var(--_link-visibility-transition); */
 
             &[open] {
               --_icon-transform: scaleY(-1);

package/app/components/03.organisms/services/service-detail/CONSUMER-STYLING.md

@@ -1,3 +1,7 @@
+
+> **Changed 2026-09-27**: `--service-detail-hero-pill-bg` (and the hero text colour on the pills)
+> never applied before, because `DisplayPill`'s `neutral` variant ignored the base tokens. It now
+> falls back to them, so the hero pills are transparent with the hero text colour as documented.
 # ServiceDetail — Consumer Styling Guide
 
 ## Layout building blocks
@@ -30,6 +34,8 @@ inside an outer, wider `PageRow` — see
 notes in [page-row.md](../../../../../.claude/skills/components/page-row.md) for how nested page-rows
 compose.
 
+---
+
 ## Public token API
 
 ### Hero banner
@@ -46,7 +52,7 @@ compose.
 | `--service-detail-hero-text-colour` | `white` | Colour of the breadcrumb, eyebrow, and title over the hero image |
 | `--service-detail-breadcrumb-margin-block-end` | `0.8rem` | Space below the breadcrumb |
 | `--service-detail-hero-pills-gap` | `0.8rem` | Gap between the duration and price pills |
-| `--service-detail-hero-pill-bg` | `transparent` | Background of the price/duration pills (via `DisplayPill`'s `--theme-pill-bg`) |
+| `--service-detail-hero-pill-bg` | `transparent` | Background of the price/duration pills (via `DisplayPill`'s `--display-pill-background`) |
 | `--service-detail-hero-pill-border-colour` | `currentColor` | Border colour of the price/duration pills |
 
 The hero image is always `object-fit: cover` (not tokened) — only its anchor point changes
@@ -182,7 +188,7 @@ Section headings, sidebar labels, and CTA copy are **props**, not hardcoded stri
 
 ---
 
-## Global theming — recommended approach
+## Global theming
 
 ```css
 /* assets/styles/setup/07.components/service-detail.css */
@@ -193,7 +199,21 @@ Section headings, sidebar labels, and CTA copy are **props**, not hardcoded stri
 }
 ```
 
-## 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`.
+
+**Caveat:** `ServiceDetail` re-declares `--display-pill-background`, `--display-pill-text-colour`,
+`--display-pill-border-colour` and `--breadcrumb-colour` inside its hero, so ancestor values of those
+never reach the hero pills or breadcrumb. Use the `--service-detail-hero-*` tokens instead.
+
+### Page or section
 
 ```css
 .our-services-page {
@@ -231,3 +251,4 @@ Section headings, sidebar labels, and CTA copy are **props**, not hardcoded stri
   `@container` queries against the component's own width, not the viewport — they are not tokens
   since resizing them would need corresponding `minmax()`/`grid-template-columns` changes too, not
   just spacing (same rationale as `ServiceSummary`'s `--service-summary-grid-gap-desktop`).
+

package/app/components/03.organisms/services/service-detail/ServiceDetail.vue

@@ -326,9 +326,9 @@ watch(
             flex-wrap: wrap;
             gap: var(--service-detail-hero-pills-gap, 0.8rem);
 
-            --theme-pill-bg: var(--service-detail-hero-pill-bg, transparent);
-            --theme-pill-color: var(--service-detail-hero-text-colour, white);
-            --theme-pill-border-color: var(--service-detail-hero-pill-border-colour, currentColor);
+            --display-pill-background: var(--service-detail-hero-pill-bg, transparent);
+            --display-pill-text-colour: var(--service-detail-hero-text-colour, white);
+            --display-pill-border-colour: var(--service-detail-hero-pill-border-colour, currentColor);
           }
         }
       }