srcdev-nuxt-components 9.6.13 → 9.6.15

package/app/components/01.atoms/text-blocks/link-text/stories/LinkText.stories.ts

@@ -7,134 +7,131 @@ const meta: Meta<typeof LinkText> = {
   argTypes: {
     to: {
       control: "text",
-      description: "Link destination (internal path or external URL)",
+      description: "Link destination (internal path or external URL).",
+      table: { category: "Basic" },
     },
     linkText: {
       control: "text",
-      description: "Visible link label",
+      description: "Visible link label. It should name the destination, so it's never clamped.",
+      table: { category: "Content" },
     },
     external: {
       control: "boolean",
-      description: "Force external link handling",
-      defaultValue: false,
+      description: "Force external link handling on an internal-looking path.",
+      table: { category: "Basic" },
     },
     target: {
       control: { type: "select" },
       options: [undefined, "_blank", "_self"],
-      description: "Link target attribute",
-    },
-    styleClassPassthrough: {
-      control: "object",
-      description: "Additional classes",
-      defaultValue: [],
+      description: "Link `target`. NuxtLink adds `rel=\"noopener noreferrer\"` for an external `_blank`.",
+      table: { category: "Basic" },
     },
+    styleClassPassthrough: { table: { disable: true } },
   },
-};
-
-export default meta;
-type Story = StoryObj<typeof LinkText>;
-
-export const Default: Story = {
   args: {
     to: "/",
     linkText: "Read More",
     external: false,
-    styleClassPassthrough: [],
   },
-  render: (args) => ({
-    components: { LinkText },
-    setup() {
-      return { args };
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A `NuxtLink` styled as a standalone text link. `to` and `linkText` are required; `left` and `right` slots take icons, which stay centred on the label. Colours, underline and gap come from `--link-text-*` tokens.",
+      },
     },
-    template: `<LinkText v-bind="args" />`,
-  }),
-};
-
-export const WithLeftIcon: Story = {
-  args: {
-    to: "/",
-    linkText: "Go Back",
-    styleClassPassthrough: [],
   },
-  render: (args) => ({
-    components: { LinkText },
-    setup() {
-      return { args };
-    },
-    template: `
-      <LinkText v-bind="args">
-        <template #left>
-          <Icon name="lucide:arrow-left" />
-        </template>
-      </LinkText>
-    `,
-  }),
 };
 
-export const WithRightIcon: Story = {
-  args: {
-    to: "/",
-    linkText: "Learn More",
-    styleClassPassthrough: [],
-  },
-  render: (args) => ({
-    components: { LinkText },
-    setup() {
-      return { args };
-    },
-    template: `
-      <LinkText v-bind="args">
-        <template #right>
-          <Icon name="lucide:arrow-right" />
-        </template>
-      </LinkText>
-    `,
-  }),
-};
+export default meta;
+type Story = StoryObj<typeof LinkText>;
 
-export const WithBothIcons: Story = {
-  args: {
-    to: "/",
-    linkText: "Explore",
-    styleClassPassthrough: [],
-  },
-  render: (args) => ({
+const withIcons = (left: string | null, right: string | null) => `
+  <LinkText v-bind="args">
+    ${left ? `<template #left><Icon name="${left}" /></template>` : ""}
+    ${right ? `<template #right><Icon name="${right}" /></template>` : ""}
+  </LinkText>
+`;
+
+const story = (template: string, description: string, args: Story["args"] = {}): Story => ({
+  args,
+  render: (storyArgs) => ({
     components: { LinkText },
     setup() {
-      return { args };
+      return { args: storyArgs };
     },
-    template: `
-      <LinkText v-bind="args">
-        <template #left>
-          <Icon name="lucide:sparkles" />
-        </template>
-        <template #right>
-          <Icon name="lucide:arrow-right" />
-        </template>
-      </LinkText>
-    `,
+    template,
   }),
-};
+  parameters: { docs: { description: { story: description } } },
+});
 
-export const ExternalLink: Story = {
-  args: {
-    to: "https://nuxt.com",
-    linkText: "Nuxt Docs",
-    external: true,
-    target: "_blank",
-    styleClassPassthrough: [],
-  },
-  render: (args) => ({
+export const Default = story(withIcons(null, null), "A plain link. Use the Controls panel to change the destination, label and target.");
+
+export const WithLeftIcon = story(withIcons("lucide:arrow-left", null), "A `left` slot icon for a back or previous link.", {
+  linkText: "Go Back",
+});
+
+export const WithRightIcon = story(withIcons(null, "lucide:arrow-right"), "A `right` slot icon for a forward or more link.", {
+  linkText: "Learn More",
+});
+
+export const WithBothIcons = story(withIcons("lucide:sparkles", "lucide:arrow-right"), "Both slots. Left icon, label, then right icon.", {
+  linkText: "Explore",
+});
+
+export const ExternalLink = story(
+  withIcons(null, "lucide:external-link"),
+  "An external link opening in a new tab, with an icon that says so.",
+  { to: "https://nuxt.com", linkText: "Nuxt Docs", external: true, target: "_blank" }
+);
+
+export const StressTest: Story = {
+  name: "Stress Test (Worst-Case Data)",
+  render: () => ({
     components: { LinkText },
-    setup() {
-      return { args };
-    },
     template: `
-      <LinkText v-bind="args">
-        <template #right>
-          <Icon name="lucide:external-link" />
-        </template>
-      </LinkText>
+      <div style="display: grid; gap: 2.4rem; padding: 2.4rem; font-size: 1.6rem;">
+        <p style="margin: 0; font-size: 1.4rem;">Long German label, an unbroken label and a long URL as the label, each with icons, in an 18rem column.</p>
+        <div style="display: grid; gap: 1.6rem; justify-items: start; inline-size: 18rem; outline: 0.1rem dashed currentColor;">
+          <LinkText to="/" link-text="Alle Lieferbedingungen und Rückgaberichtlinien ansehen">
+            <template #right><Icon name="lucide:arrow-right" /></template>
+          </LinkText>
+          <LinkText to="/" link-text="Lieferbedingungenundrückgaberichtlinienansehen">
+            <template #left><Icon name="lucide:arrow-left" /></template>
+            <template #right><Icon name="lucide:arrow-right" /></template>
+          </LinkText>
+          <LinkText to="https://example.invalid/a/very/long/unbroken/url" link-text="https://example.invalid/a/very/long/unbroken/url" external target="_blank">
+            <template #right><Icon name="lucide:external-link" /></template>
+          </LinkText>
+        </div>
+
+        <p style="margin: 0; font-size: 1.4rem;">Emoji first, HTML-like text (shown as text), right-to-left with a right icon, and a single character.</p>
+        <div style="display: flex; flex-wrap: wrap; gap: 2.4rem; align-items: center;">
+          <LinkText to="/" link-text="😀 Emoji first" />
+          <LinkText to="/" link-text="<b>not bold</b>" />
+          <LinkText to="/" link-text="اقرأ المزيد" dir="rtl">
+            <template #right><Icon name="lucide:arrow-left" /></template>
+          </LinkText>
+          <LinkText to="/" link-text="A" />
+        </div>
+
+        <p style="margin: 0; font-size: 1.4rem;">Icon-only link: empty <code>link-text</code>, named with <code>aria-label</code>. Tab to it to check the focus ring.</p>
+        <LinkText to="/" link-text="" aria-label="Back to home">
+          <template #left><Icon name="lucide:house" /></template>
+        </LinkText>
+
+        <p style="margin: 0; font-size: 1.4rem;">Inside a sentence: the link sits on the text line.</p>
+        <p style="margin: 0;">Our full price list is on the <LinkText to="/" link-text="services page" /> and updated monthly.</p>
+      </div>
     `,
   }),
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          "Worst-case labels. Check: long and unbroken labels and URLs wrap inside the dashed 18rem column with their icons centred on the wrapped text; emoji and HTML-like text render as text; right-to-left puts the right slot on the inline end; an icon-only link keeps a visible focus ring; an inline link sits on the line of text.",
+      },
+    },
+  },
 };

package/app/components/01.atoms/text-blocks/link-text/tests/LinkText.spec.ts

@@ -1,177 +1,168 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, afterEach, vi } from "vitest";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
 import LinkText from "../LinkText.vue";
 
-describe("LinkText", () => {
-  // ─── Mount ───────────────────────────────────────────────────────────────
+type LinkTextProps = InstanceType<typeof LinkText>["$props"];
+
+const mounted: Awaited<ReturnType<typeof mountSuspended>>[] = [];
+
+const mountLink = async (props: Partial<LinkTextProps> = {}, slots: Record<string, string> = {}) => {
+  const wrapper = await mountSuspended(LinkText, {
+    props: { to: "/about", linkText: "About Us", ...props } as LinkTextProps,
+    slots,
+  });
+  mounted.push(wrapper);
+  return wrapper;
+};
 
+afterEach(() => {
+  mounted.splice(0).forEach((wrapper) => wrapper.unmount());
+  vi.restoreAllMocks();
+});
+
+describe("LinkText", () => {
   it("mounts without error", async () => {
-    const wrapper = await mountSuspended(LinkText, {
-      props: { to: "/about", linkText: "About Us" },
-    });
+    const wrapper = await mountLink();
     expect(wrapper.vm).toBeTruthy();
   });
 
   // ─── Snapshots ───────────────────────────────────────────────────────────
 
   it("renders correct HTML structure with default props", async () => {
-    const wrapper = await mountSuspended(LinkText, {
-      props: { to: "/about", linkText: "About Us" },
-    });
+    const wrapper = await mountLink();
     expect(wrapper.html()).toMatchSnapshot();
   });
 
   it("renders correct HTML structure with left slot", async () => {
-    const wrapper = await mountSuspended(LinkText, {
-      props: { to: "/about", linkText: "About Us" },
-      slots: { left: "<svg data-testid='icon-left' />" },
-    });
+    const wrapper = await mountLink({}, { left: "<svg data-testid='icon-left' />" });
     expect(wrapper.html()).toMatchSnapshot();
   });
 
   it("renders correct HTML structure with right slot", async () => {
-    const wrapper = await mountSuspended(LinkText, {
-      props: { to: "/about", linkText: "About Us" },
-      slots: { right: "<svg data-testid='icon-right' />" },
-    });
+    const wrapper = await mountLink({}, { right: "<svg data-testid='icon-right' />" });
     expect(wrapper.html()).toMatchSnapshot();
   });
 
   it("renders correct HTML structure with both slots", async () => {
-    const wrapper = await mountSuspended(LinkText, {
-      props: { to: "/about", linkText: "About Us" },
-      slots: {
-        left: "<svg data-testid='icon-left' />",
-        right: "<svg data-testid='icon-right' />",
-      },
-    });
+    const wrapper = await mountLink(
+      {},
+      { left: "<svg data-testid='icon-left' />", right: "<svg data-testid='icon-right' />" }
+    );
     expect(wrapper.html()).toMatchSnapshot();
   });
 
   it("renders correct HTML structure with all props set", async () => {
-    const wrapper = await mountSuspended(LinkText, {
-      props: {
-        to: "https://example.com",
-        linkText: "Visit Us",
-        external: true,
-        target: "_blank",
-        styleClassPassthrough: ["custom-class"],
-      },
+    const wrapper = await mountLink({
+      to: "https://example.com",
+      linkText: "Visit Us",
+      external: true,
+      target: "_blank",
+      styleClassPassthrough: ["custom-class"],
     });
     expect(wrapper.html()).toMatchSnapshot();
   });
 
-  // ─── Base class ──────────────────────────────────────────────────────────
+  // ─── Root and label ──────────────────────────────────────────────────────
 
   it("always has the link-text class", async () => {
-    const wrapper = await mountSuspended(LinkText, {
-      props: { to: "/", linkText: "Home" },
-    });
+    const wrapper = await mountLink({ to: "/", linkText: "Home" });
     expect(wrapper.classes()).toContain("link-text");
   });
 
-  // ─── linkText ────────────────────────────────────────────────────────────
-
   it("renders the linkText in a label span", async () => {
-    const wrapper = await mountSuspended(LinkText, {
-      props: { to: "/", linkText: "Read More" },
-    });
+    const wrapper = await mountLink({ linkText: "Read More" });
     expect(wrapper.find(".link-text__label").text()).toBe("Read More");
   });
 
   it("renders linkText with special characters", async () => {
-    const wrapper = await mountSuspended(LinkText, {
-      props: { to: "/", linkText: "Édition & Co." },
-    });
+    const wrapper = await mountLink({ linkText: "Édition & Co." });
     expect(wrapper.find(".link-text__label").text()).toBe("Édition & Co.");
   });
 
+  it("renders HTML-like linkText as text", async () => {
+    const wrapper = await mountLink({ linkText: "<b>not bold</b>" });
+    expect(wrapper.find("b").exists()).toBe(false);
+    expect(wrapper.find(".link-text__label").text()).toBe("<b>not bold</b>");
+  });
+
+  it("updates the label when linkText changes after mount", async () => {
+    const wrapper = await mountLink({ linkText: "Before" });
+    await wrapper.setProps({ linkText: "After" });
+    expect(wrapper.find(".link-text__label").text()).toBe("After");
+  });
+
   // ─── Slots ───────────────────────────────────────────────────────────────
 
   it("renders no icon spans when no slots provided", async () => {
-    const wrapper = await mountSuspended(LinkText, {
-      props: { to: "/", linkText: "No Icons" },
-    });
+    const wrapper = await mountLink();
     expect(wrapper.find(".link-text__icon--left").exists()).toBe(false);
     expect(wrapper.find(".link-text__icon--right").exists()).toBe(false);
   });
 
   it("renders left icon span when left slot is provided", async () => {
-    const wrapper = await mountSuspended(LinkText, {
-      props: { to: "/", linkText: "With Left Icon" },
-      slots: { left: "<svg />" },
-    });
+    const wrapper = await mountLink({}, { left: "<svg />" });
     expect(wrapper.find(".link-text__icon--left").exists()).toBe(true);
     expect(wrapper.find(".link-text__icon--right").exists()).toBe(false);
   });
 
   it("renders right icon span when right slot is provided", async () => {
-    const wrapper = await mountSuspended(LinkText, {
-      props: { to: "/", linkText: "With Right Icon" },
-      slots: { right: "<svg />" },
-    });
+    const wrapper = await mountLink({}, { right: "<svg />" });
     expect(wrapper.find(".link-text__icon--left").exists()).toBe(false);
     expect(wrapper.find(".link-text__icon--right").exists()).toBe(true);
   });
 
-  it("renders both icon spans when both slots are provided", async () => {
-    const wrapper = await mountSuspended(LinkText, {
-      props: { to: "/", linkText: "Both Icons" },
-      slots: { left: "<svg />", right: "<svg />" },
-    });
-    expect(wrapper.find(".link-text__icon--left").exists()).toBe(true);
-    expect(wrapper.find(".link-text__icon--right").exists()).toBe(true);
+  it("renders left icon before label and right icon after label", async () => {
+    const wrapper = await mountLink({}, { left: "<span class='l' />", right: "<span class='r' />" });
+    const children = Array.from((wrapper.element as HTMLElement).children);
+    expect(children.map((child) => child.classList[1] ?? child.classList[0])).toEqual([
+      "link-text__icon--left",
+      "link-text__label",
+      "link-text__icon--right",
+    ]);
   });
 
-  // ─── Props ───────────────────────────────────────────────────────────────
+  // ─── Link attributes ─────────────────────────────────────────────────────
+
+  it("renders the to prop as href", async () => {
+    const wrapper = await mountLink({ to: "/services" });
+    expect(wrapper.attributes("href")).toBe("/services");
+  });
 
   it("passes target prop to NuxtLink", async () => {
+    const wrapper = await mountLink({ to: "https://example.com", target: "_blank" });
+    expect(wrapper.attributes("target")).toBe("_blank");
+  });
+
+  it("adds rel noopener to an external link opening in a new tab", async () => {
+    const wrapper = await mountLink({ to: "https://example.com", external: true, target: "_blank" });
+    expect(wrapper.attributes("rel")).toContain("noopener");
+  });
+
+  it("forwards an aria-label to the link for an icon-only link", async () => {
     const wrapper = await mountSuspended(LinkText, {
-      props: { to: "https://example.com", linkText: "External", target: "_blank" },
+      props: { to: "/", linkText: "" },
+      attrs: { "aria-label": "Home" },
+      slots: { left: "<svg />" },
     });
-    expect(wrapper.attributes("target")).toBe("_blank");
+    mounted.push(wrapper);
+    expect(wrapper.attributes("aria-label")).toBe("Home");
   });
 
   // ─── styleClassPassthrough ───────────────────────────────────────────────
 
   it("applies a styleClassPassthrough array", async () => {
-    const wrapper = await mountSuspended(LinkText, {
-      props: {
-        to: "/",
-        linkText: "Styled",
-        styleClassPassthrough: ["class-a", "class-b"],
-      },
-    });
+    const wrapper = await mountLink({ styleClassPassthrough: ["class-a", "class-b"] });
     expect(wrapper.classes()).toContain("class-a");
     expect(wrapper.classes()).toContain("class-b");
   });
 
   it("applies a single styleClassPassthrough string", async () => {
-    const wrapper = await mountSuspended(LinkText, {
-      props: { to: "/", linkText: "Styled", styleClassPassthrough: "solo-class" },
-    });
+    const wrapper = await mountLink({ styleClassPassthrough: "solo-class" });
     expect(wrapper.classes()).toContain("solo-class");
   });
 
-  // ─── DOM order ───────────────────────────────────────────────────────────
-
-  it("renders left icon before label and right icon after label", async () => {
-    const wrapper = await mountSuspended(LinkText, {
-      props: { to: "/", linkText: "Ordered" },
-      slots: { left: "<span class='l' />", right: "<span class='r' />" },
-    });
-    const children = wrapper.element.children;
-    expect(children[0].classList.contains("link-text__icon--left")).toBe(true);
-    expect(children[1].classList.contains("link-text__label")).toBe(true);
-    expect(children[2].classList.contains("link-text__icon--right")).toBe(true);
-  });
-});
-
-describe("LinkText styleClassPassthrough reactivity", () => {
   it("updates classes when styleClassPassthrough changes after mount", async () => {
-    const wrapper = await mountSuspended(LinkText, {
-      props: { to: "/about", linkText: "About", styleClassPassthrough: ["original"] },
-    });
+    const wrapper = await mountLink({ styleClassPassthrough: ["original"] });
     await wrapper.setProps({ styleClassPassthrough: ["updated"] });
     expect(wrapper.classes()).not.toContain("original");
     expect(wrapper.classes()).toContain("updated");

package/app/components/02.molecules/price-list/tests/__snapshots__/PriceList.spec.ts.snap

@@ -3,14 +3,14 @@
 exports[`PriceList > Snapshots > custom headings 1`] = `
 "<div class="price-list">
   <div class="price-list__column">
-    <h2 class="hero-text price-list__heading subheading axis-horizontal">
-      <!--v-if--><span class="text-block-0">Cuts</span>
+    <h2 class="hero-text price-list__heading" data-font-size="subheading" data-axis="horizontal">
+      <!--v-if--><span class="hero-text-segment">Cuts</span>
     </h2>
     <dl class="price-list__list"></dl>
   </div>
   <div class="price-list__column">
-    <h2 class="hero-text price-list__heading subheading axis-horizontal">
-      <!--v-if--><span class="text-block-0">Colour</span>
+    <h2 class="hero-text price-list__heading" data-font-size="subheading" data-axis="horizontal">
+      <!--v-if--><span class="hero-text-segment">Colour</span>
     </h2>
     <dl class="price-list__list"></dl>
   </div>
@@ -20,8 +20,8 @@ exports[`PriceList > Snapshots > custom headings 1`] = `
 exports[`PriceList > Snapshots > default 1`] = `
 "<div class="price-list">
   <div class="price-list__column">
-    <h2 class="hero-text price-list__heading subheading axis-horizontal">
-      <!--v-if--><span class="text-block-0">Cutting &amp; Treatment</span>
+    <h2 class="hero-text price-list__heading" data-font-size="subheading" data-axis="horizontal">
+      <!--v-if--><span class="hero-text-segment">Cutting &amp; Treatment</span>
     </h2>
     <dl class="price-list__list">
       <div class="price-list__row">
@@ -39,8 +39,8 @@ exports[`PriceList > Snapshots > default 1`] = `
     </dl>
   </div>
   <div class="price-list__column">
-    <h2 class="hero-text price-list__heading subheading axis-horizontal">
-      <!--v-if--><span class="text-block-0">Hair Colouring</span>
+    <h2 class="hero-text price-list__heading" data-font-size="subheading" data-axis="horizontal">
+      <!--v-if--><span class="hero-text-segment">Hair Colouring</span>
     </h2>
     <dl class="price-list__list">
       <div class="price-list__row">

package/app/components/02.molecules/sliding-toggle/CONSUMER-STYLING.md

@@ -0,0 +1,109 @@
+# SlidingToggle — Consumer Styling Guide
+
+## Public token API
+
+### Track
+
+| Token | Default | Controls |
+|---|---|---|
+| `--sliding-toggle-surface` | `var(--theme-surface-subtle)` | Track background |
+| `--sliding-toggle-padding` | `0.4rem` | Space between the track edge and the options (the indicators sit inside it too) |
+| `--sliding-toggle-gap` | `0.4rem` | Space between options |
+| `--sliding-toggle-border-radius` | `0.8rem` | Track corner radius |
+| `--sliding-toggle-corner-shape` | `round` | `corner-shape` of the track, both indicators and the options (`squircle`, `superellipse(n)`, `bevel`, `scoop`, `notch`). Chromium 139+ only; other browsers ignore it and keep `border-radius` |
+
+### Indicators
+
+| Token | Default | Controls |
+|---|---|---|
+| `--sliding-toggle-indicator-surface` | `var(--theme-on-surface)` | Background of the selected option's sliding indicator |
+| `--sliding-toggle-indicator-shadow` | `0 0.1rem 0.3rem rgb(0 0 0 / 0.1)` | Shadow on the selected indicator |
+| `--sliding-toggle-hover-indicator-surface` | `color-mix(in oklch, var(--theme-surface-subtle), var(--theme-text) 6%)` | Background of the hover indicator, one step darker than the track |
+| `--sliding-toggle-indicator-stretch` | `1` | Multiplies both indicators' edge delays: `1` stretches then catches up, `0` slides both edges together, values between shorten the stretch |
+| `--sliding-toggle-marker-height` | `0.2rem` | Height of the accent line along the selected indicator's bottom edge (`0` hides it) |
+| `--sliding-toggle-marker-colour` | `var(--theme-accent)` | Colour of that line |
+
+### Options
+
+| Token | Default | Controls |
+|---|---|---|
+| `--sliding-toggle-option-padding` | `0.8rem 1.6rem` | Option padding |
+| `--sliding-toggle-option-border-radius` | `0.6rem` | Corner radius of the options and both indicators |
+| `--sliding-toggle-option-flex` | `0 1 auto` | Option `flex`. `1 1 0` gives equal widths (stretch the root too) |
+| `--sliding-toggle-option-font-size` | `inherit` | Label font size |
+| `--sliding-toggle-option-font-weight` | `500` | Label font weight |
+| `--sliding-toggle-option-white-space` | `normal` | Label `white-space`; `nowrap` keeps each label on one line |
+| `--sliding-toggle-option-colour` | `color-mix(in oklch, var(--theme-text) 70%, transparent)` | Label colour |
+| `--sliding-toggle-option-colour-active` | `var(--theme-text)` | Selected option's label colour |
+| `--sliding-toggle-transition-duration` | `200ms` | Label colour fade. The indicator slide is the `transitionDuration` prop |
+| `--sliding-toggle-focus-ring-width` | `0.2rem` | Focus ring width |
+| `--sliding-toggle-focus-ring-colour` | `var(--theme-border-focus)` | Focus ring colour |
+
+Private (not public API): `--_sliding-toggle-active-*` and `--_sliding-toggle-hover-*` (`-start`,
+`-end`, `-duration`, `-start-delay`, `-end-delay`), written on the root by `useSlidingIndicator`
+from the measured option positions.
+
+---
+
+## State hooks
+
+| Hook | Where | Meaning |
+|---|---|---|
+| `[data-ready]` | root | Mounted and measured. Before this (SSR, first paint) the indicators are hidden and the selected option paints its own background and marker |
+| `[data-has-selection]` | root | `v-model` matches an option |
+| `[data-hovering]` | root | The pointer is over an enabled option (with `trackHover`) |
+| `[aria-disabled="true"]` | root | The `disabled` prop |
+| `[aria-checked="true"]` | `.sliding-toggle-option` | The selected option |
+| `:disabled` | `.sliding-toggle-option` | A disabled option, or the whole group |
+
+Inner classes: `.sliding-toggle-option` (each `<button role="radio">`), `.sliding-toggle-indicator`
+with `.sliding-toggle-indicator-active` and `.sliding-toggle-indicator-hover`. The marker is the
+active indicator's `::after`.
+
+---
+
+## Motion
+
+The indicator edges slide with `useSlidingIndicator`: on a move the edge in the direction of travel
+goes first and the other follows one `transitionDuration` later. `--sliding-toggle-indicator-stretch: 0`
+turns the stretch into a plain slide for both indicators (same as TabbedContent's
+`--tabs-indicator-stretch`). Under `prefers-reduced-motion` both edges snap and the label colour
+doesn't fade.
+
+---
+
+## 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`.
+
+### Equal-width options
+
+```css
+.billing-switch {
+  --sliding-toggle-option-flex: 1 1 0;
+  --sliding-toggle-corner-shape: squircle;
+}
+
+.billing-switch .sliding-toggle {
+  inline-size: 100%;
+}
+```
+
+---
+
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root `.sliding-toggle` (the radiogroup). Reactive
+after mount.
+
+---
+
+## Notes
+
+- The root is `inline-size: fit-content` capped at `max-inline-size: 100%`; labels shrink and wrap
+  (`overflow-wrap: anywhere`) rather than overflow, and the indicators re-measure as they do.
+- No line-clamp token: labels name the choice and must stay readable.