srcdev-nuxt-components 9.2.0 → 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/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/index.md

@@ -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/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;
+      }
     }
   }
 }

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

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

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

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

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

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

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

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

package/package.json

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