srcdev-nuxt-components 9.6.2 → 9.6.3

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

@@ -287,6 +287,29 @@ prop and try to pass it. Make it unmistakable:
 
 `PriceList.stories.ts` and `GoogleReviews.stories.ts` (line-clamp controls) follow this.
 
+## Docs page
+
+`.storybook/preview.ts` sets `tags: ["autodocs"]` globally (2026-10-14), so every story file gets a
+generated Docs page and the meta doesn't need the tag. Before that, only two files opted in, and
+the earlier nightly `@nuxtjs/storybook` didn't render Docs pages at all, so a lot of existing
+`docs.description` text had never been visible. Check the page whenever you add or change a story
+(compliance checklist item 6c):
+
+- `parameters.docs.description.component` in the meta: what the component is for and its main
+  props, slots and events. `docs.description.story` on a story: what that story shows.
+- The Docs page renders every story inline in one document. Overlays (`position: fixed`), dialogs,
+  toasts, fullscreen canvases and scroll-driven effects break or overlap there. Render them in
+  their own iframe instead:
+
+  ```ts
+  parameters: {
+    docs: { story: { inline: false, height: "480px" } },
+  },
+  ```
+
+- Opt a file out with `tags: ["!autodocs"]` only when it isn't a component reference (tooling, or
+  a file with its own attached `.mdx` page, like `ColourRamps.stories.ts` with `SetupGuide.mdx`).
+
 ## 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
@@ -362,6 +385,19 @@ story: "See the [CookieConsentBanner](?path=/story/molecules-cookieconsentbanner
   controls that make sense (hide irrelevant ones with `Story.argTypes = { x: { table: { disable: true } } }`),
   or, for a fixed showcase (comparisons, all-themes grids, composition examples), add
   `controls: { disable: true }` to that story's `parameters`.
+- **Sidebar order** comes from the `storySort` function in `.storybook/preview.ts`: top-level
+  groups in tier order, everything below them alphabetical, entries within one component in file
+  order with Docs first. Storybook doesn't run that function from the compiled file. It extracts
+  the function's source and `eval`s it as plain JavaScript, so any TypeScript inside it
+  (annotations, `as` casts) or a reference to something outside its body fails the whole preview
+  build with `SyntaxError: Unexpected token ':'` (found 2026-10-15). It stays annotation-free
+  under a `// @ts-expect-error`. Check an edit without starting Storybook:
+
+  ```bash
+  node --input-type=module -e 'import { getStorySortParameter } from "storybook/internal/csf-tools"; import fs from "node:fs"; console.log(typeof getStorySortParameter(fs.readFileSync(".storybook/preview.ts", "utf8")));'
+  ```
+
+  `function` means it parses; a syntax error is the same one Storybook would hit.
 
 ## Scroll/animation-driven effects need surrounding chrome, not just the bare component
 

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

@@ -42,6 +42,52 @@ overrides (2026-08-25):
 Tier 1 is the one deliberate exception. Everything else gets a real component-prefixed name with
 an inline fallback, even if that fallback happens to be a Tier 1 or Tier 2 token underneath.
 
+## Public vs private tokens
+
+Rule: `.claude/rules/css-public-private-tokens.md`.
+
+The public/private decision is about **consumer relevance, not reuse
+count**. A value a consumer could plausibly want to customise — colours, spacing, sizes, radii,
+durations, and any per-state variant of these (a hover outline width, a focus border colour) — is
+a **public token**, consumed directly at its point of use: `border-radius: var(--component-name-border-radius, 0.5rem)`.
+This holds even when it's only used once — single-use is not a reason to demote a genuinely
+consumer-facing value to private. Per-state variants get their own public token that falls back
+to the resting one, rather than being derived privately: `--component-name-outline-width-hover`
+falling back to `--component-name-outline-width`, not a private var with no override hook.
+
+A value with **no plausible consumer relevance** — genuine internal implementation detail, e.g.
+something composed from a `v-bind()` JS value, or an intermediate that exists purely to avoid
+repeating a computation — is a **private token**, always prefixed `--_x`. Prefix it even when
+it's used only once: the underscore is a grep-able, at-a-glance "this is not public API" signal,
+and that signal shouldn't depend on how many places the value happens to appear.
+
+```css
+/* ✅ Single-use, consumer-facing — still a public token, consumed directly */
+.component-name {
+  border-radius: var(--component-name-border-radius, 0.5rem);
+  transition: all var(--component-name-transition-duration, 300ms) ease;
+}
+
+/* ✅ Resting/hover pair — both public, hover falls back to resting; --_ only wraps the
+   genuinely-shared intermediate so the fallback chain isn't repeated */
+.component-name {
+  --_border-colour: var(--component-name-border-colour, transparent);
+  border-color: var(--_border-colour);
+
+  &:hover {
+    border-color: var(--component-name-border-colour-hover, var(--_border-colour));
+  }
+}
+
+/* ✅ Private — internal only, no consumer would ever want to override this directly */
+.component-name {
+  --_computed-offset: calc(v-bind(dynamicWidth) * 0.5px);
+}
+```
+
+CLAUDE.md pitfall #20 is the concrete case (`ServicesCard`'s private layer wrapped public tokens with
+no composition or state-swap behind them: pure pass-through duplication, not genuine privacy).
+
 ## Naming convention
 
 `--{component-kebab-name}-{variant-if-any}-{property}[-state]`

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

@@ -47,7 +47,7 @@ affects buttons, inputs, prompts, and toasts simultaneously:
 | `--theme-border-focus`      | `--colour-theme-4` / `3` | Focused border                                                                                                           |
 | `--theme-ring`               | `--colour-theme-1` / `9` | Focus ring (outline)                                                                                                     |
 | `--theme-on-surface`        | `--colour-theme-0`       | Text/icon on filled/inverted surface (fixed light value in both modes — pair this with any dark-in-light-mode surface, not `--theme-text`) |
-| `--theme-text`               | `--colour-theme-9` / `2` | Text on page, outline element text (assumes a *light* surface — don't pair with `--theme-surface-hover`/`-inverted`, see pitfall #13 in `Claude.md`) |
+| `--theme-text`               | `--colour-theme-9` / `2` | Text on page, outline element text (assumes a *light* surface — don't pair with `--theme-surface-hover`/`-inverted`, see pitfall #13 in `CLAUDE.md`) |
 | `--theme-text-inverted`     | `--colour-theme-0` / `7` | Text on `--theme-surface-inverted` (fixed to a light value in light mode as of 2026-08-03 — was `--colour-theme-9`, identical to the surface it sits on) |
 
 Input-specific tokens:

package/.vscode/srcdev-component-pricing-card.code-snippets

@@ -4,97 +4,65 @@
     "scope": "vue,html",
     "body": [
       "<PricingCard",
-      "  planName=\"$1Single Site\"",
+      "  plan-name=\"$1Single Site\"",
       "  :price=\"$2199\"",
-      "  billingPeriod=\"$3one-time\"",
-      "  description=\"$4Perfect for freelancers and solo practitioners.\"",
-      "  :features=\"[",
-      "    '$5Feature 1',",
-      "    '$6Feature 2',",
-      "    '$7Feature 3',",
-      "  ]\"",
-      "  @select=\"$8handleSelect\"",
+      "  currency-symbol=\"$3£\"",
+      "  billing-period=\"$4one-time\"",
+      "  description=\"$5Perfect for freelancers and solo practitioners.\"",
+      "  :features=\"['$6Feature 1', '$7Feature 2', '$8Feature 3']\"",
+      "  @select=\"$9handleSelect\"",
       "/>"
     ]
   },
   "SRCDEV PricingCard Highlighted": {
-    "description": "PricingCard with 'Most Popular' highlight and custom button",
+    "description": "PricingCard with 'Most Popular' highlight",
     "scope": "vue,html",
     "body": [
       "<PricingCard",
-      "  planName=\"$1Agency\"",
+      "  plan-name=\"$1Agency\"",
       "  :price=\"$2499\"",
-      "  billingPeriod=\"$3one-time\"",
+      "  billing-period=\"$3one-time\"",
       "  description=\"$4Best for growing teams.\"",
-      "  :is-highlighted=\"true\"",
-      "  :features=\"[",
-      "    '$5Feature 1',",
-      "    '$6Feature 2',",
-      "    '$7Feature 3',",
-      "  ]\"",
-      "  @select=\"$8handleSelect\"",
-      ">",
-      "  <template #cta=\"{ ctaText, isDisabled, onSelect }\">",
-      "    <InputButton",
-      "      :button-text=\"ctaText\"",
-      "      variant=\"$9primary\"",
-      "      :readonly=\"isDisabled\"",
-      "      @click=\"onSelect\"",
-      "    />",
-      "  </template>",
-      "</PricingCard>"
+      "  is-highlighted",
+      "  badge-text=\"$5Most Popular\"",
+      "  :features=\"['$6Feature 1', '$7Feature 2', '$8Feature 3']\"",
+      "  @select=\"$9handleSelect\"",
+      "/>"
     ]
   },
   "SRCDEV PricingCard Grid": {
-    "description": "Three-card pricing comparison grid",
+    "description": "Pricing comparison grid from a plans array",
     "scope": "vue,html",
     "body": [
-      "<div class=\"pricing-cards-grid\">",
-      "  <PricingCard",
-      "    planName=\"Single Site\"",
-      "    :price=\"$1199\"",
-      "    billingPeriod=\"one-time\"",
-      "    description=\"$2For freelancers.\"",
-      "    :features=\"['$3Feature 1', '$4Feature 2']\"",
-      "    @select=\"handleSelect\"",
-      "  />",
-      "  <PricingCard",
-      "    planName=\"Agency\"",
-      "    :price=\"$5499\"",
-      "    billingPeriod=\"one-time\"",
-      "    description=\"$6For growing teams.\"",
-      "    :is-highlighted=\"true\"",
-      "    :features=\"['$7Feature 1', '$8Feature 2', '$9Feature 3']\"",
-      "    @select=\"handleSelect\"",
-      "  />",
+      "<div class=\"$1pricing-grid\">",
       "  <PricingCard",
-      "    planName=\"Unlimited\"",
-      "    :price=\"$10999\"",
-      "    billingPeriod=\"one-time\"",
-      "    description=\"$11Enterprise plan.\"",
-      "    :features=\"['$12Feature 1', '$13Feature 2', '$14Feature 3', '$15Feature 4']\"",
-      "    @select=\"handleSelect\"",
+      "    v-for=\"plan in $2plans\"",
+      "    :key=\"plan.id\"",
+      "    :plan-name=\"plan.name\"",
+      "    :price=\"plan.price\"",
+      "    :description=\"plan.description\"",
+      "    :features=\"plan.features\"",
+      "    :is-highlighted=\"plan.id === '$3pro'\"",
+      "    heading-tag=\"$4h2\"",
+      "    @select=\"$5handleSelect\"",
       "  />",
       "</div>"
     ]
   },
   "SRCDEV PricingCard Custom Button": {
-    "description": "PricingCard with custom button variant via #cta slot",
+    "description": "PricingCard with custom button via #cta slot",
     "scope": "vue,html",
     "body": [
       "<PricingCard",
-      "  planName=\"$1Premium\"",
+      "  plan-name=\"$1Premium\"",
       "  :price=\"$2799\"",
-      "  billingPeriod=\"$3one-time\"",
-      "  description=\"$4All features included.\"",
-      "  :features=\"['$5Feature 1', '$6Feature 2']\"",
-      "  @select=\"$7handleSelect\"",
+      "  :features=\"['$3Feature 1', '$4Feature 2']\"",
+      "  @select=\"$5handleSelect\"",
       ">",
       "  <template #cta=\"{ ctaText, isDisabled, onSelect }\">",
       "    <InputButton",
       "      :button-text=\"ctaText\"",
-      "      variant=\"$8secondary\"",
-      "      theme=\"$9default\"",
+      "      variant=\"$6secondary\"",
       "      :readonly=\"isDisabled\"",
       "      @click=\"onSelect\"",
       "    />",
@@ -107,17 +75,12 @@
     "scope": "vue,html",
     "body": [
       "<PricingCard",
-      "  planName=\"$1Annual\"",
+      "  plan-name=\"$1Annual\"",
       "  :price=\"$249\"",
-      "  billingPeriod=\"$3per year\"",
-      "  description=\"$4Early adopter pricing on the annual plan.\"",
-      "  ribbonText=\"$5EARLYBIRD50 · 50% off\"",
-      "  :features=\"[",
-      "    '$6Feature 1',",
-      "    '$7Feature 2',",
-      "    '$8Feature 3',",
-      "  ]\"",
-      "  @select=\"$9handleSelect\"",
+      "  billing-period=\"$3per year\"",
+      "  ribbon-text=\"$4EARLYBIRD50 · 50% off\"",
+      "  :features=\"['$5Feature 1', '$6Feature 2']\"",
+      "  @select=\"$7handleSelect\"",
       "/>"
     ]
   },
@@ -127,21 +90,20 @@
     "body": [
       ".$1pricing-page {",
       "  .pricing-card {",
-      "    --pricing-card-border-radius: $2;",
-      "    --pricing-card-padding: $3;",
-      "    --pricing-card-gap: $4;",
-      "    --pricing-card-shadow: $5;",
+      "    --pricing-card-background: $2;",
+      "    --pricing-card-border-radius: $3;",
+      "    --pricing-card-padding: $4;",
+      "    --pricing-card-gap: $5;",
       "    --pricing-card-name-color: $6;",
-      "    --pricing-card-amount-color: $7;",
-      "    --pricing-card-cta-bg: $8;",
-      "    --pricing-card-cta-bg-hover: $9;",
-      "    --pricing-card-ribbon-bg: $10;",
-      "    --pricing-card-ribbon-text: $11;",
+      "    --pricing-card-description-line-clamp: $7;",
+      "    --pricing-card-feature-icon-color: $8;",
+      "    --pricing-card-ribbon-bg: $9;",
+      "    --input-button-primary-surface: $10;",
       "",
       "    &.is-highlighted {",
-      "      --pricing-card-highlight-border: $12;",
-      "      --pricing-card-highlight-shadow: $13;",
-      "      --pricing-card-highlight-scale: $14;",
+      "      --pricing-card-highlight-border: $11;",
+      "      --pricing-card-highlight-scale: $12;",
+      "      --pricing-card-badge-bg: $13;",
       "    }",
       "  }",
       "}"

package/README.md

@@ -25,12 +25,12 @@ defineNuxtConfig({
 
 ## Claude Code Skills
 
-This package ships Claude Code skills — reference docs for components and development tasks — in the `.claude/` directory.
+This package ships Claude Code skills (reference docs for components and development tasks) and a curated set of Claude Code rules (short constraints for working with the layer: CSS nesting, overrides, props, NuxtImg, Storybook args) in the `.claude/` directory.
 
 To make them available in your project, add this script to your `package.json`:
 
 ```json
-"setup:claude": "cp -r node_modules/srcdev-nuxt-components/.claude/skills .claude/skills/srcdev-nuxt-components"
+"setup:claude": "rm -rf .claude/skills/srcdev-nuxt-components .claude/rules/srcdev-nuxt-components && mkdir -p .claude/skills/srcdev-nuxt-components .claude/rules/srcdev-nuxt-components && cp -r node_modules/srcdev-nuxt-components/.claude/skills/. .claude/skills/srcdev-nuxt-components && cp -r node_modules/srcdev-nuxt-components/.claude/rules/consumer/. .claude/rules/srcdev-nuxt-components"
 ```
 
 Then run it after install:
@@ -39,7 +39,7 @@ Then run it after install:
 npm run setup:claude
 ```
 
-Skills are copied into `.claude/skills/srcdev-nuxt-components/` so they never conflict with or overwrite skills your own project defines. Re-running the script after a package update is safe.
+Skills are copied into `.claude/skills/srcdev-nuxt-components/` and rules into `.claude/rules/srcdev-nuxt-components/`, so they never conflict with or overwrite your own project's. Re-running the script after a package update is safe: it replaces only those two `srcdev-nuxt-components` folders, so skills and rules dropped or renamed upstream are removed too, and your own skills and rules are never touched.
 
 ### Automate with postinstall (recommended)
 
@@ -47,7 +47,7 @@ To ensure skills are always up to date, VSCode snippets are installed, and `nuxt
 
 ```json
 "scripts": {
-  "setup:claude": "mkdir -p .claude/skills/srcdev-nuxt-components && cp -r node_modules/srcdev-nuxt-components/.claude/skills/. .claude/skills/srcdev-nuxt-components",
+  "setup:claude": "rm -rf .claude/skills/srcdev-nuxt-components .claude/rules/srcdev-nuxt-components && mkdir -p .claude/skills/srcdev-nuxt-components .claude/rules/srcdev-nuxt-components && cp -r node_modules/srcdev-nuxt-components/.claude/skills/. .claude/skills/srcdev-nuxt-components && cp -r node_modules/srcdev-nuxt-components/.claude/rules/consumer/. .claude/rules/srcdev-nuxt-components",
   "postinstall": "node node_modules/srcdev-nuxt-components/scripts/copy-snippets.mjs && nuxt prepare && npm run setup:claude"
 }
 ```
@@ -56,7 +56,7 @@ To ensure skills are always up to date, VSCode snippets are installed, and `nuxt
 
 1. `copy-snippets.mjs` — copies VSCode snippets (`.code-snippets` files) from the layer to your `.vscode/` folder
 2. `nuxt prepare` — generates Nuxt type declarations
-3. `setup:claude` — copies skills into `.claude/skills/srcdev-nuxt-components/`
+3. `setup:claude` — copies skills into `.claude/skills/srcdev-nuxt-components/` and rules into `.claude/rules/srcdev-nuxt-components/`
 
 > **Note**: The snippet copy must run from your consumer app's postinstall, not the layer's. npm doesn't invoke postinstall hooks for dependencies, so each consumer app is responsible for copying snippets into its own `.vscode/` folder. Don't set `SRCDEV_STANDALONE` in a consumer app: that flag is only for running this layer on its own (it enables dev-only modules and the ramp watcher).
 

package/app/components/01.atoms/animations/scroll-reveal-frame/stories/ScrollRevealFrame.stories.ts

@@ -25,7 +25,9 @@ const meta: Meta<typeof ScrollRevealFrame> = {
     },
   },
   parameters: {
+    // Own iframe on the Docs page: the effect depends on page scroll.
     docs: {
+      story: { inline: false, height: "600px" },
       description: {
         component:
           "Generic clipping frame that pans any slot content vertically as it scrolls through the viewport — driven entirely by CSS Scroll-driven Animations. No scroll listeners, no JS. Use this when you need the parallax reveal with arbitrary content (grids, video, etc.). For a single NuxtImg with optimisation and focal-point control, use ScrollRevealImage instead.",

package/app/components/01.atoms/animations/scroll-reveal-image/stories/ScrollRevealImage.stories.ts

@@ -50,7 +50,9 @@ const meta: Meta<typeof ScrollRevealImage> = {
     },
   },
   parameters: {
+    // Own iframe on the Docs page: the effect depends on page scroll.
     docs: {
+      story: { inline: false, height: "600px" },
       description: {
         component:
           "Single-image parallax reveal built on ScrollRevealFrame. Adds NuxtImg optimisation (src, alt, intrinsic dimensions) and a horizontal focal-point prop (focalX). For arbitrary slot content — grids, video, etc. — use ScrollRevealFrame directly.",

package/app/components/01.atoms/animations/section-parallax/stories/SectionParallax.stories.ts

@@ -45,6 +45,10 @@ export default {
     showOverlay: true,
     overlayText: "A quiet moment.",
   },
+  parameters: {
+    // Own iframe on the Docs page: the effect depends on page scroll and vh heights.
+    docs: { story: { inline: false, height: "600px" } },
+  },
 } as Meta<StoryArgs>;
 
 const Template: StoryFn<StoryArgs> = (args) => ({

package/app/components/01.atoms/animations/view-timeline/stories/WipeAwayVertical.stories.ts

@@ -20,7 +20,9 @@ const meta: Meta<typeof WipeAwayVertical> = {
     styleClassPassthrough: { table: { disable: true } },
   },
   parameters: {
+    // Own iframe on the Docs page: the effect depends on page scroll and vh heights.
     docs: {
+      story: { inline: false, height: "600px" },
       description: {
         component:
           "Scroll-driven vertical wipe effect: each sticky panel wipes away to reveal the next as its paired scrolling section crosses the viewport. Pure CSS — a single-column grid overlays `.sticky-items-container` across all `.scrolling-section` rows via `animation-timeline: view()`, so there's no scroll listener or JS measurement involved. Consumers supply `stickyItem-{n}` slots for each of `itemCount` panels, and `scrollingItem-{n}` slots for only the first `itemCount - 1` — the last panel has nothing left to reveal, so it has no wipe animation or scrolling section of its own, just a small built-in trailing buffer to release cleanly. The sticky panel's own visible height is `--wipe-away-vertical-height` (default `100vh`) — leave the root's own `height` unset (`auto`) so it sizes itself from its children. Browsers without `animation-timeline: view()` support (via `@supports not (...)`) just get the sticky items stacked in normal document flow instead.",

package/app/components/02.molecules/cookie-consent-banner/stories/CookieConsentBanner.stories.ts

@@ -40,7 +40,9 @@ export default {
     styleClassPassthrough: [],
   },
   parameters: {
+    // Own iframe on the Docs page: the banner is fixed to the viewport.
     docs: {
+      story: { inline: false, height: "400px" },
       description: {
         // Drives itself from the real useCookieConsent()/useCookie() state, so
         // once accepted/rejected in this browser it stays hidden across story

package/app/components/02.molecules/input-copy/stories/InputCopy.stories.ts

@@ -4,7 +4,6 @@ import InputCopy from "../InputCopy.vue";
 const meta: Meta<typeof InputCopy> = {
   title: "Molecules/Input Copy",
   component: InputCopy,
-  tags: ["autodocs"],
   argTypes: {
     value: { control: "text" },
     id: {