srcdev-nuxt-components 9.6.2 → 9.6.4

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/composable-cookie-consent.md

@@ -18,7 +18,7 @@
 
 ### 2. Render the banner
 
-Pair it with [[cookie-consent-banner]] (`CookieConsentBanner.vue`), registered once in the app's default layout — see that component's skill doc for placement and copy slots.
+Pair it with [[cookie-consent-banner]] (`CookieConsentBanner.vue`), registered once in the app's default layout — see that component's skill doc for placement, copy slots and label props.
 
 ## Composable reference
 

package/.claude/skills/index.md

@@ -7,10 +7,16 @@ Step-by-step guides for repeatable development tasks in this project.
 Copy skills into your project with:
 
 ```bash
-cp -r node_modules/srcdev-nuxt-components/.claude/skills .claude/skills/srcdev-nuxt-components
+rm -rf .claude/skills/srcdev-nuxt-components && mkdir -p .claude/skills/srcdev-nuxt-components && cp -r node_modules/srcdev-nuxt-components/.claude/skills/. .claude/skills/srcdev-nuxt-components
 ```
 
-Skills land in `.claude/skills/srcdev-nuxt-components/` — safe to re-run without overwriting your own skills.
+Skills land in `.claude/skills/srcdev-nuxt-components/` — safe to re-run: it replaces only that folder, so skills dropped or renamed upstream are removed and your own skills are never touched.
+
+The layer also ships a curated set of Claude Code rules in `.claude/rules/consumer/`. `npm run setup:claude` (see `setup-postinstall.md`) copies skills and rules together; to copy the rules by hand:
+
+```bash
+rm -rf .claude/rules/srcdev-nuxt-components && mkdir -p .claude/rules/srcdev-nuxt-components && cp -r node_modules/srcdev-nuxt-components/.claude/rules/consumer/. .claude/rules/srcdev-nuxt-components
+```
 
 ## Structure
 
@@ -97,10 +103,10 @@ 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
+    ├── input-copy.md           — InputCopy: readonly copy-to-clipboard input with an inline InputButton, copied state + status announcement, translatable labels/icons, container-query icon-only button, --input-copy-* tokens
     ├── banner-video.md         — BannerVideo: full-width hero video banner, depth tier system, objectFit/objectPosition, playIcon/pauseIcon/toggle-icon slot, reduced-motion fallback, CSS tokens
     ├── grid-stack.md           — GridStack: CSS Grid z-axis stacking, slot API, z-order rules, sizing, video+overlay and image+text patterns
     ├── scroll-reveal-frame.md  — ScrollRevealFrame: generic parallax clipping frame, slot API, image grid pattern, public --scroll-reveal-frame-* tokens (props only write them when passed), browser support
@@ -130,7 +136,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── site-header.md            — SiteHeader: PageRow + SkipLinks + ResponsiveHeader composition, #branding/#secondaryNavigation slots, dual styleClassPassthrough hooks
     ├── responsive-header.md      — ResponsiveHeader: overflow-collapsing adaptive nav, measurement-pipeline gotchas (unsized icons, vw font-size drift), full CSS token API
     ├── navigation-items.md       — NavigationItems: internal overflow-panel renderer for ResponsiveHeader, complement-visibility logic, not used standalone
-    ├── cookie-consent-banner.md  — CookieConsentBanner: fixed non-modal Accept/Reject banner built on AlertContent, driven by useCookieConsent; title/message/acceptLabel/rejectLabel slots, icon/showIcon/ariaLabel props, position/button tokens (panel via --alert-content-*), teleported so tokens go on html/passthrough
+    ├── cookie-consent-banner.md  — CookieConsentBanner: fixed non-modal Accept/Reject banner built on AlertContent, driven by useCookieConsent; title/message slots, acceptLabel/rejectLabel/icon/showIcon/ariaLabel props, InputButton (inline) actions, position/button tokens (panel via --alert-content-*), teleported so tokens go on html/passthrough
     ├── display-banner.md         — DisplayBanner: canvas/content stacked overlay banner, conditional slot wrappers, CSS token API
     ├── deep-expanding-menu.md         — DeepExpandingMenu: anchor-positioned popover nav panels, browser support caveat, CSS token API
     ├── deep-expanding-menu-classic.md — DeepExpandingMenuClassic: <details>-based fallback nav, click-outside close, 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

@@ -287,6 +287,37 @@ 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" } },
+  },
+  ```
+
+- A fixed or teleported overlay (banner, toast, dialog) can't be narrowed by `CanvasSwitcher`: it
+  positions against the viewport and may not even live inside the decorator. Its `StressTest`
+  (compliance checklist item 6b) renders **one** instance, switches between hostile data sets with
+  a story-only select (`stressCase`, category `"Story only"`, description starting
+  `**Story control, not a prop.**`), tells the reader to use Storybook's viewport toolbar for narrow
+  screens, and sets `docs.story: { inline: false }`. `CookieConsentBanner` and `DisplayToast`
+  follow this. A teleported component doesn't inherit a wrapper's `dir`, so wrap RTL slot copy
+  in `<span dir="rtl">`.
+- Opt a file out with `tags: ["!autodocs"]` only when it isn't a component reference (tooling, or
+  a file with its own attached `.mdx` page, like `ColourRamps.stories.ts` with `SetupGuide.mdx`).
+
 ## Link to the stories of components that use this one
 
 When the component you're working on is a building block of other components (it's rendered
@@ -362,6 +393,19 @@ story: "See the [CookieConsentBanner](?path=/story/molecules-cookieconsentbanner
   controls that make sense (hide irrelevant ones with `Story.argTypes = { x: { table: { disable: true } } }`),
   or, for a fixed showcase (comparisons, all-themes grids, composition examples), add
   `controls: { disable: true }` to that story's `parameters`.
+- **Sidebar order** comes from the `storySort` function in `.storybook/preview.ts`: top-level
+  groups in tier order, everything below them alphabetical, entries within one component in file
+  order with Docs first. Storybook doesn't run that function from the compiled file. It extracts
+  the function's source and `eval`s it as plain JavaScript, so any TypeScript inside it
+  (annotations, `as` casts) or a reference to something outside its body fails the whole preview
+  build with `SyntaxError: Unexpected token ':'` (found 2026-10-15). It stays annotation-free
+  under a `// @ts-expect-error`. Check an edit without starting Storybook:
+
+  ```bash
+  node --input-type=module -e 'import { getStorySortParameter } from "storybook/internal/csf-tools"; import fs from "node:fs"; console.log(typeof getStorySortParameter(fs.readFileSync(".storybook/preview.ts", "utf8")));'
+  ```
+
+  `function` means it parses; a syntax error is the same one Storybook would hit.
 
 ## Scroll/animation-driven effects need surrounding chrome, not just the bare component
 

package/.claude/skills/testing-add-unit-test.md

@@ -201,6 +201,25 @@ await nextTick();
 vi.runAllTimers();
 ```
 
+### Native clicks are silently dropped under frozen time
+
+Vue's event invoker ignores an event whose timestamp is at or before the moment its listener was
+attached (a guard against an event that triggered the patch also firing the new listener). With
+the clock frozen, a native `button.click()` or `dispatchEvent()` straight after mount carries the
+same timestamp, so the handler never runs and the test fails with "called 0 times". Whether it
+bites depends on render timing: `CookieConsentBanner`'s click tests passed with raw `<button>`s
+and failed once they became `InputButton`s (2026-10-15). Either use test-utils'
+`wrapper.trigger("click")` (which works, including on teleported content via `findComponent`), or
+advance the clock first:
+
+```ts
+// Vue ignores events stamped at or before its listener's attach time; fake timers freeze both.
+function click(button: HTMLElement) {
+  vi.advanceTimersByTime(1);
+  button.click();
+}
+```
+
 ## `mountSuspended` flushes component async setup — initial state may be past the first `await`
 
 `mountSuspended` calls `flushPromises()` internally, draining all pending microtasks including `await nextTick()` calls inside the component's async functions. If a component's async lifecycle starts with `await nextTick()` (e.g. to let a CSS `v-bind` update before beginning a transition), **the component will have already executed past it by the time `mountSuspended` returns**.

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]`
@@ -138,7 +184,7 @@ raw value) chains through it:
 
 ```css
 /* InputCopy's copy button defaults to InputButton's primary look */
---_button-bg: var(--input-copy-button-bg, var(--input-button-primary-surface, var(--theme-surface)));
+background-color: var(--input-copy-button-bg, var(--input-button-primary-surface, var(--theme-surface)));
 ```
 
 Three tiers deep here: instance/global override → "look like the primary button" → the theme

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-cookie-consent-banner.code-snippets

@@ -10,11 +10,13 @@
     "description": "CookieConsentBanner with translated copy and accessible name",
     "scope": "vue,html",
     "body": [
-      "<CookieConsentBanner :aria-label=\"${1:t('global.cookieConsent.ariaLabel')}\">",
-      "  <template #title>{{ ${2:t('global.cookieConsent.title')} }}</template>",
-      "  <template #message>{{ ${3:t('global.cookieConsent.message')} }}</template>",
-      "  <template #acceptLabel>{{ ${4:t('global.cookieConsent.accept')} }}</template>",
-      "  <template #rejectLabel>{{ ${5:t('global.cookieConsent.reject')} }}</template>",
+      "<CookieConsentBanner",
+      "  :aria-label=\"${1:t('global.cookieConsent.ariaLabel')}\"",
+      "  :accept-label=\"${2:t('global.cookieConsent.accept')}\"",
+      "  :reject-label=\"${3:t('global.cookieConsent.reject')}\"",
+      ">",
+      "  <template #title>{{ ${4:t('global.cookieConsent.title')} }}</template>",
+      "  <template #message>{{ ${5:t('global.cookieConsent.message')} }}</template>",
       "</CookieConsentBanner>"
     ]
   },

package/.vscode/srcdev-component-input-copy.code-snippets

@@ -1,28 +1,27 @@
 {
   "SRCDEV InputCopy Basic": {
-    "description": "Basic InputCopy component with value and label",
+    "description": "InputCopy: readonly input with a copy-to-clipboard button",
     "scope": "vue,html",
     "body": [
       "<InputCopy",
-      "  value=\"$1sk_live_abc123xyz\"",
-      "  label=\"$2API key\"",
-      "  description=\"$3Copy this key to authenticate with our API.\"",
-      "  @copy=\"$4handleCopy\"",
+      "  :value=\"${1:licenseKey}\"",
+      "  label=\"${2:License key}\"",
+      "  description=\"${3:Copy this key to activate the component in your application.}\"",
+      "  @copied=\"${4:handleCopied}\"",
       "/>"
     ]
   },
-  "SRCDEV InputCopy License Key": {
-    "description": "InputCopy for displaying a license key on success page",
+  "SRCDEV InputCopy Translated": {
+    "description": "InputCopy with translated copy and accessible names",
     "scope": "vue,html",
     "body": [
       "<InputCopy",
-      "  :value=\"licenseKey\"",
-      "  label=\"License key\"",
-      "  description=\"Your license key is ready to use. Copy it to embed in your application.\"",
-      "  buttonText=\"Copy\"",
-      "  copiedText=\"Copied to clipboard!\"",
-      "  @copy=\"$1handleCopy\"",
-      "  @copied=\"$2showCopiedFeedback\"",
+      "  :value=\"${1:value}\"",
+      "  :label=\"${2:t('account.key.label')}\"",
+      "  :description=\"${3:t('account.key.description')}\"",
+      "  :button-text=\"${4:t('common.copy')}\"",
+      "  :copied-text=\"${5:t('common.copied')}\"",
+      "  :button-aria-label=\"${6:t('account.key.copyAriaLabel')}\"",
       "/>"
     ]
   },
@@ -31,25 +30,10 @@
     "scope": "vue,html",
     "body": [
       "<InputCopy",
-      "  :value=\"$1value\"",
-      "  label=\"$2Label\"",
-      "  :is-disabled=\"true\"",
-      "  :button-text=\"$3Unavailable\"",
-      "/>"
-    ]
-  },
-  "SRCDEV InputCopy in Page": {
-    "description": "InputCopy with custom aria labels",
-    "scope": "vue,html",
-    "body": [
-      "<InputCopy",
-      "  :value=\"$1value\"",
-      "  label=\"$2License key\"",
-      "  aria-label=\"$3Your unique GuideMyHair license identifier\"",
-      "  description=\"$4Keep this key safe. You'll need it to embed the widget.\"",
-      "  button-text=\"$5Copy key\"",
-      "  copied-text=\"$6Key copied!\"",
-      "  @copy=\"$7logCopy\"",
+      "  :value=\"${1:value}\"",
+      "  label=\"${2:Label}\"",
+      "  :is-disabled=\"${3:true}\"",
+      "  button-text=\"${4:Unavailable}\"",
       "/>"
     ]
   },
@@ -57,15 +41,13 @@
     "description": "CSS override scaffold for InputCopy tokens",
     "scope": "css",
     "body": [
-      ".$1success-page {",
-      "  .input-copy {",
-      "    --input-copy-input-bg: $2;",
-      "    --input-copy-input-border: $3;",
-      "    --input-copy-input-border-radius: $4;",
-      "    --input-copy-button-bg: $5;",
-      "    --input-copy-button-bg-hover: $6;",
-      "    --input-copy-button-text-color: $7;",
-      "  }",
+      ".${1:account-page} .input-copy {",
+      "  --input-copy-input-bg: ${2:var(--theme-input-surface)};",
+      "  --input-copy-input-border: ${3:0.1rem solid var(--theme-border)};",
+      "  --input-copy-button-bg: ${4:var(--theme-surface)};",
+      "  --input-copy-button-bg-hover: ${5:var(--theme-surface-hover)};",
+      "  --input-copy-button-text-color: ${6:var(--theme-on-surface)};",
+      "  --input-copy-description-line-clamp: ${7:none};",
       "}"
     ]
   }