srcdev-nuxt-components 9.4.9 → 9.4.11

package/app/components/01.atoms/display-tooltip/DisplayTooltip.vue

@@ -115,13 +115,13 @@ watch(
       width: var(--display-tooltip-popover-width, 30rem);
 
       outline: var(--display-tooltip-popover-outline-width, 0.1rem) solid
-        var(--display-tooltip-popover-outline-colour, light-dark(var(--slate-02), var(--slate-06)));
-      color: var(--display-tooltip-popover-text-colour, light-dark(var(--slate-09), var(--slate-01)));
-      background-color: var(--display-tooltip-popover-background-colour, light-dark(var(--slate-00), var(--slate-07)));
+        var(--display-tooltip-popover-outline-colour, var(--slate-02));
+      color: var(--display-tooltip-popover-text-colour, var(--slate-09));
+      background-color: var(--display-tooltip-popover-background-colour, var(--slate-00));
       border-radius: var(--display-tooltip-popover-border-radius, 0.8rem);
       box-shadow: var(
         --display-tooltip-popover-shadow,
-        light-dark(0 0.4rem 1.6rem rgba(0, 0, 0, 0.12), 0 0.4rem 1.6rem rgba(0, 0, 0, 0.5))
+        0 0.4rem 1.6rem rgba(0, 0, 0, 0.12)
       );
 
       position-anchor: var(--_anchor-name);
@@ -147,9 +147,9 @@ watch(
         .display-tooltip-close-button {
           all: unset;
           cursor: pointer;
-          color: var(--display-tooltip-close-button-colour, light-dark(var(--slate-09), var(--slate-01)));
+          color: var(--display-tooltip-close-button-colour, var(--slate-09));
           border: var(--display-tooltip-close-button-border-width, 0.1rem) solid
-            var(--display-tooltip-close-button-border-colour, light-dark(var(--slate-03), var(--slate-06)));
+            var(--display-tooltip-close-button-border-colour, var(--slate-03));
           outline: var(--display-tooltip-close-button-outline-width, 0.1rem) solid transparent;
 
           font-weight: 600;
@@ -160,11 +160,11 @@ watch(
             text-decoration: underline;
             border-color: var(
               --display-tooltip-close-button-border-colour-hover,
-              light-dark(var(--slate-06), var(--slate-03))
+              var(--slate-06)
             );
             outline-color: var(
               --display-tooltip-close-button-outline-colour-hover,
-              light-dark(var(--slate-06), var(--slate-03))
+              var(--slate-06)
             );
             outline-offset: 0.2rem;
           }

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

@@ -9,21 +9,21 @@
 | `--pop-over-trigger-outline-colour-hover` | `var(--theme-ring)` | Trigger outline colour on focus-visible |
 | `--pop-over-width` | `30rem` | Popover panel width |
 | `--pop-over-border-width` | `0.1rem` | Popover panel border width |
-| `--pop-over-border-colour` | `light-dark(var(--slate-02), var(--slate-06))` | Popover panel border colour |
+| `--pop-over-border-colour` | `var(--slate-02)` | Popover panel border colour |
 | `--pop-over-border-radius` | `0.8rem` | Popover panel corner radius |
-| `--pop-over-background-colour` | `light-dark(var(--slate-00), var(--slate-07))` | Popover panel background |
-| `--pop-over-text-colour` | `light-dark(var(--slate-09), var(--slate-01))` | Popover panel text colour |
-| `--pop-over-shadow` | `light-dark(0 0.4rem 1.6rem rgba(0,0,0,.12), 0 0.4rem 1.6rem rgba(0,0,0,.5))` | Popover panel elevation shadow |
+| `--pop-over-background-colour` | `var(--slate-00)` | Popover panel background |
+| `--pop-over-text-colour` | `var(--slate-09)` | Popover panel text colour |
+| `--pop-over-shadow` | `0 0.4rem 1.6rem rgba(0,0,0,.12)` | Popover panel elevation shadow |
 | `--pop-over-transition-duration` | `200ms` | Open/close fade duration |
 | `--pop-over-content-padding` | `1.6rem` | Padding around the `content` slot |
 | `--pop-over-content-padding-block-start` | `3.2rem` | Extra top padding so content clears the close button |
 | `--pop-over-close-button-offset` | `0.8rem` | Distance of the close button from the panel's top/right edges |
 | `--pop-over-close-button-size` | `2.4rem` | Close button box width/height |
 | `--pop-over-close-button-border-radius` | `50%` | Close button corner radius |
-| `--pop-over-close-button-colour` | `light-dark(var(--slate-06), var(--slate-03))` | Close button icon colour |
+| `--pop-over-close-button-colour` | `var(--slate-06)` | Close button icon colour |
 | `--pop-over-close-button-icon-size` | `1.4rem` | Close button icon glyph size |
 | `--pop-over-close-button-outline-width` | `0.1rem` | Close button focus/hover outline width |
-| `--pop-over-close-button-surface-hover` | `light-dark(var(--slate-01), var(--slate-06))` | Close button background on hover/focus-visible |
+| `--pop-over-close-button-surface-hover` | `var(--slate-01)` | Close button background on hover/focus-visible |
 | `--pop-over-close-button-outline-colour-hover` | `var(--theme-ring)` | Close button outline colour on hover/focus-visible |
 
 ```css

package/app/components/01.atoms/pop-over/PopOver.vue

@@ -102,13 +102,13 @@ watch(
       margin: 0;
       inset: auto;
       border: var(--pop-over-border-width, 0.1rem) solid
-        var(--pop-over-border-colour, light-dark(var(--slate-02), var(--slate-06)));
+        var(--pop-over-border-colour, var(--slate-02));
       border-radius: var(--pop-over-border-radius, 0.8rem);
-      background-color: var(--pop-over-background-colour, light-dark(var(--slate-00), var(--slate-07)));
-      color: var(--pop-over-text-colour, light-dark(var(--slate-09), var(--slate-01)));
+      background-color: var(--pop-over-background-colour, var(--slate-00));
+      color: var(--pop-over-text-colour, var(--slate-09));
       box-shadow: var(
         --pop-over-shadow,
-        light-dark(0 0.4rem 1.6rem rgba(0, 0, 0, 0.12), 0 0.4rem 1.6rem rgba(0, 0, 0, 0.5))
+        0 0.4rem 1.6rem rgba(0, 0, 0, 0.12)
       );
       width: var(--pop-over-width, 30rem);
 
@@ -139,12 +139,12 @@ watch(
         width: var(--pop-over-close-button-size, 2.4rem);
         height: var(--pop-over-close-button-size, 2.4rem);
         border-radius: var(--pop-over-close-button-border-radius, 50%);
-        color: var(--pop-over-close-button-colour, light-dark(var(--slate-06), var(--slate-03)));
+        color: var(--pop-over-close-button-colour, var(--slate-06));
         outline: var(--pop-over-close-button-outline-width, 0.1rem) solid transparent;
 
         &:hover,
         &:focus-visible {
-          background-color: var(--pop-over-close-button-surface-hover, light-dark(var(--slate-01), var(--slate-06)));
+          background-color: var(--pop-over-close-button-surface-hover, var(--slate-01));
           outline-color: var(--pop-over-close-button-outline-colour-hover, var(--theme-ring));
           outline-offset: 0.1rem;
         }

package/app/components/01.atoms/ui-block-decorated/CONSUMER-STYLING.md

@@ -0,0 +1,39 @@
+# UiBlockDecorated — Consumer Styling Guide
+
+## Public token API
+
+Each strength level (border 1-6, shadow 1-6, inner shadow 1-4) has its own token, defaulting to a
+built-in elevation/border scale. Only the tokens for the strength levels actually in use need
+overriding.
+
+| Token | Default | Controls |
+|---|---|---|
+| `--ui-block-decorated-border-1` .. `-6` | `1px` .. `6px solid var(--theme-border)` | Border at each strength level |
+| `--ui-block-decorated-shadow-1` .. `-6` | `0 1px 2px rgba(0,0,0,0.08)` .. `0 24px 32px rgba(0,0,0,0.18)` | Drop shadow at each strength level |
+| `--ui-block-decorated-inner-shadow-1` .. `-4` | `inset 0 1px 2px rgba(0,0,0,0.08)` .. `inset 0 6px 8px rgba(0,0,0,0.14)` | Inset shadow at each strength level |
+| `--ui-block-decorated-inner-shadow-highlight` | `inset 0 1px 0 rgba(255,255,255,0.15)` | Highlight layered on top of every inner shadow strength |
+
+```css
+.my-page {
+  --ui-block-decorated-shadow-3: 0 6px 12px rgba(0, 0, 0, 0.2);
+  --ui-block-decorated-border-2: 2px dashed hotpink;
+}
+```
+
+Or scope to a single instance via `styleClassPassthrough`:
+
+```vue
+<UiBlockDecorated :shadow-strength="3" style-class-passthrough="promo-block">...</UiBlockDecorated>
+```
+
+```css
+.promo-block {
+  --ui-block-decorated-shadow-3: 0 6px 12px rgba(0, 0, 0, 0.2);
+}
+```
+
+## Strength props apply at most one class each
+
+`borderStrength`, `shadowStrength` and `innerShadowStrength` are independent — a value of `0`
+(the default) applies no class for that decoration. All three can be combined on the same
+instance (e.g. a border and a shadow together).

package/app/components/01.atoms/ui-block-decorated/UiBlockDecorated.vue

@@ -0,0 +1,141 @@
+<template>
+  <component
+    :is="tag"
+    class="ui-block-decorated"
+    :class="[
+      { [`ui-block-decorated-border-${borderStrength}`]: borderStrength > 0 },
+      { [`ui-block-decorated-shadow-${shadowStrength}`]: shadowStrength > 0 },
+      { [`ui-block-decorated-inner-shadow-${innerShadowStrength}`]: innerShadowStrength > 0 },
+      elementClasses,
+    ]"
+  >
+    <slot name="default"></slot>
+  </component>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  tag?: "div" | "p" | "span" | "section" | "article" | "aside" | "header" | "footer" | "main" | "nav" | "ul" | "ol";
+  borderStrength?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  shadowStrength?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  innerShadowStrength?: 0 | 1 | 2 | 3 | 4;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  tag: "div",
+  borderStrength: 0,
+  shadowStrength: 0,
+  innerShadowStrength: 0,
+  styleClassPassthrough: () => [],
+});
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => {
+    resetElementClasses(props.styleClassPassthrough);
+  }
+);
+</script>
+
+<style lang="css">
+@layer components {
+  .ui-block-decorated {
+    /*
+    * Border strength classes
+    */
+    &.ui-block-decorated-border-1 {
+      border: var(--ui-block-decorated-border-1, 1px solid var(--theme-border));
+    }
+    &.ui-block-decorated-border-2 {
+      border: var(--ui-block-decorated-border-2, 2px solid var(--theme-border));
+    }
+    &.ui-block-decorated-border-3 {
+      border: var(--ui-block-decorated-border-3, 3px solid var(--theme-border));
+    }
+    &.ui-block-decorated-border-4 {
+      border: var(--ui-block-decorated-border-4, 4px solid var(--theme-border));
+    }
+    &.ui-block-decorated-border-5 {
+      border: var(--ui-block-decorated-border-5, 5px solid var(--theme-border));
+    }
+    &.ui-block-decorated-border-6 {
+      border: var(--ui-block-decorated-border-6, 6px solid var(--theme-border));
+    }
+
+    /*
+    * Shadow strength classes
+    */
+    &.ui-block-decorated-shadow-1 {
+      box-shadow: var(--ui-block-decorated-shadow-1, 0 1px 2px rgba(0, 0, 0, 0.08));
+    }
+    &.ui-block-decorated-shadow-2 {
+      box-shadow: var(--ui-block-decorated-shadow-2, 0 2px 4px rgba(0, 0, 0, 0.1));
+    }
+    &.ui-block-decorated-shadow-3 {
+      box-shadow: var(--ui-block-decorated-shadow-3, 0 4px 8px rgba(0, 0, 0, 0.12));
+    }
+    &.ui-block-decorated-shadow-4 {
+      box-shadow: var(--ui-block-decorated-shadow-4, 0 8px 16px rgba(0, 0, 0, 0.14));
+    }
+    &.ui-block-decorated-shadow-5 {
+      box-shadow: var(--ui-block-decorated-shadow-5, 0 16px 24px rgba(0, 0, 0, 0.16));
+    }
+    &.ui-block-decorated-shadow-6 {
+      box-shadow: var(--ui-block-decorated-shadow-6, 0 24px 32px rgba(0, 0, 0, 0.18));
+    }
+
+    /*
+    * Inner shadow strength classes
+    * Could use substring match [class*="ui-block-decorated-inner-shadow"] but not as performant
+    */
+
+    &.ui-block-decorated-inner-shadow-1,
+    &.ui-block-decorated-inner-shadow-2,
+    &.ui-block-decorated-inner-shadow-3,
+    &.ui-block-decorated-inner-shadow-4 {
+      position: relative;
+      isolation: isolate;
+    }
+
+    &.ui-block-decorated-inner-shadow-1::before,
+    &.ui-block-decorated-inner-shadow-2::before,
+    &.ui-block-decorated-inner-shadow-3::before,
+    &.ui-block-decorated-inner-shadow-4::before {
+      content: "";
+      display: block;
+      position: absolute;
+      inset: 0;
+      pointer-events: none;
+      border-radius: inherit;
+      z-index: 2;
+    }
+
+    &.ui-block-decorated-inner-shadow-1::before {
+      box-shadow:
+        var(--ui-block-decorated-inner-shadow-1, inset 0 1px 2px rgba(0, 0, 0, 0.08)),
+        var(--ui-block-decorated-inner-shadow-highlight, inset 0 1px 0 rgba(255, 255, 255, 0.15));
+    }
+
+    &.ui-block-decorated-inner-shadow-2::before {
+      box-shadow:
+        var(--ui-block-decorated-inner-shadow-2, inset 0 2px 4px rgba(0, 0, 0, 0.1)),
+        var(--ui-block-decorated-inner-shadow-highlight, inset 0 1px 0 rgba(255, 255, 255, 0.15));
+    }
+
+    &.ui-block-decorated-inner-shadow-3::before {
+      box-shadow:
+        var(--ui-block-decorated-inner-shadow-3, inset 0 4px 6px rgba(0, 0, 0, 0.12)),
+        var(--ui-block-decorated-inner-shadow-highlight, inset 0 1px 0 rgba(255, 255, 255, 0.15));
+    }
+
+    &.ui-block-decorated-inner-shadow-4::before {
+      box-shadow:
+        var(--ui-block-decorated-inner-shadow-4, inset 0 6px 8px rgba(0, 0, 0, 0.14)),
+        var(--ui-block-decorated-inner-shadow-highlight, inset 0 1px 0 rgba(255, 255, 255, 0.15));
+    }
+  }
+}
+</style>

package/app/components/01.atoms/ui-block-decorated/stories/UiBlockDecorated.stories.ts

@@ -0,0 +1,148 @@
+import UiBlockDecorated from "../UiBlockDecorated.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof UiBlockDecorated> = {
+  title: "Atoms/UiBlockDecorated",
+  component: UiBlockDecorated,
+  argTypes: {
+    tag: {
+      control: { type: "select" },
+      options: ["div", "p", "span", "section", "article", "aside", "header", "footer", "main", "nav", "ul", "ol"],
+      description: "Root element tag",
+      table: { category: "Basic" },
+    },
+    borderStrength: {
+      control: { type: "select" },
+      options: [0, 1, 2, 3, 4, 5, 6],
+      description: "Border strength level (0 = none)",
+      table: { category: "Basic" },
+    },
+    shadowStrength: {
+      control: { type: "select" },
+      options: [0, 1, 2, 3, 4, 5, 6],
+      description: "Drop shadow strength level (0 = none)",
+      table: { category: "Basic" },
+    },
+    innerShadowStrength: {
+      control: { type: "select" },
+      options: [0, 1, 2, 3, 4],
+      description: "Inner shadow strength level (0 = none)",
+      table: { category: "Basic" },
+    },
+    styleClassPassthrough: {
+      table: { disable: true },
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A plain block wrapper that applies independent border / drop-shadow / inner-shadow strength levels via CSS custom properties (see CONSUMER-STYLING.md).",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof UiBlockDecorated>;
+
+const blockStyle = "padding: 2rem; background: var(--theme-surface, #fff);";
+
+export const Default: Story = {
+  args: {
+    tag: "div",
+  },
+  render: (args) => ({
+    components: { UiBlockDecorated },
+    setup() {
+      return { args, blockStyle };
+    },
+    template: `<UiBlockDecorated v-bind="args" :style="blockStyle">No decoration</UiBlockDecorated>`,
+  }),
+};
+
+export const Border: Story = {
+  args: {
+    tag: "div",
+    borderStrength: 3,
+  },
+  render: (args) => ({
+    components: { UiBlockDecorated },
+    setup() {
+      return { args, blockStyle };
+    },
+    template: `<UiBlockDecorated v-bind="args" :style="blockStyle">Border strength 3</UiBlockDecorated>`,
+  }),
+};
+
+export const Shadow: Story = {
+  args: {
+    tag: "div",
+    shadowStrength: 4,
+  },
+  render: (args) => ({
+    components: { UiBlockDecorated },
+    setup() {
+      return { args, blockStyle };
+    },
+    template: `<UiBlockDecorated v-bind="args" :style="blockStyle">Shadow strength 4</UiBlockDecorated>`,
+  }),
+};
+
+export const InnerShadow: Story = {
+  args: {
+    tag: "div",
+    innerShadowStrength: 3,
+  },
+  render: (args) => ({
+    components: { UiBlockDecorated },
+    setup() {
+      return { args, blockStyle };
+    },
+    template: `<UiBlockDecorated v-bind="args" :style="blockStyle">Inner shadow strength 3</UiBlockDecorated>`,
+  }),
+};
+
+export const AllCombined: Story = {
+  args: {
+    tag: "div",
+    borderStrength: 2,
+    shadowStrength: 3,
+    innerShadowStrength: 2,
+  },
+  render: (args) => ({
+    components: { UiBlockDecorated },
+    setup() {
+      return { args, blockStyle };
+    },
+    template: `<UiBlockDecorated v-bind="args" :style="blockStyle">All three combined</UiBlockDecorated>`,
+  }),
+};
+
+export const CustomTokens: Story = {
+  args: {
+    tag: "div",
+    shadowStrength: 3,
+  },
+  render: (args) => ({
+    components: { UiBlockDecorated },
+    setup() {
+      return { args, blockStyle };
+    },
+    template: `
+      <UiBlockDecorated
+        v-bind="args"
+        :style="blockStyle + ' --ui-block-decorated-shadow-3: 0 6px 12px rgba(0, 0, 0, 0.25);'"
+      >
+        Custom shadow-3 token
+      </UiBlockDecorated>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "Overriding a strength level's token via an inline `--ui-block-decorated-*` custom property.",
+      },
+    },
+  },
+};

package/app/components/01.atoms/ui-block-decorated/tests/UiBlockDecorated.spec.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import UiBlockDecorated from "../UiBlockDecorated.vue";
+
+describe("UiBlockDecorated", () => {
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(UiBlockDecorated);
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders correct HTML structure (default props)", async () => {
+    const wrapper = await mountSuspended(UiBlockDecorated);
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  it("renders a <div> by default", async () => {
+    const wrapper = await mountSuspended(UiBlockDecorated);
+    expect(wrapper.element.tagName).toBe("DIV");
+  });
+
+  it("renders the given tag", async () => {
+    const wrapper = await mountSuspended(UiBlockDecorated, { props: { tag: "section" } });
+    expect(wrapper.element.tagName).toBe("SECTION");
+  });
+
+  it("applies no strength classes by default", async () => {
+    const wrapper = await mountSuspended(UiBlockDecorated);
+    expect(wrapper.classes()).toEqual(["ui-block-decorated"]);
+  });
+
+  it("applies the border strength class", async () => {
+    const wrapper = await mountSuspended(UiBlockDecorated, { props: { borderStrength: 3 } });
+    expect(wrapper.classes()).toContain("ui-block-decorated-border-3");
+  });
+
+  it("applies the shadow strength class", async () => {
+    const wrapper = await mountSuspended(UiBlockDecorated, { props: { shadowStrength: 5 } });
+    expect(wrapper.classes()).toContain("ui-block-decorated-shadow-5");
+  });
+
+  it("applies the inner shadow strength class", async () => {
+    const wrapper = await mountSuspended(UiBlockDecorated, { props: { innerShadowStrength: 2 } });
+    expect(wrapper.classes()).toContain("ui-block-decorated-inner-shadow-2");
+  });
+
+  it("combines all three strength classes together", async () => {
+    const wrapper = await mountSuspended(UiBlockDecorated, {
+      props: { borderStrength: 1, shadowStrength: 2, innerShadowStrength: 3 },
+    });
+    expect(wrapper.classes()).toContain("ui-block-decorated-border-1");
+    expect(wrapper.classes()).toContain("ui-block-decorated-shadow-2");
+    expect(wrapper.classes()).toContain("ui-block-decorated-inner-shadow-3");
+  });
+
+  it("renders slot content", async () => {
+    const wrapper = await mountSuspended(UiBlockDecorated, {
+      slots: { default: "<p class='slot-child'>Hello</p>" },
+    });
+    expect(wrapper.find(".slot-child").exists()).toBe(true);
+    expect(wrapper.find(".slot-child").text()).toBe("Hello");
+  });
+
+  it("applies styleClassPassthrough classes", async () => {
+    const wrapper = await mountSuspended(UiBlockDecorated, {
+      props: { styleClassPassthrough: ["custom-class"] },
+    });
+    expect(wrapper.classes()).toContain("custom-class");
+  });
+
+  it("resets classes when styleClassPassthrough prop changes", async () => {
+    const wrapper = await mountSuspended(UiBlockDecorated, {
+      props: { styleClassPassthrough: ["initial-class"] },
+    });
+    expect(wrapper.classes()).toContain("initial-class");
+
+    await wrapper.setProps({ styleClassPassthrough: ["updated-class"] });
+    expect(wrapper.classes()).not.toContain("initial-class");
+    expect(wrapper.classes()).toContain("updated-class");
+  });
+});

package/app/components/01.atoms/ui-block-decorated/tests/__snapshots__/UiBlockDecorated.spec.ts.snap

@@ -0,0 +1,3 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`UiBlockDecorated > renders correct HTML structure (default props) 1`] = `"<div class="ui-block-decorated"></div>"`;

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

@@ -135,11 +135,11 @@ describe("AlertMaskedContent", () => {
     const wrapper = await mountSuspended(AlertMaskedContent, { props: { theme: "info" } });
     const contentEl = wrapper.find(".alert-mask-content");
     const style = (contentEl.element as HTMLElement).style;
-    // Default borderLeft: 6 → --insetInlineStart: 6px
-    expect(style.getPropertyValue("--insetInlineStart")).toBe("6px");
-    expect(style.getPropertyValue("--insetBlockStart")).toBe("1px");
-    expect(style.getPropertyValue("--insetInlineEnd")).toBe("1px");
-    expect(style.getPropertyValue("--insetBlockEnd")).toBe("1px");
+    // Default borderLeft: 6 → --_inset-inline-start: 6px
+    expect(style.getPropertyValue("--_inset-inline-start")).toBe("6px");
+    expect(style.getPropertyValue("--_inset-block-start")).toBe("1px");
+    expect(style.getPropertyValue("--_inset-inline-end")).toBe("1px");
+    expect(style.getPropertyValue("--_inset-block-end")).toBe("1px");
   });
 
   it("merges custom maskConfig over defaults", async () => {
@@ -148,6 +148,6 @@ describe("AlertMaskedContent", () => {
     });
     const contentEl = wrapper.find(".alert-mask-content");
     const style = (contentEl.element as HTMLElement).style;
-    expect(style.getPropertyValue("--insetInlineStart")).toBe("12px");
+    expect(style.getPropertyValue("--_inset-inline-start")).toBe("12px");
   });
 });

package/app/components/02.molecules/display-theme-switch/CONSUMER-STYLING.md

@@ -0,0 +1,34 @@
+# DisplayThemeSwitch — Consumer Styling Guide
+
+## No tokens of its own — delegates entirely to TripleToggleSwitchCore
+
+`DisplayThemeSwitch` is a thin wrapper around `TripleToggleSwitchCore` (see
+`app/components/05.forms/triple-toggle-switch/CONSUMER-STYLING.md`) and declares no
+`--display-theme-switch-*` tokens of its own. Every colour token documented there
+(`--triple-toggle-switch-surface`, `--triple-toggle-switch-border`, `--triple-toggle-switch-marker-surface`,
+etc.) applies unchanged, since `DisplayThemeSwitch` renders that component directly with no
+intermediate styling layer.
+
+## `small` class — compact sizing
+
+Pass `"small"` via `styleClassPassthrough` for a more compact gap/padding/icon-size, useful in a
+tight header/nav slot:
+
+```vue
+<DisplayThemeSwitch style-class-passthrough="small" />
+```
+
+This sets `TripleToggleSwitchCore`'s public `--triple-toggle-switch-gap`/`-padding`/
+`-option-padding`/`-icon-size` tokens to smaller values (`0.2rem`/`0.2rem`/`0.2rem`/`1.6rem` vs the
+default `0.4rem`/`0.4rem`/`0.4rem`/`2rem` — both already more compact than `TripleToggleSwitchCore`'s
+own defaults of `1rem`/`0.6rem`/`0.5rem`/`2rem`). Override any of the four directly for a custom
+size instead of using `small`:
+
+```vue
+<DisplayThemeSwitch style="--triple-toggle-switch-icon-size: 2.4rem;" />
+```
+
+## Class passthrough
+
+`styleClassPassthrough` also accepts any other class for layout purposes, alongside or instead of
+`small`.