srcdev-nuxt-components 9.4.9 → 9.4.10

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`.

package/app/components/02.molecules/display-theme-switch/DisplayThemeSwitch.vue

@@ -0,0 +1,102 @@
+<template>
+  <ClientOnly>
+    <TripleToggleSwitchCore
+      v-model="colorModeVal"
+      v-model:field-data="sampleFieldData"
+      :style-class-passthrough="[`colour-scheme-select`, elementClasses]"
+    />
+  </ClientOnly>
+</template>
+
+<script setup lang="ts">
+import type { IFormMultipleOptions } from "~/types/forms/types.forms";
+interface Props {
+  styleClassPassthrough?: string | string[];
+  systemLabel?: string;
+  lightLabel?: string;
+  darkLabel?: string;
+  systemIcon?: string;
+  lightIcon?: string;
+  darkIcon?: string;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  styleClassPassthrough: () => [],
+  systemLabel: "System",
+  lightLabel: "Light",
+  darkLabel: "Dark",
+  systemIcon: "material-symbols:night-sight-auto-sharp",
+  lightIcon: "radix-icons:sun",
+  darkIcon: "radix-icons:moon",
+});
+
+const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+const sampleFieldData = computed<IFormMultipleOptions>(() => ({
+  data: [
+    {
+      id: "system",
+      name: "colorModeVal",
+      value: "system",
+      label: props.systemLabel,
+      icon: props.systemIcon,
+    },
+    {
+      id: "light",
+      name: "colorModeVal",
+      value: "light",
+      label: props.lightLabel,
+      icon: props.lightIcon,
+    },
+    {
+      id: "dark",
+      name: "colorModeVal",
+      value: "dark",
+      label: props.darkLabel,
+      icon: props.darkIcon,
+    },
+  ],
+  total: 3,
+  skip: 0,
+  limit: 3,
+}));
+
+const { colourScheme, setColourScheme } = useSettingsStore();
+
+const colorModeVal = ref(colourScheme);
+watch(colorModeVal, (val) => {
+  setColourScheme(val);
+});
+</script>
+
+<style lang="css">
+@layer components {
+.colour-scheme-select {
+  /* Everything DisplayThemeSwitch used to redeclare here beyond sizing (wrapper background/border/
+     focus ring, marker border, option border/outline/focus/hover, option-icon colours, and the
+     system/light/dark marker gradients) was a byte-for-byte duplicate of TripleToggleSwitchCore's
+     own defaults for the exact same selectors — a no-op at best, and for the ones that bypassed
+     TripleToggleSwitchCore's public --triple-toggle-switch-* tokens with a hardcoded literal
+     (background-color, border, focus outline, marker border, option border/hover/focus, icon
+     colour) an active bug: a consumer setting e.g. --triple-toggle-switch-surface globally would
+     have been silently overridden back to the hardcoded default by this block's higher
+     specificity. Removed 2026-09-20 — TripleToggleSwitchCore already owns all of that. Only the
+     genuine "small" sizing variant remains, now driving TripleToggleSwitchCore's own public
+     sizing tokens instead of reaching into its private --_form-* and --_scheme-icon-font-size
+     locals directly (see TripleToggleSwitchCore's CONSUMER-STYLING.md). */
+  &.triple-toggle-switch {
+    --triple-toggle-switch-gap: 0.4rem;
+    --triple-toggle-switch-padding: 0.4rem;
+    --triple-toggle-switch-option-padding: 0.4rem;
+    --triple-toggle-switch-icon-size: 2rem;
+
+    &.small {
+      --triple-toggle-switch-gap: 0.2rem;
+      --triple-toggle-switch-padding: 0.2rem;
+      --triple-toggle-switch-option-padding: 0.2rem;
+      --triple-toggle-switch-icon-size: 1.6rem;
+    }
+  }
+}
+}
+</style>

package/app/components/02.molecules/display-theme-switch/stories/DisplayThemeSwitch.stories.ts

@@ -0,0 +1,115 @@
+import DisplayThemeSwitch from "../DisplayThemeSwitch.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof DisplayThemeSwitch> = {
+  title: "Molecules/DisplayThemeSwitch",
+  component: DisplayThemeSwitch,
+  argTypes: {
+    styleClassPassthrough: {
+      control: "object",
+      description: "Extra classes — pass \"small\" for a compact size",
+      table: { category: "Styling" },
+    },
+    systemLabel: {
+      control: "text",
+      description: "Accessible label for the system option",
+      table: { category: "Labels" },
+    },
+    lightLabel: {
+      control: "text",
+      description: "Accessible label for the light option",
+      table: { category: "Labels" },
+    },
+    darkLabel: {
+      control: "text",
+      description: "Accessible label for the dark option",
+      table: { category: "Labels" },
+    },
+    systemIcon: {
+      control: "text",
+      description: "Icon name for the system option",
+      table: { category: "Icons" },
+    },
+    lightIcon: {
+      control: "text",
+      description: "Icon name for the light option",
+      table: { category: "Icons" },
+    },
+    darkIcon: {
+      control: "text",
+      description: "Icon name for the dark option",
+      table: { category: "Icons" },
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A system/light/dark theme switch wrapping TripleToggleSwitchCore, wired to useSettingsStore. Colour and sizing are entirely delegated to TripleToggleSwitchCore's public --triple-toggle-switch-* tokens — see CONSUMER-STYLING.md.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof DisplayThemeSwitch>;
+
+export const Default: Story = {
+  args: {},
+  render: (args) => ({
+    components: { DisplayThemeSwitch },
+    setup() {
+      return { args };
+    },
+    template: `<DisplayThemeSwitch v-bind="args" />`,
+  }),
+};
+
+export const Small: Story = {
+  args: {
+    styleClassPassthrough: "small",
+  },
+  render: (args) => ({
+    components: { DisplayThemeSwitch },
+    setup() {
+      return { args };
+    },
+    template: `<DisplayThemeSwitch v-bind="args" />`,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "Compact sizing for use in a tight header/nav slot.",
+      },
+    },
+  },
+};
+
+export const InNavigation: Story = {
+  args: {
+    styleClassPassthrough: "small",
+  },
+  render: (args) => ({
+    components: { DisplayThemeSwitch },
+    setup() {
+      return { args };
+    },
+    template: `
+      <nav style="display: flex; align-items: center; justify-content: space-between; padding: 1.6rem 2.4rem; background: var(--theme-surface); border-radius: 0.8rem; border: 1px solid var(--theme-border);">
+        <div style="display: flex; align-items: center; gap: 1.6rem;">
+          <span style="font-weight: 600; color: var(--theme-text);">My App</span>
+          <a href="#" style="color: var(--theme-text); text-decoration: none;">Home</a>
+          <a href="#" style="color: var(--theme-text); text-decoration: none;">About</a>
+        </div>
+        <DisplayThemeSwitch v-bind="args" />
+      </nav>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "Example of the theme switch integrated into a navigation bar context.",
+      },
+    },
+  },
+};