srcdev-nuxt-components 9.6.9 → 9.6.11

package/app/components/05.forms/input-label/stories/InputLabel.stories.ts

@@ -1,7 +1,9 @@
 import type { Meta, StoryFn } from "@nuxtjs/storybook";
-import { computed } from "vue";
+import { computed, ref } from "vue";
 import StorybookComponent from "../InputLabel.vue";
+import CanvasSwitcher from "../../../01.atoms/canvas-switcher/CanvasSwitcher.vue";
 import type { InputUiVariant, InputLabelIndicator } from "~/types/forms/types.forms";
+import type { MediaCanvas } from "~/types/components";
 
 interface InputLabelStoryArgs {
   id: string;
@@ -109,8 +111,43 @@ export default {
     textLabel: "Email address",
     htmlLabel: "",
   },
+  decorators: [
+    (story, context) => ({
+      components: { story, CanvasSwitcher },
+      setup() {
+        const canvasName = ref<MediaCanvas>(context.parameters.initialCanvas ?? "fullWidthCanvas");
+        return { canvasName };
+      },
+      template: `
+        <div style="padding: 1.2rem 1.6rem; border-block-end: 1px solid currentColor;">
+          <CanvasSwitcher v-model:canvas-name="canvasName" />
+        </div>
+        <div :class="canvasName" style="margin-inline: auto; padding: 2rem; outline: 1px dashed currentColor;">
+          <story />
+        </div>
+      `,
+    }),
+  ],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "The `<label>` every labelled field wrapper renders. Label copy goes in the `textLabel` and `htmlLabel` slots (html first), `id` becomes its `for`, and `indicator` with `required` adds a required or optional marker (falling back to `app.config` `srcdev.inputLabel`). `field-has-error` and `input-variant` are styling hooks only. The control in these stories is a plain input; see [InputTextField](?path=/story/components-forms-input-text-inputtextfield--required) for it inside a real field.",
+      },
+    },
+  },
 } as Meta<InputLabelStoryArgs>;
 
+// Links in the canvas open in the Storybook manager (target="_top"), not inside the preview iframe.
+const storyNoteStyle = "margin: 0 0 1.6rem; font-size: 1.4rem;";
+const fieldNote = `
+  <p style="${storyNoteStyle}">
+    Every labelled field wrapper renders this label and forwards its own <code>required</code> prop. See it in a real field in the
+    <a href="/?path=/story/components-forms-input-text-inputtextfield--required" target="_top">InputTextField</a> story.
+  </p>
+`;
+
 const Template: StoryFn<InputLabelStoryArgs> = (args) => ({
   components: { StorybookComponent },
   setup() {
@@ -133,7 +170,8 @@ const Template: StoryFn<InputLabelStoryArgs> = (args) => ({
     return { args, componentArgs, tokenStyles };
   },
   template: `
-    <div style="max-width: 48rem; margin: 3.6rem; font-size: 1.6rem;" :style="tokenStyles">
+    <div style="max-width: 48rem; font-size: 1.6rem;" :style="tokenStyles">
+      ${fieldNote}
       <StorybookComponent v-bind="componentArgs">
         <template v-if="args.htmlLabel" #htmlLabel><span v-html="args.htmlLabel"></span></template>
         <template v-if="args.textLabel" #textLabel>{{ args.textLabel }}</template>
@@ -150,17 +188,26 @@ const Template: StoryFn<InputLabelStoryArgs> = (args) => ({
 });
 
 export const TextLabel = Template.bind({});
+TextLabel.parameters = {
+  docs: { description: { story: "Plain label text through the `textLabel` slot." } },
+};
 
 export const HtmlLabel = Template.bind({});
 HtmlLabel.args = {
   textLabel: "",
   htmlLabel: 'Email address <small style="font-weight: normal;">(work or personal)</small>',
 };
+HtmlLabel.parameters = {
+  docs: { description: { story: "Rich markup through the `htmlLabel` slot." } },
+};
 
 export const TextAndHtml = Template.bind({});
 TextAndHtml.args = {
   htmlLabel: "<strong>Work</strong> ",
 };
+TextAndHtml.parameters = {
+  docs: { description: { story: "Both slots filled: `htmlLabel` renders first, then `textLabel`." } },
+};
 
 export const MarkRequired = Template.bind({});
 MarkRequired.args = { indicator: "required", required: true };
@@ -234,3 +281,22 @@ CustomTokens.decorators = [
     `,
   }),
 ];
+
+export const StressTest = Template.bind({});
+StressTest.storyName = "Stress Test (Worst-Case Data)";
+StressTest.args = {
+  textLabel:
+    "📧 Elektronischepostadressefürdiebenachrichtigungüberbestellungen https://example.com/a/very/long/unbroken/url/for/the/label <b>not bold</b> البريد الإلكتروني",
+  indicator: "optional",
+  required: false,
+  optionalText: "(freiwilligeAngabekeinePflichtfeldbitteleerlassenwennnichtzutreffend)",
+};
+StressTest.parameters = {
+  initialCanvas: "mobileCanvas",
+  docs: {
+    description: {
+      story:
+        "Long unbroken German, a long URL, emoji, HTML-like and right-to-left text in the label, plus an unbroken optional marker. Check at every canvas width: the label and the marker wrap inside the dashed outline, markup renders as text, and the marker stays after the text in RTL. Switch `indicator` to required and turn `required` on to check the required marker. Label copy arrives through slots, so there is no line-clamp token: clamp your own slot markup if you need to.",
+    },
+  },
+};

package/app/components/05.forms/input-label/tests/InputLabel.spec.ts

@@ -1,14 +1,24 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, afterEach, vi } from "vitest";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
 import InputLabel from "../InputLabel.vue";
 
-const createWrapper = (props = {}, slots = {}) =>
-  mountSuspended(InputLabel, {
+const mounted: { unmount: () => void }[] = [];
+
+const createWrapper = async (props = {}, slots = {}) => {
+  const wrapper = await mountSuspended(InputLabel, {
     props: { id: "test-input", ...props },
     slots,
   });
+  mounted.push(wrapper);
+  return wrapper;
+};
 
 describe("InputLabel", () => {
+  afterEach(() => {
+    mounted.splice(0).forEach((wrapper) => wrapper.unmount());
+    vi.restoreAllMocks();
+  });
+
   describe("rendering", () => {
     it("renders a label linked to the control id", async () => {
       const wrapper = await createWrapper({ id: "email-input" });

package/app/components/05.forms/input-number/CONSUMER-STYLING.md

@@ -18,7 +18,8 @@ token, same as `InputText`.
 | `--input-number-surface` | `var(--theme-input-surface)` | Wrapper, input, and embedded-button background |
 | `--input-number-surface-hover` | `var(--theme-input-surface-hover)` | Embedded left/right button background on hover |
 | `--input-number-border` | `var(--theme-border)` | Border/divider colour (`normal`/`underlined` variant border, and the divider between the input and an embedded button) |
-| `--input-number-border-hover` | `var(--theme-border-focus)` | Wrapper outline colour on mouse hover over the input or either step button (`normal` variant only) |
+| `--input-number-border-hover` | the resolved border | 1px wrapper outline colour on mouse hover over the input or either step button (`normal` variant only) |
+| `--input-number-shadow` | `var(--form-element-shadow-colour, var(--colour-theme-2))` | Resting shadow ring outside the border (`normal` only). Width is the global `--form-element-shadow-width` (`0.2rem`; `0` removes it) |
 | `--input-number-border-focus` | `var(--theme-border-focus)` | Wrapper outline colour on `:focus-visible` (`normal` variant), and the embedded button's own `:focus-visible` outline |
 | `--input-number-text-color` | `var(--theme-input-text-color-normal)` | Input text colour |
 | `--input-number-placeholder-color` | `var(--theme-input-placeholder)` | Placeholder text colour |
@@ -33,6 +34,11 @@ and `step` and capped at `12em`).
 
 ---
 
+> **Changed 2026-10-17**: bordered controls carry a light shadow ring (`box-shadow`, theme step 2,
+> so red when invalid), and hover draws a 1px outline in the border colour with no offset, over the
+> ring's inner edge. Hover used to draw a 2px outline at a 2px offset in the focus colour. Focus is
+> unchanged and sits just outside the ring.
+
 ## State hooks
 
 | Attribute | On | When |

package/app/components/05.forms/input-number/InputNumber.vue

@@ -123,11 +123,10 @@ const inputmode = computed(() => {
       border: var(--form-element-border-width) solid var(--_border);
       border-radius: var(--form-input-border-radius);
       outline: var(--form-element-outline-width) solid transparent;
+      box-shadow: 0 0 0 var(--form-element-shadow-width) var(--input-number-shadow, var(--form-element-shadow-colour, var(--colour-theme-2)));
 
       &:has(input:hover, button:hover) {
-        outline: var(--form-element-outline-width-focus) solid
-          var(--input-number-border-hover, var(--theme-border-focus));
-        outline-offset: var(--form-element-outline-offset-focus);
+        outline-color: var(--input-number-border-hover, var(--_border));
       }
 
       &:has(input:focus-visible, button:focus-visible) {
@@ -167,8 +166,8 @@ const inputmode = computed(() => {
           outline-offset: -4px;
         }
 
-        &.icon-only {
-          .btn-icon {
+        &[data-icon-only] {
+          & .input-button-icon {
             margin: 0;
           }
         }

package/app/components/05.forms/input-otp/CONSUMER-STYLING.md

@@ -18,7 +18,8 @@ for the two-tier shape.
 | `--input-otp-surface` | `var(--theme-input-surface)` | Box background |
 | `--input-otp-text-color` | `var(--theme-input-text-color-normal)` | Digit colour |
 | `--input-otp-border` | `var(--theme-border)` | Box border (`normal`) or bottom border (`underlined`) |
-| `--input-otp-border-hover` | `var(--input-otp-border-focus)` | Outline colour on hover (`normal` variant) |
+| `--input-otp-border-hover` | the resolved border | 1px outline colour on hover (`normal` variant) |
+| `--input-otp-shadow` | `var(--form-element-shadow-colour, var(--colour-theme-2))` | Resting shadow ring outside the border (each box, `normal` only). Width is the global `--form-element-shadow-width` (`0.2rem`; `0` removes it) |
 | `--input-otp-border-focus` | `var(--theme-border-focus)` | Outline colour on `:focus-visible`, and the bottom border colour on focus (`underlined`) |
 
 ### Field (`InputOtpField`)
@@ -35,6 +36,11 @@ Border/outline widths and transition duration are the shared form geometry token
 Private tokens (not public API): `--_border` and `--_border-focus` on `.input-otp`, which only
 resolve the two public border tokens once for reuse across the variant rules.
 
+> **Changed 2026-10-17**: bordered controls carry a light shadow ring (`box-shadow`, theme step 2,
+> so red when invalid), and hover draws a 1px outline in the border colour with no offset, over the
+> ring's inner edge. Hover used to draw a 2px outline at a 2px offset in the focus colour. Focus is
+> unchanged and sits just outside the ring.
+
 ## State hooks
 
 | Hook | Where | Meaning |

package/app/components/05.forms/input-otp/InputOtp.vue

@@ -230,10 +230,10 @@ function onFocus(event: FocusEvent) {
       border: var(--form-element-border-width) solid var(--_border);
       border-radius: var(--input-otp-border-radius, var(--form-input-border-radius));
       outline: var(--form-element-outline-width) solid transparent;
+      box-shadow: 0 0 0 var(--form-element-shadow-width) var(--input-otp-shadow, var(--form-element-shadow-colour, var(--colour-theme-2)));
 
       &:hover {
-        outline: var(--form-element-outline-width-focus) solid var(--input-otp-border-hover, var(--_border-focus));
-        outline-offset: var(--form-element-outline-offset-focus);
+        outline-color: var(--input-otp-border-hover, var(--_border));
       }
 
       &:focus-visible {

package/app/components/05.forms/input-range/InputRange.vue

@@ -103,7 +103,7 @@ watch(
         width: var(--input-range-button-size);
         height: var(--input-range-button-size);
 
-        .btn-icon {
+        & .input-button-icon {
           margin: initial;
         }
       }

package/app/components/05.forms/input-select/CONSUMER-STYLING.md

@@ -17,7 +17,8 @@ to override just this component; leave it unset and it inherits the shared `--th
 | `--input-select-surface` | `var(--theme-input-surface)` | Wrapper/select background |
 | `--input-select-text-color` | `var(--theme-input-text-color-normal)` | Select text colour (added 2026-10-16; it inherited the page colour before) |
 | `--input-select-border` | `var(--theme-border)` | Border colour (`normal`/`underlined` variants and the open picker, resting) |
-| `--input-select-border-hover` | `var(--theme-border-focus)` | Outline colour on hover (mouse) |
+| `--input-select-border-hover` | the resolved border (`normal`), `var(--theme-border-focus)` (`underlined`) | Outline colour on hover (mouse): 1px with no offset on `normal`, 2px at a 2px offset on `underlined` |
+| `--input-select-shadow` | `var(--form-element-shadow-colour, var(--colour-theme-2))` | Resting shadow ring outside the border (`normal` only). Width is the global `--form-element-shadow-width` (`0.2rem`; `0` removes it) |
 | `--input-select-border-focus` | `var(--theme-border-focus)` | Outline colour on `:focus-visible` (keyboard/assistive), and the open picker's outline |
 
 ### Options
@@ -41,6 +42,11 @@ shows and ignores them.
 
 ---
 
+> **Changed 2026-10-17**: bordered controls carry a light shadow ring (`box-shadow`, theme step 2,
+> so red when invalid), and hover draws a 1px outline in the border colour with no offset, over the
+> ring's inner edge. Hover used to draw a 2px outline at a 2px offset in the focus colour. Focus is
+> unchanged and sits just outside the ring.
+
 ## State hooks
 
 | Attribute | On | When |

package/app/components/05.forms/input-select/InputSelect.vue

@@ -112,16 +112,25 @@ watch(
       border: var(--form-element-border-width) solid var(--_border);
       border-radius: var(--form-input-border-radius);
       outline: var(--form-element-outline-width) solid transparent;
+      box-shadow: 0 0 0 var(--form-element-shadow-width) var(--input-select-shadow, var(--form-element-shadow-colour, var(--colour-theme-2)));
+
+      &:has(:hover) {
+        outline-color: var(--input-select-border-hover, var(--_border));
+      }
+
+      &:has(select:focus-visible) {
+        outline-color: var(--_border-focus);
+      }
     }
 
     &[data-input-variant="underlined"] {
       border-bottom: var(--form-element-border-bottom-width-underlined) solid var(--_border);
-    }
 
-    &:has(:hover) {
-      outline: var(--form-element-outline-width-focus) solid
-        var(--input-select-border-hover, var(--theme-border-focus));
-      outline-offset: var(--form-element-outline-offset-focus);
+      &:has(:hover) {
+        outline: var(--form-element-outline-width-focus) solid
+          var(--input-select-border-hover, var(--theme-border-focus));
+        outline-offset: var(--form-element-outline-offset-focus);
+      }
     }
 
     &:has(select:focus-visible) {

package/app/components/05.forms/input-text/CONSUMER-STYLING.md

@@ -17,7 +17,8 @@ override just this component; leave it unset and it inherits the shared `--theme
 | `--input-text-surface` | `var(--theme-input-surface)` | Wrapper background, and slot `InputButton` background |
 | `--input-text-surface-hover` | `var(--theme-input-surface-hover)` | Slot `InputButton` background on hover |
 | `--input-text-border` | `var(--theme-border)` | Border colour (`normal`/`underlined`, resting), and the stepper's button dividers |
-| `--input-text-border-hover` | `var(--theme-border-focus)` | Outline colour on hover (`normal` only) |
+| `--input-text-border-hover` | the resolved border | 1px outline colour on hover (`normal` only) |
+| `--input-text-shadow` | `var(--form-element-shadow-colour, var(--colour-theme-2))` | Resting shadow ring outside the border (`normal` only). Width is the global `--form-element-shadow-width` (`0.2rem`; `0` removes it) |
 | `--input-text-border-focus` | `var(--theme-border-focus)` | Outline colour on `:focus-visible` (`normal` only), and a slot button's own focus outline |
 | `--input-text-color` | `var(--theme-input-text-color-normal)` | Input text and slot button colour, and autofilled text (global rule) |
 | `--input-text-placeholder-color` | `var(--theme-input-placeholder)` | Placeholder text colour |
@@ -31,6 +32,11 @@ read in several places.
 
 ---
 
+> **Changed 2026-10-17**: bordered controls carry a light shadow ring (`box-shadow`, theme step 2,
+> so red when invalid), and hover draws a 1px outline in the border colour with no offset, over the
+> ring's inner edge. Hover used to draw a 2px outline at a 2px offset in the focus colour. Focus is
+> unchanged and sits just outside the ring.
+
 ## State hooks
 
 | Attribute | On | When |

package/app/components/05.forms/input-text/InputText.vue

@@ -131,12 +131,12 @@ watch(
       border: var(--form-element-border-width) solid var(--_border);
       border-radius: var(--form-input-border-radius);
       outline: var(--form-element-outline-width) solid transparent;
+      box-shadow: 0 0 0 var(--form-element-shadow-width) var(--input-text-shadow, var(--form-element-shadow-colour, var(--colour-theme-2)));
 
       padding-inline: var(--input-padding-inline);
 
       &:has(input:is(:hover), button:is(:hover)) {
-        outline: var(--form-element-outline-width-focus) solid var(--input-text-border-hover, var(--theme-border-focus));
-        outline-offset: var(--form-element-outline-offset-focus);
+        outline-color: var(--input-text-border-hover, var(--_border));
       }
 
       &:has(input:focus-visible, button:focus-visible) {
@@ -180,8 +180,8 @@ watch(
           outline-offset: -4px;
         }
 
-        &.icon-only {
-          .btn-icon {
+        &[data-icon-only] {
+          & .input-button-icon {
             margin: 0;
           }
         }

package/app/components/05.forms/input-textarea/CONSUMER-STYLING.md

@@ -18,7 +18,8 @@ This shape mirrors `InputText`'s token set (see its own CONSUMER-STYLING.md).
 |---|---|---|
 | `--input-textarea-surface` | `var(--theme-input-surface)` | Wrapper background |
 | `--input-textarea-border` | `var(--theme-border)` | Border colour (`normal`/`underlined` variant border) |
-| `--input-textarea-border-hover` | `var(--theme-border-focus)` | Wrapper outline colour on mouse hover (`normal` only) |
+| `--input-textarea-border-hover` | the resolved border | 1px wrapper outline colour on mouse hover (`normal` only) |
+| `--input-textarea-shadow` | `var(--form-element-shadow-colour, var(--colour-theme-2))` | Resting shadow ring outside the border (`normal` only). Width is the global `--form-element-shadow-width` (`0.2rem`; `0` removes it) |
 | `--input-textarea-border-focus` | `var(--theme-border-focus)` | Wrapper outline colour on `:focus-visible` (`normal` only) |
 | `--input-textarea-text-color` | `var(--theme-input-text-color-normal)` | Textarea text colour |
 | `--input-textarea-placeholder-color` | `var(--theme-input-placeholder)` | Placeholder text colour |
@@ -41,6 +42,11 @@ Private (not public API): `--_border`, resolved once and read by both border var
 
 ---
 
+> **Changed 2026-10-17**: bordered controls carry a light shadow ring (`box-shadow`, theme step 2,
+> so red when invalid), and hover draws a 1px outline in the border colour with no offset, over the
+> ring's inner edge. Hover used to draw a 2px outline at a 2px offset in the focus colour. Focus is
+> unchanged and sits just outside the ring.
+
 ## State hooks
 
 | Attribute | On | When |

package/app/components/05.forms/input-textarea/InputTextarea.vue

@@ -105,11 +105,10 @@ watch(
       border: var(--form-element-border-width) solid var(--_border);
       border-radius: var(--form-input-border-radius);
       outline: var(--form-element-outline-width) solid transparent;
+      box-shadow: 0 0 0 var(--form-element-shadow-width) var(--input-textarea-shadow, var(--form-element-shadow-colour, var(--colour-theme-2)));
 
       &:has(textarea:is(:hover)) {
-        outline: var(--form-element-outline-width-focus) solid
-          var(--input-textarea-border-hover, var(--theme-border-focus));
-        outline-offset: var(--form-element-outline-offset-focus);
+        outline-color: var(--input-textarea-border-hover, var(--_border));
       }
 
       &:has(textarea:focus-visible) {

package/app/components/05.forms/patterns/stories/MigratedFieldsForm.stories.ts

@@ -12,7 +12,7 @@ import ToggleSwitchField from "../../toggle-switch/ToggleSwitchField.vue";
 import MultipleCheckboxes from "../../input-checkbox/MultipleCheckboxes.vue";
 import SingleCheckbox from "../../input-checkbox/SingleCheckbox.vue";
 import MultipleRadiobuttons from "../../input-radio/MultipleRadiobuttons.vue";
-import TripleToggleSwitch from "../../triple-toggle-switch/TripleToggleSwitch.vue";
+import SegmentedControl from "../../segmented-control/SegmentedControl.vue";
 import InputButton from "../../input-button/InputButton.vue";
 import FormField from "../../form-field/FormField.vue";
 import FormWrapper from "../../form-wrapper/FormWrapper.vue";
@@ -31,7 +31,7 @@ interface MigratedFieldsFormStoryArgs {
 //   InputTextAsNumberField, InputRangeField (InputRange), InputNumberField
 //   (InputNumber), InputOtpField (InputOtp), InputTextareaField (InputTextarea), InputSelectField
 //   (InputSelect), ToggleSwitchField, stacked and inline (ToggleSwitch),
-//   MultipleCheckboxes, SingleCheckbox, MultipleRadiobuttons, TripleToggleSwitch ("Theme
+//   MultipleCheckboxes, SingleCheckbox, MultipleRadiobuttons, SegmentedControl ("Theme
 //   preference": no Field wrapper or error state, so it sits under a plain caption).
 // - Rendered inside other fields: FormWrapper (wraps the form), FormField (wraps every field),
 //   FormFieldset (checkbox/radio groups), InputLabel, InputDescription (the "Full name" and
@@ -71,7 +71,7 @@ const Template: StoryFn<MigratedFieldsFormStoryArgs> = (args) => ({
     MultipleCheckboxes,
     SingleCheckbox,
     MultipleRadiobuttons,
-    TripleToggleSwitch,
+    SegmentedControl,
     InputButton,
     FormField,
     FormWrapper,
@@ -418,7 +418,7 @@ const Template: StoryFn<MigratedFieldsFormStoryArgs> = (args) => ({
           <FormField width="wide" :has-gutter="false">
             <div style="display: grid; gap: 0.8rem; justify-items: start;">
               <span>Theme preference</span>
-              <TripleToggleSwitch
+              <SegmentedControl
                 v-model="state.themePreference"
                 v-model:field-data="themeOptions"
                 name="themePreference"

package/app/components/05.forms/pending-effect/CONSUMER-STYLING.md

@@ -8,8 +8,12 @@ directly: `InputButton` renders it when `has-pending-effect` is set, and it anim
 <InputButton button-text="Save" has-pending-effect :is-pending="saving" />
 ```
 
-The CSS keys off the host button's classes: `.pending-effect` (added by `has-pending-effect`),
-`.is-pending`, and `.icon-only`. The SVG itself is `.pending-effect-container`.
+The CSS keys off the host button's state attributes: `.input-button[data-pending-effect]` (added by
+`has-pending-effect`), `[data-pending]`, and `[data-icon-only]`. The SVG itself is
+`.pending-effect-container`.
+
+> **Changed 2026-10-17**: these were the classes `.pending-effect`, `.is-pending` and `.icon-only`
+> until `InputButton` moved its state to `data-*` attributes.
 
 The line sits outside the button's edge, so nothing around it may clip overflow. `InputButton`
 sets `overflow: visible` on itself when `has-pending-effect` is on, but an ancestor with
@@ -50,7 +54,7 @@ positioning maths) and `--_offset` (the resolved `--pending-effect-offset`).
 ## Reduced motion
 
 Under `prefers-reduced-motion: reduce` the effect stays hidden. The host button still gets
-`pointer-events: none` while `.is-pending` is set, from this component's CSS, so it can't be
+`pointer-events: none` while `[data-pending]` is set, from this component's CSS, so it can't be
 clicked twice.
 
 ---

package/app/components/05.forms/pending-effect/PendingEffect.vue

@@ -34,7 +34,7 @@ watch(
 
 <style lang="css">
 @layer components {
-  .pending-effect {
+  .input-button[data-pending-effect] {
     position: relative;
 
     .pending-effect-container {
@@ -72,14 +72,14 @@ watch(
       }
     }
 
-    &.icon-only .pending-effect-container {
+    &[data-icon-only] .pending-effect-container {
       .pending-effect-blur,
       .pending-effect-line {
         rx: var(--pending-effect-border-radius-icon-only, 100vw);
       }
     }
 
-    &.is-pending {
+    &[data-pending] {
       pointer-events: none;
       cursor: wait;
 

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

@@ -54,7 +54,7 @@ describe("PendingEffect", () => {
         props: { buttonText: "Save", hasPendingEffect: true },
       });
       expect(withEffect.find(".pending-effect-container").exists()).toBe(true);
-      expect(withEffect.find("button").classes()).toContain("pending-effect");
+      expect(withEffect.find("button").attributes("data-pending-effect")).toBe("");
     });
 
     it("passes the button theme through", async () => {

package/app/components/05.forms/segmented-control/CONSUMER-STYLING.md

@@ -0,0 +1,125 @@
+# SegmentedControl — Consumer Styling Guide
+
+> **Renamed 2026-10-17**: `TripleToggleSwitch` → `SegmentedControl`, since it handles any number
+> of options. Every class and token changed prefix: `.triple-toggle-switch*` → `.segmented-control*`
+> and `--triple-toggle-switch-*` → `--segmented-control-*`, with the rest of each name unchanged.
+>
+> **Renamed 2026-09-27**: `TripleToggleSwitchCore` → `TripleToggleSwitch`. The root class was
+> already `.triple-toggle-switch`, and no token names changed.
+
+## Public token API
+
+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 | Default | Controls |
+|---|---|---|
+| `--segmented-control-surface` | `var(--theme-input-surface)` | Wrapper background |
+| `--segmented-control-border` | `var(--theme-border)` | Wrapper border colour |
+| `--segmented-control-border-hover` | the resolved border | 1px wrapper outline colour on hover |
+| `--segmented-control-shadow` | `var(--form-element-shadow-colour, var(--colour-theme-2))` | Resting shadow ring outside the border (on the wrapper). Width is the global `--form-element-shadow-width` (`0.2rem`; `0` removes it) |
+| `--segmented-control-ring-focus` | `var(--theme-ring)` | Wrapper outline colour while a radio has `:focus-visible` |
+| `--segmented-control-padding` | `0.6rem` | Wrapper padding |
+| `--segmented-control-gap` | `1rem` | Gap between the options (also drives the marker's position) |
+
+### Selected-option marker
+
+| Token | Default | Controls |
+|---|---|---|
+| `--segmented-control-marker-surface` | `var(--theme-surface)` | Marker background when the selected value isn't `system`/`light`/`dark` |
+| `--segmented-control-marker-border` | `var(--theme-text)` | Marker border colour |
+| `--segmented-control-marker-gradient-system` | green `radial-gradient(...)` | Marker `background-image` when `system` is selected |
+| `--segmented-control-marker-gradient-light` | red/orange `radial-gradient(...)` | Marker `background-image` when `light` is selected |
+| `--segmented-control-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 |
+|---|---|---|
+| `--segmented-control-option-padding` | `0.5rem` | Padding inside each option circle |
+| `--segmented-control-icon-size` | `2rem` | Icon `font-size` (and the hidden radio's hit area) |
+| `--segmented-control-option-border` | `#00000025` | Each option's resting border colour |
+| `--segmented-control-option-border-hover` | `var(--theme-text)` | Option outline colour on hover |
+| `--segmented-control-option-ring-focus` | `var(--theme-ring)` | Option outline colour on `:focus-visible` |
+| `--segmented-control-option-icon-color` | `var(--theme-text)` | Icon colour, resting |
+| `--segmented-control-option-icon-color-active` | `var(--theme-on-surface)` | Icon colour, selected |
+
+> **Changed 2026-10-17**: the marker surface defaulted to `--theme-input-surface` (white) while
+> the selected icon defaulted to white too, so any value other than `system`/`light`/`dark` showed
+> a white icon on a white marker. The marker now defaults to `--theme-surface` and the icons to
+> `--theme-text`/`--theme-on-surface`, replacing the raw `--slate-10`/`--slate-00` palette tokens
+> (close to the same colours on the default theme).
+
+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 read in
+several places, fed by the public gap/icon-size tokens) and `--_select-scheme-group-background-color`/
+`--_select-scheme-group-background-image` (swapped per selected value).
+
+> **Changed 2026-10-17**: bordered controls carry a light shadow ring (`box-shadow`, theme step 2,
+> so red when invalid), and hover draws a 1px outline in the border colour with no offset, over the
+> ring's inner edge. Hover used to draw a 2px outline at a 2px offset in the focus colour. Focus is
+> unchanged and sits just outside the ring.
+
+## 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 `--segmented-control-marker-surface` instead.
+- **Each option** (`.segmented-control-option`, the `<label>`) carries `data-value` (the
+  option's value) and `data-checked` when selected. Target one with
+  `.segmented-control-option[data-value="light"]`.
+- **Root** has `data-has-selection` when the value matches an option; without it the marker is
+  hidden.
+- **Theme**: `data-theme` on the root, from the `theme` prop.
+- **Inner classes**: `.segmented-control-wrapper`, `.segmented-control-marker-layer`,
+  `.segmented-control-marker`, `.segmented-control-options` (the `role="radiogroup"`),
+  `.segmented-control-option`, `.segmented-control-option-icon`,
+  `.segmented-control-option-input`.
+
+> **Changed 2026-10-17**: the inner classes were generic (`.selected-option-marker-wrapper`,
+> `.selected-option-marker`, `.option-group-wrapper`, `.option-group`, `.option-icon`,
+> `.option-input`) and collided with consumer CSS. State moved too: `.option-icon.active` →
+> `.segmented-control-option[data-checked]`, `.option-icon.light` (the option id as a class)
+> → `.segmented-control-option[data-value="light"]`, and `.selected-option-marker.show` is gone:
+> the marker is positioned in CSS from the first paint, no measuring.
+
+## 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) {
+  --segmented-control-surface: var(--rose-09);
+  --segmented-control-option-ring-focus: var(--rose-04);
+}
+```
+
+## 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:** when used through `DisplayThemeSwitch`, that wrapper re-declares the four sizing tokens
+(`--segmented-control-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, `SegmentedControl` re-declares nothing.
+
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root `.segmented-control` element, alongside
+`data-theme`. `DisplayThemeSwitch` uses it for its `colour-scheme-select` and `small` classes.