srcdev-nuxt-components 9.3.12 → 9.4.0

package/app/components/05.forms/input-select/stories/InputSelectCore.stories.ts

@@ -0,0 +1,69 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import { ref } from "vue";
+import StorybookComponent from "../InputSelectCore.vue";
+import type { IFormMultipleOptions } from "~/types/forms/types.forms.d";
+
+interface InputSelectCoreStoryArgs {
+  id: string;
+  name: string;
+  placeholder: string;
+  required: boolean;
+  fieldHasError: boolean;
+  inputVariant: "normal" | "outlined" | "underlined";
+}
+
+export default {
+  title: "Components/Forms/Input Select/InputSelectCore",
+  component: StorybookComponent,
+  argTypes: {
+    id: { control: "text", table: { category: "Basic" } },
+    name: { control: "text", table: { category: "Basic" } },
+    placeholder: { control: "text", table: { category: "Basic" } },
+    required: { control: "boolean", table: { category: "Basic" } },
+    fieldHasError: { control: "boolean", table: { category: "States" } },
+    inputVariant: {
+      control: { type: "select" },
+      options: ["normal", "outlined", "underlined"],
+      table: { category: "Styling" },
+    },
+  },
+  args: {
+    id: "select-default",
+    name: "selectDefault",
+    placeholder: "Choose a service",
+    required: false,
+    fieldHasError: false,
+    inputVariant: "normal",
+  },
+} as Meta<InputSelectCoreStoryArgs>;
+
+const Template: StoryFn<InputSelectCoreStoryArgs> = (args) => ({
+  components: { StorybookComponent },
+  setup() {
+    const modelValue = ref<string | number>("");
+    const fieldData = ref<IFormMultipleOptions>({
+      data: [
+        { id: "1", name: "balayage", value: "balayage", label: "Balayage" },
+        { id: "2", name: "highlights", value: "highlights", label: "Highlights" },
+        { id: "3", name: "full-colour", value: "full-colour", label: "Full Colour" },
+      ],
+      total: 3,
+      skip: 0,
+      limit: 10,
+    });
+    return { args, modelValue, fieldData };
+  },
+  template: `
+    <div style="margin: 36px; max-width: 320px;">
+      <StorybookComponent v-bind="args" v-model="modelValue" v-model:field-data="fieldData" />
+    </div>
+  `,
+});
+
+export const Default = Template.bind({});
+
+export const ErrorState = Template.bind({});
+ErrorState.args = { fieldHasError: true };
+
+export const Underlined = Template.bind({});
+Underlined.args = { inputVariant: "underlined" };

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

@@ -1,60 +1,50 @@
 # InputTextCore — Consumer Styling Guide
 
-## Two override paths
-
-Before 2026-08-22, `.input-text-wrapper` read the global `--theme-*` tokens directly
-(`--theme-input-surface`, `--theme-border`, `--theme-border-focus`, `--theme-input-surface-hover`).
-Overriding those globally (e.g. in a consumer app's unlayered `:root` block) should always have
-worked on pure CSS-cascade grounds — an unlayered `:root` declaration (specificity `0,1,0`) beats
-the layer's own `:where(html, [data-theme], [data-invalid])` declaration (specificity `0`)
-regardless of source/import order — but a consumer app hit a case where a global override wasn't
-visibly landing and the root cause wasn't pinned down (see `nuxt-components`'s own git history
-around the same date for a *different*, confirmed bug in a sibling app: wrapping consumer CSS in
-`@layer consumer` broke in production because SSR-inlined per-chunk `<style>` tags fix layer
-priority by first-reference document order, not the app's intended `@layer` statement order — sic
-that isn't what was happening here, since the consumer app's CSS was already unlayered, but it's
-the same class of "cascade behaves differently than a clean mental model predicts" issue).
-
-Rather than leave global-token overrides as the only lever, `.input-text-wrapper` now also
-exposes its own local tokens, one indirection step below the global ones:
+## Public token API
+
+Every colour token below is `var(--input-text-*, {default})` — set the `--input-text-*` name to
+override just this component; leave it unset and it inherits the shared `--theme-input-*`/
+`--theme-*` token every other themed component also falls back to. See
+`theming-component-token-pattern.md` for why this two-tier shape exists.
+
+(Before 2026-08-25 this component used a private `--_input-text-*` naming scheme presented as a
+"local override path" — that's gone. A private, underscore-prefixed custom property was never a
+real override point; renaming it public with a real fallback is the actual fix, not a second
+documented path to reach for.)
+
+| Token | Falls back to | Controls |
+|---|---|---|
+| `--input-text-surface` | `var(--theme-input-surface)` | Wrapper background |
+| `--input-text-surface-hover` | `var(--theme-input-surface-hover)` | Background of an embedded `InputButtonCore` slot on hover |
+| `--input-text-border` | `var(--theme-border)` | Border colour (`.normal`/`.underlined`, resting) |
+| `--input-text-border-hover` | `var(--theme-border-focus)` | Outline colour on hover (mouse) |
+| `--input-text-border-focus` | `var(--theme-border-focus)` | Outline colour on `:focus-visible` (keyboard/assistive) |
+| `--input-text-color` | `var(--theme-input-text-color-normal)` | Input text colour |
+| `--input-text-placeholder-color` | `var(--theme-input-placeholder)` | Placeholder text colour |
+
+Geometry (`--input-padding-*`, `--input-min-height`, `--input-font-size`,
+`--form-element-*`, etc.) is shared across every `05.forms` component and untouched by this —
+see `theming-form-geometry-tokens.md`.
 
-```css
---_input-text-surface: var(--theme-input-surface);
---_input-text-surface-hover: var(--theme-input-surface-hover);
---_input-text-border: var(--theme-border);
---_input-text-border-focus: var(--theme-border-focus);
-```
+---
 
-- **Global override** (affects every themed component, not just this one): redeclare
-  `--theme-input-surface` / `--theme-border` / `--theme-border-focus` / `--theme-input-surface-hover`
-  at whatever scope you'd normally set theme tokens (`:root`, `[data-theme]`, a page wrapper).
-- **Local override** (this component only, guaranteed to win — it's the last declaration before
-  the property that consumes it, no global-token indirection to reason about):
+## Global theming — app-level CSS file
 
 ```css
-/* Unscoped consumer CSS, no :deep() needed */
-.input-text-wrapper {
-  --_input-text-border: var(--slate-06);
-  --_input-text-border-focus: var(--slate-04);
-  --_input-text-surface: var(--slate-01);
+:where(html) {
+  --input-text-surface: var(--rose-09);
+  --input-text-border: var(--rose-05);
+  --input-text-border-focus: var(--rose-03);
 }
 ```
 
-Prefer the local override when you only want to change this one component's look, or when you've
-hit a case (like the one above) where a global-token change isn't landing and you don't have time
-to dig into why — the local path is a strictly simpler cascade to reason about.
+Only declare the tokens you want to change — everything else keeps inheriting the shared
+`--theme-input-*`/`--theme-*` tokens.
 
 ---
 
-## Other tokens
-
-- `--input-icon-slot-gap`, `--input-padding-inline`, `--input-padding-block`, `--input-min-height`,
-  `--input-font-size`, `--form-element-border-width`, `--form-input-border-radius`,
-  `--form-element-border-bottom-width-underlined`, `--form-element-outline-width(-focus)`,
-  `--form-element-outline-offset-focus` — all generic form-geometry tokens shared across every
-  `05.forms` component, declared in `setup/04.elements/forms/*.css`. Not component-local, so
-  overriding one affects every form element, not just `InputTextCore`.
-- `--theme-input-text-color-normal`, `--theme-input-placeholder`,
-  `--theme-input-placeholder-font-size` — still read directly from the global theme tokens, no
-  local indirection yet. Follow the same pattern above (`--_input-text-*`) if a future consumer
-  needs a local override for these.
+## Per-instance overrides
+
+```vue
+<InputTextCore id="email" name="email" style="--input-text-border-focus: var(--gold-04);" />
+```

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

@@ -127,19 +127,25 @@ onMounted(() => {
 <style lang="css">
 @layer components {
   .input-text-wrapper {
-    /* Local overrides, one indirection step below the global --theme-* tokens they default from
-       — a consumer can target `.input-text-wrapper { --_input-text-border: ...; }` directly for
-       a guaranteed-specific override, instead of relying solely on redefining the global token.
-       See CONSUMER-STYLING.md. */
-    --_input-text-surface: var(--theme-input-surface);
-    --_input-text-surface-hover: var(--theme-input-surface-hover);
-    --_input-text-border: var(--theme-border);
-    --_input-text-border-focus: var(--theme-border-focus);
+    /* Public --input-text-* 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-input-surface/--theme-border. --_surface etc. are
+       private locals purely so the rest of this rule can reuse the resolved value without
+       repeating the fallback chain at every property — they are not themselves an override point,
+       see CONSUMER-STYLING.md. */
+    --_surface: var(--input-text-surface, var(--theme-input-surface));
+    --_surface-hover: var(--input-text-surface-hover, var(--theme-input-surface-hover));
+    --_border: var(--input-text-border, var(--theme-border));
+    /* Split so hover (mouse) and :focus-visible (keyboard/assistive) can diverge — both default
+       to the same --theme-border-focus today, identical appearance to before this token existed,
+       but each now has its own override point. */
+    --_border-hover: var(--input-text-border-hover, var(--theme-border-focus));
+    --_border-focus: var(--input-text-border-focus, var(--theme-border-focus));
 
     display: flex;
     align-items: center;
     gap: var(--input-icon-slot-gap);
-    background-color: var(--_input-text-surface);
+    background-color: var(--_surface);
     overflow: hidden;
     transition: all var(--theme-form-transition-duration) ease-in-out;
 
@@ -147,25 +153,25 @@ onMounted(() => {
     position: relative;
 
     &.normal {
-      border: var(--form-element-border-width) solid var(--_input-text-border);
+      border: var(--form-element-border-width) solid var(--_border);
       border-radius: var(--form-input-border-radius);
       outline: var(--form-element-outline-width) solid transparent;
 
       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-focus);
+        outline: var(--form-element-outline-width-focus) solid var(--_border-hover);
         outline-offset: var(--form-element-outline-offset-focus);
       }
 
       &:has(input:focus-visible, button:focus-visible) {
-        outline: var(--form-element-outline-width-focus) solid var(--_input-text-border-focus);
+        outline: var(--form-element-outline-width-focus) solid var(--_border-focus);
         outline-offset: var(--form-element-outline-offset-focus);
       }
     }
 
     &.underlined {
-      border-bottom: var(--form-element-border-bottom-width-underlined) solid var(--_input-text-border);
+      border-bottom: var(--form-element-border-bottom-width-underlined) solid var(--_border);
       padding-inline: var(--input-padding-inline);
     }
 
@@ -180,17 +186,28 @@ onMounted(() => {
       box-sizing: content-box;
 
       .input-button-core {
-        background-color: var(--_input-text-surface);
+        /* variant="inline" ships with zero border/colour styling by design (see
+           component-inline-action-button.md) — the parent supplies all of it. This rule was
+           always missing the border/colour half of that contract, only ever setting
+           background-color; harmless before InputButtonCore's flat-button redesign, which
+           removed the unscoped base rule that used to accidentally give every variant a real
+           border regardless. Without its own border/color/outline reset, this button now falls
+           through to the browser's UA default <button> chrome (a stark outset border and
+           black/white text) instead of sitting flush with the input. */
+        background-color: var(--_surface);
+        color: var(--input-text-color, var(--theme-input-text-color-normal));
+        border: none;
+        outline: none;
         aspect-ratio: 1;
         border-radius: 0;
         width: var(--input-min-height);
 
         &:hover {
-          background-color: var(--_input-text-surface-hover);
+          background-color: var(--_surface-hover);
         }
 
         &:is(:focus-visible) {
-          outline: var(--form-element-outline-width-focus) solid var(--_input-text-border-focus);
+          outline: var(--form-element-outline-width-focus) solid var(--_border-focus);
           outline-offset: -4px;
         }
 
@@ -207,7 +224,7 @@ onMounted(() => {
       touch-action: manipulation;
       flex-grow: 1;
 
-      color: var(--theme-input-text-color-normal);
+      color: var(--input-text-color, var(--theme-input-text-color-normal));
       font-family: var(--font-family);
       font-size: var(--input-font-size);
 
@@ -219,7 +236,7 @@ onMounted(() => {
       min-height: var(--input-min-height);
 
       &::placeholder {
-        color: var(--theme-input-placeholder);
+        color: var(--input-text-placeholder-color, var(--theme-input-placeholder));
         font-size: var(--theme-input-placeholder-font-size);
         font-style: italic;
         line-height: 1;

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

@@ -0,0 +1,184 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import { reactive, ref } from "vue";
+import InputTextWithLabel from "../../input-text/variants/InputTextWithLabel.vue";
+import InputSelectWithLabel from "../../input-select/variants/InputSelectWithLabel.vue";
+import InputTextareaWithLabel from "../../input-textarea/variants/InputTextareaWithLabel.vue";
+import MultipleCheckboxes from "../../input-checkbox/MultipleCheckboxes.vue";
+import InputButtonCore from "../../input-button/InputButtonCore.vue";
+import FormField from "../../form-field/FormField.vue";
+import HeroText from "../../../01.atoms/text-blocks/hero-text/HeroText.vue";
+import type { IFormMultipleOptions, InputUiVariant } from "~/types/forms/types.forms.d";
+
+interface ContactFormStoryArgs {
+  inputVariant: InputUiVariant;
+}
+
+// Demo composition, not a component of its own — a richer variant of the pattern the real
+// luxury-locs-by-natasha-nuxt3 /contact page uses (see that repo's app/pages/contact.vue): same
+// name/phone/email + multi-select services + comments shape, plus an InputSelectWithLabel
+// "How did you hear about us?" field that page doesn't have, to also exercise the select
+// component alongside the others in one composed form. No validation wiring
+// (useZodValidation/zod) here — that's the consuming app's concern, this is a visual/composition
+// reference only.
+export default {
+  title: "Patterns/Contact Form",
+  argTypes: {
+    inputVariant: {
+      control: { type: "select" },
+      options: ["normal", "outlined", "underlined"],
+      description: "Applied to every field in the form at once",
+      table: { category: "Styling" },
+    },
+  },
+  args: {
+    inputVariant: "normal",
+  },
+} as Meta<ContactFormStoryArgs>;
+
+const Template: StoryFn<ContactFormStoryArgs> = (args) => ({
+  components: {
+    InputTextWithLabel,
+    InputSelectWithLabel,
+    InputTextareaWithLabel,
+    MultipleCheckboxes,
+    InputButtonCore,
+    FormField,
+    HeroText,
+  },
+  setup() {
+    const state = reactive({
+      fullName: "",
+      telNumber: "",
+      emailAddress: "",
+      hearAboutUs: "",
+      services: [] as string[],
+      comments: "",
+    });
+
+    const hearAboutUsOptions = ref<IFormMultipleOptions>({
+      data: [
+        { id: "search", name: "hearAboutUs", value: "search", label: "Search engine" },
+        { id: "social", name: "hearAboutUs", value: "social", label: "Social media" },
+        { id: "referral", name: "hearAboutUs", value: "referral", label: "Friend referral" },
+        { id: "other", name: "hearAboutUs", value: "other", label: "Other" },
+      ],
+      total: 4,
+      skip: 0,
+      limit: 10,
+    });
+
+    const servicesOptions = ref<IFormMultipleOptions>({
+      data: [
+        { id: "balayage", name: "services", value: "balayage", label: "Balayage" },
+        { id: "highlights", name: "services", value: "highlights", label: "Highlights" },
+        { id: "full-colour", name: "services", value: "full-colour", label: "Full Colour" },
+        { id: "cut-style", name: "services", value: "cut-style", label: "Cut & Style" },
+      ],
+      total: 4,
+      skip: 0,
+      limit: 10,
+    });
+
+    return { args, state, hearAboutUsOptions, servicesOptions };
+  },
+  template: `
+    <div style="margin: 36px; max-width: 480px;">
+      <HeroText
+        tag="h2"
+        font-size="heading"
+        :text-content="[{ text: 'Get in touch', styleClass: 'normal' }]"
+        :style-class-passthrough="['mbe-20']"
+      />
+
+      <form @submit.prevent>
+        <FormField width="wide" :has-gutter="false">
+          <InputTextWithLabel
+            v-model="state.fullName"
+            type="text"
+            name="fullName"
+            label="Full name"
+            placeholder="eg. Jane Smith"
+            error-message=""
+            :required="true"
+            :input-variant="args.inputVariant"
+          />
+        </FormField>
+
+        <FormField width="wide" :has-gutter="false">
+          <InputTextWithLabel
+            v-model="state.telNumber"
+            type="tel"
+            inputmode="tel"
+            name="telNumber"
+            label="Telephone number"
+            placeholder="eg. 07700 900000"
+            error-message=""
+            :required="true"
+            :input-variant="args.inputVariant"
+          />
+        </FormField>
+
+        <FormField width="wide" :has-gutter="false">
+          <InputTextWithLabel
+            v-model="state.emailAddress"
+            type="email"
+            inputmode="email"
+            name="emailAddress"
+            label="Email address"
+            placeholder="eg. name@domain.com"
+            error-message=""
+            :required="true"
+            :input-variant="args.inputVariant"
+          />
+        </FormField>
+
+        <FormField width="wide" :has-gutter="false">
+          <InputSelectWithLabel
+            v-model="state.hearAboutUs"
+            v-model:field-data="hearAboutUsOptions"
+            name="hearAboutUs"
+            label="How did you hear about us?"
+            placeholder="Select an option"
+            error-message=""
+            :input-variant="args.inputVariant"
+          />
+        </FormField>
+
+        <FormField width="wide" :has-gutter="false">
+          <MultipleCheckboxes
+            v-model="state.services"
+            v-model:field-data="servicesOptions"
+            name="services"
+            legend="Services of interest"
+            label="Select all that apply"
+            error-message=""
+            options-layout="inline"
+            :is-button="true"
+            :input-variant="args.inputVariant"
+          >
+            <template #descriptionText>Choose one or more services you're interested in.</template>
+          </MultipleCheckboxes>
+        </FormField>
+
+        <FormField width="wide" :has-gutter="false">
+          <InputTextareaWithLabel
+            v-model="state.comments"
+            name="comments"
+            label="Comments"
+            placeholder="Tell us a bit more about what you're looking for…"
+            error-message=""
+            :input-variant="args.inputVariant"
+          >
+            <template #descriptionText>Optional — any extra information that might help us.</template>
+          </InputTextareaWithLabel>
+        </FormField>
+
+        <FormField width="wide" :has-gutter="false">
+          <InputButtonCore type="submit" variant="primary" button-text="Send message" />
+        </FormField>
+      </form>
+    </div>
+  `,
+});
+
+export const Default = Template.bind({});

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

@@ -0,0 +1,125 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import { reactive } from "vue";
+import InputTextWithLabel from "../../input-text/variants/InputTextWithLabel.vue";
+import InputPasswordWithLabel from "../../input-text/variants/InputPasswordWithLabel.vue";
+import InputCheckboxRadioWithLabel from "../../input-checkbox-radio/InputCheckboxRadioWithLabel.vue";
+import InputButtonCore from "../../input-button/InputButtonCore.vue";
+import FormField from "../../form-field/FormField.vue";
+import GlassPanel from "../../../01.atoms/glass-panel/GlassPanel.vue";
+import HeroText from "../../../01.atoms/text-blocks/hero-text/HeroText.vue";
+import type { InputUiVariant } from "~/types/forms/types.forms.d";
+
+interface LoginFormStoryArgs {
+  inputVariant: InputUiVariant;
+}
+
+// Demo composition, not a component of its own — exercises the real-world "login form" pattern
+// (labelled text/password inputs, a single checkbox, primary + tertiary buttons) using the
+// existing WithLabel wrapper components rather than the bare *Core components other stories use,
+// since that's what a consuming app actually reaches for. No validation wiring (useZodValidation)
+// here — that's the consuming app's concern, this is a visual/composition reference only.
+export default {
+  title: "Patterns/Login Form",
+  argTypes: {
+    inputVariant: {
+      control: { type: "select" },
+      options: ["normal", "outlined", "underlined"],
+      description: "Applied to every field in the form at once",
+      table: { category: "Styling" },
+    },
+  },
+  args: {
+    inputVariant: "normal",
+  },
+} as Meta<LoginFormStoryArgs>;
+
+const Template: StoryFn<LoginFormStoryArgs> = (args) => ({
+  components: {
+    InputTextWithLabel,
+    InputPasswordWithLabel,
+    InputCheckboxRadioWithLabel,
+    InputButtonCore,
+    FormField,
+    GlassPanel,
+    HeroText,
+  },
+  setup() {
+    const state = reactive({
+      email: "",
+      password: "",
+      rememberMe: false,
+    });
+    return { args, state };
+  },
+  template: `
+    <div style="margin: 36px; max-width: 420px;">
+      <GlassPanel :style-class-passthrough="['login-panel']">
+        <div style="padding: 3.2rem;">
+          <HeroText
+            tag="h2"
+            font-size="heading"
+            :text-content="[{ text: 'Sign in', styleClass: 'normal' }]"
+            :style-class-passthrough="['mbe-20']"
+          />
+
+          <form @submit.prevent>
+            <FormField width="wide" :has-gutter="false">
+              <InputTextWithLabel
+                v-model="state.email"
+                type="email"
+                inputmode="email"
+                name="email"
+                label="Email address"
+                placeholder="you@example.com"
+                error-message=""
+                :required="true"
+                :input-variant="args.inputVariant"
+              />
+            </FormField>
+
+            <FormField width="wide" :has-gutter="false">
+              <InputPasswordWithLabel
+                v-model="state.password"
+                name="password"
+                label="Password"
+                placeholder="Enter your password"
+                error-message=""
+                :required="true"
+                :input-variant="args.inputVariant"
+              />
+            </FormField>
+
+            <FormField width="wide" :has-gutter="false">
+              <div style="display: flex; align-items: center; justify-content: space-between; gap: 1rem;">
+                <InputCheckboxRadioWithLabel
+                  v-model="state.rememberMe"
+                  type="checkbox"
+                  name="rememberMe"
+                  label="Remember me"
+                  :input-variant="args.inputVariant"
+                />
+                <InputButtonCore type="button" variant="tertiary" button-text="Forgot password?" />
+              </div>
+            </FormField>
+
+            <FormField width="wide" :has-gutter="false">
+              <!-- InputButtonCore keeps box-sizing: content-box, so width: 100% alone sizes only
+                   the content box and padding/border overflow past it — box-sizing: border-box
+                   here makes width: 100% mean the actual rendered width, not a demo-only quirk
+                   worth fixing in the component itself since content-box is relied on elsewhere
+                   (e.g. icon-only's aspect-ratio: 1). -->
+              <InputButtonCore
+                type="submit"
+                variant="primary"
+                button-text="Sign in"
+                style="width: 100%; box-sizing: border-box;"
+              />
+            </FormField>
+          </form>
+        </div>
+      </GlassPanel>
+    </div>
+  `,
+});
+
+export const Default = Template.bind({});

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

@@ -0,0 +1,49 @@
+# ToggleSwitchCore — Consumer Styling Guide
+
+## Public token API
+
+Every colour token below is `var(--toggle-switch-*, {default})` — set the `--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. Defaults are unchanged from before this migration — this is a
+token-rename pass, not a redesign.
+
+| Token | Falls back to | Controls |
+|---|---|---|
+| `--toggle-switch-surface` | `var(--theme-checkbox-symbol-surface)` | Track background (resting) |
+| `--toggle-switch-surface-hover` | `var(--theme-surface-subtle)` | Track background on hover |
+| `--toggle-switch-border` | `var(--theme-border)` | Track border colour |
+| `--toggle-switch-border-focus` | `var(--theme-border-focus)` | Track outline colour on `:focus-visible` |
+| `--toggle-switch-symbol-border` | `var(--theme-text)` | Thumb border colour |
+| `--toggle-switch-symbol-surface-off` | `var(--theme-on-surface)` | Thumb background, unchecked |
+| `--toggle-switch-symbol-surface-on` | `var(--theme-surface)` | Thumb background, checked |
+| `--toggle-switch-icon-on-color` | `var(--theme-on-surface)` | "On" icon colour |
+| `--toggle-switch-icon-off-color` | `var(--theme-surface)` | "Off" icon colour |
+
+Geometry (`--input-toggle-*`, `--form-element-*`) is shared across every `05.forms` component and
+untouched by this — see `theming-form-geometry-tokens.md`.
+
+> Five private locals (`--_icon-on-opacity`, `--_icon-off-opacity`, `--_symbol-background-color`,
+> `--_symbol-margin-inline-start`, `--_symbol-checked-offset`) were removed during this migration —
+> declared but never actually read by any property in the component, confirmed by grep. Not part
+> of any public API, so nothing to update if you were relying on them (you weren't — they had zero
+> effect).
+
+---
+
+## Global theming — app-level CSS file
+
+```css
+:where(html) {
+  --toggle-switch-symbol-surface-on: var(--rose-05);
+  --toggle-switch-border-focus: var(--rose-03);
+}
+```
+
+---
+
+## Per-instance overrides
+
+```vue
+<ToggleSwitchCore id="notifications" name="notifications" style="--toggle-switch-symbol-surface-on: var(--gold-06);" />
+```