srcdev-nuxt-components 9.6.1 → 9.6.3

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]`
@@ -83,6 +129,54 @@ Prefer this over a prop: line count is presentation, and CSS handles it without
   layout around it.
 - Document it in `CONSUMER-STYLING.md` with its default and the `1`/`none` options.
 
+## Text over an image: scrim tokens
+
+Any component that puts text over a photo (a header in a picture, a card title on its image) gets
+the same scrim token set, so a consumer can match the scrim to their photos. `ProfileSection`'s
+`header-placement="picture-top|picture-bottom"` is the reference; `ServicesCard`'s
+`titles-within-image-wrapper` has the older subset (colour and whole-background override only) and
+should gain the rest when it's next touched.
+
+| Token | Default | Purpose |
+|---|---|---|
+| `--{c}-scrim-colour` | `#000` | Colour the scrim starts from at the image's edge |
+| `--{c}-scrim-opacity` | `75%` | Its opacity at the start |
+| `--{c}-scrim-solid-stop` | `0%` | How far it stays full strength before fading, so the text sits on a clean background |
+| `--{c}-scrim-target-colour` | `transparent` | What it fades into: set to roughly the photo's colour where the fade ends, so there's no grey band |
+| `--{c}-scrim` | the gradient | Whole `background` override; `none` removes it |
+| `--{c}-text-colour` | `contrast-color(<scrim colour>)`, `#fff` without support | Text on the scrim |
+
+```css
+.component-header {
+  --_scrim-colour: var(--component-scrim-colour, #000);
+  --_scrim-start-colour: color-mix(in oklab, var(--_scrim-colour) var(--component-scrim-opacity, 75%), transparent);
+  --_scrim-solid-stop: var(--component-scrim-solid-stop, 0%);
+  --_scrim-target-colour: var(--component-scrim-target-colour, transparent);
+
+  color: var(--component-text-colour, #fff);
+  background: var(--component-scrim, linear-gradient(to top, rgb(0 0 0 / 0.75), rgb(0 0 0 / 0.75) var(--_scrim-solid-stop), var(--_scrim-target-colour)));
+
+  @supports (color: color-mix(in oklab, red, transparent)) {
+    background: var(--component-scrim, linear-gradient(to top, var(--_scrim-start-colour), var(--_scrim-start-colour) var(--_scrim-solid-stop), var(--_scrim-target-colour)));
+  }
+
+  @supports (color: contrast-color(red)) {
+    color: var(--component-text-colour, contrast-color(var(--_scrim-colour)));
+  }
+}
+```
+
+- The `@supports` fallback is for Safari before 16.2 (no `color-mix()`): it starts from 75% black
+  whatever the scrim colour, but keeps the solid stop and target colour.
+- `contrast-color()` reads the scrim colour, not the photo. Document that a consumer who removes the
+  scrim must set the text colour.
+- Round only the corners on the image's edge (`border-end-*-radius: inherit` for a bottom scrim),
+  or an opaque target colour shows rounded inner corners.
+- If the text can be long, don't clip it: let the frame grow (absolutely position the image and
+  keep `overflow` visible so `aspect-ratio` acts as a minimum).
+- Give the story a light and a dark theme built only from these tokens, each with a photo whose
+  edge suits the scrim.
+
 ## Multi-level fallback chains are fine
 
 A component that wants to *look like* another component's default (rather than duplicating a

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-display-avatar.code-snippets

@@ -6,6 +6,13 @@
       "<DisplayAvatar src=\"${1:/images/profile.jpg}\" alt=\"${2:Jane Smith}\" size=\"${3|md,xs,s,lg,xl|}\" />"
     ]
   },
+  "SRCDEV DisplayAvatar Large Image": {
+    "description": "DisplayAvatar: image avatar resized beyond the scale, with a matching image-size so it stays sharp",
+    "scope": "vue,html",
+    "body": [
+      "<DisplayAvatar src=\"${1:/images/profile.jpg}\" alt=\"${2:Jane Smith}\" :image-size=\"${3:240}\" style=\"--display-avatar-size: ${4:12rem}\" />"
+    ]
+  },
   "SRCDEV DisplayAvatar Initials": {
     "description": "DisplayAvatar: initials derived from alt (alt is announced, initials hidden from screen readers)",
     "scope": "vue,html",

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/.vscode/srcdev-component-profile-section.code-snippets

@@ -5,16 +5,16 @@
     "body": [
       "<ProfileSection",
       "  tag=\"section\"",
-      "  :profile-picture=\"{ src: '$1', alt: '$2' }\"",
+      "  :profile-picture=\"{ src: '$2', alt: '$3' }\"",
       ">",
       "  <template #eyebrowText>",
-      "    <EyebrowText text-content=\"$3\" />",
+      "    <EyebrowText text-content=\"$4\" />",
       "  </template>",
       "  <template #heroText=\"{ headingId }\">",
-      "    <HeroText :id=\"headingId\" tag=\"h2\" :text-content=\"[{ text: '$4' }]\" />",
+      "    <HeroText :id=\"headingId\" tag=\"h2\" :text-content=\"[{ text: '$5' }]\" />",
       "  </template>",
       "  <template #profile-info-1>",
-      "    <p>$5</p>",
+      "    <p>$6</p>",
       "  </template>",
       "  <template #profile-info-2>",
       "    <p>$6</p>",
@@ -22,6 +22,27 @@
       "</ProfileSection>"
     ]
   },
+  "SRCDEV ProfileSection Header In Picture": {
+    "description": "ProfileSection with the eyebrow and heading over the bottom or top of the picture, on a scrim",
+    "scope": "vue,html",
+    "body": [
+      "<ProfileSection",
+      "  tag=\"section\"",
+      "  header-placement=\"${1|picture-bottom,picture-top|}\"",
+      "  :profile-picture=\"{ src: '$2', alt: '$3' }\"",
+      ">",
+      "  <template #eyebrowText>",
+      "    <EyebrowText text-content=\"$4\" />",
+      "  </template>",
+      "  <template #heroText=\"{ headingId }\">",
+      "    <HeroText :id=\"headingId\" tag=\"h2\" :text-content=\"[{ text: '$5' }]\" />",
+      "  </template>",
+      "  <template #profile-info-1>",
+      "    <p>$6</p>",
+      "  </template>",
+      "</ProfileSection>"
+    ]
+  },
   "SRCDEV ProfileSection CSS Override": {
     "description": "CSS override scaffold for ProfileSection tokens",
     "scope": "css",
@@ -30,6 +51,8 @@
       "  --profile-section-picture-width: $2;",
       "  --profile-section-gap-wide: $3;",
       "  --profile-section-picture-border-radius: $4;",
+      "  --profile-section-highlight-colour: $5;",
+      "  --profile-section-link-colour: $6;",
       "}"
     ]
   }

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/display-avatar/CONSUMER-STYLING.md

@@ -6,13 +6,17 @@
 
 | Token | Default | Controls |
 |---|---|---|
-| `--display-avatar-size` | the size class's value | Diameter, overriding the `size` prop's scale (one instance or a whole area) |
-| `--display-avatar-font-size` | the size class's value | Initials/text size, overriding the scale |
+| `--display-avatar-size` | the `size` step's value | Diameter, overriding the `size` prop's scale (one instance or a whole area) |
+| `--display-avatar-font-size` | the `size` step's value | Initials/text size, overriding the scale |
 | `--display-avatar-size-xs` / `-s` / `-md` / `-lg` / `-xl` | `2.4rem` / `3.2rem` / `4rem` / `4.8rem` / `5.6rem` | The diameter each `size` value maps to |
 | `--display-avatar-font-size-xs` / `-s` / `-md` / `-lg` / `-xl` | `1.2rem` / `1.4rem` / `1.6rem` / `1.8rem` / `2rem` | The text size each `size` value maps to |
 
-A custom `size` string (anything other than `xs`–`xl`) is added as a class but maps to no scale
-step, so it renders at `md` unless you set `--display-avatar-size` for it.
+A custom `size` string (anything other than `xs`–`xl`) is set as `data-size` but maps to no
+scale step, so it renders at `md` unless you set `--display-avatar-size` for it (target it with
+`.display-avatar[data-size="<your-size>"]`).
+
+If you size an image avatar beyond the scale, raise the `image-size` prop (default `112`, the
+pixel width and height requested from `@nuxt/image`) to match, or the image is upscaled and blurry.
 
 ### Appearance
 
@@ -30,21 +34,33 @@ step, so it renders at `md` unless you set `--display-avatar-size` for it.
 > faint in light mode; it now uses the `--theme-*` surface and text tokens, so it follows light
 > and dark mode.
 
-Private tokens (not public API): `--_size` and `--_font-size`, which each size class sets from its
+Private tokens (not public API): `--_avatar-size` and `--_avatar-font-size`, which each size step sets from its
 scale token.
 
 ## State hooks
 
-- Size class on the root: `.xs`, `.s`, `.md`, `.lg`, `.xl` (or your custom `size` string).
-- Classes: `.display-avatar` (root), `.display-avatar-image` (the image), `.display-avatar-icon`
-  (opt-in, for your `#icon` slot content).
+- `data-size` on the root: `xs`, `s`, `md`, `lg`, `xl` (or your custom `size` string).
+- Classes: `.display-avatar` (root: size, font size, radius), `.display-avatar-surface` (fills the root,
+  carries the background and text colour, and holds all content), `.display-avatar-image` (the image), `.display-avatar-fallback`
+  (the initials or `text`; one line, clipped to the circle), `.display-avatar-icon` (opt-in, for
+  your `#icon` slot content).
 - With `chip`, the root is `DisplayChip`, so it also carries `.display-chip` and its
   `data-shape`/`data-status` attributes (status comes from the `status` prop). See `display-chip`
   for its tokens.
 
+> **Changed 2026-10-14**: the size was a bare class on the root (`.display-avatar.lg`), which a
+> consumer's own `.lg`/`.xl` utility classes could match. Replace `.display-avatar.<size>` with
+> `.display-avatar[data-size="<size>"]`. Overlong fallback text is now clipped inside the circle, the
+> avatar no longer shrinks in a flex row, and a broken image falls back to the initials.
+> With `chip`, the status dot is its configured size again (it had picked up the avatar's diameter
+> through a shared private `--_size` name). Content now sits in a full-size
+> `.display-avatar-surface`, which carries the background: the chip's cutout used to land on the
+> small initials span (cutting into the letters) and never reached the background. If you set
+> `background` directly on `.display-avatar`, use `--display-avatar-background` instead.
+>
 > **Changed 2026-10-08**: chip status is the `status` prop (forwarded to `DisplayChip` as
 > `data-status`), not an `online`/`idle`/`dnd` class through `style-class-passthrough`.
-
+>
 > **Changed 2026-09-27**: `.avatar-image` → `.display-avatar-image` and `.avatar-icon` →
 > `.display-avatar-icon`.
 
@@ -56,7 +72,7 @@ Set the tokens above on an element you own (a page or section class, or a class
 `<style scoped>`, tokens set on your element still work, but selectors that reach inside the
 component need `:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
 
-**Caveat:** the size classes set `--_size`/`--_font-size` on the avatar itself, so changing the
+**Caveat:** the size steps set `--_avatar-size`/`--_avatar-font-size` on the avatar itself, so changing the
 scale (`--display-avatar-size-md` etc.) from an ancestor works, but a one-off diameter should use
 `--display-avatar-size`, which beats the scale wherever it's set.