srcdev-nuxt-components 9.4.11 → 9.5.0

package/.claude/skills/components/toggle-switch-core.md

@@ -28,7 +28,7 @@ than `ToggleSwitchCore` directly.
 | `:style-class-passthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the root element. |
 | `:theme` | `FormUiTheme` | `"default"` | Sets `data-theme` on the root (superseded by `"error"` when `field-has-error` is true — see above). |
 | `:round` | `boolean` | `true` | `true` renders a pill-shaped track/thumb (`border-radius: 100vw`); `false` renders a rounded-square shape (`border-radius: 0.4rem`). See the `--toggle-switch-border-radius` token in CONSUMER-STYLING.md to override the exact value either state produces. |
-| `:aria-describedby` | `string` | `""` | Forwarded to the native checkbox. |
+| `:aria-describedby` | `string` | `""` | Forwarded to the native checkbox (omitted when empty). Changed 2026-09-27: it was ignored before, and the checkbox always pointed at `<id>-description` whether or not that element existed, so `ToggleSwitchWithLabel`'s error-message id never reached it. |
 
 ### v-model
 
@@ -99,7 +99,7 @@ full table with defaults.
 
 ### ToggleSwitchWithLabel
 
-`ToggleSwitchWithLabel` (`variants/ToggleSwitchWithLabel.vue`) composes `ToggleSwitchCore` with
+`ToggleSwitchWithLabel` (`ToggleSwitchWithLabel.vue`) composes `ToggleSwitchCore` with
 `InputLabel`, an optional `description` slot, and `InputError`.
 
 **Additional props over ToggleSwitchCore:**
@@ -129,7 +129,7 @@ Note this wrapper passes `id`/`name`/`required`/`field-has-error`/`true-value`/`
 
 ### ToggleSwitchWithLabelInline
 
-`ToggleSwitchWithLabelInline` (`variants/ToggleSwitchWithLabelInline.vue`) composes
+`ToggleSwitchWithLabelInline` (`ToggleSwitchWithLabelInline.vue`) composes
 `ToggleSwitchCore` with `InputLabel` laid out inline (label and switch side by side, no
 description/error-message support — this variant is for compact settings-row usage).
 

package/.claude/skills/components/triple-toggle-switch.md

@@ -0,0 +1,85 @@
+---
+name: TripleToggleSwitch
+description: TripleToggleSwitch three-option radio pill with a sliding marker, v-model + v-model:field-data, system/light/dark marker gradients, CSS token API
+type: reference
+---
+
+# TripleToggleSwitch
+
+> **Renamed 2026-09-27**: `TripleToggleSwitchCore` → `TripleToggleSwitch` (Control/Field naming,
+> see `.claude/skills/component-naming.md`). Root class `.triple-toggle-switch` unchanged.
+
+## Overview
+
+A pill containing three icon-only radio options, with a circular marker that slides behind the
+selected one. Native `<input type="radio">` elements do the work (keyboard arrows, form
+submission), hidden under each icon; each option's `label` is rendered `sr-only`.
+
+Lives in `app/components/05.forms/triple-toggle-switch/`. Its one in-library consumer is
+`DisplayThemeSwitch` (system/light/dark colour-scheme picker wired to `useSettingsStore`). Reach
+for that for a theme switch; use `TripleToggleSwitch` directly for any other three-way choice.
+
+## Props
+
+| Prop (template form) | Type | Default | Notes |
+|---|---|---|---|
+| `v-model` | `string \| number \| boolean` | (required) | Selected option `value`. |
+| `v-model:field-data` | `IFormMultipleOptions` | (required) | Options (`data[]` of `{ id, name, value, label, icon? }`). Read-only in practice; a `computed` works. |
+| `name` | `string` | `"triple-toggle-switch"` | Shared radio `name`. Give each instance on a page its own. |
+| `aria-label` | `string` | `""` | Accessible name for the `role="radiogroup"`. Omitted from the DOM when empty. Always pass one. |
+| `theme` | `FormUiTheme` | `"default"` | Rendered as `data-theme`. |
+| `step-animation-duration` | `string` | `"250ms"` | Marker slide duration. Ignored under `prefers-reduced-motion`. |
+| `style-class-passthrough` | `string \| string[]` | `[]` | Classes on the root. |
+
+Option `id`s are used as element ids (and as a class on each icon), so they must be unique on the
+page.
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import type { IFormMultipleOptions } from "srcdev-nuxt-components";
+
+const scheme = ref("system");
+const options = ref<IFormMultipleOptions>({
+  data: [
+    { id: "system", name: "scheme", value: "system", label: "System", icon: "material-symbols:night-sight-auto-sharp" },
+    { id: "light", name: "scheme", value: "light", label: "Light", icon: "radix-icons:sun" },
+    { id: "dark", name: "scheme", value: "dark", label: "Dark", icon: "radix-icons:moon" },
+  ],
+  total: 3,
+  skip: 0,
+  limit: 3,
+});
+</script>
+
+<template>
+  <TripleToggleSwitch v-model="scheme" v-model:field-data="options" name="scheme" aria-label="Colour scheme" />
+</template>
+```
+
+## Behaviour
+
+- Exactly three columns (`repeat(3, 1fr)`); more or fewer options will lay out wrongly.
+- Options without an `icon` render no visible content (the label is `sr-only`), so always give
+  each option an icon.
+- The marker is measured from the first option's width on mount and fades in after ~250ms. It
+  isn't re-measured on resize, so changing the icon-size/padding tokens after mount (e.g. toggling
+  a class) leaves the marker at its old size.
+- Marker gradients only exist for the values `system`, `light` and `dark`; other values get the
+  plain `--triple-toggle-switch-marker-surface` background.
+
+## Styling
+
+Full token list in `CONSUMER-STYLING.md` next to the component. Key tokens:
+`--triple-toggle-switch-surface`, `-border`, `-gap`, `-padding`, `-option-padding`, `-icon-size`,
+`-marker-gradient-system`/`-light`/`-dark`, `-option-icon-color`/`-color-active`.
+
+## Notes
+
+- 2026-09-27 migration: renamed from `TripleToggleSwitchCore`; marker gradients promoted to public
+  tokens; `role="radiogroup"` + `ariaLabel` prop added (the group previously had no accessible
+  name; `DisplayThemeSwitch` now passes `"Colour scheme"`); reduced-motion support for the marker;
+  dead `--_form-border-radius` token and commented-out CSS removed; three identical per-id icon
+  colour rules collapsed to one `.option-icon` rule (the per-id classes are still rendered);
+  `fieldData` is now a typed required `defineModel`. Tests added.

package/.claude/skills/composable-zod-validation.md

@@ -77,7 +77,7 @@ Pass `formRef` to the `<form>` and bind `formErrors` to each field's `error-mess
     :field-has-error="Boolean(zodFormControl.submitAttempted && formErrors?.fullName)"
     :required="true"
   />
-  <InputButtonCore
+  <InputButton
     type="submit"
     :is-pending="zodFormControl.displayLoader"
     :readonly="zodFormControl.submitDisabled"

package/.claude/skills/consumer-styles-structure.md

@@ -0,0 +1,153 @@
+# Consumer App Styles Structure
+
+## Overview
+
+How a Nuxt app that extends this layer organises its own global CSS. The app mirrors the library's
+own numbered `app/assets/styles/setup/` folders, so the consumer file that overrides a library file
+is always in the same-numbered folder, and each folder only holds what the app actually changes.
+
+Proven in a production consumer app (2026). Use it for every new consumer app
+(`new-app-scaffold.md` creates the skeleton).
+
+Related skills, which this one ties together:
+
+- `theming-colour-ramps.md` / `theming-override-default.md`: palettes and `--theme-hue`/`--theme-chroma`
+- `theming-form-geometry-tokens.md`: non-colour form tokens
+- `theming-typography-tokens.md`: the `--step-*` scale and font tokens
+- `component-local-style-override.md`: per-component site defaults and page/instance overrides
+
+---
+
+## The tree
+
+```
+app/assets/styles/
+├── main.css                      @import "./setup/";
+└── setup/
+    ├── index.css                 imports each numbered folder, in order
+    ├── 01.config/                page shell: html/body, layout grid, page transitions
+    │   ├── index.css
+    │   ├── _head.css
+    │   └── _page-transitions.css
+    ├── 02.colours/               GENERATED palette files (never hand-edited)
+    │   ├── index.css
+    │   ├── _palette-params.css
+    │   └── _<palette>.css        one per palette in ramps.config.mjs
+    ├── 03.theming/               site-wide token values, one file per concern
+    │   ├── index.css
+    │   ├── _default.css          --theme-hue/--theme-chroma + page-level tokens
+    │   ├── _forms.css            shared form colour tokens (--theme-input-*, --theme-border, ...)
+    │   └── _<component>.css      one per component whose public tokens you set site-wide
+    ├── 04.elements/              only if you change non-colour form geometry (see below)
+    │   └── index.css
+    └── 05.typography/            font family, timing functions, --step-* overrides
+        ├── index.css
+        └── 01.tokens/
+            ├── index.css
+            └── _font-family.css
+```
+
+| Consumer folder | Pairs with library folder | Put here |
+|---|---|---|
+| `01.config/` | `setup/01.config/` (normalise, head) | App shell rules: `html`/`body` behaviour, the page layout grid, `pageTransition`/`layoutTransition` CSS |
+| `02.colours/` | `setup/02.colours/` | Output of the ramp generator (`theming-colour-ramps.md`). Regenerate, don't edit |
+| `03.theming/` | `setup/03.theming/` | `_default.css` (theme hue/chroma, page tokens), shared token families (`_forms.css`, `_button.css`), and `_<component>.css` site defaults |
+| `04.elements/` | `setup/04.elements/` (form geometry) | Overrides of the form geometry tokens you actually change, nothing else |
+| `05.typography/` | `setup/05.typography/` | `--font-family`, easing/timing tokens, any `--step-*` overrides |
+
+There's no consumer `06.utility-classes/` or `a11y/` by default. The library's utilities are
+meant to be used as-is. Add a folder only when the app genuinely needs its own.
+
+Create a folder only when it has something in it. An empty numbered folder is noise, and an
+unimported one is worse (see **Keep the import chain complete**).
+
+---
+
+## Wiring
+
+`nuxt.config.ts`: the library's stylesheet first, then the app's:
+
+```ts
+css: ["srcdev-nuxt-components/app/assets/styles/main.css", "./app/assets/styles/main.css"],
+```
+
+`app/assets/styles/main.css`:
+
+```css
+@import "./setup/";
+```
+
+`app/assets/styles/setup/index.css`, in numbered order:
+
+```css
+@import "./01.config/";
+@import "./02.colours/";
+@import "./03.theming/";
+@import "./04.elements/";
+@import "./05.typography/";
+```
+
+Each folder's `index.css` imports its own files:
+
+```css
+/* setup/03.theming/index.css */
+@import "./_default.css";
+@import "./_forms.css";
+@import "./_card-core.css";
+```
+
+- A **directory** import (`@import "./03.theming/";`) resolves to that folder's `index.css`.
+- A **file** import always includes the `.css` extension (`@import "./_default.css";`). Missing
+  extensions have broken a consumer build before.
+
+**Order.** Everything in `02.colours`–`05.typography` sets custom properties on `:where(html)`, and
+custom properties resolve where they're used, so import order between those folders rarely
+changes the result. Keep numbered order anyway, so a reader can predict it. Order does matter
+within a folder when two files set the **same** token on the same selector (the later one wins),
+so import `_default.css` before files that refine it.
+
+---
+
+## Rules for every file
+
+- **Unlayered.** Never wrap consumer styles in `@layer` (including the library's reserved
+  `consumer` name). Unlayered CSS beats every library layer regardless of load order, and a named
+  layer can end up registered first and lose. Full explanation in
+  `component-local-style-override.md` and `theming-override-default.md`.
+- **Token values on `:where(html)`,** not `:root` or `html`. Zero specificity, so a colour-scheme
+  selector or a page-level `html.some-page` rule setting the same token wins cleanly. See "Site-wide
+  component defaults" in `component-local-style-override.md`.
+- **Only public tokens.** Set tokens the component's or theme's docs list as public. Never set
+  `--_` private tokens.
+- **Override, don't copy.** Put only the tokens you change in a consumer file. Don't copy the
+  library's source files into the matching consumer folder: a copy silently goes stale when the
+  library changes, and hides which values the app actually customised. This matters most for
+  `04.elements/`, where the library's form geometry files are large (`theming-form-geometry-tokens.md`
+  explains why a partial override is enough).
+- **One concern per file, with a one-line header comment** saying what it covers
+  (`/* CardCore — site-wide card look. */`).
+
+---
+
+## Keep the import chain complete
+
+A file or folder only takes effect if every `index.css` above it imports it. When adding a file,
+add its `@import` in the same change. After restructuring, check nothing is orphaned:
+
+```bash
+# every setup folder should be imported by setup/index.css
+ls -d app/assets/styles/setup/*/ | xargs -n1 basename
+grep '@import' app/assets/styles/setup/index.css
+```
+
+A numbered folder that exists but isn't imported is dead CSS that looks live, which is the
+easiest way for this structure to mislead.
+
+---
+
+## Upgrading the layer
+
+Components that haven't been migrated (`/migrate-component`) may rename their tokens when they are.
+After upgrading `srcdev-nuxt-components`, check each `03.theming/_<component>.css` against that
+component's current `CONSUMER-STYLING.md`, and `_forms.css`/`_button.css` against the theming
+skills. A renamed token fails silently: the old name is simply never read.

package/.claude/skills/icon-sets.md

@@ -22,9 +22,9 @@ The layer's `modules/icon-sets.ts` runs at dev/build time and logs an info messa
 | `bitcoin-icons` | `@iconify-json/bitcoin-icons` | Display components |
 | `gravity-ui` | `@iconify-json/gravity-ui` | NavigationItems (burger/ellipsis overflow) |
 | `ic` | `@iconify-json/ic` | CarouselFlip, SliderGallery, CanvasSwitcher |
-| `lucide` | `@iconify-json/lucide` | ColourFinder, TreatmentConsultant |
+| `lucide` | `@iconify-json/lucide` | ActionMenu, InputCopy, PopOver, SelectMenu |
 | `material-symbols` | `@iconify-json/material-symbols` | form components |
-| `mdi` | `@iconify-json/mdi` | NavigationHorizontal, form components, ServicesCard |
+| `mdi` | `@iconify-json/mdi` | Form components, ServicesCard |
 | `radix-icons` | `@iconify-json/radix-icons` | InputPasswordWithLabel, InputError, DisplayThemeSwitch |
 
 ## Fix: install missing packages
@@ -41,5 +41,5 @@ Only install the sets you actually need — unused ones cost nothing either way,
 
 - The layer's build-time info message only lists sets missing from the **consumer's own project**. It is not a hard error.
 - A consumer app can install any additional icon sets it needs for its own components — these won't conflict.
-- If you're not using a particular layer component (e.g. `ColourFinder`), missing `@iconify-json/lucide` won't cause any visible problem.
+- If you're not using a particular layer component (e.g. `SelectMenu`), missing `@iconify-json/lucide` won't cause any visible problem.
 - The `peerDependencies` + `peerDependenciesMeta (optional: true)` in the layer's `package.json` is the npm-standard signal — package managers like npm 7+ will show a notice for missing optional peers during install.

package/.claude/skills/icon-sizing.md

@@ -0,0 +1,66 @@
+# Sizing `<Icon>` Components
+
+## Rule
+
+Since 2026-09-28 the library puts `@nuxt/icon`'s injected CSS in its own `icons` cascade layer,
+ordered before `components`. Component CSS can size an `<Icon>` with `width`/`height` **or**
+`font-size`, and both work:
+
+```css
+.my-component-icon {
+  width: var(--my-component-icon-size, 2rem);
+  height: var(--my-component-icon-size, 2rem);
+}
+```
+
+`font-size` is still the neater choice when the icon should scale with surrounding text, because
+the icon's own `width: 1em; height: 1em` resolves against it.
+
+## How it's wired
+
+`@nuxt/icon` defaults to `mode: "css"`. Each icon renders as a `<span class="iconify i-set:name">`,
+styled by a rule the module injects at runtime:
+
+```css
+:where(.i-material-symbols\:check-small) {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  background-color: currentColor;
+  mask-image: var(--svg);
+  /* ... */
+}
+```
+
+Two settings keep it below component CSS:
+
+- `nuxt.config.ts`: `icon: { cssLayer: "icons" }` wraps the injected rules in `@layer icons`.
+- `app/assets/styles/setup/index.css`: the layer order statement lists `icons` before `components`
+  (`@layer reset, colours, theming, form-tokens, typography, a11y, icons, components, utilities, consumer;`).
+
+**Keep `icons` in that order statement.** A layer that isn't named there and first appears after it
+is appended last, i.e. with the highest priority, which would put the icon rule back on top.
+
+## History
+
+Before 2026-09-28 `cssLayer` wasn't set, so the icon rule was **unlayered**. Unlayered declarations
+beat every layered one regardless of specificity, so any `width`/`height` in `@layer components`
+on an icon showed struck through in DevTools and did nothing, and the rule was "use `font-size`".
+When the layer was added, the `width`/`height` declarations written against icons at the time
+(CanvasSwitcher, DisplayTooltip, PopOver, InputCopy, SelectMenu, CarouselFlip, ResponsiveHeader,
+ServiceDetail, InputSelectCore) started applying for the first time. If an icon in one of those
+looks a different size than it used to, that's the cause.
+
+## Related notes
+
+- **No `line-height` needed when the icon is a flex or grid item.** A flex/grid child is
+  laid out as a block, so no line box and no baseline gap. `line-height: 1` (or `display: block` on the
+  icon) only matters when the icon sits inline in running text inside a normal block.
+- **Colour** works via `color` on the icon (or inherited). The icon paints with
+  `background-color: currentColor` through a mask, so `fill`/`stroke` do nothing in CSS mode.
+- **`mode="svg"`** icons render an `<svg>` with presentational `width`/`height` attributes that any
+  CSS beats.
+- **Consumer apps**: a consumer's own *unlayered* CSS still beats everything here. A consumer's
+  *layered* CSS on icons now also wins over the icon rule, where it previously didn't.
+- **Don't reach for `!important`** or move declarations out of `@layer components`. Both break the
+  library's override model for consumers.

package/.claude/skills/index.md

@@ -35,7 +35,8 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── theming-component-token-pattern.md — standard shape for overridable component colours: public token + inline fallback, no bare var()/no private-only indirection; the three tiers (theme slots / cross-component families / component-scoped); rollout status
 ├── colour-scheme-disable.md         — disable light/dark scheme support in a consumer app
 ├── component-dynamic-slots.md        — named dynamic slots ($slots iteration) vs indexed dynamic slots (itemCount pattern)
-├── component-local-style-override.md — styleClassPassthrough + scoped style block for per-usage visual customisation
+├── component-naming.md               — Control/Field naming convention (InputNumber + InputNumberField, no Core/Default/WithLabel suffixes), rename procedure, backlog with consumer usage
+├── component-local-style-override.md — overriding a component from a consumer app: public tokens on an ancestor, unscoped page blocks, per-instance class/passthrough, consumer `<style scoped>` + :deep() rules, never @layer overrides
 ├── component-prop-driven-container-layout.md — vary CSS grid layout inside @container queries using data-* attribute selectors
 ├── page-transitions.md               — pageTransition/layoutTransition setup; the self-wrapped <NuxtLayout> + layout:false anti-pattern that pulls the header/nav into the transition boundary; fade CSS
 ├── css-nesting-conventions.md                — native CSS nesting rules: why &__child Sass BEM concatenation silently breaks, correct patterns
@@ -43,12 +44,14 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── css-animation-utilities.md                — scroll-driven animation utility classes: scroller-x (carousel), entry-zoom-reveal, entry-slide-in, entry-exit-blur, auto-rotate
 ├── component-aria-landmark.md        — useAriaLabelledById composable: aria-labelledby for section/article/aside tags (not main), consumer-bound vs self-bound pattern, built-in broken-reference console warning
 ├── component-export-types.md         — move inline component types to app/types/components/ barrel for consumer imports
-├── component-inline-action-button.md — InputButtonCore variant="inline" pattern for buttons embedded in custom input wrappers
+├── component-inline-action-button.md — InputButton variant="inline" pattern for buttons embedded in custom input wrappers
 ├── vue-video-autoplay.md             — autoplay on client-side navigation: use <source> child (not :src on <video>), :key, and explicit v.load()
 ├── icon-sets.md                      — icon set packages required by layer components, FOUC prevention, component→package map
+├── icon-sizing.md                    — @nuxt/icon CSS lives in an `icons` layer below components (2026-09-28), so width/height and font-size both size an <Icon>; keep `icons` in the @layer order
 ├── vercel-node-version.md            — .nvmrc pinned to Node 24 is required; without it Vercel uses npm 10 which crashes on versionless optional stubs
 ├── robots-env-aware.md               — @nuxtjs/robots: allow crawling on prod domain only, block on preview/staging via env var
 ├── new-app-scaffold.md               — scaffold a new Nuxt consumer app extending this layer (package.json, nuxt.config, app structure, CLAUDE.md)
+├── consumer-styles-structure.md       — consumer app's app/assets/styles/setup/ tree mirroring the library's numbered folders, index.css import chain, unlayered + :where(html) rules, override-don't-copy, orphaned-import check
 ├── qa-panel.md                       — collapsible panel for toggling component props live on a page, for consuming apps' own pages (gate with isDev unless demo-only); this library's own demos live in Storybook
 ├── pull-request-description.md       — produce a PR description as a fenced markdown block from git diff vs main
 ├── using-component-skills.md         — discover and use component skills in consumer apps: where skills land, browsing patterns, workflow for deciding build vs. compose
@@ -62,17 +65,20 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── composable-cookie-consent.md      — useCookieConsent: unset/granted/denied state, cookie persistence, wraps @nuxt/scripts' useScriptTriggerConsent
 ├── composable-analytics.md           — useAnalytics: provider-agnostic trackEvent/page-view tracking (google-analytics only implemented), consent-gated, single call site for setup + firing events
 └── components/
-    ├── alert-content-inner.md    — AlertContentInner: shared icon/body/dismiss molecule under AlertContent + AlertMaskedContent; app.config icon map (alertContent.icons + dismissIcon) covers all consumers
+    ├── alert-content.md          — AlertContent + AlertContentInner: themed alert panel (icon/title/content/actions/dismiss) under DisplayToast, DisplayPrompt and AlertMaskedContent; showIcon, #actions row, --alert-content-* tokens, app.config icon map
     ├── alert-mask-core.md      — AlertMaskCore: SVG border/background mask sized to slotted content via ResizeObserver, config-prop-driven geometry/colour (no CSS token API)
+    ├── alert-masked-content.md — AlertMaskedContent: AlertContentInner inside AlertMaskCore's SVG mask (accent cut-out border + translucent fill); masked variant for DisplayToast/DisplayPrompt; --alert-masked-content-* colour tokens
     ├── animated-svg-text.md    — AnimatedSvgText: inline SVG stroke-draw-then-fill animation, text slot, CSS token API
     ├── accordian-core.md       — AccordianCore indexed dynamic slots (accordian-{n}-summary/icon/content), exclusive-open grouping
     ├── eyebrow-text.md         — EyebrowText props, usage patterns, styling
     ├── hero-text.md            — HeroText props, usage patterns, styling
-    ├── layout-grid-by-cols.md  — LayoutGridByCols dynamic slots (item-{n}), props, column/gap/breakpoint decisions
+    ├── layout-grid-by-cols.md  — LayoutGridByCols dynamic slots (item-{n}), column/gap/collapse props that write public --layout-grid-by-cols-* tokens (CSS-settable), section label
     ├── page-row.md             — PageRow layout primitive: CSS grid named lines, nesting pattern, align prop, aria-labelledby, CSS token API
     ├── link-text.md            — LinkText props, slots, usage patterns, styling
     ├── header-block.md         — HeaderBlock: tagLevel/classLevel semantic-vs-visual heading decoupling, page-heading-N utility classes
+    ├── text-block.md           — TextBlock: vertical-rhythm text wrapper, --text-block-padding-block-start/-end tokens, heading-id slot prop for section/article aria-labelledby
     ├── page-hero-highlights.md — PageHeroHighlights template: hero + highlights strip grid, CSS custom property theming
+    ├── slider-gallery.md       — SliderGallery: full-screen image carousel, IGalleryData, pause-on-hover/reduced-motion auto-advance, prefixed classes, CSS tokens
     ├── services-card.md        — ServicesCard props (incl. eyebrowConfig/heroConfig), actions slot, CSS tokens, page boilerplate
     ├── services-card-grid.md        — ServicesCardGrid props, config pass-through, CSS tokens, full page boilerplate
     ├── service-summary-grid.md      — ServiceSummaryGrid props, useAlternateReverse zigzag layout, page boilerplate
@@ -85,14 +91,15 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── stepper-list.md         — StepperList dynamic slots (item-{n}/indicator-{n}), props, connector behaviour
     ├── 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 props, slots, CSS token API (--glass-panel-bg/border-color/shadow/highlight), theming override
-    ├── navigation-horizontal.md — NavigationHorizontal props, NavItemData type, CSS token API, import path gotcha
+    ├── 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
+    ├── 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
     ├── 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, CSS tokens, browser support
-    ├── scroll-reveal-image.md  — ScrollRevealImage: single-image parallax reveal, focalX, imgWidth/imgHeight, responsive frame height
+    ├── 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
+    ├── scroll-reveal-image.md  — ScrollRevealImage: single-image parallax reveal, imgWidth/imgHeight, public focal-x/focal-y crop tokens, frame tokens settable from CSS
     ├── wipe-away-vertical.md   — WipeAwayVertical: scroll-driven vertical wipe-away effect, pure-CSS grid overlay (no JS), indexed dynamic slots, sticky-centering-via-calc gotcha, CSS tokens
     ├── marquee-scroller.md     — MarqueeScroller: infinite logo/badge scroller, per-item dynamic slots (marqueeData id), hover/focus/keyboard pause, reduced-motion, CSS tokens
     ├── rotating-carousel-image.md — RotatingCarouselImage: 3D rotating image carousel, scroll-parallax tilt, focus/keyboard/hover pause, reduced-motion, CSS tokens
@@ -102,24 +109,24 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── display-qr-code.md      — DisplayQrCode: QR code SVG from a string value, colour/size/variant/radius props, currentColor default
     ├── capture-qr-code.md      — CaptureQrCode: live camera scanner, error state, visibility/route/KeepAlive lifecycle, media stream cleanup
     ├── decode-qr-code.md       — DecodeQrCode: file picker + drag-and-drop image decoder, shared results list, CSS override points
-    ├── auto-grid.md            — AutoGrid: auto-fit responsive grid, $slots iteration, --auto-grid-min-col-size/gap tokens, semantic tag + aria
-    ├── display-avatar.md       — DisplayAvatar: circular avatar with image/initials fallback, size variants, chip badge, icon slot, styleClassPassthrough
-    ├── display-theme-switch.md — DisplayThemeSwitch: system/light/dark picker wrapping TripleToggleSwitchCore, wired to useSettingsStore, labels/icons props, small sizing variant
+    ├── auto-grid.md            — AutoGrid: auto-fit responsive grid, $slots iteration, --auto-grid-gap/min-col-size-{small,default,large} tokens, is-responsive, semantic tag + aria
+    ├── display-avatar.md       — DisplayAvatar (02.molecules): circular avatar with image/initials fallback (alt announced), size scale tokens, --display-avatar-* colours, chip badge, icon slot
+    ├── display-theme-switch.md — DisplayThemeSwitch: system/light/dark picker wrapping TripleToggleSwitch, wired to useSettingsStore, labels/icons props, small sizing variant
     ├── card-core.md            — CardCore: generic card container, dynamic named slots as rows, 4 variants, blurred backdrop layer, full CSS token API
-    ├── action-menu.md          — ActionMenu + ActionMenuItemCore: ellipsis trigger + anchored popover menu, indexed item-{n} slots, link/button items, full CSS token API
+    ├── action-menu.md          — ActionMenu + ActionMenuItem: ellipsis trigger + anchored popover menu, indexed item-{n} slots, link/button items, full CSS token API
     ├── select-menu.md          — SelectMenu: v-model single-select listbox popover (ActionMenu's popover mechanics, InputSelectCore's selected-option semantics), icon/text/chevron trigger toggles, checkmark on selected option, options-array driven, full CSS token API
     ├── display-dialog.md       — DisplayDialog: native <dialog> overlay, 5 variants (dialog/modal/confirm/alert/fullscreen), useDialogControls integration, CSS token API
     ├── display-chip.md         — DisplayChip: status indicator chip overlay, CSS trig positioning, circle/square shapes, status colours, icon/label content
-    ├── display-pill.md         — DisplayPill: pill/badge label with icon slot, 6 variants, 3 sizes, reversible order, full CSS token API for border/outline/colour
+    ├── display-pill.md         — DisplayPill: pill/badge label with icon slot, 6 variants, 3 sizes, reversible order, --display-pill-* tokens (renamed from --theme-pill-*; variants fall back to base colour tokens)
     ├── carousel-flip.md        — CarouselFlip: FLIP-animated carousel, carouselDataIds slot API, buttonLayout variants (sides/controls-flanking/controls-grouped-right/overlay), CSS tokens
-    ├── samaritan-prompt-mixed.md — SamaritanPromptMixed: animated text prompt, typewriter/word-pulse effects, MessageConfig API, aria-live accessibility, CSS tokens
+    ├── samaritan-prompt.md — SamaritanPrompt + SamaritanPromptMixed: animated text prompts, typewriter/word-pulse effects, MessageConfig API, pause on hover, aria-live, CSS tokens
     ├── display-toast.md          — DisplayToast (standalone v-model) + DisplayToastProvider + useToastQueue (app-wide queue): stacking, FLIP dismiss, maxVisible, SemanticTheme × 4, masked SVG glass variant
     ├── display-prompt.md         — DisplayPrompt: inline notification banner, SemanticTheme × 4, local vs parent-controlled dismiss, outlined modifier, CSS token override
     ├── expanding-panel-classic.md — ExpandingPanelClassic: grid-template-rows animation (no Baseline-2025 dependency), same API as ExpandingPanel, cross-browser animation parity trade-off
     ├── 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 driven by useCookieConsent, message/acceptLabel/rejectLabel slots, CSS token API
+    ├── 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
     ├── 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
@@ -127,11 +134,23 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── display-tooltip-defined.md — DisplayTooltipDefined: structured title/body/action tooltip content with close button, composes DisplayTooltip
     ├── pop-over.md                — PopOver: generic anchor-positioned disclosure panel, consumer-supplied trigger/content slots, placement prop, CSS token API
     ├── input-text-core.md        — InputTextCore: native text/date/number input primitive, min/max pass-through (date-picker range), CSS token API; Variants section covers InputTextWithLabel/InputPasswordWithLabel/InputTextAsNumberWithLabel
+    ├── input-button.md           — InputButton (renamed from InputButtonCore 2026-09-28): button/NuxtLink/a, variants, icon slots, readonly (aria-disabled, activation blocked), tokens
     ├── input-range-core.md       — InputRangeCore: native range-slider primitive, markers/datalist slots, dead --theme-form-range-accent-color token fixed, CSS token API; Variants section covers InputRangeDefault
-    ├── input-number-core.md      — InputNumberCore: native number-input primitive, left/right step-button slots, missing base class/placeholder/mismatched slot-selector bugs fixed, CSS token API; Variants section covers InputNumberDefault
+    ├── input-number.md           — InputNumber: native number-input primitive, left/right step-button slots, missing base class/placeholder/mismatched slot-selector bugs fixed, CSS token API; Variants section covers InputNumberField
+    ├── form-field.md             — FormField: layout wrapper for one form control (width cap, gutter, field spacing), data-width/data-has-gutter/data-invalid hooks, dead .underline rule removed, CSS token API
+    ├── form-fieldset.md          — FormFieldset: shared fieldset+legend for checkbox/radio groups, groupRole prop (hardcoded radiogroup bug fixed), aria-required only on radiogroup, dead description slot removed, legend token API
+    ├── input-error.md            — InputError: red error strip every *Field wrapper renders under its control, data-visible/data-detached/data-input-variant hooks, generic .inner/.message class names prefixed, dead compact prop and hidden-state border CSS removed, icon prop, CSS token API
+    ├── input-description.md      — InputDescription: field help text (descriptionText/descriptionHtml slots), renders nothing without a slot, wrappers' unconditional slot forwarding/outlined double-render/missing aria id fixed, dead id/theme props removed, data-input-variant/data-invalid hooks, CSS token API
+    ├── input-label.md            — InputLabel: the <label> every labelled *Field wrapper renders (textLabel/htmlLabel slots), id is the control's id rendered as for, required/optional indicator (app.config srcdev.inputLabel, text or icon), dead name/theme props and fallthrough :for removed, data-input-variant/data-invalid hooks, CSS token API
+    ├── form-wrapper.md           — FormWrapper: width-capped outer container for a whole form, data-width hook, named inline-size container, not centred by default (--form-wrapper-margin-inline), CSS token API
+    ├── pending-effect.md         — PendingEffect: animated dashed border InputButton draws while is-pending (has-pending-effect), tokens renamed to --pending-effect-* and read at point of use, animation moved off the host button, aria-hidden
     ├── input-textarea-core.md    — InputTextareaCore: native textarea primitive, left/right decorative slots, undefined-token/dead-code/label-leak bugs fixed, CSS token API; Variants section covers InputTextareaWithLabel
     ├── input-select-core.md      — InputSelectCore: native select primitive, data-driven options with icon decorator, dead required/styleClassPassthrough/isDirty-isActive functionality fixed, appearance:base-select browser-support note, CSS token API; Variants section covers InputSelectWithLabel
+    ├── input-checkbox-radio.md   — InputCheckboxRadio (bare control), InputCheckboxRadioField (labelled), InputCheckboxRadioButton (button/pill option): renamed from Core/WithLabel, state classes → data-* hooks, type-switch v-model fix, no aria-checked, icon font-size sizing, button spacing tokens
+    ├── input-checkbox.md         — MultipleCheckboxes/SingleCheckbox: fieldset-wrapped checkbox group (data-driven, button or labelled) and single checkbox, per-box native-required/styleClassPassthrough/data-testid bugs fixed, spacing token API
+    ├── input-radio.md            — MultipleRadiobuttons: fieldset radiogroup (data-driven, button or labelled), shared-name grouping bug fixed, dead label/placeholder/equalCols props removed, data-options-layout hook, spacing token API
     ├── toggle-switch-core.md      — ToggleSwitchCore: pill/square checkbox-backed toggle primitive, dead round-prop/data-theme-error functionality and story theme-options bugs fixed, CSS token API; Variants section covers ToggleSwitchWithLabel/ToggleSwitchWithLabelInline
+    ├── triple-toggle-switch.md    — TripleToggleSwitch (renamed from TripleToggleSwitchCore): three-option icon radio pill with sliding marker, radiogroup + ariaLabel, system/light/dark marker-gradient tokens, reduced-motion, CSS token API
     ├── entry-animation.md         — EntryAnimation: scroll-driven entry animation wrapper (slide-in/zoom-reveal/exit-blur utility classes), skipAnimation for above-the-fold loop items, reduced-motion handled at the CSS layer
     ├── column-flow-grid.md        — ColumnFlowGrid (renamed from MasonryGrid): CSS multi-column text-flow layout, named dynamic slots (no count/data prop), itemMinWidth/gap/unit sizing, CSS token API; not a true masonry, see "which one do I want?"
     ├── masonry-grid.md            — MasonryGrid: real measured-height masonry (greedy shortest-column packing, animated resize) absorbed from the now-retired MasonryGridOrdered; named dynamic slots, fixedWidth/justify, CSS token API

package/.claude/skills/new-app-scaffold.md

@@ -212,7 +212,17 @@ node 20
 ```
 app/
 ├── assets/styles/
-│   └── main.css          ← brand tokens + font vars (loads after layer CSS)
+│   ├── main.css          ← @import "./setup/"; (loads after layer CSS)
+│   └── setup/            ← numbered folders mirroring the library's, see consumer-styles-structure.md
+│       ├── index.css
+│       ├── 03.theming/
+│       │   ├── index.css
+│       │   └── _default.css
+│       └── 05.typography/
+│           ├── index.css
+│           └── 01.tokens/
+│               ├── index.css
+│               └── _font-family.css
 ├── layouts/
 │   └── default.vue       ← minimal shell with <slot>
 ├── pages/
@@ -220,14 +230,42 @@ app/
 └── error.vue             ← 404 / 500 handler with clearError redirect
 ```
 
-**`app/assets/styles/main.css`** — declare brand CSS custom properties and set font-family:
+Styles follow `consumer-styles-structure.md`: only create the numbered folders the app has
+something for. `03.theming` and `05.typography` are the usual starting pair; add `02.colours`
+when you generate palettes (`theming-override-default.md`) and `01.config` for page shell rules
+or page transitions. All files unlayered, token values on `:where(html)`.
+
+**`app/assets/styles/main.css`**:
+
+```css
+@import "./setup/";
+```
+
+**`app/assets/styles/setup/index.css`**:
+
+```css
+@import "./03.theming/";
+@import "./05.typography/";
+```
+
+**`setup/03.theming/index.css`** / **`_default.css`**: brand theme values:
+
+```css
+/* index.css */
+@import "./_default.css";
+
+/* _default.css */
+:where(html) {
+  /* --theme-hue / --theme-chroma once palettes are generated (theming-override-default.md) */
+}
+```
+
+**`setup/05.typography/index.css`** → `@import "./01.tokens/";`, **`01.tokens/index.css`** →
+`@import "./_font-family.css";`, and **`_font-family.css`**:
 
 ```css
-:root {
-  /* Add brand colour tokens */
-  --font-display: "{Display Font}", serif;
-  --font-body: "{Body Font}", sans-serif;
-  font-family: var(--font-body);
+:where(html) {
+  --font-family: "{Body Font}", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
 }
 ```
 

package/.claude/skills/pull-request-description.md

@@ -46,3 +46,4 @@ Any caveats, follow-up tickets, or decisions worth flagging for reviewers (optio
 - Lead with the user-facing or functional change; CSS/test/doc tidy-ups can be secondary bullets
 - Keep the tone factual — describe what changed, not the effort involved
 - Do not include "Co-Authored-By" or other git trailer lines — those belong in the commit message, not the PR body
+- Never name a consuming app, client site or repo (or its file paths, page names or domain): this repo and its npm package are public. Say "a consumer app" instead, even when the change was prompted by a specific one.