srcdev-nuxt-components 9.4.11 → 9.5.0

package/app/components/05.forms/pending-effect/stories/PendingEffect.stories.ts

@@ -0,0 +1,132 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import { computed } from "vue";
+import InputButton from "../../input-button/InputButton.vue";
+
+interface PendingEffectStoryArgs {
+  isPending: boolean;
+  theme: "default" | "success" | "error" | "warning";
+  variant: "primary" | "secondary" | "tertiary";
+  buttonText: string;
+  lineColor: string;
+  blurColor: string;
+  lineThickness: string;
+  lineLength: string;
+  blurSize: string;
+  offset: string;
+  animationDuration: string;
+}
+
+export default {
+  title: "Components/Forms/Pending Effect/PendingEffect",
+  argTypes: {
+    isPending: { control: "boolean", description: "InputButton is-pending", table: { category: "State" } },
+    theme: {
+      control: { type: "select" },
+      options: ["default", "success", "error", "warning"],
+      table: { category: "State" },
+    },
+    variant: {
+      control: { type: "select" },
+      options: ["primary", "secondary", "tertiary"],
+      table: { category: "Host button" },
+    },
+    buttonText: { control: "text", table: { category: "Host button" } },
+    lineColor: {
+      control: "color",
+      description: "--pending-effect-line-color (empty = theme colour, var(--theme-surface))",
+      table: { category: "Tokens" },
+    },
+    blurColor: {
+      control: "color",
+      description: "--pending-effect-blur-color (empty = theme colour; only visible when blurSize > 0rem)",
+      table: { category: "Tokens" },
+    },
+    lineThickness: {
+      control: { type: "select" },
+      options: ["0.1rem", "0.2rem", "0.3rem", "0.4rem", "0.6rem"],
+      description: "--pending-effect-line-thickness (default 0.1rem)",
+      table: { category: "Tokens" },
+    },
+    lineLength: {
+      control: { type: "select" },
+      options: ["1rem", "2rem", "3rem", "3.5rem", "4.5rem"],
+      description: "--pending-effect-line-length (default 2rem; the dash pattern repeats every 5rem)",
+      table: { category: "Tokens" },
+    },
+    blurSize: {
+      control: { type: "select" },
+      options: ["0rem", "0.2rem", "0.3rem", "0.4rem", "0.6rem"],
+      description: "--pending-effect-blur-size (default 0rem = no glow)",
+      table: { category: "Tokens" },
+    },
+    offset: {
+      control: { type: "select" },
+      options: ["0rem", "0.5rem", "1rem", "2rem", "3rem"],
+      description: "--pending-effect-offset (default 1rem, split across both sides)",
+      table: { category: "Tokens" },
+    },
+    animationDuration: {
+      control: { type: "select" },
+      options: ["800ms", "1200ms", "2000ms", "3000ms", "5000ms"],
+      description: "--pending-effect-animation-duration (default 3000ms)",
+      table: { category: "Tokens" },
+    },
+  },
+  args: {
+    isPending: true,
+    theme: "default",
+    variant: "primary",
+    buttonText: "Submitting",
+    lineColor: "",
+    blurColor: "",
+    lineThickness: "0.1rem",
+    lineLength: "2rem",
+    blurSize: "0rem",
+    offset: "1rem",
+    animationDuration: "3000ms",
+  },
+} as Meta<PendingEffectStoryArgs>;
+
+const Template: StoryFn<PendingEffectStoryArgs> = (args) => ({
+  components: { InputButton },
+  setup() {
+    const tokenStyle = computed(() => ({
+      ...(args.lineColor ? { "--pending-effect-line-color": args.lineColor } : {}),
+      ...(args.blurColor ? { "--pending-effect-blur-color": args.blurColor } : {}),
+      "--pending-effect-line-thickness": args.lineThickness,
+      "--pending-effect-line-length": args.lineLength,
+      "--pending-effect-blur-size": args.blurSize,
+      "--pending-effect-offset": args.offset,
+      "--pending-effect-animation-duration": args.animationDuration,
+    }));
+    return { args, tokenStyle };
+  },
+  template: `
+    <div style="margin: 3.6rem;">
+      <p style="font-size: 1.4rem; margin-block-end: 2.4rem;">
+        PendingEffect is rendered by InputButton when <code>has-pending-effect</code> is set, and animates while
+        <code>is-pending</code> is true. It is hidden under <code>prefers-reduced-motion: reduce</code>.
+      </p>
+      <div :style="tokenStyle">
+        <InputButton
+          :button-text="args.buttonText"
+          :variant="args.variant"
+          :theme="args.theme"
+          :is-pending="args.isPending"
+          :has-pending-effect="true"
+        />
+      </div>
+    </div>
+  `,
+});
+
+export const Default = Template.bind({});
+
+export const Exaggerated = Template.bind({});
+Exaggerated.args = {
+  lineThickness: "0.4rem",
+  lineLength: "3.5rem",
+  blurSize: "0.4rem",
+  offset: "2rem",
+  animationDuration: "1200ms",
+};

package/app/components/05.forms/pending-effect/tests/PendingEffect.spec.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest";
+import { nextTick } from "vue";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import PendingEffect from "../PendingEffect.vue";
+import InputButton from "../../input-button/InputButton.vue";
+
+describe("PendingEffect", () => {
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(PendingEffect);
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders a prefixed svg container with blur and line rects", async () => {
+    const wrapper = await mountSuspended(PendingEffect);
+    const svg = wrapper.find("svg.pending-effect-container");
+    expect(svg.exists()).toBe(true);
+    expect(svg.find("rect.pending-effect-blur").exists()).toBe(true);
+    expect(svg.find("rect.pending-effect-line").exists()).toBe(true);
+  });
+
+  it("is hidden from assistive technology and not focusable", async () => {
+    const wrapper = await mountSuspended(PendingEffect);
+    const svg = wrapper.find("svg");
+    expect(svg.attributes("aria-hidden")).toBe("true");
+    expect(svg.attributes("focusable")).toBe("false");
+  });
+
+  it("defaults data-theme to default and reflects the theme prop", async () => {
+    const wrapper = await mountSuspended(PendingEffect);
+    expect(wrapper.find("svg").attributes("data-theme")).toBe("default");
+
+    await wrapper.setProps({ theme: "error" });
+    expect(wrapper.find("svg").attributes("data-theme")).toBe("error");
+  });
+
+  it("applies styleClassPassthrough and updates on change", async () => {
+    const wrapper = await mountSuspended(PendingEffect, { props: { styleClassPassthrough: ["one"] } });
+    expect(wrapper.find("svg").classes()).toContain("one");
+
+    await wrapper.setProps({ styleClassPassthrough: "two three" });
+    await nextTick();
+    const classes = wrapper.find("svg").classes();
+    expect(classes).toContain("two");
+    expect(classes).toContain("three");
+    expect(classes).not.toContain("one");
+  });
+
+  describe("inside InputButton", () => {
+    it("is rendered only when hasPendingEffect is true", async () => {
+      const without = await mountSuspended(InputButton, { props: { buttonText: "Save" } });
+      expect(without.find(".pending-effect-container").exists()).toBe(false);
+
+      const withEffect = await mountSuspended(InputButton, {
+        props: { buttonText: "Save", hasPendingEffect: true },
+      });
+      expect(withEffect.find(".pending-effect-container").exists()).toBe(true);
+      expect(withEffect.find("button").classes()).toContain("pending-effect");
+    });
+
+    it("passes the button theme through", async () => {
+      const wrapper = await mountSuspended(InputButton, {
+        props: { buttonText: "Save", hasPendingEffect: true, theme: "success" },
+      });
+      expect(wrapper.find(".pending-effect-container").attributes("data-theme")).toBe("success");
+    });
+  });
+});

package/app/components/05.forms/toggle-switch/CONSUMER-STYLING.md

@@ -55,7 +55,7 @@ fixed width independent of symbol size).
 
 ---
 
-## Global theming — app-level CSS file
+## Global theming
 
 ```css
 :where(html) {
@@ -66,7 +66,15 @@ fixed width independent of symbol size).
 
 ---
 
-## Per-instance overrides
+## 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`.
+
+### One instance
 
 ```vue
 <ToggleSwitchCore id="notifications" name="notifications" style="--toggle-switch-symbol-surface-on: var(--gold-06);" />
@@ -93,3 +101,4 @@ fixed width independent of symbol size).
   `ToggleSwitchWithLabel`/`ToggleSwitchWithLabelInline` — nothing in either file's CSS or
   `ToggleSwitchCore`'s ever read them (the actual transition durations are hardcoded `0.4s`
   literals in `ToggleSwitchCore`).
+

package/app/components/05.forms/toggle-switch/ToggleSwitchCore.vue

@@ -1,6 +1,6 @@
 <template>
   <div class="toggle-switch-core" :class="elementClasses" :data-theme="formUiTheme">
-    <div class="toggle-switch-wrapper" :class="wrapperClasses" @click="toggleSwitchValue">
+    <div class="toggle-switch-wrapper" :class="wrapperClasses()" @click="toggleSwitchValue">
       <input
         :id="inputId"
         v-model="modelValue"
@@ -8,7 +8,7 @@
         :true-value
         :false-value
         :aria-invalid="fieldHasError"
-        :aria-describedby="ariaDescribedbyId"
+        :aria-describedby="ariaDescribedby || undefined"
         :name
         :required
         :checked="isChecked"
@@ -60,7 +60,7 @@ const props = withDefaults(defineProps<Props>(), {
 });
 
 const slots = useSlots();
-const useDefaultIcons = computed(() => !slots.iconOn && !slots.iconOff);
+const useDefaultIcons = () => !slots.iconOn && !slots.iconOff;
 
 const formUiTheme = computed(() => {
   return props.fieldHasError ? "error" : props.theme;
@@ -72,16 +72,15 @@ const modelValue = defineModel<string | number | boolean>({ required: true });
 const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 
 const inputId = computed(() => `toggle-switch-${props.id}`);
-const ariaDescribedbyId = computed(() => `${props.id}-description`);
 
 const isChecked = computed(() => {
   return modelValue.value === props.trueValue;
 });
 
 // Optimized class computeds to reduce template reactivity
-const wrapperClasses = computed(() => ({
-  "use-default-icons": useDefaultIcons.value,
-}));
+const wrapperClasses = () => ({
+  "use-default-icons": useDefaultIcons(),
+});
 
 const symbolClasses = computed(() => ({
   checked: isChecked.value,
@@ -100,23 +99,6 @@ const toggleSwitchValue = () => {
     }
 
     .toggle-switch-wrapper {
-      /* --_icon-font-size, --_switch-padding, --_toggle-symbol-border-width are the only locals
-       actually read anywhere below — --_icon-on-opacity, --_icon-off-opacity,
-       --_symbol-background-color, --_symbol-margin-inline-start, --_symbol-checked-offset were
-       declared here but never referenced by any property in this file; removed as dead code
-       rather than migrated, since migrating an unread token would just create a new unread
-       public one. */
-      --_icon-font-size: 2.4rem;
-      --_switch-padding: 0.2rem;
-      --_toggle-symbol-border-width: 0.1rem;
-
-      /* Public --toggle-switch-* tokens, inline-fallback to the shared --theme-* tokens (see
-       theming-component-token-pattern.md) — overriding one here doesn't touch every other
-       themed input/control that also reads --theme-checkbox-symbol-surface/--theme-border. */
-      --_surface: var(--toggle-switch-surface, var(--theme-checkbox-symbol-surface));
-      --_surface-hover: var(--toggle-switch-surface-hover, var(--theme-surface-subtle));
-      --_border: var(--toggle-switch-border, var(--theme-border));
-      --_border-focus: var(--toggle-switch-border-focus, var(--theme-border-focus));
       --_border-radius: var(--toggle-switch-border-radius, v-bind(roundedRadiusDefault));
 
       display: flex;
@@ -129,7 +111,7 @@ const toggleSwitchValue = () => {
 
         &:focus-visible {
           + .symbol-wrapper {
-            outline: var(--form-element-outline-width-focus) solid var(--_border-focus);
+            outline: var(--form-element-outline-width-focus) solid var(--toggle-switch-border-focus, var(--theme-border-focus));
             outline-offset: var(--form-element-outline-offset-focus);
           }
         }
@@ -166,15 +148,15 @@ const toggleSwitchValue = () => {
           outline var(--theme-form-transition-duration) linear;
 
         /* UI */
-        background-color: var(--_surface);
-        border: var(--form-element-border-width) solid var(--_border);
+        background-color: var(--toggle-switch-surface, var(--theme-checkbox-symbol-surface));
+        border: var(--form-element-border-width) solid var(--toggle-switch-border, var(--theme-border));
         outline: var(--form-element-outline-width) solid transparent;
         border-radius: var(--_border-radius);
         width: var(--_track-width);
         padding: calc(var(--input-toggle-wrapper-padding) + var(--input-toggle-symbol-outline-width));
 
         &:hover {
-          background-color: var(--_surface-hover);
+          background-color: var(--toggle-switch-surface-hover, var(--theme-surface-subtle));
           cursor: pointer;
         }
 
@@ -190,7 +172,6 @@ const toggleSwitchValue = () => {
           aspect-ratio: 1/1;
 
           /* UI */
-          /* padding: calc(calc(var(--input-toggle-symbol-size) - var(--_icon-font-size)) / 2); */
           border: var(--input-toggle-symbol-border-width) solid var(--toggle-switch-symbol-border, var(--theme-text));
           outline: var(--input-toggle-symbol-outline-width) solid transparent;
           border-radius: var(--_border-radius);

package/app/components/05.forms/toggle-switch/{variants/ToggleSwitchWithLabel.vue → ToggleSwitchWithLabel.vue}

@@ -1,10 +1,8 @@
 <template>
   <div class="toggle-switch-with-label" :class="[elementClasses]" :data-theme="formUiTheme">
     <InputLabel
-      :id
-      :for="toggleSwitchId"
-      :theme
-      :name
+      :id="toggleSwitchId"
+      indicator="none"
       input-variant="normal"
       :field-has-error
       :style-class-passthrough="['input-switch-label', 'input-text-label', 'body-normal-bold']"
@@ -25,7 +23,7 @@
       :false-value
       :theme
       :round
-      :aria-describedby
+      :aria-describedby="ariaDescribedby()"
     >
       <template v-if="slots.iconOn" #iconOn>
         <slot name="iconOn"></slot>
@@ -79,10 +77,10 @@ const toggleSwitchId = computed(() => `toggle-switch-${id}`);
 const descriptionId = computed(() => `${id}-description`);
 const errorId = computed(() => `${id}-error-message`);
 
-const ariaDescribedby = computed(() => {
+const ariaDescribedby = () => {
   const ariaDescribedbyId = slots.description ? descriptionId.value : undefined;
   return props.fieldHasError ? errorId.value : ariaDescribedbyId;
-});
+};
 
 const modelValue = defineModel<string | number | boolean>({ required: true });
 const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);

package/app/components/05.forms/toggle-switch/{variants/ToggleSwitchWithLabelInline.vue → ToggleSwitchWithLabelInline.vue}

@@ -1,10 +1,8 @@
 <template>
   <div class="toggle-switch-with-label-inline" :class="[elementClasses]" :data-theme="theme">
     <InputLabel
-      :id
-      :for="toggleSwitchId"
-      :theme
-      :name
+      :id="toggleSwitchId"
+      indicator="none"
       input-variant="normal"
       :style-class-passthrough="['input-switch-label', 'input-text-label', labelWeightClass]"
     >

package/app/components/05.forms/toggle-switch/stories/ToggleSwitchWithLabel.stories.ts

@@ -1,6 +1,6 @@
 import type { Meta, StoryFn } from "@nuxtjs/storybook";
 import { ref } from "vue";
-import StorybookComponent from "../variants/ToggleSwitchWithLabel.vue";
+import StorybookComponent from "../ToggleSwitchWithLabel.vue";
 import type { FormUiTheme } from "~/types/forms/types.forms.d";
 
 interface ToggleSwitchWithLabelStoryArgs {

package/app/components/05.forms/toggle-switch/stories/ToggleSwitchWithLabelInline.stories.ts

@@ -1,6 +1,6 @@
 import type { Meta, StoryFn } from "@nuxtjs/storybook";
 import { ref } from "vue";
-import StorybookComponent from "../variants/ToggleSwitchWithLabelInline.vue";
+import StorybookComponent from "../ToggleSwitchWithLabelInline.vue";
 import type { FormUiTheme, LabelWeight } from "~/types/forms/types.forms.d";
 
 interface ToggleSwitchWithLabelInlineStoryArgs {
@@ -278,3 +278,6 @@ export const InlineFormExample: StoryFn = () => ({
     </div>
   `,
 });
+
+// Fixed showcase: hardcoded values, so Controls would do nothing here.
+InlineFormExample.parameters = { controls: { disable: true } };

package/app/components/05.forms/toggle-switch/{variants/tests → tests}/ToggleSwitchWithLabel.spec.ts

@@ -2,6 +2,7 @@
 import type { VueWrapper } from "@vue/test-utils";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
 import ComponentUnderTest from "../ToggleSwitchWithLabel.vue";
+import { defineComponent, nextTick, ref } from "vue";
 
 const initialPropsData = {
   name: "notifications",
@@ -74,4 +75,29 @@ describe("ToggleSwitchWithLabel", () => {
     expect(core.props("round")).toBe(false);
     expect(wrapper.find(".toggle-switch-core").attributes("round")).toBeUndefined();
   });
+
+  it("points aria-describedby at the description once it appears after mount", async () => {
+    const Host = defineComponent({
+      components: { ComponentUnderTest },
+      setup() {
+        return { modelValue: ref(false), showDescription: ref(false) };
+      },
+      template: `
+        <ComponentUnderTest v-model="modelValue" name="notifications" label="Enable notifications" error-message="">
+          <template v-if="showDescription" #description>Sends at most one email a week.</template>
+        </ComponentUnderTest>
+      `,
+    });
+    const host = await mountSuspended(Host);
+    const input = () => host.find("input[type='checkbox']");
+    expect(input().attributes("aria-describedby")).toBeFalsy();
+    (host.vm as unknown as { showDescription: boolean }).showDescription = true;
+    await nextTick();
+    expect(input().attributes("aria-describedby")).toMatch(/-description$/);
+  });
+
+  it("points aria-describedby at the error message when the field has an error", async () => {
+    wrapper = await wrapperFactory({ fieldHasError: true, errorMessage: "Required" });
+    expect(wrapper.find("input[type='checkbox']").attributes("aria-describedby")).toMatch(/-error-message$/);
+  });
 });

package/app/components/05.forms/triple-toggle-switch/CONSUMER-STYLING.md

@@ -1,70 +1,77 @@
-# TripleToggleSwitchCore — Consumer Styling Guide
+# TripleToggleSwitch — Consumer Styling Guide
+
+> **Renamed 2026-09-27**: `TripleToggleSwitchCore` → `TripleToggleSwitch`. The root class was
+> already `.triple-toggle-switch`, and no token names changed.
 
 ## Public token API
 
-Every colour token below is `var(--triple-toggle-switch-*, {default})` — set the
-`--triple-toggle-switch-*` name to override just this component; leave it unset and it inherits
-the shared `--theme-*` token every other themed component also falls back to. See
-`theming-component-token-pattern.md` for why this two-tier shape exists.
+Colour tokens fall back to the shared `--theme-*` tokens every other themed component uses, so
+leave them unset to follow the site theme. See `theming-component-token-pattern.md`.
+
+### Wrapper
 
-| Token | Falls back to | Controls |
+| Token | Default | Controls |
 |---|---|---|
 | `--triple-toggle-switch-surface` | `var(--theme-input-surface)` | Wrapper background |
 | `--triple-toggle-switch-border` | `var(--theme-border)` | Wrapper border colour |
-| `--triple-toggle-switch-ring-focus` | `var(--theme-ring)` | Wrapper outline colour on `:focus-visible` |
-| `--triple-toggle-switch-marker-surface` | `var(--theme-input-surface)` | Selected-option marker background, when none of the `system`/`light`/`dark` `:has()` overrides below match |
-| `--triple-toggle-switch-marker-border` | `var(--slate-10)` | Selected-option marker border colour |
-| `--triple-toggle-switch-option-border` | `#00000025` | Each option's resting border colour |
-| `--triple-toggle-switch-option-border-hover` | `var(--slate-10)` | Each option's outline colour on hover |
-| `--triple-toggle-switch-option-ring-focus` | `var(--theme-ring)` | Each option's outline colour on `:focus-visible` |
-| `--triple-toggle-switch-option-icon-color` | `var(--slate-10)` | Option icon colour, resting (shared by the `.system`/`.light`/`.dark` selectors — see note) |
-| `--triple-toggle-switch-option-icon-color-active` | `var(--slate-00)` | Option icon colour, selected |
-
-> **Two bugs fixed in this migration**:
->
-> 1. `--triple-toggle-switch-marker-surface` replaces a reference to `--theme-form-checkbox-bg`, a
->    token declared nowhere in this layer at all — an undefined `var()` with no fallback silently
->    resolves to the property's initial value, so the marker had no visible background whenever
->    none of the value-specific `:has()` overrides matched. Two more dead tokens
->    (`--theme-form-radio-border`, `--theme-form-radio-outline`, both also undeclared anywhere)
->    fed two further-unused private locals and were removed outright.
-> 2. The `.system`/`.light`/`.dark` `:has(input[value="..."])` selectors and matching
->    `.option-icon.system/.light/.dark` classes used to say `"auto"` instead of `"system"` — but
->    the only known consumer, `DisplayThemeSwitch`, has only ever emitted `id`/`value: "system"`
->    (matching `useSettingsStore`'s `colourScheme` type, which the presentational side has to
->    track). `"auto"` never matched anything real, so the system option's green gradient marker
->    had never actually fired. Renamed the selectors to `"system"` rather than the data, since the
->    data value is a real external contract (`useSettingsStore.setColourScheme` applies it as a
->    literal CSS class on `<html>` elsewhere in the app) and the selectors are this component's own
->    presentational-only concern.
->
-> **`.system`/`.light`/`.dark` selectors**: the component hardcodes these three option *values* as
-> CSS class selectors rather than being value-agnostic — a legacy of its one real consumer,
-> `DisplayThemeSwitch`'s light/dark/system theme picker. All three already shared identical colour
-> values before this migration; only the repeated literal values became tokens here, the selectors
-> themselves are otherwise unchanged (so anything already targeting them by their corrected names
-> keeps working). Making the component genuinely value-agnostic would be a larger, separate change.
-
-## Sizing tokens
+| `--triple-toggle-switch-ring-focus` | `var(--theme-ring)` | Wrapper outline colour while a radio has `:focus-visible` |
+| `--triple-toggle-switch-padding` | `0.6rem` | Wrapper padding |
+| `--triple-toggle-switch-gap` | `1rem` | Gap between the three options (also drives the marker's position) |
+
+### Selected-option marker
+
+| Token | Default | Controls |
+|---|---|---|
+| `--triple-toggle-switch-marker-surface` | `var(--theme-input-surface)` | Marker background when the selected value isn't `system`/`light`/`dark` |
+| `--triple-toggle-switch-marker-border` | `var(--slate-10)` | Marker border colour |
+| `--triple-toggle-switch-marker-gradient-system` | green `radial-gradient(...)` | Marker `background-image` when `system` is selected |
+| `--triple-toggle-switch-marker-gradient-light` | red/orange `radial-gradient(...)` | Marker `background-image` when `light` is selected |
+| `--triple-toggle-switch-marker-gradient-dark` | black/grey `radial-gradient(...)` | Marker `background-image` when `dark` is selected |
+
+> **Changed 2026-09-27**: the three marker gradients were hardcoded literals with no override hook.
+> They're now public tokens; the defaults are unchanged. Any `<image>` value works
+> (`linear-gradient(...)`, `url(...)`, `none`).
+
+### Options
 
 | Token | Default | Controls |
 |---|---|---|
-| `--triple-toggle-switch-gap` | `1rem` | Gap between the three option circles |
-| `--triple-toggle-switch-padding` | `0.6rem` | Wrapper padding |
 | `--triple-toggle-switch-option-padding` | `0.5rem` | Padding inside each option circle |
-| `--triple-toggle-switch-icon-size` | `2rem` | Icon font-size inside each option |
+| `--triple-toggle-switch-icon-size` | `2rem` | Icon `font-size` (and the hidden radio's hit area) |
+| `--triple-toggle-switch-option-border` | `#00000025` | Each option's resting border colour |
+| `--triple-toggle-switch-option-border-hover` | `var(--slate-10)` | Option outline colour on icon hover |
+| `--triple-toggle-switch-option-ring-focus` | `var(--theme-ring)` | Option outline colour on `:focus-visible` |
+| `--triple-toggle-switch-option-icon-color` | `var(--slate-10)` | Icon colour, resting |
+| `--triple-toggle-switch-option-icon-color-active` | `var(--slate-00)` | Icon colour, selected |
+
+Also read (shared, not component-specific): `--form-element-border-width`,
+`--form-element-outline-width`, `--theme-form-transition-duration`. See
+`theming-form-geometry-tokens.md`.
+
+Private tokens (not public API): `--_form-items-gap`, `--_scheme-icon-font-size` (each used twice,
+fed by the public gap/icon-size tokens) and `--_select-scheme-group-background-color`/
+`--_select-scheme-group-background-image` (swapped per selected value).
 
-Added 2026-09-20 when `DisplayThemeSwitch`'s `small` variant was found reaching directly into this
-component's private `--_form-items-gap`/`--_form-padding`/`--_select-scheme-group-padding`/
-`--_scheme-icon-font-size` locals via selector specificity — a consumer-relevant value (compact
-sizing) hidden behind a private var with no public override hook, the same bug class as CLAUDE.md
-pitfall #20. These four now wrap those locals as real public tokens; the shared geometry from
-`--form-element-*` (border width, outline width) is still shared/component-internal and untouched
-by this — see `theming-form-geometry-tokens.md` for that half.
+## State hooks
 
----
+- **Selected value**: the marker gradients key off `:has(input[value="system" | "light" | "dark"]:checked)`
+  on the root. These three values are hardcoded, a legacy of the one real consumer
+  (`DisplayThemeSwitch`). Any other value shows `--triple-toggle-switch-marker-surface` instead.
+- **Option icon classes**: each `.option-icon` carries the option's `id` as a class (e.g.
+  `.option-icon.light`) plus `.active` when selected.
+- **Marker**: `.selected-option-marker` gains `.show` roughly 250ms after mount (it's positioned
+  from a measured option width, so it stays hidden until measured).
+- **Theme**: `data-theme` on the root, from the `theme` prop.
+- **Inner classes**: `.triple-toggle-switch-wrapper`, `.selected-option-marker-wrapper`,
+  `.selected-option-marker`, `.option-group-wrapper` (the `role="radiogroup"`), `.option-group`
+  (each `<label>`), `.option-icon`, `.option-input`.
 
-## Global theming — app-level CSS file
+## Motion
+
+The marker slides between options over the `stepAnimationDuration` prop (default `250ms`). Under
+`prefers-reduced-motion: reduce` the slide transition is removed and the marker jumps.
+
+## Global theming
 
 ```css
 :where(html) {
@@ -73,14 +80,20 @@ by this — see `theming-form-geometry-tokens.md` for that half.
 }
 ```
 
----
+## Local overrides
 
-## Per-instance 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`.
 
-```vue
-<TripleToggleSwitchCore
-  v-model="scheme"
-  v-model:field-data="options"
-  style="--triple-toggle-switch-marker-surface: var(--gold-06);"
-/>
-```
+**Caveat:** when used through `DisplayThemeSwitch`, that wrapper re-declares the four sizing tokens
+(`--triple-toggle-switch-gap`, `-padding`, `-option-padding`, `-icon-size`) on the root element, so
+setting them on an ancestor has no effect there. Set them on the component itself (via
+`style` or a passthrough class) instead. Used directly, `TripleToggleSwitch` re-declares nothing.
+
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root `.triple-toggle-switch` element, alongside
+`data-theme`. `DisplayThemeSwitch` uses it for its `colour-scheme-select` and `small` classes.