srcdev-nuxt-components 9.3.0 → 9.3.1

package/.claude/skills/components/responsive-header.md

@@ -0,0 +1,161 @@
+# ResponsiveHeader Component
+
+## Overview
+
+`ResponsiveHeader` is an adaptive main-navigation bar: it measures each nav item's real
+rendered width on mount (and on resize), decides which items fit, and collapses whatever
+doesn't fit into a burger/overflow dropdown rendered by `NavigationItems`. Supports
+multi-level dropdowns (`childLinks`) at both the top-bar and overflow-panel level.
+
+Most consumers should reach for [`SiteHeader`](site-header.md) instead, which wraps this
+component together with `PageRow` and `SkipLinks` — use `ResponsiveHeader` directly only if
+you need a different outer page-header structure.
+
+[`NavigationItems`](navigation-items.md) is an internal component rendered inside
+`ResponsiveHeader`'s overflow panel — it's not meant to be used standalone in a real app,
+though it's independently testable/storyable.
+
+---
+
+## The measurement pipeline (read this before touching layout/CSS here)
+
+On mount, a two-phase pass measures `navigationWrapperRects`/`secondaryNavRects`/each nav
+item's `getBoundingClientRect()`/`offsetWidth`, then marks each item's `config.visible`.
+Items with `visible: false` get a `visually-hidden` class in the top bar and are handed to
+`NavigationItems` to render in the overflow panel instead. The pass re-runs on
+`ResizeObserver` events targeting the root `.navigation` element, and once more after
+`document.fonts.ready` resolves (a fonts-still-loading correction).
+
+**This pipeline only re-measures when the *observed wrapper's own box size* changes.** Two
+known failure modes, both fixed 2026-08-21 — keep them in mind before adding new nav content:
+
+1. **Unsized async content (icons).** The chevron and any `iconName` decorator icons render
+   via the `Icon` component, which resolves its SVG asynchronously. If an icon element has no
+   reserved `width`/`height`, it measures at ~0 during the pass and then pops in and widens
+   the item afterward — with nothing to detect it, since the wrapper's box didn't change size.
+   `.decorator-icon` and the chevron `.icon` both reserve `1.35em` square for this reason.
+   Any new icon-bearing element added to a nav item must reserve its own size too.
+2. **Viewport-relative (`vw`/`clamp()`) font-size.** `html` has `scrollbar-gutter: stable`,
+   which keeps the wrapper's own box width constant when the scrollbar toggles — but does
+   nothing to stabilise the `vw` unit itself, so a fluid ancestor font-size can drift nav-item
+   text width without ever re-triggering a re-measurement. This is why
+   `--responsive-header-link-font-size` exists (see tokens below) — set it to a fixed value
+   rather than leaving it to inherit a fluid ancestor font-size.
+
+---
+
+## The dropdown "safe triangle" (read this before touching hover-close logic)
+
+`handleNavigationItemHover()` used to close every open top-bar dropdown the instant the mouse
+entered **any** `.main-navigation-item` — including a sibling item the cursor only crossed in
+transit. Moving the mouse diagonally from a dropdown's summary down into its own
+`.main-navigation-sub-nav` panel briefly dips through the 12px gap between them
+(`.main-navigation-sub-nav`'s `translate: 0 12px`), and at some cursor angles through a
+neighbouring item's hit area — closing the dropdown before the user reached it.
+
+**A pure-CSS "safe triangle" bridge (`clip-path` on a pseudo-element) was tried first and
+reverted — don't reintroduce it without solving the problem below first.** For such a bridge to
+escape `.main-navigation-item`'s `overflow: hidden` the same way `.main-navigation-sub-nav`
+does, its *containing block* must resolve to `.navigation` (the only positioned ancestor above
+the clipping box). But `.main-navigation-sub-nav` only manages this because it has no explicit
+`top`/`left` (containing-block choice is irrelevant to where it visually lands) — a bridge
+placed to *visually* sit under a specific trigger needs `top`/`left`/`inline-size` that resolve
+against something local, which forces it onto a positioned ancestor, which is always either
+already inside the `overflow: hidden` box (gets clipped, invisible, protects nothing) or itself
+becomes the sub-nav's new containing block (moves the *panel* inside the clipped box instead —
+the first attempt's mistake). A commented-out `/* position: relative; */` still sitting in the
+`:last-child` override is evidence someone hit this exact trap once before, independently.
+Neither approach is fixable without restructuring how the panel escapes clipping, which the
+collapse-measurement pipeline depends on.
+
+**Fixed (2026-08-21) with a JS hover-intent delay instead.** `handleNavigationItemHover()` now
+calls `scheduleCloseAllNavigationDetails()`, which delays the actual close by
+`HOVER_CLOSE_DELAY` (200ms) rather than firing it immediately. Two things cancel the pending
+close before it fires:
+
+- `handleSummaryHover()` (reaching a summary — cancels, then does its own close-others/toggle)
+- a `mouseenter` on `.main-navigation-sub-nav` itself, via `handleSubNavHover()`
+
+So a brief diagonal dip through a sibling's hit area survives (the close never actually runs
+before the cursor reaches its destination), while genuinely moving to a different part of the
+page still closes the dropdown promptly. `closeAllTimer` is cleared `onUnmounted` to avoid a
+stray close firing against stale refs after the component's gone.
+
+**`handleSummaryHover` never toggles — it only ever ensures the summary it's called on is
+open.** A real mouse click moves focus to the clicked element *before* the click event fires, so
+clicking a summary the mouse had just hover-opened dispatches both a `focusin` (→
+`handleSummaryHover`) and a `click` (→ `handleSummaryAction`) in quick succession. If
+`handleSummaryHover` toggled (as it did until 2026-08-21), that focusin would flip an
+already-open item closed, and the click's own toggle would immediately flip it back open — a
+visible open→closed→open flicker on every click, and the click effectively did nothing. Only
+`handleSummaryAction` (the explicit click) is allowed to close a dropdown; hover/focus is
+idempotent-safe to fire redundantly. `@vue/test-utils`' `.trigger("click")` doesn't synthesize
+this implicit focus side effect on its own — a test asserting click-to-close must explicitly
+`.trigger("focusin")` before `.trigger("click")` to reproduce it, or it'll pass against the
+buggy toggle-based version too.
+
+---
+
+## Props reference
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `responsiveNavLinks` | `ResponsiveHeaderProp` (`{ [groupKey]: ResponsiveHeaderNavItem[] }`) | `{}` | Nav groups. Each item is either a link (`path`) or a dropdown (`childLinksTitle` + `childLinks`). A single group with no dropdowns is valid for simple sites. |
+| `gapBetweenFirstAndSecondNav` | `number` | `12` | Pixel gap reserved between the first and second nav groups (also factored into the overflow-collapse width math). |
+| `overflowDetailsSummaryIcons` | `Record<string, string>` | `{ more: "gravity-ui:ellipsis", burger: "gravity-ui:bars" }` | Icon names for the overflow button's two states: `more` shows when only *some* items collapsed, `burger` shows when `allowNavigationCollapse` is active (whole nav collapsed). |
+| `collapseBreakpoint` | `number \| null` | `null` | A fixed pixel width below which the whole main nav collapses into the overflow burger, instead of the default per-item responsive collapse. |
+| `collapseAtMainNavIntersection` | `boolean` | `false` | Like `collapseBreakpoint`, but the breakpoint is derived automatically from the main nav's own measured width rather than a fixed number. |
+| `allowExpandOnGesture` | `boolean` | `true` | When `true`, hovering/focusing a dropdown summary opens it (in addition to click). When `false`, only click toggles it. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the root `.navigation` element. |
+
+## Slots
+
+| Slot | Purpose |
+|------|---------|
+| `#secondaryNavigation` | Extra content rendered after the overflow burger button (e.g. a settings icon link). Only rendered when the slot is provided. |
+
+---
+
+## Public CSS token API
+
+All tokens are read via `var(--token, default)` — see the full list in the component's own
+`<style>` block comment. Highlights:
+
+| Token | Default | Controls |
+|---|---|---|
+| `--responsive-header-link-font-size` | `inherit` | Nav-link font-size. **Set this to a fixed value** — see the measurement-pipeline note above for why leaving it `inherit` from a fluid ancestor is a footgun. |
+| `--responsive-header-link-color` | `inherit` | Link/summary text colour. |
+| `--responsive-header-bg` / `--responsive-header-padding-*` / `--responsive-header-border*` | transparent / `0` / `none` | Root element theming. |
+| `--responsive-header-overflow-btn-*` | various | Overflow burger button sizing/colour. |
+| `--responsive-header-sub-nav-*` / `--responsive-header-overflow-nav-*` | various | Top-bar dropdown panel and overflow-panel container theming. |
+| `--responsive-nav-decorator-indicator-color` / `--responsive-nav-decorator-hovered-*` | `currentColor` / inherits | The sliding active/hover indicator bar under the main nav. |
+
+---
+
+## Usage example
+
+```vue
+<script setup lang="ts">
+const responsiveNavLinks = {
+  firstNav: [
+    { name: "Home", path: "/" },
+    {
+      name: "Components",
+      childLinksTitle: "UI Components",
+      childLinks: [{ name: "Buttons", path: "/forms/examples/buttons" }],
+    },
+  ],
+  secondNav: [{ name: "Contact", path: "/contact" }],
+};
+</script>
+
+<template>
+  <ResponsiveHeader :responsive-nav-links="responsiveNavLinks" :style-class-passthrough="['site-header-nav']">
+    <template #secondaryNavigation>
+      <NuxtLink to="/settings" aria-label="Settings">
+        <Icon name="material-symbols:settings-outline-rounded" />
+      </NuxtLink>
+    </template>
+  </ResponsiveHeader>
+</template>
+```

package/.claude/skills/components/site-header.md

@@ -0,0 +1,98 @@
+# SiteHeader Component
+
+## Overview
+
+`SiteHeader` composes the standard page-header trio into one drop-in component: `PageRow` (header row wrapper) + `SkipLinks` (a11y skip-to-content/footer anchors with a home-link slot) + `ResponsiveHeader` (the adaptive/overflow-collapsing nav with dropdowns). It replaces manually assembling those three in every consuming app's `layouts/default.vue`.
+
+This is **not** a classic multi-column "mega menu" (large flyout panels with images/promo blocks) — it's the existing `ResponsiveHeader` nav (main links, dropdown sub-nav, overflow burger collapse) wrapped for reuse. A single flat nav group with no dropdowns works fine too (see the `SimpleFlatNav` story) — you don't need to use the dropdown/overflow behaviour to benefit from the composition.
+
+Branding (logo/wordmark) is entirely consumer-authored via the `#branding` slot — `SiteHeader` has no opinion on brand markup or colours.
+
+---
+
+## Props reference
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `responsiveNavLinks` | `ResponsiveHeaderProp` | `{}` | Forwarded to `ResponsiveHeader`. Keyed nav groups; each item is either a link (`path`) or a dropdown (`childLinksTitle` + `childLinks`). A single group with no dropdowns is valid for simple sites. |
+| `gapBetweenFirstAndSecondNav` | `number` | `12` | Forwarded to `ResponsiveHeader`. |
+| `overflowDetailsSummaryIcons` | `Record<string, string>` | `{ more: "gravity-ui:ellipsis", burger: "gravity-ui:bars" }` | Forwarded to `ResponsiveHeader`. |
+| `collapseBreakpoint` | `number \| null` | `null` | Forwarded to `ResponsiveHeader`. |
+| `collapseAtMainNavIntersection` | `boolean` | `false` | Forwarded to `ResponsiveHeader`. |
+| `allowExpandOnGesture` | `boolean` | `true` | Forwarded to `ResponsiveHeader`. |
+| `pageRowVariant` | `"full" \| "popout" \| "content" \| "inset-content"` | `"content"` | Forwarded to the root `PageRow`'s `variant` prop. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra CSS classes on the root `PageRow` — targets `--site-header-*` tokens (see `CONSUMER-STYLING.md`). |
+| `navStyleClassPassthrough` | `string \| string[]` | `[]` | Extra CSS classes on the nested `ResponsiveHeader` — targets its own `--responsive-header-*`/`--overflow-nav-*` tokens. |
+
+---
+
+## Slots
+
+| Slot | Purpose |
+|------|---------|
+| `#branding` | Logo/wordmark markup, rendered inside `SkipLinks`' `#homeLink` slot. Consumer supplies the `NuxtLink`/`NuxtImg`/text — `SiteHeader` doesn't wrap or style it. |
+| `#secondaryNavigation` | Forwarded through to `ResponsiveHeader`'s own `#secondaryNavigation` slot (e.g. a settings icon link). Only rendered when provided. |
+
+---
+
+## Usage examples
+
+### Full nav with dropdowns (mega-menu-style)
+
+```vue
+<SiteHeader
+  :responsive-nav-links="responsiveNavLinks"
+  :style-class-passthrough="['header']"
+  :nav-style-class-passthrough="['site-header-nav']"
+>
+  <template #branding>
+    <NuxtLink to="/" class="home-link">Brand</NuxtLink>
+  </template>
+</SiteHeader>
+```
+
+### Simple flat nav (few pages, no dropdowns)
+
+```vue
+<script setup lang="ts">
+const responsiveNavLinks = {
+  main: [
+    { name: "Home", path: "/" },
+    { name: "About", path: "/about" },
+    { name: "Services", path: "/services" },
+    { name: "Contact", path: "/contact" },
+  ],
+};
+</script>
+
+<template>
+  <SiteHeader :responsive-nav-links="responsiveNavLinks" :style-class-passthrough="['header']">
+    <template #branding>
+      <NuxtLink to="/" class="home-link">Brand</NuxtLink>
+    </template>
+  </SiteHeader>
+</template>
+```
+
+### With a secondary navigation slot
+
+```vue
+<SiteHeader :responsive-nav-links="responsiveNavLinks">
+  <template #branding>
+    <NuxtLink to="/" class="home-link">Brand</NuxtLink>
+  </template>
+  <template #secondaryNavigation>
+    <NuxtLink to="/settings" aria-label="Settings">
+      <Icon name="material-symbols:settings-outline-rounded" />
+    </NuxtLink>
+  </template>
+</SiteHeader>
+```
+
+---
+
+## Migration notes
+
+- Consuming layouts previously assembling `PageRow` + `SkipLinks` + `ResponsiveHeader` (or `TabNavigation`) by hand can switch to `SiteHeader` directly; the two `styleClassPassthrough` props map 1:1 onto the two independent passthrough hooks that pattern used.
+- `TabNavigation`'s `NavItemData` shape (`{ main: [{ text, href, iconName, cssName }] }`) is **not** the same shape as `ResponsiveHeaderProp` (`{ groupKey: [{ name, path, childLinksTitle, childLinks }] }`) — migrating a `TabNavigation` consumer means reshaping the nav data, not just swapping the component. `TabNavigation`'s `navAlign` prop has no `SiteHeader` equivalent since `ResponsiveHeader`'s layout is fixed (branding column + nav column).
+- Requires the consuming layout's main/footer regions to carry `id="main-content"` / `id="footer-content"` — same requirement as using `SkipLinks` directly.

package/.claude/skills/index.md

@@ -36,6 +36,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── component-dynamic-slots.md        — named dynamic slots ($slots iteration) vs indexed dynamic slots (itemCount pattern)
 ├── component-local-style-override.md — styleClassPassthrough + scoped style block for per-usage visual customisation
 ├── component-prop-driven-container-layout.md — vary CSS grid layout inside @container queries using data-* attribute selectors
+├── page-transitions.md               — pageTransition/layoutTransition setup; the self-wrapped <NuxtLayout> + layout:false anti-pattern that pulls the header/nav into the transition boundary; fade CSS
 ├── css-nesting-conventions.md                — native CSS nesting rules: why &__child Sass BEM concatenation silently breaks, correct patterns
 ├── css-grid-max-width-gutters.md             — cap a centre grid column width by growing gutters, with start/center alignment variants
 ├── css-animation-utilities.md                — scroll-driven animation utility classes: scroller-x (carousel), entry-zoom-reveal, entry-slide-in, entry-exit-blur, auto-rotate
@@ -98,7 +99,11 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── carousel-flip.md        — CarouselFlip: FLIP-animated carousel, carouselDataIds slot API, buttonLayout variants (sides/controls-flanking/controls-grouped-right/overlay), CSS tokens
     ├── samaritan-prompt-mixed.md — SamaritanPromptMixed: animated text prompt, typewriter/word-pulse effects, MessageConfig API, aria-live accessibility, CSS tokens
     ├── display-toast.md          — DisplayToast (standalone v-model) + DisplayToastProvider + useToastQueue (app-wide queue): stacking, FLIP dismiss, maxVisible, SemanticTheme × 4, masked SVG glass variant
-    └── display-prompt.md         — DisplayPrompt: inline notification banner, SemanticTheme × 4, local vs parent-controlled dismiss, outlined modifier, CSS token override
+    ├── display-prompt.md         — DisplayPrompt: inline notification banner, SemanticTheme × 4, local vs parent-controlled dismiss, outlined modifier, CSS token override
+    ├── expanding-panel-classic.md — ExpandingPanelClassic: grid-template-rows animation (no Baseline-2025 dependency), same API as ExpandingPanel, cross-browser animation parity trade-off
+    ├── site-header.md            — SiteHeader: PageRow + SkipLinks + ResponsiveHeader composition, #branding/#secondaryNavigation slots, dual styleClassPassthrough hooks
+    ├── responsive-header.md      — ResponsiveHeader: overflow-collapsing adaptive nav, measurement-pipeline gotchas (unsized icons, vw font-size drift), full CSS token API
+    └── navigation-items.md       — NavigationItems: internal overflow-panel renderer for ResponsiveHeader, complement-visibility logic, not used standalone
 ```
 
 ## Skill file template

package/.claude/skills/page-transitions.md

@@ -0,0 +1,116 @@
+# Page Transitions
+
+## Overview
+
+`pageTransition`/`layoutTransition` in `nuxt.config.ts` name the Vue `<Transition>` that wraps
+`<NuxtPage>`/`<NuxtLayout>`. Getting the app's template structure wrong here means the whole page —
+header, nav, footer included — fades/animates on every navigation, not just the routed content.
+This is silent: no build error, no warning, it just looks visually wrong ("the header flickers/
+fades too") once a transition actually has a visible duration.
+
+## The anti-pattern
+
+Each page self-wraps its own content in `<NuxtLayout name="default">` and sets
+`definePageMeta({ layout: false })` to stop Nuxt's automatic layout wrapping:
+
+```vue
+<!-- pages/contact.vue — WRONG -->
+<template>
+  <div>
+    <NuxtLayout name="default">
+      <div class="hero">...</div>
+    </NuxtLayout>
+  </div>
+</template>
+
+<script setup lang="ts">
+definePageMeta({ layout: false })
+</script>
+```
+
+This often isn't a deliberate choice — it's commonly left over from a Nuxt 3→4 directory-structure
+migration, or copied from a page that had a real reason to opt out of the layout (rare). Once it's
+in one page it tends to get copy-pasted to every page.
+
+**Why it's wrong**: `<NuxtLayout name="default">` here is INSIDE the page component's own render
+tree. Since `<NuxtPage>` (wrapped in the `pageTransition`) renders the matched page component as
+its child, the layout — including the header, nav, and footer defined in `layouts/default.vue` —
+becomes part of the transitioning subtree. Every navigation unmounts and remounts the *entire*
+layout, and it visually fades/animates along with the page content.
+
+## The correct pattern
+
+Don't set `layout: false`. Don't wrap page content in `<NuxtLayout>` inside the page itself. Let
+Nuxt's default `app.vue` (no need to write your own) apply the layout once, persistently, at the
+app level:
+
+```vue
+<!-- pages/contact.vue — CORRECT -->
+<template>
+  <div class="contact-page-content">
+    <div class="hero">...</div>
+  </div>
+</template>
+
+<script setup lang="ts">
+// no definePageMeta({ layout: false }) needed
+</script>
+```
+
+`layouts/default.vue` itself needs no changes — it already receives page content via its
+`<slot name="default">` (or plain `<slot>`), which is exactly what Nuxt's automatic wrapping
+provides.
+
+With this structure, `pageTransition` only ever wraps the page component's own root element
+(`.contact-page-content` etc.) — the header/nav/footer live in the persistent `<NuxtLayout>`
+*outside* `<NuxtPage>`, so they never unmount, never fade, and stay visually static across every
+navigation. Verified via Playwright: with a real transition duration in place, the header DOM node
+and its computed `opacity` stay unchanged for the header across the whole navigation, while only
+the page-content element's class list cycles through
+`page-leave-from` → `page-leave-active`/`page-leave-to` → `page-enter-from`/`page-enter-active` →
+`page-enter-to`.
+
+## Migrating an app off the anti-pattern
+
+For every page:
+
+1. Remove `definePageMeta({ layout: false })` (delete the whole call if that was its only option).
+2. Remove the `<NuxtLayout name="default">`/`</NuxtLayout>` wrapper tags from the template,
+   de-indenting the content that was inside them by one level. Keep the page's own outer element
+   (add a scoping class here if it didn't have one — see the body-class warning in
+   `component-local-style-override.md`, since this is also the right place to move any
+   `bodyAttrs.class`-scoped local `<style>` to).
+
+Verify with `npx tsc --noEmit` (or `nuxt build`) afterward — a stray extra `</NuxtLayout>` or
+mismatched brace is easy to leave behind when doing this across many files by hand.
+
+## Giving the transition an actual CSS effect
+
+`pageTransition: { name: "page", mode: "out-in" }` alone does nothing visible — Vue's `<Transition>`
+needs matching CSS classes or it's an instant, unanimated swap. A simple fade:
+
+```css
+.page-enter-active,
+.page-leave-active {
+  transition: opacity 0.2s ease;
+}
+.page-enter-from,
+.page-leave-to {
+  opacity: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .page-enter-active,
+  .page-leave-active {
+    transition: none;
+  }
+}
+```
+
+`mode: "out-in"` fades the old page fully out before the new one fades in — no overlap, no need for
+`position: absolute` tricks during the transition.
+
+## See also
+
+- `component-local-style-override.md` — the body-class race this pattern also exposes, and the
+  `{name}-page-content` naming convention used above

package/.claude/skills/theming-form-geometry-tokens.md

@@ -17,6 +17,18 @@ imported before or after this layer's `main.css` in `nuxt.config.ts`'s `css` arr
 always wins either way. `theming-override-default.md`/`theming-partial-override.md` already rely
 on this same mechanism for colour tokens; it applies identically here.
 
+> **⚠️ Do not "fix" this by wrapping your override in `@layer consumer`** to mirror the library's
+> own `@layer reset, colours, theming, form-tokens, typography, a11y, components, utilities,
+> consumer;` stack — it looks like the intended slot but is unsafe in practice. Cascade layer
+> priority is fixed by whichever layer name is first referenced *anywhere in the document*, not by
+> its position in that pre-declaration. Nuxt/Nitro inlines many small per-component/per-page CSS
+> chunks as `<style>` tags directly in `<head>` for SSR performance — if an inlined chunk declares
+> `@layer consumer` before the library's main stylesheet (which carries the master statement) loads
+> via its `<link>`, `consumer` gets registered first and pushed to the *lowest* priority instead of
+> the highest, so `@layer form-tokens`/`theming` silently win instead, with no build error.
+> Confirmed by reproducing against a real `npm run build` + preview, not just `nuxt dev`. Stay
+> unlayered — that's what makes the guarantee above hold.
+
 So: to change one geometry value, redeclare just that one custom property in your app's own CSS
 (e.g. `app/assets/styles/setup/03.theming/_default.css`, or a new file imported the same way).
 There is no dependency between these tokens — overriding `--button-padding-inline` alone does not

package/.claude/skills/theming-override-default.md

@@ -16,6 +16,20 @@ For the full architecture see `theming-colour-ramps.md`.
 
 ## Steps
 
+> **⚠️ Keep every file in this skill unlayered — never wrap them in `@layer consumer` (or any
+> named layer)**, even though the library reserves `consumer` as the last name in its own
+> `@layer reset, colours, theming, form-tokens, typography, a11y, components, utilities, consumer;`
+> stack. Cascade layer priority is fixed by whichever layer name is first referenced *anywhere in
+> the document*, not by its position in that pre-declaration. Nuxt/Nitro inlines many small
+> per-component/per-page CSS chunks as `<style>` tags directly in `<head>` for SSR performance —
+> if one of those happens to declare `@layer consumer` before the library's main stylesheet (which
+> carries the master `@layer` statement) loads via its `<link>`, `consumer` gets registered first
+> and pushed to the *lowest* priority, so `@layer theming` silently wins instead — e.g. every
+> button reverting to the library's default blue with no build error. Confirmed by reproducing
+> against a real `npm run build` + preview, not just `nuxt dev`. Unlayered CSS always wins over
+> every named layer regardless of document order, which is what makes the "wins the cascade
+> automatically" claim below actually true.
+
 ### 1. Create `ramps.config.mjs` in your project root
 
 Define the palettes you want. You can add brand-new ones, reuse a built-in name to replace

package/.claude/skills/theming-partial-override.md

@@ -14,6 +14,23 @@ All library tokens are declared inside `@layer theming`. Any CSS written outside
 automatically — no `!important` or specificity tricks required. Override files just need to load
 after the layer styles.
 
+> **⚠️ Never wrap your override CSS in a named `@layer` (e.g. `@layer consumer`), even though the
+> library reserves `consumer` as the last name in its own `@layer reset, colours, theming,
+> form-tokens, typography, a11y, components, utilities, consumer;` stack and it looks like the
+> "correct" slot to write into.
+>
+> Cascade layer *priority* order is fixed by whichever layer name is first referenced anywhere in
+> the document — not by where it sits in a later `@layer a, b, c;` pre-declaration. Nuxt/Nitro
+> inlines many small per-component/per-page CSS chunks as `<style>` tags directly in `<head>` for
+> SSR performance. If an inlined chunk declares `@layer consumer { ... }` before the library's
+> main stylesheet (which carries the master `@layer` statement) has loaded via its `<link>`,
+> `consumer` gets registered *first* — pushed to the *lowest* priority instead of the intended
+> highest — and `@layer theming`/`@layer components` silently win instead, with no build error.
+> This reproduces in a real `npm run build` + preview, not just `nuxt dev`.
+>
+> Keep all consumer-app override CSS **unlayered**. Unlayered CSS always wins over every named
+> layer regardless of document/inlining order, which is what "wins automatically" above relies on.
+
 ## Semantic slots — the tokens to override
 
 All themed components share an 11-slot vocabulary (see `_theme-slots.css`). Overriding these

package/.vscode/srcdev-component-accordian-core.code-snippets

@@ -0,0 +1,74 @@
+{
+  "SRCDEV AccordianCore Basic": {
+    "description": "AccordianCore grouped into an exclusive-open accordion (shared name)",
+    "scope": "vue,html",
+    "body": [
+      "<AccordianCore name=\"$1faq\" :item-count=\"$2\">",
+      "  <template #accordian-0-summary>",
+      "    <span>$3Question one?</span>",
+      "  </template>",
+      "  <template #accordian-0-content>",
+      "    <p>$4Answer one.</p>",
+      "  </template>",
+      "",
+      "  <template #accordian-1-summary>",
+      "    <span>$5Question two?</span>",
+      "  </template>",
+      "  <template #accordian-1-content>",
+      "    <p>$6Answer two.</p>",
+      "  </template>",
+      "</AccordianCore>"
+    ]
+  },
+  "SRCDEV AccordianCore Classic Variant": {
+    "description": "AccordianCore using ExpandingPanelClassic panels (animation runs in every browser)",
+    "scope": "vue,html",
+    "body": [
+      "<AccordianCore name=\"$1faq\" :item-count=\"$2\" variant=\"classic\">",
+      "  <template #accordian-0-summary>",
+      "    <span>$3Question one?</span>",
+      "  </template>",
+      "  <template #accordian-0-content>",
+      "    <p>$4Answer one.</p>",
+      "  </template>",
+      "",
+      "  <template #accordian-1-summary>",
+      "    <span>$5Question two?</span>",
+      "  </template>",
+      "  <template #accordian-1-content>",
+      "    <p>$6Answer two.</p>",
+      "  </template>",
+      "</AccordianCore>"
+    ]
+  },
+  "SRCDEV AccordianCore Programmatic Slots": {
+    "description": "AccordianCore with slots generated from an items array via v-for",
+    "scope": "vue,html",
+    "body": [
+      "<AccordianCore :item-count=\"$1items.length\">",
+      "  <template v-for=\"(item, i) in $1items\" #[`accordian-\\${i}-summary`] :key=\"i\">",
+      "    <span>{{ item.$2title }}</span>",
+      "  </template>",
+      "  <template v-for=\"(item, i) in $1items\" #[`accordian-\\${i}-content`] :key=\"i\">",
+      "    <p>{{ item.$3body }}</p>",
+      "  </template>",
+      "</AccordianCore>"
+    ]
+  },
+  "SRCDEV AccordianCore CSS Override": {
+    "description": "CSS override scaffold for AccordianCore panel-level styling",
+    "scope": "css",
+    "body": [
+      ".$1my-accordian {",
+      "  .display-accordian {",
+      "    /* max-width: none; */",
+      "",
+      "    .accordian-item.expanding-panel {",
+      "      /* border-block-end: 1px solid currentColor; */",
+      "      /* border-radius: $2; */",
+      "    }",
+      "  }",
+      "}"
+    ]
+  }
+}