srcdev-nuxt-components 9.6.0 → 9.6.2

package/.claude/skills/components/tabbed-content.md

@@ -0,0 +1,300 @@
+---
+name: TabbedContent
+description: TabbedContent tab list/panel widget (was TabsCore) — indexed dynamic slots, arrow-key navigation, moving hover/active/underline indicators, CSS tokens
+type: reference
+---
+
+# TabbedContent
+
+> **Renamed 2026-10-07:** `TabsCore` → `TabbedContent`, moved from `01.atoms/navigation/tabs/` to
+> `01.atoms/tabbed-content/`. Root class `.tabs-core` → `.tabbed-content`; inner classes
+> `.tabs-list` → `.tabbed-content-list`, `.tabs-list-item` → `.tabbed-content-trigger`,
+> `.nav__hovered`/`.nav__active`/`.nav__active-indicator` → `.tabbed-content-indicator-hover`/
+> `-active`/`-underline`, `.tab-content-wrapper` → `.tabbed-content-panels`, `.tab-content` →
+> `.tabbed-content-panel`. Tokens keep their `--tabs-*` names. Slot names are unchanged.
+
+## Overview
+
+`TabbedContent` renders a WAI-ARIA tablist and its panels from indexed slots. The number of tabs is
+set via `itemCount`; each tab's trigger and content come from `tab-{n}-trigger`/`tab-{n}-content`
+slots. Indexed slots (rather than named dynamic slots) are used deliberately: `itemCount` is needed
+for ARIA linking across the two parallel loops (triggers and panels), not just the slot loop itself.
+
+Moving decorators track pointer/keyboard state: a hover highlight, an active-tab highlight, a
+thick underline/sideline under the active tab, and a thin one (`--tabs-hover-underline-indicator-height`,
+default `0.1rem`, added 2026-10-07) following the hovered tab. `trackHover` / `trackActive` /
+`trackIndicator` turn them off; the hover underline needs both `trackHover` and `trackIndicator`.
+
+Not navigation: for page/site navigation use `ResponsiveHeader` (which replaced `TabNavigation`).
+
+**Location**: `app/components/01.atoms/tabbed-content/`
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `itemCount` | `number` | — | **Required.** Number of tabs; drives both slot loops. Rounded down; 0, negative or `NaN` renders no tabs. Can change after mount (the active tab is kept if it still exists, otherwise the first tab becomes active). |
+| `axis` | `"x" \| "y"` | `"x"` | Horizontal row or vertical column. Also sets `aria-orientation` and which arrow keys move between tabs. Reactive. |
+| `transitionDuration` | `number` | `200` | ms duration of the moving indicators. Negative values clamp to 0. Reactive. |
+| `trackHover` | `boolean` | `true` | Moving hover highlight. Reactive. |
+| `trackActive` | `boolean` | `true` | Moving active-tab highlight. Reactive. |
+| `trackIndicator` | `boolean` | `true` | Moving underline/sideline. Reactive. |
+| `overflowMode` | `"menu" \| "scroll"` | `"menu"` | `axis="x"` only. `menu`: tabs that don't fit collapse from the end into a "More" button and menu (added 2026-10-07). `scroll`: the tab row scrolls sideways inside itself. Reactive. |
+| `ariaLabel` | `string` | `"Tabs"` | `aria-label` on the tablist; override for localisation. |
+| `moreLabel` | `string` | `"More tabs"` | Accessible name of the More button and its menu; override for localisation. |
+| `moreIcon` | `string` | `"lucide:ellipsis"` | Icon on the More button. |
+| `moreActiveIcon` | `string` | `"lucide:chevron-down"` | Icon after the active tab's label on the More button while that tab is collapsed. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Classes on the root `.tabbed-content` (was the tab list before 2026-10-07). |
+
+## Slots
+
+For each index `0..itemCount-1`:
+
+- `tab-{n}-trigger` — content of the tab button. May contain icons or other elements; a click
+  anywhere inside the button activates the tab.
+- `tab-{n}-content` — content of that tab's panel.
+
+```vue
+<TabbedContent :item-count="2" aria-label="Product details">
+  <template #tab-0-trigger>Overview</template>
+  <template #tab-0-content>Overview content…</template>
+  <template #tab-1-trigger>Specs</template>
+  <template #tab-1-content>Specs content…</template>
+</TabbedContent>
+```
+
+## Accessibility behaviour
+
+- `role="tablist"` is a `<div>` that owns the `role="tab"` buttons directly (it used to be a
+  `<ul>` with plain `<li>`s in between, an ARIA required-children violation, with the indicator
+  `<div>`s injected into the list by JS). Indicators are `aria-hidden` `<span>`s rendered by the
+  template.
+- `aria-orientation` follows `axis`.
+- Each trigger has `aria-controls` pointing at its panel; each panel has `aria-labelledby` pointing
+  at its trigger. IDs are prefixed with `useId()`, so several instances on one page don't clash
+  (before 2026-10-07 every instance used `tab-0-trigger` etc.).
+- Inactive panels carry the `hidden` attribute; the first panel is visible in the SSR markup.
+  Panels have `tabindex="0"` so keyboard users can reach scrollable panel content.
+- Roving tabindex: only the active trigger has `tabindex="0"`.
+- Arrow keys move focus and activate the target tab (automatic activation): `ArrowLeft`/`ArrowRight`
+  on `axis="x"`, `ArrowUp`/`ArrowDown` on `axis="y"`, wrapping at the ends; `Home`/`End` jump to
+  the first/last tab. Not mirrored for RTL.
+- Focus ring: `--tabs-focus-ring-colour` (default `--theme-border-focus`) on triggers and panels.
+
+## Overflow menu (`overflowMode="menu"`, default, since 2026-10-07)
+
+- On `axis="x"`, a ResizeObserver on the bar and the tablist measures the tabs (widths cached
+  while each is visible) and collapses the ones that don't fit, from the end, into a "More" button
+  at the end of the tab row (`--tabs-more-margin-inline-start: auto`; `0` puts it straight after
+  the last visible tab). Collapsed triggers get `hidden`, so they leave the tablist; the menu lists
+  them as `role="menuitemradio"` rows (re-rendering each tab's own `tab-{n}-trigger` slot), with
+  `aria-checked` on the active one. Picking one activates that tab and returns focus to the
+  More button.
+- The More button is outside `role="tablist"` (`aria-haspopup="menu"`, `aria-label` from
+  `moreLabel`). While nothing has overflowed it stays in the DOM but idle (invisible,
+  `tabindex="-1"`) so its width can be measured.
+- When the active tab is collapsed, the More button shows that tab's own trigger slot plus a
+  chevron (instead of `⋯`), gets `.is-active` and the active/hover indicators sit on it. A
+  ResizeObserver on the button re-measures, so if the wider button no longer fits, the tab before
+  it moves into the menu (and comes back when a visible tab is picked). The button has no
+  `aria-label`: `moreLabel` is visually hidden text inside it, so its name ("Shipping, More tabs")
+  always contains the visible label (WCAG 2.5.3). Trigger slot content renders up to three times
+  (tab, menu row, More button), so don't put `id`s in it.
+- Indicators sit on the More button while the active tab is collapsed (`useTabs` swaps any
+  hidden tab for `[data-more-trigger]` when positioning). Arrow keys move between visible tabs only, and the first visible tab keeps `tabindex="0"` so
+  the tablist stays reachable with Tab.
+- The popover uses `useAnchoredPopover` (Popover API + anchor positioning, with the Safari 16/17
+  fallbacks), like `SelectMenu` and `ActionMenu`. Menu keys: Arrow Up/Down (wrapping),
+  Home/End, Escape (light dismiss), Tab closes.
+- Not on `axis="y"`: a column doesn't run out of width.
+
+## Layout under hostile data
+
+- With `overflowMode="scroll"` the tab row scrolls sideways inside itself; the indicators scroll
+  with it. In both modes triggers never shrink, and wrap their label past
+  `--tabs-list-item-max-inline-size` (`24rem`).
+- On `axis="y"` the tab column is capped at `--tabs-axis-y-list-max-inline-size` (`50%`).
+- Panels wrap unbroken strings (`overflow-wrap: anywhere`).
+- No line-clamp token: trigger and panel text is consumer slot markup, so the consumer controls it.
+
+## CSS custom properties
+
+See `CONSUMER-STYLING.md` in the component folder for the full `--tabs-*` token API. Colour
+defaults come from the `--theme-*` slots (changed 2026-10-07, were fixed `--slate-*` steps with a
+dark panel).
+
+## useTabs
+
+`app/composables/useTabs.ts` drives the behaviour and is only used by this component. Its nav ref
+is `.tabbed-content-bar` (the indicators' positioning box); it also exposes `activeIndex` and
+`activateTabByIndex()` for the More menu. It takes
+`axis`, `transitionDuration` and `trackHover` as getters (read at use time, so prop changes apply),
+and exposes `refreshTabs()`, which the component calls on mount and after any change to the tab
+count, axis or indicator props. Click/hover handlers use `event.currentTarget` (the button), not
+`event.target`, so clicking an icon inside a trigger works. Panels are matched to triggers by
+`data-tab-index`, not by position in the `v-for` ref array, since Vue doesn't keep that array in
+source order when the list changes.
+
+## Indicator motion: edge insets (2026-10-08)
+
+`useTabs.placeIndicator(kind, animate)` writes each indicator's two edges as insets from the
+bar's start/end along the axis (`--_{kind}-start` / `--_{kind}-end`), and the CSS transitions
+`left`/`right` (or `top`/`bottom`) separately. Moving forward, the start edge gets a delay of one
+duration (`--_{kind}-start-delay`); moving back, the end edge does. So the leading edge moves first
+and the trailing edge catches up: the same stretch effect as before, symmetric both ways, with no
+settle timer. CSS retargets each edge from its current position, so a quick second move can't
+pull an edge backwards. Hover and active have separate duration/delay variables.
+
+This replaced a `translate` + `scale` model (a bar-wide box translated to the tab's left and
+scaled to its width, plus a timeout to settle after a stretch, and one shared
+`--_transition-duration`). Rightward moves animated both properties together in the settle step,
+and the indicator visibly stepped back mid-move (reported for hover, then n to n+x clicks); the
+computed values were always correct, the composition wasn't. Avoid reintroducing a transform
+pair for this.
+
+## Label colour under the sliding highlight (2026-10-08)
+
+With `trackActive`, `useTabs` re-checks every animation frame while the active indicator
+transitions (`trackCoverage`, for `transitionDuration` + 50ms) which visible tabs and the More
+button the indicator (`[data-active-indicator]`) covers by at least half, and toggles
+`data-under-active` on them (an attribute, not a class, so Vue's own class binding on the More
+button can't wipe it). CSS under `.tracks-active` colours by that attribute rather than
+`aria-selected`. The coverage window only ever extends (`coverageUntil`): a refresh landing
+mid-move (e.g. the More button resizing straight after a click) used to restart it with zero
+length, cancelling the per-frame checks while the highlight was still sliding and leaving stale
+colours (dark selected label, invisible neighbour). A More-button resize also re-places both
+indicators (`syncIndicators(true)`), since its box moves even when no tab changes sides, and an
+overflow change refreshes with `refreshTabs(true)` so an in-flight move retargets instead of
+snapping. This replaces the per-component timing trick `TripleToggleSwitch` uses (swap
+colour at half the slide), which only works for single-step moves; a tab jump passes under
+several labels.
+
+## Migration note (2026-10-07)
+
+Fixed during the compliance pass that renamed it:
+
+- Duplicate IDs across instances (above).
+- `event.target` in the click handler: clicking an element inside a trigger set the active tab to
+  that inner element, so no panel matched and every panel was hidden.
+- `axis`, `transitionDuration` and the `track*` flags were read once at setup, and a changed
+  `itemCount` was never picked up (new tabs had no roving tabindex and weren't navigable).
+- Dark-on-dark panel content by default, near-invisible focus ring, `styleClassPassthrough` on
+  the wrong element, unprefixed inner class names (pitfall #16).
+- A long label or many tabs pushed the page sideways.
+
+## Migration note (2026-09-15)
+
+Previously lived at `tabs/TabsCore.vue` with options-style `defineProps`, no tier folder, and
+several defects fixed in this pass:
+
+- `querySelectorAll("[data-nav-item")` was missing its closing `]` — an invalid selector that
+  some browsers tolerate but that throws in strict DOM implementations (including this repo's test
+  environment). Fixed to `"[data-nav-item]"`.
+- `aria-labelledby="channel-name"` was hardcoded on the tablist, pointing at an id that doesn't
+  exist anywhere in this library. Replaced with the new `ariaLabel` prop.
+- `border-bottom`/`border-left` on the tab list referenced `--_tabs-border-bottom`, a private CSS
+  variable that was never set anywhere (dead reference — the border never rendered). Promoted to
+  the public `--tabs-nav-border` token with a real default.
+- `tag`, `trackHover`, `trackActive`, and `trackIndicator` were all declared props with no effect
+  anywhere in the component or its composable (`useTabs`). `tag` had no coherent purpose (triggers
+  were always hardcoded `<button>`s) and was removed; the three `track*` flags were wired up to
+  actually gate their respective decorator elements, since removing them would have been a bigger
+  behavioural change than making them work as their names already implied.
+- Almost every colour/spacing/typography value in the `<style>` block was hardcoded with no
+  override hook at all (not even a private token) — promoted to public `--tabs-*` tokens.
+
+## Performance notes (2026-09-15)
+
+`useTabs` had a few real perf issues, fixed alongside the migration:
+
+- **Layout thrashing**: `moveActiveIndicator`/`moveHoveredIndicator`/`setFinalActivePositions`/
+  `setFinalHoveredPositions` used to interleave `offsetLeft`/`offsetWidth`/etc. reads with
+  `style.setProperty` writes, forcing a synchronous reflow between each pair. All layout reads are
+  now batched into local variables before any writes happen.
+- **`@mouseover` → `@mouseenter`**: the hover trigger listener used `mouseover`, which bubbles and
+  re-fires as the pointer crosses any child element inside the button. `mouseenter` fires exactly
+  once per tab entered.
+- **Debounced settle timers**: `moveActiveIndicator`/`moveHoveredIndicator` schedule a `setTimeout`
+  to snap the indicator to its exact final position once the CSS transition ends. Previously each
+  call scheduled a new timeout without clearing the last one, so moving the pointer quickly across
+  several tabs stacked up redundant pending timeouts. Now the previous timeout is cleared before
+  scheduling the next, and both are cleared in `onUnmounted`.
+- `handleTransitioningClass` called `.indexOf()` on the same two tabs repeatedly inside its loop
+  condition and body — now computed once per call.
+- `previousActiveTab` used `useState("previousActiveTab", ...)` with a fixed, unscoped key — every
+  `TabsCore` instance on a page would have shared that one piece of state. Not actually a
+  performance issue, but a correctness bug found while auditing this file; fixed by switching to a
+  plain per-instance `ref`, since this state doesn't need SSR/hydration sharing.
+
+## Fixed: hover/active label text could become unreadable against the indicator (2026-09-15)
+
+`--tabs-hover-indicator-text-colour` and `--tabs-active-indicator-text-colour` were set as `color`
+on `.nav__hovered`/`.nav__active` — decorative, empty, absolutely-positioned divs with no text
+content, so that `color` was dead CSS with no visible effect. The actual tab label
+(`.tabs-list-item`) used one shared `--tabs-list-item-colour-selected` token for hover, active,
+*and* transitioning alike, regardless of which of the two (potentially differently-coloured)
+indicator backgrounds was actually behind it at that moment. A consumer overriding only the hover
+indicator's background (or the active one) had no working lever to keep the label readable against
+it, and could end up with text the same colour as the background sliding behind it — this was the
+original defect noticed during this component's initial authoring, reported as "the button text
+became the same colour as the track item background and became invisible."
+
+Fixed by removing the dead `color` declarations from the two decorator divs and splitting
+`.tabs-list-item`'s combined `:hover, [aria-selected="true"], .transitioning` rule so hover uses
+`--tabs-hover-indicator-text-colour` and active uses `--tabs-list-item-colour-selected` falling
+back to `--tabs-active-indicator-text-colour` — each state's text colour now tracks the background
+actually behind it. See `CONSUMER-STYLING.md`'s "Tab-label text colour tracks the indicator behind
+it" section: overriding an indicator background without its matching text-colour token can still
+produce poor contrast (same tradeoff as any two independently-set colour tokens) — the fix makes
+the tokens functional, it doesn't auto-compute contrast.
+
+## Fixed: intermediate tab labels could go invisible during a multi-tab jump (2026-09-15)
+
+The first fix above wasn't the whole story. The exact repro that surfaced the rest of it: with tab
+1 active, hover then click tab 5 — the tabs in between briefly lost all visible text. Going the
+other direction (tab 5 active, hover then click tab 1) looked fine.
+
+Cause: `useTabs` had a `handleTransitioningClass` helper that added a `.transitioning` class to
+every tab spanned by a jump (previously shared by the `[aria-selected="true"]` colour rule fixed
+above), on the assumption the sliding indicator visually covers every spanned tab for the whole
+transition — so it force-applied the active text colour to all of them, for the full
+`transitionDuration`. It doesn't cover them the whole time: the indicator's "grow from anchor" CSS
+transition (see `moveActiveIndicator`/`moveHoveredIndicator`) keeps the box's leading edge pinned
+at the *old* tab's position on a forward move and only grows its width, so it only gradually sweeps
+across later tabs — a tab several positions away isn't actually covered until *late* in the
+transition. Recolouring it to the active text colour from the very start meant its label matched
+neither its own background nor the not-yet-arrived indicator, going invisible. A backward move
+animates position and width toward their final values together, so the box's rendered coverage is
+more consistent throughout — which is why that direction looked fine and made the bug easy to miss
+without a specific repro.
+
+Fixed by removing `handleTransitioningClass` and the `.transitioning` class entirely — it had no
+other purpose. Tabs spanned by a jump now keep their normal (inactive) styling throughout; only the
+newly-active tab (`[aria-selected="true"]`) and the currently-hovered tab (`:hover`) get their
+special colours. See `CONSUMER-STYLING.md`'s "Tabs spanned by a jump keep their normal styling".
+
+## Fixed: passed-over tab text still invisible under the active indicator specifically (2026-09-15)
+
+Removing `.transitioning` (previous fix) uncovered a second, pre-existing defect that
+`.transitioning`'s forced recolour had been accidentally masking the whole time: a non-active tab's
+normal text colour (`--tabs-list-item-colour`) was **exactly the same value** as the active
+indicator's background (`--tabs-active-indicator-colour`, same default) — this collision existed in
+the very first authored version of this component, not something introduced by any migration
+change. So whenever the active pill visually passes under (or briefly sits under) any tab that
+isn't itself marked active — which happens on every transition, single-step or distant, in either
+direction — that tab's text became literally the same colour as the background sliding beneath it.
+`--tabs-hover-indicator-colour`'s default never had this problem since it doesn't coincide with the
+inactive text default.
+
+Fixed by changing `--tabs-active-indicator-colour`'s default to one step in from the extreme,
+still clearly the boldest of the three indicator colours, but no longer numerically identical to
+`--tabs-list-item-colour`'s default. `--tabs-active-indicator-text-colour`/
+`--tabs-list-item-colour-selected` (used by the truly active tab) still contrast fine against the
+new value. See `CONSUMER-STYLING.md` for the note on keeping these two tokens from colliding again
+if you override either one.
+
+## Colour token defaults (2026-10-07)
+
+Colour defaults were flat `--slate-*` steps from 2026-09-15 (when `light-dark()` pairs were
+dropped) until 2026-10-07, when they moved to the `--theme-*` slots. Light-only, like the rest of
+the library.

package/.claude/skills/composable-anchor-scroll.md

@@ -64,26 +64,27 @@ onMounted(() => {
 >{{ section.label }}</a>
 ```
 
-### Active state in TabNavigation
+### Active state in ResponsiveHeader
 
-`TabNavigation` handles `activeHash` internally for hash nav items. No extra work needed —
-just pass anchor hrefs in `navItemData` and the active indicator moves automatically on click
-and on initial load (defaulting to the first hash item when the URL has no hash).
+`ResponsiveHeader` handles `activeHash` internally for `#` nav items. No extra work needed —
+just pass anchor paths in `responsiveNavLinks` and the active indicator moves automatically on
+click and on initial load (defaulting to the first anchor item when the URL has no hash).
+(`TabNavigation` did the same until it was removed on 2026-10-07.)
 
 ---
 
 ## Usage patterns
 
-### 1. TabNavigation with a sticky site header
+### 1. ResponsiveHeader with a sticky site header
 
-`TabNavigation` accepts an `anchorScrollOffset` prop that is passed directly to `useAnchorScroll`.
+`ResponsiveHeader` accepts an `anchorScrollOffset` prop that is passed directly to `useAnchorScroll`.
 Pass a getter so the live header height is read at scroll time — this stays correct if the
 header resizes on different viewports.
 
 ```vue
 <header ref="headerRef">
-  <TabNavigation
-    :nav-item-data="navItemData"
+  <ResponsiveHeader
+    :responsive-nav-links="responsiveNavLinks"
     :anchor-scroll-offset="() => headerRef?.offsetHeight ?? 0"
   />
 </header>
@@ -92,18 +93,18 @@ header resizes on different viewports.
 ```ts
 const headerRef = ref<HTMLElement | null>(null);
 
-const navItemData = {
+const responsiveNavLinks = {
   main: [
-    { text: "About",    href: "#about" },
-    { text: "Services", href: "#services" },
-    { text: "Contact",  href: "#contact" },
-    { text: "Blog",     href: "/blog" },  // route — NuxtLink handles as normal
+    { name: "About",    path: "#about" },
+    { name: "Services", path: "#services" },
+    { name: "Contact",  path: "#contact" },
+    { name: "Blog",     path: "/blog" },  // route — NuxtLink handles as normal
   ],
 };
 ```
 
 **CSS alternative** — if you want all anchor links site-wide to respect the sticky header
-(not just the ones inside `TabNavigation`), add `scroll-padding-top` to `html` instead and
+(not just the ones inside `ResponsiveHeader`), add `scroll-padding-top` to `html` instead and
 skip the prop:
 
 ```css
@@ -290,4 +291,4 @@ takes effect immediately on the next click.
 - **SSR** — both `handleNavClick` and `scrollToAnchor` guard with `import.meta.server` and return
   early. No special SSR setup is needed.
 - **Multiple instances** — each call to `useAnchorScroll` is independent. You can run a sticky
-  section nav alongside a `TabNavigation` on the same page with different offsets.
+  section nav alongside a `ResponsiveHeader` on the same page with different offsets.

package/.claude/skills/index.md

@@ -32,7 +32,8 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── theming-override-default.md      — replace the entire default theme with a custom palette (set --theme-hue/--theme-chroma)
 ├── theming-partial-override.md      — override a specific colour token category (palette, buttons, inputs) without a full theme replacement
 ├── theming-form-geometry-tokens.md  — non-colour form/button/input tokens (padding, border-radius, gaps): full inventory, why partial override doesn't need duplicating the source files
-├── theming-component-token-pattern.md — standard shape for overridable component colours: public token + inline fallback, no bare var()/no private-only indirection; the three tiers (theme slots / cross-component families / component-scoped); line-clamp tokens for overflowing text; rollout status
+├── theming-component-token-pattern.md — standard shape for overridable component colours: public token + inline fallback, no bare var()/no private-only indirection; the three tiers (theme slots / cross-component families / component-scoped); line-clamp tokens for overflowing text; image-overlay scrim tokens; rollout status
+├── theming-status-tokens.md        — global --status-* colours (success/warning/danger/info/neutral: solid + surface + text), which components read them, how to override once for the whole library
 ├── theming-dark-mode.md            — add a dark scheme in a consumer app (layer is light-only): enable plumbing, full dark token set without light-dark(), light-dark() alternative, light-only pinning
 ├── colour-scheme-disable.md         — disable light/dark scheme support in a consumer app
 ├── component-dynamic-slots.md        — named dynamic slots ($slots iteration) vs indexed dynamic slots (itemCount pattern)
@@ -62,7 +63,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── composable-zod-validation.md      — useZodValidation: schema-driven form validation, error binding, submit flow, API error push
 ├── composable-colour-scheme.md       — useColourScheme: reactive light/dark/auto switching, localStorage persistence, runtime config
 ├── composable-dialog-controls.md     — useDialogControls: single-call setup with config object, openDialog/closeDialog API, confirm/cancel callbacks
-├── composable-anchor-scroll.md       — useAnchorScroll: smooth anchor scrolling with reduced-motion support, dynamic offset, and TabNavigation integration
+├── composable-anchor-scroll.md       — useAnchorScroll: smooth anchor scrolling with reduced-motion support, dynamic offset, and ResponsiveHeader integration
 ├── composable-tooltips-guide.md      — useTooltipsGuide: sequential popover guide with auto-start, dismiss-to-advance, manual controls
 ├── composable-cookie-consent.md      — useCookieConsent: unset/granted/denied state, cookie persistence, wraps @nuxt/scripts' useScriptTriggerConsent
 ├── composable-analytics.md           — useAnalytics: provider-agnostic trackEvent/page-view tracking (google-analytics only implemented), consent-gated, single call site for setup + firing events
@@ -90,7 +91,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── service-detail.md            — ServiceDetail: full service detail page (hero banner, sticky sidebar booking card + related services, closing CTA), headerTag vs subheadingTag split, book-cta/sidebar-note/related-service/final-cta slots
     ├── breadcrumb.md                — Breadcrumb: items (BreadcrumbItem[]) trail, link vs current-page text, CSS token API
     ├── skip-links.md                — SkipLinks: focus-revealed accessibility skip-nav, links (SkipLink[]) data-driven, homeLink slot, CSS token API
-    ├── tabs-core.md                 — TabsCore: tablist from indexed slots (itemCount), arrow-key nav, moving hover/active/underline indicators, CSS token API
+    ├── tabbed-content.md            — TabbedContent (was TabsCore): tablist + panels from indexed slots (itemCount), arrow-key nav, moving hover/active/underline indicators, CSS token API
     ├── contact-section.md      — ContactSection props (stepperIndicatorSize pass-through), 3-item info+form layout, slot API
     ├── stepper-list.md         — StepperList dynamic slots (item-{n}/indicator-{n}), props, connector behaviour
     ├── expanding-panel.md      — ExpandingPanel v-model, forceOpened, contentIsOnTop overlay mode, slots (summary/icon/content), ARIA wiring, CSS token API
@@ -107,20 +108,20 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── wipe-away-vertical.md   — WipeAwayVertical: scroll-driven vertical wipe-away effect, pure-CSS grid overlay (no JS), indexed dynamic slots, sticky-centering-via-calc gotcha, CSS tokens
     ├── marquee-scroller.md     — MarqueeScroller: infinite logo/badge scroller, per-item dynamic slots (marqueeData id), hover/focus/keyboard pause, reduced-motion, CSS tokens
     ├── rotating-carousel-image.md — RotatingCarouselImage: 3D rotating image carousel, scroll-parallax tilt, focus/keyboard/hover pause, reduced-motion, CSS tokens
-    ├── tab-navigation.md       — TabNavigation (DEPRECATED, use ResponsiveHeader): horizontal tab nav with CSS anchor-positioning indicators, anchor scroll, burger collapse, full CSS token API
-    ├── social-icons-list.md    — SocialIconsList: data-driven social icon links, ISocialIcon type, logos: icon names, CSS tokens
+    ├── social-icons-list.md    — SocialIconsList: data-driven social icon links, ISocialIcon type, logos: icon names (dark ones vanish on dark backgrounds; mono alternatives), CSS tokens incl. --social-icons-list-icon-colour
     ├── display-qr-code.md      — DisplayQrCode: QR code SVG from a string value, colour/size/variant/radius props, currentColor default
     ├── capture-qr-code.md      — CaptureQrCode: live camera scanner, error state, visibility/route/KeepAlive lifecycle, media stream cleanup
     ├── decode-qr-code.md       — DecodeQrCode: file picker + drag-and-drop image decoder, shared results list, CSS override points
     ├── auto-grid.md            — AutoGrid: auto-fit responsive grid, $slots iteration, --auto-grid-gap/min-col-size-{small,default,large} tokens, is-responsive, semantic tag + aria
-    ├── display-avatar.md       — DisplayAvatar (02.molecules): circular avatar with image/initials fallback (alt announced), size scale tokens, --display-avatar-* colours, chip badge, icon slot
+    ├── display-avatar.md       — DisplayAvatar (02.molecules): circular avatar with image/initials fallback (alt announced), broken-image fallback, data-size scale tokens, image-size, --display-avatar-* colours, chip badge, icon slot
+    ├── profile-section.md      — ProfileSection (02.molecules): picture + numbered profile-info-N slots, eyebrow/hero header (above, or over the picture top/bottom on a scrim via header-placement), profileLinks, container-query two-column layout, .location/.services highlight tokens
     ├── display-theme-switch.md — DisplayThemeSwitch: system/light/dark picker wrapping TripleToggleSwitch, wired to useSettingsStore, labels/icons props, small sizing variant
     ├── card-core.md            — CardCore: generic card container, dynamic named slots as rows, 4 variants, blurred backdrop layer, full CSS token API
     ├── action-menu.md          — ActionMenu + ActionMenuItem: ellipsis trigger + anchored popover menu, indexed item-{n} slots, link/button items, full CSS token API
     ├── select-menu.md          — SelectMenu: v-model single-select listbox popover (ActionMenu's popover mechanics, InputSelectCore's selected-option semantics), icon/text/chevron trigger toggles, checkmark on selected option, options-array driven, full CSS token API
     ├── display-dialog.md       — DisplayDialog: native <dialog> overlay, 5 variants (dialog/modal/confirm/alert/fullscreen), useDialogControls integration, CSS token API
     ├── display-chip.md         — DisplayChip: status indicator chip overlay, CSS trig positioning, circle/square shapes, status colours, icon/label content
-    ├── display-pill.md         — DisplayPill: pill/badge label with icon slot, 6 variants, 3 sizes, reversible order, --display-pill-* tokens (renamed from --theme-pill-*; variants fall back to base colour tokens)
+    ├── display-pill.md         — DisplayPill: pill/badge label with icon slot, 6 variants, 3 sizes, reversible order, --display-pill-* tokens (variants fall back to base colour/border/ring tokens); data-size/data-variant/data-reversed hooks (2026-10-08, were bare classes), label line-clamp token, -02 ring and outlined-monochrome recipes, StressTest story
     ├── carousel-flip.md        — CarouselFlip: FLIP-animated carousel, carouselDataIds slot API, buttonLayout variants (sides/controls-flanking/controls-grouped-right/overlay), CSS tokens
     ├── samaritan-prompt.md — SamaritanPrompt + SamaritanPromptMixed: animated text prompts, typewriter/word-pulse effects, MessageConfig API, pause on hover, aria-live, CSS tokens
     ├── display-toast.md          — DisplayToast (standalone v-model) + DisplayToastProvider + useToastQueue (app-wide queue): stacking, FLIP dismiss, maxVisible, SemanticTheme × 4, masked SVG glass variant

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

@@ -268,6 +268,8 @@ export const Default: Story = {
 Key points:
 
 - `computed` is **not** auto-imported in `.ts` story files — import it explicitly from `"vue"`.
+- Components aren't auto-registered in a story's `template` string either. Every component used there, including ones you put in the component's slots (`EyebrowText`, `HeroText`, `SocialIconsList`, ...), must be imported and listed in `components: {}`. Otherwise Vue renders it as an empty unknown element (`<eyebrowtext>`) with no error. ProfileSection's header and social-icons stories rendered blank this way until 2026-10-14.
+- Props in a story's `template` string aren't type-checked either. An invalid value renders silently with no warning: ProfileSection's stories passed `font-size="large"` to `HeroText`, which only has `display`/`title`/`heading`/`subheading`/`label`, so the heading fell back to unstyled text. Check every literal prop value against the component's `interface Props`.
 - Extra args must be stripped before `v-bind` — spreading unknown keys onto a component makes them unknown HTML attributes.
 - CSS custom properties set via `:style` on the component root are picked up by `var()` in the component's scoped CSS.
 
@@ -285,6 +287,59 @@ prop and try to pass it. Make it unmistakable:
 
 `PriceList.stories.ts` and `GoogleReviews.stories.ts` (line-clamp controls) follow this.
 
+## Link to the stories of components that use this one
+
+When the component you're working on is a building block of other components (it's rendered
+inside them, or they're a specialised version of it), its stories only show it in isolation. Add a
+short note to each story that names the components using it, says what they add, and links to their
+stories, so a reader can see it in real use. Examples: `AlertContent` is the panel inside
+`DisplayToast`, `DisplayPrompt` and `CookieConsentBanner`; `AlertContentInner` is shared by
+`AlertContent` and `AlertMaskedContent`.
+
+- **Say how they're related, not just "see also".** Name the parent and what it adds, e.g. "The
+  #actions slot wired to real accept and reject handlers: see the CookieConsentBanner story."
+- **Link to the story that shows the relevant feature**, not just any story. A story about a slot
+  or behaviour links to the parent story that exercises it. Other stories can share one general
+  note.
+- **Check the parent story actually shows what the note says.** Read its component before writing
+  the note. `DisplayToast` doesn't fill `AlertContent`'s `#actions` slot, so a toast note that
+  promised action buttons would send people to the wrong place.
+- **Put the note in the canvas**, as a `<p>` above the component, so it's visible on the Canvas tab
+  as well as Docs. If the story has a `parameters.docs.description`, add the link there too.
+- Find the parent's story id from its `title` and export name: `"Molecules/CookieConsentBanner"` +
+  `Default` gives `molecules-cookieconsentbanner--default` (lowercase, `/` and spaces become `-`,
+  then `--` and the kebab-cased export name).
+
+```ts
+// Links in the canvas open in the Storybook manager (target="_top"), not inside the preview iframe.
+const storyNoteStyle = "margin: 0 0 1.6rem; font-size: 1.4rem;";
+const cookieNote = `
+  <p style="${storyNoteStyle}">
+    For the #actions slot wired up to real accept and reject handlers, open the
+    <a href="/?path=/story/molecules-cookieconsentbanner--default" target="_top">CookieConsentBanner</a> story.
+  </p>
+`;
+
+// In the story template:
+template: `
+  <div style="max-width: 600px; padding: 2rem;">
+    ${cookieNote}
+    <AlertContent v-bind="componentArgs">...</AlertContent>
+  </div>
+`,
+
+// In parameters.docs.description (markdown): use "?path=..." with no leading slash.
+story: "See the [CookieConsentBanner](?path=/story/molecules-cookieconsentbanner--default) story. ...",
+```
+
+- Canvas links need `target="_top"` and a leading `/` (`/?path=...`). Without `target="_top"` the
+  whole Storybook UI loads inside the preview frame. The leading `/` assumes Storybook is served
+  from the root of its domain, which holds locally and on the deployed Storybook.
+- Define each note once as a constant at the top of the file and interpolate it, rather than
+  repeating the markup in every story.
+
+`AlertContent.stories.ts` follows this.
+
 ## Notes
 
 - **Colour scheme:** `.storybook/preview.ts` pins every story to the light scheme

package/.claude/skills/theming-component-token-pattern.md

@@ -83,6 +83,54 @@ Prefer this over a prop: line count is presentation, and CSS handles it without
   layout around it.
 - Document it in `CONSUMER-STYLING.md` with its default and the `1`/`none` options.
 
+## Text over an image: scrim tokens
+
+Any component that puts text over a photo (a header in a picture, a card title on its image) gets
+the same scrim token set, so a consumer can match the scrim to their photos. `ProfileSection`'s
+`header-placement="picture-top|picture-bottom"` is the reference; `ServicesCard`'s
+`titles-within-image-wrapper` has the older subset (colour and whole-background override only) and
+should gain the rest when it's next touched.
+
+| Token | Default | Purpose |
+|---|---|---|
+| `--{c}-scrim-colour` | `#000` | Colour the scrim starts from at the image's edge |
+| `--{c}-scrim-opacity` | `75%` | Its opacity at the start |
+| `--{c}-scrim-solid-stop` | `0%` | How far it stays full strength before fading, so the text sits on a clean background |
+| `--{c}-scrim-target-colour` | `transparent` | What it fades into: set to roughly the photo's colour where the fade ends, so there's no grey band |
+| `--{c}-scrim` | the gradient | Whole `background` override; `none` removes it |
+| `--{c}-text-colour` | `contrast-color(<scrim colour>)`, `#fff` without support | Text on the scrim |
+
+```css
+.component-header {
+  --_scrim-colour: var(--component-scrim-colour, #000);
+  --_scrim-start-colour: color-mix(in oklab, var(--_scrim-colour) var(--component-scrim-opacity, 75%), transparent);
+  --_scrim-solid-stop: var(--component-scrim-solid-stop, 0%);
+  --_scrim-target-colour: var(--component-scrim-target-colour, transparent);
+
+  color: var(--component-text-colour, #fff);
+  background: var(--component-scrim, linear-gradient(to top, rgb(0 0 0 / 0.75), rgb(0 0 0 / 0.75) var(--_scrim-solid-stop), var(--_scrim-target-colour)));
+
+  @supports (color: color-mix(in oklab, red, transparent)) {
+    background: var(--component-scrim, linear-gradient(to top, var(--_scrim-start-colour), var(--_scrim-start-colour) var(--_scrim-solid-stop), var(--_scrim-target-colour)));
+  }
+
+  @supports (color: contrast-color(red)) {
+    color: var(--component-text-colour, contrast-color(var(--_scrim-colour)));
+  }
+}
+```
+
+- The `@supports` fallback is for Safari before 16.2 (no `color-mix()`): it starts from 75% black
+  whatever the scrim colour, but keeps the solid stop and target colour.
+- `contrast-color()` reads the scrim colour, not the photo. Document that a consumer who removes the
+  scrim must set the text colour.
+- Round only the corners on the image's edge (`border-end-*-radius: inherit` for a bottom scrim),
+  or an opaque target colour shows rounded inner corners.
+- If the text can be long, don't clip it: let the frame grow (absolutely position the image and
+  keep `overflow` visible so `aspect-ratio` acts as a minimum).
+- Give the story a light and a dark theme built only from these tokens, each with a photo whose
+  edge suits the scrim.
+
 ## Multi-level fallback chains are fine
 
 A component that wants to *look like* another component's default (rather than duplicating a

package/.claude/skills/theming-status-tokens.md

@@ -0,0 +1,60 @@
+# Status tokens
+
+Global status colours, declared on `:root` in `app/assets/styles/setup/03.theming/_status.css`.
+Components that show a status (a dot, a badge, a pill) fall back to these, so a consumer restyles
+every status indicator in the library from one place.
+
+## The set
+
+Each status has three roles:
+
+| Role | Token | Use |
+|---|---|---|
+| Solid | `--status-<name>` | Dots, markers, small fills (mid-ramp step, visible on light and dark) |
+| Surface | `--status-<name>-surface` | Tinted background of a badge or pill |
+| Text | `--status-<name>-text` | Text/icon on that surface |
+
+| Status | Solid | Surface / text | Meaning |
+|---|---|---|---|
+| `success` | `--green-06` | `--green-01` / `--green-10` | Good, active, online, complete |
+| `warning` | `--orange-05` | `--orange-01` / `--orange-10` | Needs attention, pending, idle |
+| `danger` | `--red-06` | `--red-01` / `--red-10` | Error, blocked, do not disturb |
+| `info` | `--blue-06` | `--blue-01` / `--blue-09` | Informational, in progress, new |
+| `neutral` | `--slate-05` | `--slate-01` / `--slate-09` | Inactive, offline, archived, draft |
+
+Keep the set to these five. A domain-specific state (`pending`, `archived`, `in-progress`) maps
+onto one of them rather than getting its own token; if a consumer genuinely needs a sixth colour,
+they define it in their app and pass it wherever the component takes a colour (e.g. `dotColor`).
+
+## Who reads them
+
+The component's own token always wins, then the global status token:
+
+| Component | Mapping |
+|---|---|
+| `DisplayChip` | `online` → success, `idle` → warning, `dnd` → danger, no class → neutral (solid) |
+| `DisplayPill` | `success`/`warning`/`danger` variants → surface + text. `primary` (brand) and `neutral` (dark, inverted) do **not** read the set |
+| `SelectMenu` | Nothing automatic; options pass `dotColor: "var(--status-success)"` etc. |
+
+When adding a component that shows a status, default its colour tokens to these
+(`var(--component-colour-online, var(--status-success))`), never to a palette step or hex value
+directly.
+
+## Overriding
+
+```css
+/* consuming app, unlayered */
+:root {
+  --status-success: #1f9d55;
+  --status-success-surface: #e6f6ec;
+  --status-success-text: #0f5132;
+}
+```
+
+One component only: set its own token instead (`--display-chip-colour-online: hotpink`).
+
+## Dark mode
+
+Light values only, like every other layer token (no `light-dark()`). Storybook's dark values live
+in `.storybook/color-scheme.css`: surfaces move to step `09`, text to step `02`; solids stay put.
+A consumer app with a dark scheme copies those overrides (see `theming-dark-mode.md`).

package/.vscode/srcdev-component-display-avatar.code-snippets

@@ -6,6 +6,13 @@
       "<DisplayAvatar src=\"${1:/images/profile.jpg}\" alt=\"${2:Jane Smith}\" size=\"${3|md,xs,s,lg,xl|}\" />"
     ]
   },
+  "SRCDEV DisplayAvatar Large Image": {
+    "description": "DisplayAvatar: image avatar resized beyond the scale, with a matching image-size so it stays sharp",
+    "scope": "vue,html",
+    "body": [
+      "<DisplayAvatar src=\"${1:/images/profile.jpg}\" alt=\"${2:Jane Smith}\" :image-size=\"${3:240}\" style=\"--display-avatar-size: ${4:12rem}\" />"
+    ]
+  },
   "SRCDEV DisplayAvatar Initials": {
     "description": "DisplayAvatar: initials derived from alt (alt is announced, initials hidden from screen readers)",
     "scope": "vue,html",
@@ -21,7 +28,8 @@
       "  src=\"${1:/images/profile.jpg}\"",
       "  alt=\"${2:Jane Smith}\"",
       "  :chip=\"{ size: '${3:12px}', maskWidth: '${4:4px}', offset: '${5:0px}', angle: '${6:45deg}' }\"",
-      "  :style-class-passthrough=\"['${7|online,offline|}']\"",
+      "  status=\"${7|online,idle,dnd,offline|}\"",
+      "  status-label=\"${8:Online}\"",
       "/>"
     ]
   }