srcdev-nuxt-components 9.5.7 → 9.6.0

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

@@ -34,7 +34,16 @@
           role="none"
           @mouseenter="hoveredItemKey = `${String(groupKey)}-${localIndex}`"
         >
-          <NuxtLink class="overflow-navigation-link" :to="link.path" role="menuitem">
+          <a
+            v-if="isAnchorPath(link.path)"
+            class="overflow-navigation-link"
+            :href="link.path"
+            role="menuitem"
+            @click="emit('anchorClick', $event, link.path)"
+          >
+            <span class="overflow-navigation-text">{{ link.name }}</span>
+          </a>
+          <NuxtLink v-else class="overflow-navigation-link" :to="link.path" role="menuitem">
             <span class="overflow-navigation-text">{{ link.name }}</span>
           </NuxtLink>
         </li>
@@ -87,7 +96,16 @@
                     }"
                     @mouseenter="hoveredChildKey = `${String(groupKey)}-${localIndex}-${childIndex}`"
                   >
-                    <NuxtLink :to="childLink.path" class="overflow-navigation-sub-nav-link" role="menuitem">
+                    <a
+                      v-if="childLink.path && isAnchorPath(childLink.path)"
+                      :href="childLink.path"
+                      class="overflow-navigation-sub-nav-link"
+                      role="menuitem"
+                      @click="emit('anchorClick', $event, childLink.path)"
+                    >
+                      <span class="overflow-navigation-sub-nav-text">{{ childLink.name }}</span>
+                    </a>
+                    <NuxtLink v-else :to="childLink.path" class="overflow-navigation-sub-nav-link" role="menuitem">
                       <span class="overflow-navigation-sub-nav-text">{{ childLink.name }}</span>
                     </NuxtLink>
                   </li>
@@ -117,6 +135,8 @@ interface Props {
   ariaLabel?: string;
   /** aria-label on each submenu summary; {title} is replaced with the item's title. */
   submenuAriaLabel?: string;
+  /** The active "#anchor" path, owned by ResponsiveHeader so both menus agree. */
+  activeHash?: string;
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -128,8 +148,13 @@ const props = withDefaults(defineProps<Props>(), {
   styleClassPassthrough: () => [],
   ariaLabel: "Overflow navigation menu",
   submenuAriaLabel: "{title} submenu",
+  activeHash: "",
 });
 
+const emit = defineEmits<{
+  anchorClick: [event: MouseEvent, href: string];
+}>();
+
 const submenuLabel = (link: ResponsiveHeaderNavItem) =>
   props.submenuAriaLabel.replace("{title}", link.childLinksTitle ?? link.name);
 
@@ -162,9 +187,13 @@ onUnmounted(() => {
 
 const route = useRoute();
 
+const isAnchorPath = (path?: string) => Boolean(path?.startsWith("#"));
+const isCurrentPath = (path?: string) =>
+  Boolean(path) && (isAnchorPath(path) ? path === props.activeHash : path === route.path);
+
 const isActiveNavItem = (link: ResponsiveHeaderNavItem): boolean => {
-  if (link.path) return route.path === link.path;
-  if (link.childLinks) return link.childLinks.some((child) => child.path && route.path === child.path);
+  if (link.path) return isCurrentPath(link.path);
+  if (link.childLinks) return link.childLinks.some((child) => isCurrentPath(child.path));
   return false;
 };
 // const DETAILS_ANIMATION_DURATION_STRING = `${DETAILS_ANIMATION_DURATION}ms` as const;

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

@@ -39,8 +39,18 @@
           @mouseenter="handleNavigationItemHover(`${String(groupKey)}-${localIndex}`)"
           @focusin="handleNavigationItemHover(`${String(groupKey)}-${localIndex}`)"
         >
+          <a
+            v-if="link.path && isAnchorPath(link.path)"
+            class="main-navigation-link"
+            :class="{ 'has-icon': link.iconName }"
+            :href="link.path"
+            @click="handleAnchorClick($event, link.path)"
+          >
+            <Icon v-if="link.iconName" :name="link.iconName" class="decorator-icon" aria-hidden="true" />
+            {{ link.name }}
+          </a>
           <NuxtLink
-            v-if="link.path"
+            v-else-if="link.path"
             class="main-navigation-link"
             :class="{ 'has-icon': link.iconName }"
             :to="link.path"
@@ -69,7 +79,16 @@
                   :key="childIndex"
                   class="main-navigation-sub-nav-item"
                 >
-                  <NuxtLink :to="childLink.path" class="main-navigation-sub-nav-link" role="menuitem">
+                  <a
+                    v-if="childLink.path && isAnchorPath(childLink.path)"
+                    :href="childLink.path"
+                    class="main-navigation-sub-nav-link"
+                    role="menuitem"
+                    @click="handleAnchorClick($event, childLink.path)"
+                  >
+                    {{ childLink.name }}
+                  </a>
+                  <NuxtLink v-else :to="childLink.path" class="main-navigation-sub-nav-link" role="menuitem">
                     {{ childLink.name }}
                   </NuxtLink>
                 </li>
@@ -108,6 +127,8 @@
             :panel-variant="panelVariant"
             :aria-label="overflowMenuAriaLabel"
             :submenu-aria-label="submenuAriaLabel"
+            :active-hash="activeHash"
+            @anchor-click="handleAnchorClick"
           />
         </div>
       </details>
@@ -144,6 +165,11 @@ interface Props {
   overflowButtonLabel?: string;
   /** aria-label on each dropdown summary; {title} is replaced with the item's title. Forwarded to NavigationItems. */
   submenuAriaLabel?: string;
+  /**
+   * Pixels to leave above a section when a same-page "#anchor" link scrolls to it (e.g. a sticky
+   * header's height). Pass a getter to read it at click time.
+   */
+  anchorScrollOffset?: number | (() => number);
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -165,6 +191,7 @@ const props = withDefaults(defineProps<Props>(), {
   overflowMenuAriaLabel: "Overflow navigation menu",
   overflowButtonLabel: "More navigation",
   submenuAriaLabel: "{title} submenu",
+  anchorScrollOffset: undefined,
 });
 
 const submenuLabel = (link: ResponsiveHeaderNavItem) =>
@@ -315,12 +342,32 @@ const hoveredItemKey = ref<string | null>(null);
 
 const route = useRoute();
 
+// "#anchor" paths are same-page section links: plain <a>, smooth-scrolled, active by hash.
+const { handleNavClick, activeHash } = useAnchorScroll({ offset: props.anchorScrollOffset });
+const isAnchorPath = (path?: string) => Boolean(path?.startsWith("#"));
+const isCurrentPath = (path?: string) =>
+  Boolean(path) && (isAnchorPath(path) ? path === activeHash.value : path === route.path);
+
 const isActiveNavItem = (link: ResponsiveHeaderNavItem): boolean => {
-  if (link.path) return route.path === link.path;
-  if (link.childLinks) return link.childLinks.some((child) => child.path && route.path === child.path);
+  if (link.path) return isCurrentPath(link.path);
+  if (link.childLinks) return link.childLinks.some((child) => isCurrentPath(child.path));
   return false;
 };
 
+const handleAnchorClick = (event: MouseEvent, href: string) => {
+  handleNavClick(event, href);
+  closeAllNavigationDetails();
+};
+
+onMounted(() => {
+  if (activeHash.value) return;
+  const firstAnchor = Object.values(props.responsiveNavLinks)
+    .flat()
+    .flatMap((link) => [link, ...(link.childLinks ?? [])])
+    .find((link) => isAnchorPath(link.path));
+  if (firstAnchor?.path) activeHash.value = firstAnchor.path;
+});
+
 const isAnimated = ref(true);
 
 // Local (non-useState) flag — resets to false on every mount.

package/app/components/03.organisms/responsive-header/stories/ResponsiveHeader.stories.ts

@@ -82,6 +82,11 @@ const meta: Meta<StoryArgs> = {
       description: "aria-label on each dropdown summary; {title} is replaced with the item's title",
       table: { category: "Labels", defaultValue: { summary: "{title} submenu" } },
     },
+    anchorScrollOffset: {
+      control: { type: "number", min: 0, step: 10 },
+      description: "Pixels left above a section when a #anchor link scrolls to it (e.g. a sticky header's height)",
+      table: { category: "Behaviour", defaultValue: { summary: "0" } },
+    },
     styleClassPassthrough: {
       control: "object",
       description: "Extra CSS classes applied to the root element",
@@ -200,6 +205,53 @@ export const MainNavAlignment: Story = {
   },
 };
 
+export const SamePageAnchorLinks: Story = {
+  name: "Same-Page Anchor Links",
+  args: {
+    responsiveNavLinks: {
+      main: [
+        { name: "Home", path: "#rh-home" },
+        { name: "About", path: "#rh-about" },
+        { name: "Testimonials", path: "#rh-testimonials" },
+        {
+          name: "More",
+          childLinks: [
+            { name: "Prices", path: "#rh-prices" },
+            { name: "Blog (a route)", path: "/blog" },
+          ],
+        },
+        { name: "Contact", path: "#rh-contact" },
+      ],
+    },
+    anchorScrollOffset: 80,
+  },
+  render: renderWith(`
+    <div style="position: sticky; top: 0; z-index: 2; background: var(--page-bg, white); border-block-end: 1px solid currentColor;">
+      <ResponsiveHeader v-bind="componentArgs" />
+    </div>
+    <section
+      v-for="id in ['rh-home', 'rh-about', 'rh-testimonials', 'rh-prices', 'rh-contact']"
+      :id="id"
+      :key="id"
+      style="min-block-size: 70vh; padding: 2.4rem; border-block-end: 1px dashed currentColor;"
+    >
+      <h2 style="margin: 0;">#{{ id }}</h2>
+    </section>
+  `),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Items whose `path` starts with `#` are same-page section links: they render as plain `<a>` (not NuxtLink), " +
+          "smooth-scroll to the section (an instant jump under reduced motion), and are active by hash rather than by " +
+          "route; the first anchor is active on load. `anchorScrollOffset` (80 here) leaves room for the sticky header. " +
+          "Route links like Blog mix in as normal. Narrow the canvas so items move into the overflow menu: anchor links " +
+          "there scroll the same way and close the menu. This replaces TabNavigation's anchor mode.",
+      },
+    },
+  },
+};
+
 // ─── Stress test ──────────────────────────────────────────────────────────────
 
 const stressNavLinks: ResponsiveHeaderProp = {

package/app/components/03.organisms/responsive-header/tests/NavigationItems.spec.ts

@@ -168,4 +168,24 @@ describe("NavigationItems", () => {
     });
     expect(wrapper.html()).toMatchSnapshot();
   });
+
+  // ─── Same-page anchor links ─────────────────────────────────────────────
+
+  it("renders #anchor items as plain links, emits anchorClick and follows activeHash", async () => {
+    const wrapper = await mountSuspended(NavigationItems, {
+      props: {
+        activeHash: "#about",
+        mainNavigationState: {
+          clonedNavLinks: { firstNav: [{ name: "Home", path: "#home" }, { name: "About", path: "#about" }] },
+          navListVisibility: { firstNav: false },
+          hasSecondNav: false,
+        },
+      },
+    });
+    const links = wrapper.findAll(".overflow-navigation-link");
+    expect(links[0]!.attributes("href")).toBe("#home");
+    expect(wrapper.findAll(".overflow-navigation-item")[1]!.classes()).toContain("is-active");
+    await links[0]!.trigger("click");
+    expect(wrapper.emitted("anchorClick")?.[0]?.[1]).toBe("#home");
+  });
 });

package/app/components/03.organisms/responsive-header/tests/ResponsiveHeader.spec.ts

@@ -401,4 +401,44 @@ describe("ResponsiveHeader", () => {
     });
     expect(wrapper.html()).toMatchSnapshot();
   });
+
+  // ─── Same-page anchor links ─────────────────────────────────────────────
+
+  describe("anchor links", () => {
+    const anchorLinks: ResponsiveHeaderProp = {
+      firstNav: [
+        { name: "Home", path: "#home" },
+        { name: "About", path: "#about" },
+        { name: "Blog", path: "/blog" },
+      ],
+    };
+
+    it("renders #anchor paths as plain links and route paths as NuxtLinks", async () => {
+      const wrapper = await mountSuspended(ResponsiveHeader, { props: { responsiveNavLinks: anchorLinks } });
+      const links = wrapper.findAll(".main-navigation-link");
+      expect(links[0]!.attributes("href")).toBe("#home");
+      expect(links[2]!.attributes("href")).toBe("/blog");
+    });
+
+    it("marks the first anchor item active on load", async () => {
+      const wrapper = await mountSuspended(ResponsiveHeader, { props: { responsiveNavLinks: anchorLinks } });
+      await nextTick();
+      const items = wrapper.findAll(".main-navigation-item");
+      expect(items[0]!.classes()).toContain("is-active");
+      expect(items[1]!.classes()).not.toContain("is-active");
+    });
+
+    it("moves the active item to a clicked anchor and scrolls instead of jumping", async () => {
+      vi.stubGlobal("matchMedia", vi.fn().mockReturnValue({ matches: false }));
+      const section = document.createElement("section");
+      section.id = "about";
+      section.scrollIntoView = vi.fn();
+      document.body.appendChild(section);
+      const wrapper = await mountSuspended(ResponsiveHeader, { props: { responsiveNavLinks: anchorLinks } });
+      await wrapper.findAll(".main-navigation-link")[1]!.trigger("click");
+      expect(section.scrollIntoView).toHaveBeenCalled();
+      expect(wrapper.findAll(".main-navigation-item")[1]!.classes()).toContain("is-active");
+      section.remove();
+    });
+  });
 });

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

@@ -1,40 +1,8 @@
+# ServiceDetail — Consumer Styling Guide
 
 > **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
-
-The hero banner is a [GridStack](../../../../../.claude/skills/components/grid-stack.md) with two
-stacked layers — an `image` layer (the service photo) behind a `content` layer (the scrim +
-breadcrumb/title/pills). Each layer's root element is itself a
-[PageRow](../../../../../.claude/skills/components/page-row.md): `.service-detail__hero-image-row`
-(prop `heroImageVariant`, default `"full"`) wraps the photo, and `.service-detail__hero-overlay`
-(prop `heroContentVariant`, default `"content"`) *is* the scrim/alignment element, not a wrapper
-around one — a `PageRow`'s own box always spans the full width of its parent regardless of variant,
-only its children default into the variant's grid column, so the one element can carry the
-full-bleed scrim while its child (`.service-detail__hero-content`) still gets pulled to the
-configured column. This means the photo bleeds to whatever width `.service-detail` itself is allowed
-(edge-to-edge if `ServiceDetail` is placed without a content-constraining wrapper around it), while
-the breadcrumb/title/pills always stay pulled into the page's normal content-width column,
-regardless of how wide the photo bleeds. `--service-detail-hero-padding` now only controls
-**block** (vertical) padding on the scrim — horizontal alignment of the text is handled entirely by
-`.service-detail__hero-overlay`'s own `PageRow` grid, not by padding, so it can't fight the page's
-content-grid gutters.
-
-The two-column body (main content + sticky sidebar) is wrapped in its own `PageRow`, whose variant
-is a prop: `bodyVariant` (`"full" | "popout" | "content" | "inset-content"`, default `"content"`).
-The closing full-width CTA banner is wrapped the same way via `finalCtaVariant` (same type, same
-`"content"` default). This means a consumer no longer needs to wrap `ServiceDetail` itself in an
-outer `PageRow` purely to constrain either section's width — pass `body-variant`/`final-cta-variant`
-directly. It's still fine (and necessary for a genuine full-bleed hero) to place `ServiceDetail`
-inside an outer, wider `PageRow` — see
-[service-summary.md](../../../../../.claude/skills/components/service-summary.md)-style nesting
-notes in [page-row.md](../../../../../.claude/skills/components/page-row.md) for how nested page-rows
-compose.
-
----
 
 ## Public token API
 
@@ -44,12 +12,25 @@ compose.
 |---|---|---|
 | `--service-detail-hero-border-radius` | `0.8rem` | Corner rounding on the hero (clips the image/content layers — set to `0` for a true edge-to-edge bleed hero) |
 | `--service-detail-hero-content-align` | `end` | `align-content` on `.service-detail__hero-content` (the breadcrumb/title/pills wrapper) — where that content sits within the hero's block axis (`end` = bottom-anchored) |
-| `--service-detail-hero-min-height-mobile` | `32rem` | Hero banner height below the `768px` container breakpoint. The hero image always fills this height (`object-fit`/`object-position` control cropping) |
-| `--service-detail-hero-min-height-tablet` | `36rem` | Hero banner height from the `768px` container breakpoint |
-| `--service-detail-hero-min-height-desktop` | `42rem` | Hero banner height from the `1024px` container breakpoint |
+| `--service-detail-hero-min-height-mobile` | `32rem` | Minimum hero banner height below the `768px` container breakpoint. The hero grows past it when its content (a long title, say) needs more room; the image always fills the hero (`object-fit`/`object-position` control cropping) |
+| `--service-detail-hero-min-height-tablet` | `36rem` | Minimum hero banner height from the `768px` container breakpoint |
+| `--service-detail-hero-min-height-desktop` | `42rem` | Minimum hero banner height from the `1024px` container breakpoint |
+
+> Changed 2026-10-06: these were applied as a fixed `height`, so a long title was clipped by the
+> hero. They are now a true minimum (`min-block-size`), matching their names.
+>
+> Also 2026-10-06: line-clamp tokens for the hero eyebrow and title, sidebar labels and values,
+> and the final CTA heading and body. The hero title's and final CTA heading's spacing moved from
+> utility classes (`mb-20`, `mbs-0`/`mbe-8`) into the component CSS, same values, so the clamp can
+> keep descenders and italic overhang visible.
 | `--service-detail-hero-padding` | `3.2rem` | **Block-axis (vertical)** padding around the breadcrumb/title/pills content — horizontal alignment comes from the nested content `PageRow`, not this token |
 | `--service-detail-hero-scrim` | `linear-gradient(0deg, rgb(0 0 0 / 70%) 0%, rgb(0 0 0 / 10%) 60%, transparent 100%)` | Overlay gradient behind the hero text, for legibility over the image |
 | `--service-detail-hero-text-colour` | `white` | Colour of the breadcrumb, eyebrow, and title over the hero image |
+| `--service-detail-hero-eyebrow-line-clamp` | `none` | Max lines of the hero eyebrow (subtitle), ellipsis on the last. `1` is single-line ellipsis |
+| `--service-detail-hero-title-line-clamp` | `none` | Max lines of the hero title |
+
+For the breadcrumb, set Breadcrumb's own `--breadcrumb-item-line-clamp` (it reaches the hero
+breadcrumb from any ancestor).
 | `--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 `--display-pill-background`) |
@@ -100,8 +81,8 @@ target `--stepper-list-*` directly under `.service-detail__process` — see
 | `--service-detail-ideal-for-gap` | `1.2rem` | Gap between ideal-for cards |
 | `--service-detail-ideal-for-item-gap` | `1rem` | Gap between icon and text within a card |
 | `--service-detail-ideal-for-item-padding` | `1.6rem` | Padding inside a card |
-| `--service-detail-ideal-for-item-background` | `var(--slate-09)` | Card background colour |
-| `--service-detail-ideal-for-item-border-colour` | `var(--slate-06)` | Card border colour |
+| `--service-detail-ideal-for-item-background` | `var(--theme-surface-subtle)` | Card background colour |
+| `--service-detail-ideal-for-item-border-colour` | `transparent` | Card border colour |
 | `--service-detail-ideal-for-item-border-radius` | `0.4rem` | Card corner rounding |
 | `--service-detail-ideal-for-icon-size` | `1.6rem` | Icon size |
 | `--service-detail-ideal-for-icon-colour` | `var(--colour-text-accent)` | Icon colour |
@@ -129,17 +110,28 @@ The ideal-for grid becomes 2 columns at a **500px container width**.
 | `--service-detail-sidebar-row-book-cta-padding-block` | `2rem` | Vertical padding on the `book-cta` slot's own row (only renders when the slot has content) |
 | `--service-detail-sidebar-row-book-cta-justify-content` | `end` | Horizontal alignment of the `book-cta` slot content within its row |
 | `--service-detail-sidebar-row-label-font-size` | `1.2rem` | Font size of a row's label (e.g. "Price") |
+| `--service-detail-sidebar-label-line-clamp` | `none` | Max lines of the "Book This Service" / "You May Also Like" labels |
+| `--service-detail-sidebar-value-line-clamp` | `none` | Max lines of a row's value (price, duration, location) |
+
+A row's label takes the width of its own words (up to half the row) and wraps between words only;
+the value takes the rest and wraps anywhere.
 | `--service-detail-sidebar-note-font-size` | `1.2rem` | Font size of the `sidebar-note` slot content |
 | `--service-detail-sidebar-note-margin-block-start` | `1.2rem` | Space above the `sidebar-note` slot content |
 | `--service-detail-related-items-gap` | `1rem` | Gap between related-service item cards |
-| `--service-detail-related-item-background` | `var(--slate-09)` | Background colour of a related-service item's card |
+| `--service-detail-related-item-background` | `var(--theme-surface-subtle)` | Background colour of a related-service item's card |
 | `--service-detail-related-item-padding` | `1rem` | Padding inside a related-service item's card |
-| `--service-detail-related-item-border-colour` | `var(--slate-06)` | Border colour of a related-service item's card |
+| `--service-detail-related-item-border-colour` | `transparent` | Border colour of a related-service item's card |
 | `--service-detail-related-item-border-radius` | `0.4rem` | Corner rounding of a related-service item's card |
 | `--service-detail-related-item-gap` | `1.2rem` | Gap between a related item's thumbnail and its text |
 | `--service-detail-related-image-size` | `5.6rem` | Width/height of a related-service thumbnail |
 | `--service-detail-related-image-border-radius` | `0.4rem` | Corner rounding of a related-service thumbnail |
 | `--service-detail-related-price-font-size` | `1.2rem` | Font size of a related item's price |
+| `--service-detail-related-title-line-clamp` | `none` | Max lines of a related item's title (default item only, not the `related-service` slot). `1` is single-line ellipsis |
+
+> Changed 2026-10-06: the ideal-for and related-service cards defaulted to dark `--slate-09` with a
+> `--slate-06` border but set no text colour, so on a light page their inherited dark text was
+> unreadable. They now default to `var(--theme-surface-subtle)` with a transparent border. To keep
+> dark cards, set the four `-background`/`-border-colour` tokens.
 | `--service-detail-related-price-margin-block-start` | `0.6rem` | Space between a related item's title and its price |
 | `--service-detail-muted-opacity` | `0.7` | Opacity shared by every secondary/muted text element (sidebar label, sidebar note, related price, final CTA body) |
 
@@ -153,6 +145,11 @@ The booking card is a `GlassPanel` — its own `--glass-panel-*` tokens also app
 | `--service-detail-final-cta-margin-block-start` | `3.2rem` | Space above the banner |
 | `--service-detail-final-cta-padding-block` | `3.2rem 3.2rem` | Padding (block-start block-end) around the banner content, below its divider |
 | `--service-detail-final-cta-divider-colour` | `currentColor` | Divider line above the banner |
+| `--service-detail-final-cta-heading-line-clamp` | `none` | Max lines of the banner heading |
+| `--service-detail-final-cta-body-line-clamp` | `none` | Max lines of the banner body text |
+
+The `final-cta` slot sits in `.service-detail__final-cta-action`, which never shrinks: long copy
+wraps beside it instead of pushing the button out of the banner.
 
 The banner becomes a single row (copy left, CTA right) at a **700px container width**. Its own
 breakout width is controlled by the `finalCtaVariant` prop (default `"content"`), not a token —
@@ -160,6 +157,47 @@ see Layout building blocks above.
 
 ---
 
+## State hooks
+
+No state classes. Inner classes are all `service-detail__*` (hero, hero image/overlay/content, breadcrumb,
+hero pills, body, main, process, ideal-for and its items/icon, faqs and each faq/question, sidebar,
+booking card, sidebar label/rows/note, related items, final CTA). FAQ questions render one heading level
+below `subheadingTag` (`h3` for the default `h2`, `h4` for `h3`).
+
+---
+
+## Layout building blocks
+
+The hero banner is a [GridStack](../../../../../.claude/skills/components/grid-stack.md) with two
+stacked layers — an `image` layer (the service photo) behind a `content` layer (the scrim +
+breadcrumb/title/pills). Each layer's root element is itself a
+[PageRow](../../../../../.claude/skills/components/page-row.md): `.service-detail__hero-image-row`
+(prop `heroImageVariant`, default `"full"`) wraps the photo, and `.service-detail__hero-overlay`
+(prop `heroContentVariant`, default `"content"`) *is* the scrim/alignment element, not a wrapper
+around one — a `PageRow`'s own box always spans the full width of its parent regardless of variant,
+only its children default into the variant's grid column, so the one element can carry the
+full-bleed scrim while its child (`.service-detail__hero-content`) still gets pulled to the
+configured column. This means the photo bleeds to whatever width `.service-detail` itself is allowed
+(edge-to-edge if `ServiceDetail` is placed without a content-constraining wrapper around it), while
+the breadcrumb/title/pills always stay pulled into the page's normal content-width column,
+regardless of how wide the photo bleeds. `--service-detail-hero-padding` now only controls
+**block** (vertical) padding on the scrim — horizontal alignment of the text is handled entirely by
+`.service-detail__hero-overlay`'s own `PageRow` grid, not by padding, so it can't fight the page's
+content-grid gutters.
+
+The two-column body (main content + sticky sidebar) is wrapped in its own `PageRow`, whose variant
+is a prop: `bodyVariant` (`"full" | "popout" | "content" | "inset-content"`, default `"content"`).
+The closing full-width CTA banner is wrapped the same way via `finalCtaVariant` (same type, same
+`"content"` default). This means a consumer no longer needs to wrap `ServiceDetail` itself in an
+outer `PageRow` purely to constrain either section's width — pass `body-variant`/`final-cta-variant`
+directly. It's still fine (and necessary for a genuine full-bleed hero) to place `ServiceDetail`
+inside an outer, wider `PageRow` — see
+[service-summary.md](../../../../../.claude/skills/components/service-summary.md)-style nesting
+notes in [page-row.md](../../../../../.claude/skills/components/page-row.md) for how nested page-rows
+compose.
+
+---
+
 ## Text content — props, not CSS
 
 Section headings, sidebar labels, and CTA copy are **props**, not hardcoded strings:
@@ -177,6 +215,14 @@ Section headings, sidebar labels, and CTA copy are **props**, not hardcoded stri
 | `relatedServicesHeading` | `"You May Also Like"` |
 | `finalCtaHeading` | `"Ready to book your appointment?"` |
 | `finalCtaBody` | `"Get in touch to book your appointment."` |
+| `pricePrefix` | `"From"` (hero price pill; `""` shows the price alone) |
+| `breadcrumbAriaLabel` | Breadcrumb's own default |
+| `idealForIcon` | `"mdi:diamond-stone"` (decorative, hidden from assistive tech) |
+
+A section is left out, heading and all, when its data is empty (`process`, `idealFor`, `faqs`,
+`maintenance`, a `heroHeading` with no text), and so is any heading or label prop set to `""`. Empty
+`subtitle`, `title`, `price`, `duration`, `longDescription`, `whatIsIt` and FAQ questions/answers render
+nothing, and empty breadcrumb labels are dropped.
 
 ```vue
 <ServiceDetail
@@ -226,6 +272,12 @@ never reach the hero pills or breadcrumb. Use the `--service-detail-hero-*` toke
 
 ---
 
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root `.service-detail`. Reactive after mount.
+
+---
+
 ## Notes
 
 - Routing is entirely delegated to the consumer via slots: `book-cta` (scoped `serviceData`),
@@ -251,4 +303,3 @@ never reach the hero pills or breadcrumb. Use the `--service-detail-hero-*` toke
   `@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`).
-