srcdev-nuxt-components 9.1.59 → 9.2.1

package/.claude/settings.json

@@ -57,11 +57,14 @@
       "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)"
+      "WebFetch(domain:luxury-locs-by-natasha-nuxt3.vercel.app)",
+      "Bash(cd /Users/simoncornforth/websites/nuxt-components *)",
+      "Bash(node -e \"JSON.parse\\(require\\('fs'\\).readFileSync\\('/Users/simoncornforth/websites/nuxt-components/.vscode/srcdev-component-banner-video.code-snippets','utf8'\\)\\); console.log\\('valid json'\\)\")"
     ],
     "additionalDirectories": [
       "/Users/simoncornforth/websites/instepreflexology",
-      "/Users/simoncornforth/websites/nuxt-components/.vscode"
+      "/Users/simoncornforth/websites/nuxt-components/.vscode",
+      "/Users/simoncornforth/websites/nuxt-components/.claude/skills/components"
     ]
   }
 }

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/banner-video.md

@@ -1,6 +1,6 @@
 ---
 name: BannerVideo
-description: BannerVideo full-width hero video banner — props, depth tier system, verticalPosition/horizontalPosition, reduced-motion fallback, CSS tokens, consumer styling
+description: BannerVideo full-width hero video banner — props, depth tier system, verticalPosition/horizontalPosition, playIcon/pauseIcon/toggle-icon slot, reduced-motion fallback, CSS tokens, consumer styling
 type: reference
 ---
 
@@ -8,9 +8,9 @@ type: reference
 
 ## Overview
 
-`BannerVideo` renders a full-width banner section that plays a muted, looping mp4 video. A poster image is shown as fallback when the user has `prefers-reduced-motion: reduce` set — handled entirely in CSS, no JS.
+`BannerVideo` renders a full-width banner section that plays a muted, looping mp4 video. A poster image is shown as fallback when the user has `prefers-reduced-motion: reduce` set — handled entirely in CSS, no JS. A visible pause/play toggle is always rendered over the video (see "Pause/play toggle" below) to satisfy WCAG 2.2.2 (Pause, Stop, Hide), since the video autoplays and loops indefinitely.
 
-The banner is sized via `aspect-ratio` so it scales naturally. The `depth` prop selects a responsive `max-height` tier (`xs` → `xl`) implemented with `clamp()` — no breakpoint props needed. Each tier exposes a `--theme-banner-video-max-height-{depth}` CSS token that consuming pages can override.
+The banner is sized via `aspect-ratio` so it scales naturally. The `depth` prop selects a responsive `max-height` tier (`xs` → `xl`) implemented with `clamp()` — no breakpoint props needed. Each tier exposes a `--banner-video-max-height-{depth}` CSS token that consuming pages can override.
 
 ### Autoplay mechanism
 
@@ -26,13 +26,21 @@ The video uses `autoplay muted loop playsinline preload="auto"` attributes on th
 | `imgWidth` | `number` | `1920` | Intrinsic width of the poster image — required for NuxtImg/IPX optimisation. |
 | `imgHeight` | `number` | `1080` | Intrinsic height of the poster image — required for NuxtImg/IPX optimisation. |
 | `tag` | `"section" \| "div" \| "header" \| "main" \| "article"` | `"section"` | HTML element rendered as the root. |
-| `depth` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Responsive max-height tier. Each maps to a `clamp()` scale; override via `--theme-banner-video-max-height-{depth}`. |
+| `depth` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Responsive max-height tier. Each maps to a `clamp()` scale; override via `--banner-video-max-height-{depth}`. |
 | `aspectRatio` | `string` | `"21/9"` | CSS `aspect-ratio` of the container (e.g. `"16/9"`, `"21/9"`, `"4/3"`). |
 | `objectFit` | `"cover" \| "contain" \| "fill" \| "none" \| "scale-down"` | `"cover"` | How the video and fallback image fill the banner frame. |
 | `verticalPosition` | `"start" \| "center" \| "end"` | `"center"` | Vertical crop position. Maps to `align-self` on the video element and `object-position` Y on the fallback image. |
 | `horizontalPosition` | `"start" \| "center" \| "end"` | `"center"` | Horizontal crop position. Maps to `object-position` X on the fallback image. |
+| `playIcon` | `string` | `"mdi:play"` | Iconify icon name shown on the toggle button before playback starts. |
+| `pauseIcon` | `string` | `"mdi:pause"` | Iconify icon name shown on the toggle button once playback starts. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
 
+## Slots
+
+| Slot | Slot props | Purpose |
+|---|---|---|
+| `toggle-icon` | `{ isPlaying: boolean }` | Replaces the toggle button's icon entirely. Default renders `<Icon :name="isPlaying ? pauseIcon : playIcon" />` — use this slot instead of `playIcon`/`pauseIcon` when an Iconify name isn't enough (custom SVG, different icon set). |
+
 ## Basic usage
 
 ```vue
@@ -87,6 +95,20 @@ The video uses `autoplay muted loop playsinline preload="auto"` attributes on th
 />
 ```
 
+### Custom toggle icon
+
+```vue
+<!-- Swap the Iconify icon name -->
+<BannerVideo src="…" poster="…" play-icon="mdi:play-circle" pause-icon="mdi:pause-circle" />
+
+<!-- Replace the icon entirely (custom SVG, different icon set) -->
+<BannerVideo src="…" poster="…">
+  <template #toggle-icon="{ isPlaying }">
+    <MyCustomIcon :name="isPlaying ? 'pause' : 'play'" />
+  </template>
+</BannerVideo>
+```
+
 ## Positioning explained
 
 The video element uses `height: auto; min-height: 100%` so it overflows the container naturally when aspect ratios differ. `overflow: hidden` on the root clips it. `verticalPosition` maps to `align-self` on the video (shifting which portion of the overflow is visible) and to `object-position` Y on the fallback image.
@@ -135,20 +157,55 @@ Inline style tokens (set from props):
 
 | depth | token | clamp value |
 |---|---|---|
-| `xs` | `--theme-banner-video-max-height-xs` | `clamp(12rem, 15vw, 24rem)` |
-| `sm` | `--theme-banner-video-max-height-sm` | `clamp(18rem, 22vw, 36rem)` |
-| `md` | `--theme-banner-video-max-height-md` | `clamp(28rem, 38vw, 56rem)` |
-| `lg` | `--theme-banner-video-max-height-lg` | `clamp(40rem, 52vw, 72rem)` |
-| `xl` | `--theme-banner-video-max-height-xl` | `clamp(52rem, 65vw, 90rem)` |
+| `xs` | `--banner-video-max-height-xs` | `clamp(12rem, 15vw, 24rem)` |
+| `sm` | `--banner-video-max-height-sm` | `clamp(18rem, 22vw, 36rem)` |
+| `md` | `--banner-video-max-height-md` | `clamp(28rem, 38vw, 56rem)` |
+| `lg` | `--banner-video-max-height-lg` | `clamp(40rem, 52vw, 72rem)` |
+| `xl` | `--banner-video-max-height-xl` | `clamp(52rem, 65vw, 90rem)` |
 
 **Override a tier in a consuming page:**
 
 ```css
 .my-page {
-  --theme-banner-video-max-height-md: clamp(32rem, 45vw, 64rem);
+  --banner-video-max-height-md: clamp(32rem, 45vw, 64rem);
 }
 ```
 
+### Toggle button token defaults
+
+| 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 |
+
+Full details, plus global/page-scoped/per-instance override patterns, live in the
+component's own `CONSUMER-STYLING.md`.
+
+## Pause/play toggle
+
+A `<button class="banner-video__toggle">` is always rendered in the bottom-right corner of the
+banner, overlaying the video. It calls `videoEl.pause()` / `.play()` directly and its
+`aria-label` reflects actual playback state ("Pause background video" / "Play background video"),
+tracked via the video's native `play`/`pause` events rather than assumed — autoplay can be
+blocked by the browser, so the label starts as "Play background video" until a `play` event
+actually fires.
+
+This exists to satisfy **WCAG 2.2.2 (Pause, Stop, Hide)**: content that autoplays and lasts more
+than 5 seconds needs an on-page mechanism to pause it. The `prefers-reduced-motion` fallback only
+covers users who have set that OS-level preference — everyone else still needs a way to stop the
+loop, which is why the toggle is unconditional, not opt-in via a prop.
+
+The toggle is hidden under `prefers-reduced-motion: reduce` (alongside the `<video>` itself,
+since the fallback image is already static and has nothing to pause).
+
+No captions/transcript are needed for this component's use case (silent, decorative ambient
+background video) — if a consumer ever uses `BannerVideo` for a video that conveys information,
+that content needs its own accessible alternative (transcript, captions) handled outside this
+component, since `BannerVideo` has no slot for it.
+
 ## CSS classes
 
 | Class | Applied when |
@@ -156,6 +213,7 @@ Inline style tokens (set from props):
 | `.banner-video` | Always — the root element |
 | `.video` | The `<video>` element |
 | `.fallback` | The `<NuxtImg>` fallback — hidden by default, shown via `prefers-reduced-motion` CSS |
+| `.banner-video__toggle` | The pause/play button — always rendered except under `prefers-reduced-motion: reduce` |
 
 ## Consumer styling
 
@@ -164,12 +222,19 @@ Use an unscoped style block scoped by a page or section wrapper class. No `:deep
 ```vue
 <style>
 .my-page {
-  /* Override the md tier's clamp range for this page */
-  --theme-banner-video-max-height-md: clamp(32rem, 45vw, 64rem);
+  .banner-video {
+    /* Override the md tier's clamp range and the toggle's colours for this page */
+    --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);
+  }
 }
 </style>
 ```
 
+See the component's `CONSUMER-STYLING.md` for the full token API and global/page-scoped/
+per-instance override patterns.
+
 ## Gotcha: aspect-ratio is overridden by max-height at wide viewports
 
 `max-height` from the depth tier silently wins over `aspect-ratio` once the viewport is wide enough. For example, at `depth="md"` the max-height clamp caps at `56rem` — so changing `aspectRatio` from `"21/9"` to `"1/1"` produces no visible change on a wide desktop because `max-height` is the binding constraint.
@@ -178,11 +243,11 @@ Use an unscoped style block scoped by a page or section wrapper class. No `:deep
 
 ```css
 .my-page {
-  --theme-banner-video-max-height-xs: 80rem;
-  --theme-banner-video-max-height-sm: 80rem;
-  --theme-banner-video-max-height-md: 80rem;
-  --theme-banner-video-max-height-lg: 80rem;
-  --theme-banner-video-max-height-xl: 80rem;
+  --banner-video-max-height-xs: 80rem;
+  --banner-video-max-height-sm: 80rem;
+  --banner-video-max-height-md: 80rem;
+  --banner-video-max-height-lg: 80rem;
+  --banner-video-max-height-xl: 80rem;
 }
 ```
 
@@ -190,11 +255,11 @@ Or via inline `:style` on the parent element (useful for dev QA exploration):
 
 ```vue
 <div :style="{
-  '--theme-banner-video-max-height-xs': '80rem',
-  '--theme-banner-video-max-height-sm': '80rem',
-  '--theme-banner-video-max-height-md': '80rem',
-  '--theme-banner-video-max-height-lg': '80rem',
-  '--theme-banner-video-max-height-xl': '80rem',
+  '--banner-video-max-height-xs': '80rem',
+  '--banner-video-max-height-sm': '80rem',
+  '--banner-video-max-height-md': '80rem',
+  '--banner-video-max-height-lg': '80rem',
+  '--banner-video-max-height-xl': '80rem',
 }">
   <BannerVideo aspect-ratio="1/1" depth="lg" ... />
 </div>
@@ -205,6 +270,6 @@ You must override **all five tier tokens** — overriding only the active depth
 ## Notes
 
 - `loading="eager"` and `decoding="async"` are hardcoded on the fallback `NuxtImg` — it is above the fold by definition.
-- The video has `autoplay muted loop playsinline preload="auto"` — intentional and not configurable. This component is for ambient background video only, not user-controlled media.
+- The video has `autoplay muted loop playsinline preload="auto"` — intentional and not configurable. This component is for ambient background video only, not a media player — the pause/play toggle exists purely for WCAG 2.2.2 compliance, not as a general playback UI (no seek bar, volume, etc.).
 - `prefers-reduced-motion` is handled in CSS (`.video { display: none }` + `.fallback { display: block }`), not via JS.
 - Storybook: the `"none"` image provider is active, so `poster` paths pass through unchanged. Always provide explicit `img-width` and `img-height` to avoid the `w=1536` fallback in deployed Storybook.

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()
@@ -74,7 +74,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── glass-panel.md          — GlassPanel props, slots, CSS token API (--glass-panel-bg/border-color/shadow/highlight), theming override
     ├── navigation-horizontal.md — NavigationHorizontal props, NavItemData type, CSS token API, import path gotcha
     ├── input-copy-core.md      — InputCopyCore: readonly copy-to-clipboard input; props, emits, slots, CSS classes, usage
-    ├── banner-video.md         — BannerVideo: full-width hero video banner, depth tier system, objectFit/objectPosition, reduced-motion fallback, CSS tokens
+    ├── banner-video.md         — BannerVideo: full-width hero video banner, depth tier system, objectFit/objectPosition, playIcon/pauseIcon/toggle-icon slot, reduced-motion fallback, CSS tokens
     ├── grid-stack.md           — GridStack: CSS Grid z-axis stacking, slot API, z-order rules, sizing, video+overlay and image+text patterns
     ├── scroll-reveal-frame.md  — ScrollRevealFrame: generic parallax clipping frame, slot API, image grid pattern, CSS tokens, browser support
     ├── scroll-reveal-image.md  — ScrollRevealImage: single-image parallax reveal, focalX, imgWidth/imgHeight, responsive frame height

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/banner-video/BannerVideo.vue

@@ -24,6 +24,8 @@
       :style="{ objectFit: props.objectFit }"
       @loadeddata="handleLoadedData"
       @canplay="handleCanPlay"
+      @play="isPlaying = true"
+      @pause="isPlaying = false"
     >
       <source :src="src" type="video/mp4" />
     </video>
@@ -38,40 +40,34 @@
       decoding="async"
       :style="{ objectFit: props.objectFit, objectPosition: imgObjectPosition }"
     />
+    <button
+      type="button"
+      class="banner-video__toggle"
+      :aria-label="isPlaying ? 'Pause background video' : 'Play background video'"
+      @click="togglePlayback"
+    >
+      <slot name="toggle-icon" :is-playing="isPlaying">
+        <Icon :name="isPlaying ? pauseIcon : playIcon" aria-hidden="true" />
+      </slot>
+    </button>
   </component>
 </template>
 
 <script setup lang="ts">
 interface Props {
-  /** HTML element to render as the root. Defaults to `section` for landmark semantics. */
   tag?: "section" | "div" | "header" | "main" | "article";
-  /** Path to the video source file (mp4). */
   src: string;
-  /** Path to the fallback/poster image. Used as video poster and as the visible fallback
-   *  when the video cannot play or when the user prefers reduced motion. */
   poster: string;
   alt?: string;
-  /** Intrinsic width of the poster image — required for NuxtImg optimisation. */
   imgWidth?: number;
-  /** Intrinsic height of the poster image — required for NuxtImg optimisation. */
   imgHeight?: number;
-  /**
-   * Depth tier controlling the responsive max-height via a `clamp()` scale.
-   * Each tier maps to a `--theme-banner-video-max-height-{depth}` CSS token that
-   * consuming pages can override. Defaults to `"md"`.
-   */
   depth?: "xs" | "sm" | "md" | "lg" | "xl";
-  /**
-   * CSS aspect-ratio of the banner container (e.g. `"16/9"`, `"21/9"`, `"4/3"`).
-   * Provides the intrinsic height that `max-height` caps at larger viewport widths.
-   */
   aspectRatio?: string;
-  /** How the video and fallback image fill the banner frame. Defaults to `"cover"`. */
   objectFit?: "cover" | "contain" | "fill" | "none" | "scale-down";
-  /** Vertical crop position within the banner. Maps to `align-self` on the video and `object-position` on the fallback image. Defaults to `"center"`. */
   verticalPosition?: "start" | "center" | "end";
-  /** Horizontal crop position within the banner. Maps to `object-position` on the fallback image. Defaults to `"center"`. */
   horizontalPosition?: "start" | "center" | "end";
+  playIcon?: string;
+  pauseIcon?: string;
   styleClassPassthrough?: string | string[];
 }
 
@@ -85,6 +81,8 @@ const props = withDefaults(defineProps<Props>(), {
   objectFit: "cover",
   verticalPosition: "center",
   horizontalPosition: "center",
+  playIcon: "mdi:play",
+  pauseIcon: "mdi:pause",
   styleClassPassthrough: () => [],
 });
 
@@ -106,12 +104,22 @@ watch(
 );
 
 const videoEl = shallowRef<HTMLVideoElement | null>(null);
+const isPlaying = ref(false);
+
+const togglePlayback = () => {
+  const v = videoEl.value;
+  if (!v) return;
+  if (v.paused) {
+    void v.play();
+  } else {
+    v.pause();
+  }
+};
 
 const tryPlay = async () => {
   const v = videoEl.value;
   if (!v) return;
   try {
-    // Ensure muted stays true — required for programmatic autoplay in all browsers
     v.muted = true;
     await v.play();
   } catch {
@@ -123,9 +131,7 @@ const kickOffLoad = async () => {
   await nextTick();
   const v = videoEl.value;
   if (!v) return;
-  // Force the media element to (re)read its source child and begin fetching
   v.load();
-  // Attempt immediate play; loadeddata/canplay handlers will retry once data arrives
   void tryPlay();
 };
 
@@ -136,7 +142,6 @@ const handleCanPlay = () => {
   void tryPlay();
 };
 
-// Runs on mount AND whenever src changes (covers route-change re-use edge cases)
 watch(
   () => props.src,
   () => {
@@ -145,7 +150,6 @@ watch(
   { immediate: true, flush: "post" }
 );
 
-// Extra safety: when the component becomes active again (e.g. returning via keep-alive)
 onActivated(() => {
   void kickOffLoad();
 });
@@ -154,7 +158,7 @@ onActivated(() => {
 <style lang="css">
 @layer components {
   .banner-video {
-    --_max-height: var(--theme-banner-video-max-height, clamp(28rem, 38vw, 56rem));
+    --_max-height: var(--banner-video-max-height, clamp(28rem, 38vw, 56rem));
 
     display: grid;
     grid-template-areas: "media";
@@ -164,19 +168,19 @@ onActivated(() => {
     overflow: hidden;
 
     &[data-depth="xs"] {
-      --_max-height: var(--theme-banner-video-max-height-xs, clamp(12rem, 15vw, 24rem));
+      --_max-height: var(--banner-video-max-height-xs, clamp(12rem, 15vw, 24rem));
     }
     &[data-depth="sm"] {
-      --_max-height: var(--theme-banner-video-max-height-sm, clamp(18rem, 22vw, 36rem));
+      --_max-height: var(--banner-video-max-height-sm, clamp(18rem, 22vw, 36rem));
     }
     &[data-depth="md"] {
-      --_max-height: var(--theme-banner-video-max-height-md, clamp(28rem, 38vw, 56rem));
+      --_max-height: var(--banner-video-max-height-md, clamp(28rem, 38vw, 56rem));
     }
     &[data-depth="lg"] {
-      --_max-height: var(--theme-banner-video-max-height-lg, clamp(40rem, 52vw, 72rem));
+      --_max-height: var(--banner-video-max-height-lg, clamp(40rem, 52vw, 72rem));
     }
     &[data-depth="xl"] {
-      --_max-height: var(--theme-banner-video-max-height-xl, clamp(52rem, 65vw, 90rem));
+      --_max-height: var(--banner-video-max-height-xl, clamp(52rem, 65vw, 90rem));
     }
 
     .video {
@@ -196,6 +200,32 @@ onActivated(() => {
       height: 100%;
     }
 
+    .banner-video__toggle {
+      grid-area: media;
+      align-self: end;
+      justify-self: end;
+      margin: var(--banner-video-toggle-offset, 1.2rem);
+      z-index: 1;
+
+      display: grid;
+      place-items: center;
+      width: var(--banner-video-toggle-size, 3.2rem);
+      height: var(--banner-video-toggle-size, 3.2rem);
+      padding: 0;
+
+      background-color: var(--banner-video-toggle-background, oklch(0% 0 0 / 0.4));
+      color: var(--banner-video-toggle-icon-color, white);
+      border: none;
+      border-radius: 100vw;
+      cursor: pointer;
+      transition: background-color 0.2s ease;
+
+      &:hover,
+      &:focus-visible {
+        background-color: var(--banner-video-toggle-background-hover, oklch(0% 0 0 / 0.6));
+      }
+    }
+
     @media (prefers-reduced-motion: reduce) {
       .video {
         display: none;
@@ -203,6 +233,9 @@ onActivated(() => {
       .fallback {
         display: block;
       }
+      .banner-video__toggle {
+        display: none;
+      }
     }
   }
 }