srcdev-nuxt-components 9.6.18 → 9.6.20

package/.claude/skills/storybook-add-story.md

@@ -313,6 +313,39 @@ prop and try to pass it. Make it unmistakable:
 
 `PriceList.stories.ts` and `GoogleReviews.stories.ts` (line-clamp controls) follow this.
 
+## Where shared story helpers can live
+
+Nowhere shared, so far. Stories ship in the package (`app/` is in `package.json` `files`) but
+`.storybook/` doesn't, so a story importing from `.storybook/` breaks in a consumer's type-check;
+and any `.ts` under `app/components/` is registered as a component (`pathPrefix: false` scan).
+Repeat small fixtures per story instead (the grid `StressTest` stories, 2026-10-21, each carry their
+own oversized-content block).
+
+## Simulating hardware or library events in a stress story
+
+When a component's data only arrives from hardware or a third-party child (a camera, a file
+decoder), a story can't feed it worst-case data through props. Add story-only buttons that call the
+component's own handlers through its internal instance, and say so in the story text:
+
+```ts
+const cmpRef = ref<ComponentPublicInstance | null>(null);
+const internals = () =>
+  (cmpRef.value?.$ as unknown as { setupState: { onDetect: (codes: { rawValue: string }[]) => void } } | undefined)
+    ?.setupState;
+```
+
+`setupState` is internal (not on the public type, hence the cast) but present in every build.
+Don't `defineExpose` handlers just for a story. `CaptureQrCode` and `DecodeQrCode` (2026-10-21)
+follow this.
+
+## Dynamic slot names in template strings
+
+A dynamic slot argument can't contain spaces: `` #[`item-${i + 6}-summary`] `` is cut at the first space
+(HTML attribute names end there) and the story fails with "Missing } in template expression". It
+only shows when Storybook renders the story, since the template is a string. Write the expression
+without spaces (`` #[`item-${i}-summary`] ``), or build the names in `setup()` and bind them:
+`#[item.summarySlot]` (AccordionChat's StressTest, 2026-10-20).
+
 ## Docs page
 
 `.storybook/preview.ts` sets `tags: ["autodocs"]` globally (2026-10-14), so every story file gets a

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

@@ -346,6 +346,32 @@ be resolved from the ends and never reaches it. Mount with two items sharing the
 then `setProps` with the first and last items swapped, and assert the rendered labels in order
 (`SkipLinks.spec.ts`). With an `href`-only key that test rendered five links instead of four.
 
+## Stub third-party children that hold shared state
+
+When a component renders a library child whose behaviour the spec doesn't need (the spec drives
+the parent's own handlers), stub the child in the mount helper. Unmounting doesn't isolate a
+library that keeps module-level state: `QrcodeStream` queues every camera start/stop on one shared
+promise chain, so a start left from an earlier test failed mid-test and emitted `error` into the
+next `CaptureQrCode`, but only under full-suite load and only with `SRCDEV_STANDALONE=true`
+(2026-10-21).
+
+```typescript
+const qrcodeStreamStub = { name: "QrcodeStream", emits: ["detect", "error"], template: `<div class="qrcode-stream-stub"></div>` };
+
+const mountCapture = async (options: CaptureMountOptions = {}) => {
+  const wrapper = await mountSuspended(CaptureQrCode, {
+    ...options,
+    global: { ...options?.global, stubs: { QrcodeStream: qrcodeStreamStub, ...options?.global?.stubs } },
+  });
+  mounted.push(wrapper);
+  return wrapper;
+};
+```
+
+Assert against the stub's class, not the component's tag name (see
+`.claude/rules/test-no-vacuous-assertions.md`). Run the spec with `npm run test:run` so
+standalone-only modules load.
+
 ## Mocking browser APIs
 
 ### Global constructors (ResizeObserver, IntersectionObserver, etc.)

package/.claude/skills/using-component-skills.md

@@ -47,7 +47,7 @@ Component skills land in `.claude/skills/srcdev-nuxt-components/components/`:
 │           ├── pricing-card.md         — SaaS pricing plan card
 │           ├── input-copy.md           — copy-to-clipboard input
 │           ├── expanding-panel.md      — single expand/collapse panel
-│           ├── accordian-core.md       — native accordion (grouped panels)
+│           ├── accordion-group.md      — native accordion (grouped panels)
 │           ├── display-avatar.md       — circular avatar component
 │           ├── card-core.md            — generic card container
 │           ├── auto-grid.md            — responsive auto-fit grid

package/.vscode/srcdev-component-accordion-chat.code-snippets

@@ -0,0 +1,42 @@
+{
+  "SRCDEV AccordionChat": {
+    "description": "AccordionChat: questions as right-hand bubbles, answers as left-hand bubbles with an avatar",
+    "scope": "vue,html",
+    "body": [
+      "<AccordionChat name=\"${1:faq}\" avatar-label=\"${2:AM}\">",
+      "  <template #item-0-summary>${3:Question one?}</template>",
+      "  <template #item-0-content><p>${4:Answer one.}</p></template>",
+      "",
+      "  <template #item-1-summary>${5:Question two?}</template>",
+      "  <template #item-1-content><p>${6:Answer two.}</p></template>",
+      "</AccordionChat>"
+    ]
+  },
+  "SRCDEV AccordionChat Looped": {
+    "description": "AccordionChat driven by an array via dynamic item-{n} slot names",
+    "scope": "vue,html",
+    "body": [
+      "<AccordionChat name=\"${1:faq}\" avatar-label=\"${2:AM}\">",
+      "  <template v-for=\"(item, i) in ${3:items}\" :key=\"`s\\${i}`\" #[`item-\\${i}-summary`]>{{ item.${4:question} }}</template>",
+      "  <template v-for=\"(item, i) in ${3:items}\" :key=\"`c\\${i}`\" #[`item-\\${i}-content`]><p>{{ item.${5:answer} }}</p></template>",
+      "</AccordionChat>"
+    ]
+  },
+  "SRCDEV AccordionChat CSS Override": {
+    "description": "AccordionChat colour and type tokens scoped to a page or section class",
+    "scope": "css",
+    "body": [
+      ".${1:faq-section} {",
+      "  --accordion-chat-question-surface: ${2:#ececec};",
+      "  --accordion-chat-question-colour: ${3:#1d1d1f};",
+      "  --accordion-chat-question-surface-open: ${4:#1d1d1f};",
+      "  --accordion-chat-question-colour-open: ${5:#ffffff};",
+      "  --accordion-chat-answer-surface: ${6:#ffffff};",
+      "  --accordion-chat-answer-border: ${7:#e6e4e1};",
+      "  --accordion-chat-answer-colour: ${8:#2a2a2c};",
+      "  --accordion-chat-avatar-surface: ${9:#1d1d1f};",
+      "  --accordion-chat-avatar-colour: ${10:#ffffff};",
+      "}"
+    ]
+  }
+}

package/.vscode/srcdev-component-accordion-group.code-snippets

@@ -0,0 +1,38 @@
+{
+  "SRCDEV AccordionGroup": {
+    "description": "AccordionGroup with item-{n}-summary/content slots; a shared name makes it exclusive-open",
+    "scope": "vue,html",
+    "body": [
+      "<AccordionGroup name=\"${1:faq}\">",
+      "  <template #item-0-summary>${2:Question one?}</template>",
+      "  <template #item-0-content><p>${3:Answer one.}</p></template>",
+      "",
+      "  <template #item-1-summary>${4:Question two?}</template>",
+      "  <template #item-1-content><p>${5:Answer two.}</p></template>",
+      "</AccordionGroup>"
+    ]
+  },
+  "SRCDEV AccordionGroup Looped": {
+    "description": "AccordionGroup driven by an array via dynamic item-{n} slot names",
+    "scope": "vue,html",
+    "body": [
+      "<AccordionGroup name=\"${1:faq}\">",
+      "  <template v-for=\"(item, i) in ${2:items}\" :key=\"`s\\${i}`\" #[`item-\\${i}-summary`]>{{ item.${3:question} }}</template>",
+      "  <template v-for=\"(item, i) in ${2:items}\" :key=\"`c\\${i}`\" #[`item-\\${i}-content`]><p>{{ item.${4:answer} }}</p></template>",
+      "</AccordionGroup>"
+    ]
+  },
+  "SRCDEV AccordionGroup CSS Override": {
+    "description": "AccordionGroup width and panel divider overrides scoped to a page or section class",
+    "scope": "css",
+    "body": [
+      ".${1:faq-section} {",
+      "  --accordion-group-max-width: ${2:72rem};",
+      "",
+      "  .accordion-group-item:not(:last-child) {",
+      "    border-block-end: 0.1rem solid ${3:var(--theme-border)};",
+      "  }",
+      "}"
+    ]
+  }
+}

package/.vscode/srcdev-component-action-menu.code-snippets

@@ -20,8 +20,8 @@
     "scope": "vue,html",
     "body": [
       "<ActionMenu>",
-      "  <template v-for=\"($1action, $2i) in $3actions\" :key=\"$1action.label\" #[`item-${$2i}`]>",
-      "    <ActionMenuItem :label=\"$1action.label\" :href=\"$1action.href\" @click=\"$1action.onClick\" />",
+      "  <template v-for=\"(action, i) in ${1:actions}\" :key=\"`\\${i}-\\${action.label}`\" #[`item-\\${i}`]>",
+      "    <ActionMenuItem :label=\"action.label\" :href=\"action.href\" @click=\"action.onClick\" />",
       "  </template>",
       "</ActionMenu>"
     ]
@@ -30,7 +30,7 @@
     "description": "CSS override scaffold for ActionMenu tokens",
     "scope": "css",
     "body": [
-      ".$1my-page {",
+      ".${1:my-page} {",
       "  --action-menu-trigger-icon-color: $2;",
       "  --action-menu-popover-background: $3;",
       "  --action-menu-popover-border: $4;",

package/.vscode/srcdev-component-capture-decode-qr-code.code-snippets

@@ -3,7 +3,11 @@
     "description": "CaptureQrCode live camera scanner with localisable copy",
     "scope": "vue,html",
     "body": [
-      "<CaptureQrCode camera-stopped-label=\"${1:Camera stopped}\" reset-camera-label=\"${2:Reset camera}\" />"
+      "<CaptureQrCode",
+      "  camera-stopped-label=\"${1:Camera stopped}\"",
+      "  reset-camera-label=\"${2:Reset camera}\"",
+      "  :error-messages=\"{ NotAllowedError: '${3:Camera access was blocked.}', default: '${4:The camera could not be started.}' }\"",
+      "/>"
     ]
   },
   "SRCDEV CaptureQrCode Custom Error": {
@@ -22,7 +26,12 @@
     "description": "DecodeQrCode image upload / drop decoder",
     "scope": "vue,html",
     "body": [
-      "<DecodeQrCode upload-label=\"${1:Upload a QR code image}\" drop-label=\"${2:Or drop a QR code image here}\" />"
+      "<DecodeQrCode",
+      "  upload-label=\"${1:Upload a QR code image}\"",
+      "  drop-label=\"${2:Or drop a QR code image here}\"",
+      "  no-result-label=\"${3:No QR code was found in that image.}\"",
+      "  read-error-label=\"${4:That file couldn't be read as an image.}\"",
+      "/>"
     ]
   }
 }

package/.vscode/srcdev-component-carousel-flip.code-snippets

@@ -3,7 +3,7 @@
     "description": "CarouselFlip with looped item slots",
     "scope": "vue,html",
     "body": [
-      "<CarouselFlip :carousel-data-ids=\"$1items.map((item) => item.id)\">",
+      "<CarouselFlip :carousel-data-ids=\"$1items.map((item) => item.id)\" aria-label=\"${4:Image carousel}\">",
       "  <template v-for=\"$2item in $1items\" :key=\"$2item.id\" #[$2item.id]>",
       "    $3",
       "  </template>",
@@ -25,15 +25,33 @@
       "</CarouselFlip>"
     ]
   },
+  "SRCDEV CarouselFlip Track Edges": {
+    "description": "CarouselFlip with prev/next overlaid on the ends of the visible track",
+    "scope": "vue,html",
+    "body": [
+      "<CarouselFlip",
+      "  :carousel-data-ids=\"$1items.map((item) => item.id)\"",
+      "  button-layout=\"track-edges\"",
+      "  :allow-carousel-overflow=\"true\"",
+      ">",
+      "  <template v-for=\"$2item in $1items\" :key=\"$2item.id\" #[$2item.id]>",
+      "    $3",
+      "  </template>",
+      "</CarouselFlip>"
+    ]
+  },
   "SRCDEV CarouselFlip CSS Override": {
     "description": "CSS override scaffold for CarouselFlip tokens",
     "scope": "css",
     "body": [
       ".$1my-page {",
       "  .carousel-flip {",
-      "    --carousel-flip-gap: $2;",
-      "    --carousel-flip-marker-active-colour: $3;",
-      "    --carousel-flip-button-background-colour: $4;",
+      "    --carousel-flip-gap: ${2:1rem};",
+      "    --carousel-flip-marker-active-colour: ${3:var(--theme-surface)};",
+      "    --carousel-flip-button-background-colour: ${4:var(--theme-surface-subtle)};",
+      "    --carousel-flip-button-icon-colour: ${5:var(--theme-text)};",
+      "    --carousel-flip-button-align: ${6:center};",
+      "    --carousel-flip-button-inline-offset: ${7:0px};",
       "  }",
       "}"
     ]

package/.vscode/srcdev-component-deep-expanding-menu-classic.code-snippets

@@ -1,9 +1,39 @@
 {
   "SRCDEV DeepExpandingMenuClassic Basic": {
-    "description": "DeepExpandingMenuClassic — <details>-based fallback nav",
+    "description": "DeepExpandingMenuClassic — <details>-based nav",
     "scope": "vue,html",
+    "prefix": "srcdev-deep-expanding-menu-classic",
     "body": [
-      "<DeepExpandingMenuClassic :nav-links=\"$1navLinks\" />"
+      "<DeepExpandingMenuClassic :nav-links=\"${1:navLinks}\" aria-label=\"${2:Main}\" />"
+    ]
+  },
+  "SRCDEV DeepExpandingMenuClassic Nav Links": {
+    "description": "DeepExpandingMenuClassic — navLinks data (ResponsiveHeaderNavItem[])",
+    "scope": "typescript,vue",
+    "prefix": "srcdev-deep-expanding-menu-classic-links",
+    "body": [
+      "const ${1:navLinks}: ResponsiveHeaderNavItem[] = [",
+      "  { name: \"${2:Home}\", path: \"${3:/}\" },",
+      "  {",
+      "    name: \"${4:Services}\",",
+      "    childLinksTitle: \"${5:Our services}\",",
+      "    childLinks: [",
+      "      { name: \"${6:Haircuts}\", path: \"${7:/services/haircuts}\" },",
+      "    ],",
+      "  },",
+      "];"
+    ]
+  },
+  "SRCDEV DeepExpandingMenuClassic Style Override": {
+    "description": "DeepExpandingMenuClassic — unlayered token override scaffold",
+    "scope": "css,vue",
+    "prefix": "srcdev-deep-expanding-menu-classic-css",
+    "body": [
+      ".${1:site-nav} {",
+      "  --deep-expanding-menu-classic-item-gap: ${2:2.4rem};",
+      "  --deep-expanding-menu-classic-panel-background-colour: ${3:var(--theme-surface-subtle)};",
+      "  --deep-expanding-menu-classic-panel-heading-line-clamp: ${4:none};",
+      "}"
     ]
   }
 }

package/.vscode/srcdev-component-deep-expanding-menu.code-snippets

@@ -2,8 +2,38 @@
   "SRCDEV DeepExpandingMenu Basic": {
     "description": "DeepExpandingMenu — anchor-positioned popover nav panels",
     "scope": "vue,html",
+    "prefix": "srcdev-deep-expanding-menu",
     "body": [
-      "<DeepExpandingMenu :nav-links=\"$1navLinks\" />"
+      "<DeepExpandingMenu :nav-links=\"${1:navLinks}\" aria-label=\"${2:Main}\" />"
+    ]
+  },
+  "SRCDEV DeepExpandingMenu Nav Links": {
+    "description": "DeepExpandingMenu — navLinks data (ResponsiveHeaderNavItem[])",
+    "scope": "typescript,vue",
+    "prefix": "srcdev-deep-expanding-menu-links",
+    "body": [
+      "const ${1:navLinks}: ResponsiveHeaderNavItem[] = [",
+      "  { name: \"${2:Home}\", path: \"${3:/}\" },",
+      "  {",
+      "    name: \"${4:Services}\",",
+      "    childLinksTitle: \"${5:Our services}\",",
+      "    childLinks: [",
+      "      { name: \"${6:Haircuts}\", path: \"${7:/services/haircuts}\" },",
+      "    ],",
+      "  },",
+      "];"
+    ]
+  },
+  "SRCDEV DeepExpandingMenu Style Override": {
+    "description": "DeepExpandingMenu — unlayered token override scaffold",
+    "scope": "css,vue",
+    "prefix": "srcdev-deep-expanding-menu-css",
+    "body": [
+      ".${1:site-nav} {",
+      "  --deep-expanding-menu-gap: ${2:2.4rem};",
+      "  --deep-expanding-menu-panel-background-colour: ${3:var(--theme-surface-subtle)};",
+      "  --deep-expanding-menu-panel-heading-line-clamp: ${4:none};",
+      "}"
     ]
   }
 }

package/.vscode/srcdev-component-samaritan-prompt.code-snippets

@@ -48,13 +48,14 @@
     ]
   },
   "SRCDEV SamaritanPrompt Tokens": {
-    "description": "SamaritanPrompt / SamaritanPromptMixed CSS token overrides",
+    "description": "SamaritanPrompt / SamaritanPromptMixed CSS token overrides (classic white-on-black look)",
     "scope": "css,vue",
     "body": [
       "--samaritan-prompt-font-size: ${1:2rem};",
-      "--samaritan-prompt-text-colour: ${2:var(--theme-text)};",
-      "--samaritan-prompt-underline-colour: ${3:var(--theme-text)};",
-      "--samaritan-prompt-cursor-colour: ${4:#cc0000};"
+      "--samaritan-prompt-text-colour: ${2:#fff};",
+      "--samaritan-prompt-underline-colour: ${3:#fff};",
+      "--samaritan-prompt-cursor-colour: ${4:#cc0000};",
+      "--samaritan-prompt-text-line-clamp: ${5:none};"
     ]
   }
 }

package/.vscode/srcdev-component-site-header.code-snippets

@@ -14,6 +14,18 @@
       "</SiteHeader>"
     ]
   },
+  "SRCDEV SiteHeader Sticky Tokens": {
+    "description": "SiteHeader sticky + layout token overrides (set on the styleClassPassthrough class)",
+    "scope": "css",
+    "body": [
+      ".${1:header} {",
+      "  --site-header-position: ${2:sticky};",
+      "  --site-header-sticky-offset: ${3:0px};",
+      "  --site-header-bg: ${4:var(--theme-surface-subtle)};",
+      "  --site-header-branding-max-width: ${5:50%};",
+      "}"
+    ]
+  },
   "SRCDEV SiteHeader With Secondary Navigation": {
     "description": "SiteHeader with the secondaryNavigation slot (e.g. a settings icon link)",
     "scope": "vue,html",
@@ -36,7 +48,7 @@
     "body": [
       "<SiteHeader",
       "  :responsive-nav-links=\"$1responsiveNavLinks\"",
-      "  home-nav-aria-label=\"${2:Home Navigation}\"",
+      "  home-nav-aria-label=\"${2:Home navigation}\"",
       "  main-nav-aria-label=\"${3:Main navigation}\"",
       "  secondary-nav-aria-label=\"${4:Secondary navigation}\"",
       "  overflow-menu-aria-label=\"${5:Overflow navigation menu}\"",

package/.vscode/srcdev-component-sparkle-effect.code-snippets

@@ -0,0 +1,33 @@
+{
+  "SRCDEV SparkleEffect Button": {
+    "description": "SparkleEffect around a pill button (sparkles along its border on hover/focus)",
+    "scope": "vue,html",
+    "body": [
+      "<SparkleEffect :count=\"${1:5}\"${4| continuous,|}>",
+      "  <InputButton button-text=\"${2:Button text}\" variant=\"${3|primary,secondary,tertiary|}\" is-pill />",
+      "</SparkleEffect>"
+    ]
+  },
+  "SRCDEV SparkleEffect Card": {
+    "description": "SparkleEffect around block content with its own corner radius",
+    "scope": "vue,html",
+    "body": [
+      "<SparkleEffect tag=\"div\" radius=\"${1:1.2rem}\" :count=\"${2:7}\">",
+      "  $0",
+      "</SparkleEffect>"
+    ]
+  },
+  "SRCDEV SparkleEffect CSS Override": {
+    "description": "SparkleEffect token overrides scoped to a page or section class",
+    "scope": "css,vue",
+    "body": [
+      ".${1:page-name} {",
+      "  --sparkle-effect-colour: ${2:hsl(260 80% 70%)};",
+      "  --sparkle-effect-size: ${3:0.7rem};",
+      "  --sparkle-effect-blur: ${6:1px};",
+      "  --sparkle-effect-duration: ${4:1.5s};",
+      "  --sparkle-effect-glow-opacity: ${5:0.5};",
+      "}"
+    ]
+  }
+}

package/app/components/01.atoms/animations/sparkle-effect/CONSUMER-STYLING.md

@@ -0,0 +1,75 @@
+# SparkleEffect — Consumer Styling Guide
+
+## Public token API
+
+| Token | Default | Description |
+|---|---|---|
+| `--sparkle-effect-colour` | `var(--theme-border)` | Glow colour, and the base hue the sparkles shift from. With relative colour support each sparkle is a lightened, hue-shifted version of it; without, they use it as-is. |
+| `--sparkle-effect-size` | `0.7rem` | Width of one sparkle arm (each arm is 1:3, and each sparkle scales this by its preset). |
+| `--sparkle-effect-blur` | `1px` | Blur on each sparkle. `0` gives crisp sparkles; the original pen used `3px`. |
+| `--sparkle-effect-duration` | `1.5s` | Base travel time; each sparkle multiplies it by its own speed. |
+| `--sparkle-effect-radius` | `100vw` | Corner shape of the path the sparkles follow and of the glow. Match the slotted element's radius. Also set by the `radius` prop. |
+| `--sparkle-effect-glow-blur` | `1.2rem` | Blur of the glow behind the slot. |
+| `--sparkle-effect-glow-opacity` | `0.5` | Glow opacity while active. |
+
+Private tokens, not public API: `--_sparkle-effect-colour` (the resolved colour) and the per-sparkle
+`--_sparkle-effect-spark-*` values (colour, scale, translate, offset, speed, timing), which
+the component writes inline on each sparkle from its preset table.
+
+## State hooks
+
+| Selector | Meaning |
+|---|---|
+| `.sparkle-effect` | Root element (`span` or `div`, per `tag`). |
+| `.sparkle-effect::before` | The glow, behind the slot. |
+| `.sparkle-effect-sparks` | `aria-hidden` layer holding the sparkles, over the slot. |
+| `.sparkle-effect-spark` | One sparkle. |
+| `.sparkle-effect[data-continuous]` | Set by the `continuous` prop: sparkles loop while active. |
+
+The effect runs on `.sparkle-effect:hover` and when anything inside has `:focus-visible`. It's
+suppressed while the slotted element (direct child) is `:disabled` or `[aria-disabled="true"]`.
+
+## Motion and browser support
+
+- Sparkles travel along the wrapper's border box with `offset-path: border-box`. They render only
+  where that's supported (Chrome 116+, Safari 17.2+, Firefox 122+). Elsewhere, including Safari
+  16, the glow still works.
+- Under `prefers-reduced-motion: reduce` the sparkles are hidden and only the glow fades in.
+- Sparkles start at the top-left of the path and snap back when the pointer leaves, so each hover
+  replays the effect. With `continuous`, each sparkle loops instead (`sparkle-effect-travel` keyframes:
+  travel, drift and fade in one), at its own speed, until the hover or focus ends.
+
+## Shape
+
+The wrapper shrinks to its slot (`inline-grid` for `span`, `grid` for `div`) and can't read the
+slotted element's own `border-radius`, so set `--sparkle-effect-radius` (or `radius`) to match it:
+the default `100vw` suits pill buttons, a card might need `1.2rem`, a round icon button `50%`.
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<style scoped>`, tokens set on your element still work, but selectors that reach inside the component need
+`:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
+
+**Caveat:** the `radius` prop writes `--sparkle-effect-radius` inline on the root, so when it's set
+an ancestor's value for that token never lands.
+
+## Class passthrough
+
+`styleClassPassthrough` adds classes to the root, for sizing or placing the wrapper (e.g.
+`inline-size: 100%` around a full-width card) or for setting the tokens above on one instance.
+
+```vue
+<SparkleEffect style-class-passthrough="promo-sparkle">
+  <InputButton button-text="Join the waitlist" is-pill />
+</SparkleEffect>
+```
+
+```css
+.promo-sparkle {
+  --sparkle-effect-colour: hsl(260 80% 70%);
+  --sparkle-effect-duration: 2s;
+}
+```