srcdev-nuxt-components 9.1.58 → 9.2.0

package/.claude/settings.json

@@ -54,7 +54,10 @@
       "Bash(SRCDEV_STANDALONE=true npx vitest run app/components/01.atoms/toast)",
       "Bash(SRCDEV_STANDALONE=true npx vitest run app/components/02.molecules/alert-content)",
       "Bash(SRCDEV_STANDALONE=true npx vitest run app/components/01.atoms/prompt)",
-      "Bash(git fetch *)"
+      "Bash(git fetch *)",
+      "Bash(python3 -m json.tool /Users/simoncornforth/websites/nuxt-components/.vscode/srcdev-component-services-section.code-snippets)",
+      "Bash(node -e \"JSON.parse\\(require\\('fs'\\).readFileSync\\('/Users/simoncornforth/websites/nuxt-components/.vscode/srcdev-component-services-section.code-snippets','utf8'\\)\\); console.log\\('valid json'\\)\")",
+      "WebFetch(domain:luxury-locs-by-natasha-nuxt3.vercel.app)"
     ],
     "additionalDirectories": [
       "/Users/simoncornforth/websites/instepreflexology",

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

@@ -15,14 +15,40 @@ All routing and CTA decisions are delegated to the consumer via slots.
 |------|------|---------|----------|
 | `serviceData` | `Service` | — | **yes** |
 | `tag` | `"div" \| "section" \| "article" \| "main"` | `"div"` | no |
+| `headerTag` | `"h1" \| "h2" \| "h3"` | `"h2"` | no |
 | `index` | `number` | `0` | no |
 | `isSummary` | `boolean` | `false` | no |
 | `summaryAlignment` | `"start" \| "center" \| "end"` | `"center"` | no |
 | `reverse` | `boolean` | `false` | no |
 | `durationIcon` | `string` | `"mdi:clock-time-four-outline"` | no |
 | `priceIcon` | `string` | `"mdi:currency-gbp"` | no |
+| `processHeading` | `string` | `"The Process"` | no |
+| `idealForHeading` | `string` | `"Ideal For"` | no |
+| `maintenanceHeading` | `string` | `"Aftercare & Maintenance"` | no |
+| `faqsHeading` | `string` | `"Frequently Asked Questions"` | no |
+| `ctaHeading` | `string` | `"Ready to book your appointment?"` | no |
+| `ctaBody` | `string` | `"Get in touch to book your appointment."` | no |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | no |
 
+### Heading and CTA copy props
+
+All section subheadings and the default CTA panel's heading/body are props, not hardcoded
+text — override them with wording specific to the consuming business:
+
+```vue
+<ServicesSection
+  :service-data="service"
+  process-heading="How It Works"
+  cta-heading="Ready to book your colour appointment?"
+  cta-body="Mobile service across Bath — I come to you."
+/>
+```
+
+Name the actual service in `ctaHeading` (rather than a generic phrase) if every service page
+shares one CTA wrapper — a single hardcoded heading applied to every service previously caused
+a real bug in production, where a "Colour" service page's CTA read "Ready to book your
+**highlights** appointment?" regardless of which service was being viewed.
+
 ### Icon customisation
 
 The two icons in the price/duration row default to `mdi:clock-time-four-outline` and `mdi:currency-gbp`. Override them for a different currency or icon style:
@@ -51,8 +77,12 @@ Flips the image to the right column and content to the left (CSS `order: 2` on t
 |------|-----------|---------------|---------|
 | `summary-link` | `{ serviceData: Service }` | `isSummary` is `true` | Navigation link below the `whatIsIt` text in summary mode |
 | `cta` | `{ serviceData: Service }` | `isSummary` is `false` | CTA button/link inside the closing `GlassPanel` in full mode |
+| `cta-panel` | `{ serviceData: Service, ctaHeading: string, ctaBody: string }` | `isSummary` is `false` | Replaces the entire default `GlassPanel` CTA block — use when a consumer needs a different component or layout, not just different copy |
 
-Both slots receive `serviceData` as a scoped prop.
+All three slots receive `serviceData` as a scoped prop. `cta-panel`'s default content *is*
+the `GlassPanel` + `ctaHeading`/`ctaBody` + `cta` slot combination described above — providing
+`cta-panel` replaces that whole block, so the `ctaHeading`/`ctaBody` props and `cta` slot are
+only useful if the `cta-panel` slot fallback (or the consumer's own override) still renders them.
 
 ## Summary mode usage
 
@@ -102,6 +132,21 @@ Both slots receive `serviceData` as a scoped prop.
 </ServicesSection>
 ```
 
+## Replacing the whole CTA panel (slot override)
+
+Use `cta-panel` instead of `ctaHeading`/`ctaBody` when the CTA needs a different component
+entirely — not just different text inside `GlassPanel`:
+
+```vue
+<ServicesSection :service-data="service">
+  <template #cta-panel="{ serviceData, ctaHeading, ctaBody }">
+    <MyPromoBanner :heading="ctaHeading" :body="ctaBody">
+      <template #cta><InputButtonCore button-text="Enquire Now" href="/contact" /></template>
+    </MyPromoBanner>
+  </template>
+</ServicesSection>
+```
+
 ## Rendering a list (summary mode)
 
 ```vue
@@ -122,9 +167,12 @@ Both slots receive `serviceData` as a scoped prop.
 
 ## Local style override scaffold
 
-When consuming this component, scaffold a style block using `styleClassPassthrough`. Delete the block if unused.
+When consuming this component, prefer the `--services-section-*` CSS custom properties
+documented in `CONSUMER-STYLING.md` (in the component's own folder) over raw class overrides.
+For anything the tokens don't cover, scaffold a style block using `styleClassPassthrough`.
+Delete the block if unused.
 
-See [component-local-style-override.md](../component-local-style-override.md) for the full pattern.
+See [component-local-style-override.md](../component-local-style-override.md) for the general pattern.
 
 ```vue
 <ServicesSection :style-class-passthrough="['my-section']" :service-data="service">
@@ -138,8 +186,10 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
    ─────────────────────────────────────────────────────────────────── */
 .services-section {
   &.my-section {
-    /* Geometry — image wrapper */
-    /* .image-wrapper { border-radius: 1.2rem; } */
+    --services-section-image-border-radius: 1.2rem;
+
+    /* Deeper overrides target the BEM element classes directly, e.g.: */
+    /* .services-section__faq { } */
   }
 }
 </style>
@@ -150,6 +200,12 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
 - Component is auto-imported in Nuxt — no import needed.
 - The `Service` type is imported from `~/types/types.services`.
 - `summary-link` slot is guarded by `v-if="isSummary"` — it will not render in full mode even if provided.
-- `cta` slot lives inside a `v-if="!isSummary"` `GlassPanel` — it will not render in summary mode.
-- The section gets `aria-labelledby` automatically when `tag` is `"section"` or `"article"`, pointing to the internal heading id.
+- `cta` and `cta-panel` slots live inside `v-if="!isSummary"` — neither renders in summary mode.
+- Internal element classes are BEM-namespaced: `services-section__image-wrapper`,
+  `services-section__info-wrapper`, `services-section__price-duration`,
+  `services-section__decorator`, `services-section__faq`, `services-section__faq-answer`,
+  `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"`, `"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/components/tab-navigation.md

@@ -220,3 +220,52 @@ the component source folder for the full token reference.
   stacking-context constraint.
 - `--tab-nav-panel-bg` should match `--page-bg` for a seamless panel appearance in the collapsed
   state.
+
+## Known issue: SSR/hydration layout shift when the nav needs to collapse (2026-07-07)
+
+**Symptom:** on first page load (hard reload/direct navigation), the header briefly renders taller
+than its settled state, then shrinks — visibly shifting all content below it up. Most noticeable on
+short pages (little content below the fold makes the jump occupy a large fraction of the viewport),
+but the same underlying reflow happens on every page where the nav actually needs to collapse at
+the viewport's width; it's just less visible on long pages or when the timing happens to resolve
+before first paint.
+
+**Root cause:** `useNavCollapse`'s `isLoaded` ref (and therefore `isCollapsed`) can only be
+determined client-side — the server has no way to measure real DOM/viewport widths. So:
+
+```vue
+<ul v-if="!isCollapsed || !isLoaded" ...>
+```
+
+SSR and the very first client paint always render the **full, uncollapsed** `<ul>` (since
+`!isLoaded` is true pre-mount), regardless of whether it will actually fit. Once mounted,
+`checkOverflow()` runs (in `onMounted`, after `nextTick()`), and if the nav overflows, sets
+`isCollapsed = true` — swapping the full list out for the shorter collapsed/burger variant. That
+swap is what shrinks the header and shifts everything below it.
+
+Confirmed via `PerformanceObserver({type: "layout-shift"})` plus DOM `MutationObserver` tracing in a
+consuming app (`luxury-locs-by-natasha-nuxt3`): the class mutation on `.tab-navigation` (adding
+`is-loaded is-animated`) lines up exactly with `.main-content`'s bounding-rect top moving by the
+header's full height delta, at a variable point (roughly 100ms–800ms after first paint depending on
+hydration timing) after first paint.
+
+**Candidate fixes (not yet implemented — pick up later):**
+
+1. **CSS-only collapse instead of JS-measured overflow.** Use a `@container` or `@media` breakpoint
+   to switch between the full nav and the burger button, so the correct variant renders on the very
+   first paint (both server and client agree, no measurement round-trip needed). Loses the
+   "collapse exactly when it overflows, regardless of item count" precision of the current
+   JS-measured approach, gains zero-reflow correctness. Probably the most robust fix if a
+   reasonably conservative breakpoint can be chosen.
+2. **Reserve height instead of eliminating the swap.** Give the header a `min-height` matching the
+   taller (uncollapsed) state so the swap doesn't change the header's box size — trades a visible
+   "jump" for a slightly awkward gap during the pre-collapse window, but never moves content below
+   it. Cheap, but doesn't fix the actual root cause, just its visible symptom.
+3. **Suppress the flash rather than the shift**, e.g. hide the header's nav content entirely
+   (`visibility: hidden` or `opacity: 0`) until `isLoaded` is true, then fade in — avoids showing
+   the "wrong" state at all, but delays when the nav becomes visible/interactive, and would need
+   care to avoid its own CLS/accessibility issues (e.g. focus order, screen readers encountering
+   hidden nav).
+4. Investigate whether a plausible default guess for `isCollapsed` could be derived from something
+   SSR does have access to (e.g. a `Sec-CH-Viewport-Width` client hint header, if the deployment
+   target reliably sends one) — likely not worth the complexity/fragility versus option 1.

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()
@@ -67,7 +67,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── services-card.md        — ServicesCard props (incl. eyebrowConfig/heroConfig), actions slot, CSS tokens, page boilerplate
     ├── services-card-grid.md        — ServicesCardGrid props, config pass-through, CSS tokens, full page boilerplate
     ├── services-section-grid.md     — ServicesSectionGrid props, useAlternateReverse zigzag layout, page boilerplate
-    ├── services-section.md          — ServicesSection props, summary-link/cta slots, summary vs full mode
+    ├── services-section.md          — ServicesSection props (incl. heading/CTA copy), summary-link/cta/cta-panel slots, summary vs full mode
     ├── contact-section.md      — ContactSection props (stepperIndicatorSize pass-through), 3-item info+form layout, slot API
     ├── stepper-list.md         — StepperList dynamic slots (item-{n}/indicator-{n}), props, connector behaviour
     ├── expanding-panel.md      — ExpandingPanel v-model, forceOpened, slots (summary/icon/content), ARIA wiring

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

@@ -4,15 +4,15 @@ exports[`ServicesSectionGrid > renders correct HTML structure 1`] = `
 "<div class="services-grid">
   <div class="services-section">
     <div class="services-section__grid">
-      <div class="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="image" src="/_ipx/_/images/locs-installation.jpg"></div>
-      <div class="info-wrapper is-summary align-center">
+      <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="price-duration">
-          <div class="flex-row"><span class="iconify i-mdi:clock-time-four-outline decorator" aria-hidden="true"></span><span>60 mins</span></div>
-          <div class="flex-row"><span class="iconify i-mdi:currency-gbp decorator" aria-hidden="true"></span><span>£50</span></div>
+        <div class="services-section__price-duration">
+          <div class="flex-row"><span class="iconify i-mdi:clock-time-four-outline services-section__decorator" aria-hidden="true"></span><span>60 mins</span></div>
+          <div class="flex-row"><span class="iconify i-mdi:currency-gbp services-section__decorator" aria-hidden="true"></span><span>£50</span></div>
         </div>
         <!--v-if-->
         <!--v-if-->
@@ -31,15 +31,15 @@ exports[`ServicesSectionGrid > renders correct HTML structure 1`] = `
   </div>
   <div class="services-section">
     <div class="services-section__grid">
-      <div class="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="image" src="/_ipx/_/images/locs-retwist.jpg"></div>
-      <div class="info-wrapper is-summary align-center">
+      <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="price-duration">
-          <div class="flex-row"><span class="iconify i-mdi:clock-time-four-outline decorator" aria-hidden="true"></span><span>60 mins</span></div>
-          <div class="flex-row"><span class="iconify i-mdi:currency-gbp decorator" aria-hidden="true"></span><span>£50</span></div>
+        <div class="services-section__price-duration">
+          <div class="flex-row"><span class="iconify i-mdi:clock-time-four-outline services-section__decorator" aria-hidden="true"></span><span>60 mins</span></div>
+          <div class="flex-row"><span class="iconify i-mdi:currency-gbp services-section__decorator" aria-hidden="true"></span><span>£50</span></div>
         </div>
         <!--v-if-->
         <!--v-if-->
@@ -58,15 +58,15 @@ exports[`ServicesSectionGrid > renders correct HTML structure 1`] = `
   </div>
   <div class="services-section">
     <div class="services-section__grid">
-      <div class="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="image" src="/_ipx/_/images/colour-treatment.jpg"></div>
-      <div class="info-wrapper is-summary align-center">
+      <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="price-duration">
-          <div class="flex-row"><span class="iconify i-mdi:clock-time-four-outline decorator" aria-hidden="true"></span><span>60 mins</span></div>
-          <div class="flex-row"><span class="iconify i-mdi:currency-gbp decorator" aria-hidden="true"></span><span>£50</span></div>
+        <div class="services-section__price-duration">
+          <div class="flex-row"><span class="iconify i-mdi:clock-time-four-outline services-section__decorator" aria-hidden="true"></span><span>60 mins</span></div>
+          <div class="flex-row"><span class="iconify i-mdi:currency-gbp services-section__decorator" aria-hidden="true"></span><span>£50</span></div>
         </div>
         <!--v-if-->
         <!--v-if-->