srcdev-nuxt-components 9.4.9 → 9.4.11

package/.claude/component-ledger/template.html

@@ -390,6 +390,7 @@ footer.note code{
           <th data-key="variants" data-type="bool" title="Uses a variants/ subfolder">Variants folder</th>
           <th data-key="legacy_props" data-type="bool" title="Still options-style defineProps({...}), not defineProps&lt;Props&gt;()">Legacy props</th>
           <th data-key="story_args_bug" data-type="bool" title="A story destructures/refs Storybook's reactive args at setup-time, so most Controls-panel changes silently stop updating the rendered story after first render">Story args bug</th>
+          <th data-key="eslint_issues" data-type="bool" title="npx eslint reports at least one error or warning on a .vue file in this group">ESLint issues</th>
           <th data-key="score" data-type="num">Score</th>
         </tr>
       </thead>
@@ -400,6 +401,7 @@ footer.note code{
   <footer class="note">
     <p><strong>Methodology:</strong> "Styling doc", "Tests", "Story" and "Variants folder" are filesystem checks (<code>CONSUMER-STYLING.md</code>, a <code>tests/</code> dir, a <code>stories/</code> dir or <code>*.stories.ts</code> file, a <code>variants/</code> subfolder). "Skill doc" and "Snippet" match the component's kebab-case name against <code>.claude/skills/components/*.md</code> and <code>.vscode/*.code-snippets</code> &mdash; a small number of near-miss names may read as false negatives and are worth a manual glance before acting. "Score" is the count of the five doc/test/story/skill/snippet checks passed, out of 5, and is what "reference-quality" and "only incomplete" are based on. "Legacy props" is a source check for options-style <code>defineProps({...})</code> rather than <code>defineProps&lt;Props&gt;()</code> &mdash; like "Variants folder" it is <em>not</em> counted in the 5-point score (deliberately, so it stays visible instead of vanishing into an already-high score), but it does factor into "reference-quality" and "only incomplete", same as "Variants folder".</p>
     <p style="margin-top:0.8rem;"><strong>"Story args bug"</strong> flags a story whose <code>setup()</code> destructures or spreads Storybook's <code>args</code> into local variables/refs at mount time (e.g. <code>const { modelValue, ...otherArgs } = args;</code> then <code>ref(modelValue)</code>). @storybook/vue3 mounts the story component once and mutates the same <code>args</code> object in place on every Controls change &mdash; it does not re-run <code>setup()</code> &mdash; so a destructured copy freezes at its initial value and most Controls silently stop updating the rendered story after first render. The fix is to bind the template straight to <code>args.x</code> (optionally through a <code>computed()</code> that strips non-prop extra args), never to a value copied out in <code>setup()</code>. Also not counted in the 5-point score, for the same reason as "Legacy props".</p>
+    <p style="margin-top:0.8rem;"><strong>"ESLint issues"</strong> runs <code>npx eslint</code> across every <code>.vue</code> file under <code>app/components/</code> once per build and flags a group if any of its files reported an error or a warning. Added 2026-09-21 after fixing a dead <code>const props = withDefaults(...)</code> in <code>InputRangeCore</code> (the assignment's value was never read once its only reference &mdash; a since-removed dead computed &mdash; was cleaned up) and finding the same pattern live in <code>FormField</code>/<code>FormWrapper</code>. It also currently flags 13 groups for <code>vue/require-default-prop</code> firing on <code>defineModel()</code>-declared props, an eslint-plugin-vue rule with no options to exempt models (it predates <code>defineModel</code>) &mdash; the fix there is <code>defineModel&lt;T&gt;({'{'} required: true {'}'})</code> where the native element genuinely can't be meaningfully "empty" (matching what <code>InputRangeCore</code>/<code>InputRangeDefault</code> now do), not a blanket rule disable or an artificial default value. Not counted in the 5-point score, same reasoning as "Legacy props"/"Story args bug".</p>
     <p style="margin-top:0.8rem;"><strong>On <code>--_</code> vars:</strong> the public/private split is decided by consumer relevance, not reuse count &mdash; a private var is correct even used once, as long as the value has no plausible consumer override. This column is a raw count of <code>--_</code>-prefixed CSS custom properties per group; it is <em>not</em> scored and doesn't factor into "reference-quality" or "score." A high count is only a prompt to check each one by hand for a value that should have been public (a colour, size, or per-state variant with no override token) &mdash; the bug class the <code>ServicesCard</code> fix (CLAUDE.md pitfall #20) caught, not the presence of the prefix itself.</p>
     <p style="margin-top:0.8rem;"><strong>This page regenerates from <code>.claude/component-ledger/build.mjs</code></strong>, triggered whenever a staged commit touches <code>app/components/</code> (see the <code>create-commit-message</code> skill's hook). All numbers on this page, including the narrative above, are computed live from the latest scan &mdash; nothing here is hand-written prose that can drift out of date.</p>
   </footer>
@@ -439,11 +441,12 @@ statDefs.forEach(sd => {
 });
 
 // ---- dynamic narrative (every number computed from DATA, nothing hand-written) ----
-const fullyCompliant = DATA.filter(d => d.score === 5 && d.tier !== "NONE" && !d.variants && !d.legacy_props && !d.story_args_bug);
+const fullyCompliant = DATA.filter(d => d.score === 5 && d.tier !== "NONE" && !d.variants && !d.legacy_props && !d.story_args_bug && !d.eslint_issues);
 const unplaced = DATA.filter(d => d.tier === "NONE");
 const forkedVariants = DATA.filter(d => d.variants);
 const legacyProps = DATA.filter(d => d.legacy_props);
 const storyArgsBug = DATA.filter(d => d.story_args_bug);
+const eslintIssues = DATA.filter(d => d.eslint_issues);
 const noSkillAndUnplaced = unplaced.filter(d => !d.skill).length;
 const topPrivate = DATA.filter(d => d.priv_tokens > 0).sort((a,b) => b.priv_tokens - a.priv_tokens).slice(0, 3);
 
@@ -455,6 +458,7 @@ narrativeEl.innerHTML = `
   <p>${forkedVariants.length ? `<strong>${forkedVariants.length} group${forkedVariants.length===1?"":"s"}</strong> still fork${forkedVariants.length===1?"s":""} variants into a <code class="mono">variants/</code> subfolder &mdash; deprecated in favour of documenting the variation in the parent skill.md.` : `No component groups currently fork variants into a <code class="mono">variants/</code> subfolder.`}</p>
   <p>${legacyProps.length ? `<strong>${legacyProps.length} group${legacyProps.length===1?"":"s"}</strong> still use${legacyProps.length===1?"s":""} options-style <code class="mono">defineProps({...})</code> instead of <code class="mono">defineProps&lt;Props&gt;()</code> &mdash; this doesn't move the 5-point score, so it can hide behind an otherwise-complete-looking group.` : `No component groups currently use options-style defineProps.`}</p>
   <p>${storyArgsBug.length ? `<strong>${storyArgsBug.length} group${storyArgsBug.length===1?"":"s"}</strong> ha${storyArgsBug.length===1?"s":"ve"} a story that destructures/refs Storybook's <code class="mono">args</code> at setup-time (${storyArgsBug.map(d => `<code class="mono">${d.compdir.split("/").pop()}</code>`).join(", ")}) &mdash; the Controls panel silently stops updating most props on that story after first render. This doesn't move the 5-point score either, for the same reason as "Legacy props".` : `No component groups currently have this Storybook Controls reactivity bug.`}</p>
+  <p>${eslintIssues.length ? `<strong>${eslintIssues.length} group${eslintIssues.length===1?"":"s"}</strong> ha${eslintIssues.length===1?"s":"ve"} at least one live <code class="mono">npx eslint</code> finding (${eslintIssues.map(d => `<code class="mono">${d.compdir.split("/").pop()}</code>`).join(", ")}) &mdash; a component can score 5/5 on docs/tests/story/skill/snippet and still carry these. Not counted in the 5-point score, same reasoning as "Legacy props"/"Story args bug".` : `No component groups currently have a live ESLint finding.`}</p>
   <p><strong>${topPrivate.length ? "On --_ vars:" : ""}</strong> ${topPrivate.length
     ? `the largest private-token surfaces right now are ${topPrivate.map(d => `<code class="mono">${d.compdir.split("/").pop()}</code> (${d.priv_tokens})`).join(", ")} &mdash; worth a manual look for a value that should have been public, per the corrected rule in the footer below. A high count on its own isn't a defect.`
     : ""}</p>
@@ -521,7 +525,7 @@ function tierLabel(t){ return t === "NONE" ? "unplaced" : t; }
 function render(){
   let rows = DATA.slice();
   if (activeTier !== "all") rows = rows.filter(d => d.tier === activeTier);
-  if (onlyIncomplete) rows = rows.filter(d => d.score < 5 || d.tier === "NONE" || d.variants || d.legacy_props || d.story_args_bug);
+  if (onlyIncomplete) rows = rows.filter(d => d.score < 5 || d.tier === "NONE" || d.variants || d.legacy_props || d.story_args_bug || d.eslint_issues);
   const q = searchEl.value.trim().toLowerCase();
   if (q) rows = rows.filter(d => d.compdir.toLowerCase().includes(q));
 
@@ -551,6 +555,7 @@ function render(){
       <td class="check">${d.variants ? '<span class="no" style="opacity:1;color:var(--warn);">●</span>' : '<span class="no">–</span>'}</td>
       <td class="check">${d.legacy_props ? '<span class="no" style="opacity:1;color:var(--warn);">●</span>' : '<span class="no">–</span>'}</td>
       <td class="check">${d.story_args_bug ? '<span class="no" style="opacity:1;color:var(--warn);">●</span>' : '<span class="no">–</span>'}</td>
+      <td class="check">${d.eslint_issues ? '<span class="no" style="opacity:1;color:var(--warn);">●</span>' : '<span class="no">–</span>'}</td>
       <td><span class="score-bar">${dots}</span></td>
     </tr>`;
   }).join("");

package/.claude/skills/component-dynamic-slots.md

@@ -134,7 +134,7 @@ Some components pair multiple slot types per index (e.g. TabsCore):
 - `app/components/01.atoms/navigation/tabs/TabsCore.vue`
 - `app/components/accordian/AccordianCore.vue`
 - `app/components/02.molecules/stepper-list/StepperList.vue`
-- `app/components/view-timeline/WipeAwayVertical.vue`
+- `app/components/01.atoms/animations/view-timeline/WipeAwayVertical.vue`
 
 ---
 

package/.claude/skills/components/alert-mask-core.md

@@ -0,0 +1,84 @@
+---
+name: AlertMaskCore
+description: AlertMaskCore SVG border/background mask sized to slotted content; config-prop-driven geometry/colour, no CSS token API
+type: reference
+---
+
+# AlertMaskCore
+
+## Overview
+
+`AlertMaskCore` draws a border + background around its default slot content using an SVG `<mask>`,
+sized to the content's measured dimensions via `ResizeObserver`. It's the low-level primitive
+`AlertMaskedContent` (`app/components/02.molecules/alert-masked-content/`) builds on for its
+accent-bordered alert shape.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `config` | `AlertMaskConfig` | `{}` | Border/background colour and geometry (see below). All fields optional. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
+
+### `AlertMaskConfig` (`app/types/components/alert-mask-core.d.ts`)
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `backgroundColour` | `string` | `"rgba(0,0,0,0.25)"` | Inner fill colour. |
+| `borderColour` | `string` | `"var(--orange-08)"` | Border fill colour. |
+| `radiusLeft` | `number` | `12` | Left-side corner radius (px). |
+| `radiusRight` | `number` | `12` | Right-side corner radius (px). |
+| `borderLeft` | `number` | `8` | Left border thickness (px). |
+| `borderTop` | `number` | `8` | Top border thickness (px). |
+| `borderRight` | `number` | `8` | Right border thickness (px). |
+| `borderBottom` | `number` | `8` | Bottom border thickness (px). |
+
+## Basic usage
+
+```vue
+<AlertMaskCore>
+  <p>Alert content</p>
+</AlertMaskCore>
+
+<AlertMaskCore
+  :config="{
+    borderColour: 'var(--theme-accent)',
+    backgroundColour: 'rgba(0, 0, 0, 0.3)',
+    radiusLeft: 8,
+    radiusRight: 4,
+    borderLeft: 6,
+    borderTop: 1,
+    borderRight: 1,
+    borderBottom: 1,
+  }"
+>
+  <p>Accent-bordered alert content</p>
+</AlertMaskCore>
+```
+
+## How it works
+
+- The default-slot content is measured via `ResizeObserver` (initial measurement runs after
+  `nextTick` on mount).
+- An SVG outer path (rounded rect using `radiusLeft`/`radiusRight`) and inner path (the same rect
+  inset by the border thicknesses) are computed from that measurement, and the region between them
+  is masked to `borderColour`; the inner region is filled with `backgroundColour`.
+- The slot content itself sits in a separate `.alert-mask-content` div, inset by the same border
+  thicknesses via internal `--_inset-*` custom properties, so it visually sits inside the drawn
+  border without overlapping it.
+
+## No CSS token API
+
+Unlike most components in this library, `AlertMaskCore` has no public `--alert-mask-core-*` CSS
+custom properties — the SVG path geometry can't be driven by `var()`, so `config` is the entire
+override surface (colour included). See CONSUMER-STYLING.md.
+
+## Notes
+
+- 2026-09-20 migration: moved from `app/components/alert-mask/` (unplaced) into
+  `01.atoms/alert-mask/`; converted from options-style `defineProps({...})` to
+  `interface Props` + `withDefaults`; renamed the internal `--alertHeight`/`--insetInlineStart`/
+  `--insetInlineEnd`/`--insetBlockStart`/`--insetBlockEnd` custom properties to private
+  `--_height`/`--_inset-inline-start`/`--_inset-inline-end`/`--_inset-block-start`/
+  `--_inset-block-end` (they're JS-computed plumbing, not a consumer override surface — `config`
+  already covers that). No behaviour change.

package/.claude/skills/components/canvas-switcher.md

@@ -47,7 +47,7 @@ const canvasName = ref<MediaCanvas>("desktopCanvas");
 The selected value doubles as a utility class name: `CanvasSwitcher`'s stylesheet also declares
 `.mobileCanvas`/`.tabletCanvas`/`.laptopCanvas`/`.desktopCanvas`/`.fullWidthCanvas` (max-width
 utilities, not scoped to `.canvas-switcher`), so binding `:class="canvasName"` directly onto a
-preview wrapper constrains it to match — see `LayoutGridA`/`LayoutGridB` stories for the pattern.
+preview wrapper constrains it to match — see `DashboardQuadGrid`/`DashboardStatsGrid` stories for the pattern.
 These classes only ship in the bundle once `CanvasSwitcher` (or another importer of them) is
 actually imported somewhere, since Nuxt only bundles a component's SFC styles when it's used.
 

package/.claude/skills/components/carousel-flip.md

@@ -1,188 +1,132 @@
+---
+name: CarouselFlip
+description: CarouselFlip FLIP-animated multi-item carousel — named dynamic slots (per data id), swipe/keyboard/marker navigation, button layout variants, CSS tokens, consumer styling
+type: reference
+---
+
 # CarouselFlip
 
 ## Overview
 
-A FLIP-animated carousel that reorders items in the DOM using CSS `order` and animates transitions with the FLIP technique (First, Last, Invert, Play). Supports swipe, keyboard navigation, and marker dots. The prev/next buttons and controls bar can be placed in several layouts via a single prop.
-
----
+`CarouselFlip` is a multi-item carousel that reorders its items via the FLIP animation technique
+(First-Last-Invert-Play) on navigation, rather than a simple track-translate. Items are named
+dynamic slots keyed by `carouselDataIds`. It supports swipe, arrow-key, marker-click, and
+prev/next-button navigation, and four `buttonLayout` variants for positioning the prev/next
+buttons relative to the marker controls.
 
-## Implementation guide
+Has live production usage on instepreflexology — check before making a breaking change to its
+default rendered output.
 
-When a dev asks to implement CarouselFlip, work through the following questions before writing any code. Each answer maps directly to a prop or CSS decision. You do not need to ask all questions at once — use context clues where the answer is obvious.
+## Props
 
-### Step 1 — Data source
-
-Ask: **"Where is the carousel data coming from — a static array, an API, or a Nuxt `useFetch`?"**
-
-- **Static array**: Define `carouselDataIds` directly as a `const`.
-- **API / useFetch**: Derive `carouselDataIds` as a `computed` from the response. Gate the component with `v-if="status === 'success'"` to avoid a flash of empty slots.
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `carouselDataIds` | `string[]` | `[]` | Slot names, in display order. One item renders per id. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra CSS classes on the root element. |
+| `transitionSpeed` | `number` | `200` | Transition duration in ms. |
+| `allowCarouselOverflow` | `boolean` | `false` | Allows items to overflow the item track horizontally instead of clipping. |
+| `useFlipAnimation` | `boolean` | `false` | Changes the initial item offset used in the FLIP reorder calculation. |
+| `useSpringEffect` | `boolean` | `false` | Uses `var(--spring-easing)` as the transition timing function instead of `ease`. |
+| `buttonLayout` | `"sides" \| "controls-flanking" \| "controls-grouped-right" \| "overlay"` | `"sides"` | Where the prev/next buttons sit relative to the carousel/controls. |
+| `showControls` | `boolean` | `true` | Shows/hides the marker (dot) controls bar. Prev/next buttons remain regardless. |
+| `ariaLabel` | `string` | `"Image carousel"` | `aria-label` on the root region — override for localisation. |
+| `itemsAriaLabel` | `string` | `"Carousel items"` | `aria-label` on the item group — override for localisation. |
+| `previousLabel` | `string` | `"Go to previous item"` | Prev button `aria-label` — override for localisation. |
+| `nextLabel` | `string` | `"Go to next item"` | Next button `aria-label` — override for localisation. |
+| `jumpToItemLabel` | `string` | `"Jump to item"` | Marker button `aria-label` prefix — the 1-based index is appended (`"Jump to item 3"`). |
+| `itemPositionAnnouncement` | `(current: number, total: number) => string` | `` (current, total) => `Item ${current} of ${total}` `` | Builds the screen-reader live-region text on navigation — override for localisation or a different phrasing. |
+| `prevIcon` | `string` | `"ic:outline-keyboard-arrow-left"` | Iconify name for the previous button icon. Ignored if the `prev-icon` slot is used. |
+| `nextIcon` | `string` | `"ic:outline-keyboard-arrow-right"` | Iconify name for the next button icon. Ignored if the `next-icon` slot is used. |
+
+## Slots
+
+One dynamically-named slot per `carouselDataIds` entry, named after that id:
 
 ```vue
-<!-- API pattern -->
-const { data, status } = await useFetch<MyType>("/api/items");
-const carouselDataIds = computed(() => data.value?.items.map(i => i.id) ?? []);
-
-<CarouselFlip v-if="status === 'success'" :carousel-data-ids="carouselDataIds">
-  <template v-for="item in data.items" :key="item.id" #[item.id]>
-    <!-- slot content -->
-  </template>
+<CarouselFlip :carousel-data-ids="['slide-1', 'slide-2', 'slide-3']">
+  <template #slide-1><img src="/a.jpg" alt="A" /></template>
+  <template #slide-2><img src="/b.jpg" alt="B" /></template>
+  <template #slide-3><img src="/c.jpg" alt="C" /></template>
 </CarouselFlip>
 ```
 
-### Step 2 — Button layout
-
-Ask: **"Where should the prev/next buttons sit?"** Show these options:
-
-| Value | Visual description |
-|---|---|
-| `"sides"` | Buttons float on the left and right edges of the carousel frame, centred vertically — the classic look |
-| `"controls-flanking"` | Buttons move down into the controls row: prev · markers · next |
-| `"controls-grouped-right"` | Markers stretch left, both buttons grouped together at the far right of the controls row |
-| `"overlay"` | Buttons stay on the sides; the markers bar overlays the bottom edge of the carousel frame |
-
-Set via `:button-layout="..."`. Default is `"sides"`.
-
-### Step 3 — Show or hide the markers bar
-
-Ask: **"Do you want the dot/marker navigation bar visible?"**
-
-- **Yes** (default): omit the prop or pass `:show-controls="true"`.
-- **No**: pass `:show-controls="false"`. The element is fully removed from the DOM — no layout space, no keyboard listener.
-
-> If `showControls` is false and `buttonLayout` is `"controls-flanking"` or `"controls-grouped-right"`, the controls row collapses entirely — only the buttons remain. Recommend switching `buttonLayout` to `"sides"` or `"overlay"` in that case.
-
-### Step 4 — Edge peek (overflow)
-
-Ask: **"Should adjacent carousel items peek in from the sides?"**
-
-- **No peek** (default): `:allow-carousel-overflow="false"` — clean, contained look.
-- **Peek visible**: `:allow-carousel-overflow="true"` — items bleed slightly out of the container. Requires CSS custom properties to control how much:
-
-```css
-.my-carousel.carousel-flip {
-  --_carousel-item-track-gap: 16px;
-  --_carousel-item-edge-preview-width: 32px; /* keep at 2× track-gap */
-  --_carousel-container-max-inline-size: 900px;
-}
-```
-
-### Step 5 — Animation style
-
-Ask: **"What animation feel are you going for?"**
-
-| Prop | Effect |
-|---|---|
-| `:use-flip-animation="false"` (default) | Slides — items translate horizontally |
-| `:use-flip-animation="true"` | FLIP reorder — items swap position with a physics-aware delta animation |
-| `:use-spring-effect="true"` | Adds spring easing to FLIP transitions. Requires `var(--spring-easing)` in the theme |
-| `:transition-speed="400"` | Duration in ms. Default `200`. Recommended range: `200`–`1200` |
-
-### Step 6 — Minimal working implementation
-
-Once the above decisions are made, assemble the component:
+`prev-icon`/`next-icon` replace the prev/next button icon entirely — use these instead of
+`prevIcon`/`nextIcon` when an Iconify name isn't enough (custom SVG, a different icon set):
 
 ```vue
-<CarouselFlip
-  :carousel-data-ids="carouselDataIds"
-  :allow-carousel-overflow="true"
-  :transition-speed="600"
-  :use-flip-animation="true"
-  :use-spring-effect="false"
-  button-layout="sides"
-  :show-controls="true"
-  :style-class-passthrough="['my-carousel']"
->
-  <template v-for="item in items" :key="item.id" #[item.id]>
-    <div class="my-carousel__item">
-      <!-- item content -->
-    </div>
-  </template>
+<CarouselFlip :carousel-data-ids="ids">
+  <template #prev-icon><MyCustomArrowLeft /></template>
+  <template #next-icon><MyCustomArrowRight /></template>
+  ...
 </CarouselFlip>
 ```
 
-### Step 7 — Style the component
-
-Always scope overrides using `styleClassPassthrough` + a page/section wrapper class. Required tokens for a usable carousel:
-
-```css
-.my-carousel.carousel-flip {
-  --_carousel-item-track-gap: 16px;
-  --_carousel-container-max-inline-size: 900px;
-  --_carousel-item-edge-preview-width: 32px; /* 2× track-gap when overflow is on */
-
-  /* Items */
-  .item {
-    border-radius: 1.2rem;
-    overflow: hidden;
-  }
-
-  /* Markers */
-  .btn-marker {
-    width: 10px;
-    height: 10px;
-    border-radius: 100vw;
-    background: oklch(70% 0 0);
-
-    &.active { background: white; }
-  }
-
-  /* Prev/next buttons */
-  .btn-action {
-    padding: 10px;
-    background: oklch(0% 0 0 / 0.4);
-    border: none;
-    border-radius: 100vw;
-    color: white;
-  }
-}
-```
-
----
-
-## Props reference
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `carouselDataIds` | `string[]` | `[]` | Ordered list of unique IDs — each becomes a named slot |
-| `transitionSpeed` | `number` | `200` | Animation duration in ms |
-| `allowCarouselOverflow` | `boolean` | `false` | Allows peeking items outside the container bounds |
-| `useFlipAnimation` | `boolean` | `false` | Enables FLIP reorder animation on prev/next |
-| `useSpringEffect` | `boolean` | `false` | Uses spring easing (`var(--spring-easing)`) instead of `ease` |
-| `buttonLayout` | `"sides" \| "controls-flanking" \| "controls-grouped-right" \| "overlay"` | `"sides"` | Controls placement of prev/next buttons relative to the carousel frame and controls bar |
-| `showControls` | `boolean` | `true` | Show or hide the markers/controls bar. When `false` the element is removed from the DOM; `controlsContainerRef` becomes null and its keyboard listener detaches automatically |
-| `styleClassPassthrough` | `string \| string[]` | `[]` | Classes applied to the root element |
-
-## CSS custom properties
-
-| Property | Purpose |
-|---|---|
-| `--_carousel-item-track-gap` | Gap between carousel items (default `10px`) |
-| `--_carousel-container-max-inline-size` | Max width of the visible carousel window |
-| `--_carousel-item-edge-preview-width` | How much of adjacent items to reveal (edge peek). Keep at `2× --_carousel-item-track-gap` |
-| `--_carousel-display-max-width` | Max width of the whole component inc. controls |
-
-## HTML structure
-
-```text
-section.carousel-flip               ← grid root, data-button-layout="..."
-  div.item-container                ← grid-area: carousel — flex row of items
-    div.item[data-id]               ← one per carouselDataIds entry
-  div.controls-container            ← grid-area: controls — markers bar (v-if="showControls")
-    div.markers-container
-      ul.markers-list
-        li.markers-item
-          button.btn-marker
-  div.buttons-container             ← display: contents by default (transparent to grid)
-    button.btn-action.btn-prev      ← grid-area: prev (row 1, col 1)
-    button.btn-action.btn-next      ← grid-area: next (row 1, col 3)
-```
-
-`buttons-container` uses `display: contents` so `.btn-prev`/`.btn-next` participate directly in the parent grid. In the `controls-grouped-right` variant the component sets `display: flex` on it, making it the grid child instead.
+## Navigation
+
+- **Swipe** (touch): left swipe → next, right swipe → previous.
+- **Keyboard**: `ArrowLeft`/`ArrowRight` on either the item track or the controls bar (both are
+  `tabindex="0"`).
+- **Marker click**: jumps directly to that item.
+- **Prev/next buttons**: always rendered, regardless of `showControls`.
+- All navigation wraps around at the ends.
+
+## `buttonLayout` variants
+
+- `"sides"` (default): prev/next buttons flank the item track (CSS grid areas `prev`/`next`).
+- `"controls-flanking"`: prev/next buttons sit in the row below, flanking the marker controls.
+- `"controls-grouped-right"`: markers centred, prev/next buttons grouped to the right of them.
+- `"overlay"`: markers float over the bottom edge of the item track instead of occupying their
+  own grid row.
+
+## CSS token API
+
+See [CONSUMER-STYLING.md](../../app/components/03.organisms/image-galleries/carousel-flip/CONSUMER-STYLING.md).
+
+| Token | Default | Controls |
+|---|---|---|
+| `--carousel-flip-gap` | `1rem` | Gap between items inside the item track |
+| `--carousel-flip-layout-gap` | `1rem` | Grid gap between the prev/carousel/next/controls areas |
+| `--carousel-flip-display-max-width` | `80rem` | Max width of the item track and the controls bar |
+| `--carousel-flip-item-max-width` | `80rem` | Max width of a single item, before subtracting the edge-preview width |
+| `--carousel-flip-edge-preview-width` | `4rem` | How much of the neighbouring items peek in at each edge |
+| `--carousel-flip-marker-gap` | `1rem` | Gap between marker (dot) buttons |
+| `--carousel-flip-marker-active-colour` | `light-dark(var(--slate-10), var(--slate-00))` | Active marker background colour |
+| `--carousel-flip-button-background-colour` | `light-dark(white, var(--slate-08))` | Prev/next button background colour |
+| `--carousel-flip-button-border-width` | `0.1rem` | Prev/next button border width |
+| `--carousel-flip-button-border-colour` | `light-dark(hsl(0, 29%, 3%), hsl(0, 0%, 92%))` | Prev/next button border colour |
+| `--carousel-flip-button-border-radius` | `100vw` | Prev/next button corner radius |
+| `--carousel-flip-button-padding` | `0.8rem` | Prev/next button padding |
+| `--carousel-flip-button-icon-size` | `2.4rem` | Prev/next button icon glyph size |
+| `--carousel-flip-buttons-gap` | `1rem` | Gap between prev/next buttons in the `controls-grouped-right` layout |
+| `--carousel-flip-overlay-controls-offset` | `1rem` | Distance of the controls bar from the bottom edge in the `overlay` layout |
+| `--carousel-flip-focus-outline-width` | `0.2rem` | Marker button focus-visible outline width |
+| `--carousel-flip-focus-outline-colour` | `var(--theme-ring)` | Marker button focus-visible outline colour |
+| `--carousel-flip-focus-outline-offset` | `0.2rem` | Marker button focus-visible outline offset |
+
+## Accessibility
+
+- Reduced motion: both the CSS transform transition and the JS-driven FLIP reorder transition
+  are skipped when `prefers-reduced-motion: reduce` is set — items still reorder, just instantly.
+- Marker buttons previously had `outline: 1px solid transparent`, which suppressed the focus ring
+  with no replacement. Fixed 2026-09-21 — they now get a visible `:focus-visible` outline via
+  `--carousel-flip-focus-outline-*`.
+- All interactive controls have accessible names via the label props above.
 
 ## Notes
 
-- **Opacity fade-in**: The root starts at `opacity: 0` and gets `.mounted` (opacity 1) after `initialSetup()` completes. This prevents a flash of unstyled layout on mount.
-- **z-index**: `.btn-prev`/`.btn-next` have `z-index: 1` to sit above `.item-container` which uses `isolation: isolate` (carousel items are translated and can overlap the button columns).
-- **ResizeObserver**: `initialSetup()` re-runs on resize to recalculate item widths. CSS `translate` on `.item` is driven by the measured `itemWidth` via `v-bind`.
-- **Spring easing**: `useSpringEffect` switches to `var(--spring-easing)`. Make sure this custom property is defined in your theme or global CSS when enabling it.
-- **buttonLayout + showControls combo**: `"controls-flanking"` and `"controls-grouped-right"` place buttons in the controls row. If `showControls` is false that row collapses — use `"sides"` or `"overlay"` instead.
+- Migrated from `app/components/carousels/CarouselFlip.vue` (unplaced, legacy location) to
+  `03.organisms/image-galleries/carousel-flip/` on 2026-09-21, alongside `SliderGallery`.
+- Sibling components `CarouselBasic` and `CarouselInfinite` were deleted in the same migration —
+  they had no consumer usage anywhere and were never fully built out (no tests/story/skill for
+  `CarouselInfinite`; `CarouselBasic`'s active-marker colour was hardcoded to plain `red`).
+- **Bug fixed 2026-09-21**: `--carousel-flip-display-max-width`/`--carousel-flip-item-max-width`/
+  `--carousel-flip-edge-preview-width` were previously referenced as `--_carousel-display-max-width`
+  /`--_carousel-container-max-inline-size`/`--_carousel-item-edge-preview-width` — private custom
+  properties that were never declared anywhere, with no fallback. Per CSS spec this makes the
+  whole declaration invalid at computed-value time, so the item edge-preview offset and the
+  width caps were silently never applying in production. Now declared as real public tokens with
+  real defaults (`80rem`/`80rem`/`4rem`) — this is a visible change to the live carousel on
+  instepreflexology, done deliberately after confirming with the maintainer.
+- Removed dead commented-out code in `itemWidthOffsetStr`'s computed (an unreachable
+  `if (props.allowCarouselOverflow)` branch, entirely commented out, that duplicated the live
+  branch's logic).

package/.claude/skills/components/container-glow.md

@@ -0,0 +1,123 @@
+---
+name: ContainerGlow
+description: ContainerGlow pointer-proximity glow-border cards, named dynamic slots (one card per slot), config-prop-driven layout/interaction, full CSS token API for static visuals
+type: reference
+---
+
+# ContainerGlow
+
+## Overview
+
+`ContainerGlow` renders one "glow card" per named default slot the consumer provides — each card
+tracks the pointer and reveals an animated conic-gradient glow border when the pointer is near it.
+It uses the named dynamic slots pattern (`v-for="(_, name) in $slots"`), so there's no
+`itemCount`-style prop; the consumer's slot names are the source of truth.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `"div" \| "li" \| "article" \| "section"` | `"div"` | HTML tag rendered for each card. |
+| `config` | `ContainerGlowConfig` | `{}` | Proximity/spread/blur/gap/direction/inactive-opacity — see below. All fields optional. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root wrapper element. |
+
+### `ContainerGlowConfig` (`app/types/components/container-glow.d.ts`)
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `proximity` | `number` | `40` | Pointer distance (px) at which a card starts glowing. |
+| `spread` | `number` | `80` | Angular spread of the glow (degrees). |
+| `blur` | `number` | `20` | Blur applied to the glow layer (px). |
+| `gap` | `number` | `32` | Gap between cards in the wrapper (px). |
+| `vertical` | `boolean` | `false` | Stack cards vertically instead of horizontally. |
+| `inactiveOpacity` | `number` | `0` | Glow opacity when the pointer isn't nearby. |
+
+## Slots
+
+Named dynamic — every slot the consumer provides renders as one glow card. There is no fixed slot
+name list or count prop.
+
+```vue
+<ContainerGlow>
+  <template #one><p>Card one</p></template>
+  <template #two><p>Card two</p></template>
+</ContainerGlow>
+```
+
+## Basic usage
+
+```vue
+<ContainerGlow :config="{ blur: 40, vertical: true }">
+  <template #pricing><p>Starter plan</p></template>
+  <template #featured><p>Pro plan</p></template>
+</ContainerGlow>
+```
+
+## How it works
+
+- A single `pointermove` listener on `document.body` (added on mount, removed via `AbortController`
+  on unmount) drives every card at once, throttled to one `requestAnimationFrame` per frame.
+- For each card, the listener checks whether the pointer is within `config.proximity` px of the
+  card's bounding box. If so, it computes the pointer's angle relative to the card centre and sets
+  that on a private `--_start` custom property (registered via `@property` so it participates in
+  the conic-gradient mask math); the card's `--_opacity-active` is set to `1` (or
+  `config.inactiveOpacity` otherwise).
+- Two pseudo-elements (`::before`/`::after`) and a `.glows` layer combine a thin proximity ring, a
+  coloured gradient glow, and a blurred backdrop glow, all masked by conic gradients driven from
+  `--_start` and `--_spread`.
+- `config.gap`/`config.blur`/`config.spread`/`config.vertical` are applied once (and on every
+  `config` change, via a deep `watch`) as private custom properties on the wrapper, which cards
+  inherit.
+
+## Styling
+
+Card background/padding/sizing/border-radius/highlight-colour/brightness/transition-duration and
+the glow gradient itself are public CSS custom properties — see `CONSUMER-STYLING.md` for the full
+token table. Layout and interaction behaviour (proximity, spread, blur, gap, direction, inactive
+opacity) go through the `config` prop instead, since they're computed in JavaScript per pointer
+event rather than static CSS.
+
+```vue
+<ContainerGlow style="--container-glow-border-radius: 4px; --container-glow-brightness: 2;">
+  <template #cta><p>Sharper, brighter glow</p></template>
+</ContainerGlow>
+```
+
+## Motion
+
+The opacity transition is disabled under `prefers-reduced-motion: reduce` (proximity state changes
+apply instantly instead of fading).
+
+## Notes
+
+- 2026-09-20 migration: renamed from `ContainerGlowCore` to `ContainerGlow` — the `Core` suffix in
+  this library denotes a primitive with a non-Core wrapper built on top of it (`InputTextCore` →
+  `InputTextWithLabel`, `AlertMaskCore` → `AlertMaskedContent`), and this component has no such
+  sibling. Checked all consumer repos first; found one real usage in the defunct
+  `nuxt-extend-nuxt-forms` demo app, left as a follow-up for that repo rather than edited here.
+- Moved from `app/components/container-glow/` (unplaced) into
+  `01.atoms/animations/container-glow/`.
+- The `Config` type was previously an inline, non-exported interface with **all fields required**,
+  so passing a partial `:config="{ blur: 40 }"` silently dropped every other field to `undefined`
+  (breaking the proximity/spread/gap/direction maths). Fixed: all `ContainerGlowConfig` fields are
+  now optional, merged against defaults internally, and the type is exported from
+  `app/types/components/container-glow.d.ts` for consumers to import.
+- `config.gap` and `config.vertical` were computed in JS (`--gap`/`--direction` custom properties
+  set on the wrapper) but never actually consumed anywhere in the CSS — the wrapper's flex layout
+  hardcoded `gap: 3.2rem` with no `flex-direction` at all, so both fields were silently inert.
+  Fixed by wiring the wrapper's `gap`/`flex-direction` to the (now privately-prefixed) computed
+  values.
+- `@property --start` was nested inside the `.container-glow-wrapper` style rule, which is invalid
+  CSS (`@property` must be a top-level or `@layer`-nested rule, not nested inside a normal
+  selector) — browsers silently drop invalid nested at-rules, so the custom property was never
+  actually type-registered. Moved to a top-level declaration inside `@layer components`, renamed
+  `--start` → `--_start` to match the private-token convention.
+- Removed a dead, never-referenced `--alpha: 0` custom property that appeared on two pseudo-element
+  rules.
+- Promoted the previously hardcoded background/padding/aspect-ratio/border-radius/min-max-width/
+  content-gap/highlight-colour/brightness/transition-duration and gradient colours to public
+  `--container-glow-*` tokens; the JS/config-driven proximity/spread/blur/gap/direction/opacity
+  custom properties were renamed to `--_start`/`--_opacity-active`/`--_gap`/`--_blur`/`--_spread`/
+  `--_direction`/`--_gradient` to match the private-token convention (they're config-driven, not a
+  direct CSS override surface).
+- Added a `prefers-reduced-motion: reduce` guard disabling the opacity transition.