srcdev-nuxt-components 9.4.11 → 9.5.0

package/app/components/02.molecules/alert-content/CONSUMER-STYLING.md

@@ -0,0 +1,84 @@
+# AlertContent — Consumer Styling Guide
+
+Covers `AlertContent` and its inner `AlertContentInner`. The inner tokens also apply inside
+`AlertMaskedContent`, which has its own guide for its outer shape.
+
+## Public token API
+
+### Outer shape (`.alert-content`)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--alert-content-accent` | `var(--theme-accent)` | Accent stripe colour (the root's background, showing at the left edge) |
+| `--alert-content-accent-width` | `0.6rem` | Accent stripe width |
+| `--alert-content-border` | `0.1rem solid var(--theme-border)` | Border (shorthand) |
+| `--alert-content-border-radius-start` | `0.8rem` | Left-hand corner radii (also rounds the inner panel) |
+| `--alert-content-border-radius-end` | `0.4rem` | Right-hand corner radii |
+
+### Inside (`.alert-content-inner`)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--alert-content-inner-background` | `var(--theme-surface-subtle)` | Panel background |
+| `--alert-content-text-colour` | `var(--theme-text)` | Text colour (icon, title, message and dismiss inherit it) |
+| `--alert-content-padding` | `1.2rem 1.5rem` | Panel padding |
+| `--alert-content-gap` | `1.2rem` | Gap between icon, message column and dismiss button |
+| `--alert-content-icon-colour` | `currentColor` | Theme icon colour |
+| `--alert-content-icon-size` | `2.5rem` | Theme icon size (`font-size`) |
+| `--alert-content-body-gap` | `0.4rem` | Gap between title and message |
+| `--alert-content-title-font-size` | `var(--step-4)` | Title size |
+| `--alert-content-text-font-size` | `var(--step-3)` | Message size |
+| `--alert-content-actions-spacing` | `1.2rem` | Space between the message and the actions row |
+| `--alert-content-actions-gap` | `0.8rem` | Gap between action controls |
+| `--alert-content-actions-justify` | `flex-end` | Horizontal alignment of the actions row (`justify-content`) |
+
+### Dismiss button
+
+| Token | Default | Controls |
+|---|---|---|
+| `--alert-content-dismiss-border-colour` | `var(--theme-border)` | Button border |
+| `--alert-content-dismiss-icon-size` | `1.5rem` | Close icon size |
+| `--alert-content-dismiss-background-hover` | `var(--theme-surface-hover)` | Background on hover/focus |
+| `--alert-content-dismiss-colour-hover` | `var(--theme-on-surface)` | Icon colour on hover/focus |
+| `--alert-content-dismiss-ring` | `var(--theme-ring)` | Focus/hover outline colour |
+
+> **Changed 2026-09-27**: every value above except `--alert-content-inner-background` was hardcoded
+> (or read a `--theme-*` token directly, CLAUDE.md pitfall #14). Defaults are unchanged apart from
+> the px radii and stripe width, which are now the same sizes in rem. The icon and dismiss colours now
+> inherit the text colour (still `--theme-text` by default) so one token recolours all of it.
+
+Private tokens (not public API): `--_radius-start`/`--_radius-end` on `.alert-content`, resolving the
+radius tokens once for the four corners.
+
+## State hooks
+
+- `data-theme` on `.alert-content`, from the required `theme` prop. It sets the `--theme-*` tokens
+  that every default above reads, so it drives all the colours, in light and dark mode.
+- Classes: `.alert-content` > `.alert-content-inner` > `.alert-content-icon` (when `showIcon`),
+  `.alert-content-main` > (`.alert-content-body` > `.alert-content-title`, `.alert-content-text`) +
+  `.alert-content-actions` (when the `#actions` slot is used), then `.alert-content-dismiss`
+  (when `dismissible`).
+- `data-test-id`: `alert-icon`, `alert-title`, `alert-content`, `alert-actions`, `alert-dismiss`.
+
+> **Changed 2026-09-27**: `.title`/`.content` renamed to `.alert-content-title`/`.alert-content-text`
+> (generic names collide with site CSS when the alert renders inline). The body and new actions row
+> are wrapped in `.alert-content-main`.
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a plain `class` on the
+component, which falls through to the root `.alert-content`): they inherit down into the component.
+Keep the block **unlayered** (no `@layer` wrapper) so it beats the library's `@layer components`. If
+your own file uses `<style scoped>`, tokens set on your element still work, but selectors that reach
+inside the component need `:deep()`. Patterns and examples:
+`.claude/skills/component-local-style-override.md`.
+
+**Caveat:** `.alert-content` sets `data-theme` on itself, so `--theme-*` values set on an ancestor
+don't reach it: the alert always uses its own `theme` prop's palette. Override the `--alert-content-*`
+tokens instead. When it's rendered by `DisplayToast`/`DisplayToastProvider` it's teleported to
+`<body>`, so set tokens globally or through the toast's own hooks rather than on a page wrapper.
+
+## Class passthrough
+
+No `style-class-passthrough` prop. A plain `class` attribute falls through to the root `.alert-content`
+(`AlertContent` has a single root), which is enough for setting tokens on one instance.

package/app/components/02.molecules/alert-content/stories/AlertContent.stories.ts

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from "@nuxtjs/storybook";
 import AlertContent from "../AlertContent.vue";
+import InputButton from "../../../05.forms/input-button/InputButton.vue";
 
 const meta: Meta<typeof AlertContent> = {
   title: "Molecules/AlertContent",
@@ -16,6 +17,11 @@ const meta: Meta<typeof AlertContent> = {
       description: "Iconify icon name to override the default theme icon",
       table: { category: "Appearance" },
     },
+    showIcon: {
+      control: "boolean",
+      description: "Render the theme icon column",
+      table: { category: "Appearance" },
+    },
     dismissible: {
       control: "boolean",
       description: "Show a close button (emits 'dismiss' on click)",
@@ -26,6 +32,7 @@ const meta: Meta<typeof AlertContent> = {
   },
   args: {
     theme: "info",
+    showIcon: true,
     dismissible: false,
   },
 };
@@ -129,3 +136,35 @@ export const AllThemes: Story = {
     `,
   }),
 };
+
+/** Actions — a row of buttons under the message, e.g. for a consent or confirm prompt. */
+export const WithActions: Story = {
+  name: "With Actions",
+  args: { theme: "info", customIcon: "material-symbols:cookie-outline" },
+  render: (args) => ({
+    components: { AlertContent, InputButton },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div :data-theme="args.theme" style="max-width: 600px; padding: 2rem;">
+        <AlertContent v-bind="args">
+          <template #title>Cookies</template>
+          <template #content>This site uses cookies to understand how it's used. You can accept or reject them.</template>
+          <template #actions>
+            <InputButton type="button" variant="tertiary" button-text="Reject" />
+            <InputButton type="button" variant="primary" button-text="Accept" />
+          </template>
+        </AlertContent>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The #actions slot renders a wrapping row under the message, outside the aria-live/contentId body so the buttons aren't announced or pulled into aria-describedby. Actions are right-aligned by default (--alert-content-actions-justify). The cookie icon comes from customIcon; set showIcon to false to drop the icon column.",
+      },
+    },
+  },
+};

package/app/components/02.molecules/alert-content/tests/AlertContent.spec.ts

@@ -132,4 +132,36 @@ describe("AlertContent", () => {
     });
     expect(wrapper.find(".sr-only").text()).toBe("Close");
   });
+
+  // ─── showIcon / actions (added 2026-09-27) ──────────────────────────────────
+
+  it("omits the icon region when showIcon is false", async () => {
+    const wrapper = await mountSuspended(AlertContent, { props: { theme: "info", showIcon: false } });
+    expect(wrapper.find("[data-test-id='alert-icon']").exists()).toBe(false);
+  });
+
+  it("renders the #actions slot in its own row, outside the live/described body", async () => {
+    const wrapper = await mountSuspended(AlertContent, {
+      props: { theme: "info", contentId: "msg-1", ariaLive: "polite" },
+      slots: { content: "Body", actions: '<button type="button" class="act">Do it</button>' },
+    });
+    const actions = wrapper.find("[data-test-id='alert-actions']");
+    expect(actions.exists()).toBe(true);
+    expect(actions.find(".act").exists()).toBe(true);
+    expect(wrapper.find(".alert-content-body").find(".act").exists()).toBe(false);
+  });
+
+  it("does not render the actions row without the #actions slot", async () => {
+    const wrapper = await mountSuspended(AlertContent, { props: { theme: "info" }, slots: { content: "Body" } });
+    expect(wrapper.find("[data-test-id='alert-actions']").exists()).toBe(false);
+  });
+
+  it("uses component-prefixed classes for the title and text", async () => {
+    const wrapper = await mountSuspended(AlertContent, {
+      props: { theme: "info" },
+      slots: { title: "T", content: "C" },
+    });
+    expect(wrapper.find(".alert-content-title").exists()).toBe(true);
+    expect(wrapper.find(".alert-content-text").exists()).toBe(true);
+  });
 });

package/app/components/02.molecules/alert-content/tests/AlertContentInner.spec.ts

@@ -132,4 +132,36 @@ describe("AlertContentInner", () => {
     });
     expect(wrapper.find(".sr-only").text()).toBe("Close");
   });
+
+  // ─── showIcon / actions (added 2026-09-27) ──────────────────────────────────
+
+  it("omits the icon region when showIcon is false", async () => {
+    const wrapper = await mountSuspended(AlertContentInner, { props: { theme: "info", showIcon: false } });
+    expect(wrapper.find("[data-test-id='alert-icon']").exists()).toBe(false);
+  });
+
+  it("renders the #actions slot in its own row, outside the live/described body", async () => {
+    const wrapper = await mountSuspended(AlertContentInner, {
+      props: { theme: "info", contentId: "msg-1", ariaLive: "polite" },
+      slots: { content: "Body", actions: '<button type="button" class="act">Do it</button>' },
+    });
+    const actions = wrapper.find("[data-test-id='alert-actions']");
+    expect(actions.exists()).toBe(true);
+    expect(actions.find(".act").exists()).toBe(true);
+    expect(wrapper.find(".alert-content-body").find(".act").exists()).toBe(false);
+  });
+
+  it("does not render the actions row without the #actions slot", async () => {
+    const wrapper = await mountSuspended(AlertContentInner, { props: { theme: "info" }, slots: { content: "Body" } });
+    expect(wrapper.find("[data-test-id='alert-actions']").exists()).toBe(false);
+  });
+
+  it("uses component-prefixed classes for the title and text", async () => {
+    const wrapper = await mountSuspended(AlertContentInner, {
+      props: { theme: "info" },
+      slots: { title: "T", content: "C" },
+    });
+    expect(wrapper.find(".alert-content-title").exists()).toBe(true);
+    expect(wrapper.find(".alert-content-text").exists()).toBe(true);
+  });
 });

package/app/components/02.molecules/alert-masked-content/AlertMaskedContent.vue

@@ -4,6 +4,7 @@
       <AlertContentInner
         :theme="theme"
         :custom-icon="customIcon"
+        :show-icon="showIcon"
         :dismissible="dismissible"
         :content-id="contentId"
         :aria-live="ariaLive"
@@ -18,6 +19,9 @@
         <template v-if="slots.content" #content>
           <slot name="content"></slot>
         </template>
+        <template v-if="slots.actions" #actions>
+          <slot name="actions"></slot>
+        </template>
         <template v-if="slots.dismissIcon" #dismissIcon>
           <slot name="dismissIcon"></slot>
         </template>
@@ -35,6 +39,7 @@ import type { SemanticTheme, AlertMaskConfig } from "~/types/components";
 interface Props {
   theme: SemanticTheme;
   customIcon?: string;
+  showIcon?: boolean;
   dismissible?: boolean;
   contentId?: string;
   ariaLive?: "polite" | "assertive" | "off";
@@ -43,6 +48,7 @@ interface Props {
 
 const props = withDefaults(defineProps<Props>(), {
   customIcon: undefined,
+  showIcon: true,
   dismissible: false,
   contentId: undefined,
   ariaLive: undefined,
@@ -55,8 +61,8 @@ const slots = useSlots();
 
 // Shape matches AlertContent: 8px left radius, 4px right, 6px accent bar on left, 1px border elsewhere
 const resolvedMaskConfig = computed<AlertMaskConfig>(() => ({
-  borderColour: "var(--theme-accent)",
-  backgroundColour: "rgba(0, 0, 0, 0.3)",
+  borderColour: "var(--alert-masked-content-border-colour, var(--theme-accent))",
+  backgroundColour: "var(--alert-masked-content-background, color-mix(in oklab, var(--theme-surface-subtle) 80%, transparent))",
   radiusLeft: 8,
   radiusRight: 4,
   borderLeft: 6,
@@ -70,9 +76,7 @@ const resolvedMaskConfig = computed<AlertMaskConfig>(() => ({
 <style lang="css">
 @layer components {
   .alert-masked-content {
-    .alert-content-inner {
-      --_alert-content-inner-bg: transparent;
-    }
+    --alert-content-inner-background: transparent;
   }
 }
 </style>

package/app/components/02.molecules/alert-masked-content/CONSUMER-STYLING.md

@@ -0,0 +1,73 @@
+# AlertMaskedContent — Consumer Styling Guide
+
+`AlertMaskedContent` is `AlertContentInner` (icon, title, body, dismiss button) wrapped in
+`AlertMaskCore`'s SVG mask: an accent-coloured border drawn as a cut-out, and a translucent fill,
+so whatever sits behind the alert stays visible. It's the variant `DisplayToast`
+(`appearance.masked`) and `DisplayPrompt` (`masked`) swap in.
+
+## Public token API
+
+### Mask colours
+
+| Token | Default | Controls |
+|---|---|---|
+| `--alert-masked-content-border-colour` | `var(--theme-accent)` | Border colour (6px accent bar on the left, 1px elsewhere). |
+| `--alert-masked-content-background` | `color-mix(in oklab, var(--theme-surface-subtle) 80%, transparent)` | Translucent fill behind the content: the theme's own surface colour at 80%, so text contrast matches `AlertContent` in light and dark mode. |
+
+These reach the SVG as `fill` styles, so they resolve like any inherited custom property. A
+`maskConfig.borderColour` / `maskConfig.backgroundColour` prop value replaces the token entirely
+for that instance.
+
+### Mask geometry
+
+Radius and border thickness aren't tokens: `AlertMaskCore` computes the SVG path from them in JS.
+Set them with the `maskConfig` prop (`AlertMaskConfig`). Defaults: `radiusLeft: 8`,
+`radiusRight: 4`, `borderLeft: 6`, `borderTop`/`borderRight`/`borderBottom: 1`.
+
+### Content
+
+Icon, text and dismiss button styling come from `AlertContentInner` and follow the `data-theme`
+set on the root (`--theme-text`, `--theme-border`, etc.).
+
+### Private tokens
+
+None of its own. `AlertMaskCore`'s `--_height` / `--_inset-*` are measured plumbing, not public API.
+
+## State hooks
+
+- `data-theme="info" | "success" | "warning" | "error"` on the root `.alert-masked-content`,
+  from the `theme` prop. Drives `--theme-accent` and the content colours.
+- Inner classes: `.alert-mask-core` > `.alert-mask-decorator` (the SVG) + `.alert-mask-content` >
+  `.alert-content-inner` > `.alert-content-icon`, `.alert-content-main` > (`.alert-content-body` >
+  `.alert-content-title`, `.alert-content-text`) + `.alert-content-actions`, then `.alert-content-dismiss`.
+  The inner content tokens (`--alert-content-gap`, `-padding`, `-text-colour`, `-icon-size`, `-title-font-size`,
+  `-actions-gap`, the dismiss-button tokens, ...) apply here too; see `AlertContent`'s CONSUMER-STYLING.md.
+  Its outer-shape tokens (`--alert-content-accent`, `-border`, `-border-radius-*`, `-accent-width`) don't:
+  the masked shape comes from `maskConfig`.
+
+> **Changed 2026-09-27**: `.title`/`.content` renamed to `.alert-content-title`/`.alert-content-text`,
+> and body + actions now sit in `.alert-content-main`.
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a plain `class` on
+`<AlertMaskedContent>`, which falls through to the root since there's no passthrough prop): they
+inherit down into the component. Keep the block **unlayered** (no `@layer` wrapper) so it beats the
+library's `@layer components`. If your own file uses `<style scoped>`, tokens set on your element
+still work, but selectors that reach inside the component need `:deep()`. Patterns and examples:
+`.claude/skills/component-local-style-override.md`.
+
+**Caveat:** the root sets `--alert-content-inner-background: transparent` on itself, so an
+ancestor value of that token never reaches the masked variant. That's deliberate: an opaque inner
+background would hide the mask. Change the fill with `--alert-masked-content-background` instead.
+
+## Class passthrough
+
+There's no `styleClassPassthrough` prop. A plain `class` attribute falls through to the root
+`.alert-masked-content` element.
+
+## Notes
+
+- The default fill is the theme's own surface (`--theme-surface-subtle`) at 80%, matching the
+  surface `--theme-text` is designed for, so contrast holds in light and dark mode. Lowering the
+  percentage shows more backdrop but costs contrast; check it over your real imagery.

package/app/components/02.molecules/alert-masked-content/stories/AlertMaskedContent.stories.ts

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from "@nuxtjs/storybook";
 import AlertMaskedContent from "../AlertMaskedContent.vue";
+import AlertContent from "../../alert-content/AlertContent.vue";
 
 const meta: Meta<typeof AlertMaskedContent> = {
   title: "Molecules/AlertMaskedContent",
@@ -34,22 +35,18 @@ const meta: Meta<typeof AlertMaskedContent> = {
 export default meta;
 type Story = StoryObj<typeof AlertMaskedContent>;
 
-const wrapperStyle = `
-  max-width: 600px;
-  padding: 2rem;
-  background: linear-gradient(135deg, oklch(40% 0.15 250), oklch(25% 0.1 300));
-  border-radius: 8px;
-`;
+const wrapperStyle =
+  "max-width: 600px; padding: 2rem; background: linear-gradient(135deg, oklch(40% 0.15 250), oklch(25% 0.1 300)); border-radius: 8px;";
 
 /** Default — info theme over a coloured background to show the glass effect. */
 export const Default: Story = {
   render: (args) => ({
     components: { AlertMaskedContent },
     setup() {
-      return { args };
+      return { args, wrapperStyle };
     },
     template: `
-      <div :data-theme="args.theme" :style="'${wrapperStyle}'">
+      <div :data-theme="args.theme" :style="wrapperStyle">
         <AlertMaskedContent v-bind="args">
           <template #title>Alert title</template>
           <template #content>This is the alert body. It describes what happened and what the user should do next.</template>
@@ -65,10 +62,10 @@ export const Dismissible: Story = {
   render: (args) => ({
     components: { AlertMaskedContent },
     setup() {
-      return { args };
+      return { args, wrapperStyle };
     },
     template: `
-      <div :data-theme="args.theme" :style="'${wrapperStyle}'">
+      <div :data-theme="args.theme" :style="wrapperStyle">
         <AlertMaskedContent v-bind="args">
           <template #title>Dismissible alert</template>
           <template #content>Click the close button to emit the dismiss event.</template>
@@ -130,3 +127,87 @@ export const BackgroundVariants: Story = {
     `,
   }),
 };
+
+const busyBackdrop = [
+  "repeating-linear-gradient(45deg, oklch(100% 0 0 / 0.18) 0 1.2rem, transparent 1.2rem 2.4rem)",
+  "linear-gradient(120deg, oklch(70% 0.2 30), oklch(75% 0.18 90) 35%, oklch(65% 0.2 200) 70%, oklch(55% 0.22 300))",
+].join(", ");
+
+/**
+ * Over imagery — the mask only reads as a mask with something busy behind it. Each row pairs
+ * the plain AlertContent (opaque surface) with AlertMaskedContent over the same backdrop, so the
+ * translucent fill and the cut-out accent border are directly comparable.
+ */
+export const OverImagery: Story = {
+  name: "Over Imagery (mask in action)",
+  args: { theme: "info", dismissible: true },
+  render: (args) => ({
+    components: { AlertMaskedContent, AlertContent },
+    setup() {
+      const backdrops = [
+        { label: "Photo", style: "background: url('/images/banners/video/lake-banner.jpg') center / cover;" },
+        { label: "Photo", style: "background: url('/images/page/hero/hero-blonde.jpg') center 30% / cover;" },
+        { label: "Striped gradient", style: `background: ${busyBackdrop};` },
+      ];
+      return { args, backdrops };
+    },
+    template: `
+      <div style="display: grid; gap: 2.4rem; max-width: 110rem;">
+        <p style="margin: 0; font-family: sans-serif; font-size: 1.4rem; max-width: 70ch;">
+          Left: <strong>AlertContent</strong> (opaque surface). Right: <strong>AlertMaskedContent</strong>:
+          the SVG mask draws only the accent border and a translucent fill, so the backdrop stays visible
+          through the body and around the border's cut-out.
+        </p>
+        <div
+          v-for="(backdrop, i) in backdrops"
+          :key="i"
+          :data-theme="args.theme"
+          :style="backdrop.style + ' display: grid; grid-template-columns: repeat(auto-fit, minmax(32rem, 1fr)); gap: 2.4rem; padding: 4rem 2.4rem; border-radius: 1.2rem;'"
+        >
+          <AlertContent v-bind="args">
+            <template #title>AlertContent ({{ backdrop.label }})</template>
+            <template #content>Opaque surface: nothing behind it shows through.</template>
+          </AlertContent>
+          <AlertMaskedContent v-bind="args">
+            <template #title>AlertMaskedContent ({{ backdrop.label }})</template>
+            <template #content>Translucent fill and cut-out border: the backdrop shows through.</template>
+          </AlertMaskedContent>
+        </div>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Photos and a striped gradient behind each pair. Compare the opaque AlertContent on the left with the masked variant on the right.",
+      },
+    },
+  },
+};
+
+/** Token overrides — the public colour tokens set on a wrapper you own, over the same busy backdrop. */
+export const TokenOverrides: Story = {
+  name: "Token Overrides",
+  args: { theme: "warning", dismissible: false },
+  render: (args) => ({
+    components: { AlertMaskedContent },
+    setup() {
+      return { args, busyBackdrop };
+    },
+    template: `
+      <div :data-theme="args.theme" :style="'background: ' + busyBackdrop + '; padding: 4rem 2.4rem; border-radius: 1.2rem; display: grid; gap: 2.4rem; max-width: 60rem;'">
+        <AlertMaskedContent v-bind="args">
+          <template #title>Default tokens</template>
+          <template #content>--theme-accent border, --theme-surface-subtle fill at 80%.</template>
+        </AlertMaskedContent>
+        <div style="--alert-masked-content-border-colour: white; --alert-masked-content-background: color-mix(in oklab, var(--theme-surface-subtle) 55%, transparent);">
+          <AlertMaskedContent v-bind="args">
+            <template #title>Overridden tokens</template>
+            <template #content>White border, fill dropped to 55% so more of the backdrop shows (at some cost to contrast).</template>
+          </AlertMaskedContent>
+        </div>
+      </div>
+    `,
+  }),
+};

package/app/components/02.molecules/alert-masked-content/tests/AlertMaskedContent.spec.ts

@@ -142,6 +142,26 @@ describe("AlertMaskedContent", () => {
     expect(style.getPropertyValue("--_inset-block-end")).toBe("1px");
   });
 
+  it("routes the default mask colours through public tokens", async () => {
+    const wrapper = await mountSuspended(AlertMaskedContent, { props: { theme: "info" } });
+    const paths = wrapper.findAll(".alert-mask-decorator > path");
+    expect((paths[0]!.element as unknown as SVGElement).style.fill).toBe(
+      "var(--alert-masked-content-border-colour, var(--theme-accent))"
+    );
+    expect((paths[1]!.element as unknown as SVGElement).style.fill).toBe(
+      "var(--alert-masked-content-background, color-mix(in oklab, var(--theme-surface-subtle) 80%, transparent))"
+    );
+  });
+
+  it("lets maskConfig colours replace the token defaults", async () => {
+    const wrapper = await mountSuspended(AlertMaskedContent, {
+      props: { theme: "info", maskConfig: { borderColour: "red", backgroundColour: "blue" } },
+    });
+    const paths = wrapper.findAll(".alert-mask-decorator > path");
+    expect((paths[0]!.element as unknown as SVGElement).style.fill).toBe("red");
+    expect((paths[1]!.element as unknown as SVGElement).style.fill).toBe("blue");
+  });
+
   it("merges custom maskConfig over defaults", async () => {
     const wrapper = await mountSuspended(AlertMaskedContent, {
       props: { theme: "info", maskConfig: { borderLeft: 12 } },
@@ -150,4 +170,36 @@ describe("AlertMaskedContent", () => {
     const style = (contentEl.element as HTMLElement).style;
     expect(style.getPropertyValue("--_inset-inline-start")).toBe("12px");
   });
+
+  // ─── showIcon / actions (added 2026-09-27) ──────────────────────────────────
+
+  it("omits the icon region when showIcon is false", async () => {
+    const wrapper = await mountSuspended(AlertMaskedContent, { props: { theme: "info", showIcon: false } });
+    expect(wrapper.find("[data-test-id='alert-icon']").exists()).toBe(false);
+  });
+
+  it("renders the #actions slot in its own row, outside the live/described body", async () => {
+    const wrapper = await mountSuspended(AlertMaskedContent, {
+      props: { theme: "info", contentId: "msg-1", ariaLive: "polite" },
+      slots: { content: "Body", actions: '<button type="button" class="act">Do it</button>' },
+    });
+    const actions = wrapper.find("[data-test-id='alert-actions']");
+    expect(actions.exists()).toBe(true);
+    expect(actions.find(".act").exists()).toBe(true);
+    expect(wrapper.find(".alert-content-body").find(".act").exists()).toBe(false);
+  });
+
+  it("does not render the actions row without the #actions slot", async () => {
+    const wrapper = await mountSuspended(AlertMaskedContent, { props: { theme: "info" }, slots: { content: "Body" } });
+    expect(wrapper.find("[data-test-id='alert-actions']").exists()).toBe(false);
+  });
+
+  it("uses component-prefixed classes for the title and text", async () => {
+    const wrapper = await mountSuspended(AlertMaskedContent, {
+      props: { theme: "info" },
+      slots: { title: "T", content: "C" },
+    });
+    expect(wrapper.find(".alert-content-title").exists()).toBe(true);
+    expect(wrapper.find(".alert-content-text").exists()).toBe(true);
+  });
 });

package/app/components/02.molecules/cookie-consent-banner/CONSUMER-STYLING.md

@@ -0,0 +1,95 @@
+# CookieConsentBanner — Consumer Styling Guide
+
+The banner is a fixed, teleported wrapper around `AlertContent`. The panel itself (background, text
+colour, border, radius, padding, accent stripe, icon, title and message sizes, actions alignment) is
+`AlertContent`'s, styled with its `--alert-content-*` tokens: see
+`app/components/02.molecules/alert-content/CONSUMER-STYLING.md`. This guide covers what the banner
+adds: position, motion and the two buttons.
+
+> **Changed 2026-09-27**: rebuilt on `AlertContent`. The banner's own panel tokens
+> (`--cookie-consent-banner-padding`, `-gap`, `-border-radius`, `-border`, `-accent-border-width`,
+> `-background`, `-text-colour`, `-actions-gap`) are gone; use the matching `--alert-content-*`
+> tokens. The panel now follows `data-theme` in light and dark mode (a theme-tinted surface) instead
+> of a fixed white panel, with a left accent stripe instead of a top border.
+>
+> Earlier the same day: classes, tokens and `data-test-id`s renamed from `privacy-notice-banner` to
+> `cookie-consent-banner`. The consent cookie's own name (`privacy-notice-consent`, owned by
+> `useCookieConsent`) is unchanged.
+
+## Public token API
+
+### Position and motion
+
+| Token | Default | Controls |
+|---|---|---|
+| `--cookie-consent-banner-z-index` | `999999` | Stacking order (matches `DisplayDialog`/`DisplayToast`) |
+| `--cookie-consent-banner-gutter` | `1.6rem` | Distance from the viewport's bottom and side edges |
+| `--cookie-consent-banner-max-width` | `64rem` | Maximum width (centred) |
+| `--cookie-consent-banner-transition-duration` | `200ms` | Close fade and button hover transitions |
+
+### Buttons
+
+| Token | Default | Controls |
+|---|---|---|
+| `--cookie-consent-banner-accent` | `var(--theme-accent)` | Accept background and reject hover border |
+| `--cookie-consent-banner-button-padding` | `0.8rem 1.6rem` | Button padding |
+| `--cookie-consent-banner-button-border-radius` | `0.4rem` | Button corner radius |
+| `--cookie-consent-banner-focus-ring` | `var(--theme-border-focus)` | `:focus-visible` outline colour on both buttons |
+| `--cookie-consent-banner-reject-border-colour` | `var(--theme-border)` | Reject button border, resting |
+| `--cookie-consent-banner-reject-border-colour-hover` | `var(--cookie-consent-banner-accent)` | Reject button border, hover/focus |
+| `--cookie-consent-banner-accept-background` | `var(--cookie-consent-banner-accent)` | Accept button background |
+| `--cookie-consent-banner-accept-text-colour` | `var(--theme-on-surface)` | Accept button text |
+
+The gap between the buttons and their alignment (right by default) are `AlertContent`'s
+`--alert-content-actions-gap` and `--alert-content-actions-justify`.
+
+Private tokens (not public API): `--_gutter`, `--_transition-duration`, `--_accent` on the root,
+each resolving a public token once for reuse.
+
+## State hooks
+
+- `data-theme` on the root and on the inner `.alert-content`, from the `theme` prop or `app.config`
+  (default `info`). It drives every `--theme-*` default, for the panel and the buttons.
+- `.closed` on the root once consent is granted or denied. The banner fades out and becomes
+  `visibility: hidden`, so its buttons leave the tab order and the accessibility tree.
+- Classes: `.cookie-consent-banner` > `.cookie-consent-banner-inner` (the `role="region"`) >
+  `.alert-content` (see its guide for the inner structure); the buttons are
+  `.cookie-consent-banner-reject` and `.cookie-consent-banner-accept` inside `.alert-content-actions`.
+- `data-test-id`: `cookie-consent-banner`, `cookie-consent-banner-reject`, `cookie-consent-banner-accept`,
+  plus `AlertContent`'s `alert-icon`, `alert-title`, `alert-content`, `alert-actions`.
+
+## Motion
+
+Closing fades opacity and collapses `grid-template-rows` over the transition duration. Under
+`prefers-reduced-motion: reduce` it closes instantly.
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<style scoped>`, tokens set on your element still work, but selectors that reach inside the
+component need `:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
+
+**Caveat:** the banner is teleported to `<body>`, so tokens set on a page or section wrapper never
+reach it. Set them on `:root`/`html`, on `body`, or on the banner itself through
+`style-class-passthrough`. That includes the `--alert-content-*` panel tokens; setting them on the
+banner scopes them to the banner, leaving other alerts on the page alone.
+
+## Recipe: neutral panel
+
+The pre-2026-09-27 look (white panel, dark text, no tint), scoped to the banner:
+
+```css
+.cookie-consent-banner {
+  --alert-content-inner-background: var(--slate-00);
+  --alert-content-text-colour: var(--slate-10);
+  --alert-content-border: 0.1rem solid var(--slate-10);
+}
+```
+
+## Class passthrough
+
+`style-class-passthrough` adds classes to the teleported root `.cookie-consent-banner`, next to
+`data-theme` and `.closed`. It's reachable in normal use and is the most reliable place to set
+tokens for this component, since ancestor wrappers don't contain it.