srcdev-nuxt-components 9.6.19 → 9.6.20

package/app/components/03.organisms/image-galleries/carousel-flip/tests/CarouselFlip.spec.ts

@@ -77,13 +77,6 @@ vi.mock("@vueuse/core", () => ({
   }),
 }));
 
-// Mock Icon component
-vi.mock("#imports", () => ({
-  useStyleClassPassthrough: vi.fn((classes) => ({
-    elementClasses: Array.isArray(classes) ? classes.join(" ") : classes || "",
-  })),
-}));
-
 describe("CarouselFlip", () => {
   let wrapper: ReturnType<typeof mountSuspended>;
   let component: CarouselFlipInstance;
@@ -137,7 +130,7 @@ describe("CarouselFlip", () => {
     it("renders with required accessibility attributes", async () => {
       await createWrapper();
 
-      const carousel = wrapper.find('[role="region"]');
+      const carousel = wrapper.find('section.carousel-flip');
       expect(carousel.exists()).toBe(true);
       expect(carousel.attributes("aria-label")).toBe("Image carousel");
 
@@ -157,7 +150,7 @@ describe("CarouselFlip", () => {
     it("renders all carousel items with correct slots", async () => {
       await createWrapper();
 
-      const items = wrapper.findAll(".item");
+      const items = wrapper.findAll(".carousel-flip-item");
       expect(items).toHaveLength(6);
 
       for (let i = 0; i < 6; i++) {
@@ -170,7 +163,7 @@ describe("CarouselFlip", () => {
     it("renders marker buttons for each item", async () => {
       await createWrapper();
 
-      const markers = wrapper.findAll(".btn-marker");
+      const markers = wrapper.findAll(".carousel-flip-marker");
       expect(markers).toHaveLength(6);
 
       markers.forEach((marker: ReturnType<typeof wrapper.find>, index: number) => {
@@ -182,8 +175,8 @@ describe("CarouselFlip", () => {
     it("renders navigation buttons with correct icons and labels", async () => {
       await createWrapper();
 
-      const prevButton = wrapper.find('[aria-label="Go to previous item"]');
-      const nextButton = wrapper.find('[aria-label="Go to next item"]');
+      const prevButton = wrapper.find('.carousel-flip-button-prev');
+      const nextButton = wrapper.find('.carousel-flip-button-next');
 
       expect(prevButton.exists()).toBe(true);
       expect(nextButton.exists()).toBe(true);
@@ -201,7 +194,7 @@ describe("CarouselFlip", () => {
         carouselDataIds: customData,
       });
 
-      const items = wrapper.findAll(".item");
+      const items = wrapper.findAll(".carousel-flip-item");
       expect(items).toHaveLength(3);
       expect(component.itemCount).toBe(3);
     });
@@ -223,11 +216,11 @@ describe("CarouselFlip", () => {
       // The transition speed is used in computed property transitionSpeedStr
     });
 
-    it("applies allowCarouselOverflow class conditionally", async () => {
+    it("sets data-allow-overflow on the track when allowCarouselOverflow is on", async () => {
       await createWrapper({ allowCarouselOverflow: true });
 
-      const container = wrapper.find(".item-container");
-      expect(container.classes()).toContain("allow-overflow");
+      const container = wrapper.find(".carousel-flip-track");
+      expect(container.attributes("data-allow-overflow")).toBe("");
     });
 
     it("handles useFlipAnimation prop in calculations", async () => {
@@ -248,29 +241,29 @@ describe("CarouselFlip", () => {
     it("shows controls container by default", async () => {
       await createWrapper();
 
-      expect(wrapper.find(".controls-container").exists()).toBe(true);
-      expect(wrapper.findAll(".btn-marker").length).toBe(6);
+      expect(wrapper.find(".carousel-flip-controls").exists()).toBe(true);
+      expect(wrapper.findAll(".carousel-flip-marker").length).toBe(6);
     });
 
     it("hides controls container when showControls is false", async () => {
       await createWrapper({ showControls: false });
 
-      expect(wrapper.find(".controls-container").exists()).toBe(false);
-      expect(wrapper.findAll(".btn-marker").length).toBe(0);
+      expect(wrapper.find(".carousel-flip-controls").exists()).toBe(false);
+      expect(wrapper.findAll(".carousel-flip-marker").length).toBe(0);
     });
 
     it("still renders navigation buttons when showControls is false", async () => {
       await createWrapper({ showControls: false });
 
-      expect(wrapper.find('[aria-label="Go to previous item"]').exists()).toBe(true);
-      expect(wrapper.find('[aria-label="Go to next item"]').exists()).toBe(true);
+      expect(wrapper.find('.carousel-flip-button-prev').exists()).toBe(true);
+      expect(wrapper.find('.carousel-flip-button-next').exists()).toBe(true);
     });
 
     it("navigation still works when showControls is false", async () => {
       await createWrapper({ showControls: false });
       await nextTick();
 
-      const nextButton = wrapper.find('[aria-label="Go to next item"]');
+      const nextButton = wrapper.find('.carousel-flip-button-next');
       await nextButton.trigger("click");
       await nextTick();
 
@@ -292,10 +285,10 @@ describe("CarouselFlip", () => {
         jumpToItemLabel: "View look",
       });
 
-      expect(wrapper.find('[role="region"]').attributes("aria-label")).toBe("Featured looks");
+      expect(wrapper.find('section.carousel-flip').attributes("aria-label")).toBe("Featured looks");
       expect(wrapper.find('[role="group"]').attributes("aria-label")).toBe("Look slides");
-      expect(wrapper.find('[aria-label="Previous look"]').exists()).toBe(true);
-      expect(wrapper.find('[aria-label="Next look"]').exists()).toBe(true);
+      expect(wrapper.find('.carousel-flip-button-prev').exists()).toBe(true);
+      expect(wrapper.find('.carousel-flip-button-next').exists()).toBe(true);
       expect(wrapper.find('[aria-label="View look 1"]').exists()).toBe(true);
     });
 
@@ -310,8 +303,8 @@ describe("CarouselFlip", () => {
     it("overrides prev/next icons via props", async () => {
       await createWrapper({ prevIcon: "mdi:chevron-left", nextIcon: "mdi:chevron-right" });
 
-      const prevButton = wrapper.find('[aria-label="Go to previous item"]');
-      const nextButton = wrapper.find('[aria-label="Go to next item"]');
+      const prevButton = wrapper.find('.carousel-flip-button-prev');
+      const nextButton = wrapper.find('.carousel-flip-button-next');
 
       expect(prevButton.html()).toContain("i-mdi:chevron-left");
       expect(nextButton.html()).toContain("i-mdi:chevron-right");
@@ -345,7 +338,7 @@ describe("CarouselFlip", () => {
       await createWrapper();
       await nextTick();
 
-      const nextButton = wrapper.find('[aria-label="Go to next item"]');
+      const nextButton = wrapper.find('.carousel-flip-button-next');
       await nextButton.trigger("click");
       await nextTick();
 
@@ -361,15 +354,16 @@ describe("CarouselFlip", () => {
       expect(component.currentActiveIndex).toBe(0);
       expect(component.displayActiveIndex).toBe(0);
 
-      const firstMarker = wrapper.find(".btn-marker");
-      expect(firstMarker.classes()).toContain("active");
+      const firstMarker = wrapper.find(".carousel-flip-marker");
+      expect(firstMarker.attributes("data-active")).toBe("");
+      expect(firstMarker.attributes("aria-current")).toBe("true");
     });
 
     it("sets up item order and z-index correctly", async () => {
       await createWrapper();
       await nextTick();
 
-      const items = wrapper.findAll(".item");
+      const items = wrapper.findAll(".carousel-flip-item");
       // After initialization, items are reordered by the component
       // Just verify that all items have order and z-index set
       items.forEach((item: ReturnType<typeof wrapper.find>) => {
@@ -378,12 +372,12 @@ describe("CarouselFlip", () => {
       });
     });
 
-    it("adds mounted class after initialization", async () => {
+    it("sets data-mounted after initialization", async () => {
       await createWrapper();
       await nextTick();
       await nextTick(); // Wait for nextTick in component
 
-      expect(wrapper.classes()).toContain("mounted");
+      expect(wrapper.attributes("data-mounted")).toBe("");
     });
 
     it("marks carousel as initialized", async () => {
@@ -401,7 +395,7 @@ describe("CarouselFlip", () => {
     });
 
     it("navigates to next item when next button is clicked", async () => {
-      const nextButton = wrapper.find('[aria-label="Go to next item"]');
+      const nextButton = wrapper.find('.carousel-flip-button-next');
       await nextButton.trigger("click");
       await nextTick();
 
@@ -410,7 +404,7 @@ describe("CarouselFlip", () => {
     });
 
     it("navigates to previous item when previous button is clicked", async () => {
-      const prevButton = wrapper.find('[aria-label="Go to previous item"]');
+      const prevButton = wrapper.find('.carousel-flip-button-prev');
       await prevButton.trigger("click");
       await nextTick();
 
@@ -423,7 +417,7 @@ describe("CarouselFlip", () => {
       component.currentActiveIndex = 5;
       await nextTick();
 
-      const nextButton = wrapper.find('[aria-label="Go to next item"]');
+      const nextButton = wrapper.find('.carousel-flip-button-next');
       await nextButton.trigger("click");
       await nextTick();
 
@@ -431,7 +425,7 @@ describe("CarouselFlip", () => {
     });
 
     it("wraps around when navigating before first item", async () => {
-      const prevButton = wrapper.find('[aria-label="Go to previous item"]');
+      const prevButton = wrapper.find('.carousel-flip-button-prev');
       await prevButton.trigger("click");
       await nextTick();
 
@@ -439,7 +433,7 @@ describe("CarouselFlip", () => {
     });
 
     it("jumps to specific item when marker is clicked", async () => {
-      const thirdMarker = wrapper.findAll(".btn-marker")[2];
+      const thirdMarker = wrapper.findAll(".carousel-flip-marker")[2];
       await thirdMarker.trigger("click");
       await nextTick();
 
@@ -448,17 +442,18 @@ describe("CarouselFlip", () => {
     });
 
     it("updates active marker visually", async () => {
-      const thirdMarker = wrapper.findAll(".btn-marker")[2];
+      const thirdMarker = wrapper.findAll(".carousel-flip-marker")[2];
       await thirdMarker.trigger("click");
       await nextTick();
 
-      const markers = wrapper.findAll(".btn-marker");
-      expect(markers[0].classes()).not.toContain("active");
-      expect(markers[2].classes()).toContain("active");
+      const markers = wrapper.findAll(".carousel-flip-marker");
+      expect(markers[0].attributes("data-active")).toBeUndefined();
+      expect(markers[2].attributes("data-active")).toBe("");
+      expect(markers[2].attributes("aria-current")).toBe("true");
     });
 
     it("updates screen reader announcement when navigating", async () => {
-      const nextButton = wrapper.find('[aria-label="Go to next item"]');
+      const nextButton = wrapper.find('.carousel-flip-button-next');
       await nextButton.trigger("click");
       await nextTick();
 
@@ -467,12 +462,12 @@ describe("CarouselFlip", () => {
     });
 
     it("updates aria-current for active item", async () => {
-      const nextButton = wrapper.find('[aria-label="Go to next item"]');
+      const nextButton = wrapper.find('.carousel-flip-button-next');
       await nextButton.trigger("click");
       await nextTick();
 
-      const items = wrapper.findAll(".item");
-      expect(items[0].attributes("aria-current")).toBe("false");
+      const items = wrapper.findAll(".carousel-flip-item");
+      expect(items[0].attributes("aria-current")).toBeUndefined();
       expect(items[1].attributes("aria-current")).toBe("true");
     });
   });
@@ -506,7 +501,7 @@ describe("CarouselFlip", () => {
     });
 
     it("ignores other keys", async () => {
-      const container = wrapper.find(".item-container");
+      const container = wrapper.find(".carousel-flip-track");
       const initialIndex = component.currentActiveIndex;
 
       await container.trigger("keydown", { key: "Space" });
@@ -557,16 +552,16 @@ describe("CarouselFlip", () => {
       await nextTick();
     });
 
-    it("applies loaded class after user interaction", async () => {
-      const items = wrapper.findAll(".item");
-      expect(items[0].classes()).not.toContain("loaded");
+    it("sets data-loaded after user interaction", async () => {
+      const items = wrapper.findAll(".carousel-flip-item");
+      expect(items[0].attributes("data-loaded")).toBeUndefined();
 
-      const nextButton = wrapper.find('[aria-label="Go to next item"]');
+      const nextButton = wrapper.find('.carousel-flip-button-next');
       await nextButton.trigger("click");
       await nextTick();
 
-      const updatedItems = wrapper.findAll(".item");
-      expect(updatedItems[0].classes()).toContain("loaded");
+      const updatedItems = wrapper.findAll(".carousel-flip-item");
+      expect(updatedItems[0].attributes("data-loaded")).toBe("");
     });
 
     it("calls reorderItems without animation during initial setup", async () => {
@@ -580,7 +575,7 @@ describe("CarouselFlip", () => {
       // Test that navigation works which implicitly tests reorderItems is called
       const initialIndex = component.currentActiveIndex;
 
-      const nextButton = wrapper.find('[aria-label="Go to next item"]');
+      const nextButton = wrapper.find('.carousel-flip-button-next');
       await nextButton.trigger("click");
       await nextTick();
 
@@ -594,30 +589,31 @@ describe("CarouselFlip", () => {
     it("handles empty carousel data", async () => {
       await createWrapper({ carouselDataIds: [] });
 
-      const items = wrapper.findAll(".item");
+      const items = wrapper.findAll(".carousel-flip-item");
       expect(items).toHaveLength(0);
       expect(component.itemCount).toBe(0);
 
-      const markers = wrapper.findAll(".btn-marker");
+      const markers = wrapper.findAll(".carousel-flip-marker");
       expect(markers).toHaveLength(0);
     });
 
     it("handles single item carousel", async () => {
       await createWrapper({ carouselDataIds: ["single-item"] });
 
-      const items = wrapper.findAll(".item");
+      const items = wrapper.findAll(".carousel-flip-item");
       expect(items).toHaveLength(1);
 
-      const markers = wrapper.findAll(".btn-marker");
-      expect(markers).toHaveLength(1);
-      expect(markers[0].classes()).toContain("active");
+      expect(wrapper.findAll(".carousel-flip-marker")).toHaveLength(0);
+      expect(wrapper.find(".carousel-flip-button-prev").exists()).toBe(false);
+      expect(wrapper.find(".carousel-flip-button-next").exists()).toBe(false);
+      expect(items[0]!.attributes("aria-current")).toBe("true");
     });
 
     it("prevents navigation when carousel is not initialized", async () => {
       await createWrapper();
       component.carouselInitComplete = false;
 
-      const nextButton = wrapper.find('[aria-label="Go to next item"]');
+      const nextButton = wrapper.find('.carousel-flip-button-next');
       await nextButton.trigger("click");
       await nextTick();
 
@@ -655,7 +651,7 @@ describe("CarouselFlip", () => {
     it("applies transition speed as CSS custom property", async () => {
       await createWrapper({ transitionSpeed: 300 });
 
-      const items = wrapper.findAll(".item");
+      const items = wrapper.findAll(".carousel-flip-item");
       if (items.length > 0) {
         // CSS custom properties are handled by Vue's reactivity system
         expect(component).toBeDefined();
@@ -672,4 +668,64 @@ describe("CarouselFlip", () => {
       expect(component).toBeDefined();
     });
   });
+
+  describe("Worst-case data", () => {
+    it("mounts with no items without hanging, and renders no buttons or markers", async () => {
+      await createWrapper({ carouselDataIds: [] });
+      await nextTick();
+      expect(wrapper.findAll(".carousel-flip-item")).toHaveLength(0);
+      expect(wrapper.find(".carousel-flip-buttons").exists()).toBe(false);
+      expect(wrapper.find(".carousel-flip-controls").exists()).toBe(false);
+      expect(wrapper.find("[aria-live]").text()).toBe("");
+    });
+
+    it("keeps the item count in step when carouselDataIds changes after mount", async () => {
+      await createWrapper({ carouselDataIds: ["item-1", "item-2"] });
+      expect(wrapper.findAll(".carousel-flip-marker")).toHaveLength(2);
+
+      await wrapper.setProps({ carouselDataIds: ["item-1", "item-2", "item-3", "item-4"] });
+      expect(wrapper.findAll(".carousel-flip-marker")).toHaveLength(4);
+      expect(wrapper.find("[aria-live]").text()).toContain("of 4");
+    });
+
+    it("resets to the first item when the active one is removed", async () => {
+      await createWrapper();
+      component.jumpToFrame(5);
+      await nextTick();
+      await wrapper.setProps({ carouselDataIds: ["item-1", "item-2"] });
+      await nextTick();
+      expect(component.currentActiveIndex).toBe(0);
+    });
+
+    it("renders items whose ids repeat without dropping one", async () => {
+      await createWrapper({ carouselDataIds: ["item-1", "item-1", "item-2"] });
+      expect(wrapper.findAll(".carousel-flip-item")).toHaveLength(3);
+    });
+
+    it("gives the controls bar no tab stop of its own", async () => {
+      await createWrapper();
+      expect(wrapper.find(".carousel-flip-controls").attributes("tabindex")).toBeUndefined();
+    });
+
+    it("replaces styleClassPassthrough classes when the prop changes", async () => {
+      await createWrapper({ styleClassPassthrough: ["first"] });
+      await wrapper.setProps({ styleClassPassthrough: ["second"] });
+      expect(wrapper.classes()).not.toContain("first");
+      expect(wrapper.classes()).toContain("second");
+    });
+
+    it("renders both buttons inside the buttons group in the track-edges layout", async () => {
+      await createWrapper({ buttonLayout: "track-edges" });
+      expect(wrapper.attributes("data-button-layout")).toBe("track-edges");
+      const group = wrapper.find(".carousel-flip-buttons");
+      expect(group.find(".carousel-flip-button-prev").exists()).toBe(true);
+      expect(group.find(".carousel-flip-button-next").exists()).toBe(true);
+    });
+
+    it("names the prev and next buttons with their visually hidden text", async () => {
+      await createWrapper({ previousLabel: "Previous look", nextLabel: "Next look" });
+      expect(wrapper.find(".carousel-flip-button-prev").text()).toContain("Previous look");
+      expect(wrapper.find(".carousel-flip-button-next").text()).toContain("Next look");
+    });
+  });
 });

package/app/components/03.organisms/services/service-detail/tests/ServiceDetail.spec.ts

@@ -129,38 +129,38 @@ describe("ServiceDetail", () => {
 
   it("defaults heroImageVariant to full, heroContentVariant and bodyVariant to content", async () => {
     const wrapper = await mountSuspended(ServiceDetail, { props: { serviceData: mockService } });
-    expect(wrapper.find(".service-detail__hero-image-row").classes()).toContain("full");
-    expect(wrapper.find(".service-detail__hero-overlay").classes()).toContain("content");
-    expect(wrapper.find(".service-detail__body-row").classes()).toContain("content");
+    expect(wrapper.find(".service-detail__hero-image-row").attributes("data-variant")).toBe("full");
+    expect(wrapper.find(".service-detail__hero-overlay").attributes("data-variant")).toBe("content");
+    expect(wrapper.find(".service-detail__body-row").attributes("data-variant")).toBe("content");
   });
 
   it("applies the heroImageVariant prop to the hero image PageRow", async () => {
     const wrapper = await mountSuspended(ServiceDetail, {
       props: { serviceData: mockService, heroImageVariant: "popout" },
     });
-    expect(wrapper.find(".service-detail__hero-image-row").classes()).toContain("popout");
+    expect(wrapper.find(".service-detail__hero-image-row").attributes("data-variant")).toBe("popout");
   });
 
   it("applies the heroContentVariant prop to the hero content PageRow", async () => {
     const wrapper = await mountSuspended(ServiceDetail, {
       props: { serviceData: mockService, heroContentVariant: "inset-content" },
     });
-    expect(wrapper.find(".service-detail__hero-overlay").classes()).toContain("inset-content");
+    expect(wrapper.find(".service-detail__hero-overlay").attributes("data-variant")).toBe("inset-content");
   });
 
   it("applies the bodyVariant prop to the body PageRow", async () => {
     const wrapper = await mountSuspended(ServiceDetail, {
       props: { serviceData: mockService, bodyVariant: "popout" },
     });
-    expect(wrapper.find(".service-detail__body-row").classes()).toContain("popout");
+    expect(wrapper.find(".service-detail__body-row").attributes("data-variant")).toBe("popout");
   });
 
   it("defaults finalCtaVariant to content and applies the prop to the final CTA PageRow", async () => {
     const wrapper = await mountSuspended(ServiceDetail, { props: { serviceData: mockService } });
-    expect(wrapper.find(".service-detail__final-cta-row").classes()).toContain("content");
+    expect(wrapper.find(".service-detail__final-cta-row").attributes("data-variant")).toBe("content");
 
     await wrapper.setProps({ finalCtaVariant: "full" });
-    expect(wrapper.find(".service-detail__final-cta-row").classes()).toContain("full");
+    expect(wrapper.find(".service-detail__final-cta-row").attributes("data-variant")).toBe("full");
   });
 
   // ─── Service data ───────────────────────────────────────────────────────

package/app/components/03.organisms/services/service-detail/tests/__snapshots__/ServiceDetail.spec.ts.snap

@@ -4,10 +4,10 @@ exports[`ServiceDetail > renders correct HTML structure 1`] = `
 "<div class="service-detail">
   <div class="grid-stack service-detail__hero">
     <div class="grid-stack__layer">
-      <div class="page-row full service-detail__hero-image-row"><img width="1920" height="1080" data-nuxt-img="" srcset="/_ipx/s_1920x1080/images/balayage.jpg 1x, /_ipx/s_3840x2160/images/balayage.jpg 2x" alt="Balayage" loading="eager" fetchpriority="high" class="service-detail__hero-image" src="/_ipx/s_1920x1080/images/balayage.jpg"></div>
+      <div class="page-row service-detail__hero-image-row" data-variant="full"><img width="1920" height="1080" data-nuxt-img="" srcset="/_ipx/s_1920x1080/images/balayage.jpg 1x, /_ipx/s_3840x2160/images/balayage.jpg 2x" alt="Balayage" loading="eager" fetchpriority="high" class="service-detail__hero-image" src="/_ipx/s_1920x1080/images/balayage.jpg"></div>
     </div>
     <div class="grid-stack__layer">
-      <div class="page-row content service-detail__hero-overlay">
+      <div class="page-row service-detail__hero-overlay" data-variant="content">
         <div class="service-detail__hero-content">
           <nav class="breadcrumb service-detail__breadcrumb" aria-label="Breadcrumb">
             <ol class="breadcrumb__list">
@@ -26,7 +26,7 @@ exports[`ServiceDetail > renders correct HTML structure 1`] = `
       </div>
     </div>
   </div>
-  <div class="page-row content service-detail__body-row">
+  <div class="page-row service-detail__body-row" data-variant="content">
     <div class="service-detail__body">
       <div class="service-detail__main">
         <p class="page-body-normal">Balayage is a freehand hair colouring technique that creates a soft gradient.</p>
@@ -95,7 +95,7 @@ exports[`ServiceDetail > renders correct HTML structure 1`] = `
       </aside>
     </div>
   </div>
-  <div class="page-row content service-detail__final-cta-row">
+  <div class="page-row service-detail__final-cta-row" data-variant="content">
     <div class="service-detail__final-cta">
       <div class="service-detail__final-cta-copy">
         <h2 class="hero-text" data-font-size="subheading" data-axis="horizontal">

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

@@ -2,43 +2,57 @@
 
 ## Public token API
 
-All `--site-header-*` tokens style the outer `.site-header` grid row (branding column + nav
-column). They're the stable override surface — set them at any scope without touching the
-component itself.
+All `--site-header-*` tokens style the header row. They're the stable override surface: set them
+at any scope without touching the component itself.
 
 | Token | Default | Controls |
 |---|---|---|
 | `--site-header-gap` | `2.4rem` | Gap between the branding column and the nav column |
+| `--site-header-branding-max-width` | `50%` | Widest the branding column may grow (`fit-content()`); past it, the branding wraps |
 | `--site-header-padding-inline` | `2.4rem` | Horizontal padding on `.site-header` |
 | `--site-header-padding-block` | `0px` | Vertical padding on `.site-header` |
-| `--site-header-bg` | `transparent` | Background colour of `.site-header` |
+| `--site-header-bg` | `transparent` | Background colour of `.site-header` (the content column, not the full-width row) |
 | `--site-header-position` | `static` | Set to `sticky` to pin the header, paired with `--site-header-sticky-offset` |
 | `--site-header-sticky-offset` | `0px` | `top` offset when `--site-header-position: sticky` |
-| `--site-header-z-index` | `9` | Stacking order of `.site-header` |
+| `--site-header-z-index` | `9` | Stacking order of the row |
 
-`SiteHeader` composes `PageRow` + `SkipLinks` + `ResponsiveHeader` internally. Two separate
-`styleClassPassthrough` props reach the two composed components independently:
+> Changed 2026-10-21: `--site-header-position`, `--site-header-sticky-offset` and
+> `--site-header-z-index` now apply to the outer row (`.site-header-row`, the `PageRow`) instead of
+> the inner `<header>`. On the inner header, `sticky` never stuck: its parent is exactly its own
+> height, so there was nowhere for it to move. The branding column was `auto` and is now capped by
+> `--site-header-branding-max-width`, so a long brand can't squeeze the nav to nothing.
 
-- `styleClassPassthrough` → forwarded to the root `PageRow` (targets `--site-header-*` tokens above)
-- `navStyleClassPassthrough` → forwarded to the nested `ResponsiveHeader` (targets its own
-  `--responsive-header-*` and `--overflow-nav-*` tokens — see
-  [../../responsive-header/CONSUMER-STYLING.md](../../responsive-header/CONSUMER-STYLING.md) if present,
-  or the `ResponsiveHeader` skill doc)
+No private `--_` tokens.
 
----
+`SiteHeader` composes `PageRow` + `SkipLinks` + `ResponsiveHeader`. Two separate
+`styleClassPassthrough` props reach the composed components independently:
+
+- `styleClassPassthrough` → the root `PageRow` (set `--site-header-*` tokens there)
+- `navStyleClassPassthrough` → the nested `ResponsiveHeader` (its own `--responsive-header-*` and
+  `--overflow-nav-*` tokens; see `ResponsiveHeader`'s `CONSUMER-STYLING.md`)
+
+## State hooks
+
+No state attributes. Element classes:
+
+| Class | Element |
+|---|---|
+| `.site-header-row` | Root `PageRow` (with `.page-row` and the variant class); carries the sticky position |
+| `.site-header` | The `<header>` grid: branding column + nav column |
+| `.site-header-home-nav` | The branding `<nav>` wrapping `SkipLinks` and the `#branding` slot |
+
+> Changed 2026-10-21: `.site-header-home-nav` was `.home-navigation`, and `.site-header-row` is new.
 
 ## Global theming
 
-Create `assets/styles/setup/07.components/site-header.css` in the consuming app and set tokens
-on a scope class matching the one passed via `styleClassPassthrough`:
+Set tokens on the scope class passed via `styleClassPassthrough`:
 
 ```css
-/* assets/styles/setup/07.components/site-header.css */
 .header {
   --site-header-gap: 1.6rem;
   --site-header-padding-inline: 1.2rem;
   --site-header-position: sticky;
-  --site-header-bg: #00000095;
+  --site-header-bg: var(--theme-surface-subtle);
 }
 ```
 
@@ -50,8 +64,6 @@ on a scope class matching the one passed via `styleClassPassthrough`:
 </SiteHeader>
 ```
 
----
-
 ## Local overrides
 
 Set the tokens above on an element you own (a page or section class, or a class added with
@@ -60,12 +72,18 @@ Set the tokens above on an element you own (a page or section class, or a class
 `<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:** sticky positioning needs the row's own parent to be taller than the row (normally the
+page layout) and no `overflow` other than `visible` on the ancestors between it and the scroller.
+
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root `PageRow`; `nav-style-class-passthrough` to
+`ResponsiveHeader`'s root.
 
 ## Notes
 
 - The branding markup (logo image, wordmark, etc.) is entirely consumer-authored via the
-  `#branding` slot — `SiteHeader` has no opinion on brand styling.
+  `#branding` slot; `SiteHeader` has no opinion on brand styling. Long branding wraps
+  (`overflow-wrap: anywhere`) once it reaches `--site-header-branding-max-width`.
 - `SkipLinks`' hardcoded anchors (`#main-content`, `#footer-content`) expect the consuming
-  layout's main/footer regions to carry those `id`s — unchanged from using `SkipLinks` directly.
-
+  layout's main/footer regions to carry those `id`s.