srcdev-nuxt-components 9.1.59 → 9.2.0

package/.claude/skills/component-aria-landmark.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Components that accept a `tag` prop may render as a semantic landmark element (`section`, `main`, `article`, `aside`). Landmarks benefit from an accessible name via `aria-labelledby` pointing to a heading inside them. The `useAriaLabelledById` composable handles this automatically.
+Components that accept a `tag` prop may render as a semantic landmark element (`section`, `article`, `aside` — not `main`, see below). Landmarks benefit from an accessible name via `aria-labelledby` pointing to a heading inside them. The `useAriaLabelledById` composable handles generating and applying the attribute — but **binding the id to an actual heading is still the consumer's responsibility**; see "Built-in safety net" below for how that mistake gets caught.
 
 ## The composable
 
@@ -13,7 +13,29 @@ Returns `{ headingId, ariaLabelledby }`:
 - `headingId` — a stable ID (via `useId()`) to place on the heading element inside the slot
 - `ariaLabelledby` — computed: set to `headingId` when `tag` is a landmark, `undefined` otherwise (which removes the attribute entirely)
 
-Labelled tags: `section`, `main`, `article`, `aside`.
+Labelled tags: `section`, `article`, `aside`.
+
+**`main` is deliberately excluded.** A `<main>` landmark doesn't need an accessible name unless a
+page has more than one — auto-labelling it produced broken references in practice (the layout's
+top-level `<main>` wraps arbitrary page content with no single natural heading to bind).
+
+### Built-in safety net
+
+The composable itself checks, `onMounted`, whether `document.getElementById(headingId)` actually
+resolves whenever `ariaLabelledby` is set. If it doesn't, it `console.warn`s immediately with the
+tag name and id. This exists because the whole pattern is opt-in for the *consumer* — the
+composable has no way to force a heading to bind, so instead it makes the mistake loud instead of
+silent. **Do not treat the absence of a compile-time/type error as confirmation this is wired up
+correctly** — always check the console (or run an accessibility audit) after adding `tag="section"`
+(or `article`/`aside`) to any component using this pattern.
+
+This bug class previously shipped to production undetected: eight sections across one site had
+`aria-labelledby` pointing at ids that were never applied to anything, only surfaced by a WAVE
+audit. Two components (`ServicesSection`, `AutoGrid`) were also found to be *structurally* broken
+— they set `aria-labelledby` from `tag` alone without ever exposing `headingId` anywhere a
+consumer could bind it, so it was impossible to satisfy correctly. `ServicesSection` now binds
+`headingId` to its own internal title heading; `AutoGrid` has no heading concept at all, so it no
+longer sets `aria-labelledby` under any circumstance (pass `aria-label` directly if needed).
 
 ## Usage in a component
 
@@ -55,14 +77,26 @@ When `tag="div"` (default), the `aria-labelledby` attribute is absent and `headi
 
 ## Components already using this pattern
 
-- `PageHeroHighlights` (04.templates)
-- `ProfileSection` (02.molecules)
-- `ServicesSection` (03.organisms)
-- `LayoutGridByCols` (01.atoms)
-- `LayoutGridByWidth` (01.atoms)
+Consumer-bound (the component exposes `headingId` via a slot prop; whoever uses the component
+must bind it to their own heading):
+
+- `PageRow` (01.atoms) — default slot
+- `PageHeroHighlights` (04.templates) — `#header` slot
+- `ProfileSection` (02.molecules) — `#heroText` slot
+
+Self-bound (the component renders its own heading and binds `headingId` internally — no consumer
+action needed):
+
+- `ServicesSection` (03.organisms) — binds it to its own title `HeroText`
+- `LayoutGridByCols` / `LayoutGridByWidth` (01.atoms) — render their own visually-hidden `<p>` from the `label` prop
+
+Not using this pattern:
+
+- `AutoGrid` (01.atoms) — has no heading concept; never sets `aria-labelledby` regardless of `tag`
 
 ## Notes
 
-- If a component does not expose a named slot with `:heading-id`, the `headingId` is still generated — the consumer simply places their own heading inside the slot without binding the id.
+- If a component does not expose a named slot with `:heading-id`, the `headingId` is still generated — the consumer simply places their own heading inside the slot without binding the id. **This is the failure mode to watch for** — nothing prevents it at compile time, only the runtime console warning described above.
 - `headingId` is stable across renders (SSR-safe via `useId()`).
 - Do not replicate the old manual pattern (`const needsLabel = computed(() => props.tag === "section")`) — use this composable instead.
+- When adding `useAriaLabelledById` to a *new* component, prefer the self-bound pattern (render the heading yourself, or a `LayoutGridByCols`-style hidden label from a `label` prop) over the consumer-bound pattern wherever the component already controls its own heading markup — it structurally cannot go wrong the way the consumer-bound pattern can.

package/.claude/skills/components/auto-grid.md

@@ -91,11 +91,16 @@ Override `grid-template-columns` directly — there is no single token for this:
 </AutoGrid>
 ```
 
-### Semantic section with auto aria-labelledby
+### Semantic section with an accessible name
+
+`AutoGrid` has no heading concept of its own — its slots are arbitrary named items, not a
+header + body — so it does **not** auto-generate `aria-labelledby` the way `PageRow` or
+`ServicesSection` do (an earlier version of this component did attempt to, and it produced a
+guaranteed broken ARIA reference, since there was never any way to bind a heading to it). If
+`tag="section"` needs an accessible name, pass `aria-label` directly:
 
 ```vue
-<AutoGrid tag="section">
-  <!-- aria-labelledby is wired automatically via useAriaLabelledById -->
+<AutoGrid tag="section" aria-label="Practice stats">
   <template #item-1><div>Item 1</div></template>
   <template #item-2><div>Item 2</div></template>
 </AutoGrid>
@@ -128,9 +133,10 @@ const stats = [
 
 ## Accessibility
 
-- When `tag` is `section`, `article`, or `main`, `aria-labelledby` is automatically set via `useAriaLabelledById`, pointing to a generated heading ID.
-- When `tag="div"`, no ARIA attributes are added.
-- Ensure a heading element with the matching ID is present inside the grid when using semantic tags.
+- `AutoGrid` never sets `aria-labelledby` automatically, regardless of `tag` — it has no heading
+  to point to. Pass `aria-label` (or wrap it in a `PageRow`/other component that does own a
+  heading) if a landmark tag needs an accessible name.
+- No ARIA attributes are added by default for any `tag` value.
 
 See [component-aria-landmark.md](../component-aria-landmark.md) for the full landmark pattern.
 

package/.claude/skills/components/page-hero-highlights.md

@@ -147,7 +147,7 @@ Omit `#end` for a single-element header — `#start` fills full width with no la
 
 ## With aria-labelledby (section tag)
 
-When `tag="section"`, `aria-labelledby` is set automatically. Wire the heading id via the scoped slot prop:
+When `tag="section"`, `aria-labelledby` is set automatically. Wire the heading id via the scoped slot prop — if you don't, a console warning fires (from `useAriaLabelledById`) flagging the broken ARIA reference; see [component-aria-landmark.md](../component-aria-landmark.md):
 
 ```vue
 <PageHeroHighlights tag="section">
@@ -158,6 +158,8 @@ When `tag="section"`, `aria-labelledby` is set automatically. Wire the heading i
 </PageHeroHighlights>
 ```
 
+`tag="main"` renders a `<main>` element but is never auto-labelled — a `<main>` landmark doesn't need an accessible name unless a page has more than one.
+
 See [component-aria-landmark.md](../component-aria-landmark.md) for the full pattern.
 
 ## Equal-width highlights

package/.claude/skills/components/page-row.md

@@ -84,9 +84,13 @@ boundary at the track line. Useful for asymmetric imagery, pull-quotes, or decor
 
 ## Accessibility — aria-labelledby
 
-When `tag` is `section`, `main`, or `article`, `PageRow` automatically generates an
-`aria-labelledby` attribute pointing to the first heading inside. Bind the `headingId` slot prop
-to that heading's `id` to complete the association.
+When `tag` is `section`, `article`, or `aside`, `PageRow` automatically generates an
+`aria-labelledby` attribute pointing to the first heading inside. **You must bind the
+`headingId` slot prop to that heading's `id`** — `PageRow` cannot verify you did this, since the
+slot content is arbitrary. If you forget, the section gets an `aria-labelledby` pointing at an id
+that exists nowhere in the DOM, which accessibility audits (WAVE, axe) flag as a broken ARIA
+reference. A console warning fires in the browser (from `useAriaLabelledById`) the moment a
+mounted instance is missing its matching heading — check the console if you see this warning.
 
 ```vue
 <PageRow tag="section">
@@ -97,8 +101,13 @@ to that heading's `id` to complete the association.
 </PageRow>
 ```
 
-Non-landmark tags (`div`, `header`, `footer`, `nav`) do not receive `aria-labelledby`. The
-`headingId` slot prop is still provided but can be ignored.
+`tag="main"` is deliberately **not** auto-labelled — a `<main>` landmark doesn't need an
+accessible name unless a page has more than one. Other non-landmark tags (`div`, `header`,
+`footer`, `nav`) also do not receive `aria-labelledby`. The `headingId` slot prop is still
+provided in both cases but can be ignored.
+
+See [component-aria-landmark.md](../component-aria-landmark.md) for the full pattern and the
+list of components that share it.
 
 ---
 

package/.claude/skills/components/profile-section.md

@@ -8,7 +8,7 @@ type: reference
 
 ## Overview
 
-`ProfileSection` is a molecule that renders a practitioner/author profile: a header area (eyebrow + heading), a profile picture, and a flexible set of bio/info blocks alongside optional profile links. It is landmark-aware — the root element automatically gets `aria-labelledby` wired to the heading inside the `#heroText` slot.
+`ProfileSection` is a molecule that renders a practitioner/author profile: a header area (eyebrow + heading), a profile picture, and a flexible set of bio/info blocks alongside optional profile links. It is landmark-aware — when `tag` is `section`, `article`, or `aside`, the root element automatically gets `aria-labelledby` wired to the heading inside the `#heroText` slot (**you must bind `headingId` yourself, and a console warning fires if you forget** — see [component-aria-landmark.md](../component-aria-landmark.md)). `tag="main"` is never auto-labelled.
 
 ## Props
 

package/.claude/skills/components/services-section.md

@@ -207,5 +207,5 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
   `services-section__glass-panel`. If a consuming app has CSS overrides referencing older
   unprefixed names (`.image-wrapper`, `.price-duration`, `.services-faq`, etc. — from before
   this component's classnames were namespaced), those selectors need updating to match.
-- The section gets `aria-labelledby` automatically when `tag` is `"section"` or `"article"`, pointing to the internal heading id.
+- The section gets `aria-labelledby` automatically when `tag` is `"section"`, `"article"`, or `"aside"`, pointing at the id ServicesSection binds to its own title `HeroText` internally — no consumer action needed. (`tag="main"` renders a `<main>` element but is never auto-labelled; see [component-aria-landmark.md](../component-aria-landmark.md).)
 - `summaryAlignment` only has effect when `isSummary` is `true` — it aligns the info-wrapper content vertically within the grid cell.

package/.claude/skills/index.md

@@ -37,7 +37,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── css-nesting-conventions.md                — native CSS nesting rules: why &__child Sass BEM concatenation silently breaks, correct patterns
 ├── css-grid-max-width-gutters.md             — cap a centre grid column width by growing gutters, with start/center alignment variants
 ├── css-animation-utilities.md                — scroll-driven animation utility classes: scroller-x (carousel), entry-zoom-reveal, entry-slide-in, entry-exit-blur, auto-rotate
-├── component-aria-landmark.md        — useAriaLabelledById composable: aria-labelledby for section/main/article/aside tags
+├── component-aria-landmark.md        — useAriaLabelledById composable: aria-labelledby for section/article/aside tags (not main), consumer-bound vs self-bound pattern, built-in broken-reference console warning
 ├── component-export-types.md         — move inline component types to app/types/components/ barrel for consumer imports
 ├── component-inline-action-button.md — InputButtonCore variant="inline" pattern for buttons embedded in custom input wrappers
 ├── vue-video-autoplay.md             — autoplay on client-side navigation: use <source> child (not :src on <video>), :key, and explicit v.load()

package/.claude/skills/testing-add-unit-test.md

@@ -158,6 +158,24 @@ it("exposes headingId via scoped slot", async () => {
 });
 ```
 
+### Testing the aria-labelledby dev-warning (useAriaLabelledById)
+
+Components using `useAriaLabelledById` (see [component-aria-landmark.md](component-aria-landmark.md))
+`console.warn` on mount if `aria-labelledby` is set but no element in `document` has the matching
+id. To assert this warning (or its absence) in a test, `mountSuspended` must attach to the real
+document — by default VTU mounts into a detached container, so `document.getElementById` will
+never find the slotted heading even when it's correctly bound, producing a false-positive warning:
+
+```ts
+const wrapper = await mountSuspended(ComponentName, {
+  props: { tag: "section" },
+  attachTo: document.body, // required — see note above
+  slots: {
+    default: (props: { headingId: string }) => h("h2", { id: props.headingId }, "Title"),
+  },
+});
+```
+
 > Returning a plain string from a slot function does **not** produce DOM — always use `h()`.
 
 ## Key rules

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.0",
   "main": "nuxt.config.ts",
   "types": "types.d.ts",
   "license": "MIT",