srcdev-nuxt-components 9.6.13 → 9.6.14

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

@@ -6,7 +6,7 @@ paths:
 # 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: {}`.
+be listed in that story's `components: {}`. Globally registered ones (`Icon`, `NuxtLink`) are the exception.
 
 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/skills/component-compliance-checklist.md

@@ -138,6 +138,11 @@ The ledger can't see items 6c, 9, 10, 11 and 14, so check those by hand.
       `computed()`: Vue renders nothing for a fractional or negative range and only warns in dev
       (`StepperList`, 2026-10-15)
     - broken image or link URLs
+    - data a third-party child can't handle: a library that throws while rendering (an encoder, a
+      parser) breaks the whole page render. Catch it with `onErrorCaptured` and render a fallback
+      (`DisplayQrCode` threw "Data too long" on an over-capacity value until 2026-10-19). Check story
+      control ranges against the library's real range too: its `radius` control ran to 20 while the
+      library clamps to 0-1
     Describe what to check in the story's docs description, and look at it at every
     `CanvasSwitcher` width. Fixes usually mean `overflow-wrap: anywhere`, `min-inline-size: 0` on
     flex/grid children, `Array.from(str)` instead of `str[0]`, and `clamp()` on values

package/.claude/skills/components/display-qr-code.md

@@ -10,10 +10,10 @@ Renders a styled QR code SVG from a string value. Supports colour, size, corner
 |------|------|---------|-------------|
 | `qr-value` | `string` | required | The string to encode into the QR code |
 | `variant` | `QrCodeVariant` | `{ inner: "default", marker: "default", pixel: "default" }` | Shape variants for inner markers, outer markers, and pixels |
-| `radius` | `number` | `0` | Corner rounding applied to pixels/markers (0–1 scale) |
+| `radius` | `number` | `0` | Corner rounding for the rounded, circle and dots shapes, 0 to 1 (the library clamps values outside) |
 | `black-color` | `string` | `"currentColor"` | Colour for the dark modules |
 | `white-color` | `string` | `"transparent"` | Colour for the light modules |
-| `size` | `string` | `"256px"` | Width of the QR code (height matches via `aspect-ratio: 1 / 1`) |
+| `size` | `string` | `"256px"` | Width of the QR code (height matches via `aspect-ratio: 1 / 1`), never wider than its container |
 | `aria-label` | `string` | `"QR code"` | Accessible name for the QR image (root has `role="img"`). Pass something specific and translated, e.g. "Scan to book an appointment". |
 | `style-class-passthrough` | `string \| string[]` | `[]` | Extra classes on the root element |
 
@@ -22,7 +22,7 @@ Renders a styled QR code SVG from a string value. Supports colour, size, corner
 ```typescript
 import type { QrCodeVariant } from "srcdev-nuxt-components/types/components";
 
-// Each field accepts: "default" | "circle" | "rounded" | "dots" | "classy" | "classy-rounded"
+// Each field accepts: "default" | "circle" | "rounded" | "dots" | "pixelated"
 const variant: QrCodeVariant = {
   inner: "circle",
   marker: "rounded",
@@ -30,6 +30,21 @@ const variant: QrCodeVariant = {
 };
 ```
 
+## Slots and events
+
+| Name | Kind | Description |
+|------|------|-------------|
+| `fallback` | slot | Rendered in place of the code when `qr-value` is too long to encode (about 2.9KB at the lowest error correction, less at higher). Empty by default, leaving a blank box of the same size. |
+| `error` | event | `(error: Error)`, emitted once when encoding fails. Resets when `qr-value` changes. |
+
+```vue
+<DisplayQrCode :qr-value="bookingUrl" @error="reportQrError">
+  <template #fallback>
+    <a :href="bookingUrl">Open the booking page</a>
+  </template>
+</DisplayQrCode>
+```
+
 ## CSS token
 
 `--display-qr-code-size` overrides the `size` prop when set (e.g. on a page wrapper). Full reference: `app/components/01.atoms/qr-code/CONSUMER-STYLING.md`.
@@ -39,6 +54,7 @@ const variant: QrCodeVariant = {
 | Class | Where | Description |
 |-------|-------|-------------|
 | `.display-qr-code` | root | always present |
+| `.display-qr-code-fallback` | root | only when the value can't be encoded (with `data-error`) |
 
 ## Usage
 
@@ -63,7 +79,9 @@ Custom size, colour, and rounded pixels:
 
 ## Notes
 
-- The component renders directly as the `Qrcode` element from `nuxt-qrcode` — there is no wrapper `<div>`. The `.display-qr-code` class is applied to the `Qrcode` root, which renders as an `<svg>`.
+- The component renders directly as the `Qrcode` element from `nuxt-qrcode` — there is no wrapper `<div>`. The `.display-qr-code` class is applied to the `Qrcode` root, which renders as an `<svg>`. When encoding fails it renders a `<span class="display-qr-code display-qr-code-fallback">` instead.
+- Encoding errors are caught with `onErrorCaptured`, so an over-capacity value from a CMS can't break the page render. `nuxt-qrcode` must be installed in the consuming app.
 - `size` is applied via CSS `v-bind()` — pass any valid CSS length value (`px`, `rem`, `%`, etc.).
 - `black-color` defaults to `currentColor`, so the QR code inherits the surrounding text colour automatically unless overridden.
 - `white-color` defaults to `transparent`, making the background of the QR code see-through by default.
+- 2026-10-19 migration: added the `fallback` slot and `error` event, capped the width at the container, corrected the variant list (`pixelated`, no `classy`) and added a `StressTest` story; the story's radius control now uses the real 0 to 1 range.

package/.claude/skills/components/eyebrow-text.md

@@ -27,7 +27,7 @@ Do not assume placeholder text or default content.
 ## Basic Usage
 
 ```vue
-<EyebrowText textContent="Interior Design" />
+<EyebrowText text-content="Interior Design" />
 ```
 
 ## With Tag and Size
@@ -37,8 +37,8 @@ Use `tag="p"` for semantic paragraph context, or `tag="span"` when inline. Choos
 ```vue
 <EyebrowText
   tag="p"
-  fontSize="small"
-  textContent="Featured Collection"
+  font-size="small"
+  text-content="Featured Collection"
 />
 ```
 
@@ -47,10 +47,10 @@ Use `tag="p"` for semantic paragraph context, or `tag="span"` when inline. Choos
 EyebrowText is commonly placed directly above a `HeroText` heading:
 
 ```vue
-<EyebrowText tag="p" textContent="Our Services" />
+<EyebrowText tag="p" text-content="Our Services" />
 <HeroText
   tag="h2"
-  :textContent="[
+  :text-content="[
     { text: 'Crafted with', styleClass: 'normal' },
     { text: 'Care', styleClass: 'accent' },
   ]"
@@ -59,6 +59,8 @@ EyebrowText is commonly placed directly above a `HeroText` heading:
 
 ## Font Size Scale
 
+The prop is rendered as `data-font-size` on the root (not a class).
+
 | Value | CSS variable |
 |-------|-------------|
 | `large` | `--eyebrow-text-large` (default `1.4rem`) |
@@ -110,3 +112,5 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
 
 - Component is auto-imported in Nuxt — no import needed.
 - `tag` defaults to `"div"` which is block-level. Use `"span"` when the eyebrow must be inline within a flow of text.
+- Long text and unbroken strings wrap (`overflow-wrap: anywhere`). There is no line-clamp token: clamping needs `overflow: hidden`, which clips the italic overhang; `ServiceDetail` clamps its eyebrow itself with an allowance.
+- 2026-10-19 migration: the size moved from a bare `large`/`medium`/`small` class to `data-font-size`; added wrapping, a `StressTest` story and parent-story links.

package/.claude/skills/components/header-block.md

@@ -58,10 +58,11 @@ heading to have an accessible name. Bind the same id to both:
 </section>
 ```
 
-Several components in this library (`PageRow`, `LayoutGridByCols`,
-`ProfileSection`, `ServiceSummary`, `ServiceDetail`, `PageHeroHighlights`) already generate this id
-automatically via the `useAriaLabelledById` composable and expose it as a `heading-id` slot prop —
-when composing inside one of those, bind `HeaderBlock`'s `id` to that slot prop instead of writing
+Three components in this library generate this id with the `useAriaLabelledById` composable and
+expose it as a `heading-id` slot prop: `PageRow` (default slot), `ProfileSection` (`heroText` slot)
+and `PageHeroHighlights` (`header` slot). (`LayoutGridByCols`, `ServiceSummary` and `ServiceDetail`
+use the composable too, but label their own heading or an `sr-only` label, with no slot prop.) When
+composing inside one of the three, bind `HeaderBlock`'s `id` to that slot prop instead of writing
 your own id:
 
 ```vue
@@ -72,7 +73,8 @@ your own id:
 
 ## Styling
 
-`HeaderBlock` has no CSS of its own — `classLevel` applies one of the global
+The root always has the `.header-block` class, whose only style is `overflow-wrap: anywhere` (so
+an unbroken word wraps instead of overflowing). `classLevel` applies one of the global
 `.page-heading-1`–`.page-heading-6` utility classes defined in
 `app/assets/styles/setup/05.typography/02.utility-classes/_font-classes-page-heading.css`, each
 setting `font-size` from a shared fluid type-scale token (`--step-3` through `--step-8`). All six
@@ -90,3 +92,9 @@ Moved to `01.atoms/text-blocks/header-block/`, alongside `EyebrowText`/`HeroText
 added the `id` prop in the same pass — several sections need their heading to carry a specific id
 for `aria-labelledby`, and `HeaderBlock` had no explicit way to receive one (matching `PageRow`'s
 existing `id?: string | null` + `:id` convention).
+
+## Migration note (2026-10-19)
+
+Added the `.header-block` root class and `overflow-wrap: anywhere`, a `StressTest` story, a
+story-only slot-text control and docs text. The spec now unmounts every wrapper. Corrected the list
+of components that expose a `heading-id` slot prop.

package/.claude/skills/components/hero-text.md

@@ -45,7 +45,7 @@ interface TextConfig {
 ```vue
 <HeroText
   tag="h1"
-  :textContent="[
+  :text-content="[
     { text: 'Designing', styleClass: 'normal' },
     { text: 'Artistry', styleClass: 'accent' },
     { text: 'at Home', styleClass: 'normal' },
@@ -61,8 +61,8 @@ interface TextConfig {
 <HeroText
   tag="h2"
   icon="lucide:sparkles"
-  fontSize="heading"
-  :textContent="[{ text: 'Featured', styleClass: 'accent' }]"
+  font-size="heading"
+  :text-content="[{ text: 'Featured', styleClass: 'accent' }]"
 />
 ```
 
@@ -74,8 +74,8 @@ Use `axis="vertical"` to stack text segments in a column instead of a row.
 <HeroText
   tag="h1"
   axis="vertical"
-  fontSize="display"
-  :textContent="[
+  font-size="display"
+  :text-content="[
     { text: 'Modern', styleClass: 'normal' },
     { text: 'Living', styleClass: 'accent' },
   ]"
@@ -96,7 +96,9 @@ Define these CSS custom properties in your consuming app to control sizes.
 
 ## Styling
 
-Override via `styleClassPassthrough` or a parent HOC `<style>` block targeting `.hero-text`.
+Override via `styleClassPassthrough` or a parent HOC `<style>` block targeting `.hero-text`. Size
+and axis are `data-font-size` and `data-axis` attributes on the root (not classes); each segment is a
+`<span class="hero-text-segment">` plus its `styleClass`.
 
 Key CSS custom properties:
 
@@ -107,7 +109,6 @@ Key CSS custom properties:
 | `--hero-text-{scale}` | see CONSUMER-STYLING.md | Font size per `fontSize` prop value (the library theme sets them on `:root`; the component has matching fallbacks) |
 | `--hero-text-font-family` | `"Playfair Display"` | Font family of the whole component |
 | `--hero-text-margin` | `0` | Margin on the root element |
-| `--hero-text-horizontal-gap` | `0.5ch` | Gap between segments in `axis="horizontal"` mode |
 | `--hero-text-vertical-gap` | `0.4em` | Gap between segments in `axis="vertical"` mode |
 | `--hero-text-accent-offset` | `0.2em` | Underline-clearance offset on `.accent` spans (`padding-bottom` and the matching negative `margin-bottom`) |
 
@@ -115,7 +116,7 @@ Key CSS custom properties:
 
 ```css
 .my-page {
-  .hero-text.axis-vertical {
+  .hero-text[data-axis="vertical"] {
     --hero-text-vertical-gap: 0.6em;
   }
 }
@@ -149,6 +150,9 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
 
 ## Notes
 
-- Text segments are trimmed and a trailing space is automatically appended between segments in horizontal axis — do not manually pad `text` values.
+- Text segments are trimmed and a trailing space is automatically appended between segments — do not manually pad `text` values. Segments with blank or missing `text` (common in CMS data) are dropped.
+- The icon is decorative (`aria-hidden`).
+- Long text and unbroken strings wrap. No line-clamp token: clamping needs `overflow: hidden`, which clips the accent descender offset; `ServiceDetail` clamps its title itself.
+- 2026-10-19 migration: size and axis moved from bare root classes to `data-font-size`/`data-axis`, segments from `.text-block-{n}` to `.hero-text-segment`; dropped the dead `--hero-text-horizontal-gap`; added a `StressTest` story.
 - The icon is sized to match the font size. At `subheading` scale it is `0.75em` (applied as `font-size`, since `width`/`height` on an `<Icon>` are overridden by `@nuxt/icon`).
 - Component is auto-imported in Nuxt — no import needed.

package/.claude/skills/components/link-text.md

@@ -26,13 +26,13 @@ Both slots are optional. If neither is provided, no icon wrapper elements are re
 ## Basic Usage
 
 ```vue
-<LinkText to="/about" linkText="About Us" />
+<LinkText to="/about" link-text="About Us" />
 ```
 
 ## With Left Icon (back/previous pattern)
 
 ```vue
-<LinkText to="/blog" linkText="Back to Blog">
+<LinkText to="/blog" link-text="Back to Blog">
   <template #left>
     <Icon name="lucide:arrow-left" />
   </template>
@@ -42,7 +42,7 @@ Both slots are optional. If neither is provided, no icon wrapper elements are re
 ## With Right Icon (forward/more pattern)
 
 ```vue
-<LinkText to="/services" linkText="Learn More">
+<LinkText to="/services" link-text="Learn More">
   <template #right>
     <Icon name="lucide:arrow-right" />
   </template>
@@ -52,7 +52,7 @@ Both slots are optional. If neither is provided, no icon wrapper elements are re
 ## Both Icons
 
 ```vue
-<LinkText to="/collection" linkText="Explore">
+<LinkText to="/collection" link-text="Explore">
   <template #left>
     <Icon name="lucide:sparkles" />
   </template>
@@ -67,7 +67,7 @@ Both slots are optional. If neither is provided, no icon wrapper elements are re
 ```vue
 <LinkText
   to="https://example.com"
-  linkText="Visit Site"
+  link-text="Visit Site"
   :external="true"
   target="_blank"
 >
@@ -132,3 +132,6 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
 - NuxtLink handles both internal (`/path`) and external (`https://...`) URLs automatically. Only set `external: true` if you need to force external handling on an internal-looking path.
 - The label is always rendered inside `.link-text__label` — target this class if you need to style the text independently of the icons.
 - DOM order is always: left icon → label → right icon.
+- Long and unbroken labels wrap inside the column (the root is capped at `max-inline-size: 100%`). There is no line-clamp token: link text names its destination.
+- For an icon-only link, pass an empty `link-text` and an `aria-label`; it falls through to the `<a>`.
+- 2026-10-19 migration: label wrapping, rem focus ring, `StressTest` story, docs text; the spec now unmounts every wrapper.

package/.claude/skills/components/pop-over.md

@@ -28,8 +28,9 @@ and Escape dismissal.
 |------|------|---------|-------------|
 | `placement` | `"top" \| "right" \| "bottom" \| "left"` | `"right"` | Which side of the trigger the popover panel opens on. Each side has a `position-try-fallbacks` so the browser flips it automatically if it would overflow the viewport. |
 | `triggerAriaLabel` | `string` | `""` | aria-label on the trigger button — set this when the `trigger` slot is icon-only. Unset (no attribute) by default, since the trigger slot usually carries its own visible/accessible content. |
-| `popoverAriaLabel` | `string` | `""` | aria-label on the popover content region — set this when the `content` slot has no visible heading. |
-| `closeButtonAriaLabel` | `string` | `"Close"` | aria-label on the close button — override for localisation. |
+| `popoverAriaLabel` | `string` | `""` | Names the popover panel and gives it `role="dialog"` (with no label it has no role, since a name on a generic element isn't announced) — set this when the `content` slot has no visible heading. |
+| `closeButtonAriaLabel` | `string` | `"Close"` | The close button's accessible name (its `aria-label` and its visually hidden button text) — override for localisation. |
+| `closeIcon` | `string` | `"lucide:x"` | Iconify name for the close button icon. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
 
 ## Slots
@@ -80,11 +81,20 @@ the only source of space above/below the slotted content — a plain `<p>` doesn
   does the same in JS. The trigger has `aria-expanded` in every browser.
 - On open, focus moves to the close button (the composable's `onOpen`) so keyboard users land
   inside the panel immediately.
+- The close button is an icon-only `InputButton variant="inline"` with class
+  `pop-over-close-button`, pinned to the panel's block-start/inline-end corner, so it sits top left
+  in right-to-left text. The content slot's top padding keeps content clear of it.
+- The panel is never wider than the viewport minus `3.2rem` (whatever `--pop-over-width` says) or
+  taller than `--pop-over-max-block-size` (default `calc(100dvh - 3.2rem)`); taller content scrolls
+  inside the panel. Unbroken strings in the trigger and panel wrap (`overflow-wrap: anywhere`).
 
 ## CSS custom properties
 
 See `CONSUMER-STYLING.md` for the full `--pop-over-*` token API (gap, trigger outline, panel
-border/background/text/shadow/width, content padding, and close-button tokens).
+border/background/text/shadow/width/max-height, content padding, and close-button tokens).
+
+No line-clamp tokens: all text arrives through the `trigger` and `content` slots, so the consumer
+clamps it in their own markup.
 
 ## Notes
 
@@ -101,3 +111,7 @@ border/background/text/shadow/width, content padding, and close-button tokens).
   `@position-try` blocks commented out and unused; promoted every hardcoded value to a public CSS
   token; added tests, a Storybook story, this skill doc, and a VS Code snippet (all previously
   missing).
+- 2026-10-19 migration: the close button became an `InputButton variant="inline"` (it was a raw
+  `<button>`) and gained a `closeIcon` prop; it now uses logical insets. The panel caps at the
+  viewport width and height and wraps unbroken strings; the trigger wraps too. Added a
+  `StressTest` story and per-story docs descriptions.

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

@@ -180,9 +180,12 @@ Playwright `STORY_BASE` slug. The slug is derived by lowercasing and replacing s
 
 | Title                                         | STORY_BASE slug                             |
 | --------------------------------------------- | ------------------------------------------- |
-| `"Atoms/Text Blocks/HeroText"`                | `atoms-text-blocks-herotext`                |
+| `"Atoms/Text Blocks/Hero Text"`               | `atoms-text-blocks-hero-text`               |
 | `"Components/Forms/Input Text/InputText"`     | `components-forms-input-text-inputtext`     |
 
+Renaming a title changes the slug: update any `playwright/*.playwright.ts` `STORY_BASE` and any
+story links (`?path=/story/...`) that point at it.
+
 ## argTypes control types
 
 | Prop type      | `control`                        |
@@ -274,7 +277,7 @@ 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.
+- 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. Globally registered components are the exception and need no entry: `Icon` (`@nuxt/icon` registers it with `global: true`) and `NuxtLink`.
 - 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.

package/.claude/skills/testing-add-playwright.md

@@ -99,13 +99,18 @@ test.describe("ComponentName — combinations", () => {
 
 ## Deriving the STORY_BASE slug
 
-Take the story `title` from the `.stories.ts` file, lowercase everything, remove spaces,
-and replace `/` with `-`:
-
-| Story `title`                                     | `STORY_BASE`                                    |
-| ------------------------------------------------- | ----------------------------------------------- |
-| `"Atoms/Text Blocks/HeroText"`                    | `atoms-text-blocks-herotext`                    |
-| `"Components/Forms/Input Button/InputButton"` | `components-forms-input-button-inputbuttoncore` |
+Take the story `title` from the `.stories.ts` file, lowercase everything, and replace both spaces
+and `/` with `-`:
+
+| Story `title`                                 | `STORY_BASE`                                |
+| --------------------------------------------- | ------------------------------------------- |
+| `"Atoms/Text Blocks/Hero Text"`               | `atoms-text-blocks-hero-text`               |
+| `"Components/Forms/Input Button/InputButton"` | `components-forms-input-button-inputbutton` |
+
+`STORY_BASE` is hardcoded, and nothing (Vitest, ESLint, the Component Ledger) checks it. When you
+change a story `title`, update `STORY_BASE` in the component's `playwright/` folder in the same
+change. EyebrowText and HeroText pointed at ids from an older title (`...-eyebrowtext`,
+`...-herotext`) until 2026-10-19, so their suites loaded a missing story.
 
 The full story URL pattern is:
 

package/.vscode/srcdev-component-display-qr-code.code-snippets

@@ -15,8 +15,19 @@
       "  aria-label=\"$2\"",
       "  black-color=\"${3:currentColor}\"",
       "  :radius=\"${4:0.5}\"",
-      "  :variant=\"{ inner: '${5|default,circle,rounded,dots,classy,classy-rounded|}', marker: '${6|default,circle,rounded,dots,classy,classy-rounded|}', pixel: '${7|default,circle,rounded,dots,classy,classy-rounded|}' }\"",
+      "  :variant=\"{ inner: '${5|default,circle,rounded,dots,pixelated|}', marker: '${6|default,circle,rounded,dots,pixelated|}', pixel: '${7|default,circle,rounded,dots,pixelated|}' }\"",
       "/>"
     ]
+  },
+  "SRCDEV DisplayQrCode Fallback": {
+    "description": "DisplayQrCode with a fallback for values too long to encode",
+    "scope": "vue,html",
+    "body": [
+      "<DisplayQrCode :qr-value=\"${1:url}\" aria-label=\"${2:QR code}\" @error=\"${3:onQrError}\">",
+      "  <template #fallback>",
+      "    $0",
+      "  </template>",
+      "</DisplayQrCode>"
+    ]
   }
 }

package/.vscode/srcdev-component-hero-text.code-snippets

@@ -4,11 +4,27 @@
     "scope": "vue,html",
     "body": [
       "<HeroText",
-      "  tag=\"$1h1\"",
-      "  fontSize=\"$2title\"",
-      "  :textContent=\"[",
-      "    { text: '$3Designing', styleClass: 'normal' },",
-      "    { text: '$4Artistry', styleClass: 'accent' },",
+      "  tag=\"${1|h1,h2,h3,h4,h5,h6|}\"",
+      "  font-size=\"${2|title,display,heading,subheading,label|}\"",
+      "  :text-content=\"[",
+      "    { text: '${3:Designing}', styleClass: 'normal' },",
+      "    { text: '${4:Artistry}', styleClass: 'accent' },",
+      "  ]\"",
+      "/>"
+    ]
+  },
+  "SRCDEV HeroText Vertical With Icon": {
+    "description": "HeroText stacked vertically with a decorative icon",
+    "scope": "vue,html",
+    "body": [
+      "<HeroText",
+      "  tag=\"${1|h2,h1,h3,h4,h5,h6|}\"",
+      "  axis=\"vertical\"",
+      "  icon=\"${2:lucide:sparkles}\"",
+      "  font-size=\"${3|display,title,heading,subheading,label|}\"",
+      "  :text-content=\"[",
+      "    { text: '${4:Modern}', styleClass: 'normal' },",
+      "    { text: '${5:Living}', styleClass: 'accent' },",
       "  ]\"",
       "/>"
     ]

package/.vscode/srcdev-component-link-text.code-snippets

@@ -19,11 +19,11 @@
     "description": "CSS override scaffold for LinkText tokens",
     "scope": "css",
     "body": [
-      ".$1my-page {",
+      ".${1:my-page} {",
       "  --link-text-colour: $2;",
       "  --link-text-colour-hover: $3;",
-      "  --link-text-decoration: $4underline;",
-      "  --link-text-decoration-hover: $5none;",
+      "  --link-text-decoration: ${4:underline};",
+      "  --link-text-decoration-hover: ${5:none};",
       "}"
     ]
   }

package/.vscode/srcdev-component-pop-over.code-snippets

@@ -40,5 +40,33 @@
       "  </template>",
       "</PopOver>"
     ]
+  },
+  "SRCDEV PopOver Localised Close": {
+    "description": "PopOver with a localised close label and a custom close icon",
+    "scope": "vue,html",
+    "body": [
+      "<PopOver close-button-aria-label=\"${1:Close}\" close-icon=\"${2:lucide:x}\">",
+      "  <template #trigger>",
+      "    <span>$3</span>",
+      "  </template>",
+      "  <template #content>",
+      "    <p>$0</p>",
+      "  </template>",
+      "</PopOver>"
+    ]
+  },
+  "SRCDEV PopOver CSS Overrides": {
+    "description": "Unlayered CSS override scaffold for PopOver public tokens",
+    "scope": "css,vue",
+    "body": [
+      ".${1:my-section} {",
+      "  --pop-over-width: ${2:30rem};",
+      "  --pop-over-gap: ${3:1rem};",
+      "  --pop-over-background-colour: ${4:var(--slate-00)};",
+      "  --pop-over-text-colour: ${5:var(--slate-09)};",
+      "  --pop-over-border-colour: ${6:var(--slate-02)};",
+      "  --pop-over-content-padding: ${7:1.6rem};$0",
+      "}"
+    ]
   }
 }

package/app/components/01.atoms/pop-over/CONSUMER-STYLING.md

@@ -7,7 +7,8 @@
 | `--pop-over-gap` | `1rem` | Space between the trigger and the popover panel |
 | `--pop-over-trigger-outline-width` | `0.1rem` | Trigger focus outline width |
 | `--pop-over-trigger-outline-colour-hover` | `var(--theme-ring)` | Trigger outline colour on focus-visible |
-| `--pop-over-width` | `30rem` | Popover panel width |
+| `--pop-over-width` | `30rem` | Popover panel width, capped at the viewport width minus `3.2rem` |
+| `--pop-over-max-block-size` | `calc(100dvh - 3.2rem)` | Popover panel maximum height; taller content scrolls inside the panel |
 | `--pop-over-border-width` | `0.1rem` | Popover panel border width |
 | `--pop-over-border-colour` | `var(--slate-02)` | Popover panel border colour |
 | `--pop-over-border-radius` | `0.8rem` | Popover panel corner radius |
@@ -18,7 +19,7 @@
 | `--pop-over-z-index` | `999999` | Panel stacking order in browsers without CSS anchor positioning. Ignored where the panel renders in the top layer |
 | `--pop-over-content-padding` | `1.6rem` | Padding around the `content` slot |
 | `--pop-over-content-padding-block-start` | `3.2rem` | Extra top padding so content clears the close button |
-| `--pop-over-close-button-offset` | `0.8rem` | Distance of the close button from the panel's top/right edges |
+| `--pop-over-close-button-offset` | `0.8rem` | Distance of the close button from the panel's block-start and inline-end edges (top right in left-to-right text, top left in right-to-left) |
 | `--pop-over-close-button-size` | `2.4rem` | Close button box width/height |
 | `--pop-over-close-button-border-radius` | `50%` | Close button corner radius |
 | `--pop-over-close-button-colour` | `var(--slate-06)` | Close button icon colour |
@@ -27,6 +28,41 @@
 | `--pop-over-close-button-surface-hover` | `var(--slate-01)` | Close button background on hover/focus-visible |
 | `--pop-over-close-button-outline-colour-hover` | `var(--theme-ring)` | Close button outline colour on hover/focus-visible |
 
+Private tokens (not public API): `--_anchor-name` (the generated CSS anchor name), and `--_anchor-top`, `--_anchor-right`, `--_anchor-bottom`, `--_anchor-left`, and their `-inverse` forms (measured trigger edges, set by `useAnchoredPopover` only where CSS anchor positioning is unsupported).
+
+---
+
+## State hooks
+
+| Hook | Where | Meaning |
+|---|---|---|
+| `[data-placement]` | `.pop-over` root | The `placement` prop: `top`, `right`, `bottom` or `left` |
+| `[data-placement]` | `.pop-over-popover` | The resolved side, which can be the opposite of the prop when there is no room (only set where CSS anchor positioning is unsupported) |
+| `:popover-open` | `.pop-over-popover` | Panel open, where the Popover API exists |
+| `.pop-over-popover-open` | `.pop-over-popover` | Panel open on Safari 16 (no Popover API). Style it in a separate rule from `:popover-open` |
+| `[role="dialog"]` | `.pop-over-popover` | Present only when `popoverAriaLabel` is set |
+
+Inner class names: `.pop-over-trigger` (the trigger `<button>`), `.pop-over-popover` (the panel),
+`.pop-over-close-button` (an `InputButton variant="inline"`, so also `.input-button`),
+`.pop-over-close-button-icon`, `.pop-over-content` (wraps the `content` slot).
+
+> Changed 2026-10-19: the close button is now an `InputButton` (`variant="inline"`, icon-only, with
+> the `closeButtonAriaLabel` text visually hidden) instead of a raw `<button>`, and sits at the
+> inline end, so it moves to the left in right-to-left text. The panel now caps at the viewport
+> width and height and wraps unbroken strings.
+
+---
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<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`.
+
+### Page or section
+
 ```css
 .my-page {
   --pop-over-background-colour: #1a1a1a;
@@ -35,7 +71,7 @@
 }
 ```
 
-Or scope to a single instance via `styleClassPassthrough`:
+### One instance
 
 ```vue
 <PopOver style-class-passthrough="promo-pop-over">...</PopOver>
@@ -43,13 +79,10 @@ Or scope to a single instance via `styleClassPassthrough`:
 
 ---
 
-## Local overrides
+## Class passthrough
 
-Set the tokens above on an element you own (a page or section class, or a class added with
-`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
-`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
-`<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`.
+`style-class-passthrough` adds classes to the `.pop-over` root, which wraps both the trigger and the
+panel, so tokens set on that class reach the panel too.
 
 ---