srcdev-nuxt-components 9.1.59 → 9.2.1

package/app/components/01.atoms/banner-video/CONSUMER-STYLING.md

@@ -0,0 +1,120 @@
+# BannerVideo — Consumer Styling Guide
+
+## Public token API
+
+All `--banner-video-*` tokens are the stable override surface. Set them globally in a theme
+file, scoped to a page wrapper, or per-instance via `styleClassPassthrough`.
+
+### Depth tier max-height
+
+| Token | Default | Controls |
+|---|---|---|
+| `--banner-video-max-height-xs` | `clamp(12rem, 15vw, 24rem)` | Max height at `depth="xs"` |
+| `--banner-video-max-height-sm` | `clamp(18rem, 22vw, 36rem)` | Max height at `depth="sm"` |
+| `--banner-video-max-height-md` | `clamp(28rem, 38vw, 56rem)` | Max height at `depth="md"` (default) |
+| `--banner-video-max-height-lg` | `clamp(40rem, 52vw, 72rem)` | Max height at `depth="lg"` |
+| `--banner-video-max-height-xl` | `clamp(52rem, 65vw, 90rem)` | Max height at `depth="xl"` |
+| `--banner-video-max-height` | `clamp(28rem, 38vw, 56rem)` | Fallback used if the active depth tier's own token isn't set |
+
+### Pause/play toggle button
+
+| Token | Default | Controls |
+|---|---|---|
+| `--banner-video-toggle-size` | `3.2rem` | Width and height of the toggle button |
+| `--banner-video-toggle-offset` | `1.2rem` | Margin from the bottom-right corner of the banner |
+| `--banner-video-toggle-background` | `oklch(0% 0 0 / 0.4)` | Button background |
+| `--banner-video-toggle-background-hover` | `oklch(0% 0 0 / 0.6)` | Button background on hover/focus |
+| `--banner-video-toggle-icon-color` | `white` | Icon colour (and any text colour, via `color`) |
+
+---
+
+## Icon and content overrides — props and slots, not CSS
+
+The toggle's icon is prop-driven, not hardcoded:
+
+```vue
+<BannerVideo
+  src="/videos/hero.mp4"
+  poster="/images/hero-poster.jpg"
+  play-icon="mdi:play-circle"
+  pause-icon="mdi:pause-circle"
+/>
+```
+
+For anything beyond swapping the icon name (e.g. a custom SVG, or an icon set the `Icon`
+component doesn't cover), replace it with the `toggle-icon` scoped slot, which receives
+`isPlaying`:
+
+```vue
+<BannerVideo src="/videos/hero.mp4" poster="/images/hero-poster.jpg">
+  <template #toggle-icon="{ isPlaying }">
+    <MyCustomIcon :name="isPlaying ? 'pause' : 'play'" />
+  </template>
+</BannerVideo>
+```
+
+---
+
+## Global theming — recommended approach
+
+Create `assets/styles/setup/07.components/banner-video.css` in the consuming app and set
+tokens on `:root`. This applies to every `BannerVideo` across the site.
+
+```css
+/* assets/styles/setup/07.components/banner-video.css */
+:root {
+  --banner-video-max-height-md: clamp(32rem, 45vw, 64rem);
+  --banner-video-toggle-background: var(--brand-overlay);
+  --banner-video-toggle-background-hover: var(--brand-overlay-strong);
+  --banner-video-toggle-icon-color: var(--brand-on-overlay);
+}
+```
+
+---
+
+## Page-scoped overrides
+
+Override tokens for a specific banner by scoping them under the page or layout wrapper.
+No `:deep()` is required (component styles are unscoped).
+
+```css
+/* In the consuming page's unscoped <style> block */
+.homepage-hero {
+  .banner-video {
+    --banner-video-max-height-xl: 80rem;
+    --banner-video-toggle-size: 4rem;
+    --banner-video-toggle-offset: 2rem;
+  }
+}
+```
+
+---
+
+## Per-instance overrides via styleClassPassthrough
+
+Use sparingly — prefer global or page-scoped CSS. When a single instance needs a distinct
+visual style, pass a modifier class:
+
+```vue
+<BannerVideo :style-class-passthrough="['quiet-toggle']" src="…" poster="…" />
+```
+
+```css
+.banner-video.quiet-toggle {
+  --banner-video-toggle-background: transparent;
+  --banner-video-toggle-background-hover: oklch(0% 0 0 / 0.3);
+}
+```
+
+---
+
+## Notes
+
+- `--banner-video-max-height` (no suffix) only applies if the active `data-depth` tier's own
+  token isn't set — in practice this only matters if you delete a depth tier's token without
+  replacing it. Prefer setting the specific `-{depth}` token you need.
+- The toggle button's `border-radius` (`100vw`, i.e. a full circle) and `transition-duration`
+  (`0.2s`) are not tokenized — they're low-variance visual details rather than something
+  consuming apps are expected to reskin per-brand.
+- `aspectRatio`, `objectFit`, `verticalPosition`, and `horizontalPosition` are props, not
+  tokens — set them directly on the component.

package/app/components/01.atoms/banner-video/stories/BannerVideo.stories.ts

@@ -39,7 +39,7 @@ const meta: Meta<typeof BannerVideo> = {
     depth: {
       control: "select",
       options: ["xs", "sm", "md", "lg", "xl"],
-      description: "Responsive max-height tier. Each maps to a clamp() scale; override via --theme-banner-video-max-height-{depth}",
+      description: "Responsive max-height tier. Each maps to a clamp() scale; override via --banner-video-max-height-{depth}",
       table: { category: "Layout" },
     },
     aspectRatio: {
@@ -65,6 +65,16 @@ const meta: Meta<typeof BannerVideo> = {
       description: "Horizontal crop position — start (left), center, or end (right). Maps to object-position on the fallback image",
       table: { category: "Appearance" },
     },
+    playIcon: {
+      control: "text",
+      description: "Icon name for the toggle button before playback starts (any Iconify icon)",
+      table: { category: "Appearance" },
+    },
+    pauseIcon: {
+      control: "text",
+      description: "Icon name for the toggle button once playback starts (any Iconify icon)",
+      table: { category: "Appearance" },
+    },
     styleClassPassthrough: {
       table: { disable: true },
     },
@@ -73,7 +83,7 @@ const meta: Meta<typeof BannerVideo> = {
     docs: {
       description: {
         component:
-          "A full-width banner that plays a muted, looping mp4 video. The poster image is shown before the video loads, when the video fails to play, and whenever the user has `prefers-reduced-motion: reduce` set. The banner is sized via `aspect-ratio` with a responsive `max-height` driven by the `depth` tier (`xs` → `xl`). Each tier uses a `clamp()` scale and exposes a `--theme-banner-video-max-height-{depth}` token for consuming pages to override. `objectFit` controls how media fills the frame. `verticalPosition` and `horizontalPosition` control the crop focal point.",
+          "A full-width banner that plays a muted, looping mp4 video. The poster image is shown before the video loads, when the video fails to play, and whenever the user has `prefers-reduced-motion: reduce` set. The banner is sized via `aspect-ratio` with a responsive `max-height` driven by the `depth` tier (`xs` → `xl`). Each tier uses a `clamp()` scale and exposes a `--banner-video-max-height-{depth}` token for consuming pages to override. `objectFit` controls how media fills the frame. `verticalPosition` and `horizontalPosition` control the crop focal point. The pause/play toggle's icon is configurable via `playIcon`/`pauseIcon` props, or fully replaceable via the `toggle-icon` scoped slot.",
       },
     },
   },
@@ -178,3 +188,44 @@ export const Standard169: Story = {
     },
   },
 };
+
+export const CustomToggleIcons: Story = {
+  args: {
+    ...Default.args,
+    playIcon: "mdi:play-circle",
+    pauseIcon: "mdi:pause-circle",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "Custom icon names passed via playIcon and pauseIcon props — swaps the toggle button's icon without touching markup.",
+      },
+    },
+  },
+};
+
+export const CustomToggleIconSlot: Story = {
+  args: {
+    ...Default.args,
+  },
+  render: (args) => ({
+    components: { BannerVideo },
+    setup() {
+      return { args };
+    },
+    template: `
+      <BannerVideo v-bind="args">
+        <template #toggle-icon="{ isPlaying }">
+          <span style="font-size:1.4rem;font-weight:700;">{{ isPlaying ? 'II' : '▶' }}</span>
+        </template>
+      </BannerVideo>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "The toggle-icon scoped slot replaces the toggle button's icon entirely, receiving isPlaying — use when an Iconify icon name isn't enough (a custom SVG, or a different icon set).",
+      },
+    },
+  },
+};

package/app/components/01.atoms/banner-video/tests/BannerVideo.spec.ts

@@ -127,6 +127,51 @@ describe("BannerVideo", () => {
     expect(play).toHaveBeenCalled();
   });
 
+  // ─── Pause/play toggle (WCAG 2.2.2) ─────────────────────────────────────
+
+  it("renders a pause/play toggle button", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find(".banner-video__toggle").exists()).toBe(true);
+  });
+
+  it("toggle defaults to a 'Pause background video' label once playback starts", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    await wrapper.find("video").trigger("play");
+    expect(wrapper.find(".banner-video__toggle").attributes("aria-label")).toBe("Pause background video");
+  });
+
+  it("toggle reads 'Play background video' before playback has started", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find(".banner-video__toggle").attributes("aria-label")).toBe("Play background video");
+  });
+
+  it("clicking the toggle calls pause() while playing", async () => {
+    const pause = vi.fn();
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    const videoElement = wrapper.find("video").element as HTMLVideoElement;
+    videoElement.pause = pause;
+    Object.defineProperty(videoElement, "paused", { value: false, configurable: true });
+    await wrapper.find(".banner-video__toggle").trigger("click");
+    expect(pause).toHaveBeenCalled();
+  });
+
+  it("clicking the toggle calls play() while paused", async () => {
+    const play = vi.fn().mockResolvedValue(undefined);
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    const videoElement = wrapper.find("video").element as HTMLVideoElement;
+    videoElement.play = play;
+    Object.defineProperty(videoElement, "paused", { value: true, configurable: true });
+    await wrapper.find(".banner-video__toggle").trigger("click");
+    expect(play).toHaveBeenCalled();
+  });
+
+  it("updates aria-label to 'Play background video' after the video pauses", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    await wrapper.find("video").trigger("play");
+    await wrapper.find("video").trigger("pause");
+    expect(wrapper.find(".banner-video__toggle").attributes("aria-label")).toBe("Play background video");
+  });
+
   // ─── Fallback image ──────────────────────────────────────────────────────
 
   it("renders a NuxtImg fallback element", async () => {
@@ -349,4 +394,54 @@ describe("BannerVideo", () => {
     expect(wrapper.classes()).not.toContain("original");
     expect(wrapper.classes()).toContain("updated");
   });
+
+  // ─── Toggle icon ─────────────────────────────────────────────────────────
+
+  it("renders the default play icon before playback starts", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    expect(wrapper.find(".banner-video__toggle").html()).toContain("mdi:play");
+  });
+
+  it("renders the default pause icon once playback starts", async () => {
+    const wrapper = await mountSuspended(BannerVideo, { props: defaultProps });
+    await wrapper.find("video").trigger("play");
+    expect(wrapper.find(".banner-video__toggle").html()).toContain("mdi:pause");
+  });
+
+  it("renders a custom playIcon", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: { ...defaultProps, playIcon: "mdi:play-circle" },
+    });
+    expect(wrapper.find(".banner-video__toggle").html()).toContain("mdi:play-circle");
+  });
+
+  it("renders a custom pauseIcon", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: { ...defaultProps, pauseIcon: "mdi:pause-circle" },
+    });
+    await wrapper.find("video").trigger("play");
+    expect(wrapper.find(".banner-video__toggle").html()).toContain("mdi:pause-circle");
+  });
+
+  it("replaces the toggle icon via the toggle-icon slot", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: defaultProps,
+      slots: {
+        "toggle-icon": '<span class="test-custom-icon">custom</span>',
+      },
+    });
+    expect(wrapper.find(".test-custom-icon").exists()).toBe(true);
+  });
+
+  it("passes isPlaying to the toggle-icon slot", async () => {
+    const wrapper = await mountSuspended(BannerVideo, {
+      props: defaultProps,
+      slots: {
+        "toggle-icon": `<span class="test-is-playing">{{ params.isPlaying }}</span>`,
+      },
+    });
+    expect(wrapper.find(".test-is-playing").text()).toBe("false");
+    await wrapper.find("video").trigger("play");
+    expect(wrapper.find(".test-is-playing").text()).toBe("true");
+  });
 });

package/app/components/01.atoms/banner-video/tests/__snapshots__/BannerVideo.spec.ts.snap

@@ -3,11 +3,11 @@
 exports[`BannerVideo > renders correct HTML structure (all props set) 1`] = `
 "<header class="banner-video full-bleed" data-depth="xl" style="--_aspect-ratio: 16/9; --_align-self: center; --_justify-self: center;"><video class="video" autoplay="" muted="" loop="" playsinline="" preload="auto" fetchpriority="high" poster="/images/banners/video/lake-banner.jpg" style="object-fit: cover;">
     <source src="/images/banners/video/lake-banner.mp4" type="video/mp4">
-  </video><img width="1280" height="720" data-nuxt-img="" srcset="/_ipx/s_1280x720/images/banners/video/lake-banner.jpg 1x, /_ipx/s_2560x1440/images/banners/video/lake-banner.jpg 2x" class="fallback" alt="Lake banner" loading="eager" fetchpriority="high" decoding="async" style="object-fit: cover; object-position: center center;" src="/_ipx/s_1280x720/images/banners/video/lake-banner.jpg"></header>"
+  </video><img width="1280" height="720" data-nuxt-img="" srcset="/_ipx/s_1280x720/images/banners/video/lake-banner.jpg 1x, /_ipx/s_2560x1440/images/banners/video/lake-banner.jpg 2x" class="fallback" alt="Lake banner" loading="eager" fetchpriority="high" decoding="async" style="object-fit: cover; object-position: center center;" src="/_ipx/s_1280x720/images/banners/video/lake-banner.jpg"><button type="button" class="banner-video__toggle" aria-label="Play background video"><span class="iconify i-mdi:play" aria-hidden="true"></span></button></header>"
 `;
 
 exports[`BannerVideo > renders correct HTML structure (default props) 1`] = `
 "<div class="banner-video" data-depth="md" style="--_aspect-ratio: 21/9; --_align-self: center; --_justify-self: center;"><video class="video" autoplay="" muted="" loop="" playsinline="" preload="auto" fetchpriority="high" poster="/images/banners/video/lake-banner.jpg" style="object-fit: cover;">
     <source src="/images/banners/video/lake-banner.mp4" type="video/mp4">
-  </video><img width="1920" height="1080" data-nuxt-img="" srcset="/_ipx/s_1920x1080/images/banners/video/lake-banner.jpg 1x, /_ipx/s_3840x2160/images/banners/video/lake-banner.jpg 2x" class="fallback" alt="" loading="eager" fetchpriority="high" decoding="async" style="object-fit: cover; object-position: center center;" src="/_ipx/s_1920x1080/images/banners/video/lake-banner.jpg"></div>"
+  </video><img width="1920" height="1080" data-nuxt-img="" srcset="/_ipx/s_1920x1080/images/banners/video/lake-banner.jpg 1x, /_ipx/s_3840x2160/images/banners/video/lake-banner.jpg 2x" class="fallback" alt="" loading="eager" fetchpriority="high" decoding="async" style="object-fit: cover; object-position: center center;" src="/_ipx/s_1920x1080/images/banners/video/lake-banner.jpg"><button type="button" class="banner-video__toggle" aria-label="Play background video"><span class="iconify i-mdi:play" aria-hidden="true"></span></button></div>"
 `;

package/app/components/01.atoms/grids/data-grid/AutoGrid.vue

@@ -1,5 +1,5 @@
 <template>
-  <component :is="tag" class="auto-grid" :class="[elementClasses, { 'is-responsive': isResponsive }]" :aria-labelledby="ariaLabelledby">
+  <component :is="tag" class="auto-grid" :class="[elementClasses, { 'is-responsive': isResponsive }]">
     <slot v-for="(_, name) in $slots" :key="name" :name="name"></slot>
   </component>
 </template>
@@ -18,7 +18,6 @@ const props = withDefaults(defineProps<Props>(), {
 });
 
 const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
-const { ariaLabelledby } = useAriaLabelledById(props.tag);
 
 watch(
   () => props.styleClassPassthrough,

package/app/components/01.atoms/grids/data-grid/tests/AutoGrid.spec.ts

@@ -64,25 +64,17 @@ describe("AutoGrid", () => {
 
   // ─── Aria ─────────────────────────────────────────────────────────────────
 
-  it("does not set aria-labelledby when tag is div", async () => {
-    const wrapper = await mountSuspended(AutoGrid, { props: { tag: "div" } });
-    expect(wrapper.attributes("aria-labelledby")).toBeUndefined();
-  });
-
-  it("sets aria-labelledby when tag is section", async () => {
-    const wrapper = await mountSuspended(AutoGrid, { props: { tag: "section" } });
-    expect(wrapper.attributes("aria-labelledby")).toBeTruthy();
-  });
-
-  it("sets aria-labelledby when tag is article", async () => {
-    const wrapper = await mountSuspended(AutoGrid, { props: { tag: "article" } });
-    expect(wrapper.attributes("aria-labelledby")).toBeTruthy();
-  });
-
-  it("sets aria-labelledby when tag is main", async () => {
-    const wrapper = await mountSuspended(AutoGrid, { props: { tag: "main" } });
-    expect(wrapper.attributes("aria-labelledby")).toBeTruthy();
-  });
+  // AutoGrid has no heading of its own, so it never auto-generates an
+  // aria-labelledby regardless of tag — doing so would always be a broken
+  // ARIA reference, since there is no way for a consumer to bind a heading
+  // to it. Pass an explicit aria-label if a landmark tag needs a name.
+  it.each(["div", "section", "article", "main"] as const)(
+    "does not set aria-labelledby when tag is %s",
+    async (tag) => {
+      const wrapper = await mountSuspended(AutoGrid, { props: { tag } });
+      expect(wrapper.attributes("aria-labelledby")).toBeUndefined();
+    }
+  );
 
   // ─── isResponsive ────────────────────────────────────────────────────────
 

package/app/components/01.atoms/grids/data-grid/tests/__snapshots__/AutoGrid.spec.ts.snap

@@ -1,7 +1,7 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`AutoGrid > renders correct HTML structure (all props and slots set) 1`] = `
-"<section class="auto-grid custom-class is-responsive" aria-labelledby="v-0-0">
+"<section class="auto-grid custom-class is-responsive">
   <div>Item 1</div>
   <div>Item 2</div>
   <div>Item 3</div>

package/app/components/01.atoms/page-row/tests/PageRow.spec.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { h } from "vue";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
 import PageRow from "../PageRow.vue";
 
@@ -18,6 +19,9 @@ describe("PageRow", () => {
     wrapper = await mountSuspended(PageRow, {
       props: { ...props },
       slots,
+      // Attached to the real document so the aria-labelledby dev-warning check
+      // (which uses document.getElementById) can actually find slotted headings.
+      attachTo: document.body,
     });
     return wrapper;
   };
@@ -132,7 +136,7 @@ describe("PageRow", () => {
       expect(wrapper.attributes("aria-labelledby")).toBeUndefined();
     });
 
-    it.each(["section", "main", "article", "aside"] as const)(
+    it.each(["section", "article", "aside"] as const)(
       "sets aria-labelledby on <%s>",
       async (tag) => {
         await createWrapper({ tag });
@@ -140,8 +144,8 @@ describe("PageRow", () => {
       }
     );
 
-    it("does not set aria-labelledby on header, footer, nav", async () => {
-      for (const tag of ["header", "footer", "nav"] as const) {
+    it("does not set aria-labelledby on header, footer, nav, main", async () => {
+      for (const tag of ["header", "footer", "nav", "main"] as const) {
         await createWrapper({ tag });
         expect(wrapper.attributes("aria-labelledby")).toBeUndefined();
         wrapper.unmount();
@@ -167,6 +171,27 @@ describe("PageRow", () => {
       await createWrapper({}, { default: '<nav aria-label="Main navigation">Nav</nav>' });
       expect(wrapper.find("nav").attributes("aria-label")).toBe("Main navigation");
     });
+
+    it("warns when aria-labelledby is set but no element binds headingId", async () => {
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      await createWrapper({ tag: "section" }, { default: "<p>No heading here</p>" });
+      await nextTick();
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("broken ARIA reference"));
+      warnSpy.mockRestore();
+    });
+
+    it("does not warn when the heading-id slot prop is bound to a real heading", async () => {
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      await createWrapper(
+        { tag: "section" },
+        {
+          default: (slotProps: { headingId: string }) => h("h2", { id: slotProps.headingId }, "Title"),
+        }
+      );
+      await nextTick();
+      expect(warnSpy).not.toHaveBeenCalled();
+      warnSpy.mockRestore();
+    });
   });
 
   describe("CSS classes", () => {

package/app/components/02.molecules/profile-section/tests/ProfileSection.spec.ts

@@ -152,11 +152,11 @@ describe("ProfileSection", () => {
     expect(wrapper.find(".profile-section").attributes("aria-labelledby")).toBeUndefined();
   });
 
-  it("adds aria-labelledby when tag is main", async () => {
+  it("does not add aria-labelledby when tag is main (main never needs an accessible name)", async () => {
     const wrapper = await mountSuspended(ProfileSection, {
       props: { ...defaultProps, tag: "main" },
     });
-    expect(wrapper.find(".profile-section").attributes("aria-labelledby")).toBeTruthy();
+    expect(wrapper.find(".profile-section").attributes("aria-labelledby")).toBeUndefined();
   });
 
   it("does not render profile-links section when slot is not provided", async () => {

package/app/components/03.organisms/services/services-grids/tests/__snapshots__/ServicesSectionGrid.spec.ts.snap

@@ -7,7 +7,7 @@ exports[`ServicesSectionGrid > renders correct HTML structure 1`] = `
       <div class="services-section__image-wrapper"><img data-nuxt-img="" srcset="/_ipx/_/images/locs-installation.jpg 1x, /_ipx/_/images/locs-installation.jpg 2x" alt="Locs Installation" loading="eager" fetchpriority="high" class="services-section__image" src="/_ipx/_/images/locs-installation.jpg"></div>
       <div class="services-section__info-wrapper services-section__info-wrapper--summary services-section__info-wrapper--align-center">
         <div class="eyebrow-text large">Subtitle for Locs Installation</div>
-        <h2 class="hero-text mb-20 title axis-horizontal">
+        <h2 id="v-0-0-0" class="hero-text mb-20 title axis-horizontal">
           <!--v-if--><span class="text-block-0 normal">Locs Installation</span>
         </h2>
         <div class="services-section__price-duration">
@@ -34,7 +34,7 @@ exports[`ServicesSectionGrid > renders correct HTML structure 1`] = `
       <div class="services-section__image-wrapper"><img data-nuxt-img="" srcset="/_ipx/_/images/locs-retwist.jpg 1x, /_ipx/_/images/locs-retwist.jpg 2x" alt="Locs Retwist" loading="eager" fetchpriority="auto" class="services-section__image" src="/_ipx/_/images/locs-retwist.jpg"></div>
       <div class="services-section__info-wrapper services-section__info-wrapper--summary services-section__info-wrapper--align-center">
         <div class="eyebrow-text large">Subtitle for Locs Retwist</div>
-        <h2 class="hero-text mb-20 title axis-horizontal">
+        <h2 id="v-0-0-1" class="hero-text mb-20 title axis-horizontal">
           <!--v-if--><span class="text-block-0 normal">Locs Retwist</span>
         </h2>
         <div class="services-section__price-duration">
@@ -61,7 +61,7 @@ exports[`ServicesSectionGrid > renders correct HTML structure 1`] = `
       <div class="services-section__image-wrapper"><img data-nuxt-img="" srcset="/_ipx/_/images/colour-treatment.jpg 1x, /_ipx/_/images/colour-treatment.jpg 2x" alt="Colour Treatment" loading="lazy" fetchpriority="auto" class="services-section__image" src="/_ipx/_/images/colour-treatment.jpg"></div>
       <div class="services-section__info-wrapper services-section__info-wrapper--summary services-section__info-wrapper--align-center">
         <div class="eyebrow-text large">Subtitle for Colour Treatment</div>
-        <h2 class="hero-text mb-20 title axis-horizontal">
+        <h2 id="v-0-0-2" class="hero-text mb-20 title axis-horizontal">
           <!--v-if--><span class="text-block-0 normal">Colour Treatment</span>
         </h2>
         <div class="services-section__price-duration">

package/app/components/03.organisms/services/services-section/ServicesSection.vue

@@ -13,6 +13,7 @@
       <div class="services-section__info-wrapper" :class="infoWrapperClasses">
         <EyebrowText font-size="large" :text-content="serviceData.subtitle" />
         <HeroText
+          :id="headingId"
           :tag="headerTag"
           font-size="title"
           :text-content="[
@@ -191,7 +192,7 @@ const props = withDefaults(defineProps<Props>(), {
   styleClassPassthrough: () => [],
 });
 
-const { ariaLabelledby } = useAriaLabelledById(() => props.tag);
+const { headingId, ariaLabelledby } = useAriaLabelledById(() => props.tag);
 
 const infoWrapperClasses = computed(() => {
   return {

package/app/components/03.organisms/services/services-section/tests/ServicesSection.spec.ts

@@ -67,6 +67,18 @@ describe("ServicesSection", () => {
     expect(wrapper.element.tagName).toBe("SECTION");
   });
 
+  // ─── Aria ───────────────────────────────────────────────────────────────
+
+  it("binds aria-labelledby to the title HeroText's own id when tag is section", async () => {
+    const wrapper = await mountSuspended(ServicesSection, {
+      props: { serviceData: mockService, tag: "section" },
+      attachTo: document.body,
+    });
+    const ariaLabelledby = wrapper.attributes("aria-labelledby");
+    expect(ariaLabelledby).toBeTruthy();
+    expect(document.getElementById(ariaLabelledby!)?.textContent).toContain(mockService.title);
+  });
+
   // ─── Icons ──────────────────────────────────────────────────────────────
 
   it("renders the default duration icon name in the template", async () => {

package/app/components/03.organisms/services/services-section/tests/__snapshots__/ServicesSection.spec.ts.snap

@@ -6,7 +6,7 @@ exports[`ServicesSection > renders correct HTML structure 1`] = `
     <div class="services-section__image-wrapper"><img data-nuxt-img="" srcset="/_ipx/_/images/test.jpg 1x, /_ipx/_/images/test.jpg 2x" alt="Test Service" loading="eager" fetchpriority="high" class="services-section__image" src="/_ipx/_/images/test.jpg"></div>
     <div class="services-section__info-wrapper">
       <div class="eyebrow-text large">A subtitle</div>
-      <h2 class="hero-text mb-20 title axis-horizontal">
+      <h2 id="v-0-0" class="hero-text mb-20 title axis-horizontal">
         <!--v-if--><span class="text-block-0 normal">Test Service</span>
       </h2>
       <div class="services-section__price-duration">

package/app/components/04.templates/page-hero-highlights/tests/PageHeroHighlights.spec.ts

@@ -80,11 +80,11 @@ describe("PageHeroHighlights", () => {
     expect(wrapper.find(".page-hero-highlights").attributes("aria-labelledby")).toBeTruthy();
   });
 
-  it("adds aria-labelledby when tag is main", async () => {
+  it("does not add aria-labelledby when tag is main (main never needs an accessible name)", async () => {
     const wrapper = await mountSuspended(PageHeroHighlights, {
       props: { tag: "main" },
     });
-    expect(wrapper.find(".page-hero-highlights").attributes("aria-labelledby")).toBeTruthy();
+    expect(wrapper.find(".page-hero-highlights").attributes("aria-labelledby")).toBeUndefined();
   });
 
   it("does not add aria-labelledby when tag is div", async () => {

package/app/composables/tests/useAriaLabelledById.spec.ts

@@ -28,7 +28,7 @@ describe("useAriaLabelledById", () => {
   // ─── Labelled tags ────────────────────────────────────────────────────────
 
   describe("labelled tags", () => {
-    it.each(["section", "main", "article", "aside"])(
+    it.each(["section", "article", "aside"])(
       '"%s" returns ariaLabelledby = headingId',
       (tag) => {
         const { headingId, ariaLabelledby } = useAriaLabelledById(tag);
@@ -40,13 +40,18 @@ describe("useAriaLabelledById", () => {
   // ─── Non-labelled tags ────────────────────────────────────────────────────
 
   describe("non-labelled tags", () => {
-    it.each(["div", "span", "h1", "p", "ul", "nav"])(
+    it.each(["div", "span", "h1", "p", "ul", "nav", "main"])(
       '"%s" returns ariaLabelledby = undefined',
       (tag) => {
         const { ariaLabelledby } = useAriaLabelledById(tag);
         expect(ariaLabelledby.value).toBeUndefined();
       }
     );
+
+    it('"main" is never auto-labelled, even though it is a landmark', () => {
+      const { ariaLabelledby } = useAriaLabelledById("main");
+      expect(ariaLabelledby.value).toBeUndefined();
+    });
   });
 
   // ─── Reactivity ───────────────────────────────────────────────────────────

package/app/composables/useAriaLabelledById.ts

@@ -1,6 +1,8 @@
 import type { MaybeRefOrGetter } from "vue";
 
-const LABELLED_TAGS = new Set(["section", "main", "article", "aside"]);
+// "main" is deliberately excluded: a <main> landmark doesn't need an accessible
+// name unless a page has more than one, so it should never auto-label itself.
+const LABELLED_TAGS = new Set(["section", "article", "aside"]);
 
 export function useAriaLabelledById(tag: MaybeRefOrGetter<string>) {
   const headingId = useId();
@@ -9,5 +11,20 @@ export function useAriaLabelledById(tag: MaybeRefOrGetter<string>) {
     return LABELLED_TAGS.has(toValue(tag)) ? headingId : undefined;
   });
 
+  // Safety net: consumers are responsible for binding `headingId` to a real
+  // heading (directly, or via a slot prop) whenever aria-labelledby is set.
+  // Forgetting to do so produces a broken ARIA reference that otherwise only
+  // shows up in an accessibility audit (e.g. WAVE) — warn immediately instead.
+  onMounted(() => {
+    if (ariaLabelledby.value && !document.getElementById(headingId)) {
+      console.warn(
+        `[useAriaLabelledById] aria-labelledby="${headingId}" was set on a <${toValue(tag)}> element, ` +
+          `but no element with that id was found. Bind the "headingId" value returned by this composable ` +
+          `(often exposed as a "heading-id" slot prop) onto a visible heading, or the accessibility tree ` +
+          `will contain a broken ARIA reference.`
+      );
+    }
+  });
+
   return { headingId, ariaLabelledby };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "srcdev-nuxt-components",
   "type": "module",
-  "version": "9.1.59",
+  "version": "9.2.1",
   "main": "nuxt.config.ts",
   "types": "types.d.ts",
   "license": "MIT",