srcdev-nuxt-components 9.1.28 → 9.1.29

package/.claude/settings.json

@@ -36,13 +36,18 @@
       "Bash(git -C /Users/simoncornforth/websites/nuxt-components log --oneline v9.1.22..HEAD)",
       "Bash(git -C /Users/simoncornforth/websites/nuxt-components log --oneline c401cea..HEAD)",
       "Bash(git -C /Users/simoncornforth/websites/nuxt-components show 3058d63 --stat)",
-      "Bash(git -C /Users/simoncornforth/websites/nuxt-components show 0f99d7a --stat)"
+      "Bash(git -C /Users/simoncornforth/websites/nuxt-components show 0f99d7a --stat)",
+      "Bash(node -e ':*)"
     ],
     "additionalDirectories": [
       "/Users/simoncornforth/websites/nuxt-components/app/components/01.atoms/content-wrappers/content-width",
       "/Users/simoncornforth/websites/nuxt-components/.claude/skills",
       "/Users/simoncornforth/websites/nuxt-components/app/components/02.molecules/navigation/site-navigation/tests",
-      "/Users/simoncornforth/websites/luxury-locs-by-natasha-nuxt3/app/pages"
+      "/Users/simoncornforth/websites/luxury-locs-by-natasha-nuxt3/app/pages",
+      "/Users/simoncornforth/websites/nuxt-components/app/assets/styles/extends-layer",
+      "/Users/simoncornforth/websites/nuxt-components/app/components/01.atoms",
+      "/private/tmp",
+      "/Users/simoncornforth/websites/nuxt-components/app/components/01.atoms/banner-video"
     ]
   }
 }

package/.claude/settings.local.json

@@ -6,7 +6,8 @@
       "WebFetch(domain:drafts.csswg.org)",
       "Bash(grep '\"\"typescript\"\"' package.json)",
       "Bash(grep '\"\"@vue/language-server\\\\|@volar\\\\|vue-tsc\"\"' package.json)",
-      "Bash(npx nuxi prepare)"
+      "Bash(npx nuxi prepare)",
+      "Bash(ls -la /Users/simoncornforth/websites/luxury-locs-by-natasha-nuxt3/.env*)"
     ]
   }
 }

package/.claude/skills/components/banner-video.md

@@ -0,0 +1,186 @@
+---
+name: BannerVideo
+description: BannerVideo full-width hero video banner — props, verticalPosition/horizontalPosition, responsive max-height, reduced-motion fallback, CSS tokens, consumer styling
+type: reference
+---
+
+# BannerVideo
+
+## Overview
+
+`BannerVideo` renders a full-width banner section that plays a muted, looping mp4 video. A poster image is shown as fallback when the user has `prefers-reduced-motion: reduce` set — handled entirely in CSS, no JS.
+
+The banner is sized via `aspect-ratio` so it scales naturally, with `max-height` props capping height at each breakpoint.
+
+### Autoplay mechanism
+
+The video uses `autoplay muted loop playsinline preload="auto"` attributes on the `<video>` element with the src in a `<source>` child. A `:key="src"` on the video element forces Vue to remount it on src changes. `@loadeddata` and `@canplay` events call `tryPlay()`, and a `watch(() => props.src, ..., { immediate: true, flush: 'post' })` calls `kickOffLoad()` (which calls `v.load()` then `tryPlay()`) on mount and src change. `onActivated` handles keep-alive re-activation.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | — | Path to the mp4 video source. **Required.** |
+| `poster` | `string` | — | Path to the fallback/poster image. **Required.** Used as the video `poster` attribute and as the `prefers-reduced-motion` fallback. |
+| `alt` | `string` | `""` | Alt text for the fallback `NuxtImg`. |
+| `imgWidth` | `number` | `1920` | Intrinsic width of the poster image — required for NuxtImg/IPX optimisation. |
+| `imgHeight` | `number` | `1080` | Intrinsic height of the poster image — required for NuxtImg/IPX optimisation. |
+| `tag` | `"section" \| "div" \| "header" \| "main" \| "article"` | `"section"` | HTML element rendered as the root. |
+| `maxHeight` | `string` | `"56rem"` | Maximum height at desktop (≥64em / 1024px). |
+| `maxHeightTablet` | `string` | `undefined` | Maximum height at tablet (48em–64em). Falls back to `maxHeight`. |
+| `maxHeightMobile` | `string` | `undefined` | Maximum height on mobile (<48em). Falls back through tablet → desktop. |
+| `aspectRatio` | `string` | `"21/9"` | CSS `aspect-ratio` of the container (e.g. `"16/9"`, `"21/9"`, `"4/3"`). |
+| `objectFit` | `"cover" \| "contain" \| "fill" \| "none" \| "scale-down"` | `"cover"` | How the video and fallback image fill the banner frame. |
+| `verticalPosition` | `"start" \| "center" \| "end"` | `"center"` | Vertical crop position. Maps to `align-self` on the video element and `object-position` Y on the fallback image. |
+| `horizontalPosition` | `"start" \| "center" \| "end"` | `"center"` | Horizontal crop position. Maps to `object-position` X on the fallback image. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
+
+## Basic usage
+
+```vue
+<BannerVideo
+  src="/videos/hero.mp4"
+  poster="/images/hero-poster.jpg"
+  alt="Studio interior"
+/>
+```
+
+## Common variants
+
+### Responsive max-height per breakpoint
+
+```vue
+<BannerVideo
+  src="/videos/hero.mp4"
+  poster="/images/hero-poster.jpg"
+  alt="Studio interior"
+  max-height="56rem"
+  max-height-tablet="40rem"
+  max-height-mobile="24rem"
+/>
+```
+
+### Tall viewport-filling banner
+
+```vue
+<BannerVideo
+  src="/videos/hero.mp4"
+  poster="/images/hero-poster.jpg"
+  alt="Studio interior"
+  max-height="100vh"
+  aspect-ratio="16/9"
+/>
+```
+
+### Custom focal point
+
+```vue
+<BannerVideo
+  src="/videos/hero.mp4"
+  poster="/images/hero-poster.jpg"
+  alt="Studio interior"
+  vertical-position="end"
+  horizontal-position="center"
+/>
+```
+
+### Full bleed with no block margin
+
+```vue
+<BannerVideo
+  src="/videos/hero.mp4"
+  poster="/images/hero-poster.jpg"
+  alt="Studio interior"
+  :style-class-passthrough="['full-bleed', 'mbe-0']"
+/>
+```
+
+## Positioning explained
+
+The video element uses `height: auto; min-height: 100%` so it overflows the container naturally when aspect ratios differ. `overflow: hidden` on the root clips it. `verticalPosition` maps to `align-self` on the video (shifting which portion of the overflow is visible) and to `object-position` Y on the fallback image.
+
+`horizontalPosition` only affects the fallback image via `object-position` X — the video fills full width so horizontal alignment is a no-op on the video element itself.
+
+| verticalPosition | align-self | object-position Y |
+|---|---|---|
+| `"start"` | `start` | `top` |
+| `"center"` (default) | `center` | `center` |
+| `"end"` | `end` | `bottom` |
+
+| horizontalPosition | object-position X |
+|---|---|
+| `"start"` | `left` |
+| `"center"` (default) | `center` |
+| `"end"` | `right` |
+
+## imgWidth / imgHeight
+
+Always match the intrinsic dimensions of the poster file. NuxtImg uses them to avoid the `w=1536` fallback (not in Vercel's allowed widths: 640, 750, 828, 1080, 1200, 1920, 2048, 3840).
+
+| Image type | imgWidth | imgHeight |
+|---|---|---|
+| Landscape / banner (16:9) | `1920` | `1080` |
+| Wide banner (12:5) | `1920` | `800` |
+| Square | `800` | `800` |
+
+## CSS custom properties
+
+All set from props via inline `:style` on the root element.
+
+| Property | Default | Set by prop |
+|---|---|---|
+| `--_max-height` | `56rem` | `maxHeight` |
+| `--_max-height-tablet` | *(unset)* | `maxHeightTablet` |
+| `--_max-height-mobile` | *(unset)* | `maxHeightMobile` |
+| `--_aspect-ratio` | `21/9` | `aspectRatio` |
+| `--_align-self` | `center` | `verticalPosition` |
+| `--_justify-self` | `center` | `horizontalPosition` |
+
+**Responsive override example:**
+
+```css
+.my-page {
+  .banner-video {
+    --_max-height: 56rem;
+
+    @media (width < 1024px) {
+      --_max-height: 40rem;
+    }
+
+    @media (width < 768px) {
+      --_max-height: 24rem;
+    }
+  }
+}
+```
+
+## CSS classes
+
+| Class | Applied when |
+|---|---|
+| `.banner-video` | Always — the root element |
+| `.video` | The `<video>` element |
+| `.fallback` | The `<NuxtImg>` fallback — hidden by default, shown via `prefers-reduced-motion` CSS |
+
+## Consumer styling
+
+Use an unscoped style block scoped by a page or section wrapper class. No `:deep()` needed — the component's styles live in `@layer components` so page styles win automatically.
+
+```vue
+<style>
+.my-page {
+  .banner-video {
+    @media (width < 900px) {
+      --_max-height: 36rem;
+    }
+  }
+}
+</style>
+```
+
+## Notes
+
+- `loading="eager"` and `decoding="async"` are hardcoded on the fallback `NuxtImg` — it is above the fold by definition.
+- The video has `autoplay muted loop playsinline preload="auto"` — intentional and not configurable. This component is for ambient background video only, not user-controlled media.
+- `prefers-reduced-motion` is handled in CSS (`.video { display: none }` + `.fallback { display: block }`), not via JS.
+- Storybook: the `"none"` image provider is active, so `poster` paths pass through unchanged. Always provide explicit `img-width` and `img-height` to avoid the `w=1536` fallback in deployed Storybook.

package/.claude/skills/components/scroll-reveal-frame.md

@@ -0,0 +1,136 @@
+---
+name: ScrollRevealFrame
+description: ScrollRevealFrame generic parallax clipping frame — props, slot API, CSS tokens, browser support, when to use vs ScrollRevealImage
+type: reference
+---
+
+# ScrollRevealFrame
+
+## Overview
+
+`ScrollRevealFrame` is a generic clipping frame that pans its slot content vertically as it scrolls through the viewport — driven entirely by CSS Scroll-driven Animations. No scroll event listeners, no `requestAnimationFrame`, no `IntersectionObserver`.
+
+Use `ScrollRevealFrame` when the content inside the frame is **anything other than a single `NuxtImg`** — a grid of images, a video, a card, arbitrary markup. For a single optimised image with focal-point control, use `ScrollRevealImage` instead (it wraps this component).
+
+## How it works
+
+- The `<figure>` root is a fixed-height clipping window (`overflow: hidden`) that registers a named `view-timeline`.
+- The inner `.reveal-content` wrapper is taller than the frame by `parallaxOffset` and animates `translateY` as the frame scrolls through the viewport.
+- Slot content fills that wrapper — anything inside pans as a unit.
+
+Browser support (as of 2026): Chrome 115+, Edge 115+, Firefox 114+, Safari 17.2+. Older browsers fall back to a static cropped view.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `frameHeight` | `string` | `"540px"` | Height of the visible clipping frame. Any CSS length unit (`px`, `vh`, `rem`). |
+| `parallaxOffset` | `string` | `"36rem"` | Distance the content travels vertically across the full scroll range. Larger = more dramatic reveal. |
+| `radius` | `string` | `"0px"` | `border-radius` applied to the clipping frame. Slot content stays contained within the rounded shape. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root `<figure>`. |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | Content to pan. It fills a `div.reveal-content` that is taller than the frame by `parallaxOffset`. |
+
+## Basic usage — single image
+
+```vue
+<ScrollRevealFrame frame-height="540px" parallax-offset="36rem">
+  <img
+    src="/images/hero.jpg"
+    alt="Hero"
+    style="width: 100%; height: 100%; object-fit: cover; display: block;"
+  />
+</ScrollRevealFrame>
+```
+
+## Grid of images
+
+Wrap each `<img>` / `<NuxtImg>` in a `<div>` cell — `object-fit` on an `<img>` that is a direct grid item still lets the intrinsic dimensions influence the cell size. The wrapper takes the grid sizing; the image fills it.
+
+```vue
+<ScrollRevealFrame frame-height="480px" parallax-offset="36rem">
+  <div class="image-grid">
+    <div class="image-grid__cell">
+      <NuxtImg src="/images/a.jpg" alt="A" :width="800" :height="800" class="image-grid__img" />
+    </div>
+    <div class="image-grid__cell">
+      <NuxtImg src="/images/b.jpg" alt="B" :width="800" :height="800" class="image-grid__img" />
+    </div>
+    <div class="image-grid__cell">
+      <NuxtImg src="/images/c.jpg" alt="C" :width="800" :height="800" class="image-grid__img" />
+    </div>
+  </div>
+</ScrollRevealFrame>
+```
+
+```css
+.image-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  grid-template-rows: repeat(1, 1fr); /* adjust for row count */
+  gap: 4px;
+  height: 100%;
+}
+
+.image-grid__cell {
+  overflow: hidden;
+  min-height: 0; /* prevent grid blowout from intrinsic image size */
+}
+
+.image-grid__img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+```
+
+## Responsive frame height
+
+The `frameHeight` prop sets `--_frame-height` as an inline style. To vary it responsively, override the CSS custom property in a scoped style block:
+
+```css
+.my-page {
+  .reveal-frame {
+    --_frame-height: 320px;
+
+    @media (width >= 768px) {
+      --_frame-height: 540px;
+    }
+  }
+}
+```
+
+## CSS custom properties
+
+These are set from props via inline `:style` but can be overridden in CSS for responsive or contextual control.
+
+| Property | Default | Set by prop |
+|----------|---------|-------------|
+| `--_frame-height` | `540px` | `frameHeight` |
+| `--_parallax-offset` | `36rem` | `parallaxOffset` |
+| `--_radius` | `0px` | `radius` |
+
+## Choosing parallaxOffset
+
+The animation spans the full time the frame is in the viewport. On a typical desktop (~900px viewport, 540px frame) the total scroll travel is ~1440px. A rule of thumb:
+
+| Frame height | Recommended parallaxOffset |
+|---|---|
+| `320px` | `20rem–24rem` |
+| `480px` | `28rem–36rem` |
+| `540px` | `36rem` (default) |
+| `70vh` | `48rem–60rem` |
+
+Values below `20rem` tend to look static at normal scroll speeds.
+
+## Notes
+
+- `overflow: hidden` is on the root `<figure>` — content that needs to escape (dropdowns, tooltips) must be portalled outside.
+- The named `view-timeline` (`--reveal-frame-timeline`) is scoped to the component. Multiple `ScrollRevealFrame` instances on the same page are independent.
+- Reduced-motion: the animation is disabled and the content falls back to a static centred crop via `@media (prefers-reduced-motion: reduce)`.
+- Do not put `ScrollRevealFrame` inside a container with `overflow: hidden` or `overflow: clip` — this breaks the `view-timeline` scroll detection.

package/.claude/skills/components/scroll-reveal-image.md

@@ -0,0 +1,161 @@
+---
+name: ScrollRevealImage
+description: ScrollRevealImage single-image parallax reveal — props, focalX usage, CSS tokens, browser support, when to use vs ScrollRevealFrame
+type: reference
+---
+
+# ScrollRevealImage
+
+## Overview
+
+`ScrollRevealImage` is a convenience wrapper around `ScrollRevealFrame` for the common case of a single optimised image. It adds `NuxtImg` (with intrinsic dimension props for Vercel/IPX optimisation) and a `focalX` prop to pin the horizontal crop axis as the image pans vertically.
+
+For arbitrary slot content — a grid of images, video, markup — use `ScrollRevealFrame` directly.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | — | Image source path. **Required.** |
+| `alt` | `string` | `""` | Alt text for the image. |
+| `imgWidth` | `number` | `1920` | Intrinsic width of the source image — required for NuxtImg optimisation. |
+| `imgHeight` | `number` | `1080` | Intrinsic height of the source image — required for NuxtImg optimisation. |
+| `frameHeight` | `string` | `"540px"` | Height of the visible clipping frame. Any CSS length unit (`px`, `vh`, `rem`). |
+| `parallaxOffset` | `string` | `"36rem"` | Distance the image travels vertically across the full scroll range. Larger = more dramatic reveal. |
+| `focalX` | `string` | `"50%"` | Horizontal focal point — CSS `object-position` x-axis value. Controls which horizontal slice stays in view. |
+| `radius` | `string` | `"0px"` | `border-radius` applied to the clipping frame. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root `<figure>`. |
+
+## Basic usage
+
+```vue
+<ScrollRevealImage
+  src="/images/hero.jpg"
+  alt="Hair portrait"
+  :img-width="1280"
+  :img-height="1920"
+/>
+```
+
+## Common variants
+
+### Short banner frame
+
+```vue
+<ScrollRevealImage
+  src="/images/banner.webp"
+  alt="Banner"
+  :img-width="1920"
+  :img-height="800"
+  frame-height="320px"
+  parallax-offset="24rem"
+/>
+```
+
+### Rounded corners
+
+```vue
+<ScrollRevealImage
+  src="/images/hero.jpg"
+  alt="Portrait"
+  :img-width="1280"
+  :img-height="1920"
+  frame-height="480px"
+  radius="2.4rem"
+/>
+```
+
+### Horizontal focal point
+
+```vue
+<ScrollRevealImage
+  src="/images/hero.jpg"
+  alt="Portrait"
+  :img-width="1280"
+  :img-height="1920"
+  focal-x="75%"
+/>
+```
+
+### Tall frame — maximum travel
+
+```vue
+<ScrollRevealImage
+  src="/images/hero.jpg"
+  alt="Portrait"
+  :img-width="1280"
+  :img-height="1920"
+  frame-height="70vh"
+  parallax-offset="60rem"
+/>
+```
+
+## focalX explained
+
+The vertical position of the image is driven by the scroll animation (`translateY`). `focalX` controls the **horizontal** crop so the subject stays centred when the frame is narrower than the image.
+
+| Value | Crops toward |
+|-------|-------------|
+| `"0%"` or `"left"` | Left edge |
+| `"50%"` (default) | Centre |
+| `"75%"` | Right of centre — useful for a subject offset to the right |
+| `"100%"` or `"right"` | Right edge |
+
+Internally, `focalX` sets `object-position: <focalX> 0%` on the `<img>`. The `Y` is always `0%` because the animation handles vertical travel.
+
+## imgWidth / imgHeight
+
+Always provide these to match the intrinsic dimensions of the source file. NuxtImg uses them to:
+- Generate the correct `srcset` via the IPX pipeline
+- Avoid the `w=1536` fallback (not in Vercel's allowed widths: 640, 750, 828, 1080, 1200, 1920, 2048, 3840)
+
+Common pairs:
+
+| Image type | imgWidth | imgHeight |
+|-----------|----------|-----------|
+| Portrait (3:4) | `1280` | `1920` |
+| Landscape / banner (16:9) | `1920` | `1080` |
+| Wide banner (12:5) | `1920` | `800` |
+| Square | `800` | `800` |
+
+## Responsive frame height
+
+Override `--_frame-height` in a scoped style block for responsive control:
+
+```css
+.my-page {
+  .reveal-frame {
+    --_frame-height: 320px;
+
+    @media (width >= 768px) {
+      --_frame-height: 480px;
+    }
+
+    @media (width >= 1024px) {
+      --_frame-height: 540px;
+    }
+  }
+}
+```
+
+## CSS custom properties
+
+Set from props via inline `:style` — override in CSS for responsive or contextual control.
+
+| Property | Default | Set by prop |
+|----------|---------|-------------|
+| `--_frame-height` | `540px` | `frameHeight` |
+| `--_parallax-offset` | `36rem` | `parallaxOffset` |
+| `--_radius` | `0px` | `radius` |
+| `--_focal-x` | `50%` | `focalX` |
+
+## Choosing parallaxOffset
+
+See `scroll-reveal-frame.md` for the full guide. For portrait images the default `36rem` is a reliable starting point. Landscape/banner images in shorter frames work better with `20rem–24rem`.
+
+## Notes
+
+- `loading="lazy"` and `decoding="async"` are hardcoded on the `<img>`. If this component is the LCP image, override with `loading="eager"` via a CSS-only approach is not possible — use `ScrollRevealFrame` with a manual `NuxtImg` instead and set `:loading="'eager'"`.
+- Do not place inside a container with `overflow: hidden` or `overflow: clip` — breaks the `view-timeline` scroll detection inherited from `ScrollRevealFrame`.
+- Reduced-motion: animation is disabled and the image falls back to a static crop centred at `object-position: <focalX> 50%`.
+- Storybook: the `"none"` image provider is active (`nuxt.config.ts`), so `src` paths pass through unchanged. Always provide explicit `img-width` and `img-height` props to avoid the `w=1536` fallback in deployed Storybook.

package/.claude/skills/index.md

@@ -26,7 +26,9 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── storybook-add-font.md       — add a new font to Storybook
 ├── testing-add-unit-test.md    — create a Vitest unit test with snapshots
 ├── testing-add-playwright.md   — create a Playwright visual regression test
-├── theming-override-default.md      — override the default theme with a custom colour scale
+├── setup-postinstall.md             — automate nuxt prepare + Claude skills copy via postinstall so neither is forgotten after npm install
+├── theming-override-default.md      — replace the entire default theme with a custom colour scale (full palette swap)
+├── theming-partial-override.md      — override a specific token category (forms, buttons, colours) without a full theme replacement
 ├── 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)
 ├── component-local-style-override.md — styleClassPassthrough + scoped style block for per-usage visual customisation
@@ -35,6 +37,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── component-aria-landmark.md        — useAriaLabelledById composable: aria-labelledby for section/main/article/aside tags
 ├── component-export-types.md         — move inline component types to app/types/components/ barrel for consumer imports
 ├── component-inline-action-button.md — InputButtonCore variant="inline" pattern for buttons embedded in custom input wrappers
+├── vue-video-autoplay.md             — autoplay on client-side navigation: use <source> child (not :src on <video>), :key, and explicit v.load()
 ├── icon-sets.md                      — icon set packages required by layer components, FOUC prevention, component→package map
 ├── robots-env-aware.md               — @nuxtjs/robots: allow crawling on prod domain only, block on preview/staging via env var
 ├── release-notes.md                  — produce release notes as a fenced markdown block from git log
@@ -61,6 +64,9 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── glass-panel.md          — GlassPanel props, slots, CSS token API (--glass-panel-bg/border-color/shadow/highlight), theming override
     ├── navigation-horizontal.md — NavigationHorizontal props, NavItemData type, CSS token API, import path gotcha
     ├── input-copy-core.md      — InputCopyCore: readonly copy-to-clipboard input; props, emits, slots, CSS classes, usage
+    ├── banner-video.md         — BannerVideo: full-width hero video banner, objectFit/objectPosition, responsive max-height, reduced-motion fallback, CSS tokens
+    ├── scroll-reveal-frame.md  — ScrollRevealFrame: generic parallax clipping frame, slot API, image grid pattern, CSS tokens, browser support
+    ├── scroll-reveal-image.md  — ScrollRevealImage: single-image parallax reveal, focalX, imgWidth/imgHeight, responsive frame height
     ├── site-navigation.md      — SiteNavigation: responsive nav with auto-collapse, burger menu, decorator indicators, CSS token API
     └── social-icons-list.md    — SocialIconsList: data-driven social icon links, ISocialIcon type, logos: icon names, CSS tokens
 ```

package/.claude/skills/setup-postinstall.md

@@ -0,0 +1,45 @@
+# Automate nuxt prepare and Claude Skills with postinstall
+
+## Overview
+
+Prevent two common "forgot to run after install" problems in a consuming app:
+
+1. `nuxt prepare` — generates Nuxt type declarations. Skipping it causes TypeScript errors after install or package updates.
+2. `npm run setup:claude` — copies the latest `srcdev-nuxt-components` skills into `.claude/skills/srcdev-nuxt-components/`. Skipping it leaves Claude working from stale skill docs after a package update.
+
+A `postinstall` script runs both automatically after every `npm install`.
+
+## Steps
+
+### 1. Add the scripts to package.json
+
+```json
+"scripts": {
+  "setup:claude": "cp -r node_modules/srcdev-nuxt-components/.claude/skills .claude/skills/srcdev-nuxt-components",
+  "postinstall": "nuxt prepare && npm run setup:claude"
+}
+```
+
+### 2. Check whether your app needs an env flag for nuxt prepare
+
+Some apps set an env var to switch `nuxt.config.ts` behaviour when running outside the full dev server (e.g. `NUXT_STANDALONE=true`). Check your own `nuxt.config.ts` — if it gates any config behind such a variable, add it to the `postinstall` command:
+
+```json
+"postinstall": "NUXT_STANDALONE=true nuxt prepare && npm run setup:claude"
+```
+
+If your `nuxt.config.ts` has no such conditional, plain `nuxt prepare` is sufficient.
+
+### 3. Run once manually to bootstrap
+
+```bash
+npm run setup:claude
+```
+
+From this point on, `npm install` and `npm ci` trigger both steps automatically.
+
+## Notes
+
+- Skills land in `.claude/skills/srcdev-nuxt-components/` — safe to re-run without overwriting your own project's skills.
+- `postinstall` also fires on `npm ci`, so CI environments get the skills too if they have a `.claude/` directory in the project.
+- If you do not want `postinstall` running in CI, guard it: `"postinstall": "[ \"$CI\" = \"true\" ] || (nuxt prepare && npm run setup:claude)"`.

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

@@ -241,6 +241,12 @@ The consuming app's CSS loads after the layer's, so your token overrides win via
 | 24px | 2.4rem |
 | 32px | 3.2rem |
 
+## Token reference
+
+See `CONSUMER-STYLING.md` in the layer package root for the full list of available tokens grouped
+by category. This is the authoritative reference when deciding which tokens to include in your
+override files.
+
 ## Notes
 
 - The `--slate-*` scale comes from the layer and does not need to be redefined — keep all neutral/background tokens pointing at `--slate-*`.