srcdev-nuxt-components 9.6.1 → 9.6.3

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/components/profile-section.md

@@ -1,24 +1,26 @@
 ---
 name: ProfileSection
-description: ProfileSection molecule — props, dynamic profile-info slots, eyebrowText/heroText/profileLinks slots, layout, accessibility
+description: ProfileSection molecule — props, dynamic profile-info slots, eyebrowText/heroText/profileLinks slots, container-query layout, accessibility
 type: reference
 ---
 
 # ProfileSection
 
+> **Changed 2026-10-14 (breaking):** New `headerPlacement` prop (`above`, `picture-bottom`, `picture-top`) can put the header over the bottom or top of the picture. `profileInfoCount` removed — only the `profile-info-N` slots you give are rendered (it used to pad with empty blocks when none were given). The two-column switch is a container query on the component's own width, not a viewport `@media` query, and both columns are `minmax(0, …)`. The `<header>` is only rendered when a header slot is given. Highlight colours go through new `--profile-section-*` tokens. An invalid `profilePicture.width`/`height` (0, negative, `NaN`) falls back to 828×1104.
+>
 > **Classes renamed 2026-09-27:** `.picture` → `.profile-section-picture`, `.profile-picture` → `.profile-section-image`, `.profile-info` → `.profile-section-info`, `.profile-info-content` → `.profile-section-info-content`, `.profile-info-block` → `.profile-section-info-block`, `.profile-links` → `.profile-section-links`.
 
 ## Overview
 
-`ProfileSection` is a molecule that renders a practitioner/author profile: a header area (eyebrow + heading), a profile picture, and a flexible set of bio/info blocks alongside optional profile links. It is landmark-aware — when `tag` is `section`, `article`, or `aside`, the root element automatically gets `aria-labelledby` wired to the heading inside the `#heroText` slot (**you must bind `headingId` yourself, and a console warning fires if you forget** — see [component-aria-landmark.md](../component-aria-landmark.md)). `tag="main"` is never auto-labelled.
+`ProfileSection` is a molecule that renders a practitioner/author profile: a header area (eyebrow + heading), a profile picture, and a flexible set of bio/info blocks alongside optional profile links. It is landmark-aware — when `tag` is `section` or `article`, the root element automatically gets `aria-labelledby` wired to the heading inside the `#heroText` slot (**you must bind `headingId` yourself, and a console warning fires if you forget** — see [component-aria-landmark.md](../component-aria-landmark.md)). `tag="main"` is never auto-labelled.
 
 ## Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `profilePicture` | `ProfilePicture` (`{ src; alt; width?; height? }`, exported from the layer types) | — | **Required.** Rendered via `NuxtImg` with `width`/`height` defaulting to `828`/`1104` (3:4, a Vercel-allowed width). |
+| `profilePicture` | `ProfilePicture` (`{ src; alt; width?; height? }`, exported from the layer types) | — | **Required.** Rendered via `NuxtImg`. `width`/`height` default to `828`/`1104` (3:4, a Vercel-allowed width), and a missing or invalid value (0, negative, `NaN`, `Infinity`) uses the default. |
 | `tag` | `"div" \| "section" \| "article" \| "main"` | `"div"` | HTML element rendered as the root. |
-| `profileInfoCount` | `number` | `3` | Number of `profile-info-N` slots to generate when none are explicitly provided. |
+| `headerPlacement` | `"above" \| "picture-bottom" \| "picture-top"` | `"above"` | Where the `#eyebrowText`/`#heroText` header goes: above the grid, or over the bottom or top of the picture on a scrim. Template form: `header-placement`. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
 
 ## Slots
@@ -28,17 +30,19 @@ type: reference
 | `#eyebrowText` | Optional eyebrow label above the heading. Use `EyebrowText`. |
 | `#heroText` | Heading slot. Receives `headingId` as a slot prop — bind it to the heading's `id` for accessible `aria-labelledby`. |
 | `#profile-info-1` … `#profile-info-N` | Bio / info blocks. Provide as many numbered slots as needed. They are rendered in ascending numeric order. |
-| `#profileLinks` | Links / actions shown at the bottom-right of the info column (e.g. social icons, booking CTA). |
+| `#profileLinks` | Links / actions shown at the bottom-right of the info column (e.g. social icons, booking CTA). Wraps onto more lines when there are many. |
+
+The `<header class="profile-section-header">` is only rendered when `#eyebrowText` or `#heroText` is given. It renders above the grid, or inside the picture when `header-placement` is `picture-bottom` or `picture-top`.
 
 ## Basic usage
 
 ```vue
 <ProfileSection
   tag="section"
-  :profile-picture="{ src: '/images/profile/mel.jpg', alt: 'Mel Stafford, reflexologist' }"
+  :profile-picture="{ src: '/images/profile/alex.jpg', alt: 'Alex Morgan, hair stylist' }"
 >
   <template #eyebrowText>
-    <EyebrowText font-size="large" text="About Mel" />
+    <EyebrowText font-size="large" text-content="About Alex" />
   </template>
 
   <template #heroText="{ headingId }">
@@ -47,8 +51,8 @@ type: reference
       :id="headingId"
       font-size="title"
       :text-content="[
-        { text: 'Mel Stafford', styleClass: 'normal' },
-        { text: 'Reflexologist', styleClass: 'accent' },
+        { text: 'Alex Morgan', styleClass: 'normal' },
+        { text: 'Hair stylist', styleClass: 'accent' },
       ]"
     />
   </template>
@@ -58,7 +62,7 @@ type: reference
   </template>
 
   <template #profile-info-2>
-    <p>Mel is based in Lichfield…</p>
+    <p class="location">Based in <span class="highlight">Northtown</span>…</p>
   </template>
 
   <template #profileLinks>
@@ -69,11 +73,12 @@ type: reference
 
 ## Dynamic profile-info slots
 
-The `profile-info-N` slots are discovered at runtime by filtering `useSlots()` for keys matching `/^profile-info-\d+$/`. The slots are rendered in ascending numeric order.
+The `profile-info-N` slots are discovered at runtime by filtering `useSlots()` for keys matching `/^profile-info-\d+$/`, and rendered in ascending numeric order.
 
 - If you provide `#profile-info-1`, `#profile-info-2`, `#profile-info-3` — all three render in order.
-- If you provide no `profile-info-*` slots, the component renders `profileInfoCount` empty blocks (they used to contain visible placeholder text, removed 2026-09-27). Slot discovery runs every render, so slots added after mount appear.
-- Gaps are supported — you can provide `#profile-info-1` and `#profile-info-3` without `#profile-info-2`; they sort correctly.
+- If you provide none, no info blocks render.
+- Gaps are supported — you can provide `#profile-info-1` and `#profile-info-3` without `#profile-info-2`; `#profile-info-12` sorts after `#profile-info-2`.
+- Discovery runs every render, so slots added or removed after mount (a `v-if` on the slot template) appear and disappear.
 
 ## heroText slot prop
 
@@ -89,10 +94,41 @@ If you use a different heading component, bind `headingId` to whatever prop rend
 
 ## Layout
 
-- **Mobile**: single column — picture stacked above info.
-- **768px+**: two columns — `--profile-section-picture-width` (`384px`) picture column, `1fr` info column, `--profile-section-gap-wide` (`4rem`) gap (`--profile-section-gap`, `2rem`, below 768px).
-- Picture frame (`.profile-section-picture`): `--profile-section-picture-aspect-ratio` (`3 / 4`), `--profile-section-picture-border-radius` (`8px`), `overflow: hidden`. Full token list: `CONSUMER-STYLING.md` in the component folder. The `NuxtImg` fills the frame with `object-fit: cover`.
-- Profile links: `align-items: end; justify-content: flex-end` — right-aligned to the bottom of the info column.
+- The root is a size container named `profile-section`. Layout follows **the component's own width**, not the viewport.
+- **Under 768px wide**: single column — picture stacked above info, `--profile-section-gap` (`2rem`).
+- **768px wide or more**: two columns — `minmax(0, var(--profile-section-picture-width))` (`38.4rem`) picture column, `minmax(0, 1fr)` info column, `--profile-section-gap-wide` (`4rem`) gap.
+- Being an inline-size container, the root can't size itself from its content: give it a width in a flex row or other shrink-to-fit context.
+- The root sets `overflow-wrap: anywhere`, so unbroken text and URLs in any slot wrap rather than widening the grid.
+- Picture frame (`.profile-section-picture`): `--profile-section-picture-aspect-ratio` (`3 / 4`), `--profile-section-picture-border-radius` (`0.8rem`), `overflow: hidden`. The `NuxtImg` fills the frame with `object-fit: cover`. Full token list: `CONSUMER-STYLING.md` in the component folder.
+- Profile links: `flex-wrap: wrap; align-items: end; justify-content: flex-end` — right-aligned to the bottom of the info column.
+- To change the picture column width, set `--profile-section-picture-width`; don't override `grid-template-columns` in a viewport `@media` query, which no longer lines up with the component's own switch.
+
+## Header in picture
+
+With `header-placement="picture-bottom"` or `"picture-top"`, the `<header>` renders inside `.profile-section-picture`, before the image in the DOM (so it is read first), and sits at the bottom or top of the frame on a scrim that fades away from that edge. It follows ServicesCard's `titles-within-image-wrapper`:
+
+- Scrim and text come from `--profile-section-picture-header-*` tokens: scrim colour (`#000`) and opacity (`75%`), a solid stop (`0%`, how far the scrim stays full strength before fading) and a target colour (`transparent`, what it fades into, set it to roughly the photo's colour where the fade ends so it blends instead of leaving a grey band), text colour (`contrast-color()` of the scrim colour where supported, else `#fff`), eyebrow colour, padding (`2.4rem`), gap (`0.4rem`). Full list in `CONSUMER-STYLING.md`.
+- The frame drops `overflow: hidden` in this mode, so its aspect ratio is a minimum: a long header grows the frame rather than being clipped. The image is absolutely positioned and still fills the frame.
+- `aria-labelledby` still points at the heading.
+- Drop spacing utilities like `mb-20` from the heading in this mode; the header's padding handles spacing.
+
+```vue
+<ProfileSection tag="section" header-placement="picture-bottom" :profile-picture="picture">
+  <template #eyebrowText>
+    <EyebrowText tag="p" font-size="medium" text-content="About Alex" />
+  </template>
+  <template #heroText="{ headingId }">
+    <HeroText :id="headingId" tag="h2" font-size="heading" :text-content="[{ text: 'Alex Morgan', styleClass: 'normal' }]" />
+  </template>
+  ...
+</ProfileSection>
+```
+
+Two stories show themes built only from tokens: `Header In Picture (Dark, Bottom)`, ServicesCard-style, and `Header In Picture (Light, Top)`. A light scrim needs a dark `--profile-section-picture-header-text-colour`; `contrast-color()` picks one where supported, but set it for older browsers. `--profile-section-info-text-colour` sets the info column's text colour for a themed background.
+
+## Content hooks
+
+A `.highlight` inside an element with class `location` gets `--profile-section-highlight-colour` (default `var(--colour-text-accent)`); inside `services` it gets `--profile-section-link-colour` / `--profile-section-link-colour-hover` (defaults `var(--colour-link-default)` / `var(--colour-link-hover)`). Both use `--profile-section-highlight-font-weight` (`600`). The `location`/`services` class can sit on the `<p>` itself or a wrapper.
 
 ## CSS notes
 
@@ -106,8 +142,6 @@ If you use a different heading component, bind `headingId` to whatever prop rend
 }
 ```
 
-- Accent-coloured text within `.location` or `.services` info blocks can use the `.highlight` class for `var(--colour-text-accent)` or `var(--colour-link-default)` colouring respectively.
-
 ## Consumer styling scaffold
 
 ```vue
@@ -121,6 +155,8 @@ If you use a different heading component, bind `headingId` to whatever prop rend
 <style>
 .profile-section {
   &.my-profile {
+    --profile-section-picture-width: 32rem;
+
     .profile-section-header {
       margin-block-end: 3.2rem;
     }
@@ -131,6 +167,8 @@ If you use a different heading component, bind `headingId` to whatever prop rend
 
 ## Notes
 
-- `NuxtImg` is used for the profile picture — provide a real `src` path. A placeholder (grey box) is shown if the image 404s.
-- The component does not expose `imgWidth` / `imgHeight` props for the picture. If IPX optimisation is critical, use a fixed-dimension image and rely on the `384px` column cap as the natural size constraint.
+- `NuxtImg` is used for the profile picture — provide a real `src` path. A broken image shows its alt text inside the 3:4 frame.
+- Pass `width`/`height` in `profilePicture` when your image isn't 3:4 at 828px wide, so IPX/Vercel request the right size.
+- The `With Social Icons` story shows a `SocialIconsList` in `#profileLinks`; size it with `--social-icons-list-icon-size` and `--social-icons-list-gap` on your own wrapper.
+- The `StressTest` story covers hostile content (broken image, unbroken text, RTL, out-of-order slots, many links) at every canvas width.
 - Component is auto-imported in Nuxt — no import needed.

package/.claude/skills/components/social-icons-list.md

@@ -57,6 +57,8 @@ import type { ISocialIcon } from "srcdev-nuxt-components";
 | YouTube | `logos:youtube-icon` | `https://www.youtube.com/@` |
 | TikTok | `logos:tiktok-icon` | `https://www.tiktok.com/@` |
 
+`logos:instagram-icon`, `logos:x` and other dark brand icons vanish on a dark background, and their colours can't be changed. On a dark background use a mono icon such as `mdi:instagram` (any set that draws in `currentColor`) and colour it with `--social-icons-list-icon-colour` (default `currentColor`). Installed mono Instagram icons: `mdi:instagram`, `bi:instagram`, `lucide:instagram`, `akar-icons:instagram-fill`, `radix-icons:instagram-logo`.
+
 ---
 
 ## Usage example

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
 
@@ -32,7 +38,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── theming-override-default.md      — replace the entire default theme with a custom palette (set --theme-hue/--theme-chroma)
 ├── theming-partial-override.md      — override a specific colour token category (palette, buttons, inputs) without a full theme replacement
 ├── theming-form-geometry-tokens.md  — non-colour form/button/input tokens (padding, border-radius, gaps): full inventory, why partial override doesn't need duplicating the source files
-├── theming-component-token-pattern.md — standard shape for overridable component colours: public token + inline fallback, no bare var()/no private-only indirection; the three tiers (theme slots / cross-component families / component-scoped); line-clamp tokens for overflowing text; rollout status
+├── theming-component-token-pattern.md — standard shape for overridable component colours: public token + inline fallback, no bare var()/no private-only indirection; the three tiers (theme slots / cross-component families / component-scoped); line-clamp tokens for overflowing text; image-overlay scrim tokens; rollout status
 ├── theming-status-tokens.md        — global --status-* colours (success/warning/danger/info/neutral: solid + surface + text), which components read them, how to override once for the whole library
 ├── theming-dark-mode.md            — add a dark scheme in a consumer app (layer is light-only): enable plumbing, full dark token set without light-dark(), light-dark() alternative, light-only pinning
 ├── colour-scheme-disable.md         — disable light/dark scheme support in a consumer app
@@ -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
@@ -108,12 +114,13 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── wipe-away-vertical.md   — WipeAwayVertical: scroll-driven vertical wipe-away effect, pure-CSS grid overlay (no JS), indexed dynamic slots, sticky-centering-via-calc gotcha, CSS tokens
     ├── marquee-scroller.md     — MarqueeScroller: infinite logo/badge scroller, per-item dynamic slots (marqueeData id), hover/focus/keyboard pause, reduced-motion, CSS tokens
     ├── rotating-carousel-image.md — RotatingCarouselImage: 3D rotating image carousel, scroll-parallax tilt, focus/keyboard/hover pause, reduced-motion, CSS tokens
-    ├── social-icons-list.md    — SocialIconsList: data-driven social icon links, ISocialIcon type, logos: icon names, CSS tokens
+    ├── social-icons-list.md    — SocialIconsList: data-driven social icon links, ISocialIcon type, logos: icon names (dark ones vanish on dark backgrounds; mono alternatives), CSS tokens incl. --social-icons-list-icon-colour
     ├── display-qr-code.md      — DisplayQrCode: QR code SVG from a string value, colour/size/variant/radius props, currentColor default
     ├── capture-qr-code.md      — CaptureQrCode: live camera scanner, error state, visibility/route/KeepAlive lifecycle, media stream cleanup
     ├── decode-qr-code.md       — DecodeQrCode: file picker + drag-and-drop image decoder, shared results list, CSS override points
     ├── auto-grid.md            — AutoGrid: auto-fit responsive grid, $slots iteration, --auto-grid-gap/min-col-size-{small,default,large} tokens, is-responsive, semantic tag + aria
-    ├── display-avatar.md       — DisplayAvatar (02.molecules): circular avatar with image/initials fallback (alt announced), size scale tokens, --display-avatar-* colours, chip badge, icon slot
+    ├── display-avatar.md       — DisplayAvatar (02.molecules): circular avatar with image/initials fallback (alt announced), broken-image fallback, data-size scale tokens, image-size, --display-avatar-* colours, chip badge, icon slot
+    ├── profile-section.md      — ProfileSection (02.molecules): picture + numbered profile-info-N slots, eyebrow/hero header (above, or over the picture top/bottom on a scrim via header-placement), profileLinks, container-query two-column layout, .location/.services highlight tokens
     ├── display-theme-switch.md — DisplayThemeSwitch: system/light/dark picker wrapping TripleToggleSwitch, wired to useSettingsStore, labels/icons props, small sizing variant
     ├── card-core.md            — CardCore: generic card container, dynamic named slots as rows, 4 variants, blurred backdrop layer, full CSS token API
     ├── action-menu.md          — ActionMenu + ActionMenuItem: ellipsis trigger + anchored popover menu, indexed item-{n} slots, link/button items, full 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)"`.

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

@@ -268,6 +268,8 @@ export const Default: Story = {
 Key points:
 
 - `computed` is **not** auto-imported in `.ts` story files — import it explicitly from `"vue"`.
+- Components aren't auto-registered in a story's `template` string either. Every component used there, including ones you put in the component's slots (`EyebrowText`, `HeroText`, `SocialIconsList`, ...), must be imported and listed in `components: {}`. Otherwise Vue renders it as an empty unknown element (`<eyebrowtext>`) with no error. ProfileSection's header and social-icons stories rendered blank this way until 2026-10-14.
+- Props in a story's `template` string aren't type-checked either. An invalid value renders silently with no warning: ProfileSection's stories passed `font-size="large"` to `HeroText`, which only has `display`/`title`/`heading`/`subheading`/`label`, so the heading fell back to unstyled text. Check every literal prop value against the component's `interface Props`.
 - Extra args must be stripped before `v-bind` — spreading unknown keys onto a component makes them unknown HTML attributes.
 - CSS custom properties set via `:style` on the component root are picked up by `var()` in the component's scoped CSS.
 
@@ -285,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
@@ -360,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