srcdev-nuxt-components 9.6.14 → 9.6.15

package/.claude/skills/components/sliding-toggle.md

@@ -0,0 +1,108 @@
+---
+name: SlidingToggle
+description: SlidingToggle single-choice segmented radiogroup with text labels of any width, measured sliding indicator (stretch-then-catch-up) plus hover indicator, corner-shape token, CSS token API
+type: reference
+---
+
+# SlidingToggle
+
+## Overview
+
+A single-choice segmented control for short text choices such as a billing period or a site tier.
+The selected option's background slides between options of different widths, with the same
+stretch-then-catch-up motion as `TabbedContent`'s indicator (both use `useSlidingIndicator`), and a
+second indicator follows the pointer. It's a WAI-ARIA radio group of `<button role="radio">`s, not
+a form control: there are no native inputs and nothing is submitted.
+
+Lives in `app/components/02.molecules/sliding-toggle/`.
+
+**Which one to use:**
+
+- `SlidingToggle` — text labels of any width, page UI state (pricing toggles, view switches).
+- `SegmentedControl` (`05.forms`) — icon-only, equal-width options, native radio inputs that submit
+  with a form.
+- `TabbedContent` — the choice switches between panels of content.
+
+## Props
+
+| Prop (template form) | Type | Default | Notes |
+|---|---|---|---|
+| `v-model` | `T` (`string \| number`) | (required) | The selected option's `value`. A value matching no option leaves nothing selected. |
+| `options` | `SlidingToggleOption<T>[]` | (required) | `{ value, label, disabled? }`. Labels are plain text. |
+| `aria-label` | `string` | `""` | Names the radiogroup. Set this or `aria-labelledby`. |
+| `aria-labelledby` | `string` | `""` | Id of a visible heading naming the group. |
+| `disabled` | `boolean` | `false` | Disables every option. |
+| `track-hover` | `boolean` | `true` | Show the hover indicator. |
+| `transition-duration` | `number` (ms) | `200` | Length of each edge's slide. |
+| `style-class-passthrough` | `string \| string[]` | `[]` | Classes on the root. |
+
+`SlidingToggleOption` is exported from `~/types/components`.
+
+## Usage
+
+```vue
+<script setup lang="ts">
+const billing = ref<"monthly" | "yearly">("monthly");
+const billingOptions = [
+  { value: "monthly", label: "Monthly" },
+  { value: "yearly", label: "Yearly (save 20%)" },
+] as const;
+</script>
+
+<template>
+  <SlidingToggle v-model="billing" :options="[...billingOptions]" aria-label="Billing period" />
+</template>
+```
+
+Equal widths across a full-width switch:
+
+```css
+.billing-switch {
+  --sliding-toggle-option-flex: 1 1 0;
+}
+
+.billing-switch .sliding-toggle {
+  inline-size: 100%;
+}
+```
+
+## Behaviour
+
+- The root is `role="radiogroup"`, named by `aria-label` or `aria-labelledby`. Each option is a
+  `<button type="button" role="radio">` with `aria-checked`.
+- Clicking an option sets `v-model`; changing `v-model` from outside moves the selection.
+- Only the selected option is a tab stop. With no match, the first enabled option is.
+- Arrow keys move focus and select, wrapping round and skipping disabled options. Right and Down go
+  to the next option, Left and Up to the previous; inside `dir="rtl"` Left and Right swap. Home and
+  End go to the first and last enabled option.
+- `disabled` on the group or on one option blocks clicks and keys; disabled options are skipped and
+  never get the hover indicator.
+- The selected indicator slides to the new option, its leading edge first and the trailing edge one
+  `transition-duration` later. The hover indicator follows the pointer and returns to the selected
+  option when it leaves; `track-hover="false"` turns it off. `--sliding-toggle-indicator-stretch: 0`
+  makes both indicators slide their edges together instead of stretching, mirroring TabbedContent's
+  `--tabs-indicator-stretch`.
+- Under `prefers-reduced-motion` both indicators snap.
+- Before it's mounted and measured (SSR, first paint) the indicators are hidden and the selected
+  option paints its own background and marker, so there's no flash of an unselected group.
+- It re-measures when the track or any single option resizes (a late web font changes label widths
+  without resizing the track) and when options are added, removed or re-classed.
+- Long, unbroken and many labels wrap and shrink inside the track instead of overflowing.
+
+## CSS custom properties
+
+See `CONSUMER-STYLING.md` for the full `--sliding-toggle-*` token API: track surface, padding, gap,
+radii, `--sliding-toggle-corner-shape`, indicator and hover-indicator surfaces, marker, option
+padding/flex/typography/colours and the focus ring. Colours default from `--theme-*` tokens.
+
+`--sliding-toggle-corner-shape` takes any `corner-shape` value (`squircle`, `superellipse(n)`,
+`bevel`, `scoop`, `notch`). It's a progressive enhancement: Chromium 139+ only, and other browsers
+keep the `border-radius` corners.
+
+## Notes
+
+- Auto-imported in Nuxt.
+- The motion comes from the `useSlidingIndicator` composable, shared with `TabbedContent` (via
+  `useTabs`). It writes `--_sliding-toggle-active-*` / `--_sliding-toggle-hover-*` on the root.
+- Added 2026-10-19, generalised from a consumer app's pricing-page toggle (which used `aria-pressed`
+  buttons; this version uses radio semantics).

package/.claude/skills/components/tabbed-content.md

@@ -137,6 +137,10 @@ source order when the list changes.
 
 ## Indicator motion: edge insets (2026-10-08)
 
+> **Changed 2026-10-19**: the edge maths moved into `useSlidingIndicator` (`composable-sliding-indicator.md`),
+> shared with `SlidingToggle`. `useTabs.placeIndicator` now calls it and keeps the label-coverage
+> tracking. Under `prefers-reduced-motion` the indicators now snap instead of sliding.
+
 `useTabs.placeIndicator(kind, animate)` writes each indicator's two edges as insets from the
 bar's start/end along the axis (`--_{kind}-start` / `--_{kind}-end`), and the CSS transitions
 `left`/`right` (or `top`/`bottom`) separately. Moving forward, the start edge gets a delay of one
@@ -145,9 +149,10 @@ and the trailing edge catches up: the same stretch effect as before, symmetric b
 settle timer. CSS retargets each edge from its current position, so a quick second move can't
 pull an edge backwards. Hover and active have separate duration/delay variables.
 
-`--tabs-hover-indicator-stretch` (default `1`) multiplies the hover pair's two edge delays in CSS,
-so `0` turns the hover stretch into a plain slide (both edges move together over the same
-duration). The active indicator and underline always stretch.
+`--tabs-indicator-stretch` (default `1`) multiplies every indicator's two edge delays in CSS, so `0`
+turns the stretch into a plain slide (both edges move together over the same duration) for the
+hover, active and underline indicators alike. Renamed 2026-10-19 from `--tabs-hover-indicator-stretch`,
+which covered the hover pair only.
 
 This replaced a `translate` + `scale` model (a bar-wide box translated to the tab's left and
 scaled to its width, plus a timeout to settle after a stretch, and one shared

package/.claude/skills/composable-sliding-indicator.md

@@ -0,0 +1,60 @@
+# useSlidingIndicator
+
+## Overview
+
+Positions one or more sliding indicators (a highlight or underline that moves between items) inside
+a container, with a stretch-then-catch-up motion: the edge in the direction of travel moves first
+and the trailing edge follows one duration later. Used by `useTabs` (TabbedContent) and
+`SlidingToggle`. Lives in `app/composables/useSlidingIndicator.ts`, auto-imported.
+
+## API
+
+```ts
+const { place, reset } = useSlidingIndicator(containerRef, { axis?: "x" | "y", duration });
+```
+
+| Param | Type | Notes |
+|---|---|---|
+| `containerRef` | `Ref<HTMLElement \| null>` | The positioned element the indicators sit in. The CSS variables are written on it. |
+| `axis` | `MaybeRefOrGetter<"x" \| "y">` | Default `"x"`. |
+| `duration` | `MaybeRefOrGetter<number>` | Slide length per edge, in ms. Invalid or negative values count as `0`. |
+
+`place(name, target, animate)` measures `target` (its `offsetLeft`/`offsetTop` and size against the
+container's client size) and writes, on the container:
+
+- `--_{name}-start` / `--_{name}-end` — insets from the container's start and end edges, in px;
+- `--_{name}-duration`, `--_{name}-start-delay`, `--_{name}-end-delay`.
+
+It returns the transition length in ms, or `null` when the container or target is missing (nothing
+written). The first placement of a name, `animate: false`, and `prefers-reduced-motion` all snap
+(duration `0ms`).
+
+`reset(name)` forgets the last position, so the next placement snaps instead of sliding in from
+wherever the indicator last was (use it when an indicator is hidden).
+
+## CSS side
+
+```css
+.my-indicator {
+  position: absolute;
+  left: var(--_my-thing-active-start, 0px);
+  right: var(--_my-thing-active-end, 100%);
+  transition:
+    left var(--_my-thing-active-duration, 0ms) ease var(--_my-thing-active-start-delay, 0ms),
+    right var(--_my-thing-active-duration, 0ms) ease var(--_my-thing-active-end-delay, 0ms);
+}
+```
+
+Use physical `left`/`right` (and `top`/`bottom` for `"y"`): the measurements are physical, so this
+also works in right-to-left layouts.
+
+## Rules
+
+- Prefix the `name` with the component (`"sliding-toggle-active"`), so a component nested inside
+  another that uses the composable can't inherit its values (pitfall #26). `useTabs` keeps the
+  historic `"active"`/`"hovered"` names that TabbedContent's CSS reads.
+- Re-place with `animate: false` when the container or any measured item resizes, and when items
+  are added or removed (`measured-layout-observers.md`). Don't observe `style` changes: the
+  composable writes inline styles on the container.
+- Keep the indicators hidden until the first placement (SlidingToggle's `data-ready`), and give the
+  selected item its own fallback background for SSR and first paint.

package/.claude/skills/index.md

@@ -75,6 +75,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── composable-cookie-consent.md      — useCookieConsent: unset/granted/denied state, cookie persistence, wraps @nuxt/scripts' useScriptTriggerConsent
 ├── composable-analytics.md           — useAnalytics: provider-agnostic trackEvent/page-view tracking (google-analytics only implemented), consent-gated, single call site for setup + firing events
 ├── composable-anchored-popover.md    — useAnchoredPopover: popover + anchor positioning with JS fallbacks for Safari 16 (no Popover API) and 17–18 (no anchor positioning); used by ActionMenu/SelectMenu/DeepExpandingMenu/DisplayTooltip/PopOver
+├── composable-sliding-indicator.md   — useSlidingIndicator: stretch-then-catch-up sliding indicator edges written as --_{name}-* vars, reduced-motion snap; used by useTabs/TabbedContent and SlidingToggle
 └── components/
     ├── alert-content.md          — AlertContent + AlertContentInner: themed alert panel (icon/title/content/actions/dismiss) under DisplayToast, DisplayPrompt and AlertMaskedContent; showIcon, #actions row, --alert-content-* tokens, app.config icon map
     ├── alert-mask.md      — AlertMask (renamed from AlertMaskCore): SVG border/fill sized to slotted content via ResizeObserver; config-prop geometry, --alert-mask-* colour tokens
@@ -164,6 +165,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── input-radio.md            — MultipleRadiobuttons: fieldset radiogroup (data-driven, button or labelled), shared-name grouping bug fixed, dead label/placeholder/equalCols props removed, data-options-layout hook, spacing token API, useId button ids, wraps hostile content
     ├── toggle-switch.md         — ToggleSwitch (bare control), ToggleSwitchField (labelled, layout="stacked"|"inline", replaces ToggleSwitchWithLabelInline): renamed from Core/WithLabel, role="switch", prefixed inner classes + data-checked, single-toggle click handling, reduced motion, round prop + border-radius token, track width from geometry, CSS token API, stress stories
     ├── segmented-control.md    — SegmentedControl (renamed from TripleToggleSwitch): icon radio pill for any number of options with sliding marker, radiogroup + ariaLabel, system/light/dark marker-gradient tokens, reduced-motion, CSS token API
+    ├── sliding-toggle.md       — SlidingToggle: single-choice segmented radiogroup with text labels of any width, measured sliding + hover indicators (useSlidingIndicator), roving tabindex/arrow keys, corner-shape token, CSS token API
     ├── entry-animation.md         — EntryAnimation: scroll-driven entry animation wrapper (slide-in/zoom-reveal/exit-blur utility classes), skipAnimation for above-the-fold loop items, reduced-motion handled at the CSS layer
     ├── column-flow-grid.md        — ColumnFlowGrid (renamed from MasonryGrid): CSS multi-column text-flow layout, named dynamic slots (no count/data prop), itemMinWidth/gap/unit sizing, CSS token API; not a true masonry, see "which one do I want?"
     ├── masonry-grid.md            — MasonryGrid: real measured-height masonry (greedy shortest-column packing, animated resize) absorbed from the now-retired MasonryGridOrdered; named dynamic slots, fixedWidth/justify, CSS token API

package/.claude/skills/storybook-add-story.md

@@ -172,6 +172,23 @@ const Template: StoryFn<StoryArgs> = (args) => ({
 
 Don't name the inline component the same as an exported story (`TS2451: Cannot redeclare`).
 
+### Generic components (`<script setup generic="T">`)
+
+A generic component's type doesn't fit `Meta`'s `component` field (`ConcreteComponent<Args>`), so
+`npx nuxi typecheck` fails on `component: MyGeneric`. Cast it, with a one-line comment; the
+autodocs props table still generates:
+
+```ts
+import type { ConcreteComponent } from "vue";
+
+const meta: Meta<StoryArgs> = {
+  // Generic components don't fit Meta's ConcreteComponent<Args>; the props table still generates.
+  component: SlidingToggle as unknown as ConcreteComponent<StoryArgs>,
+};
+```
+
+`SlidingToggle.stories.ts` is the reference.
+
 ## Title format
 
 `"Category/Subcategory/ComponentName"` — this becomes the Storybook sidebar path and the

package/.claude/skills/testing-add-unit-test.md

@@ -396,6 +396,31 @@ afterEach(() => {
 The `as unknown as Record<string, unknown>` double-cast is required because TypeScript's
 `HTMLElement` type has no index signature — cast through `unknown` first.
 
+## A mount helper that keeps `v-model` in sync
+
+To test a `v-model` component through clicks and keys, feed `update:modelValue` back into the
+props. The handler needs the wrapper it's creating, so hold it in a `const` object: a self-referencing
+`const wrapper` is an implicit `any` under strict mode, and `let wrapper` assigned once fails
+ESLint's `prefer-const`.
+
+```ts
+const mountToggle = async (props: Record<string, unknown> = {}) => {
+  const holder: { current?: Awaited<ReturnType<typeof mountSuspended>> } = {};
+  const onUpdate = (value: string | number) => {
+    void holder.current?.setProps({ modelValue: value });
+  };
+  const wrapper = await mountSuspended(SlidingToggle, {
+    props: { modelValue: "monthly", "onUpdate:modelValue": onUpdate, ...props },
+  });
+  holder.current = wrapper;
+  mounted.push(wrapper);
+  return wrapper;
+};
+```
+
+Type the handler's `value` as the model's full type (`string | number` for a generic model), not
+the narrower one a test happens to use.
+
 ## Describe section conventions
 
 Use these section names consistently so tests are easy to scan:

package/.claude/skills/theming-component-token-pattern.md

@@ -129,6 +129,24 @@ Prefer this over a prop: line count is presentation, and CSS handles it without
   layout around it.
 - Document it in `CONSUMER-STYLING.md` with its default and the `1`/`none` options.
 
+## Corner shape tokens
+
+`corner-shape` (CSS Borders 4: `squircle`, `superellipse(n)`, `bevel`, `scoop`, `notch`, default
+`round`) reshapes the curve that `border-radius` draws. Give a component that wants it one public
+token, `--<component>-corner-shape`, defaulting to `round`, and read it on every element that has a
+radius so they stay in step:
+
+```css
+.sliding-toggle,
+.sliding-toggle-option {
+  corner-shape: var(--sliding-toggle-corner-shape, round);
+}
+```
+
+It's a progressive enhancement (Chromium 139+ when added on 2026-10-19): other browsers drop the
+declaration and keep the `border-radius` corners, so never rely on it for layout or meaning. Label
+it as Chromium-only in `CONSUMER-STYLING.md`. `SlidingToggle` is the first user.
+
 ## Text over an image: scrim tokens
 
 Any component that puts text over a photo (a header in a picture, a card title on its image) gets

package/.vscode/srcdev-component-sliding-toggle.code-snippets

@@ -0,0 +1,37 @@
+{
+  "SRCDEV SlidingToggle": {
+    "description": "SlidingToggle — single-choice segmented radiogroup with a sliding indicator",
+    "scope": "vue,html",
+    "body": [
+      "<SlidingToggle",
+      "  v-model=\"${1:selected}\"",
+      "  :options=\"[",
+      "    { value: '${2:monthly}', label: '${3:Monthly}' },",
+      "    { value: '${4:yearly}', label: '${5:Yearly}' },",
+      "  ]\"",
+      "  aria-label=\"${6:Billing period}\"",
+      "/>"
+    ]
+  },
+  "SRCDEV SlidingToggle Options Variable": {
+    "description": "SlidingToggle bound to an options array, without hover tracking",
+    "scope": "vue,html",
+    "body": [
+      "<SlidingToggle v-model=\"${1:selected}\" :options=\"${2:options}\" aria-label=\"${3:Label}\"${4: :track-hover=\"false\"} />"
+    ]
+  },
+  "SRCDEV SlidingToggle CSS Override": {
+    "description": "Unlayered CSS override scaffold for SlidingToggle tokens",
+    "scope": "css,vue",
+    "body": [
+      ".${1:my-section} {",
+      "  --sliding-toggle-surface: ${2:var(--theme-surface-subtle)};",
+      "  --sliding-toggle-indicator-surface: ${3:var(--theme-on-surface)};",
+      "  --sliding-toggle-marker-colour: ${4:var(--theme-accent)};",
+      "  --sliding-toggle-option-flex: ${5|0 1 auto,1 1 0|};",
+      "  --sliding-toggle-corner-shape: ${6|round,squircle,superellipse(3),bevel,scoop,notch|};",
+      "  --sliding-toggle-indicator-stretch: ${7|1,0|};$0",
+      "}"
+    ]
+  }
+}

package/.vscode/srcdev-component-tabbed-content.code-snippets

@@ -58,7 +58,7 @@
       "    --tabs-underline-indicator-height: ;",
       "    --tabs-hover-underline-indicator-colour: ;",
       "    --tabs-hover-underline-indicator-height: ;",
-      "    --tabs-hover-indicator-stretch: ;",
+      "    --tabs-indicator-stretch: ;",
       "    --tabs-list-item-opacity: ;",
       "    --tabs-list-item-colour: ;",
       "    --tabs-list-item-colour-selected: ;",

package/app/components/01.atoms/tabbed-content/CONSUMER-STYLING.md

@@ -58,7 +58,7 @@ box.
 | `--tabs-underline-indicator-height` | `0.4rem` | Thickness of the underline (`axis="x"`), also its width on `axis="y"` |
 | `--tabs-hover-underline-indicator-colour` | `--tabs-underline-indicator-colour` | Colour of the thin underline/sideline that follows the hovered tab (`trackHover` and `trackIndicator`) |
 | `--tabs-hover-underline-indicator-height` | `0.1rem` | Its thickness; `0` hides it. Sits under the active underline where they overlap |
-| `--tabs-hover-indicator-stretch` | `1` | Stretch of the hover highlight and hover underline as they move: `1` stretches (leading edge first, trailing edge catches up), `0` slides both edges together. Values in between shorten the stretch |
+| `--tabs-indicator-stretch` | `1` | Stretch of every indicator (hover, active and both underlines) as it moves: `1` stretches (leading edge first, trailing edge catches up), `0` slides both edges together. Values in between shorten the stretch |
 
 ### More menu (`overflowMode="menu"`, `axis="x"`)
 
@@ -100,7 +100,7 @@ insets from the bar's start and end along the axis), `--_{kind}-duration`,
 `--_{kind}-start-delay` / `--_{kind}-end-delay`; each indicator reads them through its own
 `--_start` / `--_end` / `--_duration` / `--_start-delay` / `--_end-delay`. Not public API; use the
 `transitionDuration` prop for indicator speed (one edge moves for that long, then the other), and
-`--tabs-hover-indicator-stretch` to turn the hover stretch off. The More menu also uses
+`--tabs-indicator-stretch` to turn the stretch off. The More menu also uses
 `--_anchor-name` (a per-instance anchor name) and the `--_anchor-*` position values
 `useAnchoredPopover` writes for browsers without CSS anchor positioning.
 
@@ -169,6 +169,19 @@ before.
 
 ---
 
+## Indicator motion and reduced motion
+
+The indicators slide with `useSlidingIndicator` (shared with `SlidingToggle`): the leading edge
+moves first and the trailing edge catches up. Under `prefers-reduced-motion` they snap.
+
+> **Changed 2026-10-19**: the indicators used to slide even under `prefers-reduced-motion`.
+>
+> **Changed 2026-10-19**: `--tabs-hover-indicator-stretch` (hover only) is now
+> `--tabs-indicator-stretch` and covers the active indicator and underline too. Rename it in your
+> CSS; `0` now turns the stretch off for every indicator.
+
+---
+
 ## Indicator visibility is prop-driven
 
 Whether each indicator renders is set by `trackHover` / `trackActive` / `trackIndicator`, not

package/app/components/01.atoms/tabbed-content/TabbedContent.vue

@@ -354,8 +354,8 @@ watch(
         --_start: var(--_hovered-start, 0px);
         --_end: var(--_hovered-end, 100%);
         --_duration: var(--_hovered-duration, 0ms);
-        --_start-delay: calc(var(--_hovered-start-delay, 0ms) * var(--tabs-hover-indicator-stretch, 1));
-        --_end-delay: calc(var(--_hovered-end-delay, 0ms) * var(--tabs-hover-indicator-stretch, 1));
+        --_start-delay: calc(var(--_hovered-start-delay, 0ms) * var(--tabs-indicator-stretch, 1));
+        --_end-delay: calc(var(--_hovered-end-delay, 0ms) * var(--tabs-indicator-stretch, 1));
       }
 
       .tabbed-content-indicator-active,
@@ -363,8 +363,8 @@ watch(
         --_start: var(--_active-start, 0px);
         --_end: var(--_active-end, 100%);
         --_duration: var(--_active-duration, 0ms);
-        --_start-delay: var(--_active-start-delay, 0ms);
-        --_end-delay: var(--_active-end-delay, 0ms);
+        --_start-delay: calc(var(--_active-start-delay, 0ms) * var(--tabs-indicator-stretch, 1));
+        --_end-delay: calc(var(--_active-end-delay, 0ms) * var(--tabs-indicator-stretch, 1));
       }
 
       .tabbed-content-indicator-hover,

package/app/components/01.atoms/tabbed-content/stories/TabbedContent.stories.ts

@@ -219,14 +219,14 @@ export const IndicatorColours: Story = {
   }),
 };
 
-export const HoverWithoutStretch: Story = {
-  name: "Hover Without Stretch",
+export const WithoutStretch: Story = {
+  name: "Without Stretch",
   args: { itemCount: 5 },
   parameters: {
     docs: {
       description: {
         story:
-          "--tabs-hover-indicator-stretch: 0 makes the hover highlight slide between tabs instead of stretching across and catching up. Clicking a tab still stretches the active indicator.",
+          "--tabs-indicator-stretch: 0 makes every indicator (hover, active and the underlines) slide between tabs instead of stretching across and catching up.",
       },
     },
   },
@@ -236,7 +236,7 @@ export const HoverWithoutStretch: Story = {
       return { args };
     },
     template: `
-      <div style="--tabs-hover-indicator-stretch: 0">
+      <div style="--tabs-indicator-stretch: 0">
         <TabbedContent v-bind="args">
           ${tabSlots}
         </TabbedContent>

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.