srcdev-nuxt-components 9.6.11 → 9.6.12

package/.claude/skills/component-compliance-checklist.md

@@ -204,6 +204,11 @@ The ledger can't see items 6c, 9, 10, 11 and 14, so check those by hand.
      `aria-hidden` (`ToggleSwitch`, 2026-10-16).
    - Live-updating or auto-advancing content (carousels, marquees, auto-dismissing toasts) has a
      way to pause it, per WCAG 2.2.2 — a visible control, or pause-on-hover/focus at minimum.
+   - Pause-on-focus listens for `focusin`/`focusout` on the root (with a `relatedTarget`
+     containment check), not `focus`/`blur`, which don't bubble: focusable content inside an
+     `aria-hidden` moving track otherwise gets focus while still hidden and moving. A looping
+     duplicate copy gets `inert`, and a focus-caused pause must not undo a pause the user chose
+     (`MarqueeScroller`, 2026-10-18).
    - `prefers-reduced-motion` is respected for any animation that isn't purely decorative.
    - A mode that hides a native control's own indicator (a range thumb, a checkbox box, a caret)
      draws its own visible state for the current value, and its interactive area isn't shrunk to a

package/.claude/skills/components/form-field.md

@@ -57,10 +57,25 @@ Full token table in `app/components/05.forms/form-field/CONSUMER-STYLING.md`. Pu
 Target state via `.form-field[data-width="wide"]`, `.form-field[data-has-gutter]`,
 `.form-field[data-invalid]`.
 
+FormField doesn't change `overflow-wrap` or `min-inline-size` on its slot content: wrapping long
+copy is the slotted control's job (every `*Field` component handles its own). Plain text slotted
+directly needs its own wrapping rule.
+
+---
+
+## Storybook
+
+`Components/Forms/Form Field/FormField`: `Default`, `AllWidths`, `NoGutter`, and `StressTest`
+(each width, with and without gutter and error state, around an `InputTextField` with hostile
+copy). Stories use the `CanvasSwitcher` decorator.
+
 ---
 
 ## History
 
+**2026-10-17**: added the `StressTest` story, `CanvasSwitcher` decorator and Docs-page
+descriptions; nothing in the component broke under it.
+
 **Migrated 2026-09-26** (0/5 → full compliance):
 
 - Width and gutter modifiers moved from bare classes (`.narrow`, `.medium`, `.wide`, `.has-gutter`)

package/.claude/skills/components/form-fieldset.md

@@ -21,8 +21,8 @@ ARIA semantics.
 | `:legend` | `string` | `""` | Legend text. The legend renders when this or the `legend` slot is given. |
 | `group-role` | `"group" \| "radiogroup"` | `"group"` | `"group"` renders no `role` attribute (a fieldset's native role is already `group`). `"radiogroup"` sets `role="radiogroup"`: use it for radio buttons only. |
 | `:required` | `boolean` | `false` | Sets `aria-required="true"` **only** when `group-role="radiogroup"`. `aria-required` isn't allowed on `role="group"`, so checkbox groups get nothing; put "(required)" in the legend text instead. |
-| `:field-has-error` | `boolean` | `false` | Sets `aria-invalid` on the fieldset. |
-| `:data-testid` | `string` | `""` | Passed to the fieldset. |
+| `:field-has-error` | `boolean` | `false` | Sets `aria-invalid="true"` on the fieldset; the attribute is absent when `false`. |
+| `:data-testid` | `string` | `""` | Passed to the fieldset; omitted when empty. |
 | `:style-class-passthrough` | `string \| string[]` | `[]` | Extra classes on the fieldset, via `useStyleClassPassthrough` (reacts to prop changes). |
 
 ## Slots
@@ -54,10 +54,26 @@ content `--form-fieldset-content-margin-block|margin-inline`, legend
 `--form-fieldset-legend-color|font-size|font-weight|line-height|margin-block|margin-inline`. Error state hook:
 `.form-fieldset[aria-invalid="true"]`.
 
+The fieldset sets `min-inline-size: 0` and the legend `overflow-wrap: anywhere`, so neither
+overflows a narrow column. Slotted controls handle their own wrapping.
+
+---
+
+## Storybook
+
+`Components/Forms/Form Fieldset/FormFieldset`: `Default`, `CheckboxGroup`, `WithError`, and
+`StressTest` (hostile legend copy with the error state on). Stories use the `CanvasSwitcher`
+decorator and link to the three components that render FormFieldset.
+
 ---
 
 ## History
 
+**2026-10-17**: StressTest story, CanvasSwitcher and Docs-page descriptions added. Fixed: a
+valid fieldset rendered `aria-invalid="false"`; an empty `dataTestid` rendered `data-testid=""`;
+the fieldset had no `min-inline-size: 0` (each wrapping component set it on its own class), and
+the legend didn't wrap unbroken copy.
+
 **Migrated 2026-09-26** (0/5 → full compliance):
 
 - **Role bug fixed:** `role="radiogroup"` used to be hardcoded, so screen readers announced

package/.claude/skills/components/marquee-scroller.md

@@ -10,8 +10,9 @@ type: reference
 
 `MarqueeScroller` renders an infinite horizontal scroller for small repeating items — client
 logos, badges, testimonial avatars. The track is duplicated once so the loop is seamless
-(`marquee-group` renders twice: once real, once `aria-hidden="true"`), and the whole thing pauses
-automatically on hover, on keyboard focus, and when the user has `prefers-reduced-motion` set.
+(`.marquee-scroller-group` renders twice: once real, once `aria-hidden="true"` and `inert`), and the
+whole thing pauses automatically on hover, whenever focus is inside it, and when the user has
+`prefers-reduced-motion` set.
 
 ## Props
 
@@ -24,11 +25,12 @@ automatically on hover, on keyboard focus, and when the user has `prefers-reduce
 | `ariaLabel` | `string` | `"Scrolling content"` | `aria-label` on the root region — override for localisation. |
 | `ariaDescription` | `string` | `"Use spacebar to pause or play the animation."` | Screen-reader-only instructions rendered inside the region — override for localisation. |
 | `showControls` | `boolean` | `false` | Shows a visible pause/play button. Recommended (WCAG 2.2.2, Pause/Stop/Hide) whenever content scrolls automatically and indefinitely. |
-| `respectReducedMotion` | `boolean` | `true` | Auto-pauses and disables the animation for users with `prefers-reduced-motion: reduce`, and pauses on keyboard focus. |
+| `respectReducedMotion` | `boolean` | `true` | Auto-pauses and disables the animation for users with `prefers-reduced-motion: reduce` (and keeps it paused after focus leaves). Focus-pausing no longer depends on it. |
 | `playIcon` | `string` | `"mdi:play"` | Iconify icon name shown on the control button while paused. Ignored if the `toggle-icon` slot is used. |
 | `pauseIcon` | `string` | `"mdi:pause"` | Iconify icon name shown on the control button while playing. Ignored if the `toggle-icon` slot is used. |
-| `playLabel` | `string` | `"Play animation"` | Control button `aria-label` while paused — override for localisation. |
-| `pauseLabel` | `string` | `"Pause animation"` | Control button `aria-label` while playing — override for localisation. |
+| `playLabel` | `string` | `"Play animation"` | Control button text (visually hidden, its accessible name) while paused — override for localisation. |
+| `pauseLabel` | `string` | `"Pause animation"` | Control button text (visually hidden, its accessible name) while playing — override for localisation. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes on the root `.marquee-scroller`, via `useStyleClassPassthrough` (reacts to prop changes). |
 
 Import the item types from the library's type exports when building `marqueeData`/`itemConfig`
 outside the component:
@@ -52,8 +54,10 @@ One dynamically-named slot per `marqueeData` entry, named after that item's `id`
 </MarqueeScroller>
 ```
 
-Each slot is rendered twice (once in the visible group, once in the `aria-hidden` duplicate group)
-so the loop wraps seamlessly — don't put anything with side effects or unique ids inside a slot.
+Each slot is rendered twice (once in the visible group, once in the `aria-hidden`, `inert`
+duplicate group) so the loop wraps seamlessly. Don't put anything with side effects or unique ids
+inside a slot. Links are fine: only the real copy is focusable. Items are fixed-size boxes; text
+wraps inside them (`overflow-wrap: anywhere`) but content taller than `itemConfig.height` overflows.
 
 `toggle-icon` (scoped with `{ isPaused: boolean }`) replaces the control button's icon entirely —
 use this instead of `playIcon`/`pauseIcon` when an Iconify name isn't enough (custom SVG, a
@@ -70,16 +74,25 @@ different icon set):
 ## Accessibility behaviour
 
 - The root is `role="region"` with `tabindex="0"` so it's independently focusable.
-- Spacebar toggles pause/play while the region is focused. Arrow keys do nothing — there is no
+- Spacebar toggles pause/play while the region itself is focused (keydown from inside, e.g. on the
+  control button or a link, is left to that element). Arrow keys do nothing — there is no
   manual-stepping behaviour, so the default `ariaDescription` doesn't claim one (fixed 2026-09-08;
   it previously announced "arrow keys ... for manual control" with no implementation behind it).
-- Focusing the region pauses the animation when `respectReducedMotion` is `true` (the default);
-  blurring resumes it unless the user prefers reduced motion.
+- Focus anywhere inside the region (the region itself, or a link in an item) pauses the animation
+  and removes `aria-hidden` from the track, so the focused content is announced. Focus moving between
+  elements inside keeps it paused. When focus leaves, it resumes only if focus caused the pause and
+  the user doesn't prefer reduced motion: a pause chosen with the button or spacebar sticks.
+  Focus landing on the control button doesn't auto-pause, so one click pauses. (Changed 2026-10-17:
+  this used to listen for `focus`/`blur` on the region only, gated on `respectReducedMotion`, so
+  tabbing to a link in an item left it moving and `aria-hidden`.)
 - Hovering anywhere over the scroller pauses the track and applies
   `--marquee-scroller-group-hover-filter` (default `grayscale(1)`) to every item; hovering an
   individual item restores it via `--marquee-scroller-item-hover-filter` (default `grayscale(0)`).
 - `aria-live` switches to `"polite"` while paused so screen readers announce the paused content.
-- The duplicate track group is always `aria-hidden="true"`.
+- The track is `aria-hidden="true"` while playing (attribute removed when paused). The duplicate
+  group is always `aria-hidden="true"` and `inert`, so its copies of any links can't be focused.
+- The control button is an `InputButton` (`variant="inline"`, icon-only): `playLabel`/`pauseLabel`
+  is its visually hidden text rather than an `aria-label`.
 - All user-visible copy (`ariaLabel`, `ariaDescription`, `playLabel`, `pauseLabel`) is a plain
   string prop with an English default — there's no i18n framework dependency in this library, so
   pass translated strings from the consumer's own i18n solution.
@@ -110,11 +123,11 @@ theme); only its border width is (`--marquee-scroller-control-border-width`).
 
 ## Seamless loop math
 
-The track duplicates `marqueeData` into two `.marquee-group` children so the loop can wrap without
+The track duplicates `marqueeData` into two `.marquee-scroller-group` children so the loop can wrap without
 a visible cut. The animation must shift the track by exactly one group's width plus its connecting
 gap — not `translateX(-50%)`, which overshoots short of the seam once the track's own `gap`
 between the two groups is added to its total width. This is computed as a private
-`--_track-shift: calc(itemCount * (itemWidth + gap))` token and used in the `marqueeMove`
+`--_track-shift: calc(itemCount * (itemWidth + gap))` token and used in the `marquee-scroller-move`
 keyframe. Fixed 2026-09-08 — the original `-50%` version produced a small but visible gap/overlap
 at the loop point once more than a couple of items were in `marqueeData`.
 
@@ -125,6 +138,30 @@ section on a wide viewport), the loop briefly shows empty space before snapping
 the visible track only spans as wide as the content, not the container. On mount (and on
 container resize, via `ResizeObserver`), the component measures one rendered group's `scrollWidth`
 against the root element's `offsetWidth` and repeats `marqueeData` internally (`repeatCount`)
-enough times per `.marquee-group` so a single group's width always covers the container. This is
+enough times per `.marquee-scroller-group` so a single group's width always covers the container. This is
 transparent to consumers — it doesn't change `marqueeData` or any prop, only how many times each
 item's slot is rendered internally. Fixed 2026-09-08.
+
+The repeat count is capped at 50 copies per group, so tiny items in a huge container can't flood
+the DOM (added 2026-10-17).
+
+## Storybook
+
+`Atoms/Effects/MarqueeScroller`: `WithControls`, `FocusableItems` (links in items, for the focus
+behaviour), and `StressTest` (24 items of hostile copy, a broken image, long localised labels, a
+single item, tiny items hitting the repeat cap, and empty data). Stories use the `CanvasSwitcher`
+decorator.
+
+## History
+
+**2026-10-17** (stress-test pass, breaking class renames):
+
+- Structural classes prefixed (`.marquee-scroller-item`, `-control`, `-track`, `-group`,
+  `-description`); bare `.reverse`/`.paused`/`.reduced-motion` became `data-*` attributes; keyframes
+  renamed `marquee-scroller-move`. See CONSUMER-STYLING.md for the full map.
+- Raw `<button>` replaced with `InputButton variant="inline"` (icon-only slot).
+- Focus-pausing reworked (focusin/focusout, see Accessibility behaviour); duplicate group `inert`.
+- `prefers-reduced-motion` change listener is now removed on unmount.
+- New `--marquee-scroller-focus-outline-colour` token (was bare `--theme-ring`).
+- Added `styleClassPassthrough`. Removed the redundant `aspect-ratio: 1 / 1` on items (width and
+  height are both set, and it mis-centres on old Safari). Items wrap unbroken text.

package/.vscode/srcdev-component-form-field.code-snippets

@@ -3,7 +3,7 @@
     "description": "FormField layout wrapper around a single form control",
     "scope": "vue,html",
     "body": [
-      "<FormField width=\"${1|wide,medium,narrow|}\" :has-gutter=\"${2|false,true|}\" :field-has-error=\"!!$3errors.fieldName\">",
+      "<FormField width=\"${1|wide,medium,narrow|}\" :has-gutter=\"${2|false,true|}\" :field-has-error=\"!!${3:errors.fieldName}\">",
       "  $0",
       "</FormField>"
     ]
@@ -12,12 +12,13 @@
     "description": "CSS override scaffold for FormField tokens",
     "scope": "css",
     "body": [
-      ".$1my-page {",
+      ".${1:my-page} {",
       "  .form-field {",
-      "    --form-field-max-width-narrow: $2;",
-      "    --form-field-gutter-width: $3;",
-      "    --form-field-margin-block: $4;",
-      "    --form-field-background-color: $5;",
+      "    --form-field-max-width-narrow: ${2:400px};",
+      "    --form-field-gutter-width: ${3:1.6rem};",
+      "    --form-field-margin-block: ${4:0 1.6rem};",
+      "    --form-field-background-color: ${5:transparent};",
+      "    --form-field-border-radius: ${6:0.4rem};",
       "  }",
       "}"
     ]

package/.vscode/srcdev-component-form-fieldset.code-snippets

@@ -4,11 +4,11 @@
     "scope": "vue,html",
     "body": [
       "<FormFieldset",
-      "  id=\"$1fieldId\"",
-      "  name=\"$2fieldName\"",
-      "  legend=\"$3Legend\"",
+      "  id=\"${1:fieldId}\"",
+      "  name=\"${2:fieldName}\"",
+      "  legend=\"${3:Legend}\"",
       "  group-role=\"${4|group,radiogroup|}\"",
-      "  :field-has-error=\"!!$5errors.fieldName\"",
+      "  :field-has-error=\"!!${5:errors.fieldName}\"",
       ">",
       "  <template #content>",
       "    $0",
@@ -20,15 +20,15 @@
     "description": "CSS override scaffold for FormFieldset tokens",
     "scope": "css",
     "body": [
-      ".$1my-page {",
+      ".${1:my-page} {",
       "  .form-fieldset {",
-      "    --form-fieldset-padding-block: $6;",
-      "    --form-fieldset-padding-inline: $7;",
-      "    --form-fieldset-border: $8;",
-      "    --form-fieldset-legend-color: $2;",
-      "    --form-fieldset-legend-font-size: $3;",
-      "    --form-fieldset-legend-font-weight: $4;",
-      "    --form-fieldset-legend-margin-block: $5;",
+      "    --form-fieldset-padding-block: ${2:0};",
+      "    --form-fieldset-padding-inline: ${3:0};",
+      "    --form-fieldset-border: ${4:0};",
+      "    --form-fieldset-legend-color: ${5:inherit};",
+      "    --form-fieldset-legend-font-size: ${6:var(--step-5)};",
+      "    --form-fieldset-legend-font-weight: ${7:normal};",
+      "    --form-fieldset-legend-margin-block: ${8:0.8rem};",
       "  }",
       "}"
     ]

package/.vscode/srcdev-component-marquee-scroller.code-snippets

@@ -5,16 +5,17 @@
     "body": [
       "<MarqueeScroller",
       "  :marquee-data=\"[",
-      "    { id: 1, content: '$1logo-a' },",
-      "    { id: 2, content: '$2logo-b' },",
+      "    { id: 1, content: '${1:logo-a}' },",
+      "    { id: 2, content: '${2:logo-b}' },",
       "  ]\"",
       "  :item-config=\"{ width: '${3:120px}', height: '${4:60px}', gap: '${5:24px}' }\"",
+      "  :style-class-passthrough=\"[${6:}]\"",
       ">",
       "  <template #1>",
-      "    $6",
+      "    $7",
       "  </template>",
       "  <template #2>",
-      "    $7",
+      "    $8",
       "  </template>",
       "</MarqueeScroller>"
     ]
@@ -24,11 +25,11 @@
     "scope": "vue,html",
     "body": [
       "<MarqueeScroller",
-      "  :marquee-data=\"$1items\"",
+      "  :marquee-data=\"${1:items}\"",
       "  show-controls",
-      "  aria-label=\"$2Scrolling client logos\"",
+      "  aria-label=\"${2:Scrolling client logos}\"",
       ">",
-      "  <template v-for=\"item in $1items\" #[item.id] :key=\"item.id\">",
+      "  <template v-for=\"item in ${1:items}\" #[item.id] :key=\"item.id\">",
       "    $3",
       "  </template>",
       "</MarqueeScroller>"
@@ -39,14 +40,14 @@
     "scope": "vue,html",
     "body": [
       "<MarqueeScroller",
-      "  :marquee-data=\"$1items\"",
+      "  :marquee-data=\"${1:items}\"",
       "  show-controls",
       "  play-icon=\"${2:mdi:play-circle}\"",
       "  pause-icon=\"${3:mdi:pause-circle}\"",
       "  play-label=\"${4:Play}\"",
       "  pause-label=\"${5:Pause}\"",
       ">",
-      "  <template v-for=\"item in $1items\" #[item.id] :key=\"item.id\">",
+      "  <template v-for=\"item in ${1:items}\" #[item.id] :key=\"item.id\">",
       "    $6",
       "  </template>",
       "</MarqueeScroller>"
@@ -56,7 +57,7 @@
     "description": "MarqueeScroller with the toggle-icon slot fully replacing the control button's icon",
     "scope": "vue,html",
     "body": [
-      "<MarqueeScroller :marquee-data=\"$1items\" show-controls>",
+      "<MarqueeScroller :marquee-data=\"${1:items}\" show-controls>",
       "  <template #toggle-icon=\"{ isPaused }\">",
       "    $2",
       "  </template>",
@@ -67,25 +68,27 @@
     "description": "CSS override scaffold for MarqueeScroller — scope to a page or section class",
     "scope": "css",
     "body": [
-      ".$1my-page {",
+      ".${1:my-page} {",
       "  .marquee-scroller {",
-      "    --marquee-scroller-fade-width: ;",
-      "    --marquee-scroller-focus-outline-width: ;",
-      "    --marquee-scroller-focus-outline-offset: ;",
-      "    --marquee-scroller-item-border-colour: ;",
-      "    --marquee-scroller-item-border-width: ;",
-      "    --marquee-scroller-item-border-radius: ;",
-      "    --marquee-scroller-item-transition-duration: ;",
-      "    --marquee-scroller-group-hover-filter: ;",
-      "    --marquee-scroller-item-hover-filter: ;",
-      "    --marquee-scroller-control-offset: ;",
-      "    --marquee-scroller-control-background-colour: ;",
-      "    --marquee-scroller-control-background-colour-hover: ;",
-      "    --marquee-scroller-control-text-colour: ;",
-      "    --marquee-scroller-control-border-radius: ;",
-      "    --marquee-scroller-control-border-width: ;",
-      "    --marquee-scroller-control-padding: ;",
-      "    --marquee-scroller-control-font-size: ;",
+      "    --marquee-scroller-fade-width: ${2:10%};",
+      "    --marquee-scroller-focus-outline-width: ${3:2px};",
+      "    --marquee-scroller-focus-outline-colour: ${4:var(--theme-ring)};",
+      "    --marquee-scroller-focus-outline-offset: ${5:2px};",
+      "    --marquee-scroller-item-border-colour: ${6:var(--slate-10)};",
+      "    --marquee-scroller-item-border-width: ${7:1px};",
+      "    --marquee-scroller-item-border-radius: ${8:4px};",
+      "    --marquee-scroller-item-transition-duration: ${9:0.5s};",
+      "    --marquee-scroller-group-hover-filter: ${10:grayscale(1)};",
+      "    --marquee-scroller-item-hover-filter: ${11:grayscale(0)};",
+      "    --marquee-scroller-control-offset: ${12:8px};",
+      "    --marquee-scroller-control-background-colour: ${13:rgba(0, 0, 0, 0.7)};",
+      "    --marquee-scroller-control-background-colour-hover: ${14:rgba(0, 0, 0, 0.9)};",
+      "    --marquee-scroller-control-text-colour: ${15:white};",
+      "    --marquee-scroller-control-border-radius: ${16:4px};",
+      "    --marquee-scroller-control-border-width: ${17:1px};",
+      "    --marquee-scroller-control-padding: ${18:8px};",
+      "    --marquee-scroller-control-font-size: ${19:14px};",
+      "    --marquee-scroller-control-transition-duration: ${20:0.2s};",
       "  }",
       "}"
     ]

package/app/components/01.atoms/animations/marquee-scroller/CONSUMER-STYLING.md

@@ -2,17 +2,30 @@
 
 ## Public token API
 
+### Region
+
 | Token | Default | Controls |
 |---|---|---|
 | `--marquee-scroller-fade-width` | `10%` | Width of the transparent fade at each edge of the track (`mask-image`) |
-| `--marquee-scroller-focus-outline-width` | `2px` | Outline width on the root region and the control button when keyboard-focused (colour is `--theme-ring`) |
+| `--marquee-scroller-focus-outline-width` | `2px` | Outline width on the root region and the control button when keyboard-focused |
+| `--marquee-scroller-focus-outline-colour` | `var(--theme-ring)` | Outline colour on the same two focus states |
 | `--marquee-scroller-focus-outline-offset` | `2px` | Outline offset on the same two focus states |
+
+### Items
+
+| Token | Default | Controls |
+|---|---|---|
 | `--marquee-scroller-group-hover-filter` | `grayscale(1)` | Filter applied to every item when the pointer hovers anywhere over the scroller |
 | `--marquee-scroller-item-hover-filter` | `grayscale(0)` | Filter applied to a single item when it is individually hovered (overrides the group filter for that item) |
 | `--marquee-scroller-item-transition-duration` | `0.5s` | Transition duration for the item hover filter change |
 | `--marquee-scroller-item-border-width` | `1px` | Item border width |
 | `--marquee-scroller-item-border-colour` | `var(--slate-10)` | Item border colour |
 | `--marquee-scroller-item-border-radius` | `4px` | Item border radius |
+
+### Control button
+
+| Token | Default | Controls |
+|---|---|---|
 | `--marquee-scroller-control-offset` | `8px` | Distance of the pause/play button from the top and end edges |
 | `--marquee-scroller-control-background-colour` | `rgba(0, 0, 0, 0.7)` | Pause/play button background |
 | `--marquee-scroller-control-background-colour-hover` | `rgba(0, 0, 0, 0.9)` | Pause/play button background on hover |
@@ -21,15 +34,35 @@
 | `--marquee-scroller-control-padding` | `8px` | Pause/play button padding |
 | `--marquee-scroller-control-font-size` | `14px` | Pause/play button icon font size |
 | `--marquee-scroller-control-transition-duration` | `0.2s` | Pause/play button background-colour transition duration |
-| `--marquee-scroller-control-border-width` | `1px` | Pause/play button border width in forced-colors/high-contrast mode (`prefers-contrast: high`). The border colour itself stays the system `ButtonText` keyword — see note below. |
+| `--marquee-scroller-control-border-width` | `1px` | Pause/play button border width under `prefers-contrast: high`. The border colour itself stays the system `ButtonText` keyword, see below. |
 
-```css
-.my-page {
-  --marquee-scroller-item-border-colour: #b5651d;
-  --marquee-scroller-control-background-colour: #1a1a1a;
-  --marquee-scroller-fade-width: 20%;
-}
-```
+Private tokens (not public API): `--_fade-width`, `--_focus-outline` (width + colour, shared by
+both focus states) and `--_track-shift` (the loop distance, computed from `itemConfig`).
+
+---
+
+## State hooks
+
+The root `.marquee-scroller` carries:
+
+| Attribute | When |
+|---|---|
+| `data-paused` | The track is paused (control button, spacebar, focus inside, or reduced motion) |
+| `data-reverse` | `reverse` is `true` |
+| `data-reduced-motion` | The user prefers reduced motion and `respect-reduced-motion` is on |
+
+Inner elements: `.marquee-scroller-track` (the animated row), `.marquee-scroller-group` (one copy
+of the items; the second is `aria-hidden` and `inert`), `.marquee-scroller-item` (one fixed-size
+item box), `.marquee-scroller-control` (the pause/play `InputButton`) and
+`.marquee-scroller-description` (the visually hidden instructions).
+
+> **Changed 2026-10-17**: the generic class names were renamed so they can't collide with consumer
+> CSS. `.item` → `.marquee-scroller-item`, `.control-btn` → `.marquee-scroller-control` (now an
+> `InputButton`, so it also has `.input-button`), `.marquee-track` → `.marquee-scroller-track`,
+> `.marquee-group` → `.marquee-scroller-group`, `.sr-only` → `.marquee-scroller-description`. The
+> bare state classes became attributes: `.reverse` → `[data-reverse]`, `.paused` →
+> `[data-paused]`, `.reduced-motion` → `[data-reduced-motion]`. The keyframes are now
+> `marquee-scroller-move` (was `marqueeMove`).
 
 ---
 
@@ -37,10 +70,9 @@
 
 Under `prefers-contrast: high`, the control button switches to the system colour keywords
 `ButtonFace`/`ButtonText` rather than the component's own background/text tokens. These aren't
-exposed as overridable tokens on purpose — they're meant to track the user's OS-level high-contrast
-theme, which a component-level override would defeat. Only the border *width* in that mode is a
-token (`--marquee-scroller-control-border-width`), since it's a plain dimension with no such
-constraint.
+exposed as overridable tokens on purpose: they track the user's OS-level high-contrast theme, which
+a component-level override would defeat. Only the border *width* in that mode is a token
+(`--marquee-scroller-control-border-width`), since it's a plain dimension with no such constraint.
 
 ---
 
@@ -48,7 +80,7 @@ constraint.
 
 Item `width`/`height`/`gap` and the animation duration are set via the `itemConfig` and
 `animationRuntime` props (not CSS custom properties), since they also drive the component's own
-layout math (`aspect-ratio`, track width). Override those through props:
+loop math (`--_track-shift`) and the repeat measurement. Override those through props:
 
 ```vue
 <MarqueeScroller
@@ -57,58 +89,49 @@ layout math (`aspect-ratio`, track width). Override those through props:
 />
 ```
 
----
+Item boxes are a fixed size. Text in an item wraps (`overflow-wrap: anywhere`), but content taller
+than `itemConfig.height` overflows, so size slot content to the box.
 
-## Item content via slots
+---
 
-Each entry in `marqueeData` (`{ id, content }`) renders a slot named after its `id`. Provide the
-markup for each item via that dynamically-named slot:
+## Global theming
 
-```vue
-<MarqueeScroller :marquee-data="[{ id: 1, content: 'logo-a' }, { id: 2, content: 'logo-b' }]">
-  <template #1>
-    <img src="/logos/a.svg" alt="Logo A" />
-  </template>
-  <template #2>
-    <img src="/logos/b.svg" alt="Logo B" />
-  </template>
-</MarqueeScroller>
+```css
+:where(html) {
+  --marquee-scroller-fade-width: 15%;
+  --marquee-scroller-item-border-colour: var(--slate-04);
+}
 ```
 
 ---
 
-## Control button icon and copy
-
-The pause/play button's icon and its `aria-label` copy are all overridable — see `playIcon`/
-`pauseIcon`/`playLabel`/`pauseLabel` props, or the `toggle-icon` slot for a fully custom icon
-(scoped with `isPaused`):
+## Local overrides
 
-```vue
-<MarqueeScroller
-  show-controls
-  play-icon="mdi:play-circle"
-  pause-icon="mdi:pause-circle"
-  play-label="Reproduire"
-  pause-label="Suspendre"
-/>
-```
+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`.
 
-```vue
-<MarqueeScroller show-controls>
-  <template #toggle-icon="{ isPaused }">
-    <Icon :name="isPaused ? 'lucide:play' : 'lucide:pause'" />
-  </template>
-</MarqueeScroller>
+```css
+.partners-section {
+  --marquee-scroller-item-border-colour: #b5651d;
+  --marquee-scroller-control-background-colour: #1a1a1a;
+  --marquee-scroller-fade-width: 20%;
+}
 ```
 
 ---
 
-## Local overrides
+## Class passthrough
+
+`:style-class-passthrough` (string or string array) adds classes to the root `.marquee-scroller`
+region.
+
+---
 
-Set the tokens above on an element you own (a page or section class, or a plain `class` on the
-component (it falls through to the root element)): 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`.
+## Notes
 
+- Item content and the control button's icon and copy are covered in the skill doc
+  (`marquee-scroller.md`): one slot per `marqueeData` id, `toggle-icon` slot, and the
+  `playIcon`/`pauseIcon`/`playLabel`/`pauseLabel` props.