srcdev-nuxt-components 9.6.2 → 9.6.3

package/.claude/rules/consumer/consumer-overrides.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "app/**/*.vue"
+  - "app/**/*.css"
+---
+
+# Overriding srcdev-nuxt-components styles
+
+Override a layer component through its public tokens (`--component-name-*`, listed in its
+`CONSUMER-STYLING.md`) set on an ancestor you own. Never wrap override `<style>` blocks in a named
+`@layer`, never set its private `--_` tokens, and override colours and geometry only, never
+behaviour (`display`, `visibility`, `pointer-events`, `z-index`, animations). Applies in apps that
+extend the layer, not to a component's own styles inside srcdev-nuxt-components.
+
+Why: unlayered CSS always beats the layer's `@layer components`, while a named layer can be ordered
+below it by SSR-inlined chunks; private tokens can change in any release.
+Detail: skill `component-local-style-override.md` (srcdev-nuxt-components).

package/.claude/rules/consumer/css-comment-slash.md

@@ -0,0 +1,13 @@
+---
+paths:
+  - "app/**/*.vue"
+  - "app/**/*.css"
+---
+
+# No `*/` inside CSS comments
+
+Never join token names with a bare slash in a CSS comment (`--_form-*/--_scheme-icon-font-size`);
+write "and" or space the slash.
+
+Why: `*/` closes the comment early and yields a misleading "Unclosed string" error lines later.
+

package/.claude/rules/consumer/css-native-nesting.md

@@ -0,0 +1,13 @@
+---
+paths:
+  - "app/**/*.vue"
+  - "app/**/*.css"
+---
+
+# Native CSS nesting, no Sass concatenation
+
+Never write `&__child` or `&-modifier`. Use `& .block__child` or a top-level `.block__child {}` rule.
+Nest child rules inside the component's root block.
+
+Why: it's Sass syntax; esbuild turns `&__foo` into `:is(__foo)`, which silently matches nothing.
+Detail: skill `css-nesting-conventions.md` (srcdev-nuxt-components).

package/.claude/rules/consumer/css-no-deep.md

@@ -0,0 +1,13 @@
+---
+paths:
+  - "app/**/*.vue"
+---
+
+# `:deep()` only in `<style scoped>`
+
+Never use `:deep()` in an unscoped `<style>` block (srcdev-nuxt-components' own styles are never
+scoped). There, reach a child component with a plain descendant selector (`& .input-button`), or
+better, set the child's public tokens on an ancestor. In a `<style scoped>` block it works as normal.
+
+Why: outside `<style scoped>` `:deep()` stays as an unknown pseudo-class and the browser silently
+drops the whole rule.

package/.claude/rules/consumer/css-rem-base.md

@@ -0,0 +1,11 @@
+---
+paths:
+  - "app/**/*.vue"
+  - "app/**/*.css"
+---
+
+# 1rem = 10px
+
+Calculate rem values on a 10px base (`html { font-size: 62.5% }`): `1.6rem` = 16px, `2.4rem` = 24px.
+
+Why: the browser default 16px base gives wrong sizes.

package/.claude/rules/consumer/css-surface-text-pairing.md

@@ -0,0 +1,13 @@
+---
+paths:
+  - "app/**/*.vue"
+  - "app/**/*.css"
+---
+
+# Text on dark surfaces uses `--theme-on-surface`
+
+Pair a dark/bold surface (`--theme-surface-hover`, `--theme-surface-inverted`) with
+`--theme-on-surface`, never `--theme-text` or `--theme-text-inverted`.
+
+Why: those text tokens assume a light surface, so the pairing renders dark-on-dark in light mode.
+Detail: skill `theming-partial-override.md` (srcdev-nuxt-components).

package/.claude/rules/consumer/css-webkit-support.md

@@ -0,0 +1,15 @@
+---
+paths:
+  - "app/**/*.vue"
+  - "app/**/*.css"
+---
+
+# Load-bearing CSS must work in WebKit / Safari 16
+
+Never rely on a new CSS feature (`::details-content`, `@starting-style`, `appearance: base-select`,
+anchor positioning, ...) for anything load-bearing unless Safari 16 has a working path; decorative
+extras may degrade. Prefer routing to a proven alternative implementation over a CSS-only
+`@supports` patch.
+
+Why: WebKit silently drops unsupported rules, and Chrome's device emulation is still Blink so it
+can't show the gap.

package/.claude/rules/consumer/explicit-vue-imports.md

@@ -0,0 +1,11 @@
+---
+paths:
+  - "app/**/*.spec.ts"
+  - "**/*.stories.ts"
+---
+
+# Import Vue APIs explicitly in tests and stories
+
+Always import `nextTick`, `computed`, `ref`, etc. from `"vue"` in `.spec.ts` and `.stories.ts` files.
+
+Why: auto-imports only apply inside components.

package/.claude/rules/consumer/nuxt-img-dimensions.md

@@ -0,0 +1,12 @@
+---
+paths:
+  - "app/**/*.vue"
+---
+
+# NuxtImg needs numeric width and height
+
+Always give `NuxtImg` numeric `width` and `height` props, roughly the largest rendered pixel width
+(pass a size prop through when it varies). Never `width="100%"`. CSS sizes the displayed image.
+
+Why: without them the Vercel provider requests a width it doesn't allow (`w=1536`), and a
+non-numeric width makes it request its largest screen width for every image.

package/.claude/rules/consumer/srcdev-skills-location.md

@@ -0,0 +1,9 @@
+# Where srcdev-nuxt-components skills live
+
+A skill named as "skill `x.md` (srcdev-nuxt-components)" is at
+`.claude/skills/srcdev-nuxt-components/x.md`. Per-component usage docs are in its `components/`
+subfolder (`.claude/skills/srcdev-nuxt-components/components/<component-name>.md`). Inside the
+srcdev-nuxt-components repo itself, the same files are directly under `.claude/skills/`.
+
+Why: the layer's rules name skills rather than linking a path, so they read the same in the
+library repo and in consuming apps.

package/.claude/rules/consumer/story-args.md

@@ -0,0 +1,12 @@
+---
+paths:
+  - "**/*.stories.ts"
+---
+
+# Story args stay reactive
+
+Never destructure, copy (`ref(args.x)`) or `watch` `args` at setup time. Strip non-prop extra args
+inside a `computed` before `v-bind`, and type the meta as `Meta<StoryArgs>` when it has extra args.
+
+Why: setup runs once, so copied args and watchers miss control changes, and unstripped extras become
+unknown HTML attributes. Detail: skill `storybook-add-story.md` (srcdev-nuxt-components).

package/.claude/rules/consumer/story-register-components.md

@@ -0,0 +1,12 @@
+---
+paths:
+  - "**/*.stories.ts"
+---
+
+# Register every component a story template uses
+
+Every component in a story's `template` string, including ones placed in the component's slots, must
+be listed in that story's `components: {}`.
+
+Why: components aren't auto-registered in story templates; unregistered ones render as unknown tags.
+Detail: skill `storybook-add-story.md` (srcdev-nuxt-components).

package/.claude/rules/consumer/vue-auto-imports.md

@@ -0,0 +1,14 @@
+---
+paths:
+  - "app/**/*.vue"
+  - "app/composables/**/*.ts"
+  - "app/utils/**/*.ts"
+---
+
+# Vue and Nuxt auto-imports
+
+Never import `ref`, `reactive`, `computed`, `watch`, `nextTick`, `useState`, `useRoute`, `useRouter`
+or anything from `~/composables/` in app code. Import only `type`s and external packages.
+
+Why: Nuxt auto-imports them; manual imports are noise and drift from the rest of the codebase.
+Test and story files are the exception (see `explicit-vue-imports.md`).

package/.claude/rules/consumer/vue-no-self-closing.md

@@ -0,0 +1,11 @@
+---
+paths:
+  - "app/**/*.vue"
+---
+
+# No self-closing non-void elements
+
+Always write explicit closing tags on non-void elements and slots: `<slot name="x"></slot>`,
+`<span></span>`. Never `<slot name="x" />`.
+
+Why: ESLint `vue/html-self-closing` rejects it.

package/.claude/rules/consumer/vue-prop-hyphenation.md

@@ -0,0 +1,11 @@
+---
+paths:
+  - "app/**/*.vue"
+  - "**/*.stories.ts"
+---
+
+# Hyphenated props in templates
+
+Always write camelCase props hyphenated in templates: `:item-count`, `:style-class-passthrough`.
+
+Why: ESLint `vue/attribute-hyphenation` requires it.

package/.claude/rules/consumer/vue-props-pattern.md

@@ -0,0 +1,13 @@
+---
+paths:
+  - "app/**/*.vue"
+---
+
+# Props pattern
+
+Always declare props as `interface Props` + `withDefaults(defineProps<Props>(), {...})`, with factory
+functions for array/object defaults. Never use options-style `defineProps({ x: { type, default } })`.
+Never declare `class` or `style` as props; hide them from Storybook controls via `argTypes` instead.
+
+Why: typed props are the standard across srcdev-nuxt-components and its apps, and a
+`class`/`style` prop breaks Vue's automatic `$attrs` inheritance.

package/.claude/rules/consumer/vue-slots-no-computed.md

@@ -0,0 +1,14 @@
+---
+paths:
+  - "app/**/*.vue"
+  - "app/composables/**/*.ts"
+---
+
+# Never derive state from slots in a computed
+
+Never read `useSlots()` inside a `computed()`. Use a plain function called from the template
+(`v-if="hasFooter()"`, `:aria-describedby="ariaDescribedby()"`), including anything derived from it.
+Test by toggling a `v-if`'d slot in a host component after mount.
+
+Why: the slots object isn't reactive, so the computed caches its first value and leaves split state
+when a slot is added or removed after mount.

package/.claude/rules/consumer/vue-video-source.md

@@ -0,0 +1,12 @@
+---
+paths:
+  - "app/**/*.vue"
+---
+
+# Video src goes on a `<source>` child
+
+Never bind `:src` on a `<video>`. Use `<source :src="src">` inside it, `:key="src"` on the video, and
+an explicit `videoEl.load()` on mount and src change.
+
+Why: Vue patching `:src` on client-side navigation silently skips the fetch.
+Detail: skill `vue-video-autoplay.md` (srcdev-nuxt-components).

package/.claude/skills/component-compliance-checklist.md

@@ -15,7 +15,7 @@ A component passes when its Component Ledger row (`node .claude/component-ledger
 `.claude/component-ledger/audit.json`) shows `score: 5`, a real tier, and `variants`, `legacy_props`,
 `story_args_bug`, `eslint_issues`, `redundant_priv_tokens`, `styling_doc_outdated` and `missing_stress_story`
 all `false`.
-The ledger can't see items 9, 10, 11 and 14, so check those by hand.
+The ledger can't see items 6c, 9, 10, 11 and 14, so check those by hand.
 
 ## The checklist
 
@@ -149,6 +149,21 @@ The ledger can't see items 9, 10, 11 and 14, so check those by hand.
     with nothing to stress (animation wrappers, decorative containers that only take a slot and
     tag/variant props, Storybook tooling) are exempt: they are listed in `stressStoryExempt` in
     `.claude/component-ledger/build.mjs`; add a new one there rather than writing a padding story.
+6c. **Storybook docs page** — every story file gets a generated Docs page: `tags: ["autodocs"]` is
+    set globally in `.storybook/preview.ts` (since 2026-10-14), so don't repeat it in the meta.
+    Open the component's Docs page and check that it reads well:
+    - A `parameters.docs.description.component` in the meta says what the component is for and
+      names its main props/slots/events. Per-story `docs.description.story` text explains what
+      that story shows (the Docs page is the only place either is visible).
+    - The props table is accurate. Every story-only arg has a `description` and a category, and
+      CSS-token args are labelled story-only (6b).
+    - Every story renders inline. A story that misbehaves on the shared page (fixed/sticky
+      overlays, `layout: "fullscreen"` canvases, dialogs, toasts, scroll effects, heavy stress
+      data) gets `parameters.docs.story: { inline: false, height: "<px>" }` so it renders in its
+      own iframe. Don't drop it from the page.
+    - A story file that isn't a component reference (Storybook tooling, a file that already has an
+      attached `.mdx` page) opts out with `tags: ["!autodocs"]`. `ColourRamps.stories.ts` does this.
+    See `storybook-add-story.md`, "Docs page".
 7. **Skill doc** — create or update `.claude/skills/components/<component-name>.md`, following the
    pattern of an existing one. A labelled `<Name>Field` wrapper (or any other wrapper) is documented
    in its control's doc under a "Variants" section, not in a doc of its own
@@ -235,3 +250,10 @@ The ledger can't see items 9, 10, 11 and 14, so check those by hand.
       the edits in private memory. Note that an inline-size container can't size itself from its
       content: say so in `CONSUMER-STYLING.md` (`ProfileSection`).
     - Grid tracks that hold text are `minmax(0, …)` so an unbroken string can't widen the grid.
+    - No `:deep()` in the component's `<style>`: these blocks are never scoped, so Vue leaves it
+      as-is and the browser drops the whole rule (pitfall #27). Use a descendant selector, or set
+      the child component's public tokens on an ancestor.
+    - No `font-size` (or font-size token default) under `1rem`. `html` is `62.5%`, so `1rem` is
+      10px, and values like `0.75rem`/`0.9rem` are almost always copied from a 16px-base design
+      and render at 7.5-9px. `PricingCard` had both (fixed 2026-10-15); grep
+      `font-size:\s*(var\([^,]+,\s*)?0?\.[0-9]+rem` to find them.

package/.claude/skills/component-naming.md

@@ -58,7 +58,7 @@ stripping `Core`.
 
 1. `git mv` the `.vue` files, their stories and tests (and the skill doc if it's named after the old
    control name).
-2. `sed` the old names across `app/`, `.claude/`, `.vscode/`, `MIGRATION.md` and `Claude.md`:
+2. `sed` the old names across `app/`, `.claude/`, `.vscode/`, `MIGRATION.md` and `CLAUDE.md`:
    component names, `import` paths, story titles/`*StoryArgs` interfaces, `describe()` names, and the
    root/base DOM class (update `CONSUMER-STYLING.md` and test selectors that use it).
 3. Add a "Renamed YYYY-MM-DD" note at the top of the skill doc listing old → new names and classes.

package/.claude/skills/components/pricing-card.md

@@ -2,7 +2,11 @@
 
 ## Overview
 
-`PricingCard` renders a SaaS-style pricing plan card with plan name, price, description, feature list, and call-to-action button. Supports "Most Popular" highlight state with optional badge. Features are highly customizable via CSS token overrides, and the CTA button can be customized via the `#cta` slot for custom variants and themes.
+`PricingCard` (`app/components/02.molecules/pricing-card/`) renders a pricing plan card: plan name,
+price, billing period, description, feature list and a call-to-action button. `is-highlighted`
+adds a "Most Popular" badge plus a scaled, emphasised border; `ribbon-text` adds a diagonal corner
+ribbon. The CTA can be replaced through the `#cta` slot. Styling tokens:
+`app/components/02.molecules/pricing-card/CONSUMER-STYLING.md`.
 
 ---
 
@@ -10,34 +14,42 @@
 
 > **Hyphenation rule**: Vue's ESLint config enforces `vue/attribute-hyphenation`. Always write camelCase prop names hyphenated in templates: `:style-class-passthrough`.
 
-| Prop (template form)       | Type                          | Default      | Notes                                                              |
-| -------------------------- | ----------------------------- | ------------ | ------------------------------------------------------------------ |
-| `tag`                      | `"div" \| "section" \| "article"` | `"article"` | Root element tag for semantic HTML.                               |
-| `:plan-name`               | `string`                      | (required)   | Plan/tier name (e.g., "Basic", "Professional", "Enterprise").     |
-| `:price`                   | `number`                      | (required)   | Price amount (e.g., `99`, `4.99`). Currency symbol added in template. |
-| `:billing-period`          | `string`                      | `"one-time"` | Billing frequency text (e.g., "monthly", "yearly").              |
-| `:description`             | `string`                      | (optional)   | Short plan description.                                            |
-| `:features`                | `string[]`                    | `[]`         | Array of feature strings. Rendered with checkmark icons.          |
-| `:is-highlighted`          | `boolean`                     | `false`      | Highlight state; applies "Most Popular" badge, border, shadow, and scale. |
-| `:cta-text`                | `string`                      | `"Get started"` | Button label text.                                              |
-| `:cta-disabled`            | `boolean`                     | `false`      | Disables the CTA button.                                          |
-| `:style-class-passthrough` | `string \| string[]`          | `[]`         | Extra CSS classes applied to the card root.                       |
+| Prop (template form)       | Type                                   | Default          | Notes |
+| -------------------------- | -------------------------------------- | ---------------- | ----- |
+| `tag`                      | `"div" \| "section" \| "article"`      | `"article"`      | Root element. Always labelled by the plan name heading (`aria-labelledby`). |
+| `heading-tag`              | `"h2" \| "h3" \| "h4" \| "h5" \| "h6"` | `"h3"`           | Heading level for the plan name; pick to fit the page outline. |
+| `plan-name`                | `string`                               | (required)       | Plan name. |
+| `:price`                   | `number`                               | (required)       | Whole numbers show as-is, fractional ones to two decimals (`9.5` → `9.50`). A non-finite value shows nothing. |
+| `currency-symbol`          | `string`                               | `"$"`            | Literal prefix; no locale formatting. Pass `""` for none. |
+| `billing-period`           | `string`                               | `"one-time"`     | Shown after the price; `""` hides it. |
+| `description`              | `string`                               | `undefined`      | Short plan description. |
+| `:features`                | `string[]`                             | `[]`             | Rendered as a checkmark list (checkmark hidden from screen readers). |
+| `:is-highlighted`          | `boolean`                              | `false`          | Badge, highlight border/shadow, and `scale(1.05)`. |
+| `badge-text`               | `string`                               | `"Most Popular"` | Badge copy; pass a translated string for i18n. |
+| `cta-text`                 | `string`                               | `"Get started"`  | Default button label. |
+| `:cta-disabled`            | `boolean`                              | `false`          | Sets the default button to `readonly`/`aria-disabled`. |
+| `ribbon-text`              | `string`                               | `undefined`      | Corner ribbon copy; unset for no ribbon. Caps at two lines (`--pricing-card-ribbon-line-clamp`). |
+| `:style-class-passthrough` | `string \| string[]`                   | `[]`             | Extra classes on the root. |
+
+All visitor-facing copy (`badge-text`, `cta-text`, `billing-period`) is a prop, so pass strings from
+your own i18n solution.
 
 ---
 
 ## Events
 
-| Event  | Payload    | Notes                                    |
-| ------ | ---------- | ---------------------------------------- |
-| `select` | `planName: string` | Emitted when the CTA button is clicked. |
+| Event    | Payload            | Notes |
+| -------- | ------------------ | ----- |
+| `select` | `planName: string` | Emitted when the default CTA is clicked, or when a `#cta` slot calls `onSelect`. |
 
 ---
 
 ## Slots
 
-### Default slot (features)
+### `#features`
 
-Override the default feature list rendering. Receives no slot scope.
+Replaces the default `<li>` list. Your content goes inside the component's `<ul>`, so render `<li>`
+elements. `--pricing-card-feature-line-clamp` and the checkmark only apply to the built-in list.
 
 ```vue
 <PricingCard plan-name="Pro" :price="99">
@@ -47,97 +59,57 @@ Override the default feature list rendering. Receives no slot scope.
 </PricingCard>
 ```
 
-### #cta slot
+### `#cta`
 
-Customize the CTA button. Default renders `InputButton` with theme support.
+Replaces the default `InputButton`. Slot scope:
 
-**Slot scope:**
-- `ctaText: string` — button label from `:cta-text` prop
-- `isDisabled: boolean` — button disabled state from `:cta-disabled` prop
-- `planName: string` — plan name for context
-- `onSelect: () => void` — callback to trigger `select` event
+- `ctaText: string` — from `cta-text`
+- `isDisabled: boolean` — from `cta-disabled`
+- `planName: string`
+- `onSelect: () => void` — emits `select`
 
 ```vue
 <PricingCard plan-name="Pro" :price="99" @select="handleSelect">
   <template #cta="{ ctaText, isDisabled, onSelect }">
-    <InputButton
-      :button-text="ctaText"
-      variant="secondary"
-      theme="custom"
-      :readonly="isDisabled"
-      @click="onSelect"
-    />
+    <InputButton :button-text="ctaText" variant="secondary" :readonly="isDisabled" @click="onSelect" />
   </template>
 </PricingCard>
 ```
 
 ---
 
-## CSS Token Customization
+## Styling
 
-All `--pricing-card-*` tokens can be overridden at global, page, or instance scope. See `CONSUMER-STYLING.md` in the component directory for full token documentation and examples.
+All `--pricing-card-*` tokens are listed in `CONSUMER-STYLING.md`. The common ones:
 
-**Common tokens:**
-- `--pricing-card-padding` — card internal spacing
-- `--pricing-card-border-radius` — card corners
-- `--pricing-card-cta-bg` — button background
-- `--pricing-card-highlight-border` — highlighted card border
-- `--pricing-card-name-color` — plan name text color
+- `--pricing-card-padding`, `--pricing-card-border-radius`, `--pricing-card-background`
+- `--pricing-card-highlight-border`, `--pricing-card-highlight-scale`
+- `--pricing-card-name-line-clamp`, `--pricing-card-description-line-clamp`, `--pricing-card-feature-line-clamp` (default `none`)
+- `--pricing-card-feature-icon-color` (checkmark colour)
+
+The default CTA is styled with `InputButton`'s own tokens (`--input-button-primary-surface`, etc.),
+set on the card or an ancestor. There are no `--pricing-card-cta-*` colour tokens: the old ones never
+applied and were removed 2026-10-14. `--pricing-card-cta-align` still controls CTA alignment.
 
 ---
 
-## Usage Examples
+## Usage examples
 
-### Single card with default button
+### Single card
 
 ```vue
 <PricingCard
   plan-name="Basic"
   :price="29.99"
-  billing-period="monthly"
+  currency-symbol="£"
+  billing-period="per month"
   description="Perfect for getting started"
   :features="['Feature 1', 'Feature 2', 'Feature 3']"
-  cta-text="Get started"
-  @select="handleSelect"
-/>
-```
-
-### Highlighted "Most Popular" card
-
-```vue
-<PricingCard
-  plan-name="Professional"
-  :price="79.99"
-  billing-period="monthly"
-  :is-highlighted="true"
-  :features="['All Basic features', 'Priority support', 'Advanced analytics']"
   @select="handleSelect"
 />
 ```
 
-### Card with custom button variant
-
-```vue
-<PricingCard
-  plan-name="Enterprise"
-  :price="199.99"
-  billing-period="monthly"
-  description="Everything you need"
-  :features="['Unlimited access', 'Dedicated support', 'Custom integrations']"
-  @select="handleSelect"
->
-  <template #cta="{ ctaText, isDisabled, onSelect }">
-    <InputButton
-      :button-text="ctaText"
-      variant="primary"
-      :readonly="isDisabled"
-      @click="onSelect"
-    />
-  </template>
-</PricingCard>
-```
-
-### Three-column grid with token customization
+### Comparison grid
 
 ```vue
 <div class="pricing-grid">
@@ -148,16 +120,28 @@ All `--pricing-card-*` tokens can be overridden at global, page, or instance sco
     :price="plan.price"
     :is-highlighted="plan.id === 'pro'"
     :features="plan.features"
+    heading-tag="h2"
     @select="handleSelect"
-    style="--pricing-card-padding: 2.5rem; --pricing-card-cta-bg: var(--brand-primary)"
   />
 </div>
 ```
 
+```css
+.pricing-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 26rem), 1fr));
+  gap: 2.4rem;
+}
+```
+
 ---
 
 ## Notes
 
-- Feature checkmarks are always rendered with a teal checkmark (`✓`). Customize the color via `--teal-06` or component tokens.
-- The `#cta` slot is preferred over CSS-only button customization when you need variant or theme changes.
-- Highlighted cards apply a 1.05x scale transform — consider z-index when nesting in flex/grid layouts.
+- The highlight scale is a `transform`, so it doesn't change layout size. In a stacked single
+  column set `--pricing-card-highlight-scale: 1`, or the highlighted card overhangs.
+- The badge sits centred on the top border (`translate: 0 -50%`), so leave some space above the
+  card (grid gap or padding).
+- The plan name gets `--pricing-card-ribbon-clearance` (`6rem`) of right padding while a ribbon is
+  shown, so long names don't run underneath it.
+- Stories: `Molecules/Pricing Card`, including `Stress Test (Worst-Case Data)`.

package/.claude/skills/index.md

@@ -7,10 +7,16 @@ Step-by-step guides for repeatable development tasks in this project.
 Copy skills into your project with:
 
 ```bash
-cp -r node_modules/srcdev-nuxt-components/.claude/skills .claude/skills/srcdev-nuxt-components
+rm -rf .claude/skills/srcdev-nuxt-components && mkdir -p .claude/skills/srcdev-nuxt-components && cp -r node_modules/srcdev-nuxt-components/.claude/skills/. .claude/skills/srcdev-nuxt-components
 ```
 
-Skills land in `.claude/skills/srcdev-nuxt-components/` — safe to re-run without overwriting your own skills.
+Skills land in `.claude/skills/srcdev-nuxt-components/` — safe to re-run: it replaces only that folder, so skills dropped or renamed upstream are removed and your own skills are never touched.
+
+The layer also ships a curated set of Claude Code rules in `.claude/rules/consumer/`. `npm run setup:claude` (see `setup-postinstall.md`) copies skills and rules together; to copy the rules by hand:
+
+```bash
+rm -rf .claude/rules/srcdev-nuxt-components && mkdir -p .claude/rules/srcdev-nuxt-components && cp -r node_modules/srcdev-nuxt-components/.claude/rules/consumer/. .claude/rules/srcdev-nuxt-components
+```
 
 ## Structure
 
@@ -97,7 +103,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── expanding-panel.md      — ExpandingPanel v-model, forceOpened, contentIsOnTop overlay mode, slots (summary/icon/content), ARIA wiring, CSS token API
     ├── content-docs.md         — ContentDocs docs-page shell: prop-driven docsNav/docsPageNav (not slots), DocsNavItem icons, container-width breakpoint behaviour, shared/per-side CSS token API
     ├── glass-panel.md          — GlassPanel: frosted-glass container, light-only token defaults in-component (light-dark() block removed from _default.css, no built-in dark glass), highlight behind content, section/article labelled via headingId slot prop, CSS token API
-    ├── pricing-card.md         — PricingCard: SaaS-style plan card with highlight, feature list, #cta slot for button customization, CSS token API
+    ├── pricing-card.md         — PricingCard: plan card with highlight badge, corner ribbon, feature list, #cta slot, heading-tag, line-clamp tokens
     ├── price-list.md           — PriceList: service/menu price columns (dl rows), PriceListData type, headingTag/fromLabel props, CSS token API
     ├── opening-hours.md        — OpeningHours: per-day data auto-grouped into ranges, split sessions, 24h/appointment, exceptions, Intl formatting, today highlight, JSON-LD, CSS token API
     ├── input-copy.md           — InputCopy: readonly copy-to-clipboard input, visual feedback, Clipboard API, accessibility, CSS token API

package/.claude/skills/new-app-scaffold.md

@@ -44,7 +44,7 @@ to inform the CLAUDE.md and CSS tokens.
     "dev": "nuxt dev",
     "generate": "nuxt generate",
     "preview": "nuxt preview",
-    "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": "NUXT_STANDALONE=true nuxt prepare && npm run setup:claude",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix"
@@ -71,7 +71,9 @@ to inform the CLAUDE.md and CSS tokens.
 
 > **`setup:claude` script**: `mkdir -p` is required — the destination folder won't exist on a
 > fresh clone. The trailing `/.` on the source path copies contents into the destination rather
-> than nesting a `skills` subfolder inside it.
+> than nesting a `skills` subfolder inside it. The leading `rm -rf` clears only the two
+> `srcdev-nuxt-components` folders, so skills and rules dropped or renamed upstream don't linger
+> (a stale rule stays loaded); the app's own `.claude/skills/` and `.claude/rules/` are untouched.
 
 ### 3. Create `nuxt.config.ts`
 

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

@@ -5,7 +5,7 @@
 Prevent 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.
+2. `npm run setup:claude` — copies the latest `srcdev-nuxt-components` skills into `.claude/skills/srcdev-nuxt-components/` and its consumer rules into `.claude/rules/srcdev-nuxt-components/`. Skipping it leaves Claude working from stale skill docs and rules after a package update.
 
 Additionally, `srcdev-nuxt-components` automatically copies VSCode snippet files (`.code-snippets`) to your `.vscode/` folder during its own postinstall, so components' code snippets are available immediately.
 
@@ -17,7 +17,7 @@ A consumer app's `postinstall` script runs both automatically after every `npm i
 
 ```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"
 }
 ```
@@ -26,7 +26,7 @@ This postinstall hook does three things in order:
 
 1. Copies VSCode snippets from the layer to your `.vscode/` folder
 2. Runs `nuxt prepare` to generate type declarations
-3. Runs `setup:claude` to copy skills into `.claude/skills/srcdev-nuxt-components/`
+3. Runs `setup:claude` to copy skills into `.claude/skills/srcdev-nuxt-components/` and rules into `.claude/rules/srcdev-nuxt-components/`
 
 ### 2. Check whether your app needs an env flag for nuxt prepare
 
@@ -49,6 +49,7 @@ From this point on, `npm install` and `npm ci` trigger both steps automatically.
 ## Notes
 
 - **Snippet copy must run in consumer app**: npm doesn't invoke postinstall hooks for dependencies. Each consumer app must explicitly call `scripts/copy-snippets.mjs` in its own postinstall to copy VSCode snippets to `.vscode/`. The layer's postinstall is used when the layer runs standalone, but consumers are responsible for their own `.vscode/` folder.
-- Skills land in `.claude/skills/srcdev-nuxt-components/` — safe to re-run without overwriting your own project's skills.
+- Skills land in `.claude/skills/srcdev-nuxt-components/` and rules in `.claude/rules/srcdev-nuxt-components/` — safe to re-run. The script deletes and recreates only those two folders, so anything dropped or renamed upstream is removed (a stale rule would otherwise stay loaded forever); your own project's skills and rules are never touched.
+- Only the layer's `.claude/rules/consumer/` set ships. The rest of its rules govern the library's own source (naming, ledger, demo pages) and would be wrong in an app.
 - `postinstall` also fires on `npm ci`, so CI environments get the skills and snippets too if they have a `.claude/` directory in the project.
 - If you do not want `postinstall` running in CI, guard it: `"postinstall": "[ \"$CI\" = \"true\" ] || (node node_modules/srcdev-nuxt-components/scripts/copy-snippets.mjs && nuxt prepare && npm run setup:claude)"`.