srcdev-nuxt-components 9.3.0 → 9.3.1

package/.claude/hooks/check-component-update.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# PostToolUse hook (Write|Edit) for app/components/*.vue files. Advisory nudges only
+# (missing != wrong): skill doc, story, test, CONSUMER-STYLING.md, .vscode snippet,
+# legacy tier-folder location, options-style defineProps.
+
+root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+f=$(jq -r '.tool_input.file_path // empty')
+
+case "$f" in
+  */app/components/*.vue) ;;
+  *) exit 0 ;;
+esac
+case "$f" in
+  */tests/*|*/stories/*) exit 0 ;;
+esac
+
+name=$(basename "$f" .vue)
+skill=$(printf '%s' "$name" | sed -E 's/([a-z0-9])([A-Z])/\1-\2/g; s/([A-Z]+)([A-Z][a-z])/\1-\2/g' | tr '[:upper:]' '[:lower:]')
+dir=$(dirname "$f")
+pdir=$(dirname "$dir")
+
+# variants/ files are documented under their parent component, not standalone.
+is_variant=false
+if [[ "$(basename "$dir")" == "variants" ]]; then
+  is_variant=true
+  parent_name=$(basename "$pdir")
+fi
+
+if [[ "$is_variant" == true ]]; then
+  msg="Component file $f was edited/written. This is a variant of $parent_name — per project convention, document it inside .claude/skills/components/$parent_name.md (e.g. a \"Variants\" section) rather than creating a separate .claude/skills/components/$skill.md for it."
+else
+  msg="Component file $f was edited/written. Per Claude.md Development Workflow step 7, check whether .claude/skills/components/$skill.md needs updating to reflect this change (props/slots/models/defaults/behaviour)."
+fi
+
+shopt -s nullglob
+stories=("$dir"/stories/*.stories.ts "$pdir"/stories/*.stories.ts)
+tests=("$dir"/tests/*.spec.ts "$pdir"/tests/*.spec.ts)
+shopt -u nullglob
+
+if [[ ${#stories[@]} -eq 0 ]]; then
+  msg="$msg No Storybook story found for this component (checked $dir/stories and $pdir/stories); create one."
+fi
+
+if [[ ${#tests[@]} -eq 0 ]]; then
+  msg="$msg No test spec found for this component (checked $dir/tests and $pdir/tests); create one per the Testing Requirements."
+fi
+
+if [[ "$is_variant" != true && ! -f "$dir/CONSUMER-STYLING.md" && ! -f "$pdir/CONSUMER-STYLING.md" ]]; then
+  msg="$msg No CONSUMER-STYLING.md found for this component; create one if it exposes a real --token API or class override hook (skip it if the component genuinely has neither)."
+fi
+
+if [[ ! -f "$root/.vscode/srcdev-component-$skill.code-snippets" ]]; then
+  msg="$msg No .vscode/srcdev-component-$skill.code-snippets found; create/update it per Development Workflow step 6."
+fi
+
+case "$f" in
+  */app/components/01.atoms/*|*/app/components/02.molecules/*|*/app/components/03.organisms/*|*/app/components/04.templates/*|*/app/components/05.forms/*) ;;
+  *) msg="$msg This component lives outside the 01-05 tier folders, a legacy location; move it into the matching tier (01.atoms, 02.molecules, 03.organisms, 04.templates, 05.forms) or propose a new tier folder if none fit." ;;
+esac
+
+if grep -qE 'defineProps\(\s*\{' "$f" && ! grep -q 'defineProps<' "$f"; then
+  msg="$msg This component uses the options-style defineProps({...}) pattern, an outdated-pattern signal; migrate to interface Props + withDefaults(defineProps<Props>(), {...}) per the Props Pattern in Claude.md."
+fi
+
+jq -n --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'

package/.claude/settings.json

@@ -114,7 +114,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "f=$(jq -r '.tool_input.file_path // empty'); if [[ \"$f\" == */app/components/*.vue && \"$f\" != */tests/* && \"$f\" != */stories/* ]]; then name=$(basename \"$f\" .vue); skill=$(printf '%s' \"$name\" | sed -E 's/([a-z0-9])([A-Z])/\\1-\\2/g; s/([A-Z]+)([A-Z][a-z])/\\1-\\2/g' | tr '[:upper:]' '[:lower:]'); jq -n --arg msg \"Component file $f was edited/written. Per Claude.md Development Workflow step 7, check whether .claude/skills/components/$skill.md needs updating to reflect this change (props/slots/models/defaults/behaviour).\" '{hookSpecificOutput:{hookEventName:\"PostToolUse\",additionalContext:$msg}}'; fi",
+            "command": "bash \"${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/check-component-update.sh\"",
             "timeout": 15
           }
         ]

package/.claude/skills/component-local-style-override.md

@@ -8,6 +8,19 @@ on context.
 
 No changes to the layer component are required for either pattern.
 
+> **⚠️ Never wrap consumer-app override `<style>` blocks in a named `@layer`** (e.g.
+> `@layer consumer`), even though library components wrap their own styles in `@layer components`
+> and it's tempting to mirror that. Cascade layer priority is fixed by whichever layer name is
+> first referenced anywhere in the document, not by its position in the library's master
+> `@layer reset, colours, theming, form-tokens, typography, a11y, components, utilities, consumer;`
+> statement. Nuxt/Nitro inlines many small per-component/per-page CSS chunks as `<style>` tags
+> directly in `<head>` for SSR performance — if an inlined page/component chunk declares its own
+> `@layer` before the library's main stylesheet (carrying that master statement) loads via its
+> `<link>`, layer order gets scrambled and the library's own layers can silently win instead, with
+> no build error (confirmed against a real `npm run build` + preview, not just `nuxt dev`). Keep
+> override `<style>` blocks unlayered — unlayered CSS always beats every named layer regardless of
+> document order, which is what makes both patterns below work reliably.
+
 ---
 
 ## Pattern 1 — Page-level scoping (preferred for single-use or section-scoped instances)
@@ -64,6 +77,38 @@ useHead({ bodyAttrs: { class: "contact-page" } })
 }
 ```
 
+> **⚠️ Do not use `bodyAttrs.class` as the scope for a page's *own* local `<style>` overrides if the
+> app uses `pageTransition`/`layoutTransition` (see `page-transitions.md`) — it races and breaks
+> mid-transition. `unhead` swaps `<body>`'s class the instant the *incoming* route's component sets
+> up, which happens as soon as navigation starts — not when the *outgoing* page's leave-transition
+> finishes animating. For a real transition duration (not an instant swap), the outgoing page is
+> still visible and mid-fade while `<body>` already carries the *new* page's class. Any selector
+> that depends on the old body class as an ancestor (`.contact-page .hero-bg-image { position:
+> absolute; ... }`) stops matching mid-fade, and the affected element snaps to unstyled/intrinsic
+> sizing for the rest of the transition — confirmed via direct DOM/computed-style polling against a
+> real `npm run build` + preview, not dev-server guesswork.
+>
+> Keep `bodyAttrs.class` for its legitimate use — a hook for *persistent* components (header, nav)
+> that live outside the transitioning page to react to "which page is active." For a page's own
+> local overrides, put a matching class directly on the page's own template root instead, so the
+> scope lives on the exact element that's fading and can never desync from what's rendered:
+>
+> ```vue
+> <template>
+>   <div class="contact-page-content">
+>     <div class="hero-section">...</div>
+>   </div>
+> </template>
+> <style lang="css">
+> .contact-page-content {
+>   .hero-section { ... }
+> }
+> </style>
+> ```
+>
+> Naming convention: `{name}-page-content` alongside the existing `{name}-page` body class keeps
+> the two purposes visually distinct.
+
 ---
 
 ## Pattern 2 — Per-instance modifier via styleClassPassthrough

package/.claude/skills/components/accordian-core.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-`AccordianCore` renders a group of `ExpandingPanel` components. When a shared `name` prop is supplied, the native `<details>` behaviour ensures only one panel can be open at a time. Content is filled via **indexed dynamic slots** — one set per panel, driven by `itemCount`.
+`AccordianCore` renders a group of `ExpandingPanel` components (or `ExpandingPanelClassic`, via the `variant` prop). When a shared `name` prop is supplied, the native `<details>` behaviour ensures only one panel can be open at a time. Content is filled via **indexed dynamic slots** — one set per panel, driven by `itemCount`.
 
 ---
 
@@ -35,6 +35,7 @@ For `itemCount="3"` the following slots exist:
 | `name` | `string` | `undefined` | Shared `name` passed to every `ExpandingPanel`. When set, native `<details>` grouping means only one panel can be open at a time. Omit for independent panels. |
 | `itemCount` | `number` | `0` | Number of `ExpandingPanel` components to render. |
 | `animationDuration` | `number` | `300` | Expand/collapse animation duration in ms, forwarded to every panel. |
+| `variant` | `"modern" \| "classic"` | `"modern"` | `"modern"` renders each panel as `ExpandingPanel` (`::details-content`-based, Baseline "newly available" Sept 2025 — the animation itself only runs where `interpolate-size` is supported, Chromium only as of 2026). `"classic"` renders `ExpandingPanelClassic` instead (`grid-template-rows`-based, animates identically in every browser). Applies to every panel in the group — mixing variants within one `AccordianCore` isn't supported. See [expanding-panel-classic.md](expanding-panel-classic.md). |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the root `.display-accordian` element. |
 
 ---
@@ -90,6 +91,18 @@ Passing `name="faq"` groups all panels so only one can be open at a time.
 </AccordianCore>
 ```
 
+### Classic variant (animation must run in every browser)
+
+```vue
+<AccordianCore name="faq" :item-count="2" variant="classic">
+  <template #accordian-0-summary><span>Question one?</span></template>
+  <template #accordian-0-content><p>Answer one.</p></template>
+
+  <template #accordian-1-summary><span>Question two?</span></template>
+  <template #accordian-1-content><p>Answer two.</p></template>
+</AccordianCore>
+```
+
 ### Programmatic slot rendering (many items)
 
 ```vue
@@ -107,11 +120,16 @@ Passing `name="faq"` groups all panels so only one can be open at a time.
 
 ## CSS custom properties
 
+`AccordianCore` has no `--accordian-*` tokens of its own — its panels are `ExpandingPanel`
+(or `ExpandingPanelClassic`, per `variant`) underneath, so `--expanding-panel-*` tokens apply
+directly. See `CONSUMER-STYLING.md` in the component directory for the full override reference,
+including the `.accordian-item` hook and the variant-dependent root class.
+
 Override in a consuming component or theme block:
 
 | Property | Effect |
 |----------|--------|
-| Applied via `accordian-item` class on each `ExpandingPanel` | Panels animate `margin-block-end` and `border-radius` alongside the expand transition — duration follows `animationDuration`. |
+| Applied via `accordian-item` class on each panel | Panels animate `margin-block-end` and `border-radius` alongside the expand transition — duration follows `animationDuration`. |
 
 ---
 
@@ -136,7 +154,9 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
     /* Geometry */
     /* max-width: none; */ /* default is 600px — remove the width cap */
 
-    /* Panel-level overrides via the .accordian-item hook */
+    /* Panel-level overrides via the .accordian-item hook — .expanding-panel is the
+       root class rendered by the default "modern" variant; swap in
+       .expanding-panel-classic if this instance uses variant="classic" */
     .accordian-item.expanding-panel {
       /* Border */
       /* border-block-end: 1px solid currentColor; */
@@ -153,7 +173,8 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
 
 ## Notes
 
-- `AccordianCore` always passes `style-class-passthrough="['accordian-item']"` to every inner `ExpandingPanel` — use `.accordian-item` as the hook for per-panel styling overrides.
-- For a single standalone expand/collapse panel, use `ExpandingPanel` directly instead.
+- `AccordianCore` always passes `style-class-passthrough="['accordian-item']"` to every inner panel — use `.accordian-item` as the hook for per-panel styling overrides.
+- `variant` applies to the whole group — every panel in a given `AccordianCore` renders as the same component. Switching `variant` at runtime swaps every panel's underlying component (via `<component :is>`), which resets each panel's open/closed state.
+- For a single standalone expand/collapse panel, use `ExpandingPanel` (or `ExpandingPanelClassic`) directly instead.
 - Auto-imported in Nuxt — no manual import needed.
 - File: `app/components/02.molecules/expandable/accordian/AccordianCore.vue`

package/.claude/skills/components/expanding-panel-classic.md

@@ -0,0 +1,221 @@
+# ExpandingPanelClassic Component
+
+## Overview
+
+**Prefer [`ExpandingPanel`](expanding-panel.md) unless you have a concrete reason not to.** `ExpandingPanelClassic` is the pre-`::details-content` implementation, kept only as a fallback for consumers who need the open/close animation to work identically in every browser today (its `grid-template-rows: 0fr → 1fr` sibling trick has no Baseline-2025 feature dependency). `ExpandingPanel` looks and behaves identically everywhere too — the only difference is that its animation degrades to an instant (unanimated) open/close in browsers without `interpolate-size` support (Chromium only, as of 2026), where this component still animates.
+
+`ExpandingPanelClassic` is a single expand/collapse panel built on the native `<details>`/`<summary>` element. It animates open/close via a CSS grid-template-rows trick, supports `v-model` for controlled state, and can be locked open with `forceOpened`. Multiple panels can be grouped into a native accordion by sharing the same `name` prop (see `AccordianCore`).
+
+---
+
+## Props reference
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `name` | `string` | `useId()` | Identifies the panel. Used in ARIA attributes (`id-{name}-trigger`, `id-{name}-content`). If omitted, a unique id is generated automatically. |
+| `animationDuration` | `number` | `400` | Expand/collapse transition duration in milliseconds. Pass `0` to disable animation. |
+| `forceOpened` | `boolean` | `false` | When `true`, the panel is always open. The toggle icon is hidden and clicks do not close the panel. |
+| `contentIsOnTop` | `boolean` | `false` | When `true`, the content region is taken out of flow and absolutely positioned directly below the summary, raised above surrounding page content via `z-index` — instead of pushing layout down when it opens. Applies a `content-is-on-top` class to the root `.expanding-panel-classic` element (not the content div). Also enables click-outside-to-close (see below) — not applied when `forceOpened` is `true`. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the root `.expanding-panel-classic` element. |
+
+## Model
+
+| Model | Type | Default | Notes |
+|-------|------|---------|-------|
+| `v-model` | `boolean` | `false` | Controls open/closed state. Bind to a `ref<boolean>` to manage state externally. |
+
+---
+
+## Slots
+
+| Slot | Purpose |
+|------|---------|
+| `#summary` | Content rendered inside the clickable `<summary>` row (label area). |
+| `#icon` | Custom toggle icon. Defaults to a `bi:caret-down-fill` icon that flips on open. Hidden when `forceOpened` is `true`. |
+| `#content` | Content revealed when the panel is open. Can contain any markup. |
+
+---
+
+## Usage examples
+
+### Basic uncontrolled panel
+
+```vue
+<ExpandingPanelClassic name="delivery">
+  <template #summary>
+    <span>Delivery &amp; Returns</span>
+  </template>
+  <template #content>
+    <p>Free standard delivery on orders over £50.</p>
+  </template>
+</ExpandingPanelClassic>
+```
+
+### Controlled via v-model
+
+```vue
+<script setup lang="ts">
+const isOpen = ref(false);
+</script>
+
+<template>
+  <ExpandingPanelClassic name="faq-1" v-model="isOpen">
+    <template #summary><span>What is your returns policy?</span></template>
+    <template #content><p>You can return any item within 30 days.</p></template>
+  </ExpandingPanelClassic>
+  <button @click="isOpen = !isOpen">Toggle externally</button>
+</template>
+```
+
+### Force opened (always visible, no toggle)
+
+```vue
+<ExpandingPanelClassic name="notice" :force-opened="true">
+  <template #summary><strong>Important notice</strong></template>
+  <template #content>
+    <p>This panel cannot be collapsed.</p>
+  </template>
+</ExpandingPanelClassic>
+```
+
+### Custom icon
+
+```vue
+<ExpandingPanelClassic name="custom-icon">
+  <template #summary><span>Section title</span></template>
+  <template #icon>
+    <svg width="12" height="12" viewBox="0 0 12 12">
+      <path d="M6 9L1 3h10z" fill="currentColor" />
+    </svg>
+  </template>
+  <template #content><p>Content here.</p></template>
+</ExpandingPanelClassic>
+```
+
+### Slow animation
+
+```vue
+<ExpandingPanelClassic name="slow" :animation-duration="800">
+  <template #summary><span>Slow panel</span></template>
+  <template #content><p>Opens and closes over 800 ms.</p></template>
+</ExpandingPanelClassic>
+```
+
+### Content on top (overlay instead of pushing layout)
+
+```vue
+<ExpandingPanelClassic name="overlay" :content-is-on-top="true" :style-class-passthrough="['my-overlay-panel']">
+  <template #summary><span>Open me — content overlays what's below</span></template>
+  <template #content>
+    <!-- Wrapper INSIDE the slot carries the visual styling — see
+         "Styling the content when contentIsOnTop" below for why it can't go on .inner -->
+    <div class="my-overlay-panel-body">
+      <p>Positioned absolutely below the summary, doesn't push page content down.</p>
+    </div>
+  </template>
+</ExpandingPanelClassic>
+
+<style>
+.my-overlay-panel-body {
+  background-color: white;
+  padding: 1rem;
+  box-shadow: 0 4px 12px rgb(0 0 0 / 15%);
+}
+</style>
+```
+
+---
+
+## ARIA / accessibility
+
+The component wires ARIA automatically from the `name` prop:
+
+| Element | Attribute | Value |
+|---------|-----------|-------|
+| `<summary>` | `id` | `id-{name}-trigger` |
+| `<summary>` | `aria-controls` | `id-{name}-content` |
+| `<summary>` | `aria-expanded` | `true` / `false` |
+| content div | `id` | `id-{name}-content` |
+| content div | `aria-labelledby` | `id-{name}-trigger` |
+| content div | `role` | `region` |
+
+Always supply a meaningful `name` prop when using multiple panels on the same page to avoid duplicate IDs.
+
+---
+
+## Styling the content when contentIsOnTop
+
+When `contentIsOnTop` is `true`, the component deliberately does **not** set `background-color`, `padding`, or a shadow on `.inner` — and consumers must not set them on `.inner` either. Always style a wrapper element placed *inside* the `#content` slot (see example above).
+
+Why: `.expanding-panel-classic-content` collapses via `grid-template-rows: 0fr → 1fr`, and `.inner` relies on `overflow: hidden` on its own box to clip its *children* to 0px when collapsed. `overflow: hidden` clips overflow content, but does not shrink the element's own padding/border/background — those are part of `.inner`'s own box model and still render at full size even while the row track is `0fr` and the panel is closed, producing a visible gap under the summary. A wrapper placed inside the slot is a *child* of `.inner`, so its box — including any padding/background/shadow — is correctly clipped to 0px by `.inner`'s `overflow: hidden` while closed. Baking styling into `.inner` itself would require also gating it on the open state (e.g. `.expanding-panel-classic-details[open] ~ .expanding-panel-classic-content .inner`), which is unnecessary complexity — styling the slot content is the correct fix, not a workaround.
+
+---
+
+## Constraint: don't stack contentIsOnTop panels as direct siblings
+
+`contentIsOnTop` takes the content out of document flow (`position: absolute`) specifically so opening the panel does **not** push whatever comes after it down the page — that's the entire point of the prop. The tradeoff: the panel's own container still only occupies the height of its `<summary>` row, so a *sibling* element positioned directly after it in the DOM sits exactly where the overlay renders. When that sibling is another `ExpandingPanelClassic`, opening the first one visually covers the second one's summary — this happens whether or not the two are grouped via a shared `name` (linked accordion) or opened simultaneously; it isn't specific to linking.
+
+`contentIsOnTop` is designed for a **single** panel overlaying unrelated trailing page content (e.g. a promo banner, a footer strip) — not for stacking multiple `contentIsOnTop` panels beside each other expecting normal accordion behaviour. If you need several linked/stacked panels, leave `contentIsOnTop` off (the default, in-flow layout handles that case correctly).
+
+---
+
+## Click-outside-to-close (contentIsOnTop only)
+
+When `contentIsOnTop` is `true` and the panel is open, clicking anywhere outside the panel's root element closes it (via `@vueuse/core`'s `onClickOutside`, sets `v-model` to `false`) — matching the dismissal behaviour of a native `<select>` or dropdown menu, since that's what an overlay panel functionally is. This does **not** apply to ordinary in-flow panels (`contentIsOnTop: false`, the default) — an inline accordion staying open when you click elsewhere on the page is expected, not a bug. It also never applies when `forceOpened` is `true`, regardless of `contentIsOnTop` — a forced-open panel isn't dismissible by any interaction.
+
+If you also want the panel to close when something *inside* it is activated (e.g. a nav link) — clicking outside doesn't cover that case — set `v-model` to `false` from that element's own click handler, same as any other controlled usage. See `ContentDocs`' `docsNav`/`docsPageNav` panels for a real example: both are `contentIsOnTop` on mobile, and each nav link closes its panel on click in addition to relying on click-outside.
+
+---
+
+## CSS Token Customization
+
+All `--expanding-panel-classic-*` tokens can be overridden at global, page, or instance scope. See `CONSUMER-STYLING.md` in the component directory for full token documentation and examples.
+
+**Tokens:**
+
+- `--expanding-panel-classic-summary-gap` — gap between summary label and icon
+- `--expanding-panel-classic-summary-padding-block` — summary row vertical padding
+- `--expanding-panel-classic-icon-size` — toggle icon size
+- `--expanding-panel-classic-content-z-index` — stacking order when `contentIsOnTop` is `true`
+- `--expanding-panel-classic-content-gap` — space between summary and content when `contentIsOnTop` is `true`
+
+---
+
+## Local style override scaffold
+
+When consuming this component, scaffold a style block using `styleClassPassthrough`. Delete the block if unused.
+
+See [component-local-style-override.md](../component-local-style-override.md) for the full pattern.
+
+```vue
+<ExpandingPanelClassic name="my-item" :style-class-passthrough="['my-panel']">
+  ...
+</ExpandingPanelClassic>
+
+<style>
+/* ─── ExpandingPanelClassic local overrides ───────────────────────────────
+   Colours, borders, geometry only — do not override behaviour.
+   Delete this block if no overrides are needed.
+   ─────────────────────────────────────────────────────────────────── */
+.expanding-panel-classic {
+  &.my-panel {
+    /* Border */
+    /* border-block-end: 1px solid currentColor; */
+
+    /* Summary row geometry */
+    /* .expanding-panel-classic-details .expanding-panel-classic-summary { padding-block: 1.2rem; } */
+  }
+}
+</style>
+```
+
+---
+
+## Notes
+
+- The open/close animation uses `grid-template-rows: 0fr → 1fr` — no JS height measurement needed.
+- `content-is-on-top` is applied to the root `.expanding-panel-classic` element, not `.expanding-panel-classic-content` — style overrides must scope through it, e.g. `.expanding-panel-classic.my-panel .expanding-panel-classic-content .inner { ... }`.
+- When `forceOpened` is `true`, `open` stays `true` regardless of `v-model`, but `v-model` still updates internally on clicks (useful if you later set `forceOpened` back to `false`).
+- Group panels into a native accordion (only one open at a time) by passing the same `name` to multiple panels or use `AccordianCore` which handles this automatically.
+- Auto-imported in Nuxt — no manual import needed.
+- File: `app/components/02.molecules/expandable/expanding-panel-classic/ExpandingPanelClassic.vue`

package/.claude/skills/components/expanding-panel.md

@@ -2,7 +2,11 @@
 
 ## Overview
 
-`ExpandingPanel` is a single expand/collapse panel built on the native `<details>`/`<summary>` element. It animates open/close via a CSS grid-template-rows trick, supports `v-model` for controlled state, and can be locked open with `forceOpened`. Multiple panels can be grouped into a native accordion by sharing the same `name` prop (see `AccordianCore`).
+`ExpandingPanel` is a single expand/collapse panel built on the native `<details>`/`<summary>` element. It animates open/close by styling the `::details-content` pseudo-element (the browser's own anonymous box wrapping everything after `<summary>`), supports `v-model` for controlled state, and can be locked open with `forceOpened`. Multiple panels can be grouped into a native accordion by sharing the same `name` prop (see `AccordianCore`).
+
+`::details-content` is Baseline "newly available" (Sept 2025) — Chrome, Firefox, and Safari all generate the box. The height *animation* itself depends on `interpolate-size: allow-keywords`, which as of 2026 only runs in Chromium; other browsers still open/close correctly, just without the transition (accepted progressive-enhancement trade-off, not a bug).
+
+If a consumer needs the animation to run identically in every browser today, use [`ExpandingPanelClassic`](expanding-panel-classic.md) instead — same props/model/slots API, older `grid-template-rows` implementation with no Baseline-2025 dependency.
 
 ---
 
@@ -105,8 +109,6 @@ const isOpen = ref(false);
 <ExpandingPanel name="overlay" :content-is-on-top="true" :style-class-passthrough="['my-overlay-panel']">
   <template #summary><span>Open me — content overlays what's below</span></template>
   <template #content>
-    <!-- Wrapper INSIDE the slot carries the visual styling — see
-         "Styling the content when contentIsOnTop" below for why it can't go on .inner -->
     <div class="my-overlay-panel-body">
       <p>Positioned absolutely below the summary, doesn't push page content down.</p>
     </div>
@@ -143,9 +145,7 @@ Always supply a meaningful `name` prop when using multiple panels on the same pa
 
 ## Styling the content when contentIsOnTop
 
-When `contentIsOnTop` is `true`, the component deliberately does **not** set `background-color`, `padding`, or a shadow on `.inner` — and consumers must not set them on `.inner` either. Always style a wrapper element placed *inside* the `#content` slot (see example above).
-
-Why: `.expanding-panel-content` collapses via `grid-template-rows: 0fr → 1fr`, and `.inner` relies on `overflow: hidden` on its own box to clip its *children* to 0px when collapsed. `overflow: hidden` clips overflow content, but does not shrink the element's own padding/border/background — those are part of `.inner`'s own box model and still render at full size even while the row track is `0fr` and the panel is closed, producing a visible gap under the summary. A wrapper placed inside the slot is a *child* of `.inner`, so its box — including any padding/background/shadow — is correctly clipped to 0px by `.inner`'s `overflow: hidden` while closed. Baking styling into `.inner` itself would require also gating it on the open state (e.g. `.expanding-panel-details[open] ~ .expanding-panel-content .inner`), which is unnecessary complexity — styling the slot content is the correct fix, not a workaround.
+`background-color`, `padding`, and a shadow can be set directly on `.expanding-panel-content` (or on a wrapper inside the `#content` slot — either works). The clipping boundary is now `::details-content` itself (`overflow: clip`, animated `height`), and `.expanding-panel-content` is a *child* of that box — so its own box, including padding/border/background, is correctly clipped to the animated height regardless of where the styling lives. This is a change from the previous `.inner`-based implementation, which had to clip its own box and so couldn't carry visual styling directly.
 
 ---
 
@@ -211,8 +211,8 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
 
 ## Notes
 
-- The open/close animation uses `grid-template-rows: 0fr → 1fr` — no JS height measurement needed.
-- `content-is-on-top` is applied to the root `.expanding-panel` element, not `.expanding-panel-content` — style overrides must scope through it, e.g. `.expanding-panel.my-panel .expanding-panel-content .inner { ... }`.
+- The open/close animation targets `::details-content` (`height: 0 → auto`, `overflow: clip`) — no JS height measurement needed. Requires `interpolate-size: allow-keywords` support (Chromium only as of 2026); other browsers still toggle correctly, just instantly.
+- `content-is-on-top` is applied to the root `.expanding-panel` element, not `.expanding-panel-content` — style overrides must scope through it, e.g. `.expanding-panel.my-panel .expanding-panel-content { ... }`.
 - When `forceOpened` is `true`, `open` stays `true` regardless of `v-model`, but `v-model` still updates internally on clicks (useful if you later set `forceOpened` back to `false`).
 - Group panels into a native accordion (only one open at a time) by passing the same `name` to multiple panels or use `AccordianCore` which handles this automatically.
 - Auto-imported in Nuxt — no manual import needed.

package/.claude/skills/components/navigation-items.md

@@ -0,0 +1,51 @@
+# NavigationItems Component
+
+## Overview
+
+Internal panel rendered inside [`ResponsiveHeader`](responsive-header.md)'s overflow burger
+dropdown — renders the **complement** of what's visible in the main bar. An item appears here
+only when its `config.visible` (set by `ResponsiveHeader`'s measurement pass) is `false`. Not
+meant to be mounted standalone in a real app, but is independently tested and storyable since
+it's a distinct piece of rendering logic (dropdown-within-dropdown via `ExpandingPanel`,
+active-route highlighting, hover indicator).
+
+---
+
+## Props reference
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `mainNavigationState` | `ResponsiveHeaderState` | `{ clonedNavLinks: {}, navListVisibility: {}, hasSecondNav: false }` | Shared geometry/visibility state, normally supplied by the parent `ResponsiveHeader` — not something a consumer constructs by hand outside of tests/stories. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the root `.overflow-navigation-wrapper` element. |
+
+---
+
+## Behaviour notes
+
+- A group's `<ul>` renders with the `visible` class (and thus becomes visible in the CSS)
+  only when that group's `navListVisibility[groupKey]` is `false` — i.e. only when at least
+  one item in it is collapsed.
+- Plain links render as `NuxtLink`; items with `childLinks` render an `ExpandingPanel` nested
+  dropdown (its own expand/collapse, independent of the outer overflow `<details>`).
+- Active-route highlighting reuses the same `isActiveNavItem` logic as `ResponsiveHeader`
+  (path match, or any `childLinks` path match).
+
+---
+
+## Usage example
+
+`NavigationItems` is rendered automatically by `ResponsiveHeader` — you don't place it
+yourself in a real app. For a test or story, construct the shared state directly:
+
+```ts
+const mainNavigationState: ResponsiveHeaderState = {
+  hasSecondNav: false,
+  navListVisibility: { firstNav: false },
+  clonedNavLinks: {
+    firstNav: [
+      { name: "Home", path: "/", config: { left: 0, right: 0, width: 0, visible: true } },
+      { name: "About", path: "/about", config: { left: 0, right: 0, width: 0, visible: false } },
+    ],
+  },
+};
+```