srcdev-nuxt-components 9.6.1 → 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
 
@@ -101,6 +101,10 @@ The ledger can't see items 9, 10, 11 and 14, so check those by hand.
    If other components render this one inside them (it's a child or building block of theirs),
    each story gets a short note that explains the relationship and links to the parent's story
    (`storybook-add-story.md`, "Link to the stories of components that use this one").
+   Sample copy in stories, and examples in the skill doc, use placeholders (a name like "Alex
+   Morgan", a town like "Northtown"), never a real client's name, town, business or site: the
+   stories and docs ship in the public package. **Existing component:** check for, and replace, any
+   copy lifted from a consumer app (`ProfileSection` had both).
 6a. **Storybook Controls-panel reactivity** — check every story `Template`/`render` function in
     the component's `stories/*.stories.ts` files for this bug: `@storybook/vue3` mounts the story
     component **once** and, on every Controls-panel change, mutates the same reactive `args`
@@ -134,7 +138,9 @@ The ledger can't see items 9, 10, 11 and 14, so check those by hand.
     descriptions, body text) a line-clamp token, `--<component>-<element>-line-clamp`, which
     covers ellipsis too (`1` is single-line ellipsis). Default it to `none` unless the layout
     clearly needs a cap, and never clamp text that must stay readable (legal or attribution text,
-    link text that names its destination). Shape and rules: `theming-component-token-pattern.md`,
+    link text that names its destination). Only text the component renders itself (props and data) needs a token: text that arrives
+    through a slot is the consumer's own markup, so they clamp it directly and the component adds
+    no token for it (`ProfileSection` is all slots and has none). Shape and rules: `theming-component-token-pattern.md`,
     "Line-clamp tokens". Give each line-clamp token a Controls-panel select in the stories (set on
     a wrapper `:style`, stripped from the component's args), labelled as a story-only CSS token so
     nobody mistakes it for a prop: `storybook-add-story.md`, "Label token controls as story-only".
@@ -143,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
@@ -222,3 +243,17 @@ The ledger can't see items 9, 10, 11 and 14, so check those by hand.
     - `NuxtImg` gets explicit `width` and `height`; a `<video>` uses a `<source :src>` child with
       `:key` and `.load()` (pitfall #12).
     - No `#components` import (breaks Storybook); use `resolveComponent()`.
+    - Layout breakpoints respond to the component's own width (`container: <name> / inline-size` on the
+      root, `@container <name> (min-width: …)`), not the viewport, so it still works in a narrow
+      column. **Existing component:** when converting a viewport `@media` breakpoint, grep consumer
+      repos for `@media` overrides of the same element (they now switch at a different point) and list
+      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/display-avatar.md

@@ -1,5 +1,7 @@
 # DisplayAvatar Component
 
+> **Changed 2026-10-14:** size is a `data-size` attribute, not a bare class (`.display-avatar.lg` → `.display-avatar[data-size="lg"]`). New `image-size` prop (default `112`): `NuxtImg` used to get `width="100%"`, which @nuxt/image ignores, so the Vercel provider requested its largest screen width for every avatar. A broken image now falls back to the initials, initials are emoji-safe, and long fallback text is clipped inside the circle. With `chip`, the status dot was drawn at the avatar's diameter instead of its configured size: avatar and chip both declared a private `--_size` on the same root element and the avatar's size rules won. The avatar's private tokens are now `--_avatar-size`/`--_avatar-font-size`. Content (both slots too) now sits in a full-size `.display-avatar-surface` that carries the background, so the chip's cutout covers the whole avatar instead of landing on the initials span and cutting into the letters.
+
 > **Changed 2026-10-08:** new `status`/`status-label` props, forwarded to the chip. Chip status used to be an `online`/`idle`/`dnd` class through `style-class-passthrough`, which no longer colours the dot.
 
 ## Overview
@@ -18,10 +20,11 @@
 | `src`                       | `string`                                  | —        | Image URL. Renders `NuxtImg` when set; fallback text otherwise.   |
 | `alt`                       | `string`                                  | —        | Alt text for the image; also used to derive initials.             |
 | `text`                      | `string`                                  | —        | Override the auto-derived initials with an explicit string.       |
-| `size`                      | `"xs" \| "s" \| "md" \| "lg" \| "xl"`   | `"md"`   | Controls width, height, and font-size.                            |
+| `size`                      | `"xs" \| "s" \| "md" \| "lg" \| "xl"`   | `"md"`   | Sets `data-size`, which picks width, height and font-size.        |
 | `chip`                      | `boolean \| DisplayChipConfig`           | —        | Add a status chip. `true` uses defaults; pass a config object to customise. |
 | `status`                    | `DisplayChipStatus`                       | —        | Chip status colour (`offline`/`online`/`idle`/`dnd`), forwarded to `DisplayChip`. Ignored without `chip`; the chip defaults to `offline`. |
 | `status-label`              | `string`                                  | —        | Screen-reader text for the chip status (e.g. "Online"), forwarded to `DisplayChip`. Ignored without `chip`. |
+| `:image-size`              | `number`                                  | `112`    | Pixel width and height requested from `@nuxt/image` (1x; 2x is double). Raise it if you resize the avatar past `xl` with `--display-avatar-size`. |
 | `:style-class-passthrough`  | `string \| string[]`                      | `[]`     | Extra CSS classes on the root element.                            |
 
 ### Size dimensions
@@ -45,24 +48,32 @@ Each step is a token (`--display-avatar-size-md`, `--display-avatar-font-size-md
 | `default` | Replaces the auto image/fallback content entirely.                  |
 | `icon`    | Appended inside the avatar (e.g. an icon overlay over the image). |
 
+Both slots render inside `.display-avatar-surface`, a full-size element that carries the background. With `chip`, that surface is what gets the cutout mask.
+
 ---
 
 ## Fallback text logic
 
 When `src` is not set, a `<span>` renders the fallback value:
 
-1. `text` prop — used as-is if provided.
-2. `alt` initials — first character of each word, capped at two characters.
+1. `text` prop — used as-is if it has any non-whitespace content.
+2. `alt` initials — the first character (a whole grapheme, so emoji and flags stay intact) of the first two words. Extra whitespace is ignored.
 3. Empty string — if neither is set.
 
 When `alt` is set, the initials are `aria-hidden` and the full `alt` is rendered as `sr-only` text, so a screen reader announces "Jane Smith" rather than "J S". With only `text`, the text is read as-is.
 
+If the image fails to load, the initials fallback shows instead (an empty circle when there is no `alt`). A new `src` tries the image again.
+
+The fallback is one line, clipped to the circle: keep `text` short (1–3 characters).
+
 With `src`, the image uses `alt`, or an empty (decorative) `alt` when none is given. Pass `alt` unless the name is already visible next to the avatar.
 
 ```
 alt="John Doe"     → "JD"
 alt="Alice"        → "A"
 alt="Alice Bob C"  → "AB"
+alt="🦄 Unicorn"    → "🦄U"
+alt="  Jane  Smith " → "JS"
 text="?"           → "?"
 ```
 

package/.claude/skills/components/display-chip.md

@@ -226,6 +226,7 @@ See [display-avatar.md](./display-avatar.md) for the full API.
 - `shape` must match the actual shape of the slot content — the position maths differs between `circle` (radius-based) and `square` (clamped corner-aware).
 - `config` values are geometric inputs to CSS `calc(cos())` / `calc(sin())` expressions. Pass them as strings with units (`"12px"`, `"45deg"`), not plain numbers.
 - The chip dot is rendered via `::after` pseudo-element; icon and label sit above it at `z-index: 2`.
-- The mask cutout is applied to all direct children of `.display-chip` except `.display-chip-icon`, `.display-chip-label` and the `.sr-only` status text — ensure the host element is a direct child.
+- The mask cutout is applied to all direct children of `.display-chip` except `.display-chip-icon`, `.display-chip-label` and the `.sr-only` status text. The mask is positioned in percentages of each child's own box, so slot exactly one host element that fills the chip and carries its own background (an `<img>`, or a full-size wrapper around text). A small text span as a direct child gets the notch cut into its letters, and a background set on `.display-chip` itself is never cut. `DisplayAvatar` wraps its content in a full-size `.display-avatar-surface` for this reason.
+- A component that renders `DisplayChip` as its own root (as `DisplayAvatar` does) shares that element, so it must not declare the chip's private tokens (`--_size`, `--_offset`, ...) for its own values: they collide on the same element. `DisplayAvatar` uses `--_avatar-size`.
 - The `StressTest` story shows the worst-case labels and config values.
 - `DisplayChipConfig` and `DisplayChipProps` are both exported from the layer types. Use `DisplayChipConfig` when passing geometry values (the `config` prop). Use `DisplayChipProps` only if you need to pass the full component prop set (e.g. when building a wrapper component).

package/.claude/skills/components/google-reviews.md

@@ -132,8 +132,8 @@ replaced.
 - Survives hostile data (see the `StressTest` story): long and unbroken text wraps inside its card,
   reviewer names are cut to 2 lines (`--google-reviews-author-line-clamp`),
   initials take whole characters (emoji-safe), star fill is clamped to 0–5, review text renders as
-  plain text. A broken photo URL still shows the browser's broken-image icon, since
-  `DisplayAvatar` has no image-error fallback.
+  plain text. A broken photo URL falls back to the reviewer's initials (`DisplayAvatar`'s image-error
+  fallback).
 
 ## Variants