srcdev-nuxt-components 9.1.55 → 9.1.57

package/.claude/settings.json

@@ -27,10 +27,38 @@
       "Bash(git -C /Users/simoncornforth/websites/instepreflexology log --oneline -3)",
       "Bash(git -C /Users/simoncornforth/websites/instepreflexology add package-lock.json .nvmrc)",
       "Bash(git -C /Users/simoncornforth/websites/instepreflexology commit -m ' *)",
-      "Bash(git -C /Users/simoncornforth/websites/instepreflexology push)"
+      "Bash(git -C /Users/simoncornforth/websites/instepreflexology push)",
+      "Bash(node scripts/generate-ramps.mjs)",
+      "Bash(sed -i '' 's/var\\(--theme-input-border\\)/var\\(--theme-border\\)/g' app/components/05.forms/input-text/InputTextCore.vue app/components/05.forms/input-text/variants/InputTextAsNumberWithLabel.vue app/components/05.forms/input-textarea/InputTextareaCore.vue app/components/05.forms/input-select/InputSelectCore.vue app/components/05.forms/input-checkbox-radio/InputCheckboxRadioButton.vue app/components/05.forms/input-checkbox-radio/InputCheckboxRadioCore.vue app/components/05.forms/toggle-switch/ToggleSwitchCore.vue app/components/05.forms/triple-toggle-switch/TripleToggleSwitchCore.vue app/components/display-theme-switch/DisplayThemeSwitch.vue app/components/05.forms/input-copy/InputCopyCore.vue app/components/05.forms/input-number/InputNumberCore.vue)",
+      "Bash(sed -i '' 's/var\\(--theme-input-outline\\);/transparent;/g' app/components/05.forms/input-text/InputTextCore.vue app/components/05.forms/input-textarea/InputTextareaCore.vue app/components/05.forms/input-select/InputSelectCore.vue app/components/05.forms/input-checkbox-radio/InputCheckboxRadioButton.vue app/components/05.forms/input-checkbox-radio/InputCheckboxRadioCore.vue app/components/05.forms/toggle-switch/ToggleSwitchCore.vue app/components/05.forms/triple-toggle-switch/TripleToggleSwitchCore.vue app/components/display-theme-switch/DisplayThemeSwitch.vue app/components/05.forms/input-number/InputNumberCore.vue)",
+      "Bash(sed -i '' 's/var\\(--theme-input-outline-focus\\)/var\\(--theme-border-focus\\)/g' app/components/05.forms/input-text/InputTextCore.vue app/components/05.forms/input-textarea/InputTextareaCore.vue app/components/05.forms/input-select/InputSelectCore.vue app/components/05.forms/input-checkbox-radio/InputCheckboxRadioButton.vue app/components/05.forms/input-checkbox-radio/InputCheckboxRadioCore.vue app/components/05.forms/toggle-switch/ToggleSwitchCore.vue app/components/05.forms/input-copy/InputCopyCore.vue)",
+      "Bash(sed -i '' 's/var\\(--theme-input-outline-hover\\)/var\\(--theme-ring\\)/g' app/components/05.forms/input-checkbox-radio/InputCheckboxRadioButton.vue app/components/05.forms/triple-toggle-switch/TripleToggleSwitchCore.vue app/components/display-theme-switch/DisplayThemeSwitch.vue)",
+      "Bash(sed -i '' 's/var\\(--theme-checkbox-symbol-color\\)/var\\(--theme-text\\)/g' app/components/05.forms/input-checkbox-radio/InputCheckboxRadioCore.vue app/components/05.forms/toggle-switch/ToggleSwitchCore.vue)",
+      "Bash(sed -i '' 's/var\\(--theme-input-surface-focus\\)/var\\(--theme-surface-subtle\\)/g' /Users/simoncornforth/websites/nuxt-components/app/components/05.forms/input-checkbox-radio/InputCheckboxRadioButton.vue)",
+      "Bash(sed -i '' 's/var\\(--theme-checkbox-label-text-color\\)/var\\(--colour-text-default\\)/g' /Users/simoncornforth/websites/nuxt-components/app/components/05.forms/input-checkbox-radio/InputCheckboxRadioButton.vue)",
+      "Bash(sed -i '' 's/var\\(--theme-button-border\\);/var\\(--theme-border\\);/g; s/var\\(--theme-button-outline\\);/var\\(--theme-ring\\);/g; s/var\\(--theme-button-border-hover\\);/var\\(--theme-surface\\);/g; s/var\\(--theme-button-outline-hover\\);/var\\(--theme-surface\\);/g' /Users/simoncornforth/websites/nuxt-components/app/components/display-tooltip/DisplayTooltip.vue)",
+      "Bash(sed -i '' 's/var\\(--theme-input-outline, red\\)/transparent/g' /Users/simoncornforth/websites/nuxt-components/app/components/05.forms/toggle-switch/ToggleSwitchCore.vue)",
+      "Bash(xargs ls -la)",
+      "Skill(code-review)",
+      "Skill(code-review:*)",
+      "Bash(cd /Users/simoncornforth/websites/nuxt-components/.vscode && rm srcdev-nuxt3-accordian-component.code-snippets srcdev-nuxt3-carousel-basic-component.code-snippets srcdev-nuxt3-carousel-flip-component.code-snippets srcdev-nuxt3-component-boilerplate.code-snippets srcdev-nuxt3-container-glow-component.code-snippets srcdev-nuxt3-display-banner-component.code-snippets srcdev-nuxt3-display-details-component.code-snippets srcdev-nuxt3-expanding-panel-component.code-snippets srcdev-nuxt3-layout-row.code-snippets srcdev-nuxt3-page-layout.code-snippets srcdev-nuxt3-responsive-header-component.code-snippets srcdev-nuxt3-tabs-component.code-snippets && ls *.code-snippets)",
+      "Bash(mv srcdev-nuxt3-dialog-component.code-snippets srcdev-component-dialog.code-snippets)",
+      "Bash(mv srcdev-nuxt3-display-prompt-component.code-snippets srcdev-component-display-prompt.code-snippets)",
+      "Bash(mv srcdev-nuxt3-display-toast-component.code-snippets srcdev-component-display-toast.code-snippets)",
+      "Bash(mv srcdev-nuxt3-pinia-store-setup.code-snippets srcdev-component-pinia-store.code-snippets)",
+      "Bash(SRCDEV_STANDALONE=true npx vitest run app/components/01.atoms/display-dialog)",
+      "Bash(ls /Users/simoncornforth/websites/nuxt-components/.claude/ && echo \"---\" && cat /Users/simoncornforth/websites/nuxt-components/.gitignore | grep -i \"claude\\\\|memory\\\\|projects\" && echo \"---gitignore done---\" && ls /Users/simoncornforth/.claude/projects/ 2>/dev/null | head -5)",
+      "Read(//Users/simoncornforth/.claude/projects/**)",
+      "Bash(cp /Users/simoncornforth/websites/nuxt-components/.claude/projects/-Users-simoncornforth-websites-nuxt-components/memory/project_app_config_defaults.md /Users/simoncornforth/.claude/projects/-Users-simoncornforth-websites-nuxt-components/memory/project_app_config_defaults.md)",
+      "Bash(rm -rf /Users/simoncornforth/websites/nuxt-components/.claude/projects/)",
+      "Bash(SRCDEV_STANDALONE=true npx vitest run app/components/01.atoms/toast)",
+      "Bash(SRCDEV_STANDALONE=true npx vitest run app/components/02.molecules/alert-content)",
+      "Bash(SRCDEV_STANDALONE=true npx vitest run app/components/01.atoms/prompt)",
+      "Bash(git fetch *)"
     ],
     "additionalDirectories": [
-      "/Users/simoncornforth/websites/instepreflexology"
+      "/Users/simoncornforth/websites/instepreflexology",
+      "/Users/simoncornforth/websites/nuxt-components/.vscode"
     ]
   }
 }

package/.claude/skills/components/alert-content-inner.md

@@ -0,0 +1,60 @@
+# AlertContentInner
+
+## Overview
+
+Internal molecule used by `AlertContent` and `AlertMaskedContent`, which are in turn used by
+`DisplayToast` and `DisplayPrompt`. Renders the icon, title/body text, and optional dismiss button.
+Because it sits below multiple consumer components, icon customisation here applies everywhere.
+
+**Location**: `app/components/02.molecules/alert-content/AlertContentInner.vue`
+
+## Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `theme` | `SemanticTheme` | — | **Required.** Drives the default icon and `data-theme` (set by parent `AlertContent`). |
+| `customIcon` | `string` | `undefined` | Icon name override passed down from the toast/prompt `config.content.customIcon`. |
+| `dismissible` | `boolean` | `false` | Shows the dismiss button when `true`. |
+| `contentId` | `string` | `undefined` | Sets `id` on `.alert-content-body` for `aria-describedby` wiring. |
+| `ariaLive` | `"polite" \| "assertive" \| "off"` | `undefined` | Sets `aria-live` on `.alert-content-body`. |
+
+## app.config defaults
+
+Icon names — both per-theme and the dismiss button — are configurable globally via `app.config`.
+One change here covers every toast, prompt, and any other component built on `AlertContentInner`.
+
+```ts
+// Consumer's app.config.ts
+export default defineAppConfig({
+  srcdev: {
+    alertContent: {
+      icons: {
+        info: "heroicons:information-circle",
+        success: "heroicons:check-circle",
+        warning: "heroicons:exclamation-triangle",
+        error: "heroicons:x-circle",
+      },
+      dismissIcon: "heroicons:x-mark",
+    },
+  },
+})
+```
+
+Resolution chain: **`customIcon` prop → app.config icons → hardcoded fallback**.
+
+The `dismissIcon` slot (`#dismissIcon` on `AlertContent`) always wins over app.config if provided.
+
+## Slots
+
+| Slot | Description |
+|---|---|
+| `#icon` | Replaces the entire icon region. |
+| `#title` | Title line inside `.alert-content-body`. |
+| `#content` | Body text inside `.alert-content-body`. |
+| `#dismissIcon` | Replaces the dismiss button icon. |
+| `#dismissLabel` | SR-only label for the dismiss button (default: `"Close"`). |
+
+## Notes
+
+- Do not use `AlertContentInner` directly in pages — use `AlertContent` or `AlertMaskedContent` instead.
+- `AlertMaskedContent` wraps `AlertContentInner` with a different background treatment (SVG glass border).

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

@@ -14,11 +14,13 @@ open/close state management.
 |---|---|---|---|
 | `dataDialogId` | `string` | — | **Required.** Unique identifier rendered as `data-dialog-id` attribute. |
 | `variant` | `'dialog' \| 'modal' \| 'confirm' \| 'alert' \| 'fullscreen'` | `'dialog'` | Controls panel sizing and ARIA role. |
+| `theme` | `SemanticTheme` | `undefined` | Optional header accent — `data-theme` on `.header` only; adds a coloured bottom border and tints the close icon. |
 | `v-model` | `boolean` | — | Controls open/closed state. |
 | `allowContentScroll` | `boolean` | `false` | Enables independent scroll on `.dialog-content`. |
 | `lockViewport` | `boolean` | `true` | Adds/removes `lock` class on `<body>` on mount/close. |
 | `justifyDialog` | `'start' \| 'center' \| 'end'` | `'center'` | Horizontal position of panel within overlay. |
 | `alignDialog` | `'start' \| 'center' \| 'end'` | `'center'` | Vertical position of panel within overlay. |
+| `closeIcon` | `string` | app.config | Icon name for the header close button. Override per-instance or set globally via `app.config`. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root `<dialog>` element. |
 
 ## Slots
@@ -104,6 +106,28 @@ are both disabled — the user must act via the footer buttons.
 </DisplayDialog>
 ```
 
+## app.config defaults
+
+All props except `dataDialogId` and `styleClassPassthrough` can be set globally via `app.config`.
+The resolution chain is: **explicit prop → app.config → hardcoded fallback**.
+
+```ts
+// app.config.ts in the consumer app
+export default defineAppConfig({
+  srcdev: {
+    displayDialog: {
+      variant: "modal",
+      alignDialog: "end",
+      lockViewport: true,
+      closeIcon: "heroicons:x-mark",
+      theme: "info",
+    },
+  },
+})
+```
+
+Per-instance props always win — app.config only fills in when a prop is absent.
+
 ## CSS token API
 
 See `CONSUMER-STYLING.md` in the component folder for the full token reference. Prefer global
@@ -119,6 +143,62 @@ CSS over per-instance overrides — dialogs are site-wide UI:
 }
 ```
 
+## Nested dialogs
+
+When a dialog needs to launch its own sub-dialog (e.g. "Discard changes?" before closing an edit
+form), the cleanest approach is to call `useDialogControls` **inside the dialog component itself**.
+The sub-dialog is entirely self-contained — the parent page doesn't need to know about it.
+
+```vue
+<!-- EditProfileDialog.vue -->
+<script setup lang="ts">
+const emit = defineEmits<{ close: [] }>();
+
+const { dialogsConfig, openDialog, closeDialog } = useDialogControls({
+  confirmDiscard: {
+    onConfirm: () => emit("close"),
+    onCancel: () => {},
+  },
+});
+
+const handleClose = () => {
+  if (hasUnsavedChanges.value) {
+    openDialog("confirmDiscard");
+  } else {
+    emit("close");
+  }
+};
+</script>
+
+<template>
+  <!-- main dialog content, close button calls handleClose() -->
+
+  <!-- sub-dialog rendered inside the same component -->
+  <DisplayDialog
+    v-if="dialogsConfig['confirmDiscard']"
+    v-model="dialogsConfig['confirmDiscard']"
+    variant="confirm"
+    theme="warning"
+    data-dialog-id="confirmDiscard"
+  >
+    <template #dialogTitle><p>Discard changes?</p></template>
+    <template #dialogContent><p>Your unsaved changes will be lost.</p></template>
+    <template #actionButtonLeft>
+      <button @click="closeDialog('confirmDiscard', 'cancel')">Keep editing</button>
+    </template>
+    <template #actionButtonRight>
+      <button @click="closeDialog('confirmDiscard', 'confirm')">Discard</button>
+    </template>
+  </DisplayDialog>
+</template>
+```
+
+Both dialogs are open simultaneously — native `<dialog>` stacking order ensures the confirm
+renders on top. The confirm resolves first; its `onConfirm` callback triggers the parent close.
+
+**Avoid** registering the sub-dialog on the page level — that couples the page to the dialog's
+internal concern and leaks implementation detail upward.
+
 ## Notes
 
 - Always use `v-if="dialogsConfig['id']"` (not `v-show`) — `DisplayDialog` runs body-lock logic

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

@@ -0,0 +1,163 @@
+# DisplayPrompt
+
+## Overview
+
+`DisplayPrompt` is an inline notification banner with a themed icon, title, optional content, and
+an optional dismiss button. It collapses in-place via CSS grid animation rather than removing from
+the DOM. Dismiss can be controlled locally (closes itself) or by a parent via `v-model`.
+
+**Location**: `app/components/01.atoms/prompt/DisplayPrompt.vue`
+**Types**: `~/types/components` — `DisplayPromptTheme`, `SemanticTheme`
+
+## Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `theme` | `SemanticTheme` | `"info"` | `"info" \| "success" \| "warning" \| "error"` |
+| `dismissible` | `boolean` | `false` | Shows a close button. |
+| `useAutoFocus` | `boolean` | `false` | Focuses the prompt root element on mount. |
+| `masked` | `boolean` | `false` | SVG glass border — swaps `AlertContent` for `AlertMaskedContent`. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes on the inner wrapper. Supported modifier: `"outlined"`. |
+| `v-model` | `boolean` | `false` | Optional parent control — see dismiss behaviour below. |
+
+## Slots
+
+| Slot | Description |
+|---|---|
+| `#title` | **Required in practice.** Bold heading text. Always rendered (even when empty). |
+| `#content` | Body text below the title. The `<p>` element is omitted when this slot is empty. |
+| `#customDecoratorIcon` | Replaces the default theme icon. |
+| `#customCloseIcon` | Replaces the default × close icon inside the dismiss button. |
+| `#customTitle` | Screen-reader label for the dismiss button (default: `"Close this prompt"`). |
+
+## Themes
+
+| Theme | Default icon |
+|---|---|
+| `"info"` | `akar-icons:info` |
+| `"success"` | `akar-icons:check` |
+| `"warning"` | `akar-icons:circle-alert` |
+| `"error"` | `akar-icons:circle-alert` |
+
+`data-theme` is set on `.display-prompt-wrapper`, activating the CSS palette (`--theme-accent`,
+`--theme-text`, `--theme-border`, `--theme-ring`, etc.). The wrapper's left-edge accent uses
+`--theme-accent` (step 5/4) — not `--theme-surface` — so it stays visually distinct from buttons.
+
+## Dismiss behaviour
+
+Two modes depending on whether `v-model` is bound:
+
+| Scenario | What happens on close |
+|---|---|
+| No `v-model` (or `v-model="false"`) | Sets internal `componentOpen = false` → `.closed` class → collapses via CSS |
+| `v-model="true"` | Emits `update:modelValue = false`; internal state unchanged — parent controls visibility |
+
+The `.closed` class triggers a CSS grid row animation (`grid-template-rows: 1fr → 0fr`) with
+`opacity: 0` and `pointer-events: none`.
+
+## app.config defaults
+
+All props except `styleClassPassthrough` can be set globally so every prompt in the app inherits
+the same defaults without repeating them at each usage site.
+
+```ts
+// Consumer's app.config.ts
+export default defineAppConfig({
+  srcdev: {
+    displayPrompt: {
+      theme: "info",
+      dismissible: true,
+      masked: false,
+      useAutoFocus: false,
+    },
+  },
+})
+```
+
+Resolution chain: **explicit prop → app.config → hardcoded fallback**.
+
+## Basic usage
+
+```vue
+<DisplayPrompt theme="info">
+  <template #title>Your session will expire soon.</template>
+  <template #content>Save your work to avoid losing changes.</template>
+</DisplayPrompt>
+```
+
+## Dismissible prompt
+
+```vue
+<DisplayPrompt theme="warning" :dismissible="true">
+  <template #title>Action required</template>
+  <template #content>Please verify your email address.</template>
+</DisplayPrompt>
+```
+
+## Parent-controlled dismiss (v-model)
+
+Use when the parent needs to react to dismiss (e.g. save state, conditionally re-show):
+
+```vue
+<script setup lang="ts">
+const showPrompt = ref(true)
+</script>
+
+<template>
+  <DisplayPrompt
+    v-model="showPrompt"
+    theme="success"
+    :dismissible="true"
+  >
+    <template #title>Profile updated.</template>
+  </DisplayPrompt>
+</template>
+```
+
+## `styleClassPassthrough` modifiers
+
+| Class | Effect |
+|---|---|
+| `"outlined"` | Adds `1px solid var(--theme-border)` border to the wrapper |
+
+Apply via prop:
+
+```vue
+<DisplayPrompt :style-class-passthrough="['outlined']" theme="error">
+  <template #title>Something went wrong.</template>
+</DisplayPrompt>
+```
+
+## CSS token override
+
+Scope overrides using your page or section wrapper class — no `:deep()` needed:
+
+```css
+.my-section .display-prompt-wrapper {
+  --theme-accent: oklch(60% 0.18 140); /* left-edge accent strip */
+  border-radius: 0.8rem;
+}
+```
+
+## Masked variant
+
+Setting `:masked="true"` swaps `AlertContent` for `AlertMaskedContent`, giving the prompt an SVG-based
+border and a semi-transparent background so content behind it is faintly visible. The inner layout is
+identical — all the same slots apply. Place the prompt over a coloured or image background for the
+glass effect to be visible.
+
+```vue
+<DisplayPrompt theme="info" :masked="true">
+  <template #title>Glass prompt</template>
+  <template #content>Semi-transparent, backed by AlertMaskedContent.</template>
+</DisplayPrompt>
+```
+
+## Notes
+
+- `DisplayPromptTheme` is an alias for `SemanticTheme` (`"info" | "success" | "warning" | "error"`).
+- The root element always has `tabindex="0"` — it is focusable whether or not `dismissible` is set.
+- `useAutoFocus` focuses the root element on mount (useful when injecting a prompt in response to a
+  user action that has already moved focus elsewhere).
+- The `#title` slot renders unconditionally — an empty title `<p>` will still appear. Always
+  provide meaningful content in `#title`.

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

@@ -0,0 +1,235 @@
+# DisplayToast / DisplayToastProvider
+
+## Overview
+
+Two patterns are available depending on the use case:
+
+| Pattern | Component | When to use |
+|---|---|---|
+| **Standalone** | `DisplayToast` | One-off toast tied to a specific UI action; no queueing needed |
+| **App-wide queue** | `DisplayToastProvider` + `useToastQueue` | Multiple toasts across the app, stacking, queue management |
+
+**Locations**:
+
+- `app/components/01.atoms/toast/DisplayToast.vue`
+- `app/components/01.atoms/toast/DisplayToastProvider.vue`
+- `app/composables/useToastQueue.ts`
+- `app/components/01.atoms/toast/molecules/DefaultToastContent.vue`
+
+**Types**: `~/types/components` — `DisplayToastConfig`, `DisplayToastTheme`, `ToastQueueEntry`, `ToastQueueStatus`
+
+---
+
+## Pattern 1 — Standalone (`DisplayToast`)
+
+Triggered via `v-model`. Each instance manages its own visibility and position.
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `v-model` | `boolean` | `false` | `true` shows; `false` hides. |
+| `config` | `DisplayToastConfig` | see below | All sub-keys optional. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes on the root element. |
+
+### Config shape
+
+```ts
+interface DisplayToastConfig {
+  appearance?: {
+    theme?: SemanticTheme        // "info" | "success" | "warning" | "error" — default: "info"
+    position?: "top" | "bottom"  // default: "top"
+    alignment?: "left" | "center" | "right" // default: "right"
+    fullWidth?: boolean          // default: false — overrides alignment
+    masked?: boolean             // SVG glass border — semi-transparent background — default: false
+  }
+  behavior?: {
+    autoDismiss?: boolean        // default: true
+    duration?: number            // ms before auto-dismiss — default: 5000
+    revealDuration?: number      // animation duration ms — default: 550
+    returnFocusTo?: HTMLElement | ComponentPublicInstance | null
+  }
+  content?: {
+    text?: string                // simple message (used when no title/description)
+    title?: string               // bold title line
+    description?: string         // smaller description line
+    customIcon?: string          // icon name override (e.g. "akar-icons:check-box")
+  }
+}
+```
+
+### app.config defaults
+
+`appearance` and `behavior` keys (not `content` — that's per-instance) can be set globally so
+every toast in the app inherits the same defaults without repeating them in every `config` prop.
+
+```ts
+// Consumer's app.config.ts
+export default defineAppConfig({
+  srcdev: {
+    displayToast: {
+      appearance: { theme: "success", position: "bottom", alignment: "left" },
+      behavior: { autoDismiss: true, duration: 4000 },
+    },
+  },
+})
+```
+
+Resolution chain: **`config` prop → app.config → hardcoded fallback**.
+
+### Slots
+
+| Slot | Description |
+|---|---|
+| `default` | Replaces `DefaultToastContent` entirely. `has-theme`, `tabindex`, and `aria-describedby` are omitted — accessibility is the caller's responsibility. |
+| `#customToastIcon` | Replaces the default theme icon. |
+| `#title` | Replaces `config.content.title`. Do not provide both slot and config value. |
+| `#description` | Replaces `config.content.description`. Do not provide both slot and config value. |
+
+### Basic usage
+
+```vue
+<script setup lang="ts">
+const toastVisible = ref(false)
+</script>
+
+<template>
+  <button @click="toastVisible = true">Save</button>
+
+  <DisplayToast
+    v-model="toastVisible"
+    :config="{
+      appearance: { theme: 'success' },
+      behavior: { autoDismiss: true, duration: 4000 },
+      content: { text: 'Changes saved.' },
+    }"
+  />
+</template>
+```
+
+### Notes
+
+- `onBeforeRouteLeave` dismisses the toast on navigation. This emits a Vue Router warning in Vitest (no active route record) — harmless.
+- `returnFocusTo` accepts an `HTMLElement` or a component instance with `$el`.
+- The toast uses `<Teleport to="body">`. In tests, query `document.querySelector(".display-toast")` not `wrapper.find()`.
+
+---
+
+## Pattern 2 — App-wide queue (`DisplayToastProvider` + `useToastQueue`)
+
+Place `DisplayToastProvider` once in the app layout. Trigger toasts from anywhere using `useToastQueue`. The provider promotes pending entries to visible up to `maxVisible`, manages timers, and handles stacked FLIP animations.
+
+### Setup — layout
+
+```vue
+<!-- layouts/default.vue -->
+<template>
+  <div>
+    <slot />
+    <DisplayToastProvider position="top" alignment="right" :max-visible="1" />
+  </div>
+</template>
+```
+
+Only one `DisplayToastProvider` should be mounted at a time. It uses `<Teleport to="body">` so its placement in the layout tree does not affect visual output.
+
+### `DisplayToastProvider` props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `position` | `"top" \| "bottom"` | `"top"` | Vertical screen edge |
+| `alignment` | `"left" \| "center" \| "right"` | `"right"` | Horizontal alignment (ignored when `fullWidth`) |
+| `fullWidth` | `boolean` | `false` | Toast spans the full viewport width |
+| `maxVisible` | `number` | `1` | Max toasts visible simultaneously; rest queue as pending |
+
+### `useToastQueue` API
+
+```ts
+const { show, dismiss, clear, queue } = useToastQueue()
+```
+
+| Method | Signature | Notes |
+|---|---|---|
+| `show(config)` | `(config: DisplayToastConfig) => string` | Adds a toast to the queue; returns its ID |
+| `dismiss(id)` | `(id: string) => void` | Removes a specific toast by ID |
+| `clear()` | `() => void` | Flushes all pending and visible toasts |
+| `queue` | `Readonly<Ref<ToastQueueEntry[]>>` | Reactive read-only queue state |
+
+The composable uses a **module-level singleton** — state is shared across all callers without Pinia. Safe for client-only ephemeral UI state.
+
+> **Internal API**: `DisplayToastProvider` uses `useToastQueueProvider()` (a separate export from the same file) which additionally exposes `promote`. Do not call `useToastQueueProvider` from consuming app code — manually promoting without a timer puts the queue into an inconsistent state.
+
+### Triggering toasts
+
+```vue
+<script setup lang="ts">
+const { show } = useToastQueue()
+
+const onSave = async () => {
+  try {
+    await save()
+    show({
+      appearance: { theme: 'success' },
+      behavior: { autoDismiss: true, duration: 4000 },
+      content: { title: 'Saved', description: 'Your changes have been saved.' },
+    })
+  } catch {
+    show({
+      appearance: { theme: 'error' },
+      behavior: { autoDismiss: false },
+      content: { title: 'Save failed', description: 'Check your connection and try again.' },
+    })
+  }
+}
+</script>
+```
+
+### Stacking (`maxVisible > 1`)
+
+```vue
+<DisplayToastProvider :max-visible="3" position="top" alignment="right" />
+```
+
+With `maxVisible: 3` and 5 toasts triggered:
+
+- Toasts 1–3 are visible immediately
+- Toasts 4–5 queue as `pending`
+- When toast 1 is dismissed, toast 4 is promoted and animates in
+
+Stacked dismissals use a FLIP animation — remaining toasts slide smoothly to fill the gap rather than snapping.
+
+### Themes and ARIA
+
+| Theme | ARIA role | aria-live |
+|---|---|---|
+| `"info"` | `status` | `polite` |
+| `"success"` | `status` | `polite` |
+| `"warning"` | `alert` | `assertive` |
+| `"error"` | `alert` | `assertive` |
+
+### CSS / styling
+
+Override tokens via an unscoped style block scoped to a page or layout class:
+
+```css
+.my-page .display-toast-provider-item {
+  --theme-surface: oklch(15% 0 0);
+  --theme-text: oklch(95% 0 0);
+}
+```
+
+### Masked variant
+
+Setting `appearance.masked: true` swaps `AlertContent` for `AlertMaskedContent`, which uses an SVG-based border and a semi-transparent background (`rgba(0,0,0,0.3)`) so page content is faintly visible beneath the toast.
+
+The SVG border shape matches the standard toast exactly (8px left radius, 4px right, 6px accent-colour left bar via `--theme-accent`). Override any dimension or colour via a `maskConfig` prop if using `AlertMaskedContent` standalone.
+
+The inner content layout is handled by the shared `AlertContentInner` molecule — both variants reuse it. `AlertMaskedContent` overrides `--_alert-content-inner-bg: transparent` so the glass effect shows through.
+
+### Provider notes
+
+- `useToastQueue` state persists across route changes — no `onBeforeRouteLeave` cleanup needed.
+- `crypto.randomUUID()` generates toast IDs (`toast-<uuid>`). IDs are returned by `show()` for targeted `dismiss(id)` calls.
+- In tests, query via `document.querySelector(".display-toast-provider-item")` — the Teleport renders outside the component wrapper.
+- The progress bar (`.display-toast-provider-progress`) is only rendered when `autoDismiss: true`.
+- Dismissal can be triggered by: close button click, Escape key (when the toast item has focus), `dismiss(id)`, auto-dismiss timer, or `clear()`.

package/.claude/skills/index.md

@@ -27,8 +27,9 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── testing-add-unit-test.md    — create a Vitest unit test with snapshots
 ├── testing-add-playwright.md   — create a Playwright visual regression test
 ├── setup-postinstall.md             — automate nuxt prepare + Claude skills copy via postinstall so neither is forgotten after npm install
-├── theming-override-default.md      — replace the entire default theme with a custom colour scale (full palette swap)
-├── theming-partial-override.md      — override a specific token category (forms, buttons, colours) without a full theme replacement
+├── theming-colour-ramps.md          — parametric oklch ramp system: formula, named palettes, semantic slots, generator, consumer setup
+├── theming-override-default.md      — replace the entire default theme with a custom palette (set --theme-hue/--theme-chroma)
+├── theming-partial-override.md      — override a specific token category (palette, buttons, inputs) without a full theme replacement
 ├── 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
@@ -55,6 +56,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── composable-anchor-scroll.md       — useAnchorScroll: smooth anchor scrolling with reduced-motion support, dynamic offset, and TabNavigation integration
 ├── composable-tooltips-guide.md      — useTooltipsGuide: sequential popover guide with auto-start, dismiss-to-advance, manual controls
 └── components/
+    ├── alert-content-inner.md    — AlertContentInner: shared icon/body/dismiss molecule under AlertContent + AlertMaskedContent; app.config icon map (alertContent.icons + dismissIcon) covers all consumers
     ├── 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
@@ -90,7 +92,9 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── 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
     ├── 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-mixed.md — SamaritanPromptMixed: animated text prompt, typewriter/word-pulse effects, MessageConfig API, aria-live accessibility, 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
 ```
 
 ## Skill file template