srcdev-nuxt-components 9.1.51 → 9.1.53

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

@@ -37,6 +37,7 @@ describe("ComponentName", () => {
 
   afterEach(() => {
     wrapper?.unmount();
+    vi.restoreAllMocks(); // always restore vi.spyOn() stubs after each test
   });
 
   // -------------------------
@@ -162,7 +163,7 @@ it("exposes headingId via scoped slot", async () => {
 ## Key rules
 
 - Always `mountSuspended` — never `mount` or `shallowMount` from `@vue/test-utils` directly.
-- Always `afterEach(() => wrapper?.unmount())` to prevent test leaks.
+- Always call both `wrapper?.unmount()` and `vi.restoreAllMocks()` in `afterEach`. The unmount cleans up Vue; the restore cleans up any `vi.spyOn()` stubs so they don't leak into later test files.
 - Use a `createWrapper` helper to keep individual tests short.
 - Include at least one snapshot test per meaningful visual state.
 - `nextTick` is **not** auto-imported in test files — always import it explicitly: `import { nextTick } from "vue"`.
@@ -285,7 +286,9 @@ Import the child component directly in the test file — it is not auto-imported
 
 ## Mocking browser APIs
 
-Mock before the `describe` block if the component uses ResizeObserver, IntersectionObserver, etc.:
+### Global constructors (ResizeObserver, IntersectionObserver, etc.)
+
+Use `vi.stubGlobal` before the `describe` block. Do **not** call `vi.unstubAllGlobals()` in `afterEach` — it removes stubs from `vitest.setup.ts` (`$fetch`, etc.):
 
 ```ts
 const mockResizeObserver = vi.fn(() => ({
@@ -296,6 +299,41 @@ const mockResizeObserver = vi.fn(() => ({
 vi.stubGlobal("ResizeObserver", mockResizeObserver);
 ```
 
+### Prototype methods (Popover API, Canvas, etc.)
+
+When an API is missing from jsdom entirely (e.g. `hidePopover`, `showPopover`) use `Object.defineProperty` in `beforeEach`. **`vi.restoreAllMocks()` does not clean these up** — delete them explicitly in `afterEach`:
+
+```ts
+beforeEach(() => {
+  // vi.spyOn stubs are cleaned by vi.restoreAllMocks() in afterEach
+  vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue({} as never);
+
+  // Object.defineProperty stubs are NOT cleaned by vi.restoreAllMocks() —
+  // must be deleted explicitly to prevent leaking into other test files
+  Object.defineProperty(HTMLElement.prototype, "hidePopover", {
+    value: vi.fn(),
+    writable: true,
+    configurable: true,
+  });
+  Object.defineProperty(HTMLElement.prototype, "showPopover", {
+    value: vi.fn(),
+    writable: true,
+    configurable: true,
+  });
+});
+
+afterEach(() => {
+  wrapper?.unmount();
+  vi.restoreAllMocks(); // cleans up vi.spyOn stubs
+  // Remove Object.defineProperty prototype stubs — vi.restoreAllMocks() won't touch these
+  delete (HTMLElement.prototype as unknown as Record<string, unknown>)["hidePopover"];
+  delete (HTMLElement.prototype as unknown as Record<string, unknown>)["showPopover"];
+});
+```
+
+The `as unknown as Record<string, unknown>` double-cast is required because TypeScript's
+`HTMLElement` type has no index signature — cast through `unknown` first.
+
 ## Describe section conventions
 
 Use these section names consistently so tests are easy to scan:

package/.claude/skills/vercel-node-version.md

@@ -0,0 +1,48 @@
+# Vercel Node Version — .nvmrc Required
+
+## Overview
+
+Every project deploying to Vercel must have a `.nvmrc` file pinned to Node 24. Without it, Vercel defaults to Node 22 (npm 10), which crashes with `npm error Invalid Version:` on platform-specific optional packages that npm 11 (Node 24) handles gracefully.
+
+## The problem
+
+When `npm install` runs on macOS with Node 24, it writes stub entries into `package-lock.json` for platform-specific optional packages that don't apply to the current OS. For example:
+
+```json
+"node_modules/oxc-transform/node_modules/@oxc-transform/binding-linux-arm-gnueabihf": {
+  "optional": true
+}
+```
+
+This stub has no `version` field. npm 11 (Node 24) skips it silently. npm 10 (Node 22) calls `semver.valid()` on the empty version string and throws:
+
+```
+npm error Invalid Version:
+npm error A complete log of this run can be found in: ...
+Error: Command "npm install" exited with 1
+```
+
+The build fails even though the package is optional and not needed on Vercel's Linux x86_64 runtime.
+
+## Fix
+
+### 1. Add `.nvmrc` to the project root
+
+```
+24
+```
+
+Vercel reads `.nvmrc` and provisions Node 24 (npm 11), which handles the versionless stubs without error.
+
+### 2. Verify the file exists before every deployment
+
+If `.nvmrc` is ever accidentally deleted, recreate it immediately. This applies to:
+- `nuxt-components` (the layer)
+- Every consumer app (`instepreflexology`, `luxury-locs-by-natasha-nuxt3`, etc.)
+
+## Notes
+
+- The specific stub that first surfaced this was `@oxc-transform/binding-linux-arm-gnueabihf` — a Linux ARM native binary written as a versionless placeholder on macOS.
+- The build works locally on Node 24 regardless, so the failure is silent until Vercel runs.
+- Vercel also respects the `engines.node` field in `package.json`, but `.nvmrc` is simpler and doesn't require a valid semver range.
+- Do **not** attempt to fix by deleting stubs from `package-lock.json` alone — they reappear on the next `npm install`. The `.nvmrc` file is the durable fix.

package/README.md

@@ -104,15 +104,36 @@ When disabled, no `data-color-scheme` attribute is set on `<html>` and `useColou
 
 ---
 
-## Known Dev Server Warnings
+## Known Build / Production Issues
 
-### `[request error] [GET] http://localhost:3000/_nuxt/` (404)
+### `ERR_MODULE_NOT_FOUND: vue/index.mjs` — 500 on every request (Node 22)
 
-This error appears in the terminal when running `npm run dev` and is **harmless** — it does not affect dev server operation.
+**Symptom**: After `npm run build`, running `node .output/server/index.mjs` returns HTTP 500 on every page. The terminal shows:
 
-**Cause**: The Vue/Nuxt browser DevTools extension probes `/_nuxt/` to detect if the page is a Nuxt app. Since `/_nuxt/` is a directory (not a file), the server returns 404 and logs it.
+```text
+Error [ERR_MODULE_NOT_FOUND]: Cannot find module
+  '.output/server/node_modules/vue/index.mjs'
+Did you mean to import
+  '.output/server/node_modules/.nitro/vue@3.5.34/dist/vue.cjs.prod.js'?
+```
+
+**Root cause**: Nitro's dependency tracer externalises `vue` and copies it to `.output/server/node_modules/vue/`, but only traces the CJS build (`dist/vue.cjs.prod.js`). Vue's `package.json` exports map resolves the `"import"` + `"node"` condition (used by Node 22 when importing from an ES module) to `./index.mjs` — a file that was never copied. This is a Nitro tracing bug exposed by Node 22's stricter ESM condition matching, made more likely by `vue.runtimeCompiler: true` (which changes how Nuxt aliases Vue at build time, causing Nitro to fall back to externalising it as a node_modules package).
+
+**Fix** (already applied in this repo's `nuxt.config.ts`):
+
+```ts
+nitro: {
+  externals: {
+    inline: ["vue", "@vue/runtime-core", "@vue/runtime-dom", "@vue/reactivity", "@vue/shared", "@vue/server-renderer"],
+  },
+},
+```
+
+This tells Nitro to bundle these packages inline rather than externalise them, which sidesteps the runtime resolution entirely.
+
+**Consumer apps**: This config is not gated behind `isStandalone`, so it is inherited automatically by any app that extends this layer. No consumer-side action is required.
 
-**Resolution**: It cannot be suppressed without disabling the browser extension. Since the DevTools extension is useful for inspecting Pinia stores and component state, the recommended approach is to ignore this warning.
+**When it's safe to remove**: If a future Nitro release fixes the dependency tracer so that all export-condition files are copied correctly, the `inline` list can be removed. Verify by checking that `.output/server/node_modules/vue/index.mjs` exists after a clean build without the config.
 
 ---
 

package/app/components/01.atoms/page-row/PageRow.vue

@@ -48,7 +48,11 @@ const { headingId, ariaLabelledby } = useAriaLabelledById(props.tag);
 
     --full: minmax(var(--_minimum-content-padding), 1fr);
     --popout: minmax(0, calc((var(--_popout-max-width) - var(--_content-max-width)) * 0.5));
-    --content: minmax(0, calc((var(--_content-max-width) - var(--_inset-content-max-width)) * 0.5));
+    --content: clamp(
+      0px,
+      calc((100% - var(--_minimum-content-padding) * 2 - var(--_inset-content-max-width)) * 0.5),
+      calc((var(--_content-max-width) - var(--_inset-content-max-width)) * 0.5)
+    );
     --inset-content: min(var(--_inset-content-max-width), 100% - var(--_minimum-content-padding) * 2);
 
     display: grid;

package/app/components/02.molecules/action-menu/ActionMenu.vue

@@ -0,0 +1,218 @@
+<template>
+  <div class="action-menu" :class="[elementClasses]" :style="`--_anchor-name: ${anchorName}`">
+    <button
+      ref="triggerRef"
+      :popovertarget="menuId"
+      popovertargetaction="toggle"
+      type="button"
+      class="action-menu-trigger"
+      :aria-label="label"
+      aria-haspopup="menu"
+    >
+      <Icon name="lucide:ellipsis" class="action-menu-trigger-icon" aria-hidden="true" />
+    </button>
+
+    <div
+      :id="menuId"
+      ref="popoverRef"
+      popover
+      class="action-menu-popover"
+      @toggle="handleToggle"
+      @keydown="handleKeydown"
+    >
+      <ul class="action-menu-list" role="menu" :aria-label="label">
+        <li v-for="n in itemCount" :key="n - 1" class="action-menu-list-item" role="none" @click="closeMenu">
+          <slot :name="`item-${n - 1}`"></slot>
+        </li>
+      </ul>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  label?: string;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  label: "Open actions menu",
+  styleClassPassthrough: () => [],
+});
+
+const slots = useSlots();
+const itemCount = computed(() => Object.keys(slots).filter((name) => /^item-\d+$/.test(name)).length);
+
+const id = useId();
+const menuId = `action-menu-${id}`;
+const anchorName = `--action-menu-anchor-${id}`;
+
+const triggerRef = ref<HTMLButtonElement | null>(null);
+const popoverRef = ref<HTMLDivElement | null>(null);
+
+/** Returns all focusable menuitems in DOM order. */
+const getMenuItems = (): HTMLElement[] =>
+  Array.from(popoverRef.value?.querySelectorAll<HTMLElement>('[role="menuitem"]') ?? []);
+
+/**
+ * Close the menu and return focus to the trigger.
+ * Called on item click — Escape is handled natively by the Popover API
+ * (which also restores focus to the trigger automatically).
+ */
+const closeMenu = () => {
+  popoverRef.value?.hidePopover();
+  triggerRef.value?.focus();
+};
+
+const handleToggle = (event: Event) => {
+  const toggleEvent = event as ToggleEvent;
+  if (toggleEvent.newState === "open") {
+    getMenuItems()[0]?.focus();
+  }
+};
+
+/**
+ * Keyboard navigation following the WAI-ARIA menu pattern.
+ *
+ * ArrowDown / ArrowUp  — move between items (wraps around).
+ * Home / End           — jump to first / last item.
+ * Tab                  — close the menu; let the browser Tab naturally
+ *                        (do NOT focus the trigger — Tab should advance
+ *                        to the next element in the page).
+ * Escape               — handled natively by the Popover API.
+ */
+const handleKeydown = (event: KeyboardEvent) => {
+  const items = getMenuItems();
+  if (!items.length) return;
+
+  const currentIndex = items.indexOf(document.activeElement as HTMLElement);
+
+  switch (event.key) {
+    case "ArrowDown":
+      event.preventDefault();
+      items[currentIndex === -1 ? 0 : (currentIndex + 1) % items.length]?.focus();
+      break;
+    case "ArrowUp":
+      event.preventDefault();
+      items[currentIndex === -1 ? items.length - 1 : (currentIndex - 1 + items.length) % items.length]?.focus();
+      break;
+    case "Home":
+      event.preventDefault();
+      items[0]?.focus();
+      break;
+    case "End":
+      event.preventDefault();
+      items[items.length - 1]?.focus();
+      break;
+    case "Tab":
+      // Close without stealing focus — Tab exits to the next DOM element naturally.
+      popoverRef.value?.hidePopover();
+      break;
+  }
+};
+
+const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+</script>
+
+<style lang="css">
+@layer components {
+  .action-menu {
+    --_block-distance: var(--action-menu-block-distance, 0.4rem);
+    --_trigger-size: var(--action-menu-trigger-size, 3.2rem);
+    --_trigger-border-radius: var(--action-menu-trigger-border-radius, var(--button-border-radius-icon-only, 50%));
+    --_trigger-surface: var(--action-menu-trigger-surface, transparent);
+    --_trigger-surface-hover: var(--action-menu-trigger-surface-hover, var(--slate-01));
+    --_trigger-icon-size: var(--action-menu-trigger-icon-size, 2rem);
+    --_trigger-icon-color: var(--action-menu-trigger-icon-color, var(--slate-07));
+
+    --_popover-background: var(--action-menu-popover-background, var(--slate-00));
+    --_popover-border: var(--action-menu-popover-border, 0.1rem solid var(--slate-03));
+    --_popover-border-radius: var(--action-menu-popover-border-radius, 0.8rem);
+    --_popover-min-width: var(--action-menu-popover-min-width, 20rem);
+    --_popover-shadow: var(--action-menu-popover-shadow, 0 0.4rem 1.6rem rgba(0, 0, 0, 0.1));
+    --_popover-transition-duration: var(--action-menu-popover-transition-duration, 200ms);
+    --_item-divider: var(--action-menu-item-divider, 0.1rem solid var(--slate-02));
+
+    position: relative;
+    display: inline-block;
+
+    .action-menu-trigger {
+      all: unset;
+      cursor: pointer;
+      display: grid;
+      place-items: center;
+      width: var(--_trigger-size);
+      height: var(--_trigger-size);
+      border-radius: var(--_trigger-border-radius);
+      background-color: var(--_trigger-surface);
+      color: var(--_trigger-icon-color);
+      anchor-name: var(--_anchor-name);
+      transition: background-color var(--control-transition-duration, 200ms) var(--control-transition-ease, ease);
+
+      &:hover,
+      &:focus-visible {
+        background-color: var(--_trigger-surface-hover);
+      }
+
+      &:focus-visible {
+        outline: var(--button-outline-width, 0.2rem) solid var(--theme-button-primary-outline, currentcolor);
+        outline-offset: 0.2rem;
+      }
+
+      .action-menu-trigger-icon {
+        display: block;
+        width: var(--_trigger-icon-size);
+        height: var(--_trigger-icon-size);
+      }
+    }
+
+    .action-menu-popover {
+      border: var(--_popover-border);
+      margin: 0;
+      padding: 0;
+      inset: auto;
+      background-color: var(--_popover-background);
+      border-radius: var(--_popover-border-radius);
+      min-width: var(--_popover-min-width);
+      box-shadow: var(--_popover-shadow);
+      overflow: hidden;
+
+      position-anchor: var(--_anchor-name);
+      top: calc(anchor(bottom) + var(--_block-distance));
+      right: anchor(right);
+      left: auto;
+      position-try-fallbacks: flip-block;
+
+      opacity: 0;
+      display: none;
+      transition:
+        opacity var(--_popover-transition-duration),
+        display var(--_popover-transition-duration),
+        overlay var(--_popover-transition-duration);
+      transition-behavior: allow-discrete;
+
+      &:popover-open {
+        display: block;
+        opacity: 1;
+
+        @starting-style {
+          display: block;
+          opacity: 0;
+        }
+      }
+
+      .action-menu-list {
+        list-style: none;
+        padding: 0;
+        margin: 0;
+
+        .action-menu-list-item {
+          &:not(:last-child) {
+            border-bottom: var(--_item-divider);
+          }
+        }
+      }
+    }
+  }
+}
+</style>

package/app/components/02.molecules/action-menu/ActionMenuItemCore.vue

@@ -0,0 +1,123 @@
+<template>
+  <component
+    :is="tag"
+    :type="!isLink ? 'button' : undefined"
+    :href="isLink ? href : undefined"
+    class="action-menu-item-core"
+    :class="[elementClasses]"
+    role="menuitem"
+    @click="emit('click', $event)"
+  >
+    <span v-if="slots.icon" class="action-menu-item-icon" aria-hidden="true">
+      <slot name="icon"></slot>
+    </span>
+    <span class="action-menu-item-label">{{ label }}</span>
+    <span class="action-menu-item-arrow" aria-hidden="true">
+      <Icon name="lucide:arrow-right" class="action-menu-item-arrow-icon" />
+    </span>
+  </component>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  label: string;
+  href?: string;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  href: undefined,
+  styleClassPassthrough: () => [],
+});
+
+const emit = defineEmits<{
+  click: [event: MouseEvent];
+}>();
+
+const NuxtLink = resolveComponent("NuxtLink");
+const isLink = computed(() => Boolean(props.href));
+const isInternalLink = computed(() => isLink.value && props.href?.startsWith("/"));
+const tag = computed(() => {
+  if (isInternalLink.value) return NuxtLink;
+  if (isLink.value) return "a";
+  return "button";
+});
+
+const slots = useSlots();
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+</script>
+
+<style lang="css">
+@layer components {
+  .action-menu-item-core {
+    --_surface-hover: var(--action-menu-item-surface-hover, light-dark(var(--slate-01), var(--slate-09)));
+    --_text-color: var(--action-menu-item-text-color, light-dark(var(--slate-09), var(--slate-01)));
+    --_icon-size: var(--action-menu-item-icon-size, 2rem);
+    --_padding-inline: var(--action-menu-item-padding-inline, 1.6rem);
+    --_padding-block: var(--action-menu-item-padding-block, 1.2rem);
+
+    all: unset;
+    box-sizing: border-box;
+    cursor: pointer;
+    display: grid;
+    grid-template-columns: auto 1fr auto;
+    align-items: center;
+    gap: 1.2rem;
+    width: 100%;
+    padding-inline: var(--_padding-inline);
+    padding-block: var(--_padding-block);
+    color: var(--_text-color);
+    font-family: var(--font-family);
+    font-size: var(--button-font-size, 1.4rem);
+    font-weight: var(--button-font-weight, 500);
+    line-height: var(--button-line-height, 1.2);
+    transition: background-color var(--control-transition-duration, 200ms) var(--control-transition-ease, ease);
+    text-decoration: none;
+
+    &:hover,
+    &:focus-visible {
+      background-color: var(--_surface-hover);
+    }
+
+    &:focus-visible {
+      outline: var(--button-outline-width, 0.2rem) solid var(--theme-button-primary-outline, currentcolor);
+      outline-offset: -0.2rem;
+    }
+
+    .action-menu-item-icon {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      width: var(--_icon-size);
+      height: var(--_icon-size);
+      flex-shrink: 0;
+    }
+
+    .action-menu-item-label {
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+
+    .action-menu-item-arrow {
+      display: flex;
+      align-items: center;
+      flex-shrink: 0;
+      opacity: 0.5;
+
+      .action-menu-item-arrow-icon {
+        display: block;
+        width: 1.6rem;
+        height: 1.6rem;
+      }
+    }
+  }
+}
+</style>

package/app/components/02.molecules/action-menu/CONSUMER-STYLING.md

@@ -0,0 +1,125 @@
+# ActionMenu — Consumer Styling Guide
+
+## Public token API
+
+All `--action-menu-*` tokens are the stable override surface. Because action menus appear
+repeatedly across the UI (tables, cards, list rows) the recommended approach is to set tokens
+once in a **global CSS file** rather than per-instance via `styleClassPassthrough`.
+
+### Trigger button
+
+| Token | Default | Controls |
+|---|---|---|
+| `--action-menu-trigger-size` | `3.2rem` | Trigger button width and height |
+| `--action-menu-trigger-border-radius` | `var(--button-border-radius-icon-only, 50%)` | Trigger corner rounding |
+| `--action-menu-trigger-surface` | `transparent` | Trigger background (rest state) |
+| `--action-menu-trigger-surface-hover` | `light-dark(var(--slate-01), var(--slate-09))` | Trigger background on hover/focus |
+| `--action-menu-trigger-icon-size` | `2rem` | Ellipsis icon size |
+| `--action-menu-trigger-icon-color` | `light-dark(var(--slate-07), var(--slate-03))` | Ellipsis icon colour |
+
+### Menu popover
+
+| Token | Default | Controls |
+|---|---|---|
+| `--action-menu-block-distance` | `0.4rem` | Gap between trigger bottom and menu top |
+| `--action-menu-popover-background` | `light-dark(var(--slate-00), var(--slate-10))` | Menu panel background |
+| `--action-menu-popover-border` | `0.1rem solid light-dark(var(--slate-03), var(--slate-07))` | Menu panel border shorthand |
+| `--action-menu-popover-border-radius` | `0.8rem` | Menu panel corner rounding |
+| `--action-menu-popover-min-width` | `20rem` | Minimum menu width |
+| `--action-menu-popover-shadow` | `0 0.4rem 1.6rem light-dark(rgba(0,0,0,0.1), rgba(0,0,0,0.4))` | Menu panel drop shadow |
+| `--action-menu-popover-transition-duration` | `200ms` | Open/close fade duration |
+
+### Menu items (`ActionMenuItemCore`)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--action-menu-item-divider` | `0.1rem solid light-dark(var(--slate-02), var(--slate-08))` | Divider line between items |
+| `--action-menu-item-surface-hover` | `light-dark(var(--slate-01), var(--slate-09))` | Item row background on hover/focus |
+| `--action-menu-item-text-color` | `light-dark(var(--slate-09), var(--slate-01))` | Item label and icon colour |
+| `--action-menu-item-icon-size` | `2rem` | Left icon container size |
+| `--action-menu-item-padding-inline` | `1.6rem` | Item horizontal padding |
+| `--action-menu-item-padding-block` | `1.2rem` | Item vertical padding |
+
+---
+
+## Global theming — recommended approach
+
+Create `assets/styles/setup/07.components/action-menu.css` in the consuming app and set tokens
+on `:root`. This applies to every `ActionMenu` across the site.
+
+```css
+/* assets/styles/setup/07.components/action-menu.css */
+:root {
+  --action-menu-trigger-border-radius: 0.4rem;
+  --action-menu-trigger-surface-hover: var(--brand-surface-subtle);
+  --action-menu-trigger-icon-color: var(--brand-text-muted);
+
+  --action-menu-popover-background: var(--brand-surface);
+  --action-menu-popover-border: 0.1rem solid var(--brand-border);
+  --action-menu-popover-border-radius: 0.6rem;
+  --action-menu-popover-shadow: 0 0.8rem 2.4rem rgba(0, 0, 0, 0.15);
+
+  --action-menu-item-surface-hover: var(--brand-surface-subtle);
+  --action-menu-item-text-color: var(--brand-text);
+  --action-menu-item-divider: 0.1rem solid var(--brand-border);
+  --action-menu-block-distance: 0.6rem;
+}
+```
+
+---
+
+## Page-scoped overrides
+
+Override tokens for a specific section by scoping them under the page or layout wrapper.
+No `:deep()` is required (component styles are unscoped).
+
+```css
+/* In the consuming page's unscoped <style> block */
+.admin-table {
+  .action-menu {
+    --action-menu-trigger-size: 2.8rem;
+    --action-menu-trigger-icon-size: 1.6rem;
+    --action-menu-popover-min-width: 16rem;
+    --action-menu-item-padding-block: 0.8rem;
+  }
+}
+```
+
+---
+
+## Per-instance overrides via styleClassPassthrough
+
+Use sparingly — prefer global or page-scoped CSS. When a single instance needs a distinct
+visual style, pass a modifier class:
+
+```vue
+<ActionMenu
+  :style-class-passthrough="['danger-actions']"
+>
+  ...
+</ActionMenu>
+```
+
+```css
+.action-menu.danger-actions {
+  --action-menu-trigger-icon-color: var(--color-danger);
+  --action-menu-trigger-surface-hover: light-dark(var(--red-01), var(--red-09));
+  --action-menu-item-surface-hover: light-dark(var(--red-01), var(--red-09));
+  --action-menu-item-text-color: light-dark(var(--red-09), var(--red-01));
+  --action-menu-item-divider: 0.1rem solid light-dark(var(--red-02), var(--red-08));
+}
+```
+
+---
+
+## Notes
+
+- `--action-menu-block-distance` accepts any valid `<length>`. Negative values will cause the
+  menu to overlap the trigger.
+- The menu opens **below** the trigger and right-aligns with it by default. It flips above
+  when near the bottom of the viewport (`position-try-fallbacks: flip-block`).
+- `--action-menu-popover-min-width` sets the floor — long labels will naturally expand the
+  menu wider. Set `width: max-content` on `.action-menu-popover` in a consumer override if
+  you want to suppress that.
+- The `--action-menu-item-*` tokens resolve on `.action-menu-item-core` elements, so they
+  take effect even when items are used in other contexts.